perf(vfx): port retail particle visibility degradation

Resolve DAT-authored particle ranges from the hardware GfxObj, apply retail distance and completed-cell visibility gates, and preserve the exact finite/infinite off-view update semantics. This removes dense-world simulation work without shortening terrain, entity, fog, or streaming distance.

Publish doorway-clipped outdoor cells through a focused frame controller, retain effect cell identity for outdoor statics, reject hidden emitters before particle-slot scans, and offer an explicit opt-in Extended particle range.

Release build succeeds and all 5,857 tests pass with five intentional skips. Retail-conformance, architecture, and adversarial review cycles are clean; connected Aerlinthe visual/performance gate pending.

Co-authored-by: OpenAI Codex <codex@openai.com>

tests/AcDream.App.Tests/Rendering/RetailParticleGeometryClassifierTests.cs

@@ -167,6 +167,26 @@ public sealed class RetailParticleGeometryClassifierTests
         Assert.Equal(0x33000331u, resolver.Resolve(0x34000004u, 0x76u, 1f));
     }
 
+    [Fact]
+    public void InstalledAerlintheSwarmEmitter_UsesItsHardwareGfxDegradeDistance()
+    {
+        string? datDir = ResolveDatDir();
+        if (datDir is null)
+            throw SkipException.ForSkip("Installed client_portal.dat is required.");
+
+        using var dats = new DatCollection(datDir, DatAccessType.Read);
+        var emitters = new EmitterDescRegistry(dats);
+        EmitterDesc desc = emitters.Get(0x32000223u);
+        GfxObj gfx = Assert.IsType<GfxObj>(dats.Get<GfxObj>(desc.HwGfxObjId));
+        GfxObjDegradeInfo degrade = Assert.IsType<GfxObjDegradeInfo>(
+            dats.Get<GfxObjDegradeInfo>(gfx.DIDDegrade));
+
+        Assert.Equal(
+            RetailParticleDegradeDistance.FromEntries(degrade.Degrades),
+            desc.MaxDegradeDistance);
+        Assert.Equal(64f, desc.MaxDegradeDistance);
+    }
+
     private static string? ResolveDatDir()
     {
         string? configured = System.Environment.GetEnvironmentVariable("ACDREAM_DAT_DIR");

tests/AcDream.App.Tests/Rendering/TerrainParticleCellVisibilityTests.cs

@@ -0,0 +1,119 @@
+using System.Numerics;
+using AcDream.App.Rendering;
+
+namespace AcDream.App.Tests.Rendering;
+
+public sealed class TerrainParticleCellVisibilityTests
+{
+    [Fact]
+    public void CollectVisibleCells_PublishesLandscapeCellsWithoutEntitySurvivors()
+    {
+        var cells = new HashSet<uint>();
+
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            Vector3.Zero,
+            zMin: 0f,
+            zMax: 20f,
+            frustum: null,
+            Matrix4x4.Identity,
+            ReadOnlySpan<Vector4>.Empty);
+
+        Assert.Equal(64, cells.Count);
+        Assert.Contains(0xA9B40001u, cells);
+        Assert.Contains(0xA9B40040u, cells);
+    }
+
+    [Fact]
+    public void CollectVisibleCells_ForceDrawnParentStillUsesCellFrustum()
+    {
+        var cells = new HashSet<uint>();
+        FrustumPlanes frustum = FrustumPlanes.FromViewProjection(Matrix4x4.Identity);
+
+        // The parent landblock may have entered TerrainModernRenderer's draw
+        // list through neverCullLandblockId. The cell collector deliberately
+        // receives no such bypass and still rejects its off-frustum cells.
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            new Vector3(100f, 100f, 100f),
+            zMin: 100f,
+            zMax: 120f,
+            frustum,
+            Matrix4x4.Identity,
+            ReadOnlySpan<Vector4>.Empty);
+
+        Assert.Empty(cells);
+    }
+
+    [Fact]
+    public void CollectVisibleCells_RejectsCellsOutsideDoorwayClipPlanes()
+    {
+        var cells = new HashSet<uint>();
+        var planes = new[] { new Vector4(-1f, 0f, 0f, -2f) };
+
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            Vector3.Zero,
+            zMin: 0f,
+            zMax: 20f,
+            frustum: null,
+            Matrix4x4.Identity,
+            planes);
+
+        Assert.Empty(cells);
+    }
+
+    [Fact]
+    public void CollectVisibleCells_RejectsCellsOutsideDoorwayScissorAabb()
+    {
+        var cells = new HashSet<uint>();
+
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            Vector3.Zero,
+            zMin: 0f,
+            zMax: 20f,
+            frustum: null,
+            Matrix4x4.Identity,
+            ReadOnlySpan<Vector4>.Empty,
+            ndcClipAabb: new Vector4(-4f, -4f, -2f, -2f));
+
+        Assert.Empty(cells);
+    }
+
+    [Fact]
+    public void CollectVisibleCells_UnionsCellsFromEveryLandscapeSlice()
+    {
+        var cells = new HashSet<uint>();
+
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            Vector3.Zero,
+            zMin: 0f,
+            zMax: 20f,
+            frustum: null,
+            Matrix4x4.Identity,
+            ReadOnlySpan<Vector4>.Empty,
+            ndcClipAabb: new Vector4(1f, -1_000f, 23f, 1_000f));
+        TerrainModernRenderer.CollectVisibleCells(
+            cells,
+            0xA9B4FFFFu,
+            Vector3.Zero,
+            zMin: 0f,
+            zMax: 20f,
+            frustum: null,
+            Matrix4x4.Identity,
+            ReadOnlySpan<Vector4>.Empty,
+            ndcClipAabb: new Vector4(49f, -1_000f, 71f, 1_000f));
+
+        Assert.Equal(16, cells.Count);
+        Assert.Contains(0xA9B40001u, cells);
+        Assert.Contains(0xA9B40011u, cells);
+        Assert.DoesNotContain(0xA9B40009u, cells);
+    }
+}

