Time & Weather

Day/night, seasons and weather as shared drivers for lighting, materials and demand.

Macroscopic SimulationTime & Weather

Day/Night

Drives the sun/sky lighting (Art & Lighting doc) and citizen agent schedules — commute waves keyed to time of day (Citizen Simulation doc).

Seasons

Affect ground-cover procedural material parameters (Materials/Art docs) and plausibly seasonal demand (heating/cooling load on the power subject).

Weather

Rain/snow modeled as a light system affecting the procedural road material layer (wetness/snow overlay) and possibly traffic speed.

Time Control

Player-facing pause / 1x / 2x / 3x speed controls; the calendar tick drives the macro economy simulation step (Economy doc).

Photo Mode

The debug tweak tools for scrubbing time-of-day and setting weather double as the foundation for a player-facing Photo Mode: a dedicated panel (promoted from the prototype's "Time & Weather" debug panel, which becomes a subsection within it) for posing magazine-cover-looking screenshots of a player's city. Adds one-click time-of-day presets — Noon, Morning, Golden Hour — alongside the existing scrubber, tied to the same sun/sky lighting as normal play rather than a separate render path.

Art Direction & Lighting

Data Model

Time & Weather's data lives in game/src/simulation/time/ (the calendar math and the runtime state) and game/src/tweaks.ts (the tunables other systems wire to). This is the canonical shape of each piece so Art & Lighting, Citizen Simulation, and the economy can wire to it without re-reading the source.

Entity / Constant	Shape / Fields
`Weather`	`"clear" \| "fog" \| "rain" \| "snow"` — the four weather conditions the player can dial in from the debug HUD.
`WeatherFog`	`day: hex`, `night: hex`, `density: per-cm` — the per-weather fog profile. The fog color is interpolated between `day` and `night` by the sky's `dayBrightness(dayPhase)` curve so it tracks the horizon at any time of day.
`FOG_BY_WEATHER`	`ReadonlyMap<Weather, WeatherFog>` — single source of truth for per-weather fog, one entry per weather. `clear` is subtle (matches the sky horizon so the seam is invisible); `fog` / `rain` / `snow` are progressively denser and grayer. See `tweaks.ts` for current values.
`TimeState` (runtime)	`speed: Speed`, `ticks: number` (elapsed sim seconds), `weather: Weather` — the only state on the time subject. `dayPhase`, `dayIndex`, and `season` are derived on demand from `ticks` via `calendar.ts`'s `read()`, not stored, so the calendar shape can change without a save/load migration.
`SIM_DAY_SECONDS`	Sim-seconds in one in-game day at 1x speed (`24 * 60` = 24 real minutes per game-day).
Calendar shape	`DAYS_IN_WEEK = 3`, `WEEKS_IN_MONTH = 2`, `MONTHS_IN_YEAR = 4`, `MONTHS_PER_SEASON = 1` — 24 game-days per year, deliberately compressed for fast season turnover during playtesting. See `toDisplayDate()` in `calendar.ts` for the projection onto a human-readable 30-day month.
Sun curve	`SUN_RISE_START/END` (0.21/0.25), `SUN_SET_START/END` (0.75/0.88), `SUN_MIN/MAX_INTENSITY` (0.1/1.0) — `dayPhase` values where the sun's intensity transitions, and the night/day floor & ceiling. See Art & Lighting for the visual effect.
`SUN_TERMINATOR_SOFTNESS`	Smoothstep half-width on the day/night Lambertian terminator (0.3). The Lambertian `dot(normal, sun)` is passed through `smoothstep(-SOFTNESS, +SOFTNESS, ...)` so the transition from the night ambient floor to full daylight fades instead of forming a hard contour line. Lower values approach the original hard-step behavior; the 0.3 default covers most of the visible terminator.

Questions

Whether weather is mechanically meaningful (traffic slowdowns, demand shifts) or cosmetic-only for v1.
Whether Photo Mode presets should pause simulation and freeze weather/traffic, or just dial lighting while the city keeps living.
Whether additional presets (e.g. Blue Hour, Overcast) are worth the art-direction time beyond the initial three.

Status

Implemented: Calendar math (pure functional, no state mutations), requestAnimationFrame-driven sim clock, speed controls (Pause/1x/2x/3x), toolbar clock display with live date/time, debug HUD panel with day/season/phase readout, weather control (cosmetic-only placeholder), and a throwaway day/night clear-color tint for visual feedback. Unit tests cover day boundaries, season rollover, and paused ticking.

Blocked dependencies:

Real sun/sky lighting: Requires WebGPU + Art & Lighting pipeline. The current day/night tint in game/src/render/scene.ts is a temporary stand-in, not a first draft — to be deleted wholesale once art-lighting lands.
Mechanical weather effects: Traffic slowdowns and demand shifts require traffic/economy simulation to have a hook for weather to affect. Deferred pending economy-zoning implementation.
Seasonal material parameters: Ground-cover and road material variations by season require procedural-materials` GPU pipeline.


          Citizen commute scheduling: Requires citizen-simulation, which is blocked on pathfinding on arc-spline bundles.
          Photo Mode: The debug time-panel's scrubber and weather controls are a good foundation, but the feature only becomes interesting once dayPhase actually drives real sun/sky — not the placeholder tint. Blocked on the same WebGPU + art-lighting dependencies as real lighting.
          Save/load: No persistence layer exists yet; requires designing how to serialize/restore `ticks` and calendar config alongside the rest of game state.


      
        Related docs
        
    🎨
    Art Direction & Lighting
    💰
    Economy & Zoning