Built-in Item Actions

Export

Ultimate Inventory System Version 1 includes 16 concrete Item Action types. Use them to inspect an item, move or remove it, open a choice panel, assign it to a hotbar, or compose a larger interaction. The action receives the selected ItemInfo, so its amount, collection, Inventory, and Item User determine what happens.

The Name field is the label shown to the player. Set it deliberately, especially for ItemActionWithConfirmationPopUp, MoveToInventoryItemAction, and UnAssignHotbarItemAction, which do not set a default name. OpenOtherItemViewSlotContainerItemAction defaults to the developer-oriented label Select ExternalItemAction, so it should normally be renamed too.

Choose an action by outcome

Player outcome Start with Example
Inspect the selected item DebugItemAction or DebugItemObjectAction Check the resolved attributes on an Iron Sword.
Put an item into the world DropItemAction or QuantityDropItemAction Drop one Health Potion or choose an amount from a stack.
Delete or copy an inventory entry RemoveItemAction or DuplicateItemAction Remove a consumed potion during a prototype.
Equip, unequip, transfer, or reposition MoveToCollectionItemAction, MoveToInventoryItemAction, or MoveItemAction Move an Iron Sword between Bag and Equipment.
Run a definition-specific effect UseItemActionSetAttribute Invoke the action referenced by a Health Potion or Fire Wand attribute.
Run several actions together MultiItemAction Invoke a Fire Wand effect and play its sound from one button.
Ask before continuing ItemActionWithConfirmationPopUp Confirm before removing an Iron Sword.
Play feedback PlayAudioClipItemAction Play the configured Fire Wand sound.
Assign or clear a hotbar slot AssignHotbarItemAction or UnAssignHotbarItemAction Assign a Health Potion to slot 1.
Select a slot in another panel OpenOtherItemViewSlotContainerItemAction Choose an ingredient from Bag for another UI.

Inspect item data

These actions are diagnostic. Both remain eligible even when the selected ItemInfo has no Item, so the Console output can expose missing data.

Item Action type Default name and settings Result and requirements
DebugItemAction Name: Debug; no additional fields Logs the selected ItemInfo, Item Definition, Category, and resolved Item, Definition, and Category attributes. A missing Item is reported instead of rejected.
DebugItemObjectAction Name: Debug; no additional serialized fields Adds the Item Object and Item User to the same diagnostic output. The caller must supply the target through SetItemObject; otherwise the logged Item Object is null.

Use DebugItemAction for an inventory or menu problem. Use DebugItemObjectAction only when the interaction already knows which scene ItemObject belongs to the action.

Drop, remove, or duplicate items

Item Action type Important fields and Version 1 defaults Result and requirements
DropItemAction Name: Drop; Pick Up Item Prefab: none; Drop One: off; Remove On Drop: off; Drop Radius: 2; Center Offset: (0, 0, 0) Spawns the selected amount near the Item User, or near the Inventory when there is no Item User. The prefab root must contain an ItemObject or an Inventory. Turn on Remove On Drop for a true transfer; the default creates the world object without removing the inventory entry.
QuantityDropItemAction Name: Drop; Quantity Panel Prefab: none; Pick Up Item Prefab: none; Remove On Drop: off; Drop Radius: 2; Center Offset: (0, 0, 0) Opens a quantity picker from 1 to the selected amount, then follows the same drop rules. A single item bypasses the panel. It requires a valid QuantityPickerPanel prefab and panel context when the amount is greater than one.
RemoveItemAction Name: Remove; Remove Amount: -1 Removes the selected amount from its current Item Collection. A value of 0 or less removes the full selected amount; a positive value removes no more than that value. It does not create a pickup.
DuplicateItemAction Name: Duplicate; no additional fields Adds an amount of 1 for the selected Item to the same Item Collection. Collection restrictions and overflow still apply. This reuses the same Item; it is not a deep copy of a mutable Item.

The drop actions report configuration problems only when invoked: their eligibility check does not validate the prefab, actor, or removal result. Test both the spawned object and the inventory count. For an Opsive Character Controller character, use the integration’s specialized drop actions so the world drop follows the character-controller workflow.

