Rarities

Rarities (also called tiers) are the heart of LuckyDrops. They're defined in the tiers: section of config.yml, which is the single source of truth - the other files (chances.yml, rewards.yml) refer back to the ids you define here.

Anatomy of a rarity

tiers:
  common:                              # <- this key is the rarity ID
    display-name: "<gray>Common</gray>"
    material: PLAYER_HEAD
    texture: "eyJ0ZXh0dXJlcyI6..."     # Base64 skin "textures" value
    color: "#AAAAAA"
    particle:
      type: CRIT
      count: 25
      offset-x: 0.3
      offset-y: 0.3
      offset-z: 0.3
      speed: 0.05

Field	Purpose
key (`common`)	The rarity ID - the backend name used to link the config files. Keep it lowercase with no spaces.
`display-name`	The pretty, player-facing name. Full MiniMessage support.
`material`	The item used to render the drop. Usually `PLAYER_HEAD`.
`texture`	For player heads: the Base64 `textures` value of the skin to show.
`color`	Accent colour (hex) used for the item name/lore via the `<tc>` tag.
`particle`	The celebratory particle burst (type + count + spread + speed).

IDs vs display names

The ID (common) never changes appearance - it's the wiring. The display-name (<gray>Common</gray>) is what players see. You can rename an ID to anything (bronze, tier1, …) as long as you mirror it in chances.yml and rewards.yml.

Order = progression

The order rarities appear in config.yml defines the upgrade ladder: the first entry is the lowest tier and the last is the top. A drop can only move up this ladder, never down.

The default tiers

The defaults mirror Clash Royale's 1-Star → 5-Star Magic Lucky Chests:

ID	Display	Head colour	Accent
`common`	Common	Light grey	`#AAAAAA`
`rare`	Rare	Orange	`#FF8C1A`
`epic`	Epic	Magenta	`#D94DD9`
`legendary`	Legendary	Yellow	`#FFD633`
`mythic`	Mythic	Red	`#FF3030`

Adding, removing, or renaming rarities

There can be any number of rarities. To change them:

Edit the tiers: list in config.yml.
Mirror the same ids in chances.yml (odds) and rewards.yml (loot).
Run /luckydrops reload.

Keep the three files in sync

Every rarity id must appear consistently across config.yml, chances.yml, and rewards.yml. The plugin validates this on startup and reload (see below).

How drops display

While a drop is being opened, its name and lore come from the active language file. The available placeholders are:

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`

The progress bar characters and spacing come from settings.progress in config.yml.

Sounds & particles

A tap that doesn't upgrade plays the click sound.
A tap that does upgrade plays the upgrade sound and the new tier's particle.
The final open click plays the open sound and a celebratory particle burst.

Sounds are global and configured in settings.sounds (see Configuration). Particles are per-rarity.

Validation

On startup and on /luckydrops reload, LuckyDrops cross-checks all three files and logs clear warnings for problems such as:

a rarity in rewards.yml or chances.yml that isn't defined in config.yml;
a configured rarity with no rewards;
in Simple mode, a starting rarity with no odds row, or rows that don't sum to ~100%;
max-clicks set too low to climb through every rarity.

Validation only warns - it never stops the plugin from loading.

Anatomy of a rarity​

Order = progression​

The default tiers​

Adding, removing, or renaming rarities​

How drops display​

Sounds & particles​

Validation​