Item Objects

An Item Object connects Ultimate Inventory System item data to a Unity GameObject. Add one when an item needs a physical presence, such as a Health Potion pickup, an equipped Iron Sword, or a usable Fire Wand. An item that only exists inside an Inventory does not need an Item Object.

The component is intentionally reusable: calling SetItem unbinds the previous Item and binds the new one, so one pooled pickup or equipment prefab can represent different Items over its lifetime.

Understand what the Item Object owns

Object	Responsibility
Item Definition	Database-authored identity, Category, and default Definition attributes, such as the definition for Iron Sword.
Item	The concrete common, mutable, or unique data created from a Definition. Runtime Item attributes such as Durability belong here.
Item Info	The Item plus an amount and optional Item Collection and stack context.
Item Object	A scene MonoBehaviour that holds an ItemInfo and binds its Item to a GameObject.

An Item Object does not automatically add or remove anything from an Inventory. ItemPickup performs the world-to-Inventory transfer, while an Equipper observes an Equipment collection and creates or removes the corresponding scene object.

Create a basic Item Object

1. Make sure the scene has an initialized Inventory System Manager and the intended database.
2. Select the GameObject or reusable prefab that should represent the item and add Item Object.
3. In the Item Object Inspector, confirm Database, set Amount, and select an Item Definition. When the amount is 0 or less, choosing a Definition changes it to 1.
4. Expand Item Details to confirm the generated Item name, ID, Category, Definition, and its Mutable and Unique state.
5. Inspect the Item Attributes, Item Definition Attributes, and Item Category Attributes tabs. Only Item attributes are editable from this Inspector; inherited Definition and Category values are shown for context.
6. Add the component that gives the object its role: a visualizer, pickup, binding, behavior handler, or equipment workflow.

Editor checkpoint: the Item Object shows the correct database, a positive amount, and the intended Definition. The Item Details Category should match the companion component’s requirements before entering Play Mode.

How the binding runs

On Awake, the Item Object validates that its Item has an Item Definition. In Play Mode it registers the Item with the Inventory System Manager, initializes the Item, and refreshes its attributes. Invalid data is replaced with ItemInfo.None.

At startup and whenever SetItem changes the value, the component removes its binding from the previous Item and adds itself to the new Item’s runtime Item Object list. SetAmount changes only the amount while keeping the same Item. Destroying the component removes the binding.

The Item Object sends EventNames.c_ItemObject_OnItemChanged when it is enabled and whenever its Item Info changes in Play Mode. Components such as ItemObjectVisualizer and ItemBinding listen for that event so a pooled object redraws and rebinds itself without being recreated.

One Item can be bound to more than one Item Object. GetLastItemObject therefore means the most recently bound object, not a persistent or network-safe identity.

Choose the world-object workflow

Every direct child of this section covers a different use of the same Item Object binding.

Goal	Components and important Version 1 defaults	Continue with
Equip an Iron Sword or armor visual	An Equipper watches an ItemSlotCollection. Equipment Item Collection ID defaults to name Equipped and purpose Equipped; Equipable Prefab Attribute Name defaults to EquipmentPrefab; Usable Item Prefab Attribute Name defaults to UsableItemPrefab.	Equipping Items
Copy an Item attribute into a component property	Put ItemBinding beside the Item Object, choose Database and Item Category, then add compatible attribute-to-property bindings. The Category and binding list are empty until configured.	Item Binding
Pick up a Health Potion from the world	Use ItemObject, ItemPickup, and Interactable on the prefab. Add To Item Collection defaults to Main and Fail If Full Amount Does Not Fit defaults off. The inherited Deactivate On Interact defaults on and Schedule Reactivation Time defaults to -1.	Item Pickups
Spawn loot, currency, or an Inventory pickup	ItemObjectSpawner defaults to ID 1 and needs an Item Object Prefab. ItemDropper, CurrencyDropper, and their random variants provide designer-driven drop tables and pickup prefabs.	Item and Currency Droppers
Swap the model or sprite when the Item changes	Add ItemObjectVisualizer beside the Item Object. An empty Prefab Attribute Name falls back to PickupPrefab at runtime; an empty Item Prefab Visualizer Parent uses the current transform. Default Visual Prefab is used when the Item lacks that attribute, and Item View is optional.	Item Object Visualizer
Run an equipped Fire Wand or weapon behavior	Add ItemObjectBehaviourHandler. Item Object falls back to the component on the same GameObject, while Item Object Behaviours is the ordered array used by UseItem. Each behavior decides whether it can run.	Item Object Behaviour Handler

Health Potion pickup

Use a generic pickup prefab with ItemObject, ItemPickup, Interactable, and ItemObjectVisualizer. Bind the Health Potion with amount 1; use a PickupPrefab GameObject attribute when the visualizer should swap in a potion-specific model. On interaction, ItemPickup tries the configured destination and reports success, failure, or a partial pickup through its UnityEvents and audio fields.

Turn on Fail If Full Amount Does Not Fit when the transfer should fail instead of adding only part of the stack. Leave it off when partial pickup is intentional. This flag does not keep a failed pickup active by itself: configure Deactivate On Interact and reactivation behavior for the desired failure flow.

Equipped Iron Sword

Keep the owned Iron Sword in the Inventory rather than placing a permanent Item Object on the character. Moving the Item into the Equipped ItemSlotCollection causes Equipper to create an Item Object from its EquipmentPrefab attribute and place it in the matching slot. Removing the Item destroys or returns that object to its pool.

