# Loot Box

## 🎁 LootBox Class

An object that can be opened to receive a randomized selection of items.

> **Namespace:** `Esper.Inventool.Items`\
> **Access:** `public`\
> **Type:** `class`\
> **Inherits:** `ScriptableObject`

***

### 📦 Fields

| Access   | Field           | Type                | Description                                                                  |
| -------- | --------------- | ------------------- | ---------------------------------------------------------------------------- |
| `public` | `id`            | `string`            | An ID that can be used to determine if a loot box has already been obtained. |
| `public` | `possibleDrops` | `List<LootBoxDrop>` | A list of all possible item drops.                                           |
| `public` | `minItemDrop`   | `int`               | The minimum number of items that can be dropped.                             |
| `public` | `maxItemDrop`   | `int`               | The maximum number of items that can be dropped.                             |

***

### 🧰 Methods

| Access      | Method                           | Returns           | Description                                                                                |
| ----------- | -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `public`    | `CalculateDropChance(int index)` | `float`           | Calculates the drop chance of a possible drop at a given index (percentage out of 100).    |
| `protected` | `GetTotalDropRate()`             | `float`           | Gets the total drop rate value across all possible drops. Cleans invalid entries if found. |
| `protected` | `UpdateDropRanges()`             | `void`            | Updates all drop ranges for each possible drop.                                            |
| `public`    | `GetLoot()`                      | `List<ItemStack>` | Gets random items based on the possible drops and their rates.                             |
| `public`    | `Clean()`                        | `void`            | Cleans the possible drops list by removing deleted or invalid items.                       |
| `public`    | `Save()` *(Editor only)*         | `void`            | Saves the object.                                                                          |

## Creating a Loot Box

Since loot boxes are scriptable objects, you can create them with `ScriptableObject.CreateInstance`.

```csharp
LootBox lootBox = ScriptableObject.CreateInstance<LootBox>();
```

## Working with a Loot Box

### Setting Possible Drops

#### Creating a Drop List

The code below is an example of how you can create a drop list. In the example, 2 possible drops are added to a loot box, each with a 50% probability of dropping. The `myItem` and `myOtherItem` fields are instances of an [item](https://stylishesper.gitbook.io/inventool/inventool-v1/scripting/api/items/item "mention").

```csharp
lootBox.possibleDrops = new List<LootBoxDrop>()
{
    new LootBoxDrop()
    {
        item = myItem,
        amountRange = new Vector2(0, 64),
        dropRate = 1
    },

    new LootBoxDrop()
    {
        item = myOtherItem,
        amountRange = new Vector2(0, 64),
        dropRate = 1
    },
};
```

#### Randomized Drop Amount

A random number of items are dropped based on the `minItemDrop` and `maxItemDrop` fields.

```csharp
// Random range between 1 - 5 items
lootBox.minItemDrop = 1;
lootBox.maxItemDrop = 5;
```

### Getting Drop Chances

You can get the drop chance of each possible drop as a percentage out of 100 by it's index with the `CalculateDropChance` method.

```csharp
// Get drop chance of an item drop at index 0
float dropChance = lootBox.CalculateDropChance(0);
```

### Getting Loot

The `GetLoot` method can be used to get random loot. This can be considered as opening the loot box. This returns an `ItemStack` list.

```csharp
var itemStacks = lootBox.GetLoot();
```