tests/AcDream.App.Tests/Rendering/Vfx/EntityEffectPoseRegistryTests.cs

@@ -140,6 +140,20 @@ public sealed class EntityEffectPoseRegistryTests
         Assert.Equal(0, queue.Count);
     }
 
+    [Fact]
+    public void Publish_UsesOutdoorEffectCellWithoutChangingRenderParent()
+    {
+        var poses = new EntityEffectPoseRegistry();
+        WorldEntity entity = Entity(12u, Vector3.Zero);
+        entity.ParentCellId = null;
+        entity.EffectCellId = 0xA9B4000Bu;
+
+        poses.Publish(entity, Array.Empty<Matrix4x4>());
+
+        Assert.True(poses.TryGetCellId(entity.Id, out uint cellId));
+        Assert.Equal(0xA9B4000Bu, cellId);
+    }
+
     private static WorldEntity Entity(uint id, Vector3 position) => new()
     {
         Id = id,

tests/AcDream.App.Tests/Rendering/Vfx/ParticleVisibilityControllerTests.cs

@@ -0,0 +1,67 @@
+using System.Numerics;
+using AcDream.App.Rendering.Vfx;
+using AcDream.Core.Vfx;
+
+namespace AcDream.App.Tests.Rendering.Vfx;
+
+public sealed class ParticleVisibilityControllerTests
+{
+    [Fact]
+    public void CompletedRetailViewFeedsNextParticleUpdate()
+    {
+        var particles = new ParticleSystem(new EmitterDescRegistry(), new Random(1));
+        int handle = particles.SpawnEmitter(
+            new EmitterDesc
+            {
+                DatId = 0x32000001u,
+                Type = ParticleType.Still,
+                MaxDegradeDistance = 100f,
+                MaxParticles = 1,
+                InitialParticles = 1,
+                LifetimeMin = 10f,
+                LifetimeMax = 10f,
+            },
+            Vector3.Zero,
+            attachedObjectId: 99u);
+        particles.UpdateEmitterOwnerCell(handle, 0x01010001u);
+        var controller = new ParticleVisibilityController();
+
+        controller.BeginFrame(Vector3.Zero);
+        controller.UseWorldView();
+        controller.MarkVisibleCells(new HashSet<uint> { 0x01010001u });
+        controller.CompleteFrame();
+        controller.Apply(particles, 1f);
+
+        Assert.True(Assert.Single(particles.EnumerateEmitters()).ViewEligible);
+        Assert.Equal(handle, Assert.Single(particles.EnumerateEmitters()).Handle);
+    }
+
+    [Fact]
+    public void UnresolvedFramePublishesEmptyWorldView()
+    {
+        var particles = new ParticleSystem(new EmitterDescRegistry(), new Random(1));
+        int handle = particles.SpawnEmitter(
+            new EmitterDesc
+            {
+                DatId = 0x32000002u,
+                Type = ParticleType.Still,
+                MaxDegradeDistance = 100f,
+                MaxParticles = 1,
+            },
+            Vector3.Zero,
+            attachedObjectId: 42u);
+        particles.UpdateEmitterOwnerCell(handle, 0x01010001u);
+        var controller = new ParticleVisibilityController();
+
+        controller.BeginFrame(Vector3.Zero);
+        controller.UseWorldView();
+        controller.CompleteFrame();
+        controller.Apply(particles, 1f);
+        Assert.False(Assert.Single(particles.EnumerateEmitters()).ViewEligible);
+
+        controller.BeginFrame(Vector3.Zero);
+        controller.CompleteFrame();
+        controller.Apply(particles, 1f);
+        Assert.False(Assert.Single(particles.EnumerateEmitters()).ViewEligible);
+    }
+}