Erik ec1bbb4f43 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

5.1 KiB

Raw Permalink Blame History

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.

5.1 KiB Raw Permalink Blame History