UltimateChristmas 4.0 Wiki

UltimateChristmas / Advent calendar

Advent calendar

One door per day of the season. Fix the rewards for the days that matter, let the rest roll from a weighted pool, and let streak bonuses and the catch-up system bring players back every single day.

module id: advent config: modules/advent.yml

How players use it

/christmas advent (permission ultimatechristmas.advent) opens the calendar. Today's door is a chest; opened doors turn green, missed ones red, future ones grey. /christmas advent claim claims directly, /christmas advent streak shows the current streak.

The calendar follows the season clock in config.yml — start date, length, timezone and the daily reset hour all come from there.

Core settings

door-count: 25            # capped by season.length-days in config.yml
nice-points-per-door: 1   # naughty/nice credit per opened door
celebrate: true           # particles + a sleigh-bell jingle on claim

# Missed a day? Buy it back. The cost multiplies by how many days late it is,
# so forgetting one door is cheap and abandoning the calendar is not.
catch-up:
  enabled: true
  cost-per-day: 150

# A bonus every N days opened in a row. The payout scales with the streak tier,
# so a 20-day streak pays four times what a 5-day streak does.
streak:
  bonus-every: 5
  bonus-shards: 100

Fixing rewards to specific doors

Map a day number to a reward id; every unmapped door rolls at random from the weighted pool. This is how you hand-pick the big days:

doors:
  "1":  welcome_gift       # day one hooks them
  "6":  saint_nicholas     # Saint Nicholas Day
  "12": midwinter_haul     # halfway milestone
  "24": christmas_eve
  "25": christmas_morning  # the big one

Fixed rewards use weight: 0 so they never also appear in the random pool.

Rewards

Each entry is a standard reward with a display item for the menu. The default pool runs from a lump of coal (with naughty-nice: -1) through sweets, mittens and silver bells up to a rare "frozen treasure" that broadcasts to the server:

rewards:
  lump_of_coal:
    weight: 18
    display: { material: COAL, name: "&8Lump of Coal" }
    shards: 10-25
    naughty-nice: -1
    items: [ { material: COAL, amount: 8 } ]
    messages: ["&8A lump of coal. Better behave tomorrow."]

  frozen_treasure:
    weight: 5
    display: { material: DIAMOND, name: "&b&lFrozen Treasure" }
    shards: 700-1100
    xp: 300
    pass-xp: 200
    broadcast: ["&b%player% &7found frozen treasure in the advent calendar!"]
    firework: true

Menu appearance

menu:
  title: "&c&lAdvent Calendar &7- Day %day%/%doors%"
  icons:
    opened: LIME_STAINED_GLASS_PANE
    today: CHEST
    missed: RED_STAINED_GLASS_PANE
    locked: GRAY_STAINED_GLASS_PANE
  names:
    today: "&e&lDay %day% &7- open me!"

Admin

/christmas advent reset <player> (permission ultimatechristmas.admin.advent) resets a player's calendar — useful for testing your reward pool before the season starts.