Introduction

DonaDrops is a Minecraft plugin (Paper 1.20 to 26.3) created by zDonatier and Santiago Rivers that turns any chest into a "drop chest": a chest with its own name and color, a star rarity, a category, a floating hologram, a list of rewards that gets rolled when it's opened, and non-removable decorative panels around the loot.

Requirements

• Minecraft 1.20 to 26.3, on Paper or a Paper fork.
• PlaceholderAPI is required. DonaDrops declares it as a dependency and the server won't start the plugin if it isn't installed.
• WorldGuard is optional (soft-dependency), only used if you enable worldguard-compatibility in config.yml.

The plugin is compiled against the Paper 1.20.4 API. So it also works on newer versions, everything Minecraft has renamed or changed over time (particle names, sounds, the enchantment glow, inventories) is resolved at runtime on your server, not at compile time. If a name doesn't exist on your version, a safe fallback is used instead of throwing an error.

Commands

Alias: /donadrops. Every argument has tab-completion (chest names, categories, 1-5, online players).

Permissions

Creating a chest step by step

1. Place any container block (chest, trapped chest, barrel, shulker box...).
2. Fill it with the items you want that chest to be able to give.
3. Look directly at the chest.
4. Run /dd create &6Legendary Chest 5 legendary

If you skip the rarity, 1 star is used by default. If you skip the category, common is used.

Editor GUI

Creating a chest (or running /dd editor <name>) opens a menu to edit its properties. Changes made from the GUI are saved to that drop's file. The whole editor (buttons, submenus and the messages it asks for in chat) shows up in the language set in config.yml → language.

Effect selectors

The three effect buttons open a menu with the same layout as Chest Flags:

• Each entry is a possible value. The one in use is marked Selected.
• Use config.yml (paper): the drop takes the value from config.yml (equal to -1 in the file). It doesn't exist for the animation, which is only ever set on the drop.
• None (barrier): disables that effect for this drop (equal to none).
• The rest are the available particles or animations. A click saves the choice immediately and refreshes the menu. Hovering over each one shows in its Lore what visual effect it produces, in the language set in config.yml (English shows in English, Spanish shows in Spanish, and so on for every supported language).
• If the list has more than one page, the arrows in the bottom corners flip pages and the center arrow returns to the editor.

The particle lists only show the ones your Minecraft version recognizes, and leave out the ones that need extra data (like BLOCK, ITEM or DUST). Values that can only be typed by hand, like the amount or the seconds, are edited in the drop's file.

The GUI's buttons can be customized through the files in /gui: material, name, lore, slot, head/texture, sounds, actions and decorations, depending on the menu.

Block and inventory type

The editor includes a separate inventory to change each chest's block type and InventoryType. The selection is saved as an individual type-override once enabled.

The selector can offer chests, trapped chests, barrels, ender chests, colored shulker boxes, dispensers, droppers and hoppers, plus their compatible inventory types.

type-override:
  enabled: true
  block-type: CHEST
  inventory-type: CHEST

Custom inventory size

Independent of the inventory type, each drop can define inventory-size (in slots) to use a size different from the global chest.rows:

inventory-size: 54   # -1 = use the global chest.rows value

This only applies when the resolved inventory type is CHEST (other types like BARREL, SHULKER_BOX or ENDER_CHEST have a fixed size set by Minecraft). Any value is automatically rounded up to the nearest valid multiple of 9 between 9 and 54 — for example, 32 becomes 36, and 52 becomes 54. Also editable from the editor's Inventory Size button.

Chest Flags

DonaDrops has two independent flag levels, always using the same identifiers (lowercase, kebab-case):

• Global flags — the global-flags list in config.yml. Automatically applied to every chest the plugin spawns, no matter which drop file it comes from.
• Per-chest flags — the chest-flags list inside each drop's .yml file, in /drops. Only applied to that particular chest.

A flag is active for a chest if it's in global-flags, or if it's in that drop's own chest-flags (or both). You don't need to repeat a flag on every drop if it's already active globally.

Global flags (config.yml)

By default, config.yml ships with only these two enabled, since they're meant to be necessary on practically any server:

global-flags:
  - "explosion-protect"
  - "solid-ground-only"

It's a free-form list: you can add any other flag from the table below so it applies to every chest, or remove the ones already there (even leave it empty). The tolerance for solid-ground-only is still set in spawn-restrictions.solid-ground-tolerance, whether the flag comes from here or from an individual chest-flags list.

Per-chest flags (chest-flags)

Every new drop is created with this flag enabled by default, so a freshly-created chest stays permission-protected until an admin deliberately turns it off:

chest-flags:
  - "permission-required"

It can be freely edited from the editor's Chest Flags button (which now also warns when a flag is already forced globally), or directly in the drop's file.

Currently implemented flags

These 8 flags already work in the plugin and can be used today, in both global-flags and chest-flags:

Other flags that could be added

Besides the 8 that already ship, here's a list of ideas for a reward-chest plugin — things that sound good for later on. None of the ones marked "Suggested" do anything yet; they're here so you can pick which ones you'd like to request in a future update.

Per-chest flags are toggled from the editor's Chest Flags button, which shows each flag's status, whether it's already forced globally, and a short description. Global ones are edited directly in config.yml.

Spawn zones

DonaDrops lets you define regions where chests are allowed to spawn. Zones are automatically saved in the /zones folder, one .yml file per zone.

Selecting Pos1 and Pos2

1. Run /dd zonewand to get the DonaDrops iron axe.
2. Left-click a block: Pos1.
3. Right-click a block: Pos2.

You can also use /dd pos1 <x> <y> <z> [world] and /dd pos2 <x> <y> <z> [world].

Creating and confirming

With both positions selected, run /dd createzone <name>. DonaDrops will show Click to confirm; clicking it creates the zone. Enabled zones can't overlap with another enabled zone.

Zone file

enabled: true
world: "world"
pos1:
  world: "world"
  x: 100
  y: 60
  z: 100
pos2:
  world: "world"
  x: 200
  y: 100
  z: 200
max-chests: 5
allow-manual-spawn: true

• enabled — turns that zone's restriction on or off.
• world — the world the zone belongs to.
• pos1/pos2 — the persisted coordinates of the region's corners.
• max-chests — maximum number of active chests inside that zone at once; 0 means no limit.
• allow-manual-spawn — allows or blocks /dd spawn inside the zone.

If a world has at least one enabled zone, DonaDrops's spawns in that world must land inside an enabled zone. If no zones are enabled in that world, the world keeps its normal behavior.

/dd deletezone <name> deletes the zone's file and removes any active chests that were inside it; afterwards, that world is free of that restriction again.

Automatic spawning

Controlled in config.yml → spawn-system: global cooldown, per-drop cooldown, maximum active chests, search attempts and height (Y) range.

spawn-system:
  enabled: true
  global-cooldown-seconds: 60
  max-active-chests: 10
  search-attempts: 40
  min-y: -64
  max-y: 320
  near-players: true
  near-players-radius: 60

min-y and max-y never exceed the world's real height: on 1.20 and newer the overworld goes from -64 to 320, but the Nether and the End go from 0 to 256, so there the default -64 simply gets clamped to 0.

If the world has an enabled zone, DonaDrops always tries to spawn chests inside that zone. If there's no enabled zone, near-players is used: a connected player is picked at random and the chest appears within near-players-radius blocks of them.

Min/max amount per item

Each reward stores min-amount and max-amount in its .yml file inside /drops. When the chest is opened, that item's final amount is rolled at random between those two numbers. If you don't edit them, both stay equal to the amount of the item you added (no variation). Edit them directly in the drop's file:

rewards:
  0:
    item: ...
    chance: 100.0
    min-amount: 1
    max-amount: 4

Reward lore

The additional description (lore) for the reward is automatically displayed on the items while they are in the chest's loot inventory; once the reward is retrieved, the item retains the lore.

reward-lore:
  enabled: true
  lines:
    - "&7Rarity: &f{rarity-name}"
    - "&7Probability: &f{rarity-probability}%"

• enabled: fully turns this lore on or off.
• lines: an editable list of lines; you can freely add, remove or change lines.
• {rarity}: the item's rarity key.
• {rarity-name}: the rarity's display name defined in categories.yml.
• {rarity-probability}: the rarity's probability defined in categories.yml.
• {chance}: the reward's own chance.

Lines respect the colors exactly as you write them: & codes, exact hex (&#FFD700) and MiniMessage tags, gradients included.

The lore is stored internally along with a marker so that items sharing the same lore configuration stay compatible with each other. As soon as the item actually leaves the chest, DonaDrops removes the marker and the lines it added: this is checked on every click and drag while the loot GUI is open, again the moment it's closed, and once more on whatever gets dropped to the ground - including pressing the drop key (Q) directly on a slot inside the chest, which sends the item straight to the ground without ever passing through the player's own inventory. That last case used to be missed, leaving the lore stuck on a dropped item; it's covered now too.

config.yml

Controls global behavior: baseline spawn probability, seconds to wait before it can be opened, star symbol, default title (automatically centered), global block/inventory type, global flags (see Chest Flags), spawning outside the world border, per-action sounds, messages/titles with %x% %y% %z% %world% %name%, reward lore, visibility distance, each GUI's decorative panels and reusable textured heads.

categories.yml

By default: common, rare, epic, elite, legendary, each with its own weight. You can add, remove or rename categories freely; the plugin reads them dynamically. The weight is available for any category-based rolling system you want to build on top of this data.

The same file also has a separate section, drop-items:, for the rarity of individual items inside a chest. See Item rarity.

/drops/<name>.yml files

Each chest has an editable file with its name, rarity, category, language, timings, commands on open, rewards, amounts, spawn effects and block/inventory type settings.

open-delay-seconds: 3
appear-seconds: 300

commands:
  - "give %player% diamond 1"

type-override:
  enabled: true
  block-type: CHEST
  inventory-type: CHEST

inventory-size: 54

# Spawn effects (see "Chest spawn effects").
# -1 = use config.yml, none = no effect.
pre-spawn-particles:
  type: -1
  seconds: -1
  count: -1

spawn-animation:
  type: none
  duration-ticks: 30

spawn-particles:
  type: -1
  count: -1
  interval-ticks: -1

# TIP: false (default) = this chest can spawn wherever the automatic
# spawner picks. true = it ONLY spawns at the fixed points created with
# /dd createspawn <spawnName> this_chest (see "Fixed spawn points").
spawn: false

chest-flags:
  - permission-required
  # No need to repeat solid-ground-only or explosion-protect here: they're
  # already active for every chest via config.yml -> global-flags. You can
  # add any other flag from the full list in the "Chest Flags" section.

rewards:
  0:
    item: DIAMOND
    chance: 100.0
    min-amount: 1
    max-amount: 4
    # rarity: a key from categories.yml -> drop-items: (see "Item rarity").
    # That rarity's probability gets multiplied with "chance" above.
    rarity: common

Commands can be added from the GUI or edited directly in the YAML.

The chest stays in the world until ALL the items in its loot inventory are taken out, or until appear-seconds elapses (whichever comes first). While it still has unclaimed loot, anyone can right-click it again to see what's left — it isn't re-rolled, it's the same loot generated the first time.

Item rarity

Besides the chest's own star rarity (1-5) and its category (common, rare...), each individual item among the rewards can have its own rarity. It's defined in categories.yml, under drop-items::

drop-items:
  common:
    display-name: "&7Common"
    probability: 100.0
  rare:
    display-name: "&9Rare"
    probability: 50.0
  epic:
    display-name: "&5Epic"
    probability: 25.0
  elite:
    display-name: "&6Elite"
    probability: 10.0
  legendary:
    display-name: "&e&lLegendary"
    probability: 3.0

You can create, delete or rename these categories freely. By default every new item is set to common with 100% probability (i.e., no extra penalty at all). The lower the assigned rarity's probability, the less likely that item is to appear: its own chance (set in the chest's file) gets multiplied by probability / 100.

It's edited in two ways:

• Directly in the chest's file, with the rarity: field on each reward (see /drops files).
• From /dd editor <chest> → Edit Rewards: shift-right-click an item to raise its rarity a step (category and probability), shift-left-click to lower it. Hovering over any reward shows its current rarity and probability along with these two instructions in its Lore, in the language set in config.yml. Both the rarity and the probability are always a single line each: shift-clicking updates that same line in place rather than adding new ones, no matter how many times you click.

Drop Events

A Drop Event is a temporary wave of chests that appear much faster than normal. Each event is a separate file inside the /events folder (it's created on its own the first time, with an example called drop-event.yml). You can have as many events as you want: copy the file under another name and that name becomes the key used in /dd event start <name>.

# events/drop-event.yml
enable: false

auto-start: true
auto-interval-minutes: 60

spawn-interval-seconds: 5
total-chests: 20

groups:
  main:
    weight: 100
    drops:
      - "donadrops"

messages:
  start-chat: "&6&lDrops Event &fhas started! Keep an eye out for chests."
  start-title: "&6&lDrops Event"
  start-subtitle: "&7Special chests are spawning across the map!"
  finish-chat: "&6&lDrops Event &ffinished."
  finish-title: "&6&lDrops Event"
  finish-subtitle: "&7The event has ended. See you next time!"
  next-event-title: "&eNext Drops Event"
  next-event-subtitle: "&7Starts in &f%time%"

Managed with /dd event start <name>, /dd event stop [name] and /dd event list. Only one event can be active at a time. While the event is running, every connected player sees a boss bar showing how many chests have spawned out of the total (it updates itself and disappears when the event ends).

To see how long until the next event (or the next random automatic chest), use the placeholders %donadrops_next_event_time% and %donadrops_next_chest_time% — see Placeholders.

Fixed spawn points

With /dd createspawn <spawnName> <chestName> you create a fixed spawn point, at your current location, tied to a specific chest. It's saved as a file inside the /Spawners folder, named <chest>_<spawnName>.yml:

# Spawners/donadrops_spawnroom.yml
spawn-name: "spawnroom"
chest: "donadrops"
world: "world"
x: 120
y: 68
z: -34

You can create as many points as you want for the same chest: you just need each one to have a different spawnName (that's why the file name combines chest + point name, so they never overwrite each other).

These points alone don't change anything yet: a chest still uses the normal random spawner until you set spawn: true in its own file inside /drops (see /drops files). Once set to true, that chest stops appearing anywhere random and only appears — automatically or manually — at one of its free fixed points.

Management: /dd listspawns [chestName] to see saved points, /dd deletespawn <file> to delete one.

Chest decoration

Each chest can show decorative panels around its rewards when a player opens it. These panels are purely visual: they can't be taken out, moved, or collected in any way (click, shift-click, drag or double-click to collect), no matter what material is used.

Configured per chest, inside its file in /drops, under the decoration section:

decoration:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: " "
  lore: []
  slots: "border"
  glow: false

Languages

The /lang folder contains the available languages. Currently supported: en, es, pt, fr, de, it, ru, zh, ja and ko.

The language is global for the whole plugin. The editor's language selector shows every language row by row and clearly marks the one selected. Picking one, DonaDrops immediately changes config.yml → language (e.g., en becomes es) and saves the file. There's no separate language saved per drop/chest.

Translations cover chat messages, titles and notices, and every menu the plugin builds itself: the editor, Chest Flags (including each flag's description), chest type, inventory type, language selector, reward editor, the three effect selectors and the messages the editor asks for in chat. When the language changes, menus show in the new language as soon as they're reopened. Text you customize directly in the /gui files stays exactly as you wrote it.

Each file in /lang has these main sections:

If a text is missing in a language, the English one is used instead. To fix or add a translation, edit that language's file in /lang and run /dd reload. Text accepts &, hex and MiniMessage, and \n separates lore lines.

Visibility distance

The global visibility-distance option controls the maximum visibility distance of spawned chests and their holograms. The default value is 50.

visibility-distance: 50

Players outside that distance won't visually receive the chest block or its hologram; getting closer makes the chest show up again. The distance is measured from the chest's location.

Holograms

Every spawned chest has a hologram built with Display Entities (TextDisplay), without depending on any other hologram plugin. Configurable in config.yml → hologram: lines, height, scale and text-shadow. The hologram stays upright and rotates horizontally to face the player from any side, without tilting up or down.

Besides {name} and {stars}, the hologram can show the time left until despawn through the time variable set up for it.

Textured heads

To use a custom-textured head, set PLAYER_HEAD as the material and put the texture value in the texture field.

material: PLAYER_HEAD
texture: "TEXTURE_VALUE"

The texture value corresponds to the texture/Base64 value provided by the service or resource used for the head. This lets you set up custom heads without depending on the player being online.

If you're going to reuse the same head across several menus, it's more convenient to save the texture once in config.yml → custom-heads and reference it with head instead of texture:

# config.yml
custom-heads:
  empty-slot:
    texture: "TEXTURE_VALUE"

# gui/<file>.yml
material: PLAYER_HEAD
head: empty-slot

Player heads can also use the corresponding player's own skin whenever the menu needs to show a dynamic head.

Leaderboards (/dd tops)

The leaderboard system supports configurable inventories and positions with player heads, names, stats and lore.

• If a position doesn't have a player yet, that ranking file's items.empty item (e.g. gui/rarity-ranking.yml) is shown there instead of leaving the slot empty or showing the decoration.
• As soon as a player takes that position, that item is automatically replaced by their head, with their name, position and stats.
• The empty item belongs to each category: every ranking file in /gui can give it its own material, textured head and lore. See GUI and ranking files.
• The lore for occupied positions is set globally in config.yml → leaderboard.player; the lore for empty positions is set per category in items.empty.
• The inventory can be decorated, and its size, slots, materials, sounds and actions can all be configured through the GUI.

Leaderboard data is stored in stats.yml. The available stats depend on the metrics the plugin implements.

GUI and ranking files

The gui folder uses a separate system for leaderboards. The main menu is stored in gui/categories.yml. Each ranking has its own YAML file so it can be designed independently.

Included files

gui/
├── categories.yml
├── most-opened.yml
├── rarity-ranking.yml
├── rarest-opened.yml
├── best-reward.yml
└── most-rewards.yml

/tops opens categories.yml directly. That selector's buttons use actions formatted as [opengui] menu-name. For example:

actions:
  - "[opengui] most-opened"

The names used in [opengui] match the file name without .yml. So [opengui] rarity-ranking opens gui/rarity-ranking.yml.

Designing each ranking

Each ranking file can have its own title, row count, player slots, back button, decoration and the item that fills positions still without a player. This lets you build a 27-slot, 36-slot, 45-slot or 54-slot menu without touching Java.

title: "&#C77DFF&lRarity Ranking"
rows: 4
fill-border: false
stat: rarity-score
player-slots: [10, 11, 12, 13, 14, 15, 16, 19, 20, 21]
back-slot: 31
items:
  border:
    slots: "0-8,27-30,32-35"
    material: GRAY_STAINED_GLASS_PANE
    name: " "
    lore: []
    actions: []
  empty:
    material: PLAYER_HEAD
    head: empty-slot
    name: "&#C77DFFAvailable Position"
    lore:
      - "&7Position: &f#%rank%"
      - "&7No player has reached this spot yet."
      - "&7Increase your rarity score to climb here."
    actions: []
  back:
    slot: 31
    material: ARROW
    name: "&#C77DFF&l« Back"
    lore:
      - "&7Return to the top categories."
    actions:
      - "[opengui] categories"

Decorations

Decorations are added like any other items.<name>. You can use glass, blocks, heads, decorative items, names, lore and actions. Decoration slots don't have to relate to the player slots in any way.

Instead of writing one item per slot, a single item can fill several at once with the slots field (instead of slot): it accepts "border", a comma-separated list ("0,1,7,8"), ranges ("0-8,25-26"), or a mix of both ("0-8,17,25-26"). A single glass pane plus a slot pattern is enough to decorate the whole border of the menu. If another item (like back) uses a slot that falls inside that pattern, that item is drawn afterward and sits on top of the decorative glass — it doesn't matter which order they're written in the file.

Positions without a player (items.empty)

Each ranking file can define its own items.empty: the item shown at any player-slots position that doesn't have a player assigned yet. It accepts material, texture or head (see Textured heads), name and lore, and the %rank% placeholder is replaced by that position's number. As soon as a player reaches that position, this item is automatically replaced by their head. If a ranking file doesn't define items.empty, DonaDrops falls back to a generic BARRIER.

Player slots

player-slots determines exactly where player heads will appear. The number of positions also determines how many players are shown in that menu. Want a Top 5? Put five slots. Want a Top 10? Put ten.

Menu size

rows controls the inventory's size. Chest-style menus support 1 to 6 rows, i.e. 9, 18, 27, 36, 45 or 54 slots. To apply a custom size, the inventory must be of type CHEST; the physical block used by the drops doesn't change this rule. Other inventory types keep their own fixed sizes and don't accept arbitrary sizes.

Returning to categories

items.back.slot is what actually decides where the back button shows up: to move it, change that slot. The old top-level back-slot is kept only as a fallback for when items.back isn't defined, but if both exist, items.back.slot always wins. Clicking the button returns to the menu defined by categories.yml.

Chest spawn effects

A chest can show three different effects when it spawns. They're independent: each one has its own section, its own options and its own list of values. In the order players see them:

All three ship disabled: type: none means there's no effect. To enable one, just change none to whichever name you want, without adding lines or touching indentation, or pick it from the Editor GUI's buttons. In a drop's file, -1 means "use the value from config.yml".

There are also the particles played when the last item is taken out of the chest (particles), which ship enabled: see Sounds, titles and particles.

1. Pre-spawn particles (before the chest appears)

These are the particles seen at the spot where a chest is about to appear, a few seconds before it spawns (3 by default). During that time the block isn't placed yet; once it ends, the chest appears and only then are the spawn message, title and sound sent. Works the same with automatic spawning, drop events and /dd spawn.

Ships disabled: in config.yml the type is none. To enable them, just change none to a particle's name.

# config.yml
pre-spawn-particles:
  type: none
  seconds: 3
  count: 12
  offset-x: 0.4
  offset-y: 0.6
  offset-z: 0.4

Each drop can have its own in its /drops file. On a new drop everything is -1, which means "use the same values from config.yml":

# drops/donadrops.yml
pre-spawn-particles:
  type: -1
  seconds: -1
  count: -1

For example, to make only that drop show flames for 5 seconds:

pre-spawn-particles:
  type: FLAME
  seconds: 5
  count: -1

Particles available for pre-spawn-particles

These particles can be used in pre-spawn-particles.type. The second column gives a plain-language description of what each one produces.

Particle names have changed between Minecraft versions. If you write one your server doesn't recognize, DonaDrops automatically tries its equivalent (e.g. TOTEM_OF_UNDYING and TOTEM, or DUST and REDSTONE). If a name doesn't exist on your version or is misspelled, a default particle is shown instead of stopping the spawn.

2. Spawn animation

This is a particle-based animation played the moment the chest appears (after the pre-spawn particles, if you have them enabled). Unlike the others, it's only ever set in each drop's file (or from the editor's button): it doesn't exist in config.yml.

Ships disabled. On a new drop the section is already written and ready to use; type: none means there's no animation. To enable it, just change none to an animation's name:

# drops/donadrops.yml
spawn-animation:
  type: none
  duration-ticks: 30

For example, changing none to meteor:

spawn-animation:
  type: meteor
  duration-ticks: 30

Each animation draws with its own particles, which is why it doesn't have a particle option. The particles you choose go in the other two sections: Pre-spawn particles and Persistent particles. Older drop files with particle and particle-count inside spawn-animation still load fine; those two lines are ignored and disappear the next time the drop is saved. An old spawn-animation: [] is equivalent to "no animation".

Available animations

Each drop can use one of the following values in spawn-animation.type.

3. Persistent particles

These are the particles that stay around the chest while it's in the world, until the loot is claimed or the chest disappears. They aren't the spawn particles: those are seen before the chest appears, these afterward.

Ships disabled: in config.yml the type is none. To enable them, change none to a particle's name:

# config.yml
spawn-particles:
  enabled: true
  persistent: true
  interval-ticks: 10
  type: none
  count: 30
  offset-x: 0.4
  offset-y: 0.6
  offset-z: 0.4

Each drop can have its own. On a new drop everything is -1, which means "use the values from config.yml":

# drops/donadrops.yml
spawn-particles:
  type: -1
  count: -1
  interval-ticks: -1

For example, to make only that drop use totems (you can also add enabled, persistent and the offset-* fields to override them):

spawn-particles:
  type: TOTEM_OF_UNDYING
  count: 30
  interval-ticks: 10

Drop files created with older versions that have spawn-particles: [] still work fine: [] is equivalent to "no particles".

Particles available for spawn-particles

These particles can be used in spawn-particles.type. The second column gives a plain-language description of what each one produces.

Particle names have changed between Minecraft versions. If you write one your server doesn't recognize, DonaDrops automatically tries its equivalent (e.g. TOTEM_OF_UNDYING and TOTEM, or DUST and REDSTONE). If a name doesn't exist on your version or is misspelled, a default particle is shown instead of stopping the spawn.

Security and configuration

PLAYER_COMMAND runs with the permissions of the player who clicks the button, and CONSOLE_COMMAND runs as console. DonaDrops never turns player-typed data into commands on its own. Console actions should be limited to commands the administrator has configured and authorized.

Particles and animations are resolved against the installed Paper API. If a particle doesn't exist or is misspelled, a safe fallback is used instead of stopping the spawn. The production build also strips the compiler's debug metadata to reduce development information left in the bytecode. This doesn't replace server permissions, nor does it make reverse-engineering a Java plugin impossible.

RGB colors

All of the plugin's text and menus use RGB hex colors, e.g. &#FFF9B1. Bold is kept separate with &l: &#FFF9B1&lTitle. The classic color syntax (&0-&f) still works if you use it in your own configuration, but it no longer appears in any text the plugin ships by default.

GUI system (/gui folder)

Menu item names and lore respect whatever colors you write (&, hex and MiniMessage) and no longer render in purple italics by default. For italics, use &o.

Configurable inventories live in /gui/*.yml. The configuration lets you set the inventory's size, title, buttons, positions, materials, names, lore, heads/textures, decorations, sounds and actions.

items:
  close:
    slot: 34
    material: BARRIER
    name: "&cClose"
    lore:
      - "&7Closes this menu."
    actions:
      - "sound:UI_BUTTON_CLICK"
      - "close"

The editor's special buttons keep their behavior even if their visual properties are changed. Generic buttons can use any of the configurable actions.

The GUI system is built to allow broad customization: size, title, slots, materials, lore, heads, decorations, sounds and actions.

Sounds, titles and particles

Chest sounds and effects can be configured for different events: spawn, open, locked, reward, GUI click and other events supported by the configuration.

Particles when claiming the loot

When the last item is taken out of the chest, the particles from config.yml → particles are played (defaults to EXPLOSION_LARGE). Each drop can change these in its own particles section. They're different from the three spawn effects (see Chest spawn effects).

Persistent particles keep playing as long as the chest remains unclaimed and stop once all the loot is taken out.

Stars

Rarity stars have two independent colors: one for the earned stars and another for the remaining ones. Set in config.yml → general.star-color-filled and general.star-color-empty.

The same concept applies to how stars are shown in the GUI and in the hologram, so a 3-star chest can show its 3 filled stars in one color and the rest in another.

Time remaining

The time left before a chest disappears can be shown in the hologram. The remaining opening time can also be included in the cooldown message when a player tries to open a chest that's still locked.

Placeholders

DonaDrops registers its own PlaceholderAPI expansion automatically on startup (you need PlaceholderAPI installed, since it's already a required plugin). They all start with %donadrops_...% and work in any plugin compatible with PlaceholderAPI (scoreboards, tab list, other plugins' holograms, chat, etc.).

Inside the plugin itself (chat messages, titles, commands on open, holograms), you still use the same internal variables as always: %player%, %name%, %world%, %x%, %y%, %z%, {name}/{stars} in holograms, and %time% in a Drop Event's next-event-* messages.

Troubleshooting

The plugin doesn't start: check that PlaceholderAPI is installed. It's a required dependency of DonaDrops. Also check that the server runs a supported Java version (17 on 1.20 to 1.20.4, 21 on 1.20.5 to 1.21.x, 25 on 26.x) and that it's Paper 1.20 or newer, up to 26.3.

The Edit Rewards button doesn't do anything: as of v1.3.0 it should open a 54-slot editing inventory. You can remove existing rewards and place new items; changes are saved when you close it.

Empty positions in /dd tops don't show anything: check items.empty in that ranking's file inside /gui (see GUI and ranking files). Every position without a player is automatically filled with that item, and as soon as a player reaches it, it's replaced by their head and stats. If the file doesn't define items.empty, a generic BARRIER is used as a fallback.

I want to choose which worlds a drop spawns in: edit spawn-world in the drop's file. You can list several worlds separated by commas, e.g. spawn-world: worldcustom, world, world_nether.

I want a zone: use /dd zonewand or /dd pos1 + /dd pos2, then /dd createzone <name> and click the confirmation. To remove it, use /dd deletezone <name>.

/dd reload reports a YAML error: if a YAML file is broken, the reload should be treated as failed and the console should show the file and the line the problem is on, instead of falsely reporting that the reload finished successfully.

I can't open a chest that just spawned: check the time set in open-delay-seconds. The cooldown message can show how much time is left.

I want to change the chest's type: use the editor's Inventory Type selector, or set type-override on the drop.

I want a textured head: use material: PLAYER_HEAD and texture: "TEXTURE_VALUE".

Particles disappear before the chest opens: check the spawn particle settings; they should stay active as long as the chest hasn't been opened.

I don't see particles before the chest appears: they ship disabled. In config.yml → pre-spawn-particles, change type: none to a particle's name (and check that the drop doesn't have none in its own pre-spawn-particles.type). See Pre-spawn particles.

I don't see the animation or the particles around the chest: those ship disabled too. The animation is set on the drop (spawn-animation.type) and the persistent particles in spawn-particles.type. See Chest spawn effects.

Menus don't show up in my language: the language is changed in config.yml → language or from the editor's language button, and it's global. Any /gui menus you've edited keep the text you wrote. See Languages.

A sound or particle isn't working: check that the name matches the Minecraft/Paper version you're using.

A dropped reward still shows Rarity/Probability lore after I take it out of the chest: fixed in 2.0.10. Update the plugin - the lore is now removed the moment the item leaves the chest, including when it's dropped straight to the ground with the drop key (Q).

Renaming a chest makes /dd editor say it doesn't exist: fixed in 2.0.10. Renaming a chest now updates its internal identifier (and its .yml file) to match, so the name shown by tab-completion always works.

Edit Rewards shows Rarity/Probability more than once, or lines keep piling up: fixed in 2.0.10. The editor now shows a single, self-updating line for each.

Does it work on Minecraft 26.3? Yes. v2.1.0 is compatible with Paper 26.3. Remember that Minecraft 26.x requires Java 25 or higher.

The server freezes/crashes when a chest spawns: update to the latest version of the plugin; automatic spawning no longer forces chunks to load.