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/Meshing/MotionResolver.cs

@@ -1,6 +1,7 @@
 using DatReaderWriter;
 using DatReaderWriter.DBObjs;
 using DatReaderWriter.Types;
+using AcDream.Core.Physics;
 
 namespace AcDream.Core.Meshing;
 
@@ -42,7 +43,11 @@ public static class MotionResolver
     /// to <c>Setup.PlacementFrames</c>.
     /// </summary>
     /// <param name="setup">The entity's base Setup dat.</param>
-    /// <param name="dats">Dat collection used to load the linked MotionTable + Animation.</param>
+    /// <param name="dats">Dat collection used to load the linked MotionTable.</param>
+    /// <param name="animationLoader">
+    /// Central animation loader. Production uses the retail compatibility
+    /// reader so blocking-particle hooks retain their inherited payload.
+    /// </param>
     /// <param name="motionTableIdOverride">
     /// Optional override for the motion table id. Defaults to
     /// <c>Setup.DefaultMotionTable</c>. The server's CreateObject can
@@ -71,11 +76,14 @@ public static class MotionResolver
     public static IdleCycle? GetIdleCycle(
         Setup setup,
         DatCollection dats,
+        IAnimationLoader animationLoader,
         uint? motionTableIdOverride = null,
         ushort? stanceOverride = null,
         ushort? commandOverride = null)
     {
-        var resolved = ResolveIdleCycleInternal(setup, dats, motionTableIdOverride, stanceOverride, commandOverride);
+        var resolved = ResolveIdleCycleInternal(
+            setup, dats, animationLoader,
+            motionTableIdOverride, stanceOverride, commandOverride);
         if (resolved is null) return null;
         var (anim, ad) = resolved.Value;
 
@@ -116,11 +124,14 @@ public static class MotionResolver
     public static AnimationFrame? GetIdleFrame(
         Setup setup,
         DatCollection dats,
+        IAnimationLoader animationLoader,
         uint? motionTableIdOverride = null,
         ushort? stanceOverride = null,
         ushort? commandOverride = null)
     {
-        var resolved = ResolveIdleCycleInternal(setup, dats, motionTableIdOverride, stanceOverride, commandOverride);
+        var resolved = ResolveIdleCycleInternal(
+            setup, dats, animationLoader,
+            motionTableIdOverride, stanceOverride, commandOverride);
         if (resolved is null) return null;
         var (animation, animData) = resolved.Value;
         int frameIdx = animData.LowFrame;
@@ -138,12 +149,14 @@ public static class MotionResolver
     private static (Animation, AnimData)? ResolveIdleCycleInternal(
         Setup setup,
         DatCollection dats,
+        IAnimationLoader animationLoader,
         uint? motionTableIdOverride,
         ushort? stanceOverride,
         ushort? commandOverride)
     {
         ArgumentNullException.ThrowIfNull(setup);
         ArgumentNullException.ThrowIfNull(dats);
+        ArgumentNullException.ThrowIfNull(animationLoader);
 
         uint mtableId = motionTableIdOverride ?? (uint)setup.DefaultMotionTable;
         if (mtableId == 0) return null;
@@ -238,7 +251,7 @@ public static class MotionResolver
         uint animId = (uint)animData.AnimId;
         if (animId == 0) return null;
 
-        var animation = dats.Get<Animation>(animId);
+        var animation = animationLoader.LoadAnimation(animId);
         if (animation is null) return null;
         if (animation.PartFrames.Count == 0) return null;
 

src/AcDream.Core/Physics/AnimationSequencer.cs

@@ -2,7 +2,6 @@ using System;
 using System.Collections.Generic;
 using System.Numerics;
 using AcDream.Core.Physics.Motion;
-using DatReaderWriter;
 using DatReaderWriter.DBObjs;
 using DatReaderWriter.Enums;
 using DatReaderWriter.Types;
@@ -19,17 +18,6 @@ public interface IAnimationLoader
     Animation? LoadAnimation(uint id);
 }
 
-/// <summary>
-/// Production implementation of <see cref="IAnimationLoader"/> backed by
-/// a <see cref="DatCollection"/>.
-/// </summary>
-public sealed class DatCollectionLoader : IAnimationLoader
-{
-    private readonly DatCollection _dats;
-    public DatCollectionLoader(DatCollection dats) => _dats = dats;
-    public Animation? LoadAnimation(uint id) => _dats.Get<Animation>(id);
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // AnimationSequencer — adapter rehosted on the verbatim retail CSequence core
 // (R1-P5, docs/research/2026-07-02-r1-csequence/r1-gap-map.md §3 P5).
@@ -275,8 +263,8 @@ public sealed class AnimationSequencer
     /// <param name="setup">Entity's Setup dat (for part count / default scale).</param>
     /// <param name="motionTable">Loaded MotionTable dat for this entity.</param>
     /// <param name="loader">
-    /// Animation loader. Use <see cref="DatCollectionLoader"/> for production,
-    /// or inject a test double in unit tests.
+    /// Animation loader. Production supplies the centralized retail-compatible
+    /// content reader; unit tests may inject a test double.
     /// </param>
     public AnimationSequencer(Setup setup, MotionTable motionTable, IAnimationLoader loader)
     {

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;
+}