Events

How to handle inventory events.

When working with events, the general rule is to add a callback once when the game starts. The same callback should never be added twice.

Inventool

Events available in the Inventool class.

onSlotHovered	A callback for when a slot is hovered. This accepts 1 argument: the button which acts as a slot (Button).
onSlotClicked	A callback for when a slot is clicked. This accepts 1 argument: the button which acts as a slot (Button).
onButtonHovered	A callback for when a button is hovered. This accepts 1 argument: the button (Button).
onButtonClicked	A callback for when a button is clicked. This accepts 1 argument: the button (Button).

Inventory

Events available from Inventool.Inventory.

Name	Description
onItemUsed	A callback for when an item is used. This accepts 1 argument: the item used (ItemStack).
onItemPickedUp	A callback for when an item is picked up. This accepts 2 arguments: the item picked up (ItemStack), the item drop ID (string).
onItemDropped	A callback for when an item is dropped. This accepts 1 argument: the item dropped (ItemStack).
onItemFailedToAdd	A callback for when an item failed to be added to the inventory. This accepts 2 arguments: the item failed to be added (ItemStack), the error type (InventoryError).
onItemEnchanted	A callback for when an item is enchanted. This accepts 2 arguments: the item enchanted (ItemStack), the item used to enchant (ItemStack).
onEnchantmentFailed	A callback for when an item has failed to enchant. This accepts 1 argument: the reason of failure (string).
onMaxWeightExceeded	A callback for when the weight limit is exceeded.
onMaxWeightExited	A callback for when the weight limit is exited.
onKeyItemsAdded	A callback for when a a key item is added to the inventory. This accepts 1 argument: the key item (ItemStack).
onItemsUpdated	A callback for when the item list is updated.
onCurrencyAdded	A callback for when currency is added. This accepts 1 argument: the amount added (Currency).
onCurrencyRemoved	A callback for when currency is added. This accepts 1 argument: the amount removed (Currency).
onItemDismantled	A callback for when an item is dismantled. This accepts 2 arguments: the dismantled item (ItemStack), the list of result items (List).

Equipment

Events available from Inventool.Equipment.

Name	Description
onItemEquipped	A callback for when an item is equipped. This accepts 1 argument: the item equipped (ItemStack).
onItemUnequipped	A callback for when an item is unequipped. This accepts 1 argument: the item unequipped (ItemStack).

Inventool Window

Events available from InventoolWindow.Instance you must have an instance of anInventool Window in your scene.

Name	Description
onOpened	A callback for when the window is opened.
onClosed	A callback for when the window is closed.

Merchant

Events available in the Merchant class.

Name	Description
onActionFailed	A callback for when an action performed on any merchant fails. This accepts 2 arguments: the error type (MerchantError), the error message (string).

Crafter

Events available in the Crafter class.

Name	Description
onCraftFailed	A callback for when a crafting fails. This accepts 1 argument: the error message (string).
onCraftSucceeded	A callback for when a crafting succeeds. This accepts 1 argument: the item crafted (ItemStack).

Shopkeeper

Events available in the Shopkeeper class.

Name	Description
onItemSold	A callback for when an item is sold. This accepts 1 argument: the item sold (ItemStack).
onItemBought	A callback for when an item is bought. This accepts 1 argument: the item bought (ItemStack).

ItemDrop

Events available in the ItemDrop class.

Name	Description
onEnteredPickUpRange	A callback for when the player enters the pick up range of any item drop.
onExitedPickUpRange	A callback for when the player exits the pick up range for all item drops.

Storage

Events available in the Storage class.

Name	Description
onItemsUpdate	A callback for when the item list is updated.

Stats

Events available in the Stat class.

Name	Description
onValueChanged	A callback for when a stat's current value is changed. This accepts 3 arguments: the affected stat (Stat), the previous value (StatValue), the effectiveness applied (float).
onValueReachedMax	A callback for when a stat's current value has reached its max value. This accepts 1 argument: the affected stat (Stat).
onValueReachedMin	A callback for when a stat's current value has reached its min value. This accepts 1 argument: the affected stat (Stat).
onUpgraded	A callback for when a stat's level is upgraded. This accepts 1 argument: the affected stat (Stat).
onDowngraded	A callback for when a stat's level is downgraded. This accepts 1 argument: the affected stat (Stat).