Equip, transfer, or reposition items

Item Action type Important fields and Version 1 defaults Result and requirements
MoveToCollectionItemAction Name: Equip; First Collection ID: Main; Second Collection ID: Equipped; Move From First To Second Action Name: Equip; Move From Second To First Action Name: Unequip Moves the complete selected amount between two collections in the same Inventory and changes its label for the current direction. It checks removal, destination capacity, restrictions, and equipment-slot exchange before becoming available. A displaced slot item returns to the source collection.
MoveToInventoryItemAction Name: empty; Target Inventory ID: 1; Target Collection ID: Equipped Removes the selected item from its source collection and adds it to the registered target Inventory and collection. An unaccepted amount returns to the source, and a displaced slot item moves back to the source collection. Its eligibility check confirms the two target references, but does not preflight all add or remove restrictions.
MoveItemAction Name: Move; no additional fields Starts the ItemViewSlotMoveCursor at the selected slot. It is available only when the action receives an Item View Slots Container and that container has an ItemViewSlotMoveCursor; the destination selection completes the move.

For an Iron Sword, the usual Version 1 setup is a Bag collection with the Main purpose and an Equipment ItemSlotCollection with the Equipped purpose. The default MoveToCollectionItemAction then produces one Equip/Unequip button and preserves the item displaced from the equipment slot.

Use MoveToInventoryItemAction only for a different Inventory Identifier, such as moving an item into a companion or storage Inventory. It is not the normal Bag-to-Equipment action within one Inventory.

Use, combine, or confirm effects

Item Action type Important fields and Version 1 defaults Result and requirements
UseItemActionSetAttribute Name: Use; Attribute Name: ItemActionSet; Action Index: 0; Use One: on; Remove On Use: off; Cooldown Attribute Name: Cooldown; Cooldown Item User Data Name: ItemCooldown Reads an ItemActionSet attribute from the selected Item and invokes the indexed nested action. Use One sends an amount of one. Remove On Use removes that amount after the invocation attempt. A float cooldown attribute stores the next-use time on the Item User and raises the Version 1 used-with-cooldown event.
MultiItemAction Name: Use; All Conditions Must Pass: off; Item Action Set: none Invokes every action in the referenced set in list order. When All Conditions Must Pass is on, every nested CanInvoke check must pass before the sequence starts. When it is off, the wrapper stays available and each nested action performs its own check. The action set reference is required.
ItemActionWithConfirmationPopUp Name: empty; Confirmation Pop Up Prefab: none; Item Action Set On Confirm: none; Item Action Set On Cancel: none Opens the configured ConfirmationPopUp. Confirm and cancel each invoke every action in their corresponding set, then close the popup. It requires a parent display panel, previous selection, parent transform, and popup prefab supplied by a panel-aware UI binding.
PlayAudioClipItemAction Name: Play Audio; Audio Clip Set: empty Plays one of the configured clips. It is always eligible and the core implementation does not supply a scene GameObject to the audio set; subclass it when the sound must originate from a specific object.

UseItemActionSetAttribute is a wrapper, not a healing or casting system. For a Health Potion, place the actual restore-health action at index 0 of an Item Action Set, reference that set from an ItemActionSet attribute, and turn on Remove On Use. For a Fire Wand, the referenced set can contain a custom cast action. A MultiItemAction can then combine that use action with PlayAudioClipItemAction.

The wrapper confirms that the attribute, action set, and index exist, but it does not require the nested action’s eligibility check to pass before applying Remove On Use and cooldown. Verify the nested effect as well as the item count. A cooldown attribute also requires a valid Item User; the cooldown data stored on that Item User is runtime state and is not automatically saved.

Work with hotbars and other panels

