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/EmitterDescLoader.cs

@@ -2,9 +2,13 @@ using System;
 using System.Collections.Concurrent;
 using System.Numerics;
 using DatReaderWriter;
+using DatReaderWriter.Lib.IO;
 using DatParticleEmitter = DatReaderWriter.DBObjs.ParticleEmitter;
+using DatGfxObj = DatReaderWriter.DBObjs.GfxObj;
+using DatGfxObjDegradeInfo = DatReaderWriter.DBObjs.GfxObjDegradeInfo;
 using DatEmitterType = DatReaderWriter.Enums.EmitterType;
 using DatParticleType = DatReaderWriter.Enums.ParticleType;
+using DatGfxObjFlags = DatReaderWriter.Enums.GfxObjFlags;
 
 namespace AcDream.Core.Vfx;
 
@@ -15,6 +19,7 @@ namespace AcDream.Core.Vfx;
 public sealed class EmitterDescRegistry
 {
     private readonly Func<uint, DatParticleEmitter?>? _resolver;
+    private readonly Func<DatParticleEmitter, float?>? _degradeDistanceResolver;
     private readonly ConcurrentDictionary<uint, EmitterDesc> _byId = new();
 
     public EmitterDescRegistry()
@@ -23,8 +28,10 @@ public sealed class EmitterDescRegistry
     }
 
     public EmitterDescRegistry(DatCollection dats)
-        : this(id => SafeGet(dats, id))
     {
+        ArgumentNullException.ThrowIfNull(dats);
+        _resolver = id => SafeGet<DatParticleEmitter>(dats, id);
+        _degradeDistanceResolver = emitter => ResolveMaxDegradeDistance(dats, emitter);
     }
 
     public EmitterDescRegistry(Func<uint, DatParticleEmitter?>? resolver)
@@ -55,7 +62,18 @@ public sealed class EmitterDescRegistry
             var dat = _resolver(emitterId);
             if (dat is not null)
             {
-                desc = FromDat(emitterId, dat);
+                float? resolvedDistance = _degradeDistanceResolver?.Invoke(dat);
+                if (_degradeDistanceResolver is not null && !resolvedDistance.HasValue)
+                {
+                    // ParticleEmitter::SetInfo (0x0051CE90) fails when the
+                    // authored hardware GfxObj cannot be loaded. It never
+                    // substitutes the software GfxObj.
+                    desc = null!;
+                    return false;
+                }
+                float maxDegradeDistance = resolvedDistance
+                    ?? RetailParticleDegradeDistance.DefaultDistance;
+                desc = FromDat(emitterId, dat, maxDegradeDistance);
                 _byId[emitterId] = desc;
                 return true;
             }
@@ -66,7 +84,10 @@ public sealed class EmitterDescRegistry
 
     public int Count => _byId.Count;
 
-    public static EmitterDesc FromDat(uint emitterId, DatParticleEmitter dat)
+    public static EmitterDesc FromDat(
+        uint emitterId,
+        DatParticleEmitter dat,
+        float maxDegradeDistance = RetailParticleDegradeDistance.DefaultDistance)
     {
         ArgumentNullException.ThrowIfNull(dat);
 
@@ -90,6 +111,7 @@ public sealed class EmitterDescRegistry
 
         return new EmitterDesc
         {
+            MaxDegradeDistance = maxDegradeDistance,
             DatId = emitterId,
             Type = MapParticleType(dat.ParticleType),
             EmitterKind = MapEmitterKind(dat.EmitterType),
@@ -132,13 +154,37 @@ public sealed class EmitterDescRegistry
         };
     }
 
