Item Actions

Item Actions are commands that act on an Item selected from an Inventory interface. Use them for choices such as drinking a Health Potion, equipping an Iron Sword, assigning a Fire Wand to a hotbar, moving an Item, or dropping it into the world.

An Item Action is not the visible behavior of a sword swing or spell. Those GameObject and character behaviors belong to Item Objects, abilities, or project gameplay code. The Item Action is the inventory-side command that validates the selected Item and starts that behavior or transaction.

Understand the action flow

Part	Responsibility	Standard example
Item Action	Validates and performs one command for an Item Info and Item User	Drink, Equip, or Drop
Item Action Set	Groups actions for one Item Category, with optional exception categories	Consumable actions or Weapon actions
Category Item Action Set	Orders several Item Action Sets so one Item can receive actions from every matching category	Use, Equip, then Drop
Item View Slots Container Category Item Action Set Binding	Gets the selected slot’s Item Info, finds matching actions, and opens an Item Action Panel or invokes an action directly	The action binding on the Bag grid
Item Action Panel	Presents the matching actions and invokes the player’s choice	A menu listing Drink and Drop for Health Potion
Item User	Supplies the player or character context and its inventory input	The player that owns Bag

The category mapping is additive. If Iron Sword belongs to Weapon and also matches a general droppable category, it receives the actions from both matching sets. The order of Item Action Sets in the Category Item Action Set, followed by the order of actions inside each set, determines the displayed action order.

Create the action sets

The following setup gives Health Potion a Drink command, gives Iron Sword and Fire Wand an Equip command, and gives all three Items a Drop command.

1. In the Project window, choose Create > Ultimate Inventory System > Item Actions > Item Action Set.
2. Name the first asset Consumable Item Actions, select the Inventory System Database, and set Item Category to Consumable.
3. Under Item Actions, add the project’s custom Drink action and set its Name to Drink. Its CanInvoke rule should reject Items that do not have the data required by the health system.
4. Create Weapon Item Actions, set Item Category to Weapon, and add the appropriate built-in or integration-specific equip action. Set its visible name to Equip or let a toggle action switch between Equip and Unequip when supported.
5. Create Droppable Item Actions, set Item Category to the broad category shared by Items that may be dropped, and add Drop Item Action or Quantity Drop Item Action.
6. Add any protected child categories to Exception Categories. For example, a quest-only category can inherit common Item data without receiving Drop.

An Item Action Set matches its selected category and descendant categories. Exception Categories remove their matching descendants from the action list produced for the UI.

Combine the category mappings

1. Choose Create > Ultimate Inventory System > Item Actions > Category Item Action Set.
2. Name the asset Main Inventory Category Item Actions.
3. Add Consumable Item Actions, Weapon Item Actions, and Droppable Item Actions to Category Item Actions in the order the commands should appear.
4. Avoid adding the same Item Action Set twice. Version 1 concatenates matching actions; it does not deduplicate them or apply a separate priority value.

At the editor checkpoint, selecting Health Potion should resolve Drink and Drop, while Iron Sword and Fire Wand should resolve Equip and Drop. If an Item belongs to several matching categories, verify the final combined order rather than checking only one Item Action Set.

Connect actions to an inventory grid

The UI Designer schemas normally provide the required panel and binding. When configuring a custom Inventory Grid or another Item View Slots Container:

1. Add Item View Slots Container Category Item Action Set Binding to the same UI workflow as the container.
2. Assign Action Panel when the player should choose from a list. Assign the Category Item Action Set created above.
3. Leave Auto Set Item User enabled when the bound Inventory’s Item User should perform the action. Assign Item User manually only when another actor owns the command.
4. Enable Use Item On Click when selecting or clicking a slot should open the action panel or run the configured direct action.
5. Enable Disable Action On Empty Slots and Prevent Open When No Action for a normal inventory menu.
6. Max Number Of Actions defaults to 5 and creates the initial action array. Version 1 can resize that array when more category matches are found, so this field is not a category filter or availability limit.
7. On the Item Action Panel, enable Hide Cannot Invoke Actions when unavailable commands should be omitted instead of remaining in the list and failing their final CanInvoke check.

