acdream/docs/research/2026-08-23-sky-default-script-port.md

Sky default-script (aurora/lightning/thunder) — the retail mechanism, proven

Date: 2026-08-23 · Issues: #28 (aurora), #2 (lightning, partial), #29 (clouds — not addressed here) · Phase: C.1.5c

The April contradiction, resolved

Two prior research passes (2026-04-23-sky-pes-wiring.md, 2026-04-28-pes-pseudocode.md) correctly proved GameSky never reads CelestialPosition.pes_id (SkyDesc::GetSky @0x00501EC0 writes it at 0x00501FC9; no reader exists), and issue #2 therefore banned per-SkyObject PES playback "without new decompile evidence". This document is that evidence. Both were right and both missed the actual route:

The sky PES ids ride the sky Setups' own DefaultScript, and retail plays them through the ordinary object default-script machinery — the pes_id column is a dead mirror of the same ids.

Verified in the installed Dereth DAT: Setup 0x02000714 (aurora carrier, parts 0x010001EC) has DefaultScript = 0x330007DB — byte-equal to its SkyObject's PesObjectId. Same holds for 0x02000589→0x3300042C (thunder ping-pong), 0x02000588→0x33000428 (thunder variant), 0x02000BA6→0x33000453 (lightning flash).

The retail chain (named decomp, every link read this session)

1. GameSky::UseTime @0x005075B0 (30 Hz) → CRegionDesc::GetSky → SkyDesc::GetSky @0x00501EC0 rebuilds the CelestialPosition list. Per-object visibility: if begin_time == end_time the object is always included; otherwise begin <= t <= end gates the gfx id (out-of-window → INVALID_DID). The aurora object has begin=end=0.00 in all 20 day groups → always present, all day.
2. GameSky::CreateDeletePhysicsObjects @0x005073C0: an existing sky object is kept when its current DataID equals the wanted gfx id AND the properties word is unchanged AND (props & 4 → LScape::weather_enabled did not flip). Only a mismatch destroys/recreates. ⇒ the aurora object — same id in every group — persists across day-group changes, and its emitters keep their particle population.
3. GameSky::MakeObject @0x00506EE0: props & 4 objects are only created when LScape::weather_enabled != 0; props & 1 selects after_sky_cell (post-scene) vs before_sky_cell. Creation is CPhysicsObj::makeObject(gfx_id, 0, 0).
4. CPhysicsObj::makeObject @0x00513970 → InitPartArrayObject: a Setup with default_script_id != 0 sets state |= 0x80000 and registers via CPhysics::AddStaticAnimatingObject @0x00509AF0.
5. CPhysicsObj::animate_static_object @0x00513DF0 (per tick): state 0x80000 → ScriptManager::UpdateScripts (starts/advances the default script — the PES) and updates the object's ParticleManager. This is the ~150/min CallPES churn the 2026-04-30 live trace counted (the thunder PES 0x3300042C ping-pongs via CallPES chains).

The particle laws confirmed against our port

• ParticleEmitterInfo::GetRandomOffset @0x005174A0: random vector, minus its projection onto offset_dir, normalized, × rand[min,max] — a disk PERPENDICULAR to the dir (a shell when dir is zero). Our ParticleSystem.RandomOffset is byte-faithful. The aurora's 450–700 m "Z-dir" offsets are therefore a horizontal RING around the sky-object origin, not a column above it.

• Particle::Update @0x0051C290 writes only the part origin per type formula (our ComputePosition matches, incl. Swarm cos/sin); only the GR/LR parabolic variants rotate.

• ParticleEmitter::SetInfo @0x0051CE90: parts are ordinary CPhysicsPart::makePhysicsPart(hw_gfxobj_id); there is no special "2D particle" draw. CPhysicsPart::Draw @0x0050D7A0 always feeds DrawMesh(gfxobj[deg_level], &draw_pos).

• The facing law — CPhysicsPart::calc_draw_frame @0x0050DFA0, driven by the FIRST degrade entry's mode (GfxObjDegradeInfo::get_degrade @0x0051E4B0; viewer_heading = normalized part→viewer from UpdateViewerDistance @0x0050E030):

  draw = pos
  switch deg_mode:
    2:      Frame::set_vector_heading(draw, viewer_heading)      // face viewer, roll-free
    3/4/5:  Frame::rotate_around_axis_to_vector(draw, X/Y/Z, vh) // cylindrical, one free axis
    else:   authored orientation (mode 1, mode 0, out of range)
  

  Our renderer camera-plane-aligned every "billboard" particle (cameraRight/cameraUp); retail faces each part toward the viewer per-part and honors constrained modes. CPhysicsPart::Always2D @0x0050D8A0 (mode != 1) is only consulted for cell membership (CLandCell::add_all_outside_cells @0x00533360), not drawing.

• The aurora emitters (0x32000455/56/57): BirthratePerSec 10, max 3, initial 3, lifespans 3300/900/400 s, StartTrans 0.8 → FinalTrans 1.0 (≤20 % opacity fading to nothing), StartScale 7–8, sprites 0x01001A61..63 = single ±137.5 m quads whose 64×64 additive textures are soft glow blobs (row/col profiled — no banding; peak RGB 36–71/255). First degrade mode = 2 on all three. The visible aurora is therefore nine huge, faint, viewer-facing glows in a slow Swarm drift — a pulse that re-brightens when a cohort is reborn (~6.7/15/55 min cycles), not a steady fixture.

Why the 2026-08-23 experiment looked like "whole-sky tint"

The debug controller (ACDREAM_ENABLE_SKY_PES=1) ran under day group 16 (Rainy) at t=0.125 — inside the lightning window (0.03–0.19) — so the lightning-flash and thunder PES played at the camera anchor alongside the aurora. A flash sprite at the anchor IS a full-screen additive wash. The aurora itself was drowned under a faithful-but-wrong-conditions storm.

Port deltas (this change)

1. Sky default-script playback becomes production (no env flag): every visible sky object whose Setup carries a DefaultScript plays it through PhysicsScriptRunner, anchored at the camera (retail sky-cell space is viewer-centered), pass-routed by props & 1.
2. Persistence contract: script/emitter state is keyed by (gfx id, properties) per CreateDeletePhysicsObjects — a day-group flip that keeps the same carrier Setup must NOT restart its emitters.
3. Weather gating: props & 4 objects follow the weather-enabled state (acdream's weather system), matching MakeObject's guard.
4. calc_draw_frame facing law in the particle renderer: per-sprite degrade mode picks face-viewer (2), axis-constrained (3/4/5), or authored (else) orientation — replacing the blanket camera-plane alignment.

Script ids resolve from the Setup's DefaultScript (the retail source); the PesObjectId column is only a cross-check.