Item Action type Important fields and Version 1 defaults Result and requirements
AssignHotbarItemAction Name: Assign; Async Func Action Panel Prefab: none; Add Cancel Option: on; Display Panel Manager ID: 0; Hotbar Panel Name: Item Hotbar; Toggle Assign: off; Show Item Names: off; Use Item View Slot If Available: on Finds the named display panel and its bound ItemHotbar, opens one choice per hotbar slot, and adds the selected Item to that slot. ID 0 can fall back to the parent panel manager. Toggle Assign lets the same choice clear a matching assignment. The selected item must still exist in its Item Collection.
UnAssignHotbarItemAction Name: empty; no additional fields Clears the selected ItemHotbar slot without removing the item from its Inventory. Add it only to a hotbar’s action set: its base eligibility check knows that a slot container exists, but does not confirm that the container is an ItemHotbar.
OpenOtherItemViewSlotContainerItemAction Name: Select ExternalItemAction; Display Unique Name: empty Opens another panel by its exact unique name and waits for a slot selection. Both panels need Item View Slots Container bindings. When the origin has an ItemViewDropHandler, the selection follows that drop workflow; otherwise the selected target ItemInfo is added through the origin container.

AssignHotbarItemAction does not require the legacy ItemHotbarOwner setup described by older copies of this page. In Version 1 it resolves a DisplayPanelManager, finds Hotbar Panel Name, then looks for an ItemHotbar on the panel’s bound Item View Slots Container.

Its prefab must contain an AsyncFuncActionsPanel<int> or a subclass. With Show Item Names off, the choices are numbered from 1; with it on, each choice uses the item currently assigned to that slot or Empty. When Use Item View Slot If Available is on and the choice buttons are Item View Slots, the action also draws each slot’s current ItemInfo.

Configure the sample items

  1. Open the Item Action Set used by the item’s Category. Under Item Actions, add an entry and select its Item Action type.
  2. For Health Potion, add UseItemActionSetAttribute, rename it Drink, keep Use One on, and turn on Remove On Use. Add an ItemActionSet attribute named ItemActionSet to the item data and place the actual potion effect at action index 0 in that referenced set.
  3. For Iron Sword, add MoveToCollectionItemAction. Keep Main and Equipped when Bag and Equipment use those purposes, and keep the Equip/Unequip labels.
  4. For Fire Wand, add UseItemActionSetAttribute for the wand’s custom cast effect. Add AssignHotbarItemAction when the player should choose a hotbar slot; set a valid async action-panel prefab and match Hotbar Panel Name to the panel’s unique name.
  5. Give every visible action a short player-facing Name. Avoid exposing class-style defaults such as Select ExternalItemAction.

Editor checkpoint: each Item Action Set should list the intended concrete type, all required object references should be assigned, and the action names should read naturally together. The Health Potion should show Drink, the Iron Sword should show Equip, and the Fire Wand should show Use and Assign when its prerequisites are present.

Verify in Play Mode

Test Expected result What it verifies
Select Health Potion and choose Drink The custom effect occurs, exactly one potion is removed, and the action is unavailable during a configured cooldown. Attribute spelling, action index, nested effect, Item User, removal, and cooldown.
Select Iron Sword and choose Equip, then select it in Equipment The sword moves from Bag to Equipment; the action label changes to Unequip and moves it back. Collection purposes, slot compatibility, restrictions, and dynamic action name.
Select Fire Wand and choose Assign The slot-choice panel opens, the chosen hotbar slot displays the wand, and the wand remains in its collection. Panel manager resolution, panel name, binding, and hotbar assignment.
Drop a Health Potion A configured pickup appears near the player and the Bag amount changes only when Remove On Drop is on. Prefab contents, spawn reference, selected amount, and removal choice.

Also test an ineligible case: fill or restrict the Equipment collection, then select the Iron Sword. MoveToCollectionItemAction should not offer a move that cannot complete in full.

Troubleshooting

An action is missing from the menu

Symptom: the selected item has no expected action.

Check: confirm the Category Item Action Set includes the item’s Category, does not exclude it, and the concrete action’s prerequisites pass. Panel actions also need the Item View Slots Container binding to supply panel and slot context.

Fix: correct the Category mapping or the failing collection, attribute, panel, or slot reference. Use DebugItemAction to confirm which Category and attributes the Item resolves.

Drop creates a copy or creates nothing

Symptom: a pickup appears but the Bag count does not change, or no useful pickup appears.

