UltimateChristmas 4.0 Wiki

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

Troubleshooting

SymptomCause and fix
A boss or Santa is invisible with a floating name tagThe 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 playsNoteBlockAPI is not installed. It is the one soft dependency the music module needs.
Santa is a plain villagerHis 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 presentsCheck 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 valuesMinecraft caps mob health at 1024. The plugin warns on startup when a configured health is capped.
Advent door opened at the "wrong" timeCheck season.timezone and season.reset-hour in config.yml — the calendar follows them, not the machine clock.