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": "  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
`25-31 10 *`	25–31 October, continuously
`3-4 * 2`	Every Tuesday, 03:00 → 04:59
`12`	The whole of December
`1 1 *`	1 January, all day
`0 6 2`	Every Tuesday, the 06:00 minute only

A scene is active only while the clock matches its cron. There is no start, no end and no duration — the server re-evaluates every minute and drops the scene as soon as it stops matching.

So the minute and hour fields must stay for a scene that should stay up. 0 0 25-31 10 does not mean "from midnight on the 25th"; it means "during the 00:00 minute of each of those days" — about one minute per day. Use 25-31 10 *.

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.