# Item Drop

## 🎁 ItemDrop Class

A dropped item represents an [item-stack](https://stylishesper.gitbook.io/inventool/scripting/api/items/item-stack "mention") visible in the game world.

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

***

### 📦 Fields

| Access          | Field                  | Type                   | Description                                                                                                                           |
| --------------- | ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `public`        | `id`                   | `string`               | The item drop ID. Used to determine if the item drop has already been obtained.                                                       |
| `public`        | `itemStack`            | `ItemStack`            | The item stack that this object represents.                                                                                           |
| `public`        | `useTimeout`           | `bool`                 | If the item drop should be despawned after some time. Despawn is scheduled on start.                                                  |
| `private`       | `spriteRenderer`       | `SpriteRenderer`       | The sprite renderer component that displays the item sprite.                                                                          |
| `public static` | `shouldDisable`        | `Func<string, bool>`   | A function that determines if this item drop should be disabled. Runs on start.                                                       |
| `public static` | `dropsInPickupRange`   | `List<ItemDrop>`       | A list of item drops currently in the pickup range.                                                                                   |
| `public static` | `onEnteredPickUpRange` | `UnityEvent`           | Callback for when the player enters the pickup range of any item drop.                                                                |
| `public static` | `onExitedPickUpRange`  | `UnityEvent`           | Callback for when the player exits the pickup range for all item drops.                                                               |
| `public static` | `onDropSpawned`        | `UnityEvent<ItemDrop>` | Callback for when an ItemDrop is spawned through the SpawnInstance method. This accepts 1 argument: the item drop spawned (ItemDrop). |

***

### 🧰 Methods

| Access              | Method                                                                  | Returns    | Description                                                                                                |
| ------------------- | ----------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `protected virtual` | `Awake()`                                                               | `void`     | Initializes the sprite renderer and sets the sprite if an item stack exists.                               |
| `protected virtual` | `Start()`                                                               | `void`     | Disables the drop if `shouldDisable` returns true, otherwise schedules despawn if `useTimeout` is enabled. |
| `protected virtual` | `Update()`                                                              | `void`     | Rotates the drop to face the camera if billboard mode is enabled.                                          |
| `protected virtual` | `OnBecameInvisible()`                                                   | `void`     | Clears the sprite when the object is no longer visible.                                                    |
| `protected virtual` | `OnBecameVisible()`                                                     | `void`     | Restores the sprite when the object becomes visible again.                                                 |
| `protected virtual` | `OnTriggerEnter(Collider other)`                                        | `void`     | Adds this drop to pickup range when the player enters.                                                     |
| `protected virtual` | `OnTriggerEnter2D(Collider2D collision)`                                | `void`     | Adds this drop to pickup range when the player enters (2D).                                                |
| `protected virtual` | `OnTriggerExit(Collider other)`                                         | `void`     | Removes this drop from pickup range when the player exits.                                                 |
| `protected virtual` | `OnTriggerExit2D(Collider2D collision)`                                 | `void`     | Removes this drop from pickup range when the player exits (2D).                                            |
| `protected virtual` | `OnDestroy()`                                                           | `void`     | Ensures this drop is removed from pickup range on destruction.                                             |
| `public`            | `SetItem(ItemStack itemStack)`                                          | `void`     | Sets this item drop’s stack and updates its sprite.                                                        |
| `public`            | `SetSprite(Sprite sprite)`                                              | `void`     | Sets the item sprite if a `SpriteRenderer` is attached.                                                    |
| `public static`     | `GetRandomDropPositionInRange(Vector3 target, float range)`             | `Vector3`  | Gets a random position around a target for item drop placement.                                            |
| `public static`     | `SpawnInstance(ItemStack itemStack, Vector3 position, bool useTimeout)` | `ItemDrop` | Spawns a new item drop instance at the given position.                                                     |

***

### 🧩 Nested Types

#### `public enum CollisionMode`

Defines the collision mode for item drops.

| Name               | Description   |
| ------------------ | ------------- |
| `ThreeDimensional` | For 3D games. |
| `TwoDimensional`   | For 2D games. |

***

## Creating an Item Drop

To create an `ItemDrop`, use the `SpawnInstance` method. You will need a reference to an `ItemStack`. This method spawns an instance of an `ItemDrop` in the game world. You can set the position and whether timeout should be enabled.

```csharp
ItemDrop myItemDrop = ItemDrop.SpawnInstance(myItemStack, position, useTimeout);
```

## Handling Auto Disable

Item drops can auto-disable themselves on start with the logic of your choice by setting the `ItemDrop.shouldEnable` field.

```csharp
ItemDrop.shouldDisable = new(itemDropID =>
{
    if (itemDropID == "MyItemDropID")
    {
        // Item drop should be disabled
        return true;
    }

    // Item drop should be enabled
    return false;
});
```

## Timeout

If timeout was enabled when spawning an item drop instance, the item drop will be automatically destroyed based on the `itemDropTimeout` field in [inventool-settings](https://stylishesper.gitbook.io/inventool/scripting/api/inventool-settings "mention").

## Pick Up

Picking up item drops is handled by the [inventory](https://stylishesper.gitbook.io/inventool/scripting/api/inventory "mention"). Once an item drop is picked up, the `ItemStack` it represents is added to the inventory and the `ItemDrop` instance is destroyed.

### Checking All Drops In Range

You can get the full list of items that the player is in range of with the `ItemDrop.dropsInPickupRange` field.
