# Item Stack

## 📦 ItemStack Class

Representation of a stack of items. This is the main object used for storing items in the inventory.

> **Namespace:** `Esper.Inventool.Items`\
> **Access:** `public`\
> **Type:** `class`\
> **Attributes:** `[Serializable]`

***

### 📦 Fields

| Access                | Field                 | Type                | Description                                                                   |
| --------------------- | --------------------- | ------------------- | ----------------------------------------------------------------------------- |
| `public`              | `item`                | `Item`              | The item data.                                                                |
| `public`              | `amount`              | `int`               | The number of duplicate items in this stack.                                  |
| `public`              | `placement`           | `Grid.Placement?`   | The placement of this item stack in the inventory.                            |
| `public`              | `unfilteredPlacement` | `Grid.Placement?`   | The unfiltered placement of this item stack in the inventory.                 |
| `public`              | `profile`             | `StatProfile`       | The stat profile of this item stack.                                          |
| `public`              | `appliedEnchanters`   | `List<ItemStack>`   | A list of enchanter item stacks used to enchant this stack. *(NonSerialized)* |
| `public` *(obsolete)* | `enchants`            | `List<Enchantment>` | A list of enchantments applied. *(Use `appliedEnchanters` instead)*           |
| `public`              | `vault`               | `Vault`             | The inventory or storage reference.                                           |

***

### 🔍 Properties

| Access   | Property            | Type       | Description                                   |
| -------- | ------------------- | ---------- | --------------------------------------------- |
| `public` | `BuyingPrice`       | `Currency` | The buying price of this item stack.          |
| `public` | `SellingPrice`      | `Currency` | The selling price of this item stack.         |
| `public` | `Weight`            | `float`    | The total weight of this item stack.          |
| `public` | `IsEmpty`           | `bool`     | If this item stack has no items.              |
| `public` | `IsFull`            | `bool`     | If this item stack has reached max capacity.  |
| `public` | `IsExceeded`        | `bool`     | If this item stack has exceeded max capacity. |
| `public` | `IsEquipped`        | `bool`     | If this item stack is currently equipped.     |
| `public` | `IsKeyItem`         | `bool`     | If this is a key item.                        |
| `public` | `IsDismantlable`    | `bool`     | If this item can be dismantled.               |
| `public` | `Stackable`         | `bool`     | If this item can be stacked.                  |
| `public` | `LevelingEnabled`   | `bool`     | If this item can level.                       |
| `public` | `DurabilityEnabled` | `bool`     | If durability is enabled for this item.       |

***

### 📦 Events

| Access          | Event                     | Type                                      | Description                             |
| --------------- | ------------------------- | ----------------------------------------- | --------------------------------------- |
| `public static` | `onDurabilityZero`        | `UnityEvent<ItemStack>`                   | Invoked when durability reaches zero.   |
| `public static` | `onLeveledUp`             | `UnityEvent<ItemStack>`                   | Invoked when an item stack levels up.   |
| `public static` | `onLeveledDown`           | `UnityEvent<ItemStack>`                   | Invoked when an item stack levels down. |
| `public static` | `actionMenuOptionsGetter` | `Func<ItemStack, List<ActionMenuOption>>` | Getter for action menu options.         |

***

### 🔧 Constructors

| Access   | Method                                                        | Returns | Description                              |
| -------- | ------------------------------------------------------------- | ------- | ---------------------------------------- |
| `public` | `ItemStack(Item item, int amount)`                            | –       | Creates a new item stack.                |
| `public` | `ItemStack(Item item, int amount, Grid.Placement? placement)` | –       | Creates a new item stack with placement. |

***

### 🧰 Methods

| Access                | Method                                             | Returns                  | Description                                                              |
| --------------------- | -------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
| `public`              | `CreateCopy()`                                     | `ItemStack`              | Creates a copy of this item stack.                                       |
| `public static`       | `GetDefaultActionMenuOptions(ItemStack itemStack)` | `List<ActionMenuOption>` | Creates default action menu options.                                     |
| `public`              | `GetOrientedSize(bool isRotated)`                  | `Vector2Int`             | Gets the oriented size depending on rotation.                            |
| `public virtual`      | `GetActionMenuOptions()`                           | `List<ActionMenuOption>` | Returns action menu options for this stack.                              |
| `public`              | `GetInterpolatedDescription()`                     | `string`                 | Gets the description with variable interpolation (localized if enabled). |
| `public` *(obsolete)* | `RecreateProfile()`                                | `void`                   | Recreates the stat profile. *(Use `UpdateProfile` instead)*              |
| `public`              | `UpdateProfile()`                                  | `void`                   | Updates the stat profile with enchantments.                              |
| `public`              | `TryEnchant(ItemStack enchanter, bool useCost)`    | `bool`                   | Attempts to enchant this item stack.                                     |
| `public`              | `EnchantWithoutNotify(Item enchanter)`             | `void`                   | Enchants without checks or cost.                                         |
| `public`              | `EnchantWithoutNotify(ItemStack enchanter)`        | `void`                   | Enchants without checks or cost.                                         |
| `public`              | `Add(int amount)`                                  | `int`                    | Adds to the stack. Returns excess amount.                                |
| `public`              | `Remove(int amount)`                               | `int`                    | Removes from the stack. Returns actual removed.                          |
| `public`              | `Split(int amount)`                                | `ItemStack`              | Splits this stack into two.                                              |
| `public`              | `Combine(ItemStack other)`                         | `bool`                   | Combines with another stack if possible.                                 |
| `public static`       | `Clamp(int value)`                                 | `int`                    | Clamps a value within stack limits.                                      |

