Common Attributes

Use established attribute names when a built-in UI or system component is already configured to read them. The name, value type, and attribute collection must agree with that consumer. Many components let you change the attribute name in the Inspector, so treat the names below as supported conventions rather than reserved words.

Display Items in the editor and UI

Name	Type	Recommended collection	Consumer	Standard example
Description	string	Item Definition	Item Description and its View Modules	Health Potion instructions or Iron Sword flavor text
Icon	Sprite	Item Definition	Icon Item View; also the Item Definition editor when Editor Icon is empty	A different icon for Health Potion, Iron Sword, and Fire Wand
CategoryIcon	Sprite	Item Category	Item Category editor when Editor Icon is empty	One icon representing Weapon

Declare Description and Icon in the Item Definition collection on All when every definition should have them. Health Potion, Iron Sword, and Fire Wand then inherit those declarations and override the values on their own definitions. Put CategoryIcon in the Item Category collection because it describes the category itself.

The UI reads these values only when the relevant Item View or Item Description module is present and configured with the matching attribute name.

Price Items in Gold

Name	Type	Recommended collection	Consumer	Use
BuyPrice	CurrencyAmounts	Item Definition	Shop Currency Collection and price views	What the player pays
SellPrice	CurrencyAmounts	Item Definition	Shop Currency Collection and price views	What the player receives
Price	CurrencyAmounts	Item Definition	A shop or view explicitly configured to use this alternative name	One shared price when separate buy and sell values are unnecessary

A CurrencyAmounts value can contain one or more Currency-and-amount entries. In the standard sample, set each definition’s BuyPrice to an amount of Gold. Gold remains a Currency in the database; it is referenced by the price attribute rather than becoming an Item attribute itself.

The shop documentation recommends BuyPrice and SellPrice. If the project does not need a separate sell price, the Shop Currency Collection can be configured to read BuyPrice for both transactions. Price displays must use the same configured names as the shop.

Spawn pickups and equipped prefabs

Name	Type	Recommended collection	Consumer	Standard example
PickupPrefab	GameObject	Item Definition	Item Object Visualizer configured for dropped Items	A Health Potion bottle pickup or Iron Sword world model
UsableItemPrefab	GameObject	Item Category when logic is shared; Item Definition when it differs	Equipper	Shared melee-use logic, or definition-specific Fire Wand casting logic
EquipmentPrefab	GameObject	Item Definition	Equipper	The visible Iron Sword or Fire Wand model

The Equipper separates use logic from the visible model. UsableItemPrefab normally contains the scripts that use the Item and no model. EquipmentPrefab normally contains the model and is spawned beneath the usable prefab for non-skinned equipment. The usable prefab should include an Item Object component; an Item Object Behaviour Handler can provide use behavior.

For a shared weapon interaction, define UsableItemPrefab in the Item Category collection on Weapon. If Fire Wand and Iron Sword require different use logic, declare it in Weapon’s Item Definition collection instead and set a value on each definition. Set EquipmentPrefab on each definition so each weapon displays its own model.

Give each definition its own action

Name	Type	Recommended collection	Consumer	Standard example
ItemActionSet	ItemActionSet	Item Definition	Use Item Action Set Attribute Item Action	Health Potion restores health while Fire Wand invokes a cast action

Use this pattern when Items in the same broad category need different behavior. The Use Item Action Set Attribute Item Action reads the Scriptable Object stored by the attribute and invokes an action from it. A conventional Category Item Action Set is simpler when every Item in the category performs the same action.

Support spatial and nested inventory

Name	Type	Recommended collection	Consumer	Standard example
Shape	ItemShape	Item Definition	Item Shape Grid data and Item Shape Item View modules	Iron Sword occupies a longer group of cells than Health Potion
Slots	ItemAmounts	Item when contents differ per instance	Item Slots Item View and project upgrade/socket logic	One Iron Sword contains its own rune or upgrade Items

An ItemShape stores a boolean grid and an anchor. The Item Shape Grid and its View Modules must use the same configured attribute name. Use this attribute only when Items occupy multiple cells; a regular Bag grid does not need it.

ItemAmounts stores one or more Item-and-amount entries and supports nested Item serialization. Put Slots in the Item collection when two Iron Sword instances can contain different upgrades. The Item must be mutable, and usually unique, for those contents to vary safely by instance.

Track equipped state and inventory limits