Check: inspect Remove On Drop, Pick Up Item Prefab, and the Console. The prefab root must contain an ItemObject or Inventory, and the action needs an Item User or Inventory GameObject as its spawn reference.

Fix: turn on Remove On Drop for a transfer and assign a compatible prefab. Test both the spawned object and the source count.

A quantity, confirmation, or slot-choice panel fails to open

Symptom: the action logs a missing reference, throws when invoked, or opens no usable panel.

Check: confirm the correct panel prefab and component are assigned and that the action was opened from a panel-aware item-action binding.

Fix: use a QuantityPickerPanel, ConfirmationPopUp, or matching async-function panel prefab as required, and supply it from an Item View Slots Container action workflow.

Equip, move, or hotbar assignment does nothing

Symptom: the action is unavailable, warns, or leaves the item unchanged.

Check: compare collection purposes and restrictions; confirm the destination slot accepts the Item; verify ItemViewSlotMoveCursor for MoveItemAction; and match Hotbar Panel Name exactly to a panel bound to an ItemHotbar.

Fix: correct the collection or slot configuration, add the required cursor, or repair the panel binding. Use UnAssignHotbarItemAction only from the hotbar container.

Use removes an item but the effect does not occur

Symptom: the Health Potion count decreases without restoring health.

Check: confirm the ItemActionSet attribute name, referenced set, Action Index, and nested action’s own prerequisites. The wrapper can remove the item after a nested invocation attempt that did not run.

Fix: make the nested action eligible before enabling Remove On Use, and test the effect and amount together.

Version 1 behavior and limitations

  • The core actions do not implement healing, spell casting, weapon use, or character animation. Put that behavior in a custom or integration action and call it through the appropriate wrapper.
  • Drop, duplicate, remove, audio, quantity-drop, and confirmation actions have permissive eligibility checks. A visible button is not proof that every required reference is valid.
  • Inventory mutations use the normal Item Collection add/remove paths and therefore their restrictions, overflow handling, and collection events. Panel-only choices and Item User cooldown data are transient unless another system saves them.
  • The core package does not replicate Item Action invocation over a network. Synchronize the resulting inventory and gameplay state in the networking solution used by the project.
  • The Opsive Character Controller integration provides specialized drop and equip actions. Prefer those for integrated characters rather than combining the generic core actions with character equipment manually.

Developer reference

Invocation and events

ItemAction.InvokeAction(ItemInfo itemInfo, ItemUser itemUser) calls CanInvoke before the concrete implementation. The action must be initialized. When itemUser is null and the ItemInfo has an Inventory, Version 1 uses Inventory.ItemUser as the fallback.

The concrete core types do not expose one common success event. Instead:

  • Item Collection changes raise the standard add, remove, update, rejection, and overflow events.
  • ActionPanel<T> exposes OnActionsAssigned, OnBeforeAnyItemActionInvoke, and OnAfterAnyItemActionInvoke; the Item View Slots Container binding also exposes On Cannot Open Panel, On Action Canceled, and On Action Invoked UnityEvents.
  • UseItemActionSetAttribute raises EventNames.c_CharacterGameObject_UsedItemActionWithCooldown_ItemAction_ItemInfo_Float only when it applies a configured cooldown.

Abstract extension types

Base type Context it supplies Key Version 1 field or method
ItemActionWithQuantityPickerPanel Opens a pooled quantity panel under the parent display panel and awaits an integer. Quantity Panel Prefab; override SetupQuantityPickerSettings and InvokeWithAwaitedValue.
ItemActionWithAsyncFuncActionPanel<T> Opens a list of asynchronous choices and awaits a value of type T. Async Func Action Panel Prefab; Add Cancel Option defaults on; override InvokeWithAwaitedValue.
ItemObjectAction Holds a scene ItemObject supplied by the caller. Call SetItemObject before invocation.
ItemViewSlotsContainerItemAction Receives the origin Item View Slots Container, selected slot index, display panel, and previous selection. Implements the panel and slot-container context used by move, unassign, and external-panel actions.

The catalogs above cover all 16 concrete Item Action classes shipped in the Version 1 core package. Integration packages can add more types with product-specific prerequisites.