Inventory

Export

The Inventory records which items a character owns, how many of each item are available, and which Character Item is active in each slot. Use the built-in Inventory for controller-focused loadouts, pickups, equipment, ammunition, and drops.

How the inventory fits together

The built-in inventory separates the item data from the object that appears on the character:

An Item Collection contains the project’s item categories and Item Types.
An Item Type is the built-in Item Definition and Item Identifier. It supplies the identity, capacity, categories, and Character Item prefab references; the Inventory stores the owned amount.
A Character Item is the runtime item object for one Item Definition and slot. It contains the visible first- or third-person item, item actions, equip timing, and optional Drop Prefab.
The Inventory owns Item Identifier amounts, maps each Item Identifier to its Character Items, and records the active Character Item in each slot.
The Item Set Manager uses Item Set Rules to decide which owned Character Items form valid equipment combinations. Equip and unequip requests should normally go through this manager rather than changing an Inventory slot directly.

An item such as an Iron Sword therefore has an Item Type that identifies the owned count, a Character Item for the sword held in a hand slot, and an Item Set that makes the sword an equippable choice. A consumable identifier such as Bullet can exist only as an Inventory amount when it does not need its own visible Character Item.

Before you begin

The character needs item support created by the Character Manager, an Item Collection, and at least one Item Set Rule for anything that can be equipped. Create the Item Types and Character Items first by following Item creation.

Use the built-in Inventory only when UCC owns the item data. If Ultimate Inventory System owns the inventory, follow the Ultimate Inventory System integration instead; that integration replaces the standard Inventory and Item Set Manager with bridge components.

Add inventory support to a character

Open Tools > Opsive > Ultimate Character Controller > Character Manager.
Select the character. Enable Items, assign the character’s Item Collection, and assign an Item Set Rule.
Select Build Character for a new character or Update Character for an existing one.
Confirm that the character has an Inventory and Item Set Manager, and that its hierarchy contains the Items object used for Character Items. A player-controlled character also receives the item input handling and standard item abilities.
Select the Inventory. Expand Default Loadout and confirm that every entry belongs to the same Item Collection assigned to the Item Set Manager. The Inspector reports an error when a loadout definition comes from another collection.

Editor checkpoint

Before entering Play Mode, the character should have one Inventory, one Item Set Manager using the intended Item Collection, and a Character Item prefab for every visible or equippable item. Each Character Item’s Slot ID must match the slot used by its Item Set Rule. Count-only definitions such as ammunition do not need a Character Item prefab.

Create useful starting loadouts

Start with an Iron Sword

Create an Iron Sword Item Type in Tools > Opsive > Ultimate Character Controller > Item Type Manager.
Open Tools > Opsive > Ultimate Character Controller > Item Manager. Build the sword for the character with Item Definition set to Iron Sword and the intended hand Slot ID. Keep Add to Default Loadout enabled when the character should begin with it.
On the Inventory, expand Default Loadout and set Iron Sword to an amount of 1.
Configure the Item Set Rule so the sword produces a valid set in that slot.
Set Loadout Equip to First Loadout Item for a simple one-item loadout, or choose Item Set Name when a named combination such as Sword and Shield must be selected.

The first loadout entry matters when First Loadout Item is selected. The Inventory adds the definitions first, then asks the first Item Set Group to equip the set that contains that entry. Item Set Index also addresses the first group; prefer Item Set Name when the project has multiple groups or the generated order can change.

Start with a firearm and ammunition

Create one Item Type and Character Item for the firearm. When its Shootable Action uses an Item Ammo module, create a separate ammunition Item Type, assign it as that module’s Ammo Item Definition, and add the starting ammunition amount to Default Loadout. The firearm needs a Character Item prefab; ammunition usually remains a count-only Inventory entry.

For example, add Rifle with amount 1 and Bullet with the desired reserve amount. The Rifle’s Character Item can be spawned and equipped, while reload removes Bullet amounts from the Inventory. The Bullet Item Type’s Capacity limits how much reserve ammunition the Inventory can accept.

See Shootable for the clip, ammo, and reload module workflow.

Add a pickup and a drop

Place a pickup in the scene

Create an Item Pickup with Tools > Opsive > Ultimate Character Controller > Object Manager, or add Item Pickup and a trigger Collider to a suitable prefab.
Add Iron Sword, Rifle, Bullet, or another definition to Item Definition Amounts and set the amount the object grants.
Keep Pickup On Trigger Enter enabled for automatic collection. Disable it when the Pickup ability or another interaction should initiate collection.
Enable Equip when collecting the object should request an equipment change. Set Item Set Name and Item Set Group when a particular set must be selected; otherwise the pickup tries a valid set containing one of the collected Character Items.
Set Trigger Enable Delay deliberately for dropped physics objects. A scene pickup without a Rigidbody is available immediately on its first initialization; a dropped Rigidbody waits until it settles and the delay expires.

