acdream/docs/plans/2026-04-23-sky-weather-lightning-port.md

Phase 5+ Port Plan — Sky / Weather / Lightning, retail-verbatim

Date: 2026-04-23 Scope: Port the remaining retail-accurate pieces of the sky/weather/lightning system so acdream visually matches a side-by-side retail client in all day/night + weather states (clear, cloudy, rainy, stormy).

Where we are today (main, commit 2802fb2)

Sky core, landed across Phases 1-4b:

• Region-dat SkyDesc loader with GameTime offsets ✓
• Retail LCG DayGroup picker (seed = Year × DaysPerYear + DayOfYear, Phase 3g) ✓
• Calendar tick extraction with GameTime.ZeroTimeOfYear = 3600 (Phase 3f) ✓
• Per-vertex D3D-fixed-function lighting formula (Phase 4, Phase 4b clamp) ✓
• Sky objects drawn with visibility, arc sweep, UV scroll ✓
• ACDREAM_DUMP_SKY diagnostic for retail-faithfulness verification ✓
• RetailTimeProbe tool for live memory comparison ✓

Left to do:

1. PhysicsScript — no loader, no runtime, no sky-side integration. User-visible: rain doesn't spawn when retail rolls a PES-carrying SkyObject.
2. Fog on sky — shader ignores fog uniforms; retail's D3D fog applies to sky.
3. Lightning flash trigger — storm timer + visual not ported.
4. Weather / DayGroup crossfade — retail's 10-second smooth blend between keyframe sets not ported.
5. AdminEnvirons override — packet handler exists as a stub on the wire side; not wired to our rendering.

Phases (execute in order)

Phase 5 — PhysicsScript loader + runtime + sky wiring

Output of parallel research agents #1 + #2 (2026-04-23):

• 2026-04-23-physicsscript.md — dat schema + runtime interpreter
• 2026-04-23-sky-pes-wiring.md — sky → PES lifecycle

Sub-phases:

• 5a Port PhysicsScript dat type + any nested types. Add to AcDream.Core/Dat/.
• 5b Port the runtime interpreter to C#. AcDream.Core/Vfx/PhysicsScriptRunner.cs. Wire into existing ParticleSystem as the spawner — we do NOT build a new emitter class, reuse what's there.
• 5c Hook into SkyRenderer → on per-frame sky-object iteration, for each visible SkyObject with non-zero DefaultPesObjectId, ensure its PES is running. Despawn on visibility loss or DayGroup change.
• 5d Replace WeatherSystem.SetKindFromDayGroupName's crude "Rainy" → WeatherKind.Rain string match with PES-driven spawning. The WeatherKind enum becomes fog/tone info only; particle emission is 100% PES-gated.

Tests: PhysicsScript parser conformance (golden bytes → expected struct), runtime determinism (same script + same seed → same particle stream).

Phase 6 — Fog on sky meshes

Output of research agent #4: 2026-04-23-sky-fog.md.

Sub-phases:

• 6a sky.vert computes fog factor per vertex. Formula from the agent's findings (expected: linear per-vertex based on eye-space Z).
• 6b sky.frag applies mix(fragment, fogColor, fogFactor) before the lightning-flash bump.
• 6c If sky meshes render at distances that saturate the keyframe's FOGEND (sky would be pure fog color), either:
  • Cap sky mesh eye-space Z at FOGEND - epsilon for fog purposes only, OR
  • Use a separate "sky fog" distance parameter per retail's behavior.

Tests: render-golden at 4 canonical times (dawn/noon/dusk/midnight) + 3 DayGroups (Sunny / Cloudy / Stormy) — compare against retail screenshots.

Phase 7 — Lightning flash trigger

Output of research agent #3: 2026-04-23-lightning-crossfade.md (shared with Phase 8 findings).

Sub-phases:

• 7a Port retail's storm-keyframe lightning timer.
• 7b Wire to existing uFogParams.z lightning-flash uniform in the UBO (sky.frag already consumes it).
• 7c Wire thunder audio cue via AdminEnvirons.Thunder1Sound..Thunder6Sound or a local per-flash delay (retail uses speed-of-sound distance).

Phase 8 — Weather / DayGroup crossfade

Also from agent #3.

Sub-phases:

• 8a Port DAT_008427a9 flag + _DAT_008427b8 progress mechanics into our SkyStateProvider or a new CrossfadeOrchestrator class.
• 8b Trigger a crossfade when:
  • DayGroup index changes (day rollover hits a new weather roll) — smooth swap of keyframe set over retail's step constant _DAT_007c7208.
  • AdminEnvirons override arrives — smooth fog transition to the override color.
• 8c AdminEnvirons wiring: the packet handler stub in WeatherSystem.Override already exists; wire it to the crossfade trigger + our renderer.

Optional Phase 9 — Per-cell AdjustPlanes terrain relight

From earlier research (2026-04-23-sky-decompile-hunt-A.md §1): retail reruns FUN_00532440 on every terrain cell whenever the sky keyframe advances. We currently bake terrain vertex lighting once and don't refresh. Visible effect: terrain doesn't darken smoothly as the sun sets.

Deferred because it's higher effort and lower payoff than 5-8.

Success criteria

1. A +Acdream character stationary in outdoor Holtburg for 30 real minutes (about 15 Derethian minutes with our 1:1 tick rate) produces a sky that, side-by-side with retail, is visually indistinguishable within lighting equipment tolerances (color temperature, saturation).
2. Rolling a DayGroup that contains a rain-emitting SkyObject causes acdream to spawn rain particles MATCHING retail's rain cadence (drop rate, direction, lifetime).
3. During a Stormy DayGroup, acdream shows lightning flashes at the retail cadence (8–30 sec between strikes, flash rises in ~50ms, decays in ~200ms).
4. An AdminEnvirons RedFog packet arriving mid-play crossfades acdream's fog to the red tint within ~10 real seconds, same direction retail does.

Non-goals (for this plan)

• PhysicsScript author tools — we parse + run; we don't edit.
• Retail-accurate GPU particle rendering — reuse our existing ParticleSystem backend. PhysicsScript drives IT, not a new emitter.
• Exotic EnvironChangeTypes (the Thunder3Sound, DarkLaughSound, etc. non-fog variants) — those are admin-only and we can stub-log them.
• Per-landblock weather variation — retail weather is Dereth-wide.

Open risks / unknowns (to be resolved by agents)

• Will our ParticleSystem.SpawnEmitter API be sufficient, or does retail's PhysicsScript need commands we don't expose? (agent #1).
• Does sky mesh vertex data need a 1e6-far-plane fog distance rescaling, or is retail's FOGEND authored large enough to cover sky? (agent #4).
• Does retail sync the lightning random timer across all clients (so everyone sees the same strike), or is it truly client-local? (agent #3).