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.App/Rendering/EquippedChildRenderController.cs

@@ -230,6 +230,18 @@ public sealed class EquippedChildRenderController : IDisposable
                 out IReadOnlyList<MeshRef> parts))
             return;
 
+        // A parented object may materialize here before the ordinary world
+        // hydration path sees it. Install its logical effect profile before
+        // MaterializeLiveEntity registers runtime resources, exactly as for a
+        // top-level projection; rebucketing/reattachment must never recreate it.
+        if (!_liveEntities.TryGetEffectProfile(childGuid, out _))
+        {
+            var effectProfile = childSpawn.Physics is { } physics
+                ? Vfx.EntityEffectProfile.CreateLive(childSetup, physics)
+                : Vfx.EntityEffectProfile.CreateDatStatic(childSetup);
+            _liveEntities.SetEffectProfile(childGuid, effectProfile);
+        }
+
         Remove(childGuid);
         WorldEntity? entity = _liveEntities.MaterializeLiveEntity(
             childGuid,

src/AcDream.App/Rendering/GameWindow.cs

@@ -313,7 +313,7 @@ public sealed class GameWindow : IDisposable
         AcDream.Core.World.WorldEntity Entity,
         AnimatedEntity? Animation);
 
-    private AcDream.Core.Physics.DatCollectionLoader? _animLoader;
+    private AcDream.Core.Physics.IAnimationLoader? _animLoader;
 
     // Phase E.1: central fan-out for animation hooks. Audio (E.2),
     // particles (E.3), combat (E.4), and renderer state mutators all
@@ -336,6 +336,7 @@ public sealed class GameWindow : IDisposable
     // from the server and schedules the dat-defined hooks (particle spawns,
     // sounds, light toggles) at their StartTime offsets.
     private AcDream.Core.Vfx.PhysicsScriptRunner? _scriptRunner;
+    private AcDream.Content.Vfx.RetailPhysicsScriptLoader? _physicsScriptLoader;
     private AcDream.App.Rendering.ParticleRenderer? _particleRenderer;
     // Retail GameSky copies SkyObject.PesObjectId into CelestialPosition but
     // never consumes it in CreateDeletePhysicsObjects/MakeObject/UseTime.
@@ -1432,7 +1433,7 @@ public sealed class GameWindow : IDisposable
         _cameraController.ModeChanged += OnCameraModeChanged;
 
         _dats = new DatCollection(_datDir, DatAccessType.Read);
-        _animLoader = new AcDream.Core.Physics.DatCollectionLoader(_dats);
+        _animLoader = new AcDream.Content.Vfx.RetailAnimationLoader(_dats);
         _emitterRegistry = new AcDream.Core.Vfx.EmitterDescRegistry(_dats);
 
         // Phase E.3 particles: always-on, no driver dependency. Registered
@@ -1447,7 +1448,10 @@ public sealed class GameWindow : IDisposable
         // resolve PlayScript ids, and the same ParticleHookSink the
         // animation system uses, so CreateParticleHook fired from a
         // script spawns through the normal particle pipeline.
-        _scriptRunner = new AcDream.Core.Vfx.PhysicsScriptRunner(_dats, _particleSink);
+        _physicsScriptLoader = new AcDream.Content.Vfx.RetailPhysicsScriptLoader(_dats);
+        _scriptRunner = new AcDream.Core.Vfx.PhysicsScriptRunner(
+            _physicsScriptLoader.LoadPhysicsScript,
+            _particleSink);
 
         // Phase G.2 lighting hooks: SetLightHook flips IsLit on
         // owner-tagged lights so ignite-torch animations light up,
@@ -3319,7 +3323,7 @@ public sealed class GameWindow : IDisposable
         // animated entry registered) — this happens for entities the
         // resolver short-circuits on.
         var idleCycle = AcDream.Core.Meshing.MotionResolver.GetIdleCycle(
-            setup, _dats,
+            setup, _dats, _animLoader!,
             motionTableIdOverride: spawn.MotionTableId,
             stanceOverride: stanceOverride,
             commandOverride: commandOverride);
@@ -3688,6 +3692,14 @@ public sealed class GameWindow : IDisposable
             return;
         }
 
