UltimateChristmas 4.0 Wiki

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.

KeyMeaning
weightRelative 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).
displayHow the reward looks in a menu (an item spec: material, name, lore).
shardsA number, or an inclusive range like "150-300".
xpVanilla experience.
pass-xpFestive pass progress.
naughty-niceNudges the player's naughty/nice standing (positive or negative).
itemsA list of item specs given directly; anything that does not fit the inventory is dropped.
commandsRun from the console, with %player% substituted.
player-commandsRun as the player.
messagesSent to the player.
broadcastSent to everyone online.
title / subtitleAn on-screen title.
soundAny vanilla sound name, e.g. ENTITY_PLAYER_LEVELUP.
particleAny vanilla particle name, e.g. END_ROD.
fireworktrue launches a festive firework.
effectsPotion 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:

KeyMeaning
materialA Bukkit material name, e.g. DIAMOND, LEATHER_HELMET.
amountStack size (default 1).
nameDisplay name, with & colour codes.
loreA list of lore lines.
glowtrue gives the enchanted shimmer without a visible enchant.
colourHex colour for dyeable leather items, e.g. "#c41e3a".
enchantsA map of enchantments, e.g. { sharpness: 3, frost_walker: 2 }.
head_textureA 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.