erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

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

Browse source 
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>
This commit is contained in:
Erik 2026-06-21 10:30:20 +02:00
parent ed32db70d7
commit 438bb681a5
8 changed files with 115 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

28
src/AcDream.Core/Physics/LandDefs.cs
View file

@ -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;

23
src/AcDream.Core/Physics/Position.cs Normal file
View file

@ -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)) { }
}

5
src/AcDream.Core/Physics/ShadowShapeBuilder.cs
View file

@ -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.

17
tests/AcDream.Core.Tests/Physics/AnimationSequencerTests.cs
View file

@ -10,6 +10,7 @@ using Xunit;
// Alias the DatReaderWriter enum so it doesn't clash with
// AcDream.Core.Physics.MotionCommand (which is a static class of uint constants).
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
using DatFrame = DatReaderWriter.Types.Frame;
namespace AcDream.Core.Tests.Physics;
@ -65,7 +66,7 @@ file static class Fixtures
{
var pf = new AnimationFrame((uint)numParts);
for (int p = 0; p < numParts; p++)
pf.Frames.Add(new Frame { Origin = origin, Orientation = orientation });
pf.Frames.Add(new DatFrame { Origin = origin, Orientation = orientation });
anim.PartFrames.Add(pf);
}
return anim;
@ -86,8 +87,8 @@ file static class Fixtures
var pf1 = new AnimationFrame((uint)numParts);
for (int p = 0; p < numParts; p++)
{
pf0.Frames.Add(new Frame { Origin = fromOrigin, Orientation = fromRot });
pf1.Frames.Add(new Frame { Origin = toOrigin, Orientation = toRot });
pf0.Frames.Add(new DatFrame { Origin = fromOrigin, Orientation = fromRot });
pf1.Frames.Add(new DatFrame { Origin = toOrigin, Orientation = toRot });
}
anim.PartFrames.Add(pf0);
anim.PartFrames.Add(pf1);
@ -396,7 +397,7 @@ public sealed class AnimationSequencerTests
{
var pf = new AnimationFrame(1);
float y = 10f - 5f * f; // 10, 5, 0
pf.Frames.Add(new Frame { Origin = new Vector3(0, y, 0), Orientation = Quaternion.Identity });
pf.Frames.Add(new DatFrame { Origin = new Vector3(0, y, 0), Orientation = Quaternion.Identity });
linkAnim.PartFrames.Add(pf);
}
@ -593,7 +594,7 @@ public sealed class AnimationSequencerTests
for (int f = 0; f < 4; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
pf.Frames.Add(new DatFrame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
@ -1006,7 +1007,7 @@ public sealed class AnimationSequencerTests
anim.Flags = AnimationFlags.PosFrames;
for (int f = 0; f < 4; f++)
{
anim.PosFrames.Add(new Frame
anim.PosFrames.Add(new DatFrame
{
Origin = new Vector3(1f, 0f, 0f),
Orientation = Quaternion.Identity,
@ -1153,7 +1154,7 @@ public sealed class AnimationSequencerTests
for (int f = 0; f < 10; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
pf.Frames.Add(new DatFrame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
@ -1204,7 +1205,7 @@ public sealed class AnimationSequencerTests
for (int f = 0; f < 10; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
pf.Frames.Add(new DatFrame { Origin = new Vector3(0, 0, f), Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}

41
tests/AcDream.Core.Tests/Physics/LandDefsBlockOffsetTests.cs Normal file
View file

@ -0,0 +1,41 @@
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Tests.Physics;
public class LandDefsBlockOffsetTests
{
// get_block_offset(src, dst) returns the world-meter offset from src's
// landblock origin to dst's landblock origin. block_byte<<3 = lcoord, *24 m/cell
// → nets to (Δlandblock)·192 m. Same landblock → Zero. Decomp @0x0043e630.
[Fact]
public void SameLandblock_ReturnsZero()
{
// both 0xC95B
Assert.Equal(Vector3.Zero, LandDefs.GetBlockOffset(0xC95B0001u, 0xC95B0008u));
}
[Fact]
public void SouthNeighbour_IsMinus192Y()
{
// 0xC95B (lbY=0x5B) → 0xC95A (lbY=0x5A): one landblock south = (0,-192,0).
// This is the exact #145 case: correct origin for 0xC95A relative to 0xC95B.
Assert.Equal(new Vector3(0f, -192f, 0f), LandDefs.GetBlockOffset(0xC95B0001u, 0xC95A0001u));
}
[Fact]
public void EastNeighbour_IsPlus192X()
{
// 0xC95B (lbX=0xC9) → 0xCA5B (lbX=0xCA): one landblock east = (+192,0,0).
Assert.Equal(new Vector3(192f, 0f, 0f), LandDefs.GetBlockOffset(0xC95B0001u, 0xCA5B0001u));
}
[Fact]
public void DiagonalNeighbour_CombinesBothAxes()
{
// 0xC95B → 0xCA5C: lbX +1 (+192), lbY +1 (+192).
Assert.Equal(new Vector3(192f, 192f, 0f), LandDefs.GetBlockOffset(0xC95B0001u, 0xCA5C0001u));
}
}

7
tests/AcDream.Core.Tests/Physics/ShadowShapeBuilderTests.cs
View file

@ -6,6 +6,7 @@ using DatReaderWriter.DBObjs;
using DatReaderWriter.Enums;
using DatReaderWriter.Types;
using Xunit;
using DatFrame = DatReaderWriter.Types.Frame;
namespace AcDream.Core.Tests.Physics;
@ -37,9 +38,9 @@ public class ShadowShapeBuilderTests
{
Frames =
{
new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity },
new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity },
new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity }
new DatFrame { Origin = Vector3.Zero, Orientation = Quaternion.Identity },
new DatFrame { Origin = Vector3.Zero, Orientation = Quaternion.Identity },
new DatFrame { Origin = Vector3.Zero, Orientation = Quaternion.Identity }
}
}
}

9
tests/AcDream.Core.Tests/Rendering/Vfx/EntityScriptActivatorTests.cs
View file

@ -7,6 +7,7 @@ using AcDream.Core.World;
using DatReaderWriter.Types;
using Xunit;
using DatPhysicsScript = DatReaderWriter.DBObjs.PhysicsScript;
using DatFrame = DatReaderWriter.Types.Frame;
namespace AcDream.Core.Tests.Rendering.Vfx;
@ -140,7 +141,7 @@ public sealed class EntityScriptActivatorTests
var hookSink = new ParticleHookSink(system);
// Hook offset = (1, 0, 0) in entity-local frame.
var hookOffset = new Frame
var hookOffset = new DatFrame
{
Origin = new Vector3(1f, 0f, 0f),
Orientation = Quaternion.Identity,
@ -194,7 +195,7 @@ public sealed class EntityScriptActivatorTests
var system = new ParticleSystem(registry);
var hookSink = new ParticleHookSink(system);
var script = BuildScript((0.0, new CreateParticleHook { EmitterInfoId = 100u, Offset = new Frame() }));
var script = BuildScript((0.0, new CreateParticleHook { EmitterInfoId = 100u, Offset = new DatFrame() }));
var table = new Dictionary<uint, DatPhysicsScript> { [0xAAu] = script };
var runner = new PhysicsScriptRunner(
id => table.TryGetValue(id, out var s) ? s : null,
@ -257,7 +258,7 @@ public sealed class EntityScriptActivatorTests
var system = new ParticleSystem(registry);
var hookSink = new ParticleHookSink(system);
var hookOffset = new Frame { Origin = new Vector3(1f, 0, 0), Orientation = Quaternion.Identity };
var hookOffset = new DatFrame { Origin = new Vector3(1f, 0, 0), Orientation = Quaternion.Identity };
var script = BuildScript(
(0.0, new CreateParticleHook { EmitterInfoId = 100u, Offset = hookOffset, PartIndex = 1 }));
var table = new Dictionary<uint, DatPhysicsScript> { [0xAAu] = script };
@ -297,7 +298,7 @@ public sealed class EntityScriptActivatorTests
var system = new ParticleSystem(registry);
var hookSink = new ParticleHookSink(system);
var script = BuildScript((0.0, new CreateParticleHook { EmitterInfoId = 100u, Offset = new Frame() }));
var script = BuildScript((0.0, new CreateParticleHook { EmitterInfoId = 100u, Offset = new DatFrame() }));
var table = new Dictionary<uint, DatPhysicsScript> { [0xAAu] = script };
var runner = new PhysicsScriptRunner(
id => table.TryGetValue(id, out var s) ? s : null,

3
tests/AcDream.Core.Tests/Streaming/GpuWorldStateActivatorTests.cs
View file

@ -10,6 +10,7 @@ using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using Xunit;
using DatPhysicsScript = DatReaderWriter.DBObjs.PhysicsScript;
using DatFrame = DatReaderWriter.Types.Frame;
namespace AcDream.Core.Tests.Streaming;
@ -43,7 +44,7 @@ public sealed class GpuWorldStateActivatorTests
script.ScriptData.Add(new PhysicsScriptData
{
StartTime = 0.0,
Hook = new CreateParticleHook { EmitterInfoId = 100u, Offset = new Frame() },
Hook = new CreateParticleHook { EmitterInfoId = 100u, Offset = new DatFrame() },
});
var table = new Dictionary<uint, DatPhysicsScript> { [scriptId] = script };