# Lootbox Creation Guide

Currently, the Item Wizard does not support creating **Lootbox** items directly. Instead, they must be inserted manually into the database. This guide details the required JSON structure for the `LOOTBOX` effect.

## Item Structure

To create a lootbox, you need to insert a row into the `items` table. The critical part is the `usageData` JSON column.

```json
{
  "consume": true,
  "effects": [
    {
      "type": "LOOTBOX",
      "pool": [ ... ]
    }
  ]
}
```

## Loot Table Structure

The `pool` property is an array of `LootTableItem` objects. A random item is selected based on the total `weight` of all items in the pool.

| Field | Type | Description |
|-------|------|-------------|
| `type` | `string` | One of: `CURRENCY`, `ITEM`, `XP`, `NOTHING`. |
| `weight` | `number` | The relative probability weight of this outcome. |
| `message` | `string` | (Optional) Custom message to display when this outcome is selected. |

### Outcome Types

#### 1. Currency
Gives the user coins.

```json
{
  "type": "CURRENCY",
  "weight": 50,
  "amount": 100,          // Fixed amount OR
  "minAmount": 50,        // Minimum random amount
  "maxAmount": 150        // Maximum random amount
}
```

#### 2. XP
Gives the user Experience Points.

```json
{
  "type": "XP",
  "weight": 30,
  "amount": 500           // Fixed amount OR range (minAmount/maxAmount)
}
```

#### 3. Item
Gives the user another item (by ID).

```json
{
  "type": "ITEM",
  "weight": 10,
  "itemId": 42,           // The ID of the item to give
  "amount": 1             // (Optional) Quantity to give, default 1
}
```

#### 4. Nothing
An empty roll.

```json
{
  "type": "NOTHING",
  "weight": 10,
  "message": "The box was empty! Better luck next time."
}
```

## Complete Example

Here is a full SQL insert example (using a hypothetical SQL client or Drizzle studio) for a "Basic Lootbox":

**Name**: Basic Lootbox
**Type**: CONSUMABLE
**Effect**:
- 50% chance for 100-200 Coins
- 30% chance for 500 XP
- 10% chance for Item ID 5 (e.g. Rare Gem)
- 10% chance for Nothing

**JSON for `usageData`**:
```json
{
  "consume": true,
  "effects": [
    {
      "type": "LOOTBOX",
      "pool": [
        {
          "type": "CURRENCY",
          "weight": 50,
          "minAmount": 100,
          "maxAmount": 200
        },
        {
          "type": "XP",
          "weight": 30,
          "amount": 500
        },
        {
          "type": "ITEM",
          "weight": 10,
          "itemId": 5,
          "amount": 1,
          "message": "Startstruck! You found a Rare Gem!"
        },
        {
          "type": "NOTHING",
          "weight": 10,
          "message": "It's empty..."
        }
      ]
    }
  ]
}
```