feat(vfx): decode retail hooks and typed tables

Replace the incomplete package path with one DatCollection-backed compatibility seam for PhysicsScripts and Animations. Preserve CreateBlockingParticle's inherited payload and following cursor, route every production and audit consumer through the corrected loaders, and apply retail's post-UnPack StartTime ordering.

Add exact stored-order PhysicsScriptTable upper-threshold resolution, high-byte DID and embedded-ID validation, plus live effect profiles with Setup-to-PhysicsDesc precedence across top-level and attached entity lifetimes. Keep blocking execution deferred and narrow TS-11 accordingly.

Pin synthetic malformed/cursor/order fixtures, installed-DAT blocking and recall audits, high-index IDs, IEEE boundaries, profile teardown, and ordinary decoder parity; synchronize architecture, inventory, milestones, roadmap, research, and memory.

Co-Authored-By: Codex <noreply@openai.com>

src/AcDream.Core/Vfx/ParticleHookSink.cs

@@ -24,9 +24,10 @@ namespace AcDream.Core.Vfx;
 ///   <item><description>
 ///     <see cref="CreateBlockingParticleHook"/> — has the same payload
 ///     as CreateParticleHook, but suppresses creation while the same nonzero
-///     logical emitter ID is live. It does not pause animation. The dependency
-///     currently omits that inherited payload; the retail compatibility reader
-///     owns its decoding.
+///     logical emitter ID is live. It does not pause animation. Production DAT
+///     loading substitutes <see cref="RetailCreateBlockingParticleHook"/> so
+///     the inherited payload is retained despite the dependency's header-only
+///     model. Suppression itself lands with live emitter bindings in Step 5.
 ///   </description></item>
 ///   <item><description>
 ///     <see cref="DestroyParticleHook"/> — stop the most-recent emitter
