Adding Drop Tables

Defining a Drop Table

Drop tables are JSON assets in Server/Drops/. Here’s a drop table that always gives meat and has a 30% chance to give leather:

{
  "Container": {
    "Type": "Multiple",
    "Containers": [
      {
        "Type": "Single",
        "Item": { "ItemId": "Raw_Meat", "QuantityMin": 1, "QuantityMax": 3 }
      },
      {
        "Type": "Single",
        "Weight": 30,
        "Item": { "ItemId": "Leather" }
      }
    ]
  }
}

Every drop table has a single root Container that defines what drops. Containers can nest to create complex loot logic.

Pack location: Server/Drops/
Base game reference: Assets.zip/Server/Drops/

Container Types

Each container has a Type field and an optional Weight (default: 100). Five types are available:

Single

Always drops one item. The simplest container.

{
  "Type": "Single",
  "Item": { "ItemId": "Iron_Ingot", "QuantityMin": 1, "QuantityMax": 3 }
}

Choice

Picks one container from a weighted list. Use this for “drop one of these” loot — common/uncommon/rare tiers.

{
  "Type": "Choice",
  "RollsMin": 1,
  "RollsMax": 1,
  "Containers": [
    { "Type": "Single", "Weight": 70, "Item": { "ItemId": "Common_Gem" } },
    { "Type": "Single", "Weight": 25, "Item": { "ItemId": "Uncommon_Gem" } },
    { "Type": "Single", "Weight": 5, "Item": { "ItemId": "Rare_Gem" } }
  ]
}

Weight values are relative — 70/25/5 means 70% chance, 25% chance, 5% chance. Set RollsMin/RollsMax to roll multiple times (each roll picks independently).

Multiple

Evaluates every sub-container independently. Each sub-container’s Weight is a percentage chance (0-100) to drop.

{
  "Type": "Multiple",
  "Containers": [
    { "Type": "Single", "Weight": 100, "Item": { "ItemId": "Bone" } },
    { "Type": "Single", "Weight": 50, "Item": { "ItemId": "Leather" } },
    { "Type": "Single", "Weight": 5, "Item": { "ItemId": "Rare_Fang" } }
  ]
}

This drops Bone (guaranteed), Leather (50% chance), and Rare_Fang (5% chance) — all rolled independently. Use MinCount/MaxCount to repeat the entire evaluation multiple times.

Droplist

References another drop table by ID. Use this to compose and reuse drop tables across NPCs or blocks.

{
  "Type": "Droplist",
  "DroplistId": "Drop_Common_Materials"
}

Circular references are detected at runtime — if a droplist references itself (directly or indirectly), the circular entry is silently skipped and produces no drops.

Empty

Drops nothing. Useful as an entry in a Choice container to create a chance of getting no drop at all.

{
  "Type": "Choice",
  "Containers": [
    { "Type": "Single", "Weight": 30, "Item": { "ItemId": "Rare_Item" } },
    { "Type": "Empty", "Weight": 70 }
  ]
}

This gives a 30% chance to drop an item and 70% chance to drop nothing.

Item Fields

Each Item in a Single container is an ItemDrop:

Field	Default	Description
`ItemId`	(required)	The item asset ID
`QuantityMin`	`1`	Minimum quantity
`QuantityMax`	`1`	Maximum quantity (random between min and max)
`Metadata`	`null`	BsonDocument for item variant metadata

Where Drop Tables Are Used

NPC Death

Set DropList on an NPC role to drop items when the NPC dies:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "DropList": "Drop_My_Creature",
    "Appearance": "Wolf",
    "MaxHealth": 60
  }
}

See Adding NPCs for the full NPC role format.

Block Breaking

Blocks define drops through BlockGathering on the block type config. Each gathering method can reference a drop table:

Gathering Type	When it applies
`Breaking`	Standard tool-based block breaking
`Harvest`	Harvesting (crops, plants)
`Soft`	Soft blocks (sand, snow)
`Physics`	Physics-affected blocks

Each type can specify a direct ItemId, a DropList reference, or both. Tool-specific overrides can change what drops when using particular tools.

When no drop is configured, blocks fall back to dropping their own item (the block itself).

Chest and Stash Loot

Container blocks (ItemContainerState) can reference a drop table via the Droplist field. When the chunk loads, the stash system rolls the drop table to populate the container with random loot. By default, the drop list is cleared after first population so loot only generates once.

NPC Inventory

NPCs can use PossibleInventoryItems (a drop list reference) to randomly populate their inventory at spawn time.

Farming

Animal coops use ProduceDrops to map NPC types to drop lists, generating produce items over time.

Testing with /droplist

The /droplist command simulates drop table rolls without spawning items:

/droplist <droplist> [count]

droplist — the drop table asset ID
count — number of times to roll (default: 1)

Reports what items would drop and in what quantities. Useful for verifying drop rates during development.

See /droplist command reference.

Spawning Drops from Code

To programmatically roll a drop table and spawn the results:

// roll a drop table
List<ItemStack> items = ItemModule.get().getRandomItemDrops("Drop_My_Creature");

// spawn each item as an entity
for (ItemStack item : items) {
    ItemUtils.dropItem(ref, item, store);
}

See Spawning Items for more drop spawning methods including ItemComponent.generateItemDrop() for full control over position and velocity.

Drop events are documented on the ECS Events page — use DropItemEvent.Drop to intercept or modify items being dropped into the world.