On collection, the pickup adds each definition to the Inventory, spawns any configured Character Item prefabs, updates the Item Sets, and optionally requests an equip. The definition’s capacity can reduce the amount accepted.

Make an item drop and become collectible again

Assign a Drop Prefab on the Character Item. That prefab must contain an Item Pickup-based component so the Inventory can place the dropped definition and amount on it. Add the Drop ability to remove the active Character Item and spawn that prefab. Use Wait For Unequip when the visible item should finish its unequip transition before it leaves the character.

A shootable Character Item can also contribute related identifiers, such as its ammunition, to the dropped pickup. Test the exact amount you want to transfer rather than assuming all reserve ammunition should leave with one weapon.

Choose the Inventory behavior

Choose what loads and equips

Default Loadout adds Item Definitions and amounts when the Inventory initializes. It runs again after respawn only when Load Default Loadout On Respawn is enabled.
Loadout Equip defaults to First Loadout Item. None unequips the groups, Item Set Name or Item Set Index selects a specific set, and Do Nothing leaves the existing equipment unchanged.
Auto Spawn Destroy Runtime Character Items is enabled by default. Adding an identifier spawns the Character Item prefabs referenced by its Item Type; removing the last amount can destroy runtime-spawned Character Items.
Auto Remove Character Items is enabled by default. When an amount reaches zero, the corresponding Character Items leave the valid Inventory and an equipped item is handed back through the normal Item Set transition.

Use Loadout Equip > Item Set Name instead of a generated index when a stable, meaningful Item Set state name is available. Runtime Item Set indexes can change as the owned items and rules change.

Choose what happens on death and respawn

Unequip All On Death is disabled by default. Enable it to unequip every active slot when the character dies.
Remove All On Death is disabled by default. Enable it to remove the removable Character Items and their amounts and attempt to drop them with their configured drop prefabs. Add definitions to Remove Exceptions when they must survive this removal. A count-only identifier that is not associated with a Character Item is not enumerated by RemoveAllItems; clear it explicitly when that resource must also be lost on death.
Load Default Loadout On Respawn is disabled by default. Enable it to add the configured default amounts again and then apply Loadout Equip.

Avoid using Remove All On Death and a persistent save restore as two independent authorities. Decide whether death, the save system, or another game system owns the final restored amount, then apply that state once.

Use the Unequipped state

Unequipped State Name defaults to Unequipped. The Inventory activates this state while no Character Item is active and deactivates it when an item is equipped. Leave the field empty only when the project intentionally does not use an inventory-wide unequipped state.

Verify in Play Mode

Select the character and expand Inventory > Current Inventory. Confirm the Iron Sword or Rifle and its expected count appear. Active entries are bold and show their slot numbers.
Confirm the Item Set Manager creates a valid set for the visible Character Item and that Loadout Equip activates the intended set.
Collect an Item Pickup. Confirm the count increases only up to the Item Type’s capacity, its Character Item appears when required, and the configured equipment change occurs.
For a firearm, fire and reload. Confirm the reserve Bullet amount decreases while the firearm remains owned and active.
Drop the active item. Confirm its Inventory amount decreases, the Character Item is removed or replaced through the Item Set Manager, and the spawned object can be collected again after its trigger delay.
Test death and respawn. Confirm only the selected unequip, remove, exception, loadout, and re-equip behavior occurs.

Troubleshoot inventory items

The Current Inventory is empty: check that you are in Play Mode, the definition is in Default Loadout or is actually collected, and the Inventory component is enabled. The Current Inventory foldout is read-only runtime information.
The amount does not increase: check the Item Type’s Capacity, the pickup’s Item Definition Amounts, and whether the character is entering the trigger with its main collider. Fix the capacity or pickup definition rather than adding a duplicate Item Type.
The character owns an item but no Character Item appears: check that the Item Type references a Character Item prefab and Auto Spawn Destroy Runtime Character Items is enabled. Also confirm the prefab has the same Item Definition and a valid Slot ID.
The item appears but does not equip: inspect the Item Set Manager in Play Mode. Fix the Item Set Rule, Item Category, slot mapping, or disabled Item Set, then confirm the matching Equip Unequip ability can run.
A pickup adds ammunition but equips the wrong weapon: disable Equip for an ammo-only pickup, or assign the intended Item Set Name and Item Set Group. Also check the Equip Unequip ability’s Auto Equip choices.
Dropping removes the item but spawns nothing: check the Character Item’s Drop Prefab and confirm that prefab contains an Item Pickup component. A null or incompatible prefab cannot receive the dropped Item Definition amounts.
The dropped object cannot be collected immediately: check Trigger Enable Delay, the trigger Collider, and the object’s velocity. Dropped Rigidbody objects deliberately wait until they settle and the configured delay completes.
Items duplicate after respawn or load: check Load Default Loadout On Respawn and the order of the project’s save restore. Make one system responsible for adding the final amounts.

Persistence, multiplayer, and UIS ownership