***

### ➗ Operator Overloads

| Operator | Signature           | Returns     | Description                       |
| -------- | ------------------- | ----------- | --------------------------------- |
| `/`      | `ItemStack / int`   | `ItemStack` | Divides stack amount by int.      |
| `/`      | `ItemStack / float` | `ItemStack` | Divides stack amount by float.    |
| `*`      | `ItemStack * int`   | `ItemStack` | Multiplies stack amount by int.   |
| `*`      | `ItemStack * float` | `ItemStack` | Multiplies stack amount by float. |
| `+`      | `ItemStack + int`   | `ItemStack` | Adds to stack amount.             |
| `-`      | `ItemStack - int`   | `ItemStack` | Subtracts from stack amount.      |

## Creating Item Stacks

### Constructor

To create an `ItemStack`, you need a reference to an [item](https://stylishesper.gitbook.io/inventool/scripting/api/items/item "mention").

```csharp
// Create an item stack with a stack of 10
ItemStack myItemStack = new ItemStack(myItem, 10);
```

### Copy

You can create a copy of an `ItemStack` with the `CreateCopy` method.

```csharp
ItemStack myItemStackCopy = myItemStack.CreateCopy();
```

## Managing Amounts

When managing item amounts, it's recommended to use the methods below instead of just editing the `amount` field.

### Add

The `Add` method increases the item stack's amount. It returns an int that represents the excess amount (the amount not added due to the item stack becoming full).

```csharp
// Add 10 to the stack
int excess = myItemStack.Add(10);
```

### Remove

The `Remove` method decreases the item stack's amount. It returns an int that represents the excess amount (the amount not removed due to the item stack becoming empty).

```csharp
// Remove 10 to the stack
int excess = myItemStack.Remove(10);
```

### Split

The `Split` method does 3 things: creates a copy of an `ItemStack`, gives half of the item to the copy, and returns the copy. So, if you have an ItemStack with it's amount equally to 20, using `Split` on it will cut the amount down to 10.

```csharp
ItemStack mySplitStack = myItemStack.Split();
```

### Combine

The `Combine` method takes the amount from another `ItemStack` as much as possible. This may result in the other item stack becoming empty. The method returns true if any amount of taken from the other item stack, otherwise, false will be returned.

```csharp
bool result = myItemStack.Combine(myOtherItemStack);
```

### Operators

`ItemStack`'s support some operators that you can use to change the amount field. The operators will clamp the amount within 0 and the max item stack amount.

```csharp
// Add 1 to the stack
myItemStack += 1;

// Remove 1 from the stack
myItemStack -= 1;

// Double the stack
myItemStack *= 2;

// Halve the stack
myItemStack /= 2;
```

## Enchanting

Enchanting item stacks can be handled with the `ItemStack` class itself, as long as you have a reference to an enchanter `ItemStack`. Use the `TryEnchant` method for this purpose.&#x20;

`TryEnchant` returns true if the enchant was successful. The enchant may fail if the item types were incorrect. Only enchanter items can enchant enchantable items. Learn more about enchanting [here](https://stylishesper.gitbook.io/inventool/scripting/api/enchanting).

You can choose to apply the enchanting (currency) cost by passing `true` as the second parameter.

```csharp
myEnchantableItemStack.TryEnchant(myEnchanterItemStack, true);
```

## Action Menu Options

By default, item stacks' UI counterpart logically display item options for the [action-menu](https://stylishesper.gitbook.io/inventool/editors/components/ui/ui-toolkit/action-menu "mention"). You can override these options by editing the `ItemStack.actionMenuOptionsGetter` field.

Here's an example of how you can override these options:

```csharp
ItemStack.actionMenuOptionsGetter = new(x =>
{
    List<ActionMenuOption> options = new();

    options.Add(new ActionMenuOption()
    {
        // Smallcaps is generally used by Inventool for styling purposes but it is not required
        text = $"<smallcaps>Some Action</smallcaps>",
        backgroundColor = new Color(0.3f, 0.3f, 0.3f),
        sortingOrder = 0,
        action = () => { Debug.Log("Do something"); }
    });

    return options;
});
```

You can call the `GetActionMenuOptions` method to get the options.

```csharp
var options = myItemStack.GetActionMenuOptions();
```

## Interpolated Description

You can get the item description with text interpolation with the `GetInterplatedDescription` method. This essentially helps display stats in item descriptions. Read more about this [here](https://stylishesper.gitbook.io/inventool/editors/inventool/items#stat-text-tags).

```csharp
string description = myItem.GetInterpolatedDescription();
```
