# Inventory

## 🎒 Inventory Class

Inventool's inventory logic handler and data container.

> Namespace: `Esper.Inventool`
>
> Access: `public`
>
> Type: `class`
>
> Inherits: `Vault`

***

### 📦 Fields

| Access   | Field                         | Type                                     | Description                                                                                                                                                          |
| -------- | ----------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `public` | `enableEquipment`             | `bool`                                   | If the inventory's character equipment section should be enabled.                                                                                                    |
| `public` | `enableFreeCrafting`          | `bool`                                   | If free crafting should be enabled.                                                                                                                                  |
| `public` | `enableFreeEnchanting`        | `bool`                                   | If free enchanting should be enabled.                                                                                                                                |
| `public` | `enableKeyItems`              | `bool`                                   | If the key items should be enabled. If this is enabled, key items will have their own section in the UI and will not contribute to weight.                           |
| `public` | `useWeights`                  | `bool`                                   | If the inventory should use weights.                                                                                                                                 |
| `public` | `enableDismantling`           | `bool`                                   | If item dismantling should be enabled.                                                                                                                               |
| `public` | `totalItemWeight`             | `float`                                  | The current weight of all items. This is the cached value since the last time RecalculateTotalWeight was used.                                                       |
| `public` | `maxWeight`                   | `float`                                  | The max number of item weight the inventory can hold.                                                                                                                |
| `public` | `disallowNewItemsIfMaxWeight` | `bool`                                   | If the player should not be able to obtain new items if the weight has reached the max value.                                                                        |
| `public` | `showSubtypeInKeyItemsTab`    | `bool`                                   | If the details in the key items tab should display subtype names.                                                                                                    |
| `public` | `allowItemDropping`           | `bool`                                   | If item dropping should be allowed.                                                                                                                                  |
| `public` | `showSubtypes`                | `bool`                                   | If item subtypes should be displayed in the inventory filter list.                                                                                                   |
| `public` | `deleteItemsOnDrop`           | `bool`                                   | If the item should be deleted on drop.                                                                                                                               |
| `public` | `enchantingSlotLeftIcon`      | `Sprite`                                 | The icon of the left enchanting slot.                                                                                                                                |
| `public` | `enchantingSlotRightIcon`     | `Sprite`                                 | The icon of the right enchanting slot.                                                                                                                               |
| `public` | `enchantingSlotLeftIconTint`  | `Color`                                  | The color tint of the left enchanting slot.                                                                                                                          |
| `public` | `enchantingSlotRightIconTint` | `Color`                                  | The color tint of the right enchanting slot.                                                                                                                         |
| `public` | `noFilterIcon`                | `Sprite`                                 | The icon of the no filter button.                                                                                                                                    |
| `public` | `noFilterIconColorTint`       | `Color`                                  | The color tint of the no filter icon.                                                                                                                                |
| `public` | `onItemUsed`                  | `UnityEvent<ItemStack>`                  | A callback for when an item is used. This accepts 1 argument: the item used (ItemStack).                                                                             |
| `public` | `onItemPickedUp`              | `UnityEvent<ItemStack, string>`          | A callback for when an item is picked up. This accepts 2 arguments: the item picked up (ItemStack), the item drop ID (string).                                       |
| `public` | `onItemDropped`               | `UnityEvent<ItemStack>`                  | A callback for when an item is dropped. This accepts 1 argument: the item dropped (ItemStack).                                                                       |
| `public` | `onItemFailedToAdd`           | `UnityEvent<ItemStack, InventoryError>`  | 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). |
| `public` | `onItemEnchanted`             | `UnityEvent<ItemStack, ItemStack>`       | A callback for when an item is enchanted. This accepts 2 arguments: the item enchanted (ItemStack), the item used to enchant (ItemStack).                            |
| `public` | `onEnchantmentFailed`         | `UnityEvent<string>`                     | A callback for when an item has failed to enchant. This accepts 1 argument: the reason of failure (string).                                                          |
| `public` | `onMaxWeightExceeded`         | `UnityEvent`                             | A callback for when the weight limit is exceeded.                                                                                                                    |
| `public` | `onMaxWeightExited`           | `UnityEvent`                             | A callback for when the weight limit is exited.                                                                                                                      |
| `public` | `onKeyItemsAdded`             | `UnityEvent<ItemStack>`                  | A callback for when a key item is added to the inventory. This accepts 1 argument: the key item (ItemStack).                                                         |
| `public` | `onItemsUpdated`              | `UnityEvent`                             | A callback for when the item list is updated.                                                                                                                        |
| `public` | `onCurrencyAdded`             | `UnityEvent<Currency>`                   | A callback for when currency is added. This accepts 1 argument: the amount added (Currency).                                                                         |
| `public` | `onCurrencyRemoved`           | `UnityEvent<Currency>`                   | A callback for when currency is removed. This accepts 1 argument: the amount removed (Currency).                                                                     |
| `public` | `onItemDismantled`            | `UnityEvent<ItemStack, List<ItemStack>>` | A callback for when an item is dismantled. This accepts 2 arguments: the dismantled item (ItemStack), the list of result items (List\<ItemStack>).                   |

