acdream/docs/plans/2026-04-30-sky-pes-port.md

# Plan — Sky-PES dispatch port (Issue #36)

**Filed:** 2026-04-30 from a live cdb trace of retail acclient.exe.
**Owner:** next session.
**Closes:** #28 (aurora), #29 (cloud density), partially #2 (lightning).

## What we know (from the live trace, 24,576 GameSky::Draw frames)

Retail's sky-PES dispatch chain runs as follows. All counts are from
the cdb trace summarized in `memory/project_retail_debugger.md`:

```
GameSky::Draw                       = 24,576  (60Hz render rate)
GameSky::UseTime                    = 12,288  (30Hz, MinQuantum gate)
GameSky::CreateDeletePhysicsObjects = 12,288  (30Hz)
CPhysicsObj::CallPES                =    372  (~150/min)
CallPESHook::Execute                =    372  (1:1 with CallPES)
CreateParticleHook::Execute         =     62  (15 initial + 47 burst)
CPhysicsObj::create_particle_emitter =    62  (matches CreateParticleHook)
```

Three concrete findings:

1. **Persistent particle emitters on celestial / sky objects.** 15 are
   created at cell load. More are spawned dynamically on region /
   weather / time-of-day transitions (the trace caught a +47 burst on
   one such transition).

2. **Periodic PES dispatch drives existing emitters.**
   `CallPESHook::Execute` runs script-scheduled actions which call
   `CPhysicsObj::CallPES` 1:1. ~150 dispatches/min on average.

3. **Earlier research said "GameSky doesn't read pes_id" — true but
   misleading.** GameSky doesn't read it directly; the script-hook
   system does. `CelestialPosition.pes_id` (struct offset +0x004) is
   populated by `SkyDesc::GetSky` and consumed downstream by
   `CallPESHook` / `CreateParticleHook` invocations scheduled from
   region/weather handlers.

## Decomp anchors

All addresses verified live against `refs/acclient.pdb`:

| Function | Address | Role |
|---|---|---|
| `CallPESHook::Execute` | `0x00526e20` | Script-hook action that fires CallPES |
| `CreateParticleHook::Execute` | `0x00526ec0` | Particle-creation hook |
| `CPhysicsObj::CallPES` | `0x00511af0` | Top-level PES dispatch |
| `CPhysicsObj::CallPESInternal` | `0x00511ac0` | Inner dispatch (never fires alone in trace — likely inlined) |
| `CPhysicsObj::create_particle_emitter` | `0x0050f360` | Creates a new emitter |
| `CPhysicsObj::create_blocking_particle_emitter` | `0x0050f3b0` | Creates a blocking emitter |
| `CPhysicsObj::stop_particle_emitter` | `0x0050f420` | |
| `CPhysicsObj::destroy_particle_emitter` | `0x0050f400` | |
| `CPhysicsObj::ShouldDrawParticles` | `0x0050fe60` | |
| `CPhysicsObj::makeParticleObject` | `0x00512640` | |
| `CPartArray::CreateParticle` | `0x005194f0` | |
| `CSetup::makeParticleSetup` | `0x005201f0` | |
| `LongNIHash<ParticleEmitter>::add` | `0x005198c0` | Emitter registry insertion |
| `GameSky::CreateDeletePhysicsObjects` | `0x005073c0` | Already partially decoded; entry point for sky-object lifecycle |
| `GameSky::UseTime` | `0x005075b0` | Per-frame sky update (30Hz) |
| `GameSky::Draw` | `0x00506ff0` | Sky render (60Hz) |
| `SkyDesc::GetSky` | `0x00501ec0` | Populates `CelestialPosition.pes_id` |

`CelestialPosition` struct layout:
```
+0x000 gfx_id           : 4 bytes
+0x004 pes_id           : 4 bytes  ← THIS is what gets PES-driven
+0x008 heading          : float
+0x00c rotation         : float
+0x010 tex_velocity     : Vector3
+0x01c transparent      : float
+0x020 luminosity       : float
+0x024 max_bright       : float
+0x028 properties       : 4 bytes
```

## Phase plan

### Phase M.1 — Decomp dive (no code changes)

Read these functions in order. Save findings to
`docs/research/2026-04-30-sky-pes-pseudocode.md`:

1. **`CallPESHook::Execute`** at `0x00526e20`. What state does it
   read? What does it call? Answer: probably "look up the target
   CPhysicsObj by some ID, call CallPES on it." Confirm.

