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.

{
  "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.

{
  "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.

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

3. Item

Gives the user another item (by ID).

{
  "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.

{
  "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:

{
  "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..."
        }
      ]
    }
  ]
}

2.7 KiB Raw Blame History