***

### 🔧 Properties

| Access   | Property            | Type   | Description                                              |
| -------- | ------------------- | ------ | -------------------------------------------------------- |
| `public` | `MaxWeightExceeded` | `bool` | If the total item weight is greater than the max weight. |

***

### 🧰 Methods

| Access   | Method                                                                  | Returns    | Description                                                                                                                                                                                                                                                       |
| -------- | ----------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `public` | `ClearData()`                                                           | `void`     | Clears all runtime data.                                                                                                                                                                                                                                          |
| `public` | `ResetCurrencies()`                                                     | `void`     | Resets all currencies.                                                                                                                                                                                                                                            |
| `public` | `HasEnoughCurrency(Currency amount)`                                    | `bool`     | Checks if the player has enough currency equal to greater than an amount. Returns true if the player has enough currency of the specific type to spend. Otherwise, false.                                                                                         |
| `public` | `TrySpend(Currency amount)`                                             | `bool`     | Tries to spend an amount of a currency of a player currency of the same identity. Returns true if the player has enough currency of the specific type to spend. Otherwise, false.                                                                                 |
| `public` | `GetCurrency(CurrencyIdentity identity)`                                | `Currency` | Gets a currency by identity. Returns the currency of the identity or default if one with the identity doesn't exist.                                                                                                                                              |
| `public` | `SetCurrency(Currency value)`                                           | `void`     | Sets a relevant currency to a specified value.                                                                                                                                                                                                                    |
| `public` | `TryEarn(Currency amount)`                                              | `bool`     | Adds an amount of a currency to a player currency of the same identity. Returns true if the currency was earned. The currency may not be earned if there is no currency in the inventory of the same identity.                                                    |
| `public` | `HasSpaceForItem(ItemStack itemStack)`                                  | `bool`     | Checks if the inventory has space for an item. This may also include weights. Returns true if there is space for the item stack. Otherwise, false.                                                                                                                |
| `public` | `HasSpaceForItem(Item item, int quantity = 1)`                          | `bool`     | Checks if the inventory has space for an item. This may also include weights. Returns true if there is space for the item stack. Otherwise, false.                                                                                                                |
| `public` | `Dismantle(ItemStack itemStack)`                                        | `bool`     | Dismantles an item stack. This will fail if the item stack can't be dismantled, if dismantling is disabled, if the item stack is not in the inventory. Returns true if the item was successfully dismantled.                                                      |
| `public` | `UseItem(ItemStack itemStack, int amount = 1)`                          | `void`     | This will use a specific amount of an item stack. To make something happen when an item is used, use the onItemUsed event.                                                                                                                                        |
| `public` | `PickUpAllItemsInRange()`                                               | `void`     | Picks up all items in range of the player that can fit in the inventory.                                                                                                                                                                                          |
| `public` | `PickUpItem(ItemDrop itemDrop)`                                         | `bool`     | Picks up an item. The item may not be picked up if there was no space for it in the inventory. Returns true if the item was picked up. Otherwise, false.                                                                                                          |
| `public` | `DropItem(ItemStack itemStack, int amount = 0, bool useTimeout = true)` | `void`     | Drops an item from the inventory.                                                                                                                                                                                                                                 |
| `public` | `ClearItems()`                                                          | `void`     | Simply clears the item lists.                                                                                                                                                                                                                                     |
| `public` | `SetItems(params ItemStack[] itemStacks)`                               | `void`     | Sets the items. This will override the previous item list.                                                                                                                                                                                                        |
| `public` | `SetItems(List<ItemStack> itemStacks)`                                  | `void`     | Sets the items. This will override the previous item list.                                                                                                                                                                                                        |
| `public` | `CanAddToExistingStack(ItemStack itemStack)`                            | `bool`     | Checks if an item stack can be completely added to existing stacks. Returns true if the item stack can be added to another. Otherwise, false.                                                                                                                     |
| `public` | `TryAddToExistingStack(ItemStack itemStack)`                            | `bool`     | Tries to combine an item stack to an existing item stacks in the inventory. This will decrease the amount of the item stack provided with the potential of emptying it. Returns true if any amount of the item stack was combined with another. Otherwise, false. |
| `public` | `AddItem(ItemStack itemStack)`                                          | `bool`     | Adds an item. Returns true if the item was successfully added. Otherwise, false.                                                                                                                                                                                  |
| `public` | `AddItems(params ItemStack[] itemStacks)`                               | `void`     | Adds items.                                                                                                                                                                                                                                                       |
| `public` | `AddItems(List<ItemStack> itemStacks)`                                  | `void`     | Adds items.                                                                                                                                                                                                                                                       |
| `public` | `RemoveItems(params ItemStack[] itemStacks)`                            | `void`     | Removes items.                                                                                                                                                                                                                                                    |
| `public` | `RemoveItems(List<ItemStack> itemStacks)`                               | `void`     | Remove items.                                                                                                                                                                                                                                                     |
| `public` | `RecalculateTotalWeight()`                                              | `float`    | Recalculates the total weight of all items combined. Key items are excluded if they are not in the main inventory (if enableKeyItems is true). Returns the total weight of all items combined.                                                                    |
| `public` | `ItemWillExceedWeightLimit(ItemStack itemStack)`                        | `bool`     | Checks if an item will cause the weight to exceed the weight limit if it were to be added to the inventory. Returns true if the item will cause the weight to exceed the weight limit. Otherwise, false.                                                          |
| `public` | `ItemWillExceedWeightLimit(Item item, int amount = 1)`                  | `bool`     | Checks if an item will cause the weight to exceed the weight limit if it were to be added to the inventory. Returns true if the item will cause the weight to exceed the weight limit. Otherwise, false.                                                          |

