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.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.");
+    }
+}