feat(physics #145): Slice 1 — Position/Frame types + LandDefs.GetBlockOffset (0x0043e630)

Introduces the two value types (Frame, Position) that represent retail's
cell-relative position pair (acclient.h:30647/30658). Types are unused
by consumers yet — zero behavior change. Also ports LandDefs::get_block_offset
(pc:69189, @0x0043e630): world-meter offset between two named landblock ids,
the ONLY cross-cell translation primitive in retail physics. Conformance tests:
same-landblock→Zero, south-neighbour→(0,-192,0) (the exact #145 cascade cell),
east-neighbour→(+192,0,0), diagonal→(+192,+192,0). 4/4 pass; full Core suite
1522 passed / 0 failed. DatFrame alias added to 4 files that had using
DatReaderWriter.Types + using AcDream.Core.Physics in scope simultaneously.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/AcDream.Core/Physics/LandDefs.cs

@@ -141,6 +141,34 @@ public static class LandDefs
         return false;
     }
 
+    /// <summary>
+    /// <c>LandDefs::get_block_offset</c> (pc:69189, @0x0043e630): world-meter offset
+    /// from <paramref name="source"/>'s landblock origin to <paramref name="dest"/>'s.
+    /// ZeroVector when both ids share a landblock (high words equal). The decomp's
+    /// <c>block_byte&lt;&lt;3</c> converts to lcoord (cell) units and the literal
+    /// <c>·24 m/cell</c> then nets to <c>(Δlandblock)·192 m</c> per axis. The
+    /// degenerate <c>arg==0</c> fallbacks are ported verbatim (dest==0 → raw source
+    /// id; source==0 → 0 lcoord). The ONLY cross-cell translation in retail physics:
+    /// a delta of two NAMED cell ids, never an accumulation against a moving center.
+    /// </summary>
+    public static Vector3 GetBlockOffset(uint source, uint dest)
+    {
+        uint srcBlock = source >> 16;
+        uint dstBlock = dest >> 16;
+        if (srcBlock == dstBlock)
+            return Vector3.Zero;
+
+        int srcLx, srcLy;
+        if (source == 0u) { srcLx = 0; srcLy = 0; }
+        else { srcLx = (int)((source >> 21) & 0x7f8u); srcLy = (int)((srcBlock & 0xFFu) << 3); }
+
+        int dstLx, dstLy;
+        if (dest == 0u) { dstLx = (int)source; dstLy = (int)source; }  // retail degenerate guard
+        else { dstLx = (int)((dest >> 21) & 0x7f8u); dstLy = (int)((dstBlock & 0xFFu) << 3); }
+
+        return new Vector3((dstLx - srcLx) * CellLength, (dstLy - srcLy) * CellLength, 0f);
+    }
+
     // Retail cell_in_range: landcell, envcell, or the block sentinel.
     private static bool CellLowInRange(uint low)
         => low is (>= 1u and <= 0x40u) or (>= 0x100u and <= 0xFFFDu) or 0xFFFFu;

src/AcDream.Core/Physics/Position.cs

@@ -0,0 +1,23 @@
+using System.Numerics;
+
+namespace AcDream.Core.Physics;
+
+/// <summary>
+/// Retail <c>Frame</c> (acclient.h:30647). <see cref="Origin"/> is LOCAL to the
+/// owning cell: outdoor → X/Y ∈ [0,192) within the landblock, Z = height;
+/// indoor → the EnvCell-relative placement. <see cref="Orientation"/> replaces
+/// retail's <c>m_fl2gv</c> 3×3 local→global matrix (equivalent rotation).
+/// </summary>
+public readonly record struct Frame(Vector3 Origin, Quaternion Orientation);
+
+/// <summary>
+/// Retail <c>Position</c> (acclient.h:30658): the (which-cell, where-inside) pair.
+/// One type for indoor and outdoor. The full 32-bit cell id (high 16 = landblock
+/// prefix, low 16 = cell index) plus the cell-local <see cref="Frame"/>. Neither
+/// half is ever reconstructed from a streaming center — see #145 design spec.
+/// </summary>
+public readonly record struct Position(uint ObjCellId, Frame Frame)
+{
+    public Position(uint objCellId, Vector3 origin, Quaternion orientation)
+        : this(objCellId, new Frame(origin, orientation)) { }
+}

src/AcDream.Core/Physics/ShadowShapeBuilder.cs

@@ -4,6 +4,7 @@ using System.Numerics;
 using DatReaderWriter.DBObjs;
 using DatReaderWriter.Enums;
 using DatReaderWriter.Types;
+using DatFrame = DatReaderWriter.Types.Frame;
 
 namespace AcDream.Core.Physics;
 
@@ -88,9 +89,9 @@ public static class ShadowShapeBuilder
             uint gfxId = (uint)setup.Parts[i];
             if (!hasPhysicsBsp(gfxId)) continue;
 
-            Frame partFrame = placementFrame is not null && i < placementFrame.Frames.Count
+            DatFrame partFrame = placementFrame is not null && i < placementFrame.Frames.Count
                 ? placementFrame.Frames[i]
-                : new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
+                : new DatFrame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
 
             // BSP radius default; caller substitutes the real BoundingSphere.Radius
             // at registration time when available. Loose-but-safe broadphase value.