world-time-weather

name: world-time-weather description: >- Architecture blueprint for time-of-day, weather, seasons, and climate systems: central game clocks, time scale, calendars, server/diegetic clocks, weather profiles, regional schedules, overrides, volumetric clouds, storms, systemic weather effects, survival temperature, event schedulers, daily resets, TOD lighting, rendering integration, and persistence. Use when designing day/night, weather, seasons, dynamic skies, hazards, resets, or when weather pops, forced weather leaks, the sun jitters, or time-skip floods events.

World Time & Weather

Build the time-of-day + weather layer of an open-world game — systems first: the clock, the weather state machine, their gameplay consumers, the scheduler, and the rendering integration. References: BotW/TotK (the best-datamined implementation in the genre) and Genshin (the server-clock model), broadened with the simulation-driven weather (RDR2, Sea of Thieves), seasonal (Stardew, RimWorld), and rendering (Nubis, Hillaire) traditions.

The architecture rule

One clock service, one weather service — both publish; nobody polls the raw clock.

GAME CLOCK   monotonic accumulator (double/ticks, NEVER a wrapped float);
             publishes day-phase flags + change events; dual day divisions;
             dual server/diegetic clocks; calendar/seasons if used
WEATHER      weather is DATA (climate profiles, pre-rolled regional schedules,
             the handle-based override stack) — or simulated (clouds/fronts);
             a weather state bundles precip/wind/fog/cloud/lighting/audio/flags
CONSUMERS    subscribe to events; read cached state; never poll-compute;
             continuous values (wetness 0-1) ride a global parameter bus
SCHEDULER    fixed-hour hooks, two-phase events, respawn policies, time-skip
             catch-up (fire once, never N times, never zero)
ENGINE       dynamic GI under a moving sun, sky/cloud rendering, precipitation
             + rain occlusion, the param bus written once per frame

Reference map

Systemic weather (the chemistry-engine model)

Weather earns its cost when it is an input to other systems, not a backdrop (GDC 2017: elements vs materials, "rules over content"):

• Rain: wet surfaces → climbing slip, fires extinguished, footstep masking → stealth, grounded electric attacks → AoE. Genshin: rain applies the Hydro aura — weather feeds the elemental combat system.
• Thunderstorms: lightning targets metal equipment with a ~10 s telegraph — the canonical fair hazard, and an offensive tool.
• Temperature is climate data, not simulation: per-altitude/day-night tables; damage ticks (BotW cold) or a visible gauge (Sheer Cold). Richer survival models (TLD "Feels Like", RimWorld comfort band) live in consumers.md.

Build order (4 shippable tiers)

Tier 1 — The clock
- [ ] Clock service: double/tick accumulator, configurable time scale, pause rules
- [ ] Day phases: binary flag + fine divisions; change events; clock modes
- [ ] Calendar/seasons if used (date as a persisted value)
- [ ] Debug panel: scrub time, jump to hour
Tier 2 — Weather states
- [ ] Weather profiles as data; region → climate map + pre-rolled schedule
- [ ] Timed blends between states (everything fades)
- [ ] The override stack with handles, priorities, timeouts, diagnostic
Tier 3 — Consumers
- [ ] Publish/subscribe + global parameter bus written once per frame
- [ ] Two or three systemic consumers end-to-end (climb slip, fire, stealth)
- [ ] Precipitation occlusion + interior volumes; hazards with telegraphs
Tier 4 — Scheduler, persistence, engine
- [ ] Event scheduler: fixed-hour hooks, two-phase events, time-skip catch-up
- [ ] Respawn policies with the never-on-screen invariant
- [ ] Serialization: clock, schedule + blend state, scheduler timestamps (game time)
- [ ] TOD lighting: dynamic GI, sky/cloud, param bus; budget the storm-at-dusk peak

Key numbers (starting points — sourced anchors)

Full sourced tables (with flagged "do-not-invent" gaps) in each reference file.

Engine mapping (summary)

Full detail in engine.md.