With an Action Panel assigned, triggering the binding opens the panel and lets the player choose. Without a panel, Use Item Action Index chooses a direct action; the Version 1 default of -1 invokes every matching action. Do not leave -1 on a panel-free binding that contains several destructive or mutually exclusive commands.

Add keyboard or gamepad input

Clicking a slot is only one trigger. Add Item View Slot Container Item Action Handler when input should run the selected slot’s default or indexed action.

• Item Action Binding identifies the binding to trigger.
• Default Input calls the binding’s default flow.
• Action Inputs maps inputs to explicit action indexes.
• Handle Input Only If Panel Selected prevents a background menu from responding.
• Use Item Action Binding Item User Player Input is enabled by default and reads input from the bound Item User.

Action indexes depend on the current combined category matches. Use a stable named or dedicated action flow when different Item types produce different list orders; an index that means Drink for Health Potion may mean Equip for Iron Sword.

Keep Item Info and Item User context

The binding passes the selected slot’s Item Info to the action. This preserves the exact runtime Item, amount, Item Collection, and Item Stack context. It matters when Bag contains two unique Iron Swords, when only one Health Potion should be consumed, or when Equip must move an Item from Bag rather than finding another Item with the same definition.

ItemUser supplies the acting character and its InventoryInput. When no Item User is passed and the Item Info belongs to an Inventory, ItemAction falls back to that Inventory’s Item User. Actions that require character components should return false from CanInvoke when the required Item User or component is missing.

Every invocation calls CanInvoke before performing the action. Use that check for current state such as amount, collection, cooldown, destination capacity, or required gameplay component. Still inspect the returned results of collection transactions inside the action; availability can change between displaying a button and choosing it.

Choose built-in or custom actions

Use Built-in Item Actions for the complete Version 1 list and each action’s prerequisites. The main groups are:

• Immediate actions such as Drop, Remove, Duplicate, Move To Collection, Play Audio Clip, Multi Item Action, and Use Item Action Set Attribute.
• Panel-driven actions such as Quantity Drop, Assign Hotbar, confirmation, Move Item, and Open Other Item View Slot Container.
• Abstract base actions that provide a quantity picker, asynchronous choice panel, Item Object reference, or Item View Slots Container context for a custom action.

Create a custom action when the command belongs to the project’s gameplay rules. A Drink action, for example, can read Health Potion data, ask the character health component whether healing is possible, apply the effect, then remove exactly the amount that was consumed. Keep the health calculation in the health system rather than turning the Item Action into a second character-stat system.

Verify in Play Mode

1. Put Health Potion, Iron Sword, and Fire Wand in Bag and open the inventory menu.
2. Select Health Potion. Confirm that the panel shows Drink and Drop in the configured order and does not show Equip.
3. Select Iron Sword and Fire Wand. Confirm that each shows Equip and Drop and that the action receives the exact selected weapon.
4. Invoke Equip. Confirm that the Item moves to Equipment, the Bag and Equipment views redraw, and the command changes to Unequip when the configured action supports both directions.
5. Invoke Drink with more than one Health Potion in the stack. Confirm that only the intended amount is removed and the health effect occurs once.
6. Test with an empty slot, an Item in an exception category, a full destination collection, and a missing Item User dependency. The panel should stay closed, hide the unavailable command, or refuse invocation without losing an Item.
7. Use keyboard or gamepad input while another panel is selected. When Handle Input Only If Panel Selected is enabled, the background inventory must not invoke an action.

Saving and multiplayer

Item Action Set and Category Item Action Set assets are configuration; they do not need runtime save records. Save the results of an action through the systems the action changes. For example, use the Inventory and Item savers for a consumed Health Potion or moved Iron Sword, and the Item View Slot Container saver when a hotbar assignment must persist.

ItemUser‘s runtime action-data dictionary, an open action panel, a pending quantity choice, and an in-progress action are not automatically saved. Reconstruct transient UI state after loading, or add a project saver when a custom cooldown or action state must persist outside Item attributes.

Version 1 does not provide a general networking or authority layer for Item Actions. In a multiplayer project, validate and execute inventory-changing actions on the authoritative side, then replicate the resulting Inventory, Item, equipment, or gameplay state. Do not let each client independently remove, duplicate, equip, or drop the same Item.

Troubleshooting

