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>
This commit is contained in:
Erik 2026-04-28 22:47:11 +02:00
parent 1f82b7604e
commit ec1bbb4f43
28 changed files with 2444 additions and 780 deletions

View file

@ -200,21 +200,14 @@ public static class GfxObjMesh
// docs/research/2026-04-23-sky-retail-verbatim.md §6).
var translucency = TranslucencyKind.Opaque;
var luminosity = 0f;
// SurfTranslucency = the OPACITY multiplier the shader applies
// to fragment alpha. 1.0 = fully opaque (default, non-Translucent
// surfaces). For Translucent-flag surfaces, retail's
// D3DPolyRender::SetSurface at 0x59c7a6 (decomp lines 425255-
// 425260) computes curr_alpha = _ftol2(translucency × 255) and
// feeds that as vertex.color.alpha — so the dat's Translucency
// float is the OPACITY directly (NOT inverted). For rain
// (translucency=0.5) opacity is 0.5; for cloud surface
// 0x08000023 (translucency=0.25) opacity is 0.25 — that's why
// retail's clouds are dim and acdream's were 3× too bright
// before this fix (we used 1-translucency, inverting the
// semantic). ACViewer's TextureCache.cs:142 and WorldBuilder's
// ObjectMeshManager.cs:1115 also use 1-translucency and are
// both wrong by the same misread.
var surfTranslucency = 1.0f;
// SurfOpacity = (1 - Surface.Translucency) for Translucent
// surfaces, 1.0 otherwise. See
// TranslucencyKindExtensions.OpacityFromSurfaceTranslucency for
// the decomp citation (CMaterial::SetTranslucencySimple at
// 0x005396f0 writes material alpha as 1 - translucency).
var diffuse = 1f;
var surfOpacity = 1f;
var disableFog = false;
if (dats is not null)
{
var surface = dats.Get<Surface>(surfaceId);
@ -222,13 +215,16 @@ public static class GfxObjMesh
{
translucency = TranslucencyKindExtensions.FromSurfaceType(surface.Type);
luminosity = surface.Luminosity;
diffuse = surface.Diffuse;
// Apply the dat's Translucency value as opacity ONLY
// when the Translucent flag (0x10) is set on the
// Surface. Without this gate, surfaces with
// Translucency=0 (non-Translucent default) would
// render fully transparent.
if (((uint)surface.Type & (uint)DatReaderWriter.Enums.SurfaceType.Translucent) != 0)
surfTranslucency = surface.Translucency;
surfOpacity = TranslucencyKindExtensions.OpacityFromSurfaceTranslucency(
surface.Type,
surface.Translucency);
disableFog = TranslucencyKindExtensions.DisablesFixedFunctionFog(surface.Type);
}
}
@ -256,8 +252,10 @@ public static class GfxObjMesh
{
Translucency = translucency,
Luminosity = luminosity,
Diffuse = diffuse,
NeedsUvRepeat = needsUvRepeat,
SurfTranslucency = surfTranslucency,
SurfOpacity = surfOpacity,
DisableFog = disableFog,
});
}
return result;