-    private static DatParticleEmitter? SafeGet(DatCollection dats, uint id)
+    private static float? ResolveMaxDegradeDistance(
+        DatCollection dats,
+        DatParticleEmitter emitter)
+    {
+        uint gfxObjId = GetRetailHardwareGfxObjId(emitter);
+        if (gfxObjId == 0)
+            return null;
+
+        DatGfxObj? gfx = SafeGet<DatGfxObj>(dats, gfxObjId);
+        if (gfx is null)
+            return null;
+        if (!gfx.Flags.HasFlag(DatGfxObjFlags.HasDIDDegrade)
+            || gfx.DIDDegrade == 0)
+        {
+            return RetailParticleDegradeDistance.DefaultDistance;
+        }
+
+        DatGfxObjDegradeInfo? degrade = SafeGet<DatGfxObjDegradeInfo>(dats, gfx.DIDDegrade);
+        return RetailParticleDegradeDistance.FromEntries(degrade?.Degrades);
+    }
+
+    internal static uint GetRetailHardwareGfxObjId(DatParticleEmitter emitter)
+        => emitter.HwGfxObjId.DataId;
+
+    private static T? SafeGet<T>(DatCollection dats, uint id) where T : class, IDBObj
     {
         if (dats is null)
             return null;
         try
         {
-            return dats.Get<DatParticleEmitter>(id);
+            return dats.Get<T>(id);
         }
         catch
         {
@@ -170,3 +216,24 @@ public sealed class EmitterDescRegistry
         _ => ParticleType.Unknown,
     };
 }
+
+/// <summary>
+/// Exact retail maximum-distance selection for a particle GfxObj.
+/// <c>CPhysicsPart::GetMaxDegradeDistance</c> (0x0050D510) supplies the
+/// 100-unit default; <c>GfxObjDegradeInfo::get_max_degrade_distance</c>
+/// (0x0051E2D0) selects entry zero for one/two-entry tables and the
+/// second-to-last entry for larger tables.
+/// </summary>
+public static class RetailParticleDegradeDistance
+{
+    public const float DefaultDistance = 100f;
+
+    public static float FromEntries(IReadOnlyList<DatReaderWriter.Types.GfxObjInfo>? entries)
+    {
+        if (entries is null || entries.Count == 0)
+            return DefaultDistance;
+
+        int index = entries.Count <= 2 ? 0 : entries.Count - 2;
+        return entries[index].MaxDist;
+    }
+}

src/AcDream.Core/Vfx/ParticleHookSink.cs

@@ -28,15 +28,18 @@ public sealed class ParticleHookSink : IAnimationHookSink
 {
     private readonly ParticleSystem _system;
     private readonly IEntityEffectPoseSource _poses;
+    private readonly IEntityEffectCellSource? _cells;
     private readonly ConcurrentDictionary<(uint EntityId, uint EmitterId), int> _handlesByKey = new();
     private readonly ConcurrentDictionary<uint, ConcurrentDictionary<int, byte>> _handlesByEntity = new();
     private readonly ConcurrentDictionary<int, EmitterBinding> _bindingsByHandle = new();
     private readonly ConcurrentDictionary<uint, ParticleRenderPass> _renderPassByEntity = new();
+    private readonly ConcurrentDictionary<uint, byte> _examinationOwners = new();
     private readonly ConcurrentDictionary<uint, byte> _hiddenPresentationOwners = new();
     public ParticleHookSink(ParticleSystem system, IEntityEffectPoseSource poses)
     {
         _system = system ?? throw new ArgumentNullException(nameof(system));
         _poses = poses ?? throw new ArgumentNullException(nameof(poses));
+        _cells = poses as IEntityEffectCellSource;
         _system.EmitterDied += OnEmitterDied;
     }
 
@@ -52,6 +55,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
     public int LogicalEmitterCount => _handlesByKey.Count;
     public int TrackedOwnerCount => _handlesByEntity.Count;
     public int RenderPassOwnerCount => _renderPassByEntity.Count;
+    public int ExaminationOwnerCount => _examinationOwners.Count;
     public int HiddenPresentationOwnerCount => _hiddenPresentationOwners.Count;
 
     private void OnEmitterDied(int handle)
@@ -115,11 +119,32 @@ public sealed class ParticleHookSink : IAnimationHookSink
         }
     }
 
