Weather system (preview)

Dawn Engine Weather is a planned first-class weather orchestration Gem (Gems/Weather). It drives sky, fog, precipitation, wind, surface wetness/snow/ice, audio, and gameplay queries from a continuous meteorological parameter model, and exposes 3D atmosphere sampling for flight simulation.

Maturity: planned / design complete. The Gem is not shipped; APIs, assets, and editor workflows described here are targets, not available product surfaces. Enabling any future Registry gate must leave existing SkyAtmosphere, DeferredFog, PhysX Wind, and Water paths unchanged when Weather is off.

It does not own aircraft dynamics: JSBSim (via the planned Flight Gem) consumes weather facts; Weather never computes lift, drag, or thrust.

What problem it solves

Open worlds and simulation need one authoritative answer to “what is the weather here?”—not separate fog knobs, particle toggles, and wind sources that drift apart. Weather is intended to provide:

A continuous parameter snapshot (WeatherSnapshot) instead of hard-cut enums—rain/snow mixes and custom presets are first-class;
Global weather plus regional WeatherVolume overrides (valley fog, sandstorm belts) with blend modes and timed redirects;
Orchestration bridges into existing Gems (SkyAtmosphere, DeferredFog / PostFx, OpenParticleSystem, PhysX Wind, SurfaceData, Audio)—not a second renderer;
Sparse authoritative surface state (wetness, puddles, snow depth, ice) for materials and gameplay friction multipliers;
Aviation-grade 3D sampling: pressure / OAT / density, wind profiles, turbulence, cloud layers, icing environment, and aerodrome observations for the full flight phase matrix.

Planned capabilities

Ground and environment (M0–M6)

Milestone	Focus
M0	Gem scaffold, Registry opt-in (default off), L1 core unit tests
M1	Presets, global controller, SunSky notification baseline, AtomBridge (sky / fog / PostFx)
M2	Rain / snow / hail particles, lightning + delayed thunder, wind, audio states
M3	Sparse `SurfaceStateField`, material wetness/snow SRG, friction query adapters
M4	Weather volumes, weighted scheduler, day/night coupling
M5	Large-world / render-origin contracts, volume streaming with World Streaming cells
M6	Server-authoritative multiplayer, persistence, quality tiers, performance gates

Built-in preset targets include Clear, Cloudy, Fog, Haze, rain / storm family, snow / blizzard, sleet, freezing rain, hail, and Interior.

Aviation track (MF1–MF4)

Depends on the ground milestones above; does not replace them:

Track	Focus
MF1	ISA baseline × weather modulation, `SampleAtmosphereD`, wind profiles
MF2	Cloud-layer IMC/VMC and 3D precipitation gating (volumetric clouds remain a separate render effort)
MF3	Turbulence / shear / microburst, icing environment, JSBSim FlightBridge, aerodrome weather
MF4	Route / forecast / radar data sources, networked altitude consistency, full-mission recipes

How it will work

SunSky / Scheduler / Script
 │
 ▼
Weather L1 Core (pure params / blend) ──► L2 Runtime (fixed 0.5 s tick)
 │
 ├─ AtomBridge ──► SkyAtmosphere / DeferredFog / PostFx / materials
 ├─ ParticleBridge ──► OpenParticleSystem
 ├─ PhysicsBridge ──► PhysX Wind
 ├─ SurfaceDataBridge / AudioBridge
 └─ FlightBridge ──► JSBSim (facts only, one-way)

Design rules in the specs:

Orchestrate, do not reinvent: bridges call public Gem APIs; L1/L2 stay free of render/physics Gem dependencies for headless tests.
Double-precision world queries: absolute positions use AZ::Vector3d / AabbD; GPU quantities stay render-origin-relative.
Deterministic enough for net and CI: fixed simulation steps, explicit PRNG seed/counter, quantized tolerances—not bitwise identity across every CPU.

Explicitly out of scope for v1

Not in v1	Notes
Volumetric cloud rendering	Separate Atom render program; MF2 ships fog-based in-cloud approximation
Full NWP / fluid atmosphere	Parameter model only
Airframe icing accumulation	Weather outputs severity; aircraft systems own accumulation
ICAO-compliant live METAR ingest	Structured observation APIs; live feeds are project-layer
Per-pixel snow displacement	Material + sparse cells in v1
Weather-driven water levels / seasons	Candidate for later revisions

Topic	Relationship
Double-precision rendering	Large-world sample positions and render-origin stability
World Streaming	Weather volumes load/unload with cells
PhysX Vehicle	Optional friction multipliers from surface state
Flight (planned)	Consumes `WeatherFlightRequestBus` atmosphere / wind facts
Cesium 3D Tiles	SunSky solar baseline; notification bus is an M1 prerequisite

Status and next steps

This chapter is a product preview. When Weather ships, the guide will grow Quick start, Registry keys, authoring recipes, and Script Canvas / Lua samples—consistent with chapters such as PolyTerrain and Water.