@@ -102,6 +103,13 @@ public sealed class ParticleHookSink : IAnimationHookSink
     {
         switch (hook)
         {
+            case RetailCreateBlockingParticleHook:
+                // The centralized content reader now preserves the complete
+                // retail payload. Step 5 owns live logical-ID suppression and
+                // attachment semantics; do not silently treat blocking as a
+                // normal replacement before that mechanism lands.
+                break;
+
             case CreateParticleHook cph:
                 SpawnFromHook(entityId, entityWorldPosition,
                     emitterInfoId: (uint)cph.EmitterInfoId,
@@ -111,11 +119,8 @@ public sealed class ParticleHookSink : IAnimationHookSink
                 break;
 
             case CreateBlockingParticleHook:
-                // Retail gives this the full CreateParticle payload and
-                // suppresses creation only while the same nonzero logical ID
-                // is live; it never pauses animation. The dependency loses
-                // that payload, so TS-11 remains a no-op until the centralized
-                // raw-hook compatibility reader supplies the retail shape.
+                // Defensive package-decoder shape. Production raw loaders
+                // replace this header-only model with the retail subclass.
                 break;
 
             case DestroyParticleHook dph:
@@ -128,9 +133,8 @@ public sealed class ParticleHookSink : IAnimationHookSink
                     _system.StopEmitter(handleToStop, fadeOut: true);
                 break;
 
-            // DefaultScript / CallPES are wired when PhysicsScript loading
-            // is available. They arrive at the sink but we can't act until
-            // the script table returns a real emitter list.
+            // DefaultScript / CallPES are routed by the entity-effect owner in
+            // Step 4. ParticleHookSink intentionally owns particles only.
         }
     }
 

src/AcDream.Core/Vfx/PhysicsScriptRunner.cs

@@ -2,7 +2,6 @@ using System;
 using System.Collections.Generic;
 using System.Numerics;
 using AcDream.Core.Physics;
-using DatReaderWriter;
 using DatReaderWriter.Types;
 // Local (AcDream.Core.Vfx) has its own stub `PhysicsScript` type in
 // VfxModel.cs; alias the dat-reader type to avoid name collision.
@@ -82,8 +81,8 @@ public sealed class PhysicsScriptRunner
 
     /// <summary>
     /// Preferred ctor — resolver delegate lets this class stay
-    /// DatCollection-free for testing. Production code will pass
-    /// a lambda that hits <c>DatCollection.Get&lt;PhysicsScript&gt;</c>.
+    /// DAT-reader-free for testing. Production passes the centralized retail
+    /// compatibility loader so CreateBlockingParticle cannot misalign hooks.
     /// </summary>
     public PhysicsScriptRunner(Func<uint, DatPhysicsScript?> resolver, IAnimationHookSink sink)
     {
@@ -91,21 +90,6 @@ public sealed class PhysicsScriptRunner
         _sink     = sink     ?? throw new ArgumentNullException(nameof(sink));
     }
 
-    /// <summary>
-    /// Convenience ctor — builds a resolver around a <see cref="DatCollection"/>.
-    /// </summary>
-    public PhysicsScriptRunner(DatCollection dats, IAnimationHookSink sink)
-        : this(id => SafeGet(dats, id), sink)
-    {
-    }
-
-    private static DatPhysicsScript? SafeGet(DatCollection dats, uint id)
-    {
-        if (dats is null) return null;
-        try { return dats.Get<DatPhysicsScript>(id); }
-        catch { return null; }
-    }
-
     /// <summary>Number of scripts currently active (for telemetry).</summary>
     public int ActiveScriptCount => _active.Count;
 

src/AcDream.Core/Vfx/PhysicsScriptTableResolver.cs

@@ -0,0 +1,64 @@
+using DatReaderWriter.DBObjs;
+using DatReaderWriter.Enums;
+using DatReaderWriter.Types;
+
+namespace AcDream.Core.Vfx;
+
+/// <summary>
+/// Exact retail PhysicsScriptTable lookup: hash by raw script type, then scan
+/// that type's entries in stored DAT order for the first upper threshold.
+/// </summary>
+/// <remarks>
+/// Port of <c>PhysicsScriptTable::GetScript</c> at <c>0x00521E40</c> and
+/// <c>PhysicsScriptTableData::GetScript</c> at <c>0x00521A20</c>.
+/// </remarks>
+public sealed class PhysicsScriptTableResolver
+{
+    private readonly Func<uint, PhysicsScriptTable?> _loadTable;
+
+    public PhysicsScriptTableResolver(Func<uint, PhysicsScriptTable?> loadTable)
+        => _loadTable = loadTable ?? throw new ArgumentNullException(nameof(loadTable));
+
+    /// <summary>
+    /// Returns the selected PhysicsScript DID, or null for a missing table or
+    /// type, an unordered/above-range intensity, or an invalid script DID.
+    /// </summary>
+    public uint? Resolve(uint tableDid, uint rawScriptType, float intensity)
+    {
+        if (!IsPhysicsScriptTableDid(tableDid))
+            return null;
+
+        PhysicsScriptTable? table = _loadTable(tableDid);
+        if (table is null
+            || table.Id != tableDid
+            || !table.ScriptTable.TryGetValue(
+                unchecked((PlayScript)rawScriptType),
+                out PhysicsScriptTableData? data))
+        {
+            return null;
+        }
+
+        // Retail compares intensity <= Mod. Do not sort: equal and duplicate
+        // thresholds resolve to the first stored entry. IEEE comparisons make
+        // NaN fall through all entries, +infinity fall through finite entries,
+        // and -infinity select the first finite threshold.
+        foreach (ScriptAndModData entry in data.Scripts)
+        {
+            if (intensity <= entry.Mod)
+            {
+                uint scriptDid = entry.ScriptId.DataId;
+                return IsPhysicsScriptDid(scriptDid) ? scriptDid : null;
+            }
+        }
+
+        return null;
+    }
+
+    public static bool IsPhysicsScriptDid(uint did) =>
+        // AC data IDs encode the DBObj type in the high byte; the remaining
+        // 24 bits are the file index and must not be truncated to 16 bits.
+        (did & 0xFF000000u) == 0x33000000u;
+
+    public static bool IsPhysicsScriptTableDid(uint did) =>
+        (did & 0xFF000000u) == 0x34000000u;
+}

src/AcDream.Core/Vfx/RetailCreateBlockingParticleHook.cs

@@ -0,0 +1,20 @@
+using DatReaderWriter.Enums;
+using DatReaderWriter.Types;
+
+namespace AcDream.Core.Vfx;
+
+/// <summary>
+/// Retail's CreateBlockingParticle hook has the complete CreateParticle
+/// payload. Chorizite.DatReaderWriter 2.1.7 models it as a header-only hook,
+/// so the content compatibility reader instantiates this derived shape.
+/// </summary>
+/// <remarks>
+/// Retail oracle: <c>CreateBlockingParticleHook::Execute</c> at
+/// <c>0x00526EF0</c>. The inherited emitter DID, part, Frame, and logical
+/// emitter ID are consumed by <c>ParticleManager::CreateBlockingParticleEmitter</c>
+/// at <c>0x0051B8A0</c>.
+/// </remarks>
+public sealed class RetailCreateBlockingParticleHook : CreateParticleHook
+{
+    public override AnimationHookType HookType => AnimationHookType.CreateBlockingParticle;
+}