Symptom	Check	Fix
No actions appear for Health Potion	Check the Item’s inherited categories, the Item Action Set’s Item Category, exceptions, and the binding’s Category Item Action Set.	Map Consumable to the intended set, remove an accidental exception, and assign the aggregate asset to the binding.
The same action appears twice	Inspect every matching Item Action Set and the aggregate list order.	Remove the duplicate action or duplicate set reference; Version 1 does not deduplicate matches.
Clicking an Item runs several actions immediately	Check whether Action Panel is empty and Use Item Action Index is -1.	Assign an Item Action Panel or choose one explicit index.
An action button appears but does nothing	Check CanInvoke, Item User dependencies, collection restrictions, and Hide Cannot Invoke Actions.	Supply the missing context or make CanInvoke explain the real availability rule; hide unavailable actions when appropriate.
Equip acts on the wrong Item or collection	Inspect the Item Info passed from the selected slot.	Use the provided Item Info and its source collection instead of searching again by Item Definition.
Keyboard input triggers a hidden inventory	Inspect Handle Input Only If Panel Selected and the handler’s player input source.	Enable panel-selection gating and bind the correct Item User input.
A panel-based action fails when called from code	Check whether it implements IActionWithPanel or IActionWithSlotContainer.	Invoke it through the binding/panel flow, or provide its required panel and slot-container context before calling it.
An action works locally but duplicates results online	Check which peer is allowed to invoke the inventory transaction.	Make one authoritative side execute the action and replicate only the result.

Current Version 1 boundaries

• Category matching is additive and ordered; there is no built-in priority or deduplication pass.
• Exception Categories are applied by GetItemActionsForItem, which is the UI binding’s filtered retrieval path. The direct CategoryItemActionSet.UseItemAction and UseAllItemActions methods do not apply exception filtering in Version 1.
• An action index is positional and can change when category mappings or action order changes.
• Panel-based and slot-container actions require UI context that a direct API call does not provide automatically.
• Item Actions run locally unless a project or integration adds authority and replication.
• The framework saves action results through Inventory, Item, hotbar, and project-specific savers; it does not serialize an action invocation in progress.

Related pages

• Built-in Item Actions describes every included action and its setup.
• Item Info explains the Item, amount, collection, and stack context passed to an action.
• Inventory covers the collections and restrictions that actions modify.
• Item View Slots Container explains the UI container that selects the target Item.
• Input Handlers covers the wider Version 1 inventory input flow.
• Item Objects explains the GameObject-side behavior that an Item Action may start or control.
• Save System covers the savers for Inventory, Item, and hotbar results.

Developer reference

A custom Item Action is a serializable class that inherits ItemAction. The editor discovers it for the Item Action type dropdown after Unity recompiles.

[System.Serializable]
public class MyItemAction : ItemAction
{
    protected override bool CanInvokeInternal(ItemInfo itemInfo, ItemUser itemUser)
    {
        return itemInfo.Item != null && itemInfo.Amount > 0;
    }

    protected override void InvokeActionInternal(ItemInfo itemInfo, ItemUser itemUser)
    {
        // Call project gameplay code and inspect every inventory transaction result here.
    }
}

• ItemAction.Initialize(false) must run before a directly created action can pass CanInvoke. Item Action Sets and panels initialize their serialized actions for you.
• ItemAction.Setup stores BoundItemInfo and BoundItemUser; InvokeAction(ItemInfo, ItemUser) performs its own CanInvoke check before calling InvokeActionInternal.
• CategoryItemActionSet.GetItemActionsForItem returns the ordered, exception-filtered actions for an Item. ItemViewSlotsContainerCategoryItemActionSetBinding uses that result for the selected slot.
• ItemViewSlotsContainerItemActionBindingBase exposes direct use by selected slot, slot index, action index, or action name. Prefer names over indexes only when action names are kept unique and stable.
• The binding exposes On Cannot Open Panel, On Action Canceled, and On Action Invoked UnityEvents. ActionPanel also exposes OnActionsAssigned, OnBeforeAnyItemActionInvoke, and OnAfterAnyItemActionInvoke C# events.
• IActionWithPanel, IActionWithSlotContainer, ItemActionWithQuantityPickerPanel, ItemActionWithAsyncFuncActionPanel<T>, and ItemObjectAction provide the extra context needed by more involved custom actions.