Name	Type	Recommended collection	Consumer	Use
IsEquipped	bool	Item	An Equipped Item View configured to read the attribute	Optional explicit equipped state
StackSizeLimit	int	Item Definition	Multi Stack Item Collection through Stack Size Limit Attribute Name	A smaller maximum stack for Health Potion
CategorySizeLimit	int	Item Category	Legacy Group Item Restriction configured with the matching name	Limit all Items in one category
DefinitionSizeLimit	int	Item Definition	Legacy Group Item Restriction configured with the matching name	Limit one definition, such as Iron Sword
ItemSizeLimit	int	Item	Legacy Group Item Restriction configured with the matching name	Limit one particular mutable Item

IsEquipped is optional. Most equipment UI can determine state from membership in the Equipment Item Collection, which avoids maintaining a second value. If a configured view explicitly reads IsEquipped, define it as an Item attribute and make the Item mutable so the value can change at runtime.

The Multi Stack Item Collection has a default stack limit and an attribute-name field for definition-specific limits. The Group Item Restriction remains available for attribute-driven limits, but its overflow actions are legacy. Prefer the newer Item Restriction Set and rejection event workflow for new inventory restrictions unless the older attribute-based behavior is specifically required.

Choose the value type

Use the type required by the consuming component. The images below show how the common value editors appear.

Numeric, Boolean, and text values

int stores whole numbers such as Attack or StackSizeLimit. It supports Modify expressions.

float stores decimal values such as a multiplier or precise duration. It supports Modify expressions.

bool stores an on/off value such as optional IsEquipped state.

string stores text such as Description. It supports Modify expressions.

Unity object references

Unity object types such as GameObject, Sprite, and Material reference project assets. Use Sprite for Icon and GameObject for pickup or equipment prefabs.

Inventory-specific values

ItemAmounts stores nested Items and amounts, such as the contents of Slots.

CurrencyAmounts stores Currency-and-amount entries, such as a BuyPrice paid in Gold.

ItemShape stores the occupied cells and anchor used by an Item Shape Grid.

ItemActionSet references an Item Action Set Scriptable Object for definition-specific behavior.

Editor checkpoints

Before entering Play Mode, confirm that:

• Every attribute name uses the exact spelling and capitalization expected by its consumer.
• The declared value type matches the component field: for example, Icon is a Sprite and BuyPrice is CurrencyAmounts.
• The attribute is declared in the intended collection on the closest shared Item Category.
• Health Potion, Iron Sword, and Fire Wand definitions override their own Icon, Description, and BuyPrice values.
• Weapon data exposes the expected use and equipment prefabs plus any project-defined Attack or Durability values.
• Every consuming component points to the same attribute name used by the database.

Verify in Play Mode

1. Open the Bag UI and confirm that Health Potion, Iron Sword, and Fire Wand display the expected icons and descriptions.
2. Open the shop and confirm that each definition’s price is shown in Gold and matches the value used by the transaction.
3. Drop each Item and confirm that the intended pickup visual appears.
4. Equip Iron Sword and Fire Wand and confirm that each uses the correct visual and use behavior.
5. If Shape is configured, move the Items in the shape grid and confirm that their occupied cells match their definitions.
6. If Slots is configured, change one weapon’s nested Items and confirm that another instance is unchanged.
7. Test the configured stack and inventory limits and confirm that rejected Items follow the project’s rejection workflow.

Troubleshooting

• A UI field is blank: Check the attribute spelling, type, collection, and the Item View or Item Description module’s configured attribute name.
• The editor preview uses the wrong icon: Check Editor Icon first, then verify Icon on the Item Definition or CategoryIcon on the Item Category.
• The shop shows zero or the wrong Currency: Check that the price is CurrencyAmounts, includes Gold, and uses the same name configured by the Shop Currency Collection and price view.
• The wrong equipment prefab appears: Check whether the Equipper is reading UsableItemPrefab or EquipmentPrefab, then inspect the inherited source and local override.
• A nested Item changes on every copy: Move Slots to the Item collection and confirm that the direct category is mutable and unique.
• A stack or inventory limit is ignored: Check the collection or restriction component’s attribute-name field and confirm that the value is an int on the expected Category, Definition, or Item.

Related pages

• Attributes and inheritance
• Defining Attributes
• Item Views
• Item Description
• Shops and prices
• Equipping Items
• Item Object Visualizer
• Item Skills
• Item Shape Grid
• Multi Stack Item Collection
• Item Restrictions