***

### 🧩 Nested Enums

#### InventoryError

Types of reasons why an inventory action has failed.

| Value           | Description                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Unknown`       | An unknown error.                                                                                                          |
| `NoSpace`       | An item was not able to be added to the inventory because there was no slot space.                                         |
| `Overweight`    | An item was not able to be added to the inventory because it would cause the total weight to exceed the maximum threshold. |
| `AlreadyExists` | An item was not added to the inventory because it already exists in it.                                                    |
| `EmptyStack`    | An item was not added to the inventory due to it being empty.                                                              |
| `Unaccepted`    | Attempted to add an unaccepted item.                                                                                       |

## Accessing the Inventory

You can access the player's inventory with `Inventool.Inventory`.

## Dismantling

You can use the `Dismantle` method to dismantle an item. This will remove an item stack from the inventory and add it's dismantle result items to the inventory.

```csharp
Inventool.Inventory.Dismantle(myItemStack);
```

It's important to note that dismantling may not always work, which is why the method returns true or false.

```csharp
if (Inventool.Inventory.Dismantle(myItemStack))
{
    Debug.Log("Dismantled");
}
```

## Items

### Setting Items

You can set items with the `SetItems` method. This will remove all previous items in the inventory.

```csharp
Inventool.Inventory.SetItems(myItemStackList);
```

### Adding Items

With the `AddItems` method, you can add a single or a list of item stacks to the inventory.

```csharp
Inventool.Inventory.AddItems(myItemStack);
```

### Remove Items

With the `RemoveItems` method, you can remove a single or a list of item stacks from the inventory.

```csharp
Inventool.Inventory.RemoveItems(myItemStack);
```

### Getting Items

You can get the full list of items with the `itemStacks` and `keyItems` fields.

#### Get All Items in a Specific Page

```csharp
// Get item stacks in the first page (page numbers start at 0)
var itemStacks = Inventool.Inventory.GetAllItemsInPage(0);
```

#### Get All Items in the Current Page

```csharp
var itemStacks = Inventool.Inventory.GetAllItemsInCurrentPage();
```

#### Checking If An Item Can Fit

You can check if an item will fit in the inventory with the `HasSpaceForItem` method.

```csharp
bool result = Inventool.Inventory.HasSpaceForItem(myItem);
```

### Checking Items

You can use the `Contains` method to check and see if the player has an instance of an item in their inventory. You can use an `Item` object, the item ID, or the item name to perform this check.

```csharp
// Check if the player has an item called 'Door Key'
bool result = Inventool.Inventory.Contains("Door Key");
```

### Using Items

Items in the inventory can be used with the `UseItem` method. Used items are removed from the inventory.

```csharp
Inventool.Inventory.UseItem(itemToUse);
```

### Pick Up Items

Pick up methods simply pick up (remove) [item-drop](https://stylishesper.gitbook.io/inventool/scripting/api/items/item-drop "mention")s from the game world and adds its `itemStack` field to the player's inventory.

`PickUpAllItemsInRange` method picks up all items that the player is in range of in the game world.

```csharp
Inventool.Inventory.PickUpAllItemsInRange();
```

To pick up a single item, use `PickUpItem`.

```csharp
Inventool.Inventory.PickUpItem(itemToPickUp);
```

### Drop Items

To drop a specific item (remove it from the inventory), use the `DropItem` method. This may create an instance of an [item-drop](https://stylishesper.gitbook.io/inventool/editors/components/item-drop "mention") in the game world.

```csharp
Inventool.Inventory.DropItem(itemStackToDrop);
```

## Currencies

In the examples below, `cost` is a [currency](https://stylishesper.gitbook.io/inventool/scripting/api/currencies/currency "mention"). You can access the full list of currencies with the `Inventool.Inventory.currencies` field.

### Spending

A currency can be spent with the `TrySpend` method. This method returns a `bool`. False will be returned if the player doesn't have enough of the specific currency. Otherwise, it will return true.

```csharp
bool result = Inventool.Inventory.TrySpend(cost);
```

### Earning

You can add an amount to a player's currency with the `TryEarn` method. While this method returns a `bool`, it should always return true unless the specific currency type does not exist in the inventory.

```csharp
bool result = Inventool.Inventory.TryEarn(cost);
```

### Sufficient Funds Checking

You can check if the player has enough of a particular currency with the `HasEnoughCurrency` method and providing a cost parameter.

```csharp
bool sufficientFunds = Inventool.Inventory.HasEnoughCurrency(cost);
```

### Resetting

You can reset all currencies to their starting values with the `ResetCurrencies` method.

```csharp
Inventool.Inventory.ResetCurrencies();
```

## Weights

Weights are only relevant if the `useWeights` field is set to true.

### Max Weight

You can get and set the max weight with the `maxWeight` field.

```csharp
Inventool.Inventory.maxWeight = 100;
```

### Total Item Weight

To get the total weight of all items in the inventory, use `RecalculateTotalWeight`.

```csharp
float totalWeight = Inventool.Inventory.RecalculateTotalWeight();
```

### Checking If An Item Will Exceed the Weight

Sometimes it may be necessary to check if an item will cause the max weight to be exceeded. You can use the `ItemWillExceedWeightLimit` method for this purpose.

```csharp
bool result = Inventool.Inventory.ItemWillExceedWeightLimit(myItem);
```

## Pages & Organization

Inventory items are organized in grid-based pages. Whether your inventory 1 page or 100, the logic is the same.

### Reorganization

You can reorganize the inventory with the `Reorganize` method. **This will also recreate all pages.**

```csharp
Inventool.Inventory.Reorganize();
```

If you'd only like to regroup item stacks, use the `Regroup` method.

```csharp
Inventool.Inventory.Regroup();
```

### Filters

Inventory items can be filtered with [item-type](https://stylishesper.gitbook.io/inventool/scripting/api/items/item-type "mention"). Items that don't match the filter will not be returned when using the `GetAllItemsInPage` or `GetAllItemsInCurrentPage` methods. If the `ItemType` is a parent, items with the parent type or any of it's child types **will not** be filtered out.

#### Set the Item Filter

```csharp
Inventool.Inventory.SetItemFilter(ItemType);
```

#### Remove Item Filter

```csharp
Inventool.Inventory.RemoveItemFilter();
```

### Page Sizes

#### Setting the Size

You can set the page size by editing the `minPageSize` or `pageSize` fields. When these are changed, the inventory may need to be reorganized.

```csharp
// 6x6 inventory grid
Inventool.Inventory.pageSize = new Vector2Int(6, 6);
Inventool.Inventory.Reorganize();
```

### Pagination

#### Current Page

The current page number is stored in the `currentPage` field.

You can flip to the next page with the `NextPage` method.

```csharp
Inventool.Inventory.NextPage();
```

Similarly, you can flip to the previous page with `PreviousPage` method.

```csharp
Inventool.Inventory.PreviousPage();
```

Alternatively, you can set the current page (page numbers start at 0).

```csharp
Inventool.Inventory.SetPage(0);
```

## Customize Accepted Items

You can customize the items accepted with the `canAcceptItem` function.

#### Example

```csharp
// Only accept key items
Inventool.Inventory.canAcceptItem = itemStack =>
{
    if (itemStack.IsKeyItem)
    {
        return true;
    }

    return false;
};
```
