Planeador de cenas

Uma cena é uma configuração parcial que se sobrepõe às suas definições normais quando o horário corresponde. Configure-a uma vez e funciona sozinha todos os anos.

As cenas vivem em data/scenes.json, dentro do recurso. É a única parte do HZ-Loading que se edita como ficheiro em vez de no painel — um calendário é uma alteração rara e deliberada, não diária.

Anatomia

{
  "scenes": [
    {
      "id": "halloween",
      "name": "Halloween",
      "schedule": "* * 25-31 10 *",
      "config": {
        "theme": "vice",
        "tagline": "Spooky season",
        "imagePlaylist": ["default-01.jpg", "default-02.jpg"],
        "tips": [
          "Fiquem juntos — a noite é longa",
          "Doçura ou travessura — escrevam /halloween para o evento"
        ]
      }
    }
  ]
}

Campo	Significado
`id`	Identificador único. Aparece na etiqueta de cena do loading screen.
`name`	Nome visível, por exemplo `Halloween`.
`schedule`	Cron POSIX de 5 campos, em UTC.
`config`	Qualquer subconjunto das definições geridas pelo Creator.

As regras

Ganha a primeira correspondência. As cenas são avaliadas pela ordem do array e é aplicada a primeira cujo horário corresponda. Ordene o array deliberadamente — coloque a cena mais específica primeiro. Parcial por conceção. Tudo o que uma cena não declara volta diretamente à sua configuração normal. É isso que mantém as cenas pequenas e seguras: uma cena de Halloween que só define um slogan e uma lista de imagens não altera mais nada.

Os campos de lista são substituições completas, não acréscimos. Uma cena que declara imagePlaylist substitui a lista inteira durante a sua vigência; não lhe acrescenta nada. O mesmo para tips e musicPlaylist.

Uma cena sem schedule nunca fica ativa. Normalmente é um lapso, por isso o servidor escreve um aviso explícito no arranque em vez de ficar calado.

Cron

Cinco campos, UTC: minuto hora dia mês dia-da-semana.

Horário	Significado
`* * 25-31 10 *`	De 25 a 31 de outubro, em contínuo
`* 3-4 * * 2`	Todas as terças, das 03:00 às 04:59
`* * * 12 *`	Todo o mês de dezembro
`* * 1 1 *`	1 de janeiro, todo o dia
`0 6 * * 2`	Todas as terças, apenas o minuto das 06:00

Uma cena está ativa apenas enquanto o relógio corresponder ao seu cron. Não há início, nem fim, nem duração — o servidor reavalia a cada minuto e larga a cena assim que deixa de corresponder.

Por isso os campos de minuto e hora têm de ficar em * para uma cena que deva permanecer visível. 0 0 25-31 10 * não significa «a partir da meia-noite do dia 25»; significa «durante o minuto 00:00 de cada um desses dias», ou seja, cerca de um minuto por dia. Use * * 25-31 10 *.

UTC, não a hora local do seu servidor. No verão, um operador europeu que escreva 0 6 obtém as 08:00 locais.

Aplicar e verificar

Edite data/scenes.json, depois refresh e restart hz_loading. As cenas são a única coisa que não é recarregada a quente.

/hzloading:scenes (admin) lista todas as cenas declaradas, qual está ativa e porquê. Use-o para confirmar que uma expressão cron faz o que julga antes de a data chegar — vale mais do que esperar por outubro para descobrir.

Quando uma cena está ativa, os jogadores veem por baixo do bloco de marca uma etiqueta discreta com o seu nome, para que a variação se leia como intencional e não como um erro.