+        if (!_liveEntities!.TryGetEffectProfile(spawn.Guid, out _))
+        {
+            var effectProfile = spawn.Physics is { } physics
+                ? AcDream.App.Rendering.Vfx.EntityEffectProfile.CreateLive(setup, physics)
+                : AcDream.App.Rendering.Vfx.EntityEffectProfile.CreateDatStatic(setup);
+            _liveEntities.SetEffectProfile(spawn.Guid, effectProfile);
+        }
+
         bool createdProjection = false;
         var entity = _liveEntities!.MaterializeLiveEntity(
             spawn.Guid,
@@ -4169,7 +4181,7 @@ public sealed class GameWindow : IDisposable
         // garbage frame count → OOM).
         uint poseDid = ResolvePaperdollPoseDid();
         if ((poseDid >> 24) != 0x03u) return;
-        var anim  = dats.Get<DatReaderWriter.DBObjs.Animation>(poseDid);
+        var anim  = _animLoader?.LoadAnimation(poseDid);
         var setup = dats.Get<DatReaderWriter.DBObjs.Setup>(setupId);
         if (anim is null || setup is null || anim.PartFrames.Count == 0) return;
 
@@ -4361,6 +4373,14 @@ public sealed class GameWindow : IDisposable
     private void RouteSameGenerationCreateObject(
         AcDream.App.World.SameGenerationCreateObjectEvents refresh)
     {
+        if (_liveEntities!.TryGetEffectProfile(
+                refresh.Appearance.Guid,
+                out var effectProfile)
+            && effectProfile is AcDream.App.Rendering.Vfx.EntityEffectProfile liveProfile)
+        {
+            liveProfile.ApplyNetworkDescription(refresh.Description);
+        }
+
         OnLiveAppearanceUpdated(refresh.Appearance);
 
         if (refresh.Parent is { } parent
@@ -4481,7 +4501,7 @@ public sealed class GameWindow : IDisposable
         if (mt is null) return null;
 
         var pose = AcDream.Core.Physics.Motion.MotionTablePose.DefaultStatePartFrames(
-            mt, id => _dats.Get<DatReaderWriter.DBObjs.Animation>(id));
+            mt, id => _animLoader?.LoadAnimation(id));
 
         if (Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOTION") == "1")
         {
@@ -5464,7 +5484,7 @@ public sealed class GameWindow : IDisposable
         // a concrete Animation + frame range. Only swap when the resolver
         // returns a clearly-better cycle.
         var newCycle = AcDream.Core.Meshing.MotionResolver.GetIdleCycle(
-            ae.Setup, _dats,
+            ae.Setup, _dats, _animLoader!,
             motionTableIdOverride: null,
             stanceOverride: stance,
             commandOverride: command);

src/AcDream.App/Rendering/RenderBootstrap.cs

@@ -135,7 +135,7 @@ public static class RenderBootstrap
         var textureCache = new TextureCache(gl, dats, bindless);
 
         // --- AnimLoader (GameWindow ~1240) ---
-        var animLoader = new AcDream.Core.Physics.DatCollectionLoader(dats);
+        var animLoader = new AcDream.Content.Vfx.RetailAnimationLoader(dats);
 
         // --- WbMeshAdapter (GameWindow ~2286-2287) ---
         var wbLogger     = NullLogger<Wb.WbMeshAdapter>.Instance;

src/AcDream.App/Rendering/Vfx/EntityEffectProfile.cs

@@ -0,0 +1,73 @@
+using AcDream.App.World;
+using AcDream.Core.Net.Messages;
+using AcDream.Core.Vfx;
+using DatReaderWriter.DBObjs;
+
+namespace AcDream.App.Rendering.Vfx;
+
+/// <summary>
+/// DAT defaults and the currently installed network effect description for
+/// one logical entity incarnation.
+/// </summary>
+/// <remarks>
+/// Retail precedence comes from <c>CPhysicsObj::InitDefaults</c>
+/// (<c>0x005139D0</c>) followed by <c>CPhysicsObj::set_description</c>
+/// (<c>0x00514F40</c>). Setup's direct default PES runs during initialization;
+/// a network PhysicsDesc then unconditionally replaces the typed table, even
+/// when PeTable was absent or zero.
+/// </remarks>
+public sealed class EntityEffectProfile : ILiveEntityEffectProfile
+{
+    private EntityEffectProfile(Setup setup)
+    {
+        SetupDefaultScriptDid = NormalizePhysicsScriptDid(setup.DefaultScript.DataId);
+        CurrentPhysicsScriptTableDid = NormalizeTableDid((uint)setup.DefaultScriptTable);
+    }
+
+    public uint? SetupDefaultScriptDid { get; }
+    public uint? CurrentPhysicsScriptTableDid { get; private set; }
+    public uint RawDefaultScriptType { get; private set; }
+    public float DefaultScriptIntensity { get; private set; }
+    public bool HasNetworkDescription { get; private set; }
+
+    /// <summary>Setup defaults remain active for a DAT/static object.</summary>
+    public static EntityEffectProfile CreateDatStatic(Setup setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        return new EntityEffectProfile(setup);
+    }
+
+    /// <summary>
+    /// Applies Setup initialization followed by the live PhysicsDesc, matching
+    /// retail construction order.
+    /// </summary>
+    public static EntityEffectProfile CreateLive(
+        Setup setup,
+        PhysicsSpawnData physics)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var profile = new EntityEffectProfile(setup);
+        profile.ApplyNetworkDescription(physics);
+        return profile;
+    }
+
+    /// <summary>
+    /// Replaces all network-owned effect defaults. Nullable wire fields use
+    /// PhysicsDesc's initialized zero values; they never resurrect Setup's
+    /// typed table.
+    /// </summary>
+    public void ApplyNetworkDescription(PhysicsSpawnData physics)
+    {
+        CurrentPhysicsScriptTableDid = NormalizeTableDid(
+            physics.PhysicsScriptTableId.GetValueOrDefault());
+        RawDefaultScriptType = physics.DefaultScriptType.GetValueOrDefault();
+        DefaultScriptIntensity = physics.DefaultScriptIntensity.GetValueOrDefault();
+        HasNetworkDescription = true;
+    }
+
+    private static uint? NormalizePhysicsScriptDid(uint did) =>
+        PhysicsScriptTableResolver.IsPhysicsScriptDid(did) ? did : null;
+
+    private static uint? NormalizeTableDid(uint did) =>
+        PhysicsScriptTableResolver.IsPhysicsScriptTableDid(did) ? did : null;
+}

src/AcDream.App/World/InboundPhysicsStateController.cs

@@ -542,6 +542,7 @@ public sealed class InboundPhysicsStateController
                 : null;
 
         return new SameGenerationCreateObjectEvents(
+            physics,
             new ObjDescEvent.Parsed(
                 incoming.Guid,
                 new CreateObject.ModelData(
@@ -632,6 +633,7 @@ public readonly record struct CreateParentUpdate(
     ushort ChildPositionSequence);
 
 public readonly record struct SameGenerationCreateObjectEvents(
+    PhysicsSpawnData Description,
     ObjDescEvent.Parsed Appearance,
     CreateParentUpdate? Parent,
     WorldSession.EntityPositionUpdate? Position,

src/AcDream.App/World/LiveEntityRuntime.cs

@@ -477,6 +477,30 @@ public sealed class LiveEntityRuntime
         return true;
     }
 
+    public void SetEffectProfile(uint serverGuid, ILiveEntityEffectProfile profile)
+    {
+        ArgumentNullException.ThrowIfNull(profile);
+        if (!_recordsByGuid.TryGetValue(serverGuid, out LiveEntityRecord? record))
+            throw new InvalidOperationException(
+                $"Cannot bind an effect profile before live entity 0x{serverGuid:X8} exists.");
+        record.EffectProfile = profile;
+    }
+
+    public bool TryGetEffectProfile(
+        uint serverGuid,
+        out ILiveEntityEffectProfile profile)
+    {
+        if (_recordsByGuid.TryGetValue(serverGuid, out LiveEntityRecord? record)
+            && record.EffectProfile is { } found)
+        {
+            profile = found;
+            return true;
+        }
+
+        profile = null!;
+        return false;
+    }
+
     public bool TryGetSnapshot(uint guid, out WorldSession.EntitySpawn spawn) =>
         _inbound.TryGetSnapshot(guid, out spawn);
 

src/AcDream.Content/MeshExtractor.cs

@@ -1,4 +1,5 @@
 using AcDream.Core.Rendering.Wb;
+using AcDream.Content.Vfx;
 using BCnEncoder.Decoder;
 using BCnEncoder.ImageSharp;
 using BCnEncoder.Shared;
@@ -31,6 +32,7 @@ namespace AcDream.Content;
 public sealed class MeshExtractor {
     private readonly IDatReaderWriter _dats;
     private readonly ILogger _logger;
+    private readonly RetailPhysicsScriptLoader _physicsScripts;
 
     // Cache for decoded textures to avoid redundant BCn decoding
     private readonly ConcurrentQueue<uint> _decodedTextureLru = new();
@@ -60,6 +62,7 @@ public sealed class MeshExtractor {
         _dats = dats;
         _logger = logger;
         _sideStagedSink = sideStagedSink;
+        _physicsScripts = new RetailPhysicsScriptLoader(dats.Portal);
     }
 
     /// <summary>
@@ -151,9 +154,10 @@ public sealed class MeshExtractor {
     }
 
     private void CollectEmittersFromScript(uint scriptId, List<StagedEmitter> emitters, CancellationToken ct) {
-        if (_dats.Portal.TryGet<PhysicsScript>(scriptId, out var script)) {
+        var script = _physicsScripts.LoadPhysicsScript(scriptId);
+        if (script is not null) {
             foreach (var hook in script.ScriptData) {
-                if (hook.Hook.HookType == AnimationHookType.CreateParticle && hook.Hook is CreateParticleHook particleHook) {
+                if (hook.Hook is CreateParticleHook particleHook) {
                     if (_dats.Portal.TryGet<ParticleEmitter>(particleHook.EmitterInfoId.DataId, out var emitter)) {
                          emitters.Add(new StagedEmitter {
                              Emitter = emitter,

src/AcDream.Content/Vfx/RetailAnimationHookReader.cs

@@ -0,0 +1,48 @@
+using AcDream.Core.Vfx;
+using DatReaderWriter.Enums;
+using DatReaderWriter.Lib.IO;
+using DatReaderWriter.Types;
+
+namespace AcDream.Content.Vfx;
+
+/// <summary>
+/// Narrow compatibility seam for the one retail hook schema that
+/// Chorizite.DatReaderWriter 2.1.7 decodes incorrectly.
+/// </summary>
+/// <remarks>
+/// Retail container dispatch is ported from <c>AnimFrame::UnPack</c>
+/// (<c>0x0051F8E0</c>) and <c>PhysicsScript::UnPack</c>
+/// (<c>0x005218B0</c>). The substituted payload shape is proven by
+/// <c>CreateBlockingParticleHook::Execute</c> (<c>0x00526EF0</c>).
+/// </remarks>
+public static class RetailAnimationHookReader
+{
+    /// <summary>
+    /// Reads one hook at the current cursor. Ordinary hooks are delegated to
+    /// the package decoder; CreateBlockingParticle is decoded through the
+    /// retail CreateParticle-shaped model.
+    /// </summary>
+    public static AnimationHook Read(DatBinReader reader)
+    {
+        ArgumentNullException.ThrowIfNull(reader);
+
+        // PhysicsScriptData::UnPack / AnimFrame::UnPack peek the type and
+        // restore the cursor before dispatch. Preserve that exact contract so
+        // the selected hook consumes its own shared header exactly once.
+        var type = (AnimationHookType)reader.ReadUInt32();
+        reader.Skip(-sizeof(uint));
+
+        AnimationHook? hook = type is AnimationHookType.CreateBlockingParticle
+            ? new RetailCreateBlockingParticleHook()
+            : AnimationHook.Unpack(reader, type);
+
+        if (hook is null)
+            throw new InvalidDataException(
+                $"Unsupported animation hook type 0x{(uint)type:X8} at byte {reader.Offset}.");
+
+        if (type is AnimationHookType.CreateBlockingParticle)
+            hook.Unpack(reader);
+
+        return hook;
+    }
+}

src/AcDream.Content/Vfx/RetailAnimationLoader.cs

@@ -0,0 +1,108 @@
+using System.Collections.Concurrent;
+using AcDream.Core.Physics;
+using DatReaderWriter;
+using DatReaderWriter.DBObjs;
+using DatReaderWriter.Enums;
+using DatReaderWriter.Lib.IO;
+using DatReaderWriter.Types;
+
+namespace AcDream.Content.Vfx;
+
+/// <summary>
+/// Raw Animation loader using <see cref="RetailAnimationHookReader"/> for
+/// frame hooks and the package's ordinary Frame model for transforms.
+/// </summary>
+/// <remarks>
+/// Container order and field widths match <c>CAnimation::UnPack</c> at
+/// <c>0x0051FB50</c> and <c>AnimFrame::UnPack</c> at <c>0x0051F8E0</c>.
+/// </remarks>
+public sealed class RetailAnimationLoader : IAnimationLoader
+{
+    private readonly Func<uint, byte[]?> _readRaw;
+    private readonly DatDatabase? _database;
+    private readonly ConcurrentDictionary<uint, Lazy<Animation?>> _cache = new();
+
+    public RetailAnimationLoader(DatCollection dats)
+    {
+        ArgumentNullException.ThrowIfNull(dats);
+        _database = dats.Portal;
+        _readRaw = id => dats.Portal.TryGetFileBytes(id, out byte[]? bytes)
+            ? bytes
+            : null;
+    }
+
+    public RetailAnimationLoader(IDatDatabase portal)
+    {
+        ArgumentNullException.ThrowIfNull(portal);
+        _database = portal.Db;
+        _readRaw = id => portal.TryGetFileBytes(id, out byte[]? bytes)
+            ? bytes
+            : null;
+    }
+
+    public Animation? LoadAnimation(uint id)
+    {
+        if (!IsAnimationDid(id))
+            return null;
+
+        return _cache.GetOrAdd(
+            id,
+            key => new Lazy<Animation?>(
+                () => LoadUncached(key),
+                LazyThreadSafetyMode.ExecutionAndPublication)).Value;
+    }
+
+    private Animation? LoadUncached(uint id)
+    {
+        byte[]? bytes = _readRaw(id);
+        if (bytes is null)
+            return null;
+
+        Animation animation = Parse(bytes, _database);
+        if (animation.Id != id)
+            throw new InvalidDataException(
+                $"Animation entry 0x{id:X8} contained id 0x{animation.Id:X8}.");
+        return animation;
+    }
+
+    public static Animation Parse(
+        ReadOnlyMemory<byte> bytes,
+        DatDatabase? database = null)
+    {
+        var reader = new DatBinReader(bytes, database);
+        var animation = new Animation
+        {
+            Id = reader.ReadUInt32(),
+            Flags = (AnimationFlags)reader.ReadUInt32(),
+            NumParts = reader.ReadUInt32(),
+        };
+        uint frameCount = reader.ReadUInt32();
+
+        if ((animation.Flags & AnimationFlags.PosFrames) != 0)
+        {
+            for (uint i = 0; i < frameCount; i++)
+                animation.PosFrames.Add(reader.ReadItem<Frame>());
+        }
+
+        for (uint frameIndex = 0; frameIndex < frameCount; frameIndex++)
+        {
+            var frame = new AnimationFrame(animation.NumParts);
+            for (uint partIndex = 0; partIndex < animation.NumParts; partIndex++)
+                frame.Frames.Add(reader.ReadItem<Frame>());
+
+            uint hookCount = reader.ReadUInt32();
+            for (uint hookIndex = 0; hookIndex < hookCount; hookIndex++)
+                frame.Hooks.Add(RetailAnimationHookReader.Read(reader));
+            animation.PartFrames.Add(frame);
+        }
+
+        if (reader.Offset != reader.Length)
+            throw new InvalidDataException(
+                $"Animation 0x{animation.Id:X8} consumed {reader.Offset} of {reader.Length} bytes.");
+        return animation;
+    }
+
+    public static bool IsAnimationDid(uint did) =>
+        // AC data IDs reserve only the high byte for DBObj type.
+        (did & 0xFF000000u) == 0x03000000u;
+}

src/AcDream.Content/Vfx/RetailPhysicsScriptLoader.cs

@@ -0,0 +1,109 @@
+using System.Collections.Concurrent;
+using DatReaderWriter;
+using DatReaderWriter.DBObjs;
+using DatReaderWriter.Lib.IO;
+using DatReaderWriter.Types;
+using DatPhysicsScript = DatReaderWriter.DBObjs.PhysicsScript;
+
+namespace AcDream.Content.Vfx;
+
+/// <summary>
+/// Raw PhysicsScript loader that substitutes the retail hook reader while
+/// leaving every ordinary hook in Chorizite.DatReaderWriter's decoder.
+/// </summary>
+/// <remarks>
+/// Container order and field widths match <c>PhysicsScript::UnPack</c> at
+/// <c>0x005218B0</c>.
+/// </remarks>
+public sealed class RetailPhysicsScriptLoader
+{
+    private readonly Func<uint, byte[]?> _readRaw;
+    private readonly DatDatabase? _database;
+    private readonly ConcurrentDictionary<uint, Lazy<DatPhysicsScript?>> _cache = new();
+
+    public RetailPhysicsScriptLoader(DatCollection dats)
+    {
+        ArgumentNullException.ThrowIfNull(dats);
+        _database = dats.Portal;
+        _readRaw = id => dats.Portal.TryGetFileBytes(id, out byte[]? bytes)
+            ? bytes
+            : null;
+    }
+
+    public RetailPhysicsScriptLoader(IDatDatabase portal)
+    {
+        ArgumentNullException.ThrowIfNull(portal);
+        _database = portal.Db;
+        _readRaw = id => portal.TryGetFileBytes(id, out byte[]? bytes)
+            ? bytes
+            : null;
+    }
+
+    /// <summary>Loads and caches one immutable portal-DAT PhysicsScript.</summary>
+    public DatPhysicsScript? LoadPhysicsScript(uint id)
+    {
+        if (!AcDream.Core.Vfx.PhysicsScriptTableResolver.IsPhysicsScriptDid(id))
+            return null;
+
+        return _cache.GetOrAdd(
+            id,
+            key => new Lazy<DatPhysicsScript?>(
+                () => LoadUncached(key),
+                LazyThreadSafetyMode.ExecutionAndPublication)).Value;
+    }
+
+    private DatPhysicsScript? LoadUncached(uint id)
+    {
+        byte[]? bytes = _readRaw(id);
+        if (bytes is null)
+            return null;
+
+        DatPhysicsScript script = Parse(bytes, _database);
+        if (script.Id != id)
+            throw new InvalidDataException(
+                $"PhysicsScript entry 0x{id:X8} contained id 0x{script.Id:X8}.");
+        return script;
+    }
+
+    /// <summary>
+    /// Parses a complete raw DAT entry. Full consumption is part of the
+    /// contract: a malformed hook cannot silently shift the following entry.
+    /// </summary>
+    public static DatPhysicsScript Parse(
+        ReadOnlyMemory<byte> bytes,
+        DatDatabase? database = null)
+    {
+        var reader = new DatBinReader(bytes, database);
+        var script = new DatPhysicsScript
+        {
+            Id = reader.ReadUInt32(),
+        };
+
+        uint count = reader.ReadUInt32();
+        for (uint i = 0; i < count; i++)
+        {
+            script.ScriptData.Add(new PhysicsScriptData
+            {
+                StartTime = reader.ReadDouble(),
+                Hook = RetailAnimationHookReader.Read(reader),
+            });
+        }
+
+        // PhysicsScript::UnPack 0x005218B0 qsorts the decoded pointer array
+        // with PhysicsScriptData::Sort 0x00521600 before publishing its tail.
+        // The runtime consumes one forward cursor, so this is behavioral—not
+        // merely canonicalization of the DAT representation.
+        script.ScriptData.Sort(static (left, right) =>
+            left.StartTime.CompareTo(right.StartTime));
+
+        EnsureFullyConsumed(reader, nameof(DatPhysicsScript), script.Id);
+        return script;
+    }
+
+    private static void EnsureFullyConsumed(DatBinReader reader, string type, uint id)
+    {
+        if (reader.Offset != reader.Length)
+            throw new InvalidDataException(
+                $"{type} 0x{id:X8} consumed {reader.Offset} of {reader.Length} bytes.");
+    }
+}

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