docs(issues): #28 root-caused (PES particles), #29 filed (residual cloud gap)

Updated #28 (aurora effect) from "unknown root cause" to "PES
particles attached via CelestialPosition.pes_id". Includes the
verbatim retail header struct, the StarsProbe-confirmed list of
PES-bearing entries in Dereth Rainy DG3 (notably PES 0x3300042C
active 0.27-0.91, which is the user's Warmtide screenshot), the
implementation outline, and decomp pointers to
CPhysicsObj::InitPartArrayObject + CPartArray::CreateSetup.

Filed #29 for the residual cloud-density gap that remained after
this session's Translucent-override fix (commit 375065b) and Setup
wiring (commit 646ccca). Two follow-up hypotheses captured —
likely rolls into #28 once PES rendering lands.
This commit is contained in:
Erik 2026-04-27 23:24:17 +02:00
parent 646ccca85e
commit 0c82d2c9e9

View file

@ -279,15 +279,73 @@ missing is the plugin-API surface.
**Filed:** 2026-04-26
**Component:** sky / vfx
**Description:** Retail occasionally renders an aurora-borealis-style "northern lights" effect in the sky during certain weather/time conditions. acdream renders no aurora at all.
**Description:** Retail renders a dynamic colored "light play" effect in the sky during certain Rainy/Cloudy DayGroup time windows. The user describes it as aurora-borealis-style. acdream renders no comparable effect.
**Root cause / status:** Unknown — the mechanism hasn't been investigated. Aurora is NOT in the visible SkyObject lists (`tools/StarsProbe` shows the standard 7-object Sunny/Clear/Cloudy DayGroup composition, with extra weather objects in Rainy groups). Hypotheses: (a) it's a special PES on a low-probability DayGroup not yet enumerated; (b) it's a separate shader path not driven by `Region.SkyInfo`; (c) it requires a specific weather/time combo we haven't triggered; (d) it's an entirely separate `EnvironChangeType` system we don't decode.
**Root cause:** PES (Particle Effect Schedule) particles attached to SkyObjects via the `CelestialPosition.pes_id` field. Retail header at `acclient.h` line 35451 (verbatim):
**Files:** Unknown.
```c
struct CelestialPosition {
IDClass<...> gfx_id;
IDClass<...> pes_id; // ← particle scheduler ID
float heading; float rotation;
Vector3 tex_velocity;
float transparent; float luminosity; float max_bright;
unsigned int properties;
};
```
**Research:** None yet. Probably needs a retail-decomp grep for "aurora", "northern", a 360° survey of DayGroup PES contents, and possibly a deepdive into the `LScape::weather_enabled` and `EnvironChange*` paths.
`StarsProbe` confirmed Dereth Rainy DayGroup 3 carries multiple PES-bearing entries (verified 2026-04-27). Sample for the user's observed Warmtide-Rainy state:
**Acceptance:** When retail shows an aurora at a specific in-game time / weather, acdream shows a visually-comparable effect at the same time.
| OI | Gfx | **PES** | Active window | Notes |
|----|-----|---------|----|----|
| 5 | 0x02000714 | 0x330007DB | always | low-rate background |
| 7 | 0x02000BA6 | 0x33000453 | 0.030.19 | early morning |
| 17 | 0x02000589 | **0x3300042C** | **0.270.91** | **active during user's screenshot** |
acdream's geometry half is now wired (commit landing 2026-04-27 — `EnsureSetupUploaded` walks `Setup.Parts` for `0x020xxx` IDs). The dynamic visual half — emitting and animating the PES particles — is unimplemented and provides the actual aurora look. Phase E.3 already has data-only PES support per memory crib `project_session_2026_04_18.md`; this issue requires the runtime + visual half.
**Implementation outline:**
1. PES dat decode (already partially in `AcDream.Core.World.PesData` per Phase E.3).
2. PES emitter runtime — schedule, spawn, advect, color-cycle, expire each particle.
3. `SkyRenderer` integration — when `MakeObject` sees `pes_id != 0`, spawn the PES at the SkyObject's celestial position.
4. PES vertex-sprite renderer — billboarded textured quads with additive blending and color cycling. Probably reuses the future general-purpose particle renderer (issue #L? — TBD).
**Decomp pointers:**
- `CPhysicsObj::InitPartArrayObject` decomp ~280484 — dispatches type 7 to Setup loader.
- `CPartArray::CreateSetup` decomp ~287490 — Setup → Parts → optional PES wiring.
**Files:**
- `src/AcDream.Core/World/SkyDescLoader.cs``SkyObjectData` needs to carry `PesObjectId` (currently dropped on the floor).
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — needs a particle-emission step alongside the per-SkyObject mesh draw.
**Acceptance:** When retail shows aurora-style light play at a specific in-game time / weather, acdream shows a visually-comparable effect at the same time.
---
## #29 — Cloud surface 0x08000023 still appears thinner than retail despite blend-mode + Setup fixes
**Status:** OPEN
**Severity:** LOW (aesthetic feature-parity)
**Filed:** 2026-04-27
**Component:** sky / clouds
**Description:** User screenshot comparison showed acdream's clouds let too much sun through; retail's are denser and have a purpleish tint. Two follow-up fixes landed without visible improvement:
1. `TranslucencyKindExtensions.FromSurfaceType` now applies retail's Translucent-override at `D3DPolyRender::SetSurface` (decomp 425246-425260) — surface `0x08000023` (Type=`0x10114` = `B1ClipMap | Translucent | Alpha | Additive`) is now correctly classified as `AlphaBlend` instead of `Additive`.
2. `SkyRenderer.EnsureSetupUploaded` now loads `0x020xxxxx` Setup IDs (e.g. `0x02000588`, `0x02000589`, `0x02000714`, `0x02000BA6`) which were silently dropped. Setup parts are flattened via `SetupMesh.Flatten` and uploaded with their per-part transform baked into vertex positions.
Despite both being decomp-correct fixes, the user reports no observable visual change in dual-client comparison. Two follow-up hypotheses:
- The Setup objects are tiny placeholder meshes (one `0x010001EC` part each) that exist mainly to anchor a PES emitter — the cloud "density" / "purple sheen" the user perceives is entirely the PES particle layer, not the static mesh.
- The cloud surface might still be rendering correctly per its dat data, and what looks "thicker" in retail is the additional aurora-like PES sheen overlaid on top.
If hypothesis (a) is correct, this issue effectively rolls into **#28** — the PES rendering work would resolve both.
**Files:**
- `src/AcDream.Core/Meshing/TranslucencyKind.cs` — Translucent override
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs``EnsureSetupUploaded`
**Acceptance:** Cloud sheets look as dense/purple as retail in dual-client side-by-side. May require #28 (PES) to land first.
---