The generic Equipper does not change character stats or play equip animations. Those are project-specific behavior or integration responsibilities.

Usable Fire Wand

For a Fire Wand, the Equipper can create the functional UsableItemPrefab and place the visual EquipmentPrefab beneath it. Put ItemObjectBehaviourHandler and the wand behaviors on the usable prefab. Add ItemBinding when Definition or Item attributes such as Attack or projectile count should drive public component properties.

ItemObjectBehaviourHandler only dispatches the selected array entry when its CanUse value is true. It does not define the spell, animation, targeting, or input by itself.

Verify in Play Mode

Test	Expected result	What it verifies
Rebind one pooled pickup from Health Potion to Fire Wand	Item Details refer to the new Item, the visual changes once, and no old potion data remains on bound properties.	Item Object rebinding, change event, visualizer, and Item Binding.
Interact with a Health Potion pickup	The accepted amount appears in the destination Main collection and the pickup reports success, partial success, or failure consistently with capacity.	Item Info amount, Interactable, destination collection, and pickup settings.
Move Iron Sword into and out of Equipment	The sword object appears in the matching character slot and is removed or pooled when unequipped.	Equipment collection ID, Item Slot Set, prefab attributes, and Equipper listeners.
Use the equipped Fire Wand	The intended behavior index runs only when CanUse is true, with the wand Item Object and character Item User.	Behavior array order, Item User route, cooldown logic, and bound attributes.

Also disable and re-enable a reusable pickup. Its visual and bound properties should still match its current Item after the Item Object change event runs.

Persistence and multiplayer boundaries

ItemObject has no dedicated Version 1 saver. Inventory Saver and Inventory System Manager Item Saver preserve Inventory contents and registered mutable or unique Item data; they do not preserve the runtime list that links an Item to scene Item Objects. GameObjectSaver can preserve selected transform, active, destroyed, or component-enabled state, but it does not serialize the Item Object’s ItemInfo association.

For persistent world loot, save enough item identity, amount, and transform data to respawn or rebind the object. For equipped visuals, restore the Equipment collection and let the Equipper rebuild its Item Objects.

The Version 1 core package does not replicate Item Object bindings, spawns, pickup outcomes, or behavior calls over a network. Replicate the authoritative Item identity and amount, then call SetItem on each required representation so local listeners update.

Troubleshooting

Symptom	Check	Fix
The Item Object clears itself at startup	Check whether the selected Item has a valid Item Definition from the active database.	Select the correct Database and Definition; use the database conversion prompt only when equivalent objects exist.
A pooled object keeps the previous model or property values	Check that the new Item is assigned with SetItem, that the visualizer or binding is enabled, and that ItemBinding uses a Category containing both Items.	Rebind through SetItem, keep event listeners paired, and broaden or split the configured binding Category.
A Health Potion cannot be picked up	Check the Interactable, an Inventory-capable Interactor, Add To Item Collection, destination restrictions, and Fail If Full Amount Does Not Fit.	Repair the interaction setup or destination and choose whether partial pickup is allowed.
Iron Sword is in Equipment but no object appears	Check the Equipper’s Inventory, Equipment Item Collection ID, Item Slot Set, matching slot Category, and non-null EquipmentPrefab attribute.	Make the collection, slot set, and Equipper use the same IDs and assign a prefab that can become an Item Object.
Fire Wand input runs the wrong behavior or nothing	Check Item Object Behaviours order, null entries, selected action index, and each behavior’s CanUse.	Reorder or assign the array and make the chosen behavior eligible before dispatch.

Related pages

• Items explains Definition, Item, identity, mutability, and attributes.
• Inventory explains collection ownership and transactions.
• Item Slot Collection configures Equipment slots used by the Equipper.
• Interaction System configures Interactable and Interactor behavior.
• Built-in Item Actions covers UI-driven drop, move, use, and hotbar actions.
• Save System covers Inventory, Item, and GameObject persistence.
• Events explains safe Version 1 event registration and unregistration.

Use the Item Object API

Register for the parameterless change event while the listener is enabled. Run the handler once after registration so the component is correct even when Unity enables the Item Object first.

using EventHandler = Opsive.Shared.Events.EventHandler;

private void OnEnable()
{
    EventHandler.RegisterEvent(
        m_ItemObject,
        EventNames.c_ItemObject_OnItemChanged,
        HandleItemChanged);

    HandleItemChanged();
}

private void OnDisable()
{
    EventHandler.UnregisterEvent(
        m_ItemObject,
        EventNames.c_ItemObject_OnItemChanged,
        HandleItemChanged);
}

private void HandleItemChanged()
{
    var itemInfo = m_ItemObject.ItemInfo;
    // Refresh this component from itemInfo.
}

Create and bind an Item through the manager. SetItem(Item) uses an amount of one; SetAmount keeps the current Item; SetItem(ItemInfo.None) clears the binding.

var healthPotion = InventorySystemManager.CreateItem("Health Potion");

m_ItemObject.SetItem(healthPotion);
m_ItemObject.SetAmount(5);

var stack = (ItemInfo)(3, healthPotion);
m_ItemObject.SetItem(stack);

// Clear the world representation before reusing it.
m_ItemObject.SetItem(ItemInfo.None);

The Item-side lookup methods expose current runtime bindings only. Iterate them when several representations are valid; do not save an array index or assume GetLastItemObject is authoritative.

for (var i = 0; i < healthPotion.GetItemObjectCount(); i++)
{
    var itemObject = healthPotion.GetItemObjectAt(i);
    // Use the current scene representation.
}