-    public void SetEntityRenderPass(uint entityId, ParticleRenderPass renderPass) =>
+    public void SetEntityRenderPass(uint entityId, ParticleRenderPass renderPass)
+    {
         _renderPassByEntity[entityId] = renderPass;
+        RefreshOwnerVisibilityPolicy(entityId);
+    }
 
-    public void ClearEntityRenderPass(uint entityId) =>
+    public void ClearEntityRenderPass(uint entityId)
+    {
         _renderPassByEntity.TryRemove(entityId, out _);
+        RefreshOwnerVisibilityPolicy(entityId);
+    }
+
+    /// <summary>
+    /// Mirrors retail <c>CPhysicsObj::m_bExaminationObject</c>. Examination
+    /// previews bypass world distance and cell visibility without conflating
+    /// that policy with attachment identity.
+    /// </summary>
+    public void SetEntityExaminationObject(uint entityId, bool isExaminationObject)
+    {
+        if (isExaminationObject)
+            _examinationOwners[entityId] = 0;
+        else
+            _examinationOwners.TryRemove(entityId, out _);
+
+        RefreshOwnerVisibilityPolicy(entityId);
+    }
 
     /// <summary>
     /// Mirrors live cell membership without ending emitter lifetime. Retail
@@ -158,9 +183,18 @@ public sealed class ParticleHookSink : IAnimationHookSink
             bool presentationVisible =
                 !_hiddenPresentationOwners.ContainsKey(binding.OwnerLocalId);
             if (TryResolveAnchor(binding.OwnerLocalId, binding.PartIndex,
-                    binding.HookOffsetOrigin, out Vector3 anchor, out Quaternion rotation))
+                    binding.HookOffsetOrigin,
+                    out Vector3 anchor,
+                    out Quaternion rotation,
+                    out Vector3 ownerPosition))
             {
                 _system.UpdateEmitterAnchor(handle, anchor, rotation);
+                _system.UpdateEmitterOwnerPosition(handle, ownerPosition);
+                _system.UpdateEmitterOwnerCell(
+                    handle,
+                    _cells is not null && _cells.TryGetCellId(binding.OwnerLocalId, out uint cellId)
+                        ? cellId
+                        : 0u);
                 // Keep the anchor current while spatially paused; re-entry
                 // resumes at the authoritative pose without generating the
                 // absent interval's time- or distance-driven emissions.
@@ -193,6 +227,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
                 _handlesByKey.TryRemove(key, out _);
         }
         ClearEntityRenderPass(entityId);
+        _examinationOwners.TryRemove(entityId, out _);
         _hiddenPresentationOwners.TryRemove(entityId, out _);
     }
 
