forked from syntaxbullet/AuroraBot-discord
128 lines
2.7 KiB
Markdown
128 lines
2.7 KiB
Markdown
# 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..."
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|