Tutorial The Clock

Tutorial: The Clock (Time, Day-Parts, Seasons)

One optional file gives your project a sense of time -- data/clock.json:

{
 "mode": "real",
 "day_parts": [
  {"name": "morn", "start": "04:00"},
  {"name": "day",  "start": "10:00"},
  {"name": "nite", "start": "18:00"}
 ],
 "seasons": {"1": "spring", "2": "summer", "3": "autumn", "4": "winter"}
}

• mode: "real" reads the player's OS clock -- the Gold/Silver feel, no set-the-clock ceremony. mode: "scaled" runs fan-game time instead: scale game-seconds per real second from a fixed start, saved with the game (turbo never accelerates it).
• Day-parts are yours to name -- any buckets over the 24h day, ascending starts; the span before the first start belongs to the last part, so an 18:00 nite covers midnight to dawn for free.
• Seasons map calendar months to names (Vermilion uses the Gen-5 monthly rotation so players see all four in four months). Weekdays come free (sunday..saturday).

Event conditions read all of it with the same expressions they already use for badges and flags -- time_part_nite, time_season_winter, time_weekday_monday, time_hour:

{"trigger": {"kind": "interact", "object": "SPRITE_OAK",
             "when": "time_part_nite and badge_count >= 1"}}

A project without clock.json is exactly what it was before -- clockless, untouched. Testers: --clock=2026-01-10T23:00 pins a frozen time for a run, and automated runs pin themselves so replays stay deterministic.