Item Actions

Item Actions are used to perform actions on an item from the Inventory. It should not be confused with item object behaviors which are meant to use items within the game world, having a reference to a GameObject (such as swinging a sword).

The Item Drop action is a good example of an Item Action. It is used to drop an item from the inventory.

Item Actions have two main methods. CanInvoke(ItemInfo, ItemUser) and Invoke(ItemInfo, ItemUser). Using the Item Info you can create your own logic that lets you choose when an action can or cannot be performed. If the action can be performed then you can access the item attributes to invoke an action specific to the item used. The Item User allows you to pass in a reference to an Item User object, which is usually located on the Player Character. This is useful if you wish get references to components on a character.

Item Actions can be used anywhere at any time but they are mostly used in Item View Slots Containers like the Inventory Grid or Item Hotbar. With the Item Action Set and Category Item Action Set you can map Item Categories to different Item Actions.

Item Action Set

Item Action Set is a Scriptable Object that can be created from Create -> Ultimate Inventory System -> Item Actions -> Item Action Set.  Using the same path you’ll be able to create the Category Item Action Set.

Item Action Sets let you set a list of Item Actions that are relevant to the Item Category specified. For example a “Pickupable” Item Category could have a “Drop” action.

You may also add categories to the exclude categories. These categories will be used by the Category Item Action Set to find all Item Actions which matches with an Item.

Category Item Action Set

The Category Item Action Set is a list of Item Action Sets and it can be used by the “Item View Slots Container Category Item Action Set Binding” component to match item actions for a selected Item. This allows the UI to know which actions can be used by an item and will behave accordingly. For example an item “Sword” could be part of an “Equippable”, “Pickupable” and “Hotbar Item” Item Category. Which mean the Item Actions available for the “Sword” will be “Equip”, “Drop” and “Assign” each from a different Item Action Set object. The Inventory Grid inspector the list of item action will allow you to show a list of possible action when clicking on an item.

Item Action API

Creating your own Item Action is very simple, you simply need to create a new class that inherits Item Action and override the CanInvokeInternal and InvokeActionInternal function.

[System.Serializable]
public class MyItemAction : ItemAction
{
    /// <summary>
    /// Can the item action be invoked.
    /// </summary>
    /// <param name="itemInfo">The item info.</param>
    /// <param name="itemUser">The item user (can be null).</param>
    /// <returns>True if it can be invoked.</returns>
    protected override bool CanInvokeInternal(ItemInfo itemInfo, ItemUser itemUser)
    {
        // Return true if the item can be invoked or false if it cannot.
        return true;
    }

    /// <summary>
    /// Consume the item.
    /// </summary>
    /// <param name="itemInfo">The item info.</param>
    /// <param name="itemUser">The item user (can be null).</param>
    protected override void InvokeActionInternal(ItemInfo itemInfo, ItemUser itemUser)
    {
        // Invoke the item action
    }
}

There are a few special Interfaces and abstract Item Actions which can be particularly useful when creating a custom Item Action. Here is a list:

• IActionWithPanel: Allows you to set the Panel which called the Item Action. Example : Move Item Action
• ItemActionWithQuantityPickerPanel: Spawns a Quantity Picker Panel from prefab and uses async/await to get a quantity before calling the “real” Item Action. Example: Quantity Drop Item Action.
• ItemViewSlotsContainerItemAction: An Item Action with a reference to an Item View Slots Container. Example : Open Other Item View Slots Container Item Action.
• ItemActionWithAsyncFuncActionPanel<T>: Spawns an Async Func Action Panel which can be used to show a list of options. Example: Assign Hotbar Item Action
• ItemObjectAction : Lets you reference an Item Object which may be useful when the Item User has no way to identify the relevant Item Object from the Item Info.

Once your custom Item Action is created it will appear in the Item Action type drop down of the Category Item Actions object.

Call an Item Action directly through code, no UI

In the example below we try to drop two Apples.

public void ManuallyCallDropItemAction()
{
    //To call an item action directly in code you will need 3 things
    //1) The ItemInfo
    //2) The ItemAction
    //3) The ItemUser

    //First get the item you want. Here we'll get the first stack of apples we find.
    var result = m_Inventory.GetItemInfo(InventorySystemManager.GetItemDefinition("Apple"));
    
    //if the result does not have a value we do no have Apples in the inventory
    if(result.HasValue == false){ return; }
    //We have the apple ItemInfo now.
    var appleItemInfo = result.Value;
    
    //Lets trim to 2 apples maximum
    appleItemInfo = new ItemInfo(Mathf.Max(2, appleItemInfo.Amount), appleItemInfo);
    
    //Lets get the ItemUser. This is usually placed of the same gameobject as the Inventory, but not always
    var itemUser = m_Inventory.GetComponent<ItemUser>();
    
    //now lets create the drop item action, You can cache this object and reuse it if you which for more performance.
    var dropItemAction = new DropItemAction();
    
    //You must initialize the item action before using it. This can be only once
    dropItemAction.Initialize(false);
    
    //OPTIONAL: check if you are allowed to invoke the action (it will do this anyways internally)
    var canInvoke = dropItemAction.CanInvoke(appleItemInfo, itemUser);
    
    //Invoke the action
    dropItemAction.InvokeAction(appleItemInfo, itemUser);
    
    //For some actions you'll even have extra data you can use
    //For example drop action keeps track of the last dropped pickup object
    var droppedPickup = dropItemAction.PickUpGameObject;
}

Note: not all item actions will work calling them directly like this. Some are depedent on additional data, like the MoveItemAction and a few others which inherit IActionWithPanel and expect a reference to a ItemViewSlotContaner or a panel. These can be set through code.