Loot Tables, Open Actions, and Container Delivery

This is the page to keep open while you are editing actual rewards.

Where loot really lives

For Airdrops, the real loot table is usually the open.commands.roll_each list inside each crate entry.

That list can mix several action types in one crate:

• message
• command
• item
• itemspray

This is more flexible than a simple chest table because one crate open can both reward items and trigger server-side commands or announcements.

The basic open flow

A typical crate open block looks like this:

open:
  deliveryMode: container
  commands:
    roll_each:
    - chance: 100
      type: message
      scope: '@a'
      amp: '&f%player_name% opened an &cExample Crate&f!'
    - chance: 35
      type: item
      item:
        ==: org.bukkit.inventory.ItemStack
        type: SHEARS
    - chance: 60
      type: itemspray
      items: [item]
      item_weights: [item]
      min_count: 1
      max_count: 3
      allow_duplicates: false

deliveryMode

The current code supports:

• WORLD_DROP
• CONTAINER

WORLD_DROP is the older drop-it-into-the-world feel.
CONTAINER opens a virtual inventory and can drop leftovers on close depending on effects.crate.container.*.

If you want reward review, player pacing, and less item explosion on the ground, container mode is usually the cleaner choice.

message actions

These are broadcast or scoped chat lines triggered on open.

Common fields:

• chance
• type: message
• scope
• amp

Use them for open announcements, not for critical game logic.

command actions

These let the crate execute server commands when it opens.

Common fields:

• chance
• type: command
• as
• run

This is the right place for things like:

• vehicle keys
• economy payouts
• unlock tokens
• integration bridges into other plugins

item actions

type: item is the clean single-stack reward lane.

Use it when a reward is one exact serialized item with one roll chance. That is much easier to read than wrapping every single item in a one-entry itemspray.

itemspray actions

This is the broader multi-entry reward pool system.

The current source supports both:

• legacy ids
• exact items

It also supports the newer tuning controls:

• id_weights
• item_weights
• total_count
• min_count
• max_count
• allow_duplicates

That means you can keep older logical pool workflows while also moving toward real serialized item pools where needed.

items at the crate root

Outside the open section, each crate can also define:

items:
  some_logical_id: <ItemStack>

That gives the crate a local named-item library. It is useful when staff want stable logical references without duplicating the same serialized stack everywhere.

The most important migration rule

If you are carrying forward rewards from an older 1.15.2 server, migrate the reward logic, not the whole runtime expectation.

That means:

• keep the reward tables players already know
• keep the crate IDs if they already anchor your server
• retune delivery, visuals, and interaction behavior for the current Paper build

Live editing

The current plugin gives you several safer ways to edit loot without hand-authoring every serialized block:

• /airdrop loot <crateType>
• /airdrop addhand <crateType> <chance>
• SHIFT-click inventory items into the loot editor for quick single-item entries
• SHIFT-click inventory items into the itemspray editor for quick pool entries
• use the simulate button before you trust a live crate

A good reward-maintenance order

Use this order when you update loot:

1. preserve crate IDs
2. preserve crate family intent
3. update reward entries
4. simulate the roll
5. spawn the crate in-game
6. only then rebalance chance numbers

That approach avoids regressions where the file is technically valid but the live player result no longer matches the crate family.

Next pages

• admin GUI, Migration, and Live Editing
• commands, Permissions, and Admin Workflows