UltimateChristmas / Installation
Installation
Drop the jar in, start the server, point players at the resource pack. Everything else is optional tuning.
First run
Put UltimateChristmas-4.0.0.jar in plugins/ and start the server. The plugin unpacks everything it ships with into its data folder:
plugins/UltimateChristmas/ ├─ config.yml global settings (season, currency, storage, resource pack) ├─ lang.yml every player-facing message ├─ modules/ one commented config file per module (20 files) ├─ music/ 23 bundled .nbs carols — drop your own here too ├─ models/ the 4 bundled Blockbench models + README.txt ├─ rigs/ compiled animation rigs for the built-in renderer ├─ pack/ UltimateChristmas-Models.zip — the client resource pack └─ playerdata/ player profiles (or players.db with SQLite storage)
Then set up the resource pack so clients can see the animated bosses, and run /christmas in game.
The season clock
Everything date-related reads one clock in config.yml, so the advent calendar, the countdown and daily resets can never disagree with each other:
season:
start: "" # Day 1 of the season, yyyy-MM-dd. Blank = 1 December.
length-days: 25 # Season length. The advent calendar is capped by this.
christmas-day: "" # Blank = 25 December of the start year.
timezone: "UTC" # Full zone id ("Europe/Paris"), so DST is handled.
reset-hour: 0 # Hour (0-23) the day rolls over. With 5, anything
# before 05:00 still counts as the previous day.
reset-hour: 5 suits servers whose players are most active late at night — opening the advent door at 2 a.m. still counts as "yesterday".
Player storage
storage:
type: yaml # yaml = one file per player under playerdata/
# sqlite = a single players.db
auto-save-seconds: 300 # How often pending changes are flushed.
Writes are batched and always happen off the main thread; data is also saved when a player disconnects and when the server stops, so auto-save-seconds is only a safety net. Switch to sqlite past a few thousand players — it also turns leaderboards into an indexed query instead of a folder scan.
Currency name
currency: singular: "shard" plural: "shards"
The name is global because it appears in messages from the shop, the advent calendar and boss rewards alike.
Disabling features before first start
Normally you manage modules in game (module system), but you can also pre-disable features by hand:
modules: disabled: [secretsanta, snowball]
Updating the plugin
- Bundled assets (models, rigs, the resource pack) are versioned by content. When an update changes them, the plugin refreshes the shipped copies automatically and backs up the old ones to
plugins/UltimateChristmas/model-backups/. - Your own additional models and rigs are left alone, and with an unchanged bundle your local edits survive restarts.
- If the resource pack changed, players need the new zip — re-host or re-merge it (see resource pack).
- One-time config migrations back up the original file beside itself first (for example
bosses.yml.before-grinch-remastered-20261116), and preserve your customized health, loot, locations and messages.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| A boss or Santa is invisible with a floating name tag | The client does not have the resource pack. Set up delivery, or set model.provider: none (per boss in bosses.yml, or in santa.yml) for the vanilla mob. |
| Music commands exist but nothing plays | NoteBlockAPI is not installed. It is the one soft dependency the music module needs. |
| Santa is a plain villager | His model is turned off (model.provider: none) or the santa_claus rig failed to load — check the console on startup. In that fallback, LibsDisguises plus skin in modules/santa.yml gives him a player skin. |
| Santa never drops presents | Check gifts.drops.enabled in modules/santa.yml, and that fewer than max-on-ground unopened presents are lying around. /christmas santa drop forces one. |
| A boss's health bar looks wrong at huge values | Minecraft caps mob health at 1024. The plugin warns on startup when a configured health is capped. |
| Advent door opened at the "wrong" time | Check season.timezone and season.reset-hour in config.yml — the calendar follows them, not the machine clock. |