feat(vfx): Phase C.1 — PES particle renderer + post-review fixes

Ports retail's ParticleEmitterInfo / Particle::Init / Particle::Update (0x005170d0..0x0051d400) and PhysicsScript runtime to a C# data-layer plus a Silk.NET billboard renderer. Sky-PES path is debug-only behind ACDREAM_ENABLE_SKY_PES because named-retail decomp confirms GameSky copies SkyObject.pes_id but never reads it (CreateDeletePhysicsObjects 0x005073c0, MakeObject 0x00506ee0, UseTime 0x005075b0). Post-review fixes folded into this commit: H1: AttachLocal (is_parent_local=1) follows live parent each frame. ParticleSystem.UpdateEmitterAnchor + ParticleHookSink.UpdateEntityAnchor let the owning subsystem refresh AnchorPos every tick — matches ParticleEmitter::UpdateParticles 0x0051d2d4 which re-reads the live parent frame when is_parent_local != 0. Drops the renderer-side cameraOffset hack that only worked when the parent was the camera. H3: Strip the long stale comment in GfxObjMesh.cs that contradicted the retail-faithful (1 - translucency) opacity formula. The code was right; the comment was a leftover from an earlier hypothesis and would have invited a wrong "fix". M1: SkyRenderer tracks textures whose wrap mode it set to ClampToEdge and restores them to Repeat at end-of-pass, so non-sky renderers that share the GL handle can't silently inherit clamped wrap state. M2: Post-scene Z-offset (-120m) only fires when the SkyObject is weather-flagged AND bit 0x08 is clear, matching retail GameSky::UpdatePosition 0x00506dd0. The old code applied it to every post-scene object — a no-op today (every Dereth post-scene entry happens to be weather-flagged) but a future post-scene-only sun rim would have been pushed below the camera. M4: ParticleSystem.EmitterDied event lets ParticleHookSink prune dead handles from the per-entity tracking dictionaries, fixing a slow leak where naturally-expired emitters' handles stayed in the ConcurrentBag forever during long sessions. M5: SkyPesEntityId moves the post-scene flag bit to 0x08000000 so it can't ever overlap the object-index range. Synthetic IDs stay in the reserved 0xFxxxxxxx space. New tests (ParticleSystemTests + ParticleHookSinkTests): - UpdateEmitterAnchor_AttachLocal_ParticlePositionFollowsLiveAnchor - UpdateEmitterAnchor_AttachLocalCleared_ParticleFrozenAtSpawnOrigin - EmitterDied_FiresOncePerHandle_AfterAllParticlesExpire - Birthrate_PerSec_EmitsOnePerTickWhenIntervalElapsed (retail-faithful single-emit-per-frame behavior) - UpdateEntityAnchor_WithAttachLocal_MovesParticleToLiveAnchor - EmitterDied_PrunesPerEntityHandleTracking dotnet build green, dotnet test green: 695 / 393 / 243 = 1331 passed (up from 1325). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-28 22:47:11 +02:00 · 2026-04-28 22:47:11 +02:00 · ec1bbb4f43
commit ec1bbb4f43
parent 1f82b7604e
28 changed files with 2444 additions and 780 deletions
--- a/docs/research/2026-04-28-pes-pseudocode.md
+++ b/docs/research/2026-04-28-pes-pseudocode.md
@ -0,0 +1,345 @@
+# Phase C.1 PES particle pseudocode
+
+Retail sources:
+
+- `docs/research/named-retail/acclient_2013_pseudo_c.txt`
+  - `ParticleEmitterInfo::{GetRandom*,InitEnd,ShouldEmitParticle,UnPack}`
+    at `0x005170d0..0x005179f0`
+  - `ParticleManager::{CreateParticleEmitter,DestroyParticleEmitter,StopParticleEmitter}`
+    at `0x0051b6c0..0x0051b7a0`
+  - `Particle::{Update,Init}` and `ParticleEmitter::{EmitParticle,UpdateParticles}`
+    at `0x0051b863..0x0051d400`
+  - `PhysicsScript::{UnPack}` at `0x005218b0`
+  - `CallPESHook::Execute`, `CreateParticleHook::Execute`,
+    `DestroyParticleHook::Execute`, `StopParticleHook::Execute` at
+    `0x00529eb0..0x0052a070`
+  - `GameSky::{Draw,CreateDeletePhysicsObjects}` at
+    `0x00506ff0..0x005075d0`
+- `docs/research/named-retail/acclient.h`
+  - `EmitterType`, `ParticleType`
+  - `ParticleEmitterInfo`, `Particle`, `ParticleEmitter`
+  - `CreateParticleHook`, `CreateBlockingParticleHook`,
+    `DestroyParticleHook`, `StopParticleHook`, `CallPESHook`
+  - `CelestialPosition` with `pes_id`
+- Cross-checks:
+  - `references/ACViewer/ACViewer/Physics/Particles/*`
+  - `references/ACE/Source/ACE.DatLoader/Entity/ParticleEmitterInfo.cs`
+  - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ParticleBatcher.cs`
+
+## ParticleEmitterInfo
+
+```text
+UnPack(reader):
+    read id/header
+    read unknown
+    read emitter_type
+    read particle_type
+    read gfxobj_id
+    read hw_gfxobj_id
+    read birthrate
+    read max_particles
+    read initial_particles
+    read total_particles
+    read total_seconds
+    read lifespan
+    read lifespan_rand
+    read offset_dir, min_offset, max_offset
+    read A, min_a, max_a
+    read B, min_b, max_b
+    read C, min_c, max_c
+    read start_scale, final_scale, scale_rand
+    read start_trans, final_trans, trans_rand
+    read is_parent_local
+
+InitEnd():
+    sorting_sphere.center = (0, 0, 0)
+    sorting_sphere.radius = max(max_offset, max_a * lifespan)
+
+RandomScale(base):
+    value = base + RollDice(-1, 1) * scale_rand
+    return clamp(value, 0.1, 10.0)
+
+RandomTrans(base):
+    value = base + RollDice(-1, 1) * trans_rand
+    return clamp(value, 0.0, 1.0)
+
+RandomLifespan():
+    value = lifespan + RollDice(-1, 1) * lifespan_rand
+    return max(value, 0.0)
+
+RandomVector(dir, min, max):
+    return dir * Random(min, max)
+
+RandomOffset():
+    v = random vector in [-1, 1]^3
+    v = v - project(v, offset_dir)
+    if length(v) is near zero:
+        v = perpendicular fallback
+    v = normalize(v)
+    return v * Random(min_offset, max_offset)
+
+ShouldEmitParticle(emitter):
+    if total_particles != 0 and emitter.total_emitted >= total_particles:
+        return false
+    if emitter.num_particles >= max_particles:
+        return false
+    if emitter_type == BirthratePerSec:
+        return Timer.cur_time - emitter.last_emit_time > birthrate
+    if emitter_type == BirthratePerMeter:
+        delta = emitter.last_emit_offset - emitter.current_parent_offset
+        return dot(delta, delta) > birthrate * birthrate
+    return false
+```
+
+Notes:
+
+- Retail stores `birthrate` as seconds between emissions for
+  `BirthratePerSec`, not particles per second.
+- Retail clamps start/final scale to `[0.1, 10]` and translucency to
+  `[0, 1]`.
+- The named decomp shows final scale/trans add their own base values.
+  ACE/ACViewer have a few copy-paste mistakes in these helpers; the decomp
+  wins.
+
+## ParticleManager and emitter lifetime
+
+```text
+CreateParticleEmitter(parent, emitter_info_id, part_index, offset, requested_id):
+    if requested_id != 0:
+        remove existing emitter with requested_id
+    info = Dat.Get(ParticleEmitterInfo, emitter_info_id)
+    emitter = makeParticleEmitter()
+    emitter.SetInfo(info)
+    emitter.SetParenting(parent, part_index, offset)
+    emitter.InitEnd()
+    emitter.id = requested_id if requested_id != 0 else next_emitter_id++
+    particle_table.add(emitter.id, emitter)
+    return emitter.id
+
+DestroyParticleEmitter(id):
+    remove emitter id from particle_table
+
+StopParticleEmitter(id):
+    emitter.stopped = true
+
+UpdateParticles():
+    for each emitter:
+        keep = emitter.UpdateParticles()
+        if !keep:
+            remove emitter
+```
+
+`ParticleEmitter::EmitParticle` finds a free/recyclable slot, samples all
+random fields from the `ParticleEmitterInfo`, initializes a `Particle`, adds
+the particle part, and records `total_emitted`, `last_emit_time`, and
+`last_emit_offset`.
+
+`ParticleEmitter::UpdateParticles`:
+
+```text
+if drawable/parent is valid:
+    for each live particle:
+        parent_frame = parent-local ? current parent frame : particle.start_frame
+        particle.Update(parent_frame, now, persistent)
+        if particle.lifetime >= particle.lifespan:
+            kill particle
+
+    while !stopped and info.ShouldEmitParticle(this):
+        EmitParticle()
+
+    if total_seconds != 0 and now - creation_time > total_seconds:
+        stopped = true
+    if total_particles != 0 and total_emitted >= total_particles:
+        stopped = true
+
+return num_particles != 0 || !stopped
+```
+
+## Particle integrators
+
+Every particle computes position from age/lifetime, not by accumulating
+Euler steps. `parent.origin` below is the parent frame origin chosen by
+`is_parent_local`.
+
+```text
+age = now - birthtime
+
+Still:
+    pos = parent.origin + offset
+
+LocalVelocity, GlobalVelocity:
+    pos = parent.origin + offset + age * A
+
+ParabolicLVGA, ParabolicLVLA, ParabolicGVGA:
+    pos = parent.origin + offset + age * A + 0.5 * age^2 * B
+
+ParabolicLVGAGR, ParabolicLVLALR, ParabolicGVGAGR:
+    frame = parent
+    frame.origin += offset + age * A + 0.5 * age^2 * B
+    frame.rotate_by(age * C)
+    pos = frame.origin
+
+Swarm:
+    pos = parent.origin + offset + age * A
+    pos.x += cos(age * B.x) * C.x
+    pos.y += sin(age * B.y) * C.y
+    pos.z += cos(age * B.z) * C.z
+
+Explode:
+    pos.x = parent.origin.x + offset.x + (age * B.x + C.x * A.x) * age
+    pos.y = parent.origin.y + offset.y + (age * B.y + C.y * A.x) * age
+    pos.z = parent.origin.z + offset.z + (age * B.z + C.z * A.x + A.z) * age
+
+Implode:
+    pos = parent.origin + offset + cos(A.x * age) * C + age^2 * B
+```
+
+`Particle::Init` resolves vector spaces once at spawn:
+
+```text
+offset = transform_local_vector(random_offset, start_frame)
+
+LocalVelocity, ParabolicLVGA:
+    A = local_to_global(A)
+
+ParabolicLVLA:
+    A = local_to_global(A)
+    B = local_to_global(B)
+
+ParabolicLVGAGR:
+    A = local_to_global(A)
+    C = C
+
+Swarm:
+    A = local_to_global(A)
+
+Explode:
+    A = A
+    B = B
+    C = normalized random direction scaled by the local C axes
+
+Implode:
+    A = A
+    B = B
+    offset *= C component-wise
+    C = offset
+
+ParabolicLVLALR:
+    A = local_to_global(A)
+    B = local_to_global(B)
+    C = local_to_global(C)
+
+ParabolicGVGA, GlobalVelocity:
+    A/B/C remain global as applicable
+
+ParabolicGVGAGR:
+    A and B remain global
+    C = C
+```
+
+After motion:
+
+```text
+t = clamp(age / lifespan, 0, 1)
+scale = lerp(start_scale, final_scale, t)
+trans = lerp(start_trans, final_trans, t)
+opacity = 1 - trans
+```
+
+`StartTrans` / `FinalTrans` are transparency values, not source alpha.
+Retail sends the interpolated value to `PhysicsPart::SetTranslucency`; the
+render path uses its complement as opacity. WorldBuilder's particle renderer
+cross-check does the same (`opacity = 1 - currentTrans`).
+
+## PhysicsScript and hooks
+
+`PhysicsScript::UnPack` reads ordered `(start_time, hook)` entries and sorts
+them by start time. The runner keeps active script instances keyed by
+`(script_id, entity_id)` and fires all hooks whose `start_time <= elapsed`.
+
+Hook execution:
+
+```text
+CreateParticleHook:
+    parent.create_particle_emitter(emitter_info_id, part_index, offset, emitter_id)
+
+CreateBlockingParticleHook:
+    same particle creation path, plus sequencer blocking semantics
+
+DestroyParticleHook:
+    parent.destroy_particle_emitter(emitter_id)
+
+StopParticleHook:
+    parent.stop_particle_emitter(emitter_id)
+
+CallPESHook:
+    parent.CallPES(pes_id, pause)
+```
+
+The C.1 implementation keeps hook dispatch in Core and renders the resulting
+particles in App. Nested `CallPESHook` stays in `PhysicsScriptRunner`, while
+`ParticleHookSink` converts create/destroy/stop hooks into runtime emitter
+handles.
+
+## Sky integration
+
+`CelestialPosition` has both `gfx_id` and `pes_id`. Retail sky object
+creation copies `properties` and draws two sky cells. A named-retail recheck
+on 2026-04-28 corrected the original C.1 assumption:
+
+```text
+SkyDesc::GetSky (0x00501ec0):
+    copy SkyObject.gfx_id into CelestialPosition.gfx_id
+    copy SkyObject.default_pes_object into CelestialPosition.pes_id
+    copy properties / rotate / arc angle / tex velocity
+
+GameSky.CreateDeletePhysicsObjects (0x005073c0):
+    for each visible CelestialPosition:
+        post_scene = (properties & 0x01) != 0
+        make/update sky gfx object from gfx_id in before/after cell
+        do not read pes_id
+
+GameSky.MakeObject (0x00506ee0):
+    CPhysicsObj::makeObject(gfx_id, 0, 0)
+    set texture velocity
+
+GameSky.UseTime (0x005075b0):
+    CreateDeletePhysicsObjects()
+    CalcFrame()
+    set_frame / luminosity / diffusion / translucency
+    do not read pes_id
+
+GameSky.Draw(post_scene):
+    if post_scene == false:
+        draw before_sky_cell
+    else:
+        draw after_sky_cell
+```
+
+The sky renderer must preserve the existing `0x01` pre/post split for sky
+meshes. `SkyObject.default_pes_object` is parsed and retained for diagnostics,
+but it is not a retail render-path particle source. In acdream the experimental
+sky-PES path is therefore gated behind `ACDREAM_ENABLE_SKY_PES=1` and disabled
+for normal visual comparison.
+
+## GL rendering
+
+WorldBuilder's `ParticleBatcher` confirms the GL-side policy:
+
+```text
+collect live billboard instances
+sort back-to-front by camera distance for alpha blending
+depth test enabled
+depth writes disabled
+cull disabled
+blend SrcAlpha/OneMinusSrcAlpha for alpha
+blend SrcAlpha/One for additive
+stream dynamic instance VBO
+draw instanced unit quads
+```
+
+C.1 keeps that policy and splits draw calls by particle render pass:
+
+- pre-scene sky particles after the pre-scene sky meshes
+- scene particles after opaque world/static objects
+- post-scene sky particles after post-scene sky/weather meshes
--- a/docs/research/2026-04-28-sky-cloud-material-trace.md
+++ b/docs/research/2026-04-28-sky-cloud-material-trace.md
@ -0,0 +1,97 @@
+# 2026-04-28 Sky Cloud Material Trace
+
+Context: Phase C.1 originally treated the Rainy/Cloudy sky visual as a
+SkyObject PES problem. Retail named-decomp and dat inspection disprove that
+for the broad cloud/ray layer.
+
+## Retail Trace
+
+- `LScape::draw` (`0x00506330`) calls `GameSky::Draw(0)` before terrain and
+  `GameSky::Draw(1)` after terrain.
+- `SkyDesc::GetSky` copies `pes_id`, but `GameSky::CreateDeletePhysicsObjects`
+  compares/replaces only `gfx_id` and calls `GameSky::MakeObject(gfx_id, ...)`.
+  The sky object PES id is not part of retail `GameSky` rendering.
+- `GameSky::UseTime` applies keyframe replace fields to instantiated sky
+  objects:
+  - `0x005076e1`: `CPhysicsObj::SetLuminosity(luminosity * 0.01)`
+  - `0x00507715`: `CPhysicsObj::SetDiffusion(max_bright * 0.01)`
+  - `0x00507747`: `CPhysicsObj::SetTranslucency(transparent * 0.01)`
+- `CMaterial::SetTranslucencySimple` (`0x005396f0`) writes material alpha as
+  `1 - translucency`.
+- `CMaterial::SetDiffuseSimple` (`0x00539750`) writes material diffuse RGB.
+  Therefore `SkyObjectReplace.MaxBright` is diffuse, not an emissive cap.
+- `D3DPolyRender::SetSurface` (`0x0059c4d0`) disables fixed-function fog alpha
+  whenever the raw `SurfaceType.Additive` bit is set (`0x0059c882`), even when
+  the earlier `Translucent + ClipMap` branch forces normal alpha blending.
+
+## Dat Trace
+
+The broad Rainy/Cloudy layer is `GfxObj 0x01004C35`, not one of the tiny
+`0x020xxxxx` setup anchors:
+
+- `0x01004C35`: huge sky mesh, bbox roughly `20175 x 20175 x 1180`, UVs tile
+  across the sheet.
+- Surface `0x08000023`: `Base1ClipMap | Translucent | Alpha | Additive`
+  (`0x00010114`), `Translucency=0.25`, `Luminosity=0`, `Diffuse=1`.
+- Texture `0x060037AF`: 256x256 A8R8G8B8 cloud/ray texture.
+
+The setup ids observed in Rainy groups (`0x02000588`, `0x02000589`,
+`0x02000BA6`, `0x02000714`) are one-part dummy anchors with tiny `0x010001EC`
+geometry and default scripts/PES for sounds/flashes. They are not the broad
+cloud layer.
+
+## Port Consequences
+
+- Keep per-SkyObject PES rendering debug-only until another retail path proves
+  it is used.
+- Render `0x08000023` as final alpha blend because retail's translucent/clipmap
+  branch overrides the raw additive blend.
+- Still disable sky fog for that surface because retail keys fog-alpha disable
+  off the raw `Additive` bit.
+- Route `MaxBright` to diffuse (`uDiffuseFactor`) and `Luminosity` to emissive.
+- Use a final opacity multiplier for material/surface transparency before the
+  fragment alpha write; dynamic keyframe transparency remains `1 - value`.
+
+## WorldBuilder Cross-Check
+
+Cloned upstream `https://github.com/Chorizite/WorldBuilder.git` at commit
+`167788be6fce65f5ebe79eef07a0b7d28bd7aa81`. Its
+`Chorizite.OpenGLSDLBackend/Lib/SkyboxRenderManager.cs` renders sky objects
+camera-centered with depth off, but it is not a faithful retail oracle for sky
+tint: `GameScene.cs` has the skybox render call commented out, the manager
+always selects `DayGroups[0]`, and it uploads `SunlightColor = Vector3.Zero`
+/ `AmbientColor = Vector3.One` for sky. `RegionInfo.cs` interpolates
+DayGroup[0] lighting for terrain/world objects, not the active retail
+DayGroup/weather sky.
+
+That explains why WorldBuilder cannot answer the missing green/purple Rainy
+sky tint directly. The actionable lesson is narrower: do not fog-paint the
+raw-additive cloud sheet itself. In acdream, non-additive sky layers now receive
+the keyframe fog tint so the broad background wash appears behind clouds, while
+surfaces with the raw Additive bit (notably `0x08000023`) keep fixed-function
+fog disabled and preserve the pink cloud/ray detail.
+
+WorldBuilder's regular object path does collect `Setup.DefaultScript`
+particle hooks (`ObjectMeshManager.CollectEmittersFromScript`) and instantiates
+them via `ObjectRenderManagerBase`, but its skybox manager does not use that
+setup/particle path for SkyObjects. Dat inspection also showed the canonical
+Rainy default script target `0x3300042C` is a sound-loop chain (`SoundTweaked`
+ `CallPES`), not the broad green tint or cloud ray layer.
+
+Additional renderer lessons from upstream WorldBuilder:
+
+- Particle blend is material-derived. `ParticleEmitterInfo` does not carry an
+  additive flag; WorldBuilder reads `ObjectRenderData.Batches[0].IsAdditive`
+  from the particle GfxObj surface. acdream now leaves DAT emitters non-additive
+  by default and resolves particle blend from the selected particle surface.
+- Particles must be globally sorted back-to-front before drawing. Sorting only
+  inside per-texture dictionaries can reorder translucent particles whenever
+  multiple textures/blend states are active.
+- Particle quads come from the authored particle GfxObj bounds. Degenerate
+  extents fall back to `1.0`, and point-sprite degrade mode applies a `0.9`
+  base scale.
+- Texture decoding must try highres `RenderSurface` records after portal lookup
+  and must zero alpha for black pixels on compressed clipmap textures.
+- WorldBuilder tracks UV wrap and cull mode per object batch. acdream's sky path
+  already uses authored UV wrap, but shared object rendering still needs the
+  same metadata carried through a later C.4 pass.