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>

tests/AcDream.Core.Tests/Vfx/ParticleSystemTests.cs

@@ -34,6 +34,43 @@ public sealed class ParticleSystemTests
         };
     }
 
+    private static EmitterDesc MakeInitialParticleDesc(
+        ParticleType type,
+        Vector3 a,
+        Vector3 b,
+        Vector3 c)
+    {
+        return new EmitterDesc
+        {
+            DatId = 0x3200AA01u,
+            Type = type,
+            MaxParticles = 1,
+            InitialParticles = 1,
+            LifetimeMin = 10f,
+            LifetimeMax = 10f,
+            Lifespan = 10f,
+            LifespanRand = 0f,
+            OffsetDir = Vector3.UnitZ,
+            MinOffset = 0f,
+            MaxOffset = 0f,
+            InitialVelocity = Vector3.Zero,
+            Gravity = Vector3.Zero,
+            A = a,
+            MinA = 1f,
+            MaxA = 1f,
+            B = b,
+            MinB = 1f,
+            MaxB = 1f,
+            C = c,
+            MinC = 1f,
+            MaxC = 1f,
+            StartSize = 0.5f,
+            EndSize = 0.5f,
+            StartAlpha = 1f,
+            EndAlpha = 1f,
+        };
+    }
+
     [Fact]
     public void SpawnEmitter_ReturnsPositiveHandle_AndTracksEmitter()
     {
@@ -60,7 +97,7 @@ public sealed class ParticleSystemTests
     public void Tick_ParticlesDieAtLifetime()
     {
         var sys = MakeSystem();
-        sys.SpawnEmitter(MakeDesc(emitRate: 20f, lifetime: 0.5f, maxParticles: 100), Vector3.Zero);
+        int handle = sys.SpawnEmitter(MakeDesc(emitRate: 20f, lifetime: 0.5f, maxParticles: 100), Vector3.Zero);
 
         // Use many short ticks so we can observe the death curve.
         // At 20/sec with 0.5s lifetime and a stable emission pool, the
@@ -69,11 +106,10 @@ public sealed class ParticleSystemTests
         int steadyState = sys.ActiveParticleCount;
         Assert.InRange(steadyState, 7, 13);
 
-        // Now advance further with no spawns (stop emitter); all should die.
-        sys.SpawnEmitter(MakeDesc(emitRate: 0f, maxParticles: 1), Vector3.Zero); // noop
-        // Continue time; particles age past lifetime.
+        // Now advance further with no new spawns; all should die.
+        sys.StopEmitter(handle, fadeOut: true);
         for (int i = 0; i < 30; i++) sys.Tick(0.05f);   // 1.5s more than lifetime
-        Assert.True(sys.ActiveParticleCount <= steadyState);
+        Assert.Equal(0, sys.ActiveParticleCount);
     }
 
     [Fact]
@@ -100,7 +136,7 @@ public sealed class ParticleSystemTests
         var desc = new EmitterDesc
         {
             DatId = 0x32000002u,
-            Type = ParticleType.Parabolic,
+            Type = ParticleType.ParabolicLVGA,
             EmitRate = 10f,
             MaxParticles = 100,
             LifetimeMin = 2f, LifetimeMax = 2f,
@@ -192,7 +228,7 @@ public sealed class ParticleSystemTests
     }
 
     [Fact]
-    public void MaxParticles_CapEnforced_OverwriteOldest()
+    public void MaxParticles_CapEnforced()
     {
         var sys = MakeSystem();
         // Low cap, high rate, long life → rapidly hit cap.
@@ -219,4 +255,239 @@ public sealed class ParticleSystemTests
         reg.Register(desc);
         Assert.Same(desc, reg.Get(0x32001234u));
     }
+
+    [Fact]
+    public void LocalVelocity_TransformsABySpawnRotation()
+    {
+        var sys = MakeSystem();
+        var desc = MakeInitialParticleDesc(
+            ParticleType.LocalVelocity,
+            Vector3.UnitX,
+            Vector3.Zero,
+            Vector3.Zero);
+
+        sys.SpawnEmitter(desc, Vector3.Zero, Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI * 0.5f));
+        sys.Tick(1f);
+
+        var live = sys.EnumerateLive().Single();
+        var pos = live.Emitter.Particles[live.Index].Position;
+        Assert.InRange(pos.X, -0.0001f, 0.0001f);
+        Assert.InRange(pos.Y, 0.9999f, 1.0001f);
+    }
+
+    [Fact]
+    public void GlobalVelocity_DoesNotTransformABySpawnRotation()
+    {
+        var sys = MakeSystem();
+        var desc = MakeInitialParticleDesc(
+            ParticleType.GlobalVelocity,
+            Vector3.UnitX,
+            Vector3.Zero,
+            Vector3.Zero);
+
+        sys.SpawnEmitter(desc, Vector3.Zero, Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI * 0.5f));
+        sys.Tick(1f);
+
+        var live = sys.EnumerateLive().Single();
+        var pos = live.Emitter.Particles[live.Index].Position;
+        Assert.InRange(pos.X, 0.9999f, 1.0001f);
+        Assert.InRange(pos.Y, -0.0001f, 0.0001f);
+    }
+
+    [Fact]
+    public void ParabolicLVLA_TransformsLocalAcceleration()
+    {
+        var sys = MakeSystem();
+        var desc = MakeInitialParticleDesc(
+            ParticleType.ParabolicLVLA,
+            Vector3.Zero,
+            Vector3.UnitX,
+            Vector3.Zero);
+
+        sys.SpawnEmitter(desc, Vector3.Zero, Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI * 0.5f));
+        sys.Tick(1f);
+
+        var live = sys.EnumerateLive().Single();
+        var pos = live.Emitter.Particles[live.Index].Position;
+        Assert.InRange(pos.X, -0.0001f, 0.0001f);
+        Assert.InRange(pos.Y, 0.4999f, 0.5001f);
+    }
+
+    [Fact]
+    public void ParabolicLVGA_KeepsGlobalAcceleration()
+    {
+        var sys = MakeSystem();
+        var desc = MakeInitialParticleDesc(
+            ParticleType.ParabolicLVGA,
+            Vector3.Zero,
+            Vector3.UnitX,
+            Vector3.Zero);
+
+        sys.SpawnEmitter(desc, Vector3.Zero, Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI * 0.5f));
+        sys.Tick(1f);
+
+        var live = sys.EnumerateLive().Single();
+        var pos = live.Emitter.Particles[live.Index].Position;
+        Assert.InRange(pos.X, 0.4999f, 0.5001f);
+        Assert.InRange(pos.Y, -0.0001f, 0.0001f);
+    }
+
+    [Fact]
+    public void EmitterDescRegistry_FromDat_PreservesRetailEnumValuesAndRates()
+    {
+        var dat = new DatReaderWriter.DBObjs.ParticleEmitter
+        {
+            EmitterType = DatReaderWriter.Enums.EmitterType.BirthratePerSec,
+            ParticleType = DatReaderWriter.Enums.ParticleType.Swarm,
+            GfxObjId = 0x01000001u,
+            HwGfxObjId = 0x01000002u,
+            Birthrate = 0.25,
+            MaxParticles = 17,
+            InitialParticles = 3,
+            TotalParticles = 9,
+            TotalSeconds = 4,
+            Lifespan = 2,
+            LifespanRand = 0.5,
+            A = new Vector3(1, 0, 0),
+            MinA = 0.5f,
+            MaxA = 2f,
+            StartScale = 0.2f,
+            FinalScale = 0.8f,
+            StartTrans = 1f,
+            FinalTrans = 0f,
+            IsParentLocal = true,
+        };
+
+        var desc = EmitterDescRegistry.FromDat(0x32000099u, dat);
+
+        Assert.Equal(ParticleType.Swarm, desc.Type);
+        Assert.Equal(ParticleEmitterKind.BirthratePerSec, desc.EmitterKind);
+        Assert.Equal(4f, desc.EmitRate);
+        Assert.Equal(0x01000001u, desc.GfxObjId);
+        Assert.Equal(0x01000002u, desc.HwGfxObjId);
+        Assert.Equal(3, desc.InitialParticles);
+        Assert.Equal(9, desc.TotalParticles);
+        Assert.Equal(1.5f, desc.LifetimeMin);
+        Assert.Equal(2.5f, desc.LifetimeMax);
+        Assert.Equal(0f, desc.StartAlpha);
+        Assert.Equal(1f, desc.EndAlpha);
+        Assert.Equal(EmitterFlags.Billboard | EmitterFlags.FaceCamera | EmitterFlags.AttachLocal, desc.Flags);
+        Assert.True((desc.Flags & EmitterFlags.AttachLocal) != 0);
+    }
+
+    [Fact]
+    public void UpdateEmitterAnchor_AttachLocal_ParticlePositionFollowsLiveAnchor()
+    {
+        // Retail ParticleEmitter::UpdateParticles 0x0051d2d4 reads the live
+        // parent frame each tick when is_parent_local=1. With the cameraOffset
+        // hack removed, AttachLocal correctness now depends on the owning
+        // subsystem updating AnchorPos every frame via UpdateEmitterAnchor.
+        var sys = MakeSystem();
+        var desc = new EmitterDesc
+        {
+            DatId = 0x32AABBCCu,
+            Type = ParticleType.Still,
+            Flags = EmitterFlags.AttachLocal | EmitterFlags.Billboard,
+            MaxParticles = 1,
+            InitialParticles = 1,
+            LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
+            StartSize = 1f, EndSize = 1f,
+            StartAlpha = 1f, EndAlpha = 1f,
+            // Zero motion + zero offset so position == origin == AnchorPos.
+        };
+        int handle = sys.SpawnEmitter(desc, anchor: new Vector3(10, 0, 0));
+        sys.Tick(0.01f);
+
+        var p1 = sys.EnumerateLive().Single().Emitter.Particles[0];
+        Assert.Equal(new Vector3(10, 0, 0), p1.Position);
+
+        // Move the live anchor; AttachLocal should track it on the next tick.
+        sys.UpdateEmitterAnchor(handle, new Vector3(50, 20, 5));
+        sys.Tick(0.01f);
+
+        var p2 = sys.EnumerateLive().Single().Emitter.Particles[0];
+        Assert.Equal(new Vector3(50, 20, 5), p2.Position);
+    }
+
+    [Fact]
+    public void UpdateEmitterAnchor_AttachLocalCleared_ParticleFrozenAtSpawnOrigin()
+    {
+        // is_parent_local=0 → particle uses its frozen EmissionOrigin; later
+        // anchor updates must NOT move it (retail's "frame snapshotted at
+        // spawn" semantics).
+        var sys = MakeSystem();
+        var desc = new EmitterDesc
+        {
+            DatId = 0x32AABBCDu,
+            Type = ParticleType.Still,
+            Flags = EmitterFlags.Billboard,    // NO AttachLocal
+            MaxParticles = 1,
+            InitialParticles = 1,
+            LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
+            StartSize = 1f, EndSize = 1f,
+            StartAlpha = 1f, EndAlpha = 1f,
+        };
+        int handle = sys.SpawnEmitter(desc, anchor: new Vector3(10, 0, 0));
+        sys.Tick(0.01f);
+
+        sys.UpdateEmitterAnchor(handle, new Vector3(99, 99, 99));
+        sys.Tick(0.01f);
+
+        var p = sys.EnumerateLive().Single().Emitter.Particles[0];
+        Assert.Equal(new Vector3(10, 0, 0), p.Position);
+    }
+
+    [Fact]
+    public void EmitterDied_FiresOncePerHandle_AfterAllParticlesExpire()
+    {
+        var sys = MakeSystem();
+        var fired = new System.Collections.Generic.List<int>();
+        sys.EmitterDied += h => fired.Add(h);
+
+        int handle = sys.SpawnEmitter(MakeDesc(emitRate: 5f, lifetime: 0.2f, maxParticles: 4), Vector3.Zero);
+        sys.StopEmitter(handle, fadeOut: false);   // kill emitter + all particles immediately
+        sys.Tick(0.01f);
+
+        Assert.Single(fired);
+        Assert.Equal(handle, fired[0]);
+        Assert.False(sys.IsEmitterAlive(handle));
+    }
+
+    [Fact]
+    public void Birthrate_PerSec_EmitsOnePerTickWhenIntervalElapsed()
+    {
+        // Retail ParticleEmitterInfo::ShouldEmitParticle 0x00517420 checks
+        // (cur_time - last_emit_time) > birthrate. RecordParticleEmission
+        // 0x0051c870 then sets last_emit_time = cur_time, so retail's
+        // UpdateParticles fires AT MOST one EmitParticle per frame
+        // (the dispatch is `if (ShouldEmit) EmitParticle()`, not a loop).
+        // Lock that behavior in.
+        var sys = MakeSystem();
+        var desc = new EmitterDesc
+        {
+            DatId = 0x32AAAA01u,
+            Type = ParticleType.Still,
+            EmitterKind = ParticleEmitterKind.BirthratePerSec,
+            Birthrate = 0.05f,         // 50ms minimum between emits
+            EmitRate = 0f,             // disable the EmitRate fallback path
+            MaxParticles = 100,
+            LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
+            StartSize = 1f, EndSize = 1f,
+            StartAlpha = 1f, EndAlpha = 1f,
+        };
+        sys.SpawnEmitter(desc, Vector3.Zero);
+
+        // Single 1-second tick. Retail-faithful behavior: exactly one
+        // particle emits, regardless of how many birthrate intervals fit in dt.
+        sys.Tick(1.0f);
+        Assert.Equal(1, sys.ActiveParticleCount);
+
+        // Subsequent small ticks each emit once if birthrate has elapsed.
+        sys.Tick(0.06f);  // > 0.05s since last emit
+        Assert.Equal(2, sys.ActiveParticleCount);
+
+        // A tick smaller than birthrate adds nothing.
+        sys.Tick(0.01f);
+        Assert.Equal(2, sys.ActiveParticleCount);
+    }
 }