The built-in UCC Inventory does not include a general persistence component that saves arbitrary inventory amounts. A project save system should record each stable Item Type ID and amount, resolve those IDs through the same Item Collection, restore them with the Inventory API, and then restore or request the intended Item Set after the Character Items have been created.

UCC includes conditional multiplayer hooks for authoritative item addition, removal, equipment, pooling, and dropped-object spawning. Those hooks do not provide a transport or complete inventory replication layer by themselves; use the supported networking integration and perform mutations on the authoritative instance.

Ultimate Inventory System is a different ownership model. It provides collections, mutable item data, equipment UI, shops, crafting, and its own saving workflow. In the UCC integration, UIS owns those items and the bridge presents them to UCC as Character Items and Item Sets. Do not keep both the standard UCC Inventory and the UIS character inventory bridge active on the same character.

Item creation builds Item Types and Character Item prefabs.
Item Type, Definition, and Category explains the identifiers, capacity, and category data used by Inventory.
Character Item configures slots, visible objects, item actions, and drop prefabs.
Item Set and Rules controls valid equipment combinations.
Item Pickup covers pickup object settings.
Equip Unequip controls animated equipment transitions.
Drop removes equipped items and spawns their pickup prefabs.
Ultimate Inventory System integration replaces built-in inventory ownership with UIS.

Developer reference

Depend on InventoryBase when code should work with the standard Inventory or a supported inventory bridge. The standard Inventory implementation stores the amounts, active items, default loadout, removal exceptions, and loadout-equip behavior.

Query and change amounts

GetAllItemIdentifiers() returns the identifiers currently owned. GetAllCharacterItems() returns the spawned Character Items, which is a different collection and can contain the slot-specific objects for an identifier.

using Opsive.Shared.Inventory;
using Opsive.UltimateCharacterController.Inventory;
using UnityEngine;

public static class InventoryExample
{
    public static void AddAndRemove(GameObject character, IItemIdentifier itemIdentifier)
    {
        var inventory = character.GetComponent<InventoryBase>();
        if (inventory == null || itemIdentifier == null) {
            return;
        }

        var amountBefore = inventory.GetItemIdentifierAmount(itemIdentifier);
        var amountAdded = inventory.AddItemIdentifierAmount(itemIdentifier, 1);
        var amountRemoved = inventory.RemoveItemIdentifierAmount(itemIdentifier, 1);
        Debug.Log($"{amountBefore} before, {amountAdded} added, {amountRemoved} removed.");
    }
}

AdjustItemIdentifierAmount(itemIdentifier, amount) accepts a positive amount to add or a negative amount to remove. The returned value is the actual adjustment, so capacity and removal rules can make it smaller than the request.

Call PickupItem when the caller must supply a slot, immediate-pickup choice, or force-equip choice. The two-argument AddItemIdentifierAmount follows the Inventory’s automatic Character Item spawning setting; with automatic spawning enabled, it routes through PickupItem and sends pickup notifications. The overload that accepts spawnCharacterItems changes the amount without calling the outer PickupItem path. However, when it creates or reinitializes a Character Item for an owned identifier, the spawn callback calls OnItemIdentifierPickedUp and sends OnInventoryPickupItemIdentifier and OnInventoryPickupItem. It is therefore not a notification-free add when spawning occurs. Pass spawnCharacterItems: false when you need an amount-only adjustment; the amount-adjustment event still fires.

Equip and drop through the owning systems

Use ItemSetManagerBase.TryEquipItemSet for normal equipment requests:

var itemSetManager = character.GetComponent<ItemSetManagerBase>();
var equipped = itemSetManager != null &&
               itemSetManager.TryEquipItemSet("IronSword", -1, true, false);

The group index -1 searches the groups for a matching Item Set name. The final two arguments request a forced transition and a non-immediate transition. Use the Character Item Drop Prefab and the Drop ability for a player-facing drop. Lower-level code can use RemoveItemIdentifierAmount(itemIdentifier, slotID, amount, true) or DropCharacterItem, but it is then responsible for the intended authority and animation timing.

Listen for inventory events

The Inventory Inspector exposes Unity Events for add, pickup, equip, amount adjustment, unequip, and remove. The Opsive Event System provides the corresponding runtime messages, including:

OnInventoryAdjustItemIdentifierAmount with (IItemIdentifier, int previousAmount, int newAmount);
OnInventoryPickupItemIdentifier with (IItemIdentifier, int amount, bool immediatePickup, bool forceEquip);
OnInventoryPickupItem with (CharacterItem, int amount, bool immediatePickup, bool forceEquip);
OnInventoryWillAddItem and OnInventoryAddItem with (CharacterItem);
OnInventoryEquipItem and OnInventoryUnequipItem with (CharacterItem, int slotID);
OnInventoryRemoveItem with (CharacterItem, int slotID); and
OnInventoryLoadDefaultLoadoutComplete and OnInventoryRespawned without parameters.