# Events

## Inventool

Events available in the `Inventool` class.

| Name                | Description                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| onSlotHovered       | A callback for when a UITK slot is hovered. This accepts 1 argument: the button which acts as a slot (Button). |
| onSlotClicked       | A callback for when a UITK slot is clicked. This accepts 1 argument: the button which acts as a slot (Button). |
| onButtonHovered     | A callback for when a UITK button is hovered. This accepts 1 argument: the button (Button).                    |
| onButtonClicked     | A callback for when a UITK button is clicked. This accepts 1 argument: the button (Button).                    |
| onUGUISlotHovered   | A callback for when a uGUI slot is hovered. This accepts 1 argument: the button which acts as a slot (Button). |
| onUGUISlotClicked   | A callback for when a uGUI slot is clicked. This accepts 1 argument: the button which acts as a slot (Button). |
| onUGUIButtonHovered | A callback for when a uGUI button is hovered. This accepts 1 argument: the button (Button).                    |
| onUGUIButtonClicked | A callback for when a uGUI 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 2 arguments: the item equipped (ItemStack), the affected equipment slot (EquipmentSlot).    |
| onItemUnequipped | A callback for when an item is unequipped. This accepts 2 argument: the item unequipped (ItemStack), the affected equipment slot (EquipmentSlot). |

## Windows

Each window has on open and on close events. The code will be slightly different depending on your UI choice. Here are all the windows that support these events:

* UGUI
  * InventoolWindowUGUI
  * CraftingWindowUGUI
  * EnchantingWindowUGUI
  * EquipmentWindowUGUI
  * InventoryWIndowUGUI
  * KeyItemWindowUGUI
  * ShopWindowUGUI
  * StorageWindowUGUI
* UITK
  * InventoolWindow
  * CraftingWindow
  * EnchantingWindow
  * EquipmentWindow
  * InventoryWIndow
  * KeyItemWindow
  * ShopWindow
  * StorageWindow

These events available from `[Window].Instance` (replace `[Window]` with one of the options as listed above). You must have an instance of it 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). |

## Item Stack

Events available in the `ItemStack` class.

| Name             | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| onDurabilityZero | A callback for when the durability of any item reaches zero. This accepts 1 argument: the item stack (ItemStack). |
| onLeveledUp      | A callback for when an item stack is leveled up. This accepts 1 argument: the item stack (ItemStack).             |
| onLeveledDown    | A callback for when an item stack is leveled down. This accepts 1 argument: the item stack (ItemStack).           |

## Item Drop

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.                                                              |
| onDropSpawned        | A callback for when an ItemDrop is spawned through the SpawnInstance method. This accepts 1 argument: the item drop spawned (ItemDrop). |

## Storage

Events available in the `Storage` class.

| Name                | Description                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| onItemsUpdated      | A callback for when the item list is updated.                                                                                |
| onItemDeposited     | A callback for when an item is deposited. This accepts 2 arguments: the item stored (ItemStack), the storage (Storage).      |
| onItemWithdrawn     | A callback for when an item is added. This accepts 2 arguments: the item withdrawn (ItemStack), the storage (Storage).       |
| onCurrencyDeposited | A callback for when currency is deposited. This accepts 2 arguments: the amount stored (Currency), the storage (Storage).    |
| onCurrencyWithdrawn | A callback for when currency is withdrawn. This accepts 2 arguments: the amount withdrawn (Currency), the storage (Storage). |
| onItemDropped       | A callback for when an item is dropped. This accepts 1 argument: the item dropped (ItemStack), the storage (Storage).        |
| onActionFailed      | A callback for when an action failed. This accepts 1 argument: the error type (StorageError).                                |
| onStorageOpened     | A callback for when the window is opened. This accepts 1 argument: the opened storage (Storage).                             |
| onStorageClosed     | A callback for when the window is closed. This accepts 1 argument: the closed storage (Storage).                             |

## Stats

Events available in an instance of a [stat](https://stylishesper.gitbook.io/inventool/scripting/api/stats/stat "mention").

| Name          | Description                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onChanged     | A callback for when the current value is changed. This accepts 3 arguments: the new value (StatValue), the previous value (StatValue), the effectiveness applied (float). |
| onReachedHigh | A callback for when the current value has reached the high value.                                                                                                         |
| onReachedLow  | A callback for when the current value has reached the low value.                                                                                                          |
| onLeveledUp   | A callback for when the level is increased.                                                                                                                               |
| onLeveledDown | A callback for when the level is decreased.                                                                                                                               |

## Scaling Value

Events available in an instance of a [scaling-value](https://stylishesper.gitbook.io/inventool/scripting/api/stats/scaling-value "mention").

| Name          | Description                                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| onChanged     | A callback for when the current value is changed. This accepts 2 arguments: the new value (NumericValue), the previous value (NumericValue). |
| onReachedHigh | A callback for when the current value has reached the high value.                                                                            |
| onReachedLow  | A callback for when the current value has reached its low value.                                                                             |
| onLeveledUp   | A callback for when the level is increased.                                                                                                  |
| onLeveledDown | A callback for when the level is decreased.                                                                                                  |

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

## Character Stats

| Name             | Description                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| onDurabilityZero | A callback for when the durability of any character reaches zero. This accepts 1 argument: the character stats (CharacterStats). |

## Usage Examples

The method of registering a callback for all events is similar.&#x20;

### Item Equipping Example

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

{% hint style="info" %}
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.
{% endhint %}

```csharp
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.

{% hint style="info" %}
Inventool already handles these error messages by default. This is just here for learning purposes.
{% endhint %}

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