Cross Input Support

Events available in the CrossInputSupport and CrossInputSupportUGUI classes.

Name	Description
onTab	A callback for when the tab button is pressed.
onCancel	A callback for when the cancel button is pressed.
onConfirm	A callback for when the confirm button is pressed.
onMove	A callback for when a move button is pressed.

Split UI

Events available in the CrossInputSupportedWindow and CrossInputSupportedWindowUGUI classes.

Name	Description
onOpen	A callback for when the window is opened.
onClose	A callback for when the window is closed.

Usage Examples

The method of registering a callback for all events is similar.

Item Equipping Example

Below is an example of how you can use events to equip/unequip items visually on your character model.

This method is the simplest way of handling this, but it's not great. It's recommended to somehow incorporate the custom object field that's available for all items.

using Esper.Inventool;
using Esper.Inventool.Items;
using UnityEngine;

public class EquippingEventExample : MonoBehaviour
{
    [SerializeField]
    private GameObject myItemObject;

    private void Awake()
    {
        // Register a callback that will run when an item is equipped
        Inventool.Equipment.onItemEquipped.AddListener(OnItemEquippedHandler);

        // Register a callback that will run when an item is unequipped
        Inventool.Equipment.onItemUnequipped.AddListener(OnItemUnequippedHandler);
    }

    /// <summary>
    /// Handles item equipping by enabling a specific object based on the item that was equipped.
    /// </summary>
    /// <param name="itemStack">The item stack equipped.</param>
    private void OnItemEquippedHandler(ItemStack itemStack)
    {
        // Enable the GameObject if the item name is a match
        if (itemStack.item.displayName == "My Item Name")
        {
            myItemObject.SetActive(true);
        }
    }

    /// <summary>
    /// Handles item unequipping by disabling a specific object based on the item that was equipped.
    /// </summary>
    /// <param name="itemStack">The item stack equipped.</param>
    private void OnItemUnequippedHandler(ItemStack itemStack)
    {
        // Disable the GameObject if the item name is a match
        if (itemStack.item.displayName == "My Item Name")
        {
            myItemObject.SetActive(false);
        }
    }
}

Error Message Example

Below is an example of how you can use the Merchant.onActionFailed event.

Inventool already handles these error messages by default. This is just here for learning purposes.

using Esper.Inventool.Merchants;
using Esper.Inventool.UI;
using UnityEngine;

public class EventExample : MonoBehaviour
{
    private void Awake()
    {
        // Register the callback
        Merchant.onActionFailed.AddListener(HandleMerchantError);
    }
    
    private void OnDestroy()
    {
        // Unregister the callback when the object is destroyed
        Merchant.onActionFailed.RemoveListener(HandleMerchantError);
    }

    /// <summary>
    /// Handles merchant errors by displaying the error message to the player with the
    /// InventoolConfirmPrompt.
    /// </summary>
    /// <param name="error">The merchant error type.</param>
    /// <param name="message">The error message.</param>
    private void HandleMerchantError(Merchant.MerchantError error, string message)
    {
        switch (error)
        {
            case Merchant.MerchantError.Unknown:
                InventoolConfirmPrompt.Instance.Open("Unknown Error", "An unknown error has occurred. If this persists, please contact the developer.", null, null, true, false, "Ok");
                break;

            case Merchant.MerchantError.InsufficientResources:
                InventoolConfirmPrompt.Instance.Open("Failed", message, null, null, true, false, "Ok");
                break;

            case Merchant.MerchantError.NoSpace:
                InventoolConfirmPrompt.Instance.Open("Failed", message, null, null, true, false, "Ok");
                break;

            case Merchant.MerchantError.ServiceOrGoodsNotProvided:
                InventoolConfirmPrompt.Instance.Open("Failed", message, null, null, true, false, "Ok");
                break;
        }
    }
}