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>

src/AcDream.Core/Vfx/ParticleSystem.cs

@@ -35,7 +35,8 @@ public sealed class ParticleSystem : IParticleSystem
         Quaternion? rot = null,
         uint attachedObjectId = 0,
         int attachedPartIndex = -1,
-        ParticleRenderPass renderPass = ParticleRenderPass.Scene)
+        ParticleRenderPass renderPass = ParticleRenderPass.Scene,
+        ParticleVisibilityPolicy visibilityPolicy = ParticleVisibilityPolicy.World)
     {
         ArgumentNullException.ThrowIfNull(desc);
 
@@ -45,10 +46,12 @@ public sealed class ParticleSystem : IParticleSystem
             Handle = handle,
             Desc = desc,
             AnchorPos = anchor,
+            OwnerPosition = anchor,
             AnchorRot = rot ?? Quaternion.Identity,
             AttachedObjectId = attachedObjectId,
             AttachedPartIndex = attachedPartIndex,
             RenderPass = renderPass,
+            VisibilityPolicy = visibilityPolicy,
             Particles = new Particle[Math.Max(1, desc.MaxParticles)],
             StartedAt = _time,
             LastEmitTime = _time,
@@ -70,10 +73,18 @@ public sealed class ParticleSystem : IParticleSystem
         Quaternion? rot = null,
         uint attachedObjectId = 0,
         int attachedPartIndex = -1,
-        ParticleRenderPass renderPass = ParticleRenderPass.Scene)
+        ParticleRenderPass renderPass = ParticleRenderPass.Scene,
+        ParticleVisibilityPolicy visibilityPolicy = ParticleVisibilityPolicy.World)
     {
         var desc = _registry.Get(emitterId);
-        return SpawnEmitter(desc, anchor, rot, attachedObjectId, attachedPartIndex, renderPass);
+        return SpawnEmitter(
+            desc,
+            anchor,
+            rot,
+            attachedObjectId,
+            attachedPartIndex,
+            renderPass,
+            visibilityPolicy);
     }
 
     public bool TrySpawnEmitterById(
@@ -83,6 +94,7 @@ public sealed class ParticleSystem : IParticleSystem
         uint attachedObjectId,
         int attachedPartIndex,
         ParticleRenderPass renderPass,
+        ParticleVisibilityPolicy visibilityPolicy,
         out int handle)
     {
         if (!_registry.TryGet(emitterId, out EmitterDesc? desc))
@@ -97,7 +109,8 @@ public sealed class ParticleSystem : IParticleSystem
             rot,
             attachedObjectId,
             attachedPartIndex,
-            renderPass);
+            renderPass,
+            visibilityPolicy);
         return true;
     }
 
@@ -116,6 +129,7 @@ public sealed class ParticleSystem : IParticleSystem
         {
             for (int i = 0; i < em.Particles.Length; i++)
                 em.Particles[i].Alive = false;
+            em.ActiveCount = 0;
             // Retail DestroyParticleEmitter removes the table entry now; it
             // does not wait for the next update. This is also required for a
             // hard-stopped emitter whose cell-less simulation is paused.
@@ -145,6 +159,77 @@ public sealed class ParticleSystem : IParticleSystem
             em.AnchorRot = rot.Value;
     }
 
+    /// <summary>
+    /// Refreshes the owning physics object's root used by retail's particle
+    /// degradation-distance check. This remains distinct from an animated
+    /// part's emitter anchor.
+    /// </summary>
+    public void UpdateEmitterOwnerPosition(int handle, Vector3 ownerPosition)
+    {
+        if (_byHandle.TryGetValue(handle, out ParticleEmitter? emitter))
+            emitter.OwnerPosition = ownerPosition;
+    }
+
+    public void UpdateEmitterOwnerCell(int handle, uint ownerCellId)
+    {
+        if (_byHandle.TryGetValue(handle, out ParticleEmitter? emitter))
+            emitter.OwnerCellId = ownerCellId;
+    }
+
+    public void SetEmitterVisibilityPolicy(
+        int handle,
+        ParticleVisibilityPolicy visibilityPolicy)
+    {
+        if (_byHandle.TryGetValue(handle, out ParticleEmitter? emitter))
+            emitter.VisibilityPolicy = visibilityPolicy;
+    }
+
+    /// <summary>
+    /// Applies <c>CPhysicsObj::ShouldDrawParticles</c> (0x0050FE60) to every
+    /// live emitter. The App layer supplies the previous completed retail
+    /// PView's cell set, equivalent to <c>CObjCell::IsInView</c> when the next
+    /// physics update runs.
+    /// </summary>
+    public void ApplyRetailView(
+        Vector3 viewerPosition,
+        IReadOnlySet<uint> visibleCellIds,
+        bool hasCompletedView,
+        float rangeMultiplier = 1f)
+    {
+        ArgumentNullException.ThrowIfNull(visibleCellIds);
+        if (!float.IsFinite(rangeMultiplier) || rangeMultiplier <= 0f)
+            rangeMultiplier = 1f;
+
+        foreach (int handle in _handleOrder)
+        {
+            if (!_byHandle.TryGetValue(handle, out ParticleEmitter? emitter))
+                continue;
+
+            if (emitter.VisibilityPolicy != ParticleVisibilityPolicy.World)
+            {
+                emitter.ViewEligible = true;
+                continue;
+            }
+            if (!hasCompletedView)
+            {
+                // With no completed world PView (portal space, login, or a
+                // reset frame), a world cell cannot report IsInView.
+                emitter.ViewEligible = false;
+                continue;
+            }
+
+            float maxDistance = emitter.Desc.MaxDegradeDistance * rangeMultiplier;
+            float distance = RetailDistance(emitter.OwnerPosition, viewerPosition);
+            emitter.ViewEligible = emitter.OwnerCellId != 0
+                && visibleCellIds.Contains(emitter.OwnerCellId)
+                // The x87 comparison in ShouldDrawParticles admits unordered
+                // comparisons (NaN) and reject a negative authored range.
+                && (float.IsNaN(distance)
+                    || float.IsNaN(maxDistance)
+                    || distance <= maxDistance);
+        }
+    }
+
     /// <summary>
     /// Changes only render presentation. Logical lifetime is unaffected.
     /// </summary>