@@ -236,7 +271,9 @@ public sealed class ParticleHookSink : IAnimationHookSink
         Vector3 offsetOrigin = offset?.Origin ?? Vector3.Zero;
         Quaternion offsetOrientation = offset?.Orientation ?? Quaternion.Identity;
         if (!TryResolveAnchor(ownerLocalId, partIndex, offsetOrigin,
-                out Vector3 anchor, out Quaternion rotation))
+                out Vector3 anchor,
+                out Quaternion rotation,
+                out Vector3 ownerPosition))
         {
             DiagnosticSink?.Invoke(
                 $"No live effect pose for owner 0x{ownerLocalId:X8}, part {partIndex}; " +
@@ -247,6 +284,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
         ParticleRenderPass renderPass = _renderPassByEntity.TryGetValue(ownerLocalId, out var pass)
             ? pass
             : ParticleRenderPass.Scene;
+        ParticleVisibilityPolicy visibilityPolicy = ResolveVisibilityPolicy(ownerLocalId);
         if (!_system.TrySpawnEmitterById(
                 emitterInfoId,
                 anchor,
@@ -254,6 +292,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
                 ownerLocalId,
                 partIndex,
                 renderPass,
+                visibilityPolicy,
                 out int handle))
         {
             DiagnosticSink?.Invoke(
@@ -261,6 +300,12 @@ public sealed class ParticleHookSink : IAnimationHookSink
                 $"0x{ownerLocalId:X8} was not found; no fallback was created.");
             return;
         }
+        _system.UpdateEmitterOwnerPosition(handle, ownerPosition);
+        _system.UpdateEmitterOwnerCell(
+            handle,
+            _cells is not null && _cells.TryGetCellId(ownerLocalId, out uint cellId)
+                ? cellId
+                : 0u);
         if (_hiddenPresentationOwners.ContainsKey(ownerLocalId))
         {
             _system.SetEmitterPresentationVisible(handle, false);
@@ -282,20 +327,45 @@ public sealed class ParticleHookSink : IAnimationHookSink
             _handlesByKey[(ownerLocalId, logicalId)] = handle;
     }
 
+    private ParticleVisibilityPolicy ResolveVisibilityPolicy(uint ownerLocalId)
+    {
+        if (_examinationOwners.ContainsKey(ownerLocalId))
+            return ParticleVisibilityPolicy.Examination;
+
+        return _renderPassByEntity.TryGetValue(ownerLocalId, out ParticleRenderPass pass)
+               && pass != ParticleRenderPass.Scene
+            ? ParticleVisibilityPolicy.PassOwned
+            : ParticleVisibilityPolicy.World;
+    }
+
+    private void RefreshOwnerVisibilityPolicy(uint ownerLocalId)
+    {
+        if (!_handlesByEntity.TryGetValue(ownerLocalId, out var handles))
+            return;
+
+        ParticleVisibilityPolicy policy = ResolveVisibilityPolicy(ownerLocalId);
+        foreach (int handle in handles.Keys)
+            _system.SetEmitterVisibilityPolicy(handle, policy);
+    }
+
     private bool TryResolveAnchor(
         uint ownerLocalId,
         int partIndex,
         Vector3 offsetOrigin,
         out Vector3 anchor,
-        out Quaternion rotation)
+        out Quaternion rotation,
+        out Vector3 ownerPosition)
     {
         if (!_poses.TryGetRootPose(ownerLocalId, out Matrix4x4 rootWorld))
         {
             anchor = default;
             rotation = default;
+            ownerPosition = default;
             return false;
         }
 
+        ownerPosition = new Vector3(rootWorld.M41, rootWorld.M42, rootWorld.M43);
+
         Matrix4x4 ownerFrame = rootWorld;
         if (partIndex != -1)
         {
@@ -303,6 +373,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
             {
                 anchor = default;
                 rotation = default;
+                ownerPosition = default;
                 return false;
             }
             ownerFrame = partLocal * rootWorld;
@@ -313,6 +384,7 @@ public sealed class ParticleHookSink : IAnimationHookSink
         {
             anchor = default;
             rotation = default;
+            ownerPosition = default;
             return false;
         }
         rotation = Quaternion.Normalize(rotation);

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)

src/AcDream.Core/Vfx/VfxModel.cs

@@ -46,6 +46,18 @@ public enum ParticleRenderPass
     SkyPostScene = 2,
 }
 
+/// <summary>
+/// Authority used by retail's particle presentation gate. World-owned
+/// emitters follow <c>CPhysicsObj::ShouldDrawParticles</c>; examination and
+/// dedicated render-pass emitters are explicitly exempt from world PView.
+/// </summary>
+public enum ParticleVisibilityPolicy
+{
+    World = 0,
+    Examination = 1,
+    PassOwned = 2,
+}
+
 [Flags]
 public enum EmitterFlags : uint
 {
@@ -62,6 +74,12 @@ public enum EmitterFlags : uint
 /// </summary>
 public sealed class EmitterDesc
 {
+    /// <summary>
+    /// Retail distance at which the owning physics object degrades this
+    /// emitter out. Sourced from the hardware particle GfxObj's degradation
+    /// table by <c>CPhysicsPart::GetMaxDegradeDistance</c> (0x0050D510).
+    /// </summary>
+    public float MaxDegradeDistance { get; init; } = 100f;
     public uint DatId { get; init; }
     public ParticleType Type { get; init; }
     public ParticleEmitterKind EmitterKind { get; init; } = ParticleEmitterKind.BirthratePerSec;
@@ -158,6 +176,12 @@ public struct Particle
     public Vector3 B;
     public Vector3 C;
     public float SpawnedAt;
+    /// <summary>
+    /// Emitter-level frozen time at birth. This lets an infinite degraded
+    /// emitter freeze every particle's age in O(1), equivalent to retail
+    /// rewriting every live particle birth time to the current game time.
+    /// </summary>
+    public float FrozenTimeAtSpawn;
     public float Lifetime;
     public float Age;
     public float StartSize;
@@ -184,9 +208,22 @@ public sealed class ParticleEmitter
     public int Handle { get; init; }
     public EmitterDesc Desc { get; init; } = null!;
     public Vector3 AnchorPos { get; set; }
+    /// <summary>
+    /// Root position of the owning physics object. Retail measures particle
+    /// degradation from the owner (<c>CPhysicsObj::CYpt</c>), not from an
+    /// animated hand/part hook offset.
+    /// </summary>
+    public Vector3 OwnerPosition { get; set; }
+    /// <summary>Current owning AC cell for retail <c>IsInView</c> gating.</summary>
+    public uint OwnerCellId { get; set; }
     public Quaternion AnchorRot { get; set; } = Quaternion.Identity;
     public uint AttachedObjectId { get; set; }
     /// <summary>
+    /// Explicit presentation context. Retail's examination-object bypass is
+    /// object state, not an inference from attachment identity.
+    /// </summary>
+    public ParticleVisibilityPolicy VisibilityPolicy { get; set; }
+    /// <summary>
     /// Spatial presentation latch. A cell-less owner submits no particles.
     /// </summary>
     public bool PresentationVisible { get; set; } = true;
@@ -195,6 +232,13 @@ public sealed class ParticleEmitter
     /// particles, logical identity, and elapsed-time position until re-entry.
     /// </summary>
     public bool SimulationEnabled { get; set; } = true;
+    /// <summary>
+    /// Result of retail <c>CPhysicsObj::ShouldDrawParticles</c>: authored
+    /// distance plus the previous completed PView's visibility state.
+    /// </summary>
+    public bool ViewEligible { get; set; } = true;
+    /// <summary>Retail <c>ParticleEmitter::degraded_out</c> latch.</summary>
+    public bool DegradedOut { get; set; }
     public int AttachedPartIndex { get; set; } = -1;
     public Particle[] Particles { get; init; } = null!;
     public ParticleRenderPass RenderPass { get; init; }
@@ -202,6 +246,11 @@ public sealed class ParticleEmitter
     public float EmittedAccumulator;
     public float StartedAt;
     public float LastEmitTime;
+    /// <summary>
+    /// Total time this infinite emitter spent degraded. Particles subtract
+    /// the delta since their own birth rather than being rewritten one by one.
+    /// </summary>
+    public float FrozenTime;
     public Vector3 LastEmitOffset;
     public int TotalEmitted;
     public bool Finished;
@@ -219,7 +268,8 @@ public interface IParticleSystem
         Quaternion? rot = null,
         uint attachedObjectId = 0,
         int attachedPartIndex = -1,
-        ParticleRenderPass renderPass = ParticleRenderPass.Scene);
+        ParticleRenderPass renderPass = ParticleRenderPass.Scene,
+        ParticleVisibilityPolicy visibilityPolicy = ParticleVisibilityPolicy.World);
 
     /// <summary>Fire a full PhysicsScript at a target.</summary>
     void PlayScript(uint scriptId, uint targetObjectId, float modifier = 1f);