2. **`CPhysicsObj::CallPES`** at `0x00511af0`. What does it do?
   Probably: "look up or load the PES file referenced by `pes_id`,
   start running its script timeline." Find the script-evaluation
   loop and where it dispatches `CallPESHook` events.

3. **`CreateParticleHook::Execute`** at `0x00526ec0`. When this hook
   fires, what does it create? What CPhysicsObj does it attach the
   emitter to? Probably calls `CPhysicsObj::create_particle_emitter`.

4. **`CPhysicsObj::create_particle_emitter`** at `0x0050f360`. What
   does it instantiate? What goes into the `LongNIHash<ParticleEmitter>`?

5. **`GameSky::CreateDeletePhysicsObjects`** at `0x005073c0`. The
   prior research said this doesn't read pes_id. Confirm — but ALSO
   check: does it set up the script-hook timeline somewhere? Or does
   that happen in a separate caller?

6. **The dynamic-emitter-spawn trigger.** The trace caught a +47
   burst — find what fires CreateParticleHook on region / weather /
   time-of-day transitions. Likely candidates:
   - `LScape` weather handler
   - `CDayCycle` / `CWorldFog` region handler
   - Cell-load or cell-cross handler

### Phase M.2 — Verify with detailed cdb trace (one focused session)

After M.1 reveals the wiring, attach cdb to retail and capture:

- `this` pointer + `pes_id` arg on every `CPhysicsObj::CallPES`
- GfxObj being attached on every `create_particle_emitter`
- Stack walk at `CallPESHook::Execute` to confirm the caller chain
- Watch for the dynamic +N burst — what global state changed at
  that frame?

The data should match the M.1 decomp predictions. If it diverges,
the decomp interpretation needs another pass.

### Phase M.3 — Implementation (acdream port)

1. **Persistent emitter creation at cell load.** When a sky-bearing
   landblock loads, walk SkyDesc / CelestialPosition entries; for
   each entry with non-zero `pes_id`, instantiate a ParticleEmitter
   on the corresponding sky CPhysicsObj.

2. **Dynamic emitter spawn on transitions.** Hook into our region /
   weather / day-cycle change events; replicate retail's dispatch.

3. **PES script-timeline driver.** Port the scheduler that fires
   `CallPESHook` events at script-defined moments. May reuse
   `references/holtburger` if there's a Rust port. If not, port from
   decomp directly.

4. **Particle-system rendering wire-up.** acdream already has a
   particle system (R3 era). Verify it can accept emitter spawns
   from this path. If so, just wire. If not, identify the gap.

5. **Surface 0x08000023 / cloud GfxObjs.** Once dynamic emitters spawn,
   #29's "clouds too thin" should resolve naturally.

### Phase M.4 — Live verification

1. Retail + acdream side-by-side. Aurora moment (Rainy DayGroup,
   dusk/dawn). Compare visual.
2. Cloudy moment — clouds should look as dense as retail.
3. Storm moment — lightning flashes (covers part of #2).
4. Run another cdb trace; counts should match retail's counts within
   ~10%.

## Acceptance

- Aurora visible in acdream at the same in-game moments retail shows it.
- Cloud sheets look as dense / purple as retail.
- Storm flash visible during Rainy storm windows (part of #2).
- New cdb trace shows similar PES dispatch rate (~150/min) and similar
  emitter spawn pattern (initial population + transition bursts).
- Closes #28, #29. Updates #2 with the storm-flash story.

## What this doesn't fix

- **#4 horizon-glow** is a separate issue (fog parameters, not particles).
  Tackle that in a different session — different code path, different
  cdb trace.
- **Lightning timing / thunder** (the audio half of #2) is separate;
  needs the audio system wired.

## How to start

The next session, having read CLAUDE.md (auto-loaded) and
`memory/project_retail_debugger.md` (auto-loaded), should:

1. Read this plan top to bottom (~5 minutes).
2. Begin Phase M.1 decomp dive — no code yet, just understand the
   wiring. Save findings to a research doc.
3. After M.1 lands, decide whether M.2 (verify with cdb) is needed
   before M.3 (implement). Often the decomp alone is enough; M.2 is
   for resolving ambiguity.

The cdb tooling is ready (CLAUDE.md "Retail debugger toolchain").
The user can launch retail with `C:\Turbine\Asheron's Call\acclient.exe`
on demand.