@@ -210,10 +295,19 @@ public sealed class ParticleSystem : IParticleSystem
                 continue;
             if (!em.SimulationEnabled)
                 continue;
+            bool wasFinishedBeforeUpdate = em.Finished;
 
-            AdvanceEmitter(em);
-            int live = CountAlive(em);
-            em.ActiveCount = live;
+            if (em.ViewEligible)
+            {
+                em.DegradedOut = false;
+                AdvanceEmitter(em);
+            }
+            else
+            {
+                em.DegradedOut = true;
+                AdvanceDegradedEmitter(em, dt);
+            }
+            int live = em.ActiveCount;
             _activeParticleCount += live;
 
             if (em.Desc.TotalDuration > 0f && (_time - em.StartedAt) > em.Desc.TotalDuration)
@@ -222,7 +316,10 @@ public sealed class ParticleSystem : IParticleSystem
             if (em.Desc.TotalParticles > 0 && em.TotalEmitted >= em.Desc.TotalParticles)
                 em.Finished = true;
 
-            if (em.Finished && live == 0)
+            // UpdateParticles returns true on the exact tick StopEmitter
+            // first changes state. Only the next update's already-stopped
+            // branch may return num_particles == 0 and retire the emitter.
+            if (em.Finished && live == 0 && wasFinishedBeforeUpdate)
             {
                 _byHandle.Remove(handle);
                 _handleOrder.RemoveAt(i);
@@ -253,6 +350,66 @@ public sealed class ParticleSystem : IParticleSystem
     /// </summary>
     public LiveParticleEnumerable EnumerateLive() => new(this);
 
+    /// <summary>
+    /// Enumerates live emitters in spawn order. The renderer consumes this
+    /// before particle slots so pass/visibility rejection is O(emitters), not
+    /// O(all particles in every pass).
+    /// </summary>
+    public LiveEmitterEnumerable EnumerateEmitters() => new(this);
+
+    public readonly struct LiveEmitterEnumerable : IEnumerable<ParticleEmitter>
+    {
+        private readonly ParticleSystem _owner;
+        internal LiveEmitterEnumerable(ParticleSystem owner) => _owner = owner;
+
+        public Enumerator GetEnumerator() => new(_owner);
+
+        IEnumerator<ParticleEmitter> IEnumerable<ParticleEmitter>.GetEnumerator()
+            => EnumerateBoxed(_owner).GetEnumerator();
+
+        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
+            => EnumerateBoxed(_owner).GetEnumerator();
+
+        private static IEnumerable<ParticleEmitter> EnumerateBoxed(ParticleSystem owner)
+        {
+            foreach (int handle in owner._handleOrder)
+            {
+                if (owner._byHandle.TryGetValue(handle, out ParticleEmitter? emitter))
+                    yield return emitter;
+            }
+        }
+
+        public struct Enumerator
+        {
+            private readonly ParticleSystem _owner;
+            private int _index;
+
+            internal Enumerator(ParticleSystem owner)
+            {
+                _owner = owner;
+                _index = -1;
+                Current = null!;
+            }
+
+            public ParticleEmitter Current { get; private set; }
+
+            public bool MoveNext()
+            {
+                while (++_index < _owner._handleOrder.Count)
+                {
+                    if (_owner._byHandle.TryGetValue(
+                            _owner._handleOrder[_index],
+                            out ParticleEmitter? emitter))
+                    {
+                        Current = emitter;
+                        return true;
+                    }
+                }
+                return false;
+            }
+        }
+    }
+
     /// <summary>
     /// Struct enumerable returned by <see cref="EnumerateLive"/>. Wraps the
     /// owning <see cref="ParticleSystem"/> so <c>foreach</c> gets a
@@ -342,10 +499,11 @@ public sealed class ParticleSystem : IParticleSystem
             if (!p.Alive)
                 continue;
 
-            p.Age = _time - p.SpawnedAt;
+            p.Age = EffectiveParticleAge(em, p);
             if (p.Lifetime <= 0f || p.Age >= p.Lifetime)
             {
                 p.Alive = false;
+                em.ActiveCount--;
                 continue;
             }
 
@@ -380,13 +538,63 @@ public sealed class ParticleSystem : IParticleSystem
         }
     }
 
+    /// <summary>
+    /// Retail <c>ParticleEmitter::UpdateParticles</c> (0x0051D180)
+    /// degraded branch. Infinite emitters freeze particle age without normal
+    /// updates or emissions. Finite emitters age/retire existing particles,
+    /// record at most one due emission without creating a drawable particle,
+    /// then run retail's conditional stop test.
+    /// </summary>
+    private void AdvanceDegradedEmitter(ParticleEmitter em, float dt)
+    {
+        bool infinite = em.Desc.TotalParticles == 0 && em.Desc.TotalDuration == 0f;
+        if (infinite)
+        {
+            em.FrozenTime += dt;
+            // Callback-created descriptors sometimes use the legacy EmitRate
+            // representation. Rebase that accumulator so it cannot synthesize
+            // a catch-up burst after degradation; retail performs no backlog.
+            if (em.Desc.Birthrate <= 0f && em.Desc.EmitRate > 0f)
+            {
+                em.LastEmitTime = _time;
+                em.EmittedAccumulator = 0f;
+            }
+            return;
+        }
+
+        for (int i = 0; i < em.Particles.Length; i++)
+        {
+            ref Particle particle = ref em.Particles[i];
+            if (!particle.Alive)
+                continue;
+
+            particle.Age = _time - particle.SpawnedAt;
+            if (particle.Lifetime <= 0f || particle.Age >= particle.Lifetime)
+            {
+                particle.Alive = false;
+                em.ActiveCount--;
+            }
+        }
+
+        if (!em.Finished && ShouldEmitParticle(em))
+        {
+            // ParticleEmitter::RecordParticleEmission (0x0051C870) advances
+            // both num_particles and total_emitted while degraded, but no
+            // PhysicsPart is made visible.
+            em.ActiveCount++;
+            em.TotalEmitted++;
+            em.LastEmitTime = _time;
+            em.LastEmitOffset = em.AnchorPos;
+        }
+    }
+
     private bool ShouldEmitParticle(ParticleEmitter em)
     {
         var desc = em.Desc;
         if (desc.TotalParticles > 0 && em.TotalEmitted >= desc.TotalParticles)
             return false;
 
-        if (CountAlive(em) >= desc.MaxParticles)
+        if (em.ActiveCount >= desc.MaxParticles)
             return false;
 
         if (desc.Birthrate <= 0f)
@@ -410,9 +618,11 @@ public sealed class ParticleSystem : IParticleSystem
             return false;
 
         ref var particle = ref em.Particles[slot];
+        bool replacesLiveParticle = particle.Alive;
         particle = default;
         particle.Alive = true;
         particle.SpawnedAt = _time;
+        particle.FrozenTimeAtSpawn = em.FrozenTime;
         particle.Lifetime = RandomLifespan(em.Desc);
         particle.EmissionOrigin = em.AnchorPos;
         particle.SpawnRotation = em.AnchorRot;
@@ -448,11 +658,17 @@ public sealed class ParticleSystem : IParticleSystem
         particle.Position = ComputePosition(em, particle);
 
         em.TotalEmitted++;
+        if (!replacesLiveParticle)
+            em.ActiveCount++;
         em.LastEmitTime = _time;
         em.LastEmitOffset = em.AnchorPos;
         return true;
     }
 
+    private float EffectiveParticleAge(ParticleEmitter emitter, in Particle particle)
+        => _time - particle.SpawnedAt
+           - (emitter.FrozenTime - particle.FrozenTimeAtSpawn);
+
     private Vector3 ComputePosition(ParticleEmitter em, Particle p)
     {
         float t = p.Age;
@@ -599,16 +815,22 @@ public sealed class ParticleSystem : IParticleSystem
         return slot;
     }
 
-    private static int CountAlive(ParticleEmitter em)
+    private static float RetailDistance(Vector3 a, Vector3 b)
     {
-        int n = 0;
-        for (int i = 0; i < em.Particles.Length; i++)
-        {
-            if (em.Particles[i].Alive)
-                n++;
-        }
+        // Overflow-safe Euclidean length. Vector3.DistanceSquared overflows
+        // for finite coordinates near FLT_MAX, whereas retail compares its
+        // already-computed direct distance against max_dist.
+        float dx = a.X - b.X;
+        float dy = a.Y - b.Y;
+        float dz = a.Z - b.Z;
+        float scale = MathF.Max(MathF.Abs(dx), MathF.Max(MathF.Abs(dy), MathF.Abs(dz)));
+        if (float.IsNaN(scale) || float.IsInfinity(scale) || scale == 0f)
+            return scale;
 
-        return n;
+        dx /= scale;
+        dy /= scale;
+        dz /= scale;
+        return scale * MathF.Sqrt(dx * dx + dy * dy + dz * dz);
     }
 
     private float RandomLifespan(EmitterDesc desc)