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.

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 1 argument: the item picked up (ItemStack).
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.

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
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).

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.

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;
        }
    }
}