Drop Types

LuckyDrops can run any number of different drop types, each with its own rarities, odds, rewards, look, and feel. Every drop type is a single file in the drops/ folder:

plugins/LuckyDrops/
  config.yml          # global settings only
  drops/
    default.yml       # the "default" drop type (ships by default)
    halloween.yml     # an example extra type you create
  lang/
    en_us.yml
  playerdata/
    <uuid>.yml        # per-player open stats

The file name without .yml is the drop's id (default, halloween, and so on). That id is what you use in the give command and in the placeholders.

What lives in a drop file

A drop file bundles everything about that drop in one place:

# drops/default.yml
max-clicks: 5

display:
  name: "<tc><tier> Lucky Drop <progress></tc>"
  lore:
    - "<tc>A sealed lucky drop.</tc>"
    - "<gray>Right-click to crack it open!"
    - ""
    - "<gray>Clicks remaining: <white><clicks></white>"

sounds:
  click:   { key: ui.hud.bubble_pop,           volume: 1.0, pitch: 1.0 }
  upgrade: { key: block.note_block.pling,       volume: 1.0, pitch: 1.0 }
  open:    { key: entity.experience_orb.pickup, volume: 1.0, pitch: 1.0 }

progress:
  filled: "●"
  empty: "○"
  separator: " "

chances:
  mode: simple
  simple:    { ... }    # see Chance Modes
  advanced:  { ... }

rarities:
  common:    { ... }    # see Rarities
  # ...

rewards:
  common:               # see Rewards
    - { weight: 20, type: ITEM, material: BREAD, amount: 16 }
  # ...

preview-gui:
  # ...                 # see Preview Menu

Section	What it controls	Page
`max-clicks`	Taps to fill the bar before the drop can open	Click count
`display`	The item's name and lore	Item name and lore
`sounds`	Per-click feedback sounds	Sounds
`progress`	The progress-bar characters	Progress bar
`chances`	Upgrade odds (simple or advanced)	Chance Modes
`rarities`	The rarity ladder for this drop	Rarities
`rewards`	The loot pool per rarity	Rewards
`preview-gui`	The look and layout of this drop's preview menu	Preview Menu

Self-contained

The rarity ids in chances and rewards refer to the ids you define under rarities in the same file. Each drop type is validated on its own, so two drops can use completely different rarity ladders without clashing.

Creating a new drop type

Copy drops/default.yml to drops/<name>.yml (for example drops/halloween.yml). Use a simple, lowercase name with no spaces.
Edit its rarities, chances, rewards, name and lore, sounds, and so on.
Run /luckydrops reload.
Hand it out with /luckydrops give <player> <name> ....

The default type

drops/default.yml is created automatically on first run. If you delete every file in drops/, the default is restored on the next start. Drops handed out as default are shown to players simply as "Lucky Drops" (no type name).

Per-drop settings

These sections used to be global; they now live in each drop file so every type can look and feel different.

Click count

max-clicks: 5

Taps needed to fill the bar before the drop can be opened. It must be high enough to climb every rarity in this drop (see Clicks and reachability).

Item name and lore

display:
  name: "<tc><tier> Lucky Drop <progress></tc>"
  lore:
    - "<tc>A sealed lucky drop.</tc>"
    - "<gray>Right-click to crack it open!"
    - ""
    - "<gray>Clicks remaining: <white><clicks></white>"

Both use MiniMessage. Available placeholders:

Placeholder	Meaning
`<tier>`	The current rarity's coloured `display-name`
`<progress>`	The progress bar, e.g. `● ● ○ ○ ○`
`<clicks>`	Clicks remaining before the bar is full
`<used>`	Clicks already used
`<tc>...</tc>`	Wraps text in the current rarity's accent `color`

Sounds

sounds:
  click:   { key: ui.hud.bubble_pop,           volume: 1.0, pitch: 1.0 }
  upgrade: { key: block.note_block.pling,       volume: 1.0, pitch: 1.0 }
  open:    { key: entity.experience_orb.pickup, volume: 1.0, pitch: 1.0 }

Event	Plays
A tap that did not upgrade	`sounds.click`
A tap that did upgrade	`sounds.upgrade`
The final click that opens the drop	`sounds.open`

Each sound has a key (a Minecraft sound event), volume, and pitch. An unknown key plays nothing and does not error.

Progress bar

progress:
  filled: "●"
  empty: "○"
  separator: " "

Key	Default	Meaning
`filled`	`●`	Character for a consumed click
`empty`	`○`	Character for a remaining click
`separator`	`" "`	Inserted between characters (`""` for none)

With max-clicks: 5 and two clicks used, this renders ● ● ○ ○ ○.

Giving a specific drop type

The drop type is a required argument on the give command:

/luckydrops give <player> <drop> [rarity] [amount] [-s]

See Commands.

When a drop type is deleted

If you delete a drop file and a player still holds one of its items, right-clicking it shows a "this drop type no longer exists" message and leaves the item alone (it is not consumed). Add the file back and reload and the item works again. Items handed out before drop types existed are treated as default.

Upgrading from an older version

If you are updating from a version that used a single config.yml with a tiers: section plus separate chances.yml and rewards.yml files, LuckyDrops migrates you automatically on first start and keeps .bak backups of everything it changes. See Migration and backups.

New sections are added automatically

When a new feature adds a section to drop files, LuckyDrops appends a default copy to your existing drops on the next load without touching your other keys or comments. The preview-gui section is added this way.

What lives in a drop file​

Creating a new drop type​

Per-drop settings​

Click count​

Item name and lore​

Sounds​

Progress bar​

Giving a specific drop type​

When a drop type is deleted​

Upgrading from an older version​