Scene scheduler

A scene is a partial configuration that overlays your normal settings when its schedule matches. Set it once and it runs every year without anyone touching it.

Scenes live in data/scenes.json inside the resource. This is the one part of HZ-Loading that is edited as a file rather than in the panel — a schedule is a rare, deliberate change, not a daily one.

Anatomy

{
  "scenes": [
    {
      "id": "halloween",
      "name": "Halloween",
      "schedule": "0 0 25-31 10 *",
      "config": {
        "theme": "vice",
        "tagline": "Spooky season",
        "imagePlaylist": ["default-01.jpg", "default-02.jpg"],
        "tips": [
          "Stay together — the night is long",
          "Trick or treat — type /halloween for the event"
        ]
      }
    }
  ]
}

Field	Meaning
`id`	Unique identifier. Shown in the loading screen's scene label.
`name`	Display name, e.g. `Halloween`.
`schedule`	5-field POSIX cron, in UTC.
`config`	Any subset of the settings the Creator manages.

The rules

First match wins. Scenes are evaluated in array order and the first one whose schedule matches is applied. Order the array deliberately — put your most specific scene first. Partial by design. Anything a scene does not declare falls straight through to your normal configuration. That is what keeps scenes small and safe: a Halloween scene that only sets a tagline and a playlist changes nothing else.

List fields are full replacements, not appends. A scene that declares imagePlaylist replaces the whole playlist for its duration; it does not add to it. Same for tips and musicPlaylist.

A scene with no schedule never activates. That is usually a mistake, so the server prints an explicit warning at boot rather than staying silent.

Cron

Five fields, UTC: minute hour day month day-of-week.

Schedule	Meaning
`0 0 25-31 10 *`	25–31 October, all day
`0 6 2`	Every Tuesday at 06:00
`0 0 12`	The whole of December
`0 0 1 1 *`	1 January

Fields 1 and 2 are the start time, so 0 0 25-31 10 * is active from 00:00 UTC on the 25th through the end of the 31st — it matches once per minute across the whole range, not just at midnight.

UTC, not your server's local time. In summer, a European operator writing 0 6 gets 08:00 local.

Applying and checking

Edit data/scenes.json, then refresh and restart HZ-Loading. Scenes are the one thing that is not hot-reloaded.

/hzloading:scenes (admin) lists every declared scene, which one is currently active, and why. Use it to confirm a cron expression does what you think before the date arrives — it beats waiting until October to find out.

When a scene is active, players see a discreet label under the brand block reading its name, so the variation reads as intentional rather than as a glitch.