Configuration

A drop type is a single file in drops/, and its filename is its id: what you pass to /ld give and use in placeholders. config.yml holds only a few global options. Run /ld reload after any change; no restart is needed, and drops already in inventories pick up the new rules on their next click.

Drop Types

plugins/LuckyDrops/
  config.yml        # global settings
  drops/
    default.yml     # the "default" drop (restored if deleted)
    halloween.yml   # any extra type you create
  lang/en_us.yml
  playerdata/<uuid>.yml

A drop file bundles everything about that drop. Every key is explained by the comments in the file itself:

Section	Controls
max-clicks	Taps to fill the bar before the drop opens
display	Item name and lore
sounds	Per-click sounds (click, upgrade, open)
progress	Progress-bar characters
chances	Upgrade odds: see Chance Modes
rarities	The rarity ladder: see Rarities
rewards	The loot pool per rarity: see Rewards
preview-gui	The preview menu

To add a type, copy drops/default.yml to drops/<name>.yml (lowercase, no spaces), edit it, and /ld reload. Each drop is validated on its own, so two drops can use completely different ladders. Any problems found on load - undefined rarities, empty reward pools, odds that don't add up, too few clicks - are logged as warnings and never crash the plugin.

Item name & lore

display.name and display.lore use MiniMessage and these placeholders:

Placeholder	Meaning
<tier>	Current rarity's coloured 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 colour

Rarities

Rarities (tiers) are defined in the rarities: block, and their order is the upgrade ladder: first entry is the lowest tier, last is the top, and a drop only ever moves up.

rarities:
  common:                          # the key is the rarity ID
    display-name: "<gray>Common</gray>"
    material: PLAYER_HEAD
    texture: "eyJ0ZXh0dXJlcyI6..." # Base64 skin value
    color: "#AAAAAA"
    particle: { type: CRIT, count: 25, speed: 0.05 }

Field	Purpose
key	The rarity ID: internal wiring referenced by chances and rewards in the same file. Lowercase, no spaces; rename freely.
display-name	Player-facing name
material	Item used to render the drop, usually PLAYER_HEAD
texture	For heads: the Base64 skin value
color	Accent colour for the <tc> tag
particle	The burst played when this tier is reached

Custom textures (ItemsAdder / Oraxen)

Render a rarity as a custom item by prefixing its id in material:

material: "itemsadder:namespace:item_id"
material: "oraxen:item_id"

texture and custom-model-data are then ignored. If the plugin or id is missing, the drop falls back to a plain head and logs a warning.

Chance Modes

The chances: block sets the upgrade odds in one of two modes:

Mode	You set	Best for
simple	The final outcome: overall chance to end at each rarity	Matching a known odds table (e.g. Clash Royale chests)
advanced	The per-click chance to level up at each rarity	Fine control over the tap-by-tap feel

Simple mode

For each starting rarity, give the percentage chance to end at each rarity. A drop only goes up, so omit lower rarities, and each row should sum to ~100%:

chances:
  mode: simple
  simple:
    common: { common: 31.64, rare: 43.04, epic: 20.25, legendary: 4.06, mythic: 1.01 }
    rare:   { rare: 33.36, epic: 45.59, legendary: 19.71, mythic: 1.34 }
    # ...one row per starting rarity

Advanced mode

Give the per-click chance (0.0-1.0) that a drop advances one tier when tapped:

chances:
  mode: advanced
  advanced:
    upgrade-chances:
      common: 0.55
      rare: 0.30
      # ...
    per-click:        # optional: override by tap number
      common: { 1: 0.80, 2: 0.50 }

max-clicks (default 5) must be high enough to climb every tier; in advanced mode, more clicks also means drops tend to climb higher.

Rewards

When a drop opens, one reward is chosen from the achieved rarity's pool by weighted random: an entry's chance is its weight divided by the sum of weights in that rarity. Pools live in the rewards: block, keyed by rarity id; an empty pool gives the player nothing.

rewards:
  common:
    - { weight: 20, type: ITEM, material: BREAD, amount: 16 }
    - { weight: 10, type: ITEM, material: IRON_INGOT, amount: 5 }

ITEM

Field	Required	Description
weight	✅	Relative selection weight (> 0)
material	✅	Bukkit material, e.g. DIAMOND_SWORD
amount		Stack size (default 1)
display-name		Custom name
lore		Lore lines
enchantments		Map of enchantment: level
custom-model-data		Resource-pack model id
label		Name shown in the win broadcast when no display-name is set

COMMAND

Runs one or more commands instead of giving an item: money, crate keys, permissions, and so on. <player> is replaced with the winner's name.

Field	Required	Description
weight	✅	Relative selection weight/chance (> 0)
commands	✅	A single command or a list
source		CONSOLE (default) or PLAYER
label		Name shown in the win broadcast

rewards:
  mythic:
    - weight: 25
      type: COMMAND
      label: "<gold>Mythic Bundle"
      commands:
        - "eco give <player> 10000"

Preview Menu

A read-only GUI showing a drop's rarities, the upgrade chance at each, and every possible reward with its drop chance, opened with /ld preview. Click a rarity in the top row to show its rewards below; extra rewards page with the bottom-corner arrows.

It's configured per drop under preview-gui: (title, rows, slots, buttons, paging), with every key explained by the in-file comments - omit a key or the whole block to use the defaults. A COMMAND reward has no item, so it shows as the configurable command-reward icon.

Preview placeholders

Field	Placeholders
title	<drop>: the drop's name
rarity-button	<rarity>, <next> (next tier up), <upgrade> (upgrade chance), <tc>...</tc>
reward-lore	<chance> (percent, add your own %), <weight>, <rarity>, <tc>...</tc>
previous-button / next-button	<page>, <pages>

<upgrade> shows the per-click chance in advanced mode, or the overall chance to finish higher in simple mode; at the top tier it and <next> render as —.

Settings, Language & Logging

config.yml holds the global options:

Setting	Default	Description
license-key	""	Leave empty unless you were given a key - verification is automatic.
drop-overflow-at-player	true	If a reward won't fit, drop it at the player's feet (true) or at world spawn (false).
log-events	true	Write each drop opening to logs/latest.log (rotated per server start, like vanilla logs).
language	en_us	Which lang/<language>.yml file to load.
notify-updates	true	Notify ops and console when a newer release is available.

To translate, copy lang/en_us.yml, edit the values (keep the keys and <placeholders>), set language: to the new file, and reload. A missing file falls back to en_us.