UltimateChristmas / Reward format
The reward format
Every prize in the plugin — advent doors, boss loot, Santa's gifts, hidden presents, shop entries, quest payouts, snowball hits, the tree's completion gift — uses the same YAML shape. Learn it once and you can configure everything.
All keys
Every key is optional; combine any of them.
| Key | Meaning |
|---|---|
weight | Relative chance where several rewards compete in one table. 0 = never rolled randomly (but still usable where a reward is named directly, e.g. a fixed advent door). |
display | How the reward looks in a menu (an item spec: material, name, lore). |
shards | A number, or an inclusive range like "150-300". |
xp | Vanilla experience. |
pass-xp | Festive pass progress. |
naughty-nice | Nudges the player's naughty/nice standing (positive or negative). |
items | A list of item specs given directly; anything that does not fit the inventory is dropped. |
commands | Run from the console, with %player% substituted. |
player-commands | Run as the player. |
messages | Sent to the player. |
broadcast | Sent to everyone online. |
title / subtitle | An on-screen title. |
sound | Any vanilla sound name, e.g. ENTITY_PLAYER_LEVELUP. |
particle | Any vanilla particle name, e.g. END_ROD. |
firework | true launches a festive firework. |
effects | Potion effects as ["TYPE:ticks:amplifier", ...], e.g. ["SPEED:600:1"]. |
Example
frozen_treasure:
weight: 5
display:
material: DIAMOND
name: "&b&lFrozen Treasure"
lore:
- "&7Rare. Lucky you."
shards: 700-1100
xp: 300
pass-xp: 200
naughty-nice: 2
items:
- { material: DIAMOND, amount: 4 }
commands:
- "crate key give %player% Mythic 1"
messages:
- "&b&lFrozen treasure! &aThat is a rare one."
broadcast:
- "&b%player% &7found frozen treasure!"
sound: UI_TOAST_CHALLENGE_COMPLETE
firework: true
Item specs
Wherever an item appears — in items, a display, or a shop entry — the same keys apply:
| Key | Meaning |
|---|---|
material | A Bukkit material name, e.g. DIAMOND, LEATHER_HELMET. |
amount | Stack size (default 1). |
name | Display name, with & colour codes. |
lore | A list of lore lines. |
glow | true gives the enchanted shimmer without a visible enchant. |
colour | Hex colour for dyeable leather items, e.g. "#c41e3a". |
enchants | A map of enchantments, e.g. { sharpness: 3, frost_walker: 2 }. |
head_texture | A Base64 skin texture for PLAYER_HEAD items. |
items:
- { material: LEATHER_BOOTS, name: "&b&lFrost-Walkers", colour: "#a8d8ff",
enchants: { frost_walker: 2, feather_falling: 3 }, glow: true }
Weighted tables
Where several rewards sit side by side (boss loot, Santa's gifts, present contents, the advent random pool), one is rolled per grant, with probability proportional to its weight. Weights don't need to add up to 100 — 40 / 30 / 20 / 10 and 4 / 3 / 2 / 1 behave identically.