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

Merge branch 'main' into claude/peaceful-visvesvaraya-e0a196

Browse source 
# Conflicts:
#	docs/ISSUES.md
#	docs/architecture/retail-divergence-register.md
This commit is contained in:
Erik 2026-07-09 23:18:52 +02:00
commit 217a4bad69
329 changed files with 81439 additions and 8499 deletions
Download patch file Download diff file Expand all files Collapse all files

49
tests/AcDream.App.Tests/FrameProfilerReportTests.cs Normal file
View file

@ -0,0 +1,49 @@
using AcDream.App.Diagnostics;
using Xunit;
namespace AcDream.App.Tests;
public class FrameProfilerReportTests
{
[Fact]
public void FormatReport_IsInvariantAndComplete()
{
var cpu = new FrameStatsBuffer(16);
var gpu = new FrameStatsBuffer(16);
var alloc = new FrameStatsBuffer(16);
var stages = new[] { new FrameStatsBuffer(16), new FrameStatsBuffer(16), new FrameStatsBuffer(16) };
for (long i = 1; i <= 10; i++)
{
cpu.Push(i * 1000); // 1..10 ms in µs
gpu.Push(i * 100);
alloc.Push(i * 1024); // bytes
stages[0].Push(i * 200);
stages[1].Push(i * 50);
stages[2].Push(i * 10);
}
string line = FrameProfiler.FormatReport(
frameCount: 10, cpu: cpu, gpu: gpu, gpuActive: true,
alloc: alloc, gc0: 3, gc1: 1, gc2: 0, stages: stages);
Assert.StartsWith("[frame-prof]", line);
Assert.Contains("n=10", line);
Assert.Contains("cpu_ms p50=5.0 p95=10.0 p99=10.0 max=10.0", line);
Assert.Contains("gpu_ms p50=0.5", line);
Assert.Contains("alloc_kb p50=5.0 max=10.0", line);
Assert.Contains("gc=3/1/0", line);
Assert.Contains("upd p50=1.0", line); // stage 0: 200µs·5 = 1.0 ms
Assert.DoesNotContain(",0", line.Replace("gc=3/1/0", "")); // no comma decimals (invariant culture)
}
[Fact]
public void FormatReport_GpuInactive_SaysWhy()
{
var empty = new FrameStatsBuffer(4);
string line = FrameProfiler.FormatReport(
frameCount: 0, cpu: empty, gpu: empty, gpuActive: false,
alloc: empty, gc0: 0, gc1: 0, gc2: 0,
stages: new[] { empty, empty, empty });
Assert.Contains("gpu=off(wbdiag)", line);
}
}

59
tests/AcDream.App.Tests/FrameStatsBufferTests.cs Normal file
View file

@ -0,0 +1,59 @@
using AcDream.App.Diagnostics;
using Xunit;
namespace AcDream.App.Tests;
public class FrameStatsBufferTests
{
[Fact]
public void Percentiles_OnKnownDistribution_AreExact()
{
var buf = new FrameStatsBuffer(capacity: 100);
// 1..100 µs — p50 = 50, p95 = 95, p99 = 99, max = 100.
for (long i = 1; i <= 100; i++) buf.Push(i);
Assert.Equal(50, buf.Percentile(0.50));
Assert.Equal(95, buf.Percentile(0.95));
Assert.Equal(99, buf.Percentile(0.99));
Assert.Equal(100, buf.Max());
}
[Fact]
public void Push_PastCapacity_KeepsOnlyNewestWindow()
{
var buf = new FrameStatsBuffer(capacity: 4);
foreach (long v in new long[] { 1000, 1000, 1000, 1000, 1, 2, 3, 4 })
buf.Push(v);
// The four 1000s were overwritten; window is {1,2,3,4}.
Assert.Equal(4, buf.Count);
Assert.Equal(4, buf.Max());
Assert.Equal(2, buf.Percentile(0.50));
}
[Fact]
public void Percentile_Empty_ReturnsZero()
{
var buf = new FrameStatsBuffer(capacity: 8);
Assert.Equal(0, buf.Percentile(0.95));
Assert.Equal(0, buf.Max());
Assert.Equal(0, buf.Count);
}
[Fact]
public void Reset_ClearsWindow()
{
var buf = new FrameStatsBuffer(capacity: 8);
buf.Push(5); buf.Push(7);
buf.Reset();
Assert.Equal(0, buf.Count);
Assert.Equal(0, buf.Percentile(0.5));
}
[Fact]
public void Max_AllNegative_ReturnsTrueMax()
{
var buf = new FrameStatsBuffer(capacity: 4);
buf.Push(-5); buf.Push(-2); buf.Push(-9);
Assert.Equal(-2, buf.Max());
}
}

8
tests/AcDream.App.Tests/Rendering/CornerFloodReplayTests.cs
View file

@ -88,7 +88,6 @@ public class CornerFloodReplayTests
var portals = new List<CellPortalInfo>();
var clipPlanes = new List<PortalClipPlane>();
var portalPolygons = new List<Vector3[]>();
var centroid = (boundsMin + boundsMax) * 0.5f;
foreach (var portal in envCell.CellPortals)
{
@ -106,10 +105,13 @@ public class CornerFloodReplayTests
var p2 = new Vector3(v2.Origin.X, v2.Origin.Y, v2.Origin.Z);
var normal = Vector3.Normalize(Vector3.Cross(p1 - p0, p2 - p0));
float d = -Vector3.Dot(normal, p0);
float centroidDot = Vector3.Dot(normal, centroid) + d;
// InsideSide from the dat PortalSide bit — mirrors the production fix
// (GameWindow.BuildLoadedCell): retail InitCell (0x005a4b70) + physics
// CellTransit use the dat bit; the old AABB-centroid guess mis-sided thin
// connectors (#186). Kept identical here so this replay stays a faithful mirror.
clipPlanes.Add(new PortalClipPlane
{
Normal = normal, D = d, InsideSide = centroidDot >= 0 ? 0 : 1,
Normal = normal, D = d, InsideSide = ((ushort)portal.Flags & 0x2) == 0 ? 1 : 0,
});
}
else

8
tests/AcDream.App.Tests/Rendering/Issue113MeetingHallFloodTests.cs
View file

@ -77,7 +77,6 @@ public class Issue113MeetingHallFloodTests
var portals = new List<CellPortalInfo>();
var clipPlanes = new List<PortalClipPlane>();
var portalPolygons = new List<Vector3[]>();
var centroid = (boundsMin + boundsMax) * 0.5f;
foreach (var portal in envCell.CellPortals)
{
@ -95,10 +94,13 @@ public class Issue113MeetingHallFloodTests
var p2 = new Vector3(v2.Origin.X, v2.Origin.Y, v2.Origin.Z);
var normal = Vector3.Normalize(Vector3.Cross(p1 - p0, p2 - p0));
float d = -Vector3.Dot(normal, p0);
float centroidDot = Vector3.Dot(normal, centroid) + d;
// InsideSide from the dat PortalSide bit — mirrors the production fix
// (GameWindow.BuildLoadedCell): retail InitCell (0x005a4b70) + physics
// CellTransit use the dat bit; the old AABB-centroid guess mis-sided thin
// connectors (#186). Kept identical here so this replay stays a faithful mirror.
clipPlanes.Add(new PortalClipPlane
{
Normal = normal, D = d, InsideSide = centroidDot >= 0 ? 0 : 1,
Normal = normal, D = d, InsideSide = ((ushort)portal.Flags & 0x2) == 0 ? 1 : 0,
});
}
else

280
tests/AcDream.App.Tests/Rendering/Issue176177FacilityHubFloodReplayTests.cs Normal file
View file

@ -0,0 +1,280 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Numerics;
using AcDream.App.Rendering;
using DatReaderWriter;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.App.Tests.Rendering;
/// <summary>
/// #176 (purple flashing at corridor seams, camera-angle dependent) + #177
/// (stairs pop in/out) — headless portal-flood replay in the Facility Hub
/// landblock 0x8A02. The unified hypothesis after the dat + draw-path reads:
/// both artifacts are FLOOD ADMISSION instability (a cell dropping out of
/// PortalVisibilityBuilder's admitted set paints the fog-purple clear color
/// where its geometry was; stair cells failing admission = the pop).
///
/// Production-matched inputs: Build(root, eye, lookup, viewProj,
/// buildingMembership: null, drawLiftZ: ShellDrawLiftZ) — the drawLiftZ
/// mirrors RetailPViewRenderer.DrawInside.
///
/// Scenarios:
/// A. #177 approach — stand in corridor 0x0178, look +X at the stair ramp
/// (0x0182) and the lower cell (0x0183): are they admitted?
/// B. #177 descent — eye path down the ramp crossing into 0x0183: does
/// 0x0182 (the ramp geometry's owner) drop near the transit?
/// C. #176 gaze sweep — eye parked in 0x016E near the 0x017A seam, yaw
/// sweep at several pitches: any cell admitted at angle k, gone at k+1,
/// back at k+2 (the bistability signature)?
/// D. #176 walk — eye tracks down the corridor across two seams, gaze
/// locked +X: per-step admitted-set diffs (drop-for-one-step churn).
/// </summary>
public class Issue176177FacilityHubFloodReplayTests
{
private const uint FacilityHub = 0x8A020000u;
private readonly ITestOutputHelper _out;
public Issue176177FacilityHubFloodReplayTests(ITestOutputHelper output) => _out = output;
private static Matrix4x4 ViewProjFor(Vector3 eye, Vector3 gazeDir)
{
var view = Matrix4x4.CreateLookAt(eye, eye + gazeDir, Vector3.UnitZ);
var proj = Matrix4x4.CreatePerspectiveFieldOfView(1.2f, 1280f / 720f, 0.1f, 5000f);
return view * proj;
}
private static List<uint> Flood(
Dictionary<uint, LoadedCell> cells, uint rootId, Vector3 eye, Vector3 gazeDir)
{
Func<uint, LoadedCell?> lookup = id => cells.TryGetValue(id, out var c) ? c : null;
var frame = PortalVisibilityBuilder.Build(
cells[rootId], eye, lookup, ViewProjFor(eye, gazeDir),
buildingMembership: null,
drawLiftZ: PortalVisibilityBuilder.ShellDrawLiftZ);
var result = new List<uint>(frame.OrderedVisibleCells);
result.Sort();
return result;
}
private static string CellSetString(IEnumerable<uint> ids)
=> string.Join(" ", ids.Select(id => $"{id & 0xFFFFu:X4}"));
[Fact]
public void ScenarioA_StairApproach_AdmissionsFromCorridor()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
Assert.True(cells.ContainsKey(FacilityHub | 0x0178u), "0x0178 not loaded");
// 0x0178 spans x<=95 at z −6..−3 (floor −6); the ramp cell 0x0182 runs
// x 95→98.33 descending; 0x0183 continues at z −9 beyond x=98.33.
// Eye at standing height (~1.7 m above the −6 floor), approaching the
// stair portal at x=95, gazing +X with a slight downward pitch (the
// natural look at a descending stair).
foreach (float eyeX in new[] { 88f, 90f, 92f, 94f, 94.9f })
{
var eye = new Vector3(eyeX, -40f, -4.3f);
foreach (var (gaze, label) in new (Vector3, string)[]
{
(new Vector3(1f, 0f, 0f), "level"),
(Vector3.Normalize(new Vector3(1f, 0f, -0.35f)), "pitch-19"),
(Vector3.Normalize(new Vector3(1f, 0f, -0.7f)), "pitch-35"),
})
{
var visible = Flood(cells, FacilityHub | 0x0178u, eye, gaze);
bool ramp = visible.Contains(FacilityHub | 0x0182u);
bool lower = visible.Contains(FacilityHub | 0x0183u);
_out.WriteLine($"eyeX={eyeX,5:F1} gaze={label,-8} flood={visible.Count,2} " +
$"ramp0182={(ramp ? "Y" : "MISSING")} lower0183={(lower ? "Y" : "MISSING")} " +
$"[{CellSetString(visible)}]");
}
}
}
[Fact]
public void ScenarioB_StairDescent_RampCellRetention()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
// Descend the ramp: floor z goes −6 (x=95) → −9 (x=98.33), then flat.
// Eye rides ~1.7 m above the local floor. Root = the cell containing
// the eye by x-range (0x0178 x<95, ramp 0x0182 95..98.33, 0x0183 after).
// Gaze: forward and slightly down (running down stairs).
var gazeDir = Vector3.Normalize(new Vector3(1f, 0f, -0.4f));
List<uint>? prev = null;
for (float x = 94.0f; x <= 100.5f; x += 0.1f)
{
float floorZ = x < 95f ? -6f
: x < 98.333f ? -6f - 3f * (x - 95f) / 3.333f
: -9f;
var eye = new Vector3(x, -40f, floorZ + 1.7f);
uint rootId = x < 95f ? FacilityHub | 0x0178u
: x < 98.333f ? FacilityHub | 0x0182u
: FacilityHub | 0x0183u;
var visible = Flood(cells, rootId, eye, gazeDir);
bool ramp = visible.Contains(FacilityHub | 0x0182u);
bool upper = visible.Contains(FacilityHub | 0x0178u);
string diff = "";
if (prev is not null)
{
var removed = prev.Except(visible).ToList();
var added = visible.Except(prev).ToList();
if (removed.Count > 0) diff += $" REMOVED=[{CellSetString(removed)}]";
if (added.Count > 0) diff += $" added=[{CellSetString(added)}]";
}
_out.WriteLine($"x={x,6:F1} root={rootId & 0xFFFFu:X4} eyeZ={eye.Z,6:F2} flood={visible.Count,2} " +
$"ramp0182={(ramp ? "Y" : "MISSING")} up0178={(upper ? "Y" : "-")}{diff}");
prev = visible;
}
}
[Fact]
public void ScenarioC_CorridorSeamGazeSweep_Bistability()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
// Parked eye in 0x016E near the 0x017A seam (x=85), standing height.
var eye = new Vector3(83.5f, -40f, -4.3f);
uint rootId = FacilityHub | 0x016Eu;
int churnEvents = 0;
foreach (float pitchZ in new[] { 0f, -0.35f, -0.75f, -1.2f })
{
List<uint>? prevSet = null;
float prevYaw = 0f;
var perYawSets = new List<(float yaw, List<uint> set)>();
for (float yawDeg = -180f; yawDeg <= 180f; yawDeg += 2f)
{
float rad = yawDeg * MathF.PI / 180f;
var gaze = Vector3.Normalize(new Vector3(MathF.Cos(rad), MathF.Sin(rad), pitchZ));
var visible = Flood(cells, rootId, eye, gaze);
perYawSets.Add((yawDeg, visible));
if (prevSet is not null)
{
var removed = prevSet.Except(visible).ToList();
var added = visible.Except(prevSet).ToList();
if (removed.Count > 0 || added.Count > 0)
{
_out.WriteLine($"pitch={pitchZ,5:F2} yaw {prevYaw,6:F0}->{yawDeg,6:F0}: " +
$"flood {prevSet.Count}->{visible.Count}" +
(removed.Count > 0 ? $" REMOVED=[{CellSetString(removed)}]" : "") +
(added.Count > 0 ? $" added=[{CellSetString(added)}]" : ""));
}
}
prevSet = visible;
prevYaw = yawDeg;
}
// Bistability: a cell present at yaw k, absent at k+1, present at k+2.
for (int i = 2; i < perYawSets.Count; i++)
{
var flicker = perYawSets[i - 2].set
.Intersect(perYawSets[i].set)
.Except(perYawSets[i - 1].set)
.ToList();
if (flicker.Count > 0)
{
churnEvents++;
_out.WriteLine($">>> BISTABLE pitch={pitchZ:F2} yaw={perYawSets[i - 1].yaw:F0}: " +
$"cells [{CellSetString(flicker)}] dropped for ONE 2-degree step");
}
}
}
_out.WriteLine($"bistable one-step drop events: {churnEvents}");
}
/// <summary>
/// THE production lag-window scenario (from launch-137-gate2.log
/// [cell-transit] lines): membership transits fire 0.1–0.6 m PAST the
/// portal plane in the travel direction (016E→017A at x=85.33–85.47 vs
/// the plane at x=85.00; 0182→0183 at 98.56–98.64 vs 98.33). The render
/// root (viewer cell, same membership machinery) therefore holds the OLD
/// cell while the camera eye is already beyond the boundary portal's
/// plane. This scenario reproduces exactly that window: root=old cell,
/// eye stepped across and past the plane, gaze forward. If the forward
/// chain (the next corridor cells) drops inside the window, that is #176
/// (purple = fog clear color where the forward cells' geometry was) and
/// #177(a)/(c) at the stair transit.
/// </summary>
[Theory]
[InlineData(0x016Eu, 0x017Au, 85.00f, -4.3f)] // corridor seam, plane x=85
[InlineData(0x0182u, 0x0183u, 98.333f, -7.3f)] // stair-bottom transit, plane x=98.33
public void ScenarioE_RootLagWindow_ForwardChainRetention(
uint rootLow, uint forwardLow, float planeX, float eyeZ)
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
uint rootId = FacilityHub | rootLow;
uint forwardId = FacilityHub | forwardLow;
var gazeDir = Vector3.Normalize(new Vector3(1f, 0f, -0.3f));
_out.WriteLine($"root=0x{rootLow:X4} forward=0x{forwardLow:X4} plane x={planeX:F2} " +
"(eye sweeps across; root HELD at the old cell = the production lag window)");
foreach (float dx in new[] { -0.30f, -0.10f, -0.02f, 0.00f, 0.02f, 0.05f, 0.10f, 0.20f, 0.30f, 0.45f, 0.60f })
{
var eye = new Vector3(planeX + dx, -40f, eyeZ);
var visible = Flood(cells, rootId, eye, gazeDir);
bool fwd = visible.Contains(forwardId);
_out.WriteLine($" eyeX=plane{(dx >= 0 ? "+" : "")}{dx:F2} flood={visible.Count,2} " +
$"forward={(fwd ? "Y" : ">>> DROPPED <<<")} [{CellSetString(visible)}]");
}
}
[Fact]
public void ScenarioD_CorridorWalk_PerStepChurn()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
// Walk 0x0165 → 0x016E → 0x017A along y=−40 (seams at x=75 and x=85),
// gaze locked +X, slight downward pitch (the running view). Root flips
// by x-range at the seams (the camera transits the same portals).
var gazeDir = Vector3.Normalize(new Vector3(1f, 0f, -0.3f));
List<uint>? prev = null;
int churn = 0;
for (float x = 71f; x <= 89f; x += 0.05f)
{
uint rootId = x < 75f ? FacilityHub | 0x0165u
: x < 85f ? FacilityHub | 0x016Eu
: FacilityHub | 0x017Au;
if (!cells.ContainsKey(rootId)) continue;
var eye = new Vector3(x, -40f, -4.3f);
var visible = Flood(cells, rootId, eye, gazeDir);
if (prev is not null)
{
var removed = prev.Except(visible).ToList();
var added = visible.Except(prev).ToList();
if (removed.Count > 0 || added.Count > 0)
{
churn++;
_out.WriteLine($"x={x,6:F2} root={rootId & 0xFFFFu:X4} flood={visible.Count,2}" +
(removed.Count > 0 ? $" REMOVED=[{CellSetString(removed)}]" : "") +
(added.Count > 0 ? $" added=[{CellSetString(added)}]" : ""));
}
}
prev = visible;
}
_out.WriteLine($"admitted-set change events over the walk: {churn}");
}
}

560
tests/AcDream.App.Tests/Rendering/Issue177StairDescentCameraFloodTests.cs Normal file
View file

@ -0,0 +1,560 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Numerics;
using AcDream.App.Rendering;
using AcDream.Core.Physics;
using AcDream.Core.Rendering;
using DatReaderWriter;
using DatReaderWriter.Options;
using DatEnvCell = DatReaderWriter.DBObjs.EnvCell;
using DatEnvironment = DatReaderWriter.DBObjs.Environment;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.App.Tests.Rendering;
/// <summary>
/// #177 decisive full-chain replay: drive the REAL <see cref="RetailChaseCamera"/>
/// + REAL <see cref="PhysicsCameraCollisionProbe"/> down the Facility Hub
/// staircase against the REAL BSP, then feed the swept (ViewerCellId, eye,
/// View*Projection) into <see cref="PortalVisibilityBuilder.Build"/> — exactly
/// the production coupling (GameWindow ~9055-9065 + RetailPViewRenderer.DrawInside).
///
/// The earlier Issue176177 replays fed SYNTHETIC (root, eye) pairs: Scenario A
/// admitted the stairs fine from a coherent corridor root, Scenario E collapsed
/// the flood 12->1 but only because it HELD the root at the old cell while the
/// eye crossed a portal plane. This test removes the assumption: the root IS the
/// swept camera cell, the eye IS the swept camera eye, both from the same sweep.
/// If the stairs still collapse, #177 is a production root/eye coupling defect
/// and the printed per-portal side-test D names the failing gate. If they stay
/// admitted, the flood is exonerated and the artifact lives downstream.
/// </summary>
public class Issue177StairDescentCameraFloodTests
{
private const uint FacilityHub = 0x8A020000u;
private readonly ITestOutputHelper _out;
public Issue177StairDescentCameraFloodTests(ITestOutputHelper output) => _out = output;
private static string? ResolveDatDir()
{
var fromEnv = Environment.GetEnvironmentVariable("ACDREAM_DAT_DIR");
if (!string.IsNullOrWhiteSpace(fromEnv) && Directory.Exists(fromEnv)) return fromEnv;
var def = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(def) ? def : null;
}
private static PhysicsEngine BuildHubEngine(DatCollection dats)
{
var cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
for (uint low = 0x0100u; low <= 0x01FFu; low++)
{
uint id = FacilityHub | low;
var datCell = dats.Get<DatEnvCell>(id);
if (datCell is null) continue;
var environment = dats.Get<DatEnvironment>(0x0D000000u | datCell.EnvironmentId);
if (environment is null) continue;
if (!environment.Cells.TryGetValue(datCell.CellStructure, out var cellStruct) || cellStruct is null)
continue;
var world = Matrix4x4.CreateFromQuaternion(datCell.Position.Orientation) *
Matrix4x4.CreateTranslation(datCell.Position.Origin);
cache.CacheCellStruct(id, datCell, cellStruct, world);
}
var heights = new byte[81];
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = -1000f;
engine.AddLandblock(FacilityHub, new TerrainSurface(heights, heightTable),
Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(), 0f, 0f);
return engine;
}
// Analytic ramp floor from Scenario B: flat -6 (x<95), descends to -9 across
// x 95..98.333, then flat -9.
private static float FloorZ(float x)
=> x < 95f ? -6f
: x < 98.333f ? -6f - 3f * (x - 95f) / 3.333f
: -9f;
// Replicated side test (PortalVisibilityBuilder.CameraOnInteriorSide is private).
private const float PortalSideEpsilon = 0.01f;
private static bool EyeInteriorSide(LoadedCell cell, int i, Vector3 eye)
{
if (i >= cell.ClipPlanes.Count) return true;
var pl = cell.ClipPlanes[i];
if (pl.Normal.LengthSquared() < 1e-8f) return true;
var local = Vector3.Transform(eye, cell.InverseWorldTransform);
float dot = Vector3.Dot(pl.Normal, local) + pl.D;
return pl.InsideSide == 0 ? dot >= -PortalSideEpsilon : dot <= PortalSideEpsilon;
}
private static float SideD(LoadedCell cell, int i, Vector3 eye)
{
if (i >= cell.ClipPlanes.Count) return float.NaN;
var pl = cell.ClipPlanes[i];
if (pl.Normal.LengthSquared() < 1e-8f) return float.NaN;
var local = Vector3.Transform(eye, cell.InverseWorldTransform);
return Vector3.Dot(pl.Normal, local) + pl.D;
}
private static string CellSet(IEnumerable<uint> ids)
=> string.Join(" ", ids.Select(id => $"{id & 0xFFFFu:X4}"));
[Fact]
public void StairCellComposition_ShellVsStatics()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
foreach (uint low in new uint[] { 0x01C8, 0x01C4, 0x01C9, 0x0210, 0x020E, 0x01C1, 0x01C0 })
{
uint id = FacilityHub | low;
var envCell = dats.Get<DatEnvCell>(id);
if (envCell is null) { _out.WriteLine($"0x{low:X4}: (no dat cell)"); continue; }
var environment = dats.Get<DatEnvironment>(0x0D000000u | envCell.EnvironmentId);
environment!.Cells.TryGetValue(envCell.CellStructure, out var cs);
int polys = cs?.Polygons.Count ?? -1;
int verts = cs?.VertexArray.Vertices.Count ?? -1;
var mn = new Vector3(float.MaxValue); var mx = new Vector3(float.MinValue);
if (cs is not null)
foreach (var kv in cs.VertexArray.Vertices)
{ var o = kv.Value.Origin; var v = new Vector3(o.X, o.Y, o.Z); mn = Vector3.Min(mn, v); mx = Vector3.Max(mx, v); }
int statics = envCell.StaticObjects?.Count ?? 0;
bool seenOut = (envCell.Flags & DatReaderWriter.Enums.EnvCellFlags.SeenOutside) != 0;
_out.WriteLine(FormattableString.Invariant(
$"0x{low:X4} env=0x{envCell.EnvironmentId:X4} struct={envCell.CellStructure} shellPolys={polys} shellVerts={verts} bounds=[{mn.X:F1},{mn.Y:F1},{mn.Z:F1}]..[{mx.X:F1},{mx.Y:F1},{mx.Z:F1}] portals={envCell.CellPortals.Count} statics={statics} seenOut={seenOut}"));
if (envCell.StaticObjects is not null)
foreach (var stab in envCell.StaticObjects)
{
var o = stab.Frame.Origin;
_out.WriteLine(FormattableString.Invariant(
$" static Id=0x{stab.Id:X8} kind={(stab.Id >> 24 == 0x02 ? "Setup" : stab.Id >> 24 == 0x01 ? "GfxObj" : "?")} pos=({o.X:F2},{o.Y:F2},{o.Z:F2})"));
}
// Portal normals (local space) — horizontal (|Nz|~1) = FLOOR/CEILING portal
// (the edge-on-clip suspect); vertical (|Nz|~0) = wall/doorway portal.
var lc = renderLookup(id);
if (lc is not null)
for (int i = 0; i < lc.Portals.Count; i++)
{
var n = i < lc.ClipPlanes.Count ? lc.ClipPlanes[i].Normal : Vector3.Zero;
string kind = MathF.Abs(n.Z) > 0.7f ? "FLOOR/CEIL" : MathF.Abs(n.Z) < 0.3f ? "wall" : "slope";
_out.WriteLine(FormattableString.Invariant(
$" portal[{i}]->0x{lc.Portals[i].OtherCellId:X4} N=({n.X:F2},{n.Y:F2},{n.Z:F2}) {kind} inside={lc.ClipPlanes[i].InsideSide}"));
}
}
LoadedCell? renderLookup(uint id)
{
try { return CornerFloodReplayTests.LoadCell(dats, id); }
catch (InvalidOperationException) { return null; }
}
}
/// <summary>
/// #177 re-diagnosis (fix#1 failed the visual gate): the vanish flips on a SLIGHT turn +
/// depends on zoom, so it is a gaze/eye knife-edge, not the eye-squarely-in-opening case
/// fix#1 handled. Drive the REAL camera at a fixed player spot on the 015F stairs, sweep
/// yaw FINELY at two zooms, and print the viewer cell + stair-cell admission each step to
/// locate the knife-edge and which cell flips.
/// </summary>
[Fact]
public void RealStaircase_FineYawZoomSweep_FindKnifeEdge()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var renderCells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
var engine = BuildHubEngine(dats);
Func<uint, LoadedCell?> lookup = id => renderCells.TryGetValue(id, out var c) ? c : null;
bool sC = CameraDiagnostics.CollideCamera; bool sA = CameraDiagnostics.AlignToSlope;
try
{
CameraDiagnostics.CollideCamera = true; CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.TranslationStiffness = 0.45f; CameraDiagnostics.RotationStiffness = 0.45f;
uint[] stair = { 0x015Eu, 0x015Fu, 0x01C1u, 0x01C0u, 0x020Fu };
// Player standing mid-015F stairs, eye near the ceiling boundary (per the sweep char).
foreach (var playerPos in new[] { new Vector3(60.5f, -46f, -2.5f), new Vector3(60.5f, -47f, -3.0f) })
foreach (float dist in new[] { 2.61f, 12.0f })
{
_out.WriteLine(FormattableString.Invariant(
$"=== player=({playerPos.X:F1},{playerPos.Y:F1},{playerPos.Z:F1}) zoom={dist} ==="));
var cam = new RetailChaseCamera
{
CollisionProbe = new PhysicsCameraCollisionProbe(engine),
FovY = MathF.PI / 3f, Aspect = 16f / 9f, Distance = dist,
};
uint prevViewer = 0; string prevAdmit = "";
for (float yawDeg = 0f; yawDeg < 360f; yawDeg += 6f)
{
float yaw = yawDeg * MathF.PI / 180f;
var (pcell, _) = engine.AdjustPosition(FacilityHub | 0x015Fu, playerPos + new Vector3(0, 0, 0.1f));
for (int i = 0; i < 160; i++)
cam.Update(playerPos, yaw, Vector3.Zero, true, Vector3.UnitZ, 1f / 60f, pcell, 0x5000000A);
var eye = cam.Position; uint viewer = cam.ViewerCellId;
string admit = "?";
if (viewer != 0u && renderCells.TryGetValue(viewer, out var rc))
{
var f = PortalVisibilityBuilder.Build(rc, eye, lookup, cam.View * cam.Projection, null, PortalVisibilityBuilder.ShellDrawLiftZ);
var s = f.OrderedVisibleCells;
admit = string.Concat(stair.Select(low => (s.Contains(FacilityHub | low) ? "1" : "0")));
}
// Print only when viewer or the admit pattern CHANGES (knife-edges).
if (viewer != prevViewer || admit != prevAdmit)
{
_out.WriteLine(FormattableString.Invariant(
$" yaw={yawDeg,3:F0} eye=({eye.X,6:F2},{eye.Y,6:F2},{eye.Z,6:F2}) viewer=0x{viewer & 0xFFFF:X4} stair[5E,5F,C1,C0,0F]={admit}"));
prevViewer = viewer; prevAdmit = admit;
}
}
}
}
finally { CameraDiagnostics.CollideCamera = sC; CameraDiagnostics.AlignToSlope = sA; }
}
/// <summary>
/// #177 retail-vs-us flood DEPTH: retail's cdb capture shows PView cell_draw_num reaching 26
/// cells from camera cell 015E (avg 14.3) looking down the spiral shaft. Sweep OUR real camera
/// from 015E over many gaze/zoom poses and report the max/avg OrderedVisibleCells — if ours
/// caps well below retail's 26, our flood truncates the spiral (the vanish).
/// </summary>
[Fact]
public void FloodDepthFrom015E_VsRetail26()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var renderCells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
var engine = BuildHubEngine(dats);
Func<uint, LoadedCell?> lookup = id => renderCells.TryGetValue(id, out var c) ? c : null;
bool sC = CameraDiagnostics.CollideCamera; bool sA = CameraDiagnostics.AlignToSlope;
try
{
CameraDiagnostics.CollideCamera = true; CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.TranslationStiffness = 0.45f; CameraDiagnostics.RotationStiffness = 0.45f;
int maxCells = 0; uint bestViewer = 0; double sum = 0; int n = 0; string bestSet = "";
foreach (var playerPos in new[] { new Vector3(61f, -42f, -4f), new Vector3(60f, -41f, -5f), new Vector3(62f, -43f, -4f) })
foreach (float dist in new[] { 2.61f, 4f, 8f })
foreach (float pitch in new[] { 0.291f, 0.7f, -0.2f })
{
var cam = new RetailChaseCamera { CollisionProbe = new PhysicsCameraCollisionProbe(engine), FovY = MathF.PI / 3f, Aspect = 16f / 9f, Distance = dist, Pitch = pitch };
for (float yawDeg = 0f; yawDeg < 360f; yawDeg += 10f)
{
float yaw = yawDeg * MathF.PI / 180f;
var (pcell, _) = engine.AdjustPosition(FacilityHub | 0x015Eu, playerPos + new Vector3(0, 0, 0.1f));
for (int i = 0; i < 140; i++) cam.Update(playerPos, yaw, Vector3.Zero, true, Vector3.UnitZ, 1f / 60f, pcell, 0x5000000A);
uint viewer = cam.ViewerCellId;
if (viewer == 0u || !renderCells.TryGetValue(viewer, out var rc)) continue;
var f = PortalVisibilityBuilder.Build(rc, cam.Position, lookup, cam.View * cam.Projection, null, PortalVisibilityBuilder.ShellDrawLiftZ);
int c = f.OrderedVisibleCells.Count; sum += c; n++;
if (c > maxCells) { maxCells = c; bestViewer = viewer; bestSet = CellSet(f.OrderedVisibleCells.OrderBy(v => v)); }
}
}
_out.WriteLine(FormattableString.Invariant(
$"OUR flood from 015E-area: maxCells={maxCells} (retail max=26) avg={sum / Math.Max(1, n):F1} (retail avg=14.3) bestViewer=0x{bestViewer & 0xFFFF:X4}"));
_out.WriteLine($" best set: [{bestSet}]");
}
finally { CameraDiagnostics.CollideCamera = sC; CameraDiagnostics.AlignToSlope = sA; }
}
private static Matrix4x4 ViewProj(Vector3 eye, Vector3 dir)
=> Matrix4x4.CreateLookAt(eye, eye + Vector3.Normalize(dir), Vector3.UnitZ)
* Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 0.1f, 5000f);
// Signed distance of a WORLD point to a render cell's portal[i] plane (local-space plane).
private static float PortalPlaneDistance(LoadedCell cell, int i, Vector3 worldPt)
{
var pl = cell.ClipPlanes[i];
var local = Vector3.Transform(worldPt, cell.InverseWorldTransform);
return Vector3.Dot(pl.Normal, local) + pl.D;
}
/// <summary>
/// #177 THE decisive experiment. Reproduce the captured failing frame — camera in
/// cell 0x015F with the eye sitting IN the ceiling-portal plane (production [flap]:
/// root=015F eye=(60.47,-46.57,-0.00), p->01C1 clip=0) — and confirm the upper
/// stair cell 01C1 drops from the flood. Then move the SAME eye 0.4 m off that
/// plane (into the cell interior) and confirm 01C1 is re-admitted. If the contrast
/// holds, #177's fix is a viewpoint-off-the-portal-plane rule, and the load-bearing
/// clip (#119/#181) is correct as-is.
/// </summary>
[Fact]
public void EdgeOnCeilingPortal_DropsUpperCell_OffPlaneReadmits()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
Func<uint, LoadedCell?> lookup = id => cells.TryGetValue(id, out var c) ? c : null;
var root = cells[FacilityHub | 0x015Fu];
uint upperId = FacilityHub | 0x01C1u;
// Find 015F's portal to 01C1 (the ceiling/up portal) + report its normal.
int upIdx = -1;
for (int i = 0; i < root.Portals.Count; i++)
if (root.Portals[i].OtherCellId == 0x01C1u) { upIdx = i; break; }
Assert.True(upIdx >= 0, "015F has no portal to 01C1");
var upN = root.ClipPlanes[upIdx].Normal;
_out.WriteLine(FormattableString.Invariant(
$"015F portal[{upIdx}]->01C1 localN=({upN.X:F2},{upN.Y:F2},{upN.Z:F2})"));
// Look UP the stairs so the ceiling portal + 01C1 land on screen.
var gaze = new Vector3(0f, -0.3f, 1f);
// Captured FAILING eye — in the ceiling-portal plane (world z ~0).
var eyeEdgeOn = new Vector3(60.47f, -46.57f, -0.00f);
// Same eye, pulled 0.4 m DOWN (off the ceiling portal, into 015F's interior).
var eyeOffPlane = eyeEdgeOn + new Vector3(0f, 0f, -0.40f);
foreach (var (label, eye) in new[] { ("edge-on(captured)", eyeEdgeOn), ("off-plane(-0.4z)", eyeOffPlane) })
{
float d = PortalPlaneDistance(root, upIdx, eye);
var frame = PortalVisibilityBuilder.Build(
root, eye, lookup, ViewProj(eye, gaze),
buildingMembership: null, drawLiftZ: PortalVisibilityBuilder.ShellDrawLiftZ);
var vis = frame.OrderedVisibleCells.OrderBy(v => v).ToList();
bool up = vis.Contains(upperId);
string admit = up ? "ADMITTED" : "DROPPED";
_out.WriteLine(FormattableString.Invariant(
$"{label,-18} eye=({eye.X,6:F2},{eye.Y,6:F2},{eye.Z,6:F2}) D->01C1={d,6:F3} 01C1={admit} flood={vis.Count} [{CellSet(vis)}]"));
}
// #177 CHARACTERIZATION (fix#1 reverted — this edge-on-in-plane case was NOT the
// production mechanism; the real vanish is a grazing/sliver flood collapse in the
// spiral, root 0x01C8, portals off-screen/sliver, camera NOT collision-jammed).
// Kept as a mechanism pin: an eye exactly in the ceiling-portal plane drops the upper
// cell (edge-on → <3 clip), an eye 0.4 m off admits it via the normal clip.
var fEdge = PortalVisibilityBuilder.Build(root, eyeEdgeOn, lookup, ViewProj(eyeEdgeOn, gaze), null, PortalVisibilityBuilder.ShellDrawLiftZ);
var fOff = PortalVisibilityBuilder.Build(root, eyeOffPlane, lookup, ViewProj(eyeOffPlane, gaze), null, PortalVisibilityBuilder.ShellDrawLiftZ);
Assert.DoesNotContain(upperId, fEdge.OrderedVisibleCells); // edge-on drops (mechanism)
Assert.Contains(upperId, fOff.OrderedVisibleCells); // off-plane admits (control)
}
/// <summary>
/// #177 sweep characterization: place the player on the 015F staircase and drive the
/// REAL chase camera + collision sweep, reporting where the eye lands relative to the
/// 015F ceiling-portal plane (world z=0). If the eye rests AT the plane (|D|~0) the
/// flood collapses (see EdgeOnCeilingPortal test); this shows whether that is a swept
/// contact leaving the eye on the surface vs free-space boom geometry.
/// </summary>
[Fact]
public void StaircaseSweep_EyeClearanceFromCeilingPortal()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var renderCells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
var engine = BuildHubEngine(dats);
var root015F = renderCells[FacilityHub | 0x015Fu];
int upIdx = 0; // portal[0]->01C1 (ceiling)
bool sC = CameraDiagnostics.CollideCamera; bool sA = CameraDiagnostics.AlignToSlope;
try
{
CameraDiagnostics.CollideCamera = true; CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.TranslationStiffness = 0.45f; CameraDiagnostics.RotationStiffness = 0.45f;
// Player on the 015F stairs (world y~-46, ceiling portal at world z~0), swept
// at a range of heights + facings (up-stairs = -Y, down-stairs = +Y).
foreach (float pz in new[] { -1.0f, -1.5f, -2.0f, -2.5f, -3.0f, -3.5f })
foreach (var (fLabel, yaw) in new (string, float)[] { ("up(-Y)", -MathF.PI / 2f), ("down(+Y)", MathF.PI / 2f) })
{
var playerPos = new Vector3(60.5f, -46f, pz);
var (pcell, _) = engine.AdjustPosition(FacilityHub | 0x015Fu, playerPos + new Vector3(0, 0, 0.1f));
var cam = new RetailChaseCamera
{
CollisionProbe = new PhysicsCameraCollisionProbe(engine),
FovY = MathF.PI / 3f, Aspect = 16f / 9f,
};
for (int i = 0; i < 300; i++)
cam.Update(playerPos, yaw, Vector3.Zero, true, Vector3.UnitZ, 1f / 60f, pcell, 0x5000000A);
var eye = cam.Position;
uint viewer = cam.ViewerCellId;
// D from the eye to 015F's ceiling-portal plane (only meaningful if viewer==015F).
float dCeil = PortalPlaneDistance(root015F, upIdx, eye);
_out.WriteLine(FormattableString.Invariant(
$"playerZ={pz,5:F1} face={fLabel,-8} pcell=0x{pcell & 0xFFFF:X4} eye=({eye.X,6:F2},{eye.Y,6:F2},{eye.Z,6:F2}) viewer=0x{viewer & 0xFFFF:X4} D->ceilPortal={dCeil,6:F3}"));
}
}
finally { CameraDiagnostics.CollideCamera = sC; CameraDiagnostics.AlignToSlope = sA; }
}
[Theory]
// spot label, player x, player cell, description
[InlineData(90.0f, 0x0178u, "TOP corridor 0178 (approach view)")]
[InlineData(100.0f, 0x0183u, "BOTTOM room 0183 (look-back view)")]
public void ParkedYawZoomSweep_StairAdmission(float px, uint pcell, string label)
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var renderCells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
var engine = BuildHubEngine(dats);
Func<uint, LoadedCell?> lookup = id => renderCells.TryGetValue(id, out var c) ? c : null;
bool sC = CameraDiagnostics.CollideCamera; bool sA = CameraDiagnostics.AlignToSlope;
float sT = CameraDiagnostics.TranslationStiffness, sR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true; CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.TranslationStiffness = 0.45f; CameraDiagnostics.RotationStiffness = 0.45f;
var playerPos = new Vector3(px, -40f, FloorZ(px));
uint playerCell = FacilityHub | pcell;
_out.WriteLine($"=== {label} @ ({px:F1},-40,{FloorZ(px):F2}) ===");
foreach (float dist in new[] { 2.61f, 8.0f })
{
_out.WriteLine($" -- zoom Distance={dist} --");
var cam = new RetailChaseCamera
{
CollisionProbe = new PhysicsCameraCollisionProbe(engine),
FovY = MathF.PI / 3f, Aspect = 16f / 9f, Distance = dist,
};
for (float yawDeg = 0f; yawDeg < 360f; yawDeg += 30f)
{
float yaw = yawDeg * MathF.PI / 180f;
// Settle at this yaw (static player).
for (int i = 0; i < 200; i++)
cam.Update(playerPos, yaw, Vector3.Zero, true, Vector3.UnitZ, 1f / 60f, playerCell, 0x5000000A);
Vector3 eye = cam.Position; uint viewer = cam.ViewerCellId;
var vp = cam.View * cam.Projection;
if (viewer != 0u && renderCells.TryGetValue(viewer, out var rootCell))
{
var f = PortalVisibilityBuilder.Build(rootCell, eye, lookup, vp, null, PortalVisibilityBuilder.ShellDrawLiftZ);
var vis = f.OrderedVisibleCells.OrderBy(v => v).ToList();
string flags = $"0178={(vis.Contains(FacilityHub | 0x0178u) ? "Y" : "-")} 0182={(vis.Contains(FacilityHub | 0x0182u) ? "Y" : "-")} 0183={(vis.Contains(FacilityHub | 0x0183u) ? "Y" : "-")} 0181={(vis.Contains(FacilityHub | 0x0181u) ? "Y" : "-")}";
_out.WriteLine(FormattableString.Invariant(
$" yaw={yawDeg,3:F0} eye=({eye.X,6:F2},{eye.Y,6:F2},{eye.Z,6:F2}) viewer=0x{viewer & 0xFFFF:X4} {flags} flood={vis.Count} [{CellSet(vis)}]"));
}
else
_out.WriteLine(FormattableString.Invariant($" yaw={yawDeg,3:F0} eye=({eye.X,6:F2},{eye.Y,6:F2},{eye.Z,6:F2}) viewer=0x{viewer:X8} ROOT-MISSING"));
}
}
}
finally
{
CameraDiagnostics.CollideCamera = sC; CameraDiagnostics.AlignToSlope = sA;
CameraDiagnostics.TranslationStiffness = sT; CameraDiagnostics.RotationStiffness = sR;
}
}
[Fact]
public void Descent_RealCameraSweep_StairCellRetention()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var renderCells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
var engine = BuildHubEngine(dats);
Func<uint, LoadedCell?> lookup = id => renderCells.TryGetValue(id, out var c) ? c : null;
bool savedColl = CameraDiagnostics.CollideCamera;
bool savedAlign = CameraDiagnostics.AlignToSlope;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
var cam = new RetailChaseCamera
{
CollisionProbe = new PhysicsCameraCollisionProbe(engine),
FovY = MathF.PI / 3f,
Aspect = 16f / 9f,
};
const float yaw = 0f; // facing +X, descending
const float speed = 3.0f; // m/s run
const float dt = 1f / 60f;
float startX = 88f, endX = 101.5f;
// Seat the player + settle the camera at the start pose.
uint playerCell = FacilityHub | 0x0178u;
Vector3 P(float x) => new Vector3(x, -40f, FloorZ(x));
for (int i = 0; i < 400; i++)
cam.Update(P(startX), yaw, Vector3.Zero, true, Vector3.UnitZ, dt, playerCell, 0x5000000A);
_out.WriteLine("x playerCell eye=(x,y,z) viewerCell coh flood stairs rootPortalsPastPlane");
float x = startX;
uint prevViewer = cam.ViewerCellId;
int collapses = 0, incoherentFrames = 0;
while (x <= endX)
{
var playerPos = P(x);
// Track player membership like production: AdjustPosition carry-forward.
var (pc, found) = engine.AdjustPosition(playerCell, playerPos + new Vector3(0, 0, 0.1f));
if (found) playerCell = pc;
cam.Update(playerPos, yaw, new Vector3(speed, 0, 0), true, Vector3.UnitZ, dt, playerCell, 0x5000000A);
Vector3 eye = cam.Position;
uint viewer = cam.ViewerCellId;
var viewProj = cam.View * cam.Projection;
string floodStr, stairs, coh, past;
if (viewer != 0u && renderCells.TryGetValue(viewer, out var rootCell))
{
var frame = PortalVisibilityBuilder.Build(
rootCell, eye, lookup, viewProj,
buildingMembership: null, drawLiftZ: PortalVisibilityBuilder.ShellDrawLiftZ);
var vis = frame.OrderedVisibleCells.OrderBy(v => v).ToList();
floodStr = $"{vis.Count,2} [{CellSet(vis)}]";
bool ramp = vis.Contains(FacilityHub | 0x0182u);
bool lower = vis.Contains(FacilityHub | 0x0183u);
stairs = $"r{(ramp ? "Y" : "-")}l{(lower ? "Y" : "-")}";
// Coherence: is the eye on the interior side of ALL of root's portals?
// If not, the eye is outside root -> the crossed portal's subtree drops.
var pastList = new List<string>();
bool coherent = true;
for (int i = 0; i < rootCell.Portals.Count && i < rootCell.ClipPlanes.Count; i++)
{
if (!EyeInteriorSide(rootCell, i, eye))
{
coherent = false;
pastList.Add($"p{i}->0x{rootCell.Portals[i].OtherCellId:X4}(D={SideD(rootCell, i, eye):F3})");
}
}
coh = coherent ? "IN " : "OUT";
past = pastList.Count == 0 ? "-" : string.Join(",", pastList);
if (!coherent) incoherentFrames++;
if (vis.Count <= 1) collapses++;
}
else
{
floodStr = "root-missing/0"; stairs = "--"; coh = "?"; past = $"viewer=0x{viewer:X8}";
}
bool viewerFlip = viewer != prevViewer;
prevViewer = viewer;
_out.WriteLine(FormattableString.Invariant(
$"{x,6:F2} 0x{playerCell:X8} ({eye.X,7:F3},{eye.Y,7:F3},{eye.Z,7:F3}) 0x{viewer:X8} {coh} {floodStr} {stairs} {(viewerFlip ? "FLIP " : "")}{past}"));
x += speed * dt;
}
_out.WriteLine($"SUMMARY: collapses(flood<=1)={collapses} incoherentFrames(eye-outside-root)={incoherentFrames}");
}
finally
{
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.AlignToSlope = savedAlign;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
}

100
tests/AcDream.App.Tests/Rendering/Issue181CameraParkStabilityTests.cs Normal file
View file

@ -0,0 +1,100 @@
using System;
using System.Numerics;
using AcDream.App.Rendering;
using AcDream.Core.Rendering;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.App.Tests.Rendering;
/// <summary>
/// #181 excitation probe — the live parked camera wanders ~0.9 mm/frame
/// (launch-176-leakfix.log [flap-sweep]: 19,889 distinct sought values in 20k
/// parked sweeps), which keeps the portal flood's knife-edge admissions
/// flapping. Retail's parked viewer is a bit-exact fixed point (UpdateCamera
/// dead-band `return viewer`).
///
/// This test drives RetailChaseCamera.Update with BIT-IDENTICAL inputs at the
/// live frame rate: if the camera parks bit-stable here, the live wobble comes
/// from its INPUTS (player position/yaw jitter out of GameWindow); if it
/// wobbles here, the camera loop itself fails to reach the fixed point.
/// </summary>
public class Issue181CameraParkStabilityTests
{
private readonly ITestOutputHelper _out;
public Issue181CameraParkStabilityTests(ITestOutputHelper output) => _out = output;
private sealed class PassthroughProbe : ICameraCollisionProbe
{
public CameraSweepResult SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId, Vector3 playerPos)
=> new(desiredEye, cellId);
}
[Fact]
public void ParkedCamera_StaticInputs_ReachesBitStableFixedPoint()
{
bool savedAlign = CameraDiagnostics.AlignToSlope;
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.AlignToSlope = true; // production default
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
var cam = new RetailChaseCamera { CollisionProbe = new PassthroughProbe() };
// Live-like parked pose: static player, static yaw, zero velocity,
// grounded on a flat contact plane, ~1500 fps.
var playerPos = new Vector3(49.5f, -39.9f, -5.9f);
float yaw = 1.83f;
float dt = 1f / 1500f;
void Step() => cam.Update(
playerPosition: playerPos,
playerYaw: yaw,
playerVelocity: Vector3.Zero,
isOnGround: true,
contactPlaneNormal: Vector3.UnitZ,
dt: dt,
cellId: 0x8A020142u,
selfEntityId: 0x5);
// Converge: at α≈0.003/frame the boom needs a few thousand frames
// to settle from the init pose into the dead-band.
for (int i = 0; i < 20000; i++) Step();
Vector3 a = cam.Position;
var fwdA = cam.View; // full view matrix — includes the forward half
// 2000 further frames with bit-identical inputs: every one must be
// the exact fixed point (retail parks verbatim).
float maxDelta = 0f;
Vector3 prev = a;
bool viewChanged = false;
for (int i = 0; i < 2000; i++)
{
Step();
maxDelta = MathF.Max(maxDelta, Vector3.Distance(cam.Position, prev));
prev = cam.Position;
if (cam.View != fwdA) viewChanged = true;
}
_out.WriteLine(FormattableString.Invariant(
$"post-convergence maxConsecDelta={maxDelta * 1e6f:F2}um viewChanged={viewChanged} pos=({cam.Position.X:F7},{cam.Position.Y:F7},{cam.Position.Z:F7})"));
Assert.True(maxDelta == 0f,
$"parked camera must be a bit-exact fixed point, wandered up to {maxDelta * 1e6f:F1}um/frame");
Assert.False(viewChanged, "view matrix must be frozen at park");
}
finally
{
CameraDiagnostics.AlignToSlope = savedAlign;
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
}

164
tests/AcDream.App.Tests/Rendering/Issue181VisFlapReplayTests.cs Normal file
View file

@ -0,0 +1,164 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Numerics;
using AcDream.App.Rendering;
using DatReaderWriter;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.App.Tests.Rendering;
/// <summary>
/// #181 — the portal-flood admitted set flaps 31↔32 on MICRON eye noise at a
/// parked camera (live: launch-176-leakfix.log, root 0x8A020142, vis flips
/// every ~100–200 frames for 517k frames; the swept eye carries ~7 µm
/// float-roundtrip noise). The flapping cell's visibility-scoped lights + the
/// union-AABB scissor rect strobe = the #176 washed-region flicker.
///
/// This replay hunts the knife edge headlessly: at the live parked eye
/// (49.15, −38.62, −3.98), sweep gazes and perturb the eye by ±0.5 mm per
/// axis; ANY admitted-set difference at sub-mm perturbation is the #181
/// instability, and the symmetric difference names the flapping cell.
/// </summary>
public class Issue181VisFlapReplayTests
{
private const uint FacilityHub = 0x8A020000u;
private const uint LiveRoot = FacilityHub | 0x0142u;
private static readonly Vector3 LiveEye = new(49.15f, -38.62f, -3.98f);
private readonly ITestOutputHelper _out;
public Issue181VisFlapReplayTests(ITestOutputHelper output) => _out = output;
private static Matrix4x4 ViewProjFor(Vector3 eye, Vector3 gazeDir)
{
var view = Matrix4x4.CreateLookAt(eye, eye + gazeDir, Vector3.UnitZ);
var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 0.1f, 5000f);
return view * proj;
}
private static List<uint> Flood(
Dictionary<uint, LoadedCell> cells, uint rootId, Vector3 eye, Vector3 gazeDir)
{
Func<uint, LoadedCell?> lookup = id => cells.TryGetValue(id, out var c) ? c : null;
var frame = PortalVisibilityBuilder.Build(
cells[rootId], eye, lookup, ViewProjFor(eye, gazeDir),
buildingMembership: null,
drawLiftZ: PortalVisibilityBuilder.ShellDrawLiftZ);
var result = new List<uint>(frame.OrderedVisibleCells);
result.Sort();
return result;
}
private static string CellSetString(IEnumerable<uint> ids)
=> string.Join(" ", ids.Select(id => $"{id & 0xFFFFu:X4}"));
[Fact]
public void Diagnostic_FlappingCellViewRegion_SliverOrLarge()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
uint flapper = FacilityHub | 0x0181u;
// The most unstable pose from the perturbation sweep.
float yaw = 15f * MathF.PI / 180f, pitch = -20f * MathF.PI / 180f;
var gaze = new Vector3(
MathF.Cos(pitch) * MathF.Cos(yaw),
MathF.Cos(pitch) * MathF.Sin(yaw),
MathF.Sin(pitch));
Func<uint, LoadedCell?> lookup = id => cells.TryGetValue(id, out var c) ? c : null;
foreach (var (label, eye) in new (string, Vector3)[]
{
("base ", LiveEye),
("+0.5mm x ", LiveEye + new Vector3(0.0005f, 0, 0)),
("-0.5mm x ", LiveEye - new Vector3(0.0005f, 0, 0)),
("+5mm x ", LiveEye + new Vector3(0.005f, 0, 0)),
("-5mm x ", LiveEye - new Vector3(0.005f, 0, 0)),
("+2cm z ", LiveEye + new Vector3(0, 0, 0.02f)),
("-2cm z ", LiveEye - new Vector3(0, 0, 0.02f)),
})
{
var frame = PortalVisibilityBuilder.Build(
cells[LiveRoot], eye, lookup, ViewProjFor(eye, gaze),
buildingMembership: null,
drawLiftZ: PortalVisibilityBuilder.ShellDrawLiftZ);
if (!frame.CellViews.TryGetValue(flapper, out var view) || view.IsEmpty)
{
_out.WriteLine($"{label}: 0181 NOT ADMITTED");
continue;
}
// NDC shoelace area of the admitted region (screen is 4.0 NDC-units total).
float area = 0f; int polys = 0, verts = 0;
foreach (var vp in view.Polygons)
{
var v = vp.Vertices;
polys++; verts += v.Length;
float a = 0f;
for (int i = 0; i < v.Length; i++)
{
var p = v[i]; var q = v[(i + 1) % v.Length];
a += p.X * q.Y - q.X * p.Y;
}
area += MathF.Abs(a) * 0.5f;
}
_out.WriteLine(FormattableString.Invariant(
$"{label}: 0181 admitted polys={polys} verts={verts} ndcArea={area:F4} ({area / 4f * 100f:F1}% of screen)"));
}
}
[Fact]
public void Diagnostic_SubMillimeterEyePerturbation_MustNotChangeAdmission()
{
var datDir = CornerFloodReplayTests.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var cells = Issue120ReciprocalPingPongTests.LoadAllInteriorCells(dats, FacilityHub);
Assert.True(cells.ContainsKey(LiveRoot), "live root 0x0142 not loaded");
// ±0.5 mm per axis — an order of magnitude above the live µm noise, well
// below anything visually meaningful.
var perturbations = new[]
{
new Vector3( 0.0005f, 0, 0), new Vector3(-0.0005f, 0, 0),
new Vector3(0, 0.0005f, 0), new Vector3(0, -0.0005f, 0),
new Vector3(0, 0, 0.0005f), new Vector3(0, 0, -0.0005f),
};
int unstableGazes = 0;
for (int yawDeg = 0; yawDeg < 360; yawDeg += 15)
{
foreach (float pitchDeg in new[] { 0f, -20f, -35f })
{
float yaw = yawDeg * MathF.PI / 180f, pitch = pitchDeg * MathF.PI / 180f;
var gaze = new Vector3(
MathF.Cos(pitch) * MathF.Cos(yaw),
MathF.Cos(pitch) * MathF.Sin(yaw),
MathF.Sin(pitch));
var baseline = Flood(cells, LiveRoot, LiveEye, gaze);
foreach (var d in perturbations)
{
var perturbed = Flood(cells, LiveRoot, LiveEye + d, gaze);
if (perturbed.SequenceEqual(baseline)) continue;
unstableGazes++;
var removed = baseline.Except(perturbed).ToList();
var added = perturbed.Except(baseline).ToList();
_out.WriteLine(FormattableString.Invariant(
$"UNSTABLE yaw={yawDeg} pitch={pitchDeg} d=({d.X * 1000:F1},{d.Y * 1000:F1},{d.Z * 1000:F1})mm base={baseline.Count} pert={perturbed.Count} removed=[{CellSetString(removed)}] added=[{CellSetString(added)}]"));
}
}
}
_out.WriteLine($"unstable (gaze, perturbation) pairs: {unstableGazes}");
// Diagnostic first: report, don't assert — the fix turns this into a hard pin.
}
}

188
tests/AcDream.App.Tests/Rendering/Issue181WallPressEquilibriumTests.cs Normal file
View file

@ -0,0 +1,188 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Numerics;
using AcDream.App.Rendering;
using AcDream.Core.Physics;
using AcDream.Core.Rendering;
using DatReaderWriter;
using DatReaderWriter.Options;
using DatEnvCell = DatReaderWriter.DBObjs.EnvCell;
using DatEnvironment = DatReaderWriter.DBObjs.Environment;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.App.Tests.Rendering;
/// <summary>
/// #181 excitation, isolated headlessly — the WALL-PRESS equilibrium. Live
/// evidence: a camera pressed into corridor walls/openings never reaches a
/// fixed point (sought steps α·gap into the wall per frame; the sweep clips it
/// back within adjust_to_plane's parametric 0.02 window) → the published eye
/// wanders ~1 mm/frame, and when the wander straddles a cell boundary the
/// VIEWER CELL flaps (launch-181-pressed.log: viewer≠player on 85.5% of
/// frames, one-frame A→B→A root flips) — each flip re-roots the whole
/// visibility frame (the #176/#181 flicker).
///
/// This test runs the REAL RetailChaseCamera + the REAL
/// PhysicsCameraCollisionProbe against the REAL Facility Hub BSP with a
/// static player backed against the corridor wall, and measures the
/// steady-state eye wander + ViewerCellId stability over 20k frames.
/// Diagnostic (reporting) first; the equilibrium fix turns the wander/flap
/// numbers into hard pins.
/// </summary>
public class Issue181WallPressEquilibriumTests
{
private const uint FacilityHubLandblock = 0x8A020000u;
private readonly ITestOutputHelper _out;
public Issue181WallPressEquilibriumTests(ITestOutputHelper output) => _out = output;
// Mirrors AcDream.Core.Tests Conformance.ConformanceDats (not referencable
// from App.Tests): resolve the dat dir + load real EnvCells into the cache.
private static string? ResolveDatDir()
{
var fromEnv = Environment.GetEnvironmentVariable("ACDREAM_DAT_DIR");
if (!string.IsNullOrWhiteSpace(fromEnv) && Directory.Exists(fromEnv)) return fromEnv;
var def = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(def) ? def : null;
}
private static (PhysicsEngine, PhysicsDataCache) BuildCorridorEngine(DatCollection dats)
{
var cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
for (uint low = 0x0100u; low <= 0x01FFu; low++)
{
uint id = FacilityHubLandblock | low;
var datCell = dats.Get<DatEnvCell>(id);
if (datCell is null) continue;
var environment = dats.Get<DatEnvironment>(0x0D000000u | datCell.EnvironmentId);
if (environment is null) continue;
if (!environment.Cells.TryGetValue(datCell.CellStructure, out var cellStruct) || cellStruct is null)
continue;
var world = Matrix4x4.CreateFromQuaternion(datCell.Position.Orientation) *
Matrix4x4.CreateTranslation(datCell.Position.Origin);
cache.CacheCellStruct(id, datCell, cellStruct, world);
}
var heights = new byte[81];
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = -1000f;
engine.AddLandblock(FacilityHubLandblock, new TerrainSurface(heights, heightTable),
Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(), 0f, 0f);
return (engine, cache);
}
[Fact]
public void Diagnostic_WallPressedCamera_EyeWanderAndViewerCellStability()
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: dats unavailable"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var (engine, _) = BuildCorridorEngine(dats);
bool savedAlign = CameraDiagnostics.AlignToSlope;
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.AlignToSlope = true;
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
// The live parked spot from the leak-fix log: player at the corridor
// spawn (cell 0x0142), backed near the +Y wall so the full boom is
// blocked (live [resolve]: hit=yes n=(0,-1,0) every frame).
var playerPos = new Vector3(50.331f, -39.357f, -5.90f);
// Live [resolve]: the sweep target headed (-2.13,+1.32,+0.75) from the
// pivot and hit the n=(0,-1,0) wall — so the player faces (+X,-Y)-ish
// and the boom presses -X+Y into that wall. yaw = atan2(-0.53, 0.85).
float yaw = -0.556f;
uint cellId = 0x8A020142u;
float dt = 1f / 1500f;
var cam = new RetailChaseCamera
{
CollisionProbe = new PhysicsCameraCollisionProbe(engine),
};
void Step() => cam.Update(
playerPosition: playerPos,
playerYaw: yaw,
playerVelocity: Vector3.Zero,
isOnGround: true,
contactPlaneNormal: Vector3.UnitZ,
dt: dt,
cellId: cellId,
selfEntityId: 0x5);
// Settle into the wall-press equilibrium.
for (int i = 0; i < 5000; i++) Step();
// Measure 20k steady-state frames.
var eyes = new List<Vector3>(20000);
var cells = new HashSet<uint>();
int cellTransitions = 0;
uint prevCell = cam.ViewerCellId;
Vector3 prevEye = cam.Position;
float maxStep = 0f; double sumStep = 0;
for (int i = 0; i < 20000; i++)
{
Step();
float d = Vector3.Distance(cam.Position, prevEye);
maxStep = MathF.Max(maxStep, d);
sumStep += d;
prevEye = cam.Position;
eyes.Add(cam.Position);
cells.Add(cam.ViewerCellId);
if (cam.ViewerCellId != prevCell) { cellTransitions++; prevCell = cam.ViewerCellId; }
}
// Wander bounding box.
Vector3 mn = eyes[0], mx = eyes[0];
foreach (var e in eyes) { mn = Vector3.Min(mn, e); mx = Vector3.Max(mx, e); }
var span = mx - mn;
_out.WriteLine(FormattableString.Invariant(
$"steady-state: avgStep={sumStep / 20000 * 1e6:F1}um maxStep={maxStep * 1e6:F1}um wanderBox=({span.X * 1000:F2},{span.Y * 1000:F2},{span.Z * 1000:F2})mm"));
_out.WriteLine(FormattableString.Invariant(
$"viewer cells seen: {cells.Count} transitions={cellTransitions} eye=({cam.Position.X:F6},{cam.Position.Y:F6},{cam.Position.Z:F6}) cell=0x{cam.ViewerCellId:X8}"));
// Orbit structure: 16 consecutive frames at 6dp, with the sweep's
// own [flap-sweep] lines captured for the same frames.
bool savedFlap = RenderingDiagnostics.ProbeFlapEnabled;
var savedOut = Console.Out;
try
{
RenderingDiagnostics.ProbeFlapEnabled = true;
using var writer = new StringWriter();
Console.SetOut(writer);
for (int i = 0; i < 16; i++)
{
Step();
writer.WriteLine(FormattableString.Invariant(
$"orbit[{i:D2}] eye=({cam.Position.X:F6},{cam.Position.Y:F6},{cam.Position.Z:F6})"));
}
Console.SetOut(savedOut);
foreach (var line in writer.ToString().Split('\n'))
if (line.Length > 1) _out.WriteLine(line.TrimEnd());
}
finally
{
Console.SetOut(savedOut);
RenderingDiagnostics.ProbeFlapEnabled = savedFlap;
}
}
finally
{
CameraDiagnostics.AlignToSlope = savedAlign;
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
}

244
tests/AcDream.App.Tests/Rendering/RetailChaseCameraTests.cs
View file

@ -579,31 +579,233 @@ public class RetailChaseCameraTests
}
[Fact]
public void Update_CollisionDoesNotCorruptDampedState()
public void Update_AfterClampReleases_EyeReExtendsGradually()
{
// Regression for the wall-press vibration: the sweep must NOT write its
// clamped result back into the damped "sought" eye (retail keeps
// viewer_sought_position separate from viewer). Frame 1 clamps the eye
// near the pivot; frame 2 releases. With the damp state kept clean, the
// published eye returns straight to the (constant) target on frame 2; if
// it were corrupted, frame 2 would only lerp ~7.5% back from the clamp
// and stay pinned near it.
CameraDiagnostics.CollideCamera = true;
var probe = new ClampThenReleaseProbe { ClampEye = new Vector3(0f, 0f, 2f) };
var cam = new RetailChaseCamera { CollisionProbe = probe };
// #180: retail's sought position is STATEFUL — CameraManager::UpdateCamera
// (0x00456660) interpolates from the CURRENT SWEPT VIEWER toward the desired
// pose, so after an obstruction clears the eye re-extends at the stiffness
// rate (τ ≈ 0.22 s), NOT in one jump. (The previous pin here asserted the
// instant full re-extension — the exact divergence that re-rolled the
// full-length knife-edge boom ray per frame and produced the strobe.)
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
void Step() => cam.Update(
playerPosition: Vector3.Zero, playerYaw: 0f, playerVelocity: Vector3.Zero,
isOnGround: true, contactPlaneNormal: Vector3.UnitZ, dt: 1f / 60f,
cellId: 0x100, selfEntityId: 0x5);
var probe = new ClampThenReleaseProbe { ClampEye = new Vector3(0f, 0f, 2f) };
var cam = new RetailChaseCamera { CollisionProbe = probe };
Step(); // frame 1: clamps to (0,0,2)
Step(); // frame 2: releases
void Step() => cam.Update(
playerPosition: Vector3.Zero, playerYaw: 0f, playerVelocity: Vector3.Zero,
isOnGround: true, contactPlaneNormal: Vector3.UnitZ, dt: 1f / 60f,
cellId: 0x100, selfEntityId: 0x5);
// Constant pose → target eye ≈ (-2.5, 0, 2.25). Full recovery means
// Position.X is near the target (< -2), not pinned near the clamp (X≈0).
Assert.True(cam.Position.X < -2f,
$"published eye should fully recover to the target after release, got {cam.Position}");
Step(); // frame 1: clamps to (0,0,2) — the viewer sits at the clamp
Step(); // frame 2: releases
// Constant pose → target eye ≈ (-2.5, 0, 2.25). Frame 2's eye is one
// 7.5% lerp step off the clamp (X ≈ -0.19) — near the clamp, NOT the
// full target.
Assert.True(cam.Position.X > -0.5f,
$"eye must re-extend gradually from the contact, got {cam.Position}");
// ...and converges onto the target over the following seconds.
for (int i = 0; i < 200; i++) Step();
Assert.True(cam.Position.X < -2.4f,
$"eye should converge to the target after release, got {cam.Position}");
}
finally
{
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
// Probe that records every requested sweep target and clamps the eye to a
// fixed contact point (a wall the boom is pressed into).
private sealed class RecordingClampProbe : ICameraCollisionProbe
{
public readonly System.Collections.Generic.List<Vector3> Requests = new();
public Vector3 ClampEye;
public CameraSweepResult SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId, Vector3 playerPos)
{
Requests.Add(desiredEye);
return new CameraSweepResult(ClampEye, cellId);
}
}
[Fact]
public void Update_SweepTargetConvergesOntoContact_NotTheFullBoom()
{
// THE #180 structural pin. Retail sweeps pivot → viewer_sought_position
// (SmartBox::update_viewer 0x00453ce0), and the sought derives from the
// swept viewer — so while pressed against a wall the requested sweep
// target sits ONE interpolation step past the contact. acdream's old shape
// re-requested the full-length ideal boom every frame; with mm input drift
// that full ray grazed distant geometry at r±ε and flipped its first-contact
// solution 0.27 m along the boom every few frames (the #176 stripes).
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
var wall = new Vector3(0f, 0f, 2f);
var probe = new RecordingClampProbe { ClampEye = wall };
var cam = new RetailChaseCamera { CollisionProbe = probe };
void Step() => cam.Update(
playerPosition: Vector3.Zero, playerYaw: 0f, playerVelocity: Vector3.Zero,
isOnGround: true, contactPlaneNormal: Vector3.UnitZ, dt: 1f / 60f,
cellId: 0x100, selfEntityId: 0x5);
Step(); // frame 1: init requests the full boom (AD-38), eye clamps to the wall
Step(); // frame 2: the request must now derive from the CLAMPED viewer
// Frame 1 documents the contrast: the init request is the full-length
// target, ~2.5 m from the contact.
Assert.True(Vector3.Distance(probe.Requests[0], wall) > 2f,
$"frame-1 init request should be the full boom, got {probe.Requests[0]}");
// Frame 2's request = one 7.5% lerp step off the wall (~0.19 m) — the
// knife-edge full-length ray is never re-rolled.
float reach = Vector3.Distance(probe.Requests[1], wall);
Assert.True(reach < 0.3f,
$"frame-2 sweep target must sit one step past the contact, got {reach:F3} m past it");
}
finally
{
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
// Probe that fails entirely on the FIRST call (retail set_viewer(player_pos, 1):
// eye = player, viewer_cell = 0), then releases; records requests.
private sealed class FallbackThenReleaseProbe : ICameraCollisionProbe
{
public readonly System.Collections.Generic.List<Vector3> Requests = new();
public int Calls;
public CameraSweepResult SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId, Vector3 playerPos)
{
Calls++;
Requests.Add(desiredEye);
return Calls == 1
? new CameraSweepResult(playerPos, 0u) // total fallback (pc:92886)
: new CameraSweepResult(desiredEye, cellId);
}
}
[Fact]
public void Update_TotalFallback_ReExtendsFromThePlayer()
{
// After the total sweep failure retail resets viewer AND sought to the
// player's position (set_viewer(player_pos, reset_sought=1)) — the camera
// re-extends outward from the head, so the next sweep target is NEAR THE
// PLAYER, not the full-length boom.
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
var probe = new FallbackThenReleaseProbe();
var cam = new RetailChaseCamera { CollisionProbe = probe };
void Step() => cam.Update(
playerPosition: Vector3.Zero, playerYaw: 0f, playerVelocity: Vector3.Zero,
isOnGround: true, contactPlaneNormal: Vector3.UnitZ, dt: 1f / 60f,
cellId: 0x100, selfEntityId: 0x5);
Step(); // frame 1: total fallback — viewer snaps to the player, cell 0
Assert.Equal(Vector3.Zero, cam.Position);
Assert.Equal(0u, cam.ViewerCellId);
Step(); // frame 2: the sweep target re-extends FROM the player
float reach = Vector3.Distance(probe.Requests[1], Vector3.Zero);
Assert.True(reach < 0.3f,
$"post-fallback sweep target must re-extend from the player, got {reach:F3} m out");
}
finally
{
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
// First-contact model of an infinite wall plane at X = WallX: requests whose
// ray from the pivot crosses the plane stop AT the plane; others pass through.
private sealed class WallPlaneProbe : ICameraCollisionProbe
{
public float WallX = -1f;
public CameraSweepResult SweepEye(Vector3 pivot, Vector3 desiredEye, uint cellId, uint selfEntityId, Vector3 playerPos)
{
if (desiredEye.X >= WallX || desiredEye.X - pivot.X >= -1e-6f)
return new CameraSweepResult(desiredEye, cellId);
float t = (WallX - pivot.X) / (desiredEye.X - pivot.X);
return new CameraSweepResult(pivot + (desiredEye - pivot) * t, cellId);
}
}
[Fact]
public void Update_PressedAgainstWall_EyeGlidesStably()
{
// The wall-press equilibrium: the sought parks one step past the contact,
// the sweep clips it back, and the published eye stays glued to the wall
// with no oscillation — retail's glide. (This was the fear behind the old
// "must not feed back" comment; the retail shape is stable by construction
// because the sweep target converges instead of fighting the full boom.)
bool savedColl = CameraDiagnostics.CollideCamera;
float savedT = CameraDiagnostics.TranslationStiffness;
float savedR = CameraDiagnostics.RotationStiffness;
try
{
CameraDiagnostics.CollideCamera = true;
CameraDiagnostics.TranslationStiffness = 0.45f;
CameraDiagnostics.RotationStiffness = 0.45f;
var cam = new RetailChaseCamera { CollisionProbe = new WallPlaneProbe { WallX = -1f } };
void Step() => cam.Update(
playerPosition: Vector3.Zero, playerYaw: 0f, playerVelocity: Vector3.Zero,
isOnGround: true, contactPlaneNormal: Vector3.UnitZ, dt: 1f / 60f,
cellId: 0x100, selfEntityId: 0x5);
// Settle a few frames, then watch 30 frames for per-frame jumps.
for (int i = 0; i < 5; i++) Step();
Vector3 prev = cam.Position;
float maxDelta = 0f;
for (int i = 0; i < 30; i++)
{
Step();
maxDelta = MathF.Max(maxDelta, Vector3.Distance(cam.Position, prev));
prev = cam.Position;
}
Assert.True(MathF.Abs(cam.Position.X - (-1f)) < 1e-3f,
$"eye should sit on the wall plane, got {cam.Position}");
Assert.True(maxDelta < 1e-3f,
$"pressed against a wall the eye must not jump frame-to-frame, max delta {maxDelta:F5} m");
}
finally
{
CameraDiagnostics.CollideCamera = savedColl;
CameraDiagnostics.TranslationStiffness = savedT;
CameraDiagnostics.RotationStiffness = savedR;
}
}
// ── Convergence snap (Part 1: kills the at-rest boom drift) ────────

29
tests/AcDream.Bake.Tests/AcDream.Bake.Tests.csproj Normal file
View file

@ -0,0 +1,29 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsPackable>false</IsPackable>
<LangVersion>latest</LangVersion>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="coverlet.collector" Version="6.0.4" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
</ItemGroup>
<ItemGroup>
<!-- NO Silk.NET / GL anywhere in this dependency chain (AcDream.Bake ->
AcDream.Content -> AcDream.Core are all GL-free by construction). -->
<ProjectReference Include="..\..\src\AcDream.Bake\AcDream.Bake.csproj" />
</ItemGroup>
</Project>

79
tests/AcDream.Bake.Tests/BakeDeterminismTests.cs Normal file
View file

@ -0,0 +1,79 @@
using System;
using System.Collections.Generic;
using System.IO;
using AcDream.Bake;
namespace AcDream.Bake.Tests;
/// <summary>
/// Dat-gated byte-reproducibility gate for the bake pipeline (review finding
/// 1): the plan's "bakes must be byte-reproducible run-to-run" is a whole-
/// FILE property, so it must be tested through the REAL BakeRunner — the
/// serializer-level determinism tests in Content.Tests can't see thread-
/// completion-order effects in the blob region. Skips cleanly when the dats
/// are absent (CI), same convention as
/// tests/AcDream.Core.Tests/Conformance/DatConcurrencyStressTests.
/// </summary>
public sealed class BakeDeterminismTests : IDisposable {
private readonly List<string> _tempFiles = new();
private string NewTempPakPath() {
var path = Path.Combine(Path.GetTempPath(), $"acdream-baketest-{Guid.NewGuid():N}.pak");
_tempFiles.Add(path);
return path;
}
public void Dispose() {
foreach (var f in _tempFiles) {
try { if (File.Exists(f)) File.Delete(f); } catch { /* best effort cleanup */ }
}
}
private static string? ResolveDatDir() {
// Mirrors ConformanceDats.ResolveDatDir (env var, then the well-known
// Documents fallback); duplicated because test projects can't
// reference each other's helpers.
var fromEnv = Environment.GetEnvironmentVariable("ACDREAM_DAT_DIR");
if (!string.IsNullOrWhiteSpace(fromEnv) && Directory.Exists(fromEnv)) return fromEnv;
var def = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(def) ? def : null;
}
[Fact]
public void Bake_SameIdSet_DifferentThreadCounts_ByteIdenticalPaks() {
var datDir = ResolveDatDir();
if (datDir is null) return; // dats absent (CI) — skip, matching suite convention
// Small mixed fixture: GfxObjs (incl. the #119 tricky ids), Setups
// (door setup carries emitters -> exercises the side-staged preload
// path), and a Holtburg EnvCell. Big enough to span multiple asset
// types; small enough to run in seconds.
var ids = new HashSet<uint> {
0x01000001u, 0x010002B4u, 0x010008A8u, 0x010014C3u,
0x02000001u, 0x020019FFu, 0x020005D8u,
0xA9B40100u, 0xA9B40101u,
};
var pathA = NewTempPakPath();
var pathB = NewTempPakPath();
// DIFFERENT thread counts on purpose: thread-completion order was the
// nondeterminism source the sorted-batching fix removes — identical
// bytes must hold regardless of parallelism.
int rcA = BakeRunner.Run(new BakeOptions { DatDir = datDir, OutPath = pathA, IdFilter = ids, Threads = 8 });
int rcB = BakeRunner.Run(new BakeOptions { DatDir = datDir, OutPath = pathB, IdFilter = ids, Threads = 3 });
Assert.Equal(0, rcA);
Assert.Equal(0, rcB);
var bytesA = File.ReadAllBytes(pathA);
var bytesB = File.ReadAllBytes(pathB);
Assert.True(bytesA.Length == bytesB.Length,
$"pak sizes differ between runs: {bytesA.Length} vs {bytesB.Length} bytes");
Assert.True(bytesA.AsSpan().SequenceEqual(bytesB),
"two bakes of the same id set produced different bytes — the sorted-batching determinism guarantee is broken");
}
}

28
tests/AcDream.Content.Tests/AcDream.Content.Tests.csproj Normal file
View file

@ -0,0 +1,28 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsPackable>false</IsPackable>
<LangVersion>latest</LangVersion>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="coverlet.collector" Version="6.0.4" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.9" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\AcDream.Content\AcDream.Content.csproj" />
</ItemGroup>
</Project>

38
tests/AcDream.Content.Tests/ContentConformanceDats.cs Normal file
View file

@ -0,0 +1,38 @@
using System;
using System.IO;
using Microsoft.Extensions.Logging;
namespace AcDream.Content.Tests;
/// <summary>
/// Dat-dir resolution for the Content.Tests dat-gated equivalence suite.
/// Mirrors the exact pattern used by
/// tests/AcDream.Core.Tests/Conformance/ConformanceDats.ResolveDatDir and
/// tests/AcDream.Core.Tests/Conformance/DatConcurrencyStressTests
/// ("dats absent (CI) -- skip, matching suite convention"). Content.Tests
/// cannot reference AcDream.Core.Tests (a test project, not a library), so
/// this is a deliberate small duplication of the resolution logic — not a
/// new convention.
/// </summary>
public static class ContentConformanceDats {
public static string? ResolveDatDir() {
var fromEnv = Environment.GetEnvironmentVariable("ACDREAM_DAT_DIR");
if (!string.IsNullOrWhiteSpace(fromEnv) && Directory.Exists(fromEnv)) return fromEnv;
var def = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(def) ? def : null;
}
}
/// <summary>Minimal ILogger writing to Console — surfaces MeshExtractor failures during the equivalence sweep instead of silently swallowing them (NullLogger would hide the exact failure this suite exists to catch).</summary>
internal sealed class TestConsoleLogger : ILogger {
public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
public bool IsEnabled(LogLevel logLevel) => logLevel >= LogLevel.Warning;
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter) {
if (!IsEnabled(logLevel)) return;
Console.WriteLine($"[{logLevel}] MeshExtractor: {formatter(state, exception)}");
if (exception is not null) Console.WriteLine(exception);
}
}

31
tests/AcDream.Content.Tests/Crc32Tests.cs Normal file
View file

@ -0,0 +1,31 @@
using System.Text;
using AcDream.Content.Pak;
namespace AcDream.Content.Tests;
/// <summary>
/// Known-answer vectors for the hand-rolled CRC-32 (IEEE 802.3 / zip / PNG
/// variant). Without these the suite is blind to a self-consistent-but-wrong
/// implementation: writer and reader would agree with each other while
/// producing values no external tool could reproduce (review finding 6).
/// </summary>
public class Crc32Tests {
[Fact]
public void KnownAnswer_123456789_IsCBF43926() {
// THE standard CRC-32 check value: CRC of the ASCII string
// "123456789" is 0xCBF43926 for the reflected 0xEDB88320 polynomial.
var input = Encoding.ASCII.GetBytes("123456789");
Assert.Equal(0xCBF43926u, Crc32.Compute(input));
}
[Fact]
public void KnownAnswer_EmptyInput_IsZero() {
Assert.Equal(0x00000000u, Crc32.Compute(ReadOnlySpan<byte>.Empty));
}
[Fact]
public void KnownAnswer_SingleZeroByte() {
// CRC-32 of a single 0x00 byte is 0xD202EF8D (standard vector).
Assert.Equal(0xD202EF8Du, Crc32.Compute(new byte[] { 0x00 }));
}
}

221
tests/AcDream.Content.Tests/ObjectMeshDataEquality.cs Normal file
View file

@ -0,0 +1,221 @@
using System.Linq;
using Chorizite.Core.Render.Enums;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
namespace AcDream.Content.Tests;
/// <summary>
/// Field-by-field deep-equality comparator for <see cref="ObjectMeshData"/> and
/// its whole family (<see cref="MeshBatchData"/>, <see cref="TextureBatchData"/>,
/// <see cref="StagedEmitter"/>, <see cref="TextureKey"/>). Used by both the
/// round-trip tests (Task 3) and the dat-gated equivalence suite (Task 6) so a
/// mismatch always names the exact field that diverged instead of just
/// "objects not equal".
/// </summary>
public static class ObjectMeshDataEquality {
public static void AssertEqual(ObjectMeshData? expected, ObjectMeshData? actual, string path = "root") {
if (expected is null && actual is null) return;
Assert.True(expected is not null, $"{path}: expected null but actual was non-null");
Assert.True(actual is not null, $"{path}: expected non-null but actual was null");
Assert.True(expected.ObjectId == actual.ObjectId, $"{path}.ObjectId: expected 0x{expected.ObjectId:X16}, got 0x{actual.ObjectId:X16}");
Assert.True(expected.IsSetup == actual.IsSetup, $"{path}.IsSetup: expected {expected.IsSetup}, got {actual.IsSetup}");
AssertVerticesEqual(expected.Vertices, actual.Vertices, $"{path}.Vertices");
Assert.True(expected.Batches.Count == actual.Batches.Count,
$"{path}.Batches.Count: expected {expected.Batches.Count}, got {actual.Batches.Count}");
for (int i = 0; i < expected.Batches.Count; i++)
AssertBatchEqual(expected.Batches[i], actual.Batches[i], $"{path}.Batches[{i}]");
Assert.True(expected.UploadAttempts == actual.UploadAttempts,
$"{path}.UploadAttempts: expected {expected.UploadAttempts}, got {actual.UploadAttempts}");
AssertEqual(expected.EnvCellGeometry, actual.EnvCellGeometry, $"{path}.EnvCellGeometry");
Assert.True(expected.SetupParts.Count == actual.SetupParts.Count,
$"{path}.SetupParts.Count: expected {expected.SetupParts.Count}, got {actual.SetupParts.Count}");
for (int i = 0; i < expected.SetupParts.Count; i++) {
var (eId, eT) = expected.SetupParts[i];
var (aId, aT) = actual.SetupParts[i];
Assert.True(eId == aId, $"{path}.SetupParts[{i}].GfxObjId: expected 0x{eId:X16}, got 0x{aId:X16}");
AssertMatrixEqual(eT, aT, $"{path}.SetupParts[{i}].Transform");
}
Assert.True(expected.ParticleEmitters.Count == actual.ParticleEmitters.Count,
$"{path}.ParticleEmitters.Count: expected {expected.ParticleEmitters.Count}, got {actual.ParticleEmitters.Count}");
for (int i = 0; i < expected.ParticleEmitters.Count; i++)
AssertStagedEmitterEqual(expected.ParticleEmitters[i], actual.ParticleEmitters[i], $"{path}.ParticleEmitters[{i}]");
AssertTextureBatchesEqual(expected.TextureBatches, actual.TextureBatches, $"{path}.TextureBatches");
AssertBoundingBoxEqual(expected.BoundingBox, actual.BoundingBox, $"{path}.BoundingBox");
AssertVector3Equal(expected.SortCenter, actual.SortCenter, $"{path}.SortCenter");
Assert.True(expected.DIDDegrade == actual.DIDDegrade, $"{path}.DIDDegrade: expected {expected.DIDDegrade}, got {actual.DIDDegrade}");
AssertSphereEqual(expected.SelectionSphere, actual.SelectionSphere, $"{path}.SelectionSphere");
AssertVector3ArrayEqual(expected.EdgeLines, actual.EdgeLines, $"{path}.EdgeLines");
}
private static void AssertVerticesEqual(VertexPositionNormalTexture[] expected, VertexPositionNormalTexture[] actual, string path) {
Assert.True(expected.Length == actual.Length, $"{path}.Length: expected {expected.Length}, got {actual.Length}");
for (int i = 0; i < expected.Length; i++) {
AssertVector3Equal(expected[i].Position, actual[i].Position, $"{path}[{i}].Position");
AssertVector3Equal(expected[i].Normal, actual[i].Normal, $"{path}[{i}].Normal");
Assert.True(BitEqual(expected[i].UV, actual[i].UV), $"{path}[{i}].UV: expected {expected[i].UV}, got {actual[i].UV}");
}
}
private static void AssertBatchEqual(MeshBatchData expected, MeshBatchData actual, string path) {
Assert.True(expected.Indices.SequenceEqual(actual.Indices),
$"{path}.Indices: expected [{string.Join(",", expected.Indices)}], got [{string.Join(",", actual.Indices)}]");
Assert.True(expected.TextureFormat == actual.TextureFormat,
$"{path}.TextureFormat: expected {expected.TextureFormat}, got {actual.TextureFormat}");
AssertTextureKeyEqual(expected.TextureKey, actual.TextureKey, $"{path}.TextureKey");
Assert.True(expected.TextureIndex == actual.TextureIndex,
$"{path}.TextureIndex: expected {expected.TextureIndex}, got {actual.TextureIndex}");
Assert.True(expected.TextureData.SequenceEqual(actual.TextureData),
$"{path}.TextureData: length expected {expected.TextureData.Length}, got {actual.TextureData.Length}");
Assert.True(expected.UploadPixelFormat == actual.UploadPixelFormat,
$"{path}.UploadPixelFormat: expected {expected.UploadPixelFormat}, got {actual.UploadPixelFormat}");
Assert.True(expected.UploadPixelType == actual.UploadPixelType,
$"{path}.UploadPixelType: expected {expected.UploadPixelType}, got {actual.UploadPixelType}");
Assert.True(expected.CullMode == actual.CullMode,
$"{path}.CullMode: expected {expected.CullMode}, got {actual.CullMode}");
}
private static void AssertTextureBatchDataEqual(TextureBatchData expected, TextureBatchData actual, string path) {
AssertTextureKeyEqual(expected.Key, actual.Key, $"{path}.Key");
Assert.True(expected.TextureData.SequenceEqual(actual.TextureData),
$"{path}.TextureData: length expected {expected.TextureData.Length}, got {actual.TextureData.Length}");
Assert.True(expected.UploadPixelFormat == actual.UploadPixelFormat,
$"{path}.UploadPixelFormat: expected {expected.UploadPixelFormat}, got {actual.UploadPixelFormat}");
Assert.True(expected.UploadPixelType == actual.UploadPixelType,
$"{path}.UploadPixelType: expected {expected.UploadPixelType}, got {actual.UploadPixelType}");
Assert.True(expected.Indices.SequenceEqual(actual.Indices),
$"{path}.Indices: expected [{string.Join(",", expected.Indices)}], got [{string.Join(",", actual.Indices)}]");
Assert.True(expected.CullMode == actual.CullMode, $"{path}.CullMode: expected {expected.CullMode}, got {actual.CullMode}");
Assert.True(expected.IsTransparent == actual.IsTransparent, $"{path}.IsTransparent: expected {expected.IsTransparent}, got {actual.IsTransparent}");
Assert.True(expected.IsAdditive == actual.IsAdditive, $"{path}.IsAdditive: expected {expected.IsAdditive}, got {actual.IsAdditive}");
Assert.True(expected.HasWrappingUVs == actual.HasWrappingUVs, $"{path}.HasWrappingUVs: expected {expected.HasWrappingUVs}, got {actual.HasWrappingUVs}");
}
private static void AssertTextureBatchesEqual(
System.Collections.Generic.Dictionary<(int Width, int Height, TextureFormat Format), System.Collections.Generic.List<TextureBatchData>> expected,
System.Collections.Generic.Dictionary<(int Width, int Height, TextureFormat Format), System.Collections.Generic.List<TextureBatchData>> actual,
string path) {
Assert.True(expected.Count == actual.Count, $"{path}.Count: expected {expected.Count}, got {actual.Count}");
foreach (var key in expected.Keys) {
Assert.True(actual.ContainsKey(key), $"{path}: missing key {key}");
var expList = expected[key];
var actList = actual[key];
Assert.True(expList.Count == actList.Count, $"{path}[{key}].Count: expected {expList.Count}, got {actList.Count}");
for (int i = 0; i < expList.Count; i++)
AssertTextureBatchDataEqual(expList[i], actList[i], $"{path}[{key}][{i}]");
}
}
private static void AssertStagedEmitterEqual(StagedEmitter expected, StagedEmitter actual, string path) {
Assert.True(expected.PartIndex == actual.PartIndex, $"{path}.PartIndex: expected {expected.PartIndex}, got {actual.PartIndex}");
AssertMatrixEqual(expected.Offset, actual.Offset, $"{path}.Offset");
AssertParticleEmitterEqual(expected.Emitter, actual.Emitter, $"{path}.Emitter");
}
private static void AssertParticleEmitterEqual(ParticleEmitter? expected, ParticleEmitter? actual, string path) {
if (expected is null && actual is null) return;
Assert.True(expected is not null, $"{path}: expected null but actual was non-null");
Assert.True(actual is not null, $"{path}: expected non-null but actual was null");
Assert.True(expected.Id == actual.Id, $"{path}.Id: expected 0x{expected.Id:X8}, got 0x{actual.Id:X8}");
Assert.True(expected.DataCategory == actual.DataCategory, $"{path}.DataCategory: expected {expected.DataCategory}, got {actual.DataCategory}");
Assert.True(expected.Unknown == actual.Unknown, $"{path}.Unknown: expected {expected.Unknown}, got {actual.Unknown}");
Assert.True(expected.EmitterType == actual.EmitterType, $"{path}.EmitterType: expected {expected.EmitterType}, got {actual.EmitterType}");
Assert.True(expected.ParticleType == actual.ParticleType, $"{path}.ParticleType: expected {expected.ParticleType}, got {actual.ParticleType}");
Assert.True(expected.GfxObjId.DataId == actual.GfxObjId.DataId, $"{path}.GfxObjId: expected 0x{expected.GfxObjId.DataId:X8}, got 0x{actual.GfxObjId.DataId:X8}");
Assert.True(expected.HwGfxObjId.DataId == actual.HwGfxObjId.DataId, $"{path}.HwGfxObjId: expected 0x{expected.HwGfxObjId.DataId:X8}, got 0x{actual.HwGfxObjId.DataId:X8}");
Assert.True(BitEqual(expected.Birthrate, actual.Birthrate), $"{path}.Birthrate: expected {expected.Birthrate}, got {actual.Birthrate}");
Assert.True(expected.MaxParticles == actual.MaxParticles, $"{path}.MaxParticles: expected {expected.MaxParticles}, got {actual.MaxParticles}");
Assert.True(expected.InitialParticles == actual.InitialParticles, $"{path}.InitialParticles: expected {expected.InitialParticles}, got {actual.InitialParticles}");
Assert.True(expected.TotalParticles == actual.TotalParticles, $"{path}.TotalParticles: expected {expected.TotalParticles}, got {actual.TotalParticles}");
Assert.True(BitEqual(expected.TotalSeconds, actual.TotalSeconds), $"{path}.TotalSeconds: expected {expected.TotalSeconds}, got {actual.TotalSeconds}");
Assert.True(BitEqual(expected.Lifespan, actual.Lifespan), $"{path}.Lifespan: expected {expected.Lifespan}, got {actual.Lifespan}");
Assert.True(BitEqual(expected.LifespanRand, actual.LifespanRand), $"{path}.LifespanRand: expected {expected.LifespanRand}, got {actual.LifespanRand}");
AssertVector3Equal(expected.OffsetDir, actual.OffsetDir, $"{path}.OffsetDir");
Assert.True(BitEqual(expected.MinOffset, actual.MinOffset), $"{path}.MinOffset: expected {expected.MinOffset}, got {actual.MinOffset}");
Assert.True(BitEqual(expected.MaxOffset, actual.MaxOffset), $"{path}.MaxOffset: expected {expected.MaxOffset}, got {actual.MaxOffset}");
AssertVector3Equal(expected.A, actual.A, $"{path}.A");
Assert.True(BitEqual(expected.MinA, actual.MinA), $"{path}.MinA: expected {expected.MinA}, got {actual.MinA}");
Assert.True(BitEqual(expected.MaxA, actual.MaxA), $"{path}.MaxA: expected {expected.MaxA}, got {actual.MaxA}");
AssertVector3Equal(expected.B, actual.B, $"{path}.B");
Assert.True(BitEqual(expected.MinB, actual.MinB), $"{path}.MinB: expected {expected.MinB}, got {actual.MinB}");
Assert.True(BitEqual(expected.MaxB, actual.MaxB), $"{path}.MaxB: expected {expected.MaxB}, got {actual.MaxB}");
AssertVector3Equal(expected.C, actual.C, $"{path}.C");
Assert.True(BitEqual(expected.MinC, actual.MinC), $"{path}.MinC: expected {expected.MinC}, got {actual.MinC}");
Assert.True(BitEqual(expected.MaxC, actual.MaxC), $"{path}.MaxC: expected {expected.MaxC}, got {actual.MaxC}");
Assert.True(BitEqual(expected.StartScale, actual.StartScale), $"{path}.StartScale: expected {expected.StartScale}, got {actual.StartScale}");
Assert.True(BitEqual(expected.FinalScale, actual.FinalScale), $"{path}.FinalScale: expected {expected.FinalScale}, got {actual.FinalScale}");
Assert.True(BitEqual(expected.ScaleRand, actual.ScaleRand), $"{path}.ScaleRand: expected {expected.ScaleRand}, got {actual.ScaleRand}");
Assert.True(BitEqual(expected.StartTrans, actual.StartTrans), $"{path}.StartTrans: expected {expected.StartTrans}, got {actual.StartTrans}");
Assert.True(BitEqual(expected.FinalTrans, actual.FinalTrans), $"{path}.FinalTrans: expected {expected.FinalTrans}, got {actual.FinalTrans}");
Assert.True(BitEqual(expected.TransRand, actual.TransRand), $"{path}.TransRand: expected {expected.TransRand}, got {actual.TransRand}");
Assert.True(expected.IsParentLocal == actual.IsParentLocal, $"{path}.IsParentLocal: expected {expected.IsParentLocal}, got {actual.IsParentLocal}");
}
private static void AssertTextureKeyEqual(TextureKey expected, TextureKey actual, string path) {
Assert.True(expected.Equals(actual),
$"{path}: expected SurfaceId=0x{expected.SurfaceId:X8} PaletteId=0x{expected.PaletteId:X8} Stippling={expected.Stippling} IsSolid={expected.IsSolid}, " +
$"got SurfaceId=0x{actual.SurfaceId:X8} PaletteId=0x{actual.PaletteId:X8} Stippling={actual.Stippling} IsSolid={actual.IsSolid}");
}
private static void AssertBoundingBoxEqual(Chorizite.Core.Lib.BoundingBox expected, Chorizite.Core.Lib.BoundingBox actual, string path) {
AssertVector3Equal(expected.Min, actual.Min, $"{path}.Min");
AssertVector3Equal(expected.Max, actual.Max, $"{path}.Max");
}
private static void AssertSphereEqual(Sphere? expected, Sphere? actual, string path) {
if (expected is null && actual is null) return;
Assert.True(expected is not null, $"{path}: expected null but actual was non-null");
Assert.True(actual is not null, $"{path}: expected non-null but actual was null");
AssertVector3Equal(expected.Origin, actual.Origin, $"{path}.Origin");
Assert.True(BitEqual(expected.Radius, actual.Radius), $"{path}.Radius: expected {expected.Radius}, got {actual.Radius}");
}
private static void AssertVector3Equal(System.Numerics.Vector3 expected, System.Numerics.Vector3 actual, string path) {
Assert.True(BitEqual(expected, actual), $"{path}: expected {expected}, got {actual}");
}
private static void AssertVector3ArrayEqual(System.Numerics.Vector3[] expected, System.Numerics.Vector3[] actual, string path) {
Assert.True(expected.Length == actual.Length, $"{path}.Length: expected {expected.Length}, got {actual.Length}");
for (int i = 0; i < expected.Length; i++)
AssertVector3Equal(expected[i], actual[i], $"{path}[{i}]");
}
private static void AssertMatrixEqual(System.Numerics.Matrix4x4 expected, System.Numerics.Matrix4x4 actual, string path) {
Assert.True(BitEqual(expected, actual), $"{path}: expected {expected}, got {actual}");
}
// ---- bitwise float equality ----------------------------------------------
// The pak stores raw IEEE-754 bits, so "round-trip preserved the field"
// means BIT equality, not `==` semantics: `==` is false for NaN==NaN
// (a NaN payload surviving the round-trip would FAIL a correct
// serializer) and true for -0.0==+0.0 (a sign-bit flip would silently
// PASS). Review finding 9.
private static bool BitEqual(float a, float b) =>
BitConverter.SingleToInt32Bits(a) == BitConverter.SingleToInt32Bits(b);
private static bool BitEqual(double a, double b) =>
BitConverter.DoubleToInt64Bits(a) == BitConverter.DoubleToInt64Bits(b);
private static bool BitEqual(System.Numerics.Vector2 a, System.Numerics.Vector2 b) =>
BitEqual(a.X, b.X) && BitEqual(a.Y, b.Y);
private static bool BitEqual(System.Numerics.Vector3 a, System.Numerics.Vector3 b) =>
BitEqual(a.X, b.X) && BitEqual(a.Y, b.Y) && BitEqual(a.Z, b.Z);
private static bool BitEqual(System.Numerics.Matrix4x4 a, System.Numerics.Matrix4x4 b) =>
BitEqual(a.M11, b.M11) && BitEqual(a.M12, b.M12) && BitEqual(a.M13, b.M13) && BitEqual(a.M14, b.M14) &&
BitEqual(a.M21, b.M21) && BitEqual(a.M22, b.M22) && BitEqual(a.M23, b.M23) && BitEqual(a.M24, b.M24) &&
BitEqual(a.M31, b.M31) && BitEqual(a.M32, b.M32) && BitEqual(a.M33, b.M33) && BitEqual(a.M34, b.M34) &&
BitEqual(a.M41, b.M41) && BitEqual(a.M42, b.M42) && BitEqual(a.M43, b.M43) && BitEqual(a.M44, b.M44);
}

297
tests/AcDream.Content.Tests/ObjectMeshDataSerializerTests.cs Normal file
View file

@ -0,0 +1,297 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Numerics;
using AcDream.Content.Pak;
using Chorizite.Core.Lib;
using Chorizite.Core.Render.Enums;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using CullMode = DatReaderWriter.Enums.CullMode;
using StipplingType = DatReaderWriter.Enums.StipplingType;
using EmitterType = DatReaderWriter.Enums.EmitterType;
using ParticleType = DatReaderWriter.Enums.ParticleType;
namespace AcDream.Content.Tests;
public class ObjectMeshDataSerializerTests {
// ---- fixture builders ---------------------------------------------------
private static ObjectMeshData EmptyObject() => new() {
ObjectId = 0x0100_0001u,
IsSetup = false,
};
private static ObjectMeshData VerticesAndIndicesOnly() {
var data = new ObjectMeshData {
ObjectId = 0x0100_0002u,
IsSetup = false,
Vertices = new[] {
new VertexPositionNormalTexture(new Vector3(1, 2, 3), new Vector3(0, 0, 1), new Vector2(0, 0)),
new VertexPositionNormalTexture(new Vector3(4, 5, 6), new Vector3(0, 1, 0), new Vector2(1, 0)),
new VertexPositionNormalTexture(new Vector3(7, 8, 9), new Vector3(1, 0, 0), new Vector2(1, 1)),
},
BoundingBox = new BoundingBox(new Vector3(1, 2, 3), new Vector3(7, 8, 9)),
SortCenter = new Vector3(4, 5, 6),
DIDDegrade = 0x11223344,
};
data.Batches.Add(new MeshBatchData {
Indices = new ushort[] { 0, 1, 2 },
TextureFormat = (64, 64, TextureFormat.RGBA8),
TextureKey = new TextureKey { SurfaceId = 0x08000001, PaletteId = 0x04000001, Stippling = StipplingType.Both, IsSolid = true },
TextureIndex = 0,
TextureData = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 },
UploadPixelFormat = AcDream.Content.UploadPixelFormat.Rgba,
UploadPixelType = AcDream.Content.UploadPixelType.UnsignedByte,
CullMode = CullMode.Clockwise,
});
return data;
}
private static ObjectMeshData MultipleTextureBatchGroups() {
var data = EmptyObject();
data.ObjectId = 0x0100_0003u;
TextureBatchData Batch(uint surfaceId, string tag) => new() {
Key = new TextureKey { SurfaceId = surfaceId, PaletteId = 1, Stippling = StipplingType.Positive, IsSolid = false },
TextureData = System.Text.Encoding.ASCII.GetBytes(tag),
UploadPixelFormat = AcDream.Content.UploadPixelFormat.Rgba,
UploadPixelType = AcDream.Content.UploadPixelType.UnsignedByte,
Indices = new List<ushort> { 0, 1, 2, 2, 3, 0 },
CullMode = CullMode.CounterClockwise,
IsTransparent = true,
IsAdditive = false,
HasWrappingUVs = true,
};
data.TextureBatches[(32, 32, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(1, "a"), Batch(2, "b") };
data.TextureBatches[(64, 64, TextureFormat.DXT5)] = new List<TextureBatchData> { Batch(3, "c") };
data.TextureBatches[(16, 16, TextureFormat.A8)] = new List<TextureBatchData> { Batch(4, "d"), Batch(5, "e"), Batch(6, "f") };
return data;
}
private static ObjectMeshData SetupWithParts() {
var data = EmptyObject();
data.ObjectId = 0x0200_0001u;
data.IsSetup = true;
data.SetupParts.Add((0x0100_0010u, Matrix4x4.CreateTranslation(1, 2, 3)));
data.SetupParts.Add((0x0100_0011u, Matrix4x4.CreateFromYawPitchRoll(0.1f, 0.2f, 0.3f)));
return data;
}
private static ParticleEmitter BuildEmitter(uint id) => new() {
Id = id,
DataCategory = 0x2A,
Unknown = 7,
EmitterType = EmitterType.BirthratePerSec,
ParticleType = ParticleType.Explode,
GfxObjId = new QualifiedDataId<GfxObj> { DataId = 0x0100_0099u },
HwGfxObjId = new QualifiedDataId<GfxObj> { DataId = 0x0100_009Au },
Birthrate = 2.5,
MaxParticles = 40,
InitialParticles = 5,
TotalParticles = 100,
TotalSeconds = 3.0,
Lifespan = 1.5,
LifespanRand = 0.25,
OffsetDir = new Vector3(0, 0, 1),
MinOffset = 0.1f,
MaxOffset = 0.5f,
A = new Vector3(1, 0, 0),
MinA = 0.9f,
MaxA = 1.1f,
B = new Vector3(0, 1, 0),
MinB = 0.8f,
MaxB = 1.2f,
C = new Vector3(0, 0, 1),
MinC = 0.7f,
MaxC = 1.3f,
StartScale = 0.5f,
FinalScale = 1.5f,
ScaleRand = 0.05f,
StartTrans = 1f,
FinalTrans = 0f,
TransRand = 0.1f,
IsParentLocal = true,
};
private static ObjectMeshData WithEmitters() {
var data = EmptyObject();
data.ObjectId = 0x0200_0002u;
data.IsSetup = true;
data.ParticleEmitters.Add(new StagedEmitter {
Emitter = BuildEmitter(0x2A00_0001u),
PartIndex = 3,
Offset = Matrix4x4.CreateTranslation(10, 20, 30),
});
data.ParticleEmitters.Add(new StagedEmitter {
Emitter = BuildEmitter(0x2A00_0002u),
PartIndex = 0,
Offset = Matrix4x4.Identity,
});
return data;
}
private static ObjectMeshData WithNullableFieldsPresent() {
var data = EmptyObject();
data.ObjectId = 0x0300_0001u;
data.SelectionSphere = new Sphere { Origin = new Vector3(1, 1, 1), Radius = 2.5f };
data.Batches.Add(new MeshBatchData {
Indices = new ushort[] { 0 },
UploadPixelFormat = AcDream.Content.UploadPixelFormat.Rgba,
UploadPixelType = AcDream.Content.UploadPixelType.UnsignedByte,
});
return data;
}
private static ObjectMeshData WithNullableFieldsAbsent() {
var data = EmptyObject();
data.ObjectId = 0x0300_0002u;
data.SelectionSphere = null;
data.Batches.Add(new MeshBatchData {
Indices = new ushort[] { 0 },
UploadPixelFormat = null,
UploadPixelType = null,
});
return data;
}
private static ObjectMeshData WithEdgeLines() {
var data = EmptyObject();
data.ObjectId = 0x0400_0001u;
data.EdgeLines = new[] {
new Vector3(0, 0, 0), new Vector3(1, 0, 0),
new Vector3(1, 0, 0), new Vector3(1, 1, 0),
};
return data;
}
private static ObjectMeshData WithNestedEnvCellGeometry() {
var data = EmptyObject();
data.ObjectId = 0x0D00_0001_0000_0100u | (1UL << 32);
data.IsSetup = true;
data.EnvCellGeometry = VerticesAndIndicesOnly();
return data;
}
public static IEnumerable<object[]> AllFixtures() {
yield return new object[] { EmptyObject() };
yield return new object[] { VerticesAndIndicesOnly() };
yield return new object[] { MultipleTextureBatchGroups() };
yield return new object[] { SetupWithParts() };
yield return new object[] { WithEmitters() };
yield return new object[] { WithNullableFieldsPresent() };
yield return new object[] { WithNullableFieldsAbsent() };
yield return new object[] { WithEdgeLines() };
yield return new object[] { WithNestedEnvCellGeometry() };
}
// ---- round-trip tests ----------------------------------------------------
[Theory]
[MemberData(nameof(AllFixtures))]
public void RoundTrip_PreservesEveryField(ObjectMeshData original) {
using var ms = new MemoryStream();
ObjectMeshDataSerializer.Write(original, ms);
var bytes = ms.ToArray();
var readBack = ObjectMeshDataSerializer.Read(bytes);
ObjectMeshDataEquality.AssertEqual(original, readBack);
}
// ---- determinism -----------------------------------------------------
[Fact]
public void Serialize_SameInstanceTwice_ByteIdentical() {
var data = MultipleTextureBatchGroups();
using var ms1 = new MemoryStream();
ObjectMeshDataSerializer.Write(data, ms1);
using var ms2 = new MemoryStream();
ObjectMeshDataSerializer.Write(data, ms2);
Assert.Equal(ms1.ToArray(), ms2.ToArray());
}
[Fact]
public void Serialize_DictionaryInsertedInDifferentOrders_ByteIdentical() {
TextureBatchData Batch(uint surfaceId) => new() {
Key = new TextureKey { SurfaceId = surfaceId, PaletteId = 1, Stippling = StipplingType.None, IsSolid = false },
TextureData = new byte[] { (byte)surfaceId },
Indices = new List<ushort> { 0, 1, 2 },
CullMode = CullMode.None,
};
var a = EmptyObject();
a.ObjectId = 0x0500_0001u;
a.TextureBatches[(32, 32, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(1) };
a.TextureBatches[(64, 64, TextureFormat.DXT5)] = new List<TextureBatchData> { Batch(2) };
a.TextureBatches[(16, 16, TextureFormat.A8)] = new List<TextureBatchData> { Batch(3) };
var b = EmptyObject();
b.ObjectId = 0x0500_0001u;
// Insert in a completely different order.
b.TextureBatches[(16, 16, TextureFormat.A8)] = new List<TextureBatchData> { Batch(3) };
b.TextureBatches[(32, 32, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(1) };
b.TextureBatches[(64, 64, TextureFormat.DXT5)] = new List<TextureBatchData> { Batch(2) };
using var msA = new MemoryStream();
ObjectMeshDataSerializer.Write(a, msA);
using var msB = new MemoryStream();
ObjectMeshDataSerializer.Write(b, msB);
Assert.Equal(msA.ToArray(), msB.ToArray());
}
[Fact]
public void Write_SortsTextureBatchesByWidthHeightFormatKeyTuple() {
// Insert in scrambled order; the serialized bytes must reflect the
// KEY-sorted order (Width, Height, Format), not insertion order.
var data = EmptyObject();
data.ObjectId = 0x0600_0001u;
// Each batch's TextureData is a distinctive multi-byte marker (not a
// single ambiguous byte value that could collide with unrelated
// length-prefix / width / height bytes elsewhere in the stream).
TextureBatchData Batch(byte[] marker) => new() {
Key = default,
TextureData = marker,
Indices = new List<ushort>(),
CullMode = CullMode.None,
};
byte[] markerA = { 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA };
byte[] markerB = { 0xBB, 0xBB, 0xBB, 0xBB, 0xBB, 0xBB, 0xBB, 0xBB };
byte[] markerC = { 0xCC, 0xCC, 0xCC, 0xCC, 0xCC, 0xCC, 0xCC, 0xCC };
data.TextureBatches[(100, 1, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(markerC) };
data.TextureBatches[(1, 1, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(markerA) };
data.TextureBatches[(1, 100, TextureFormat.RGBA8)] = new List<TextureBatchData> { Batch(markerB) };
using var ms = new MemoryStream();
ObjectMeshDataSerializer.Write(data, ms);
var bytes = ms.ToArray();
// markerA (width=1,height=1) < markerB (width=1,height=100) <
// markerC (width=100,height=1) in ascending (Width, Height) order.
int iA = IndexOfSequence(bytes, markerA);
int iB = IndexOfSequence(bytes, markerB);
int iC = IndexOfSequence(bytes, markerC);
Assert.True(iA >= 0 && iB >= 0 && iC >= 0, "all three markers must appear in the stream");
Assert.True(iA < iB, $"markerA (width=1,height=1) must precede markerB (width=1,height=100): iA={iA} iB={iB}");
Assert.True(iB < iC, $"markerB (width=1,height=100) must precede markerC (width=100,height=1): iB={iB} iC={iC}");
}
private static int IndexOfSequence(byte[] haystack, byte[] needle) {
for (int i = 0; i <= haystack.Length - needle.Length; i++) {
bool match = true;
for (int j = 0; j < needle.Length; j++) {
if (haystack[i + j] != needle[j]) { match = false; break; }
}
if (match) return i;
}
return -1;
}
}

161
tests/AcDream.Content.Tests/PakEquivalenceTests.cs Normal file
View file

@ -0,0 +1,161 @@
using System.Collections.Generic;
using System.IO;
using System.Linq;
using AcDream.Content.Pak;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
namespace AcDream.Content.Tests;
/// <summary>
/// MP1b Task 6: dat-gated live-vs-pak equivalence suite. Runs MeshExtractor
/// LIVE and bakes the SAME ids to a temp pak, reads the pak back, and deep-
/// compares field-by-field via the Task 3 comparator. Because the bake tool
/// and the live client drive the identical MeshExtractor code (MP1a), this
/// test is proving the pak ROUND-TRIP (serialize/deserialize) preserves
/// what extraction actually produces on real content — not re-verifying the
/// extraction algorithm itself (that's the existing Conformance suite's job).
///
/// Skips cleanly when the real dats are absent (CI), matching
/// DatConcurrencyStressTests' convention.
/// </summary>
public sealed class PakEquivalenceTests {
// Known-tricky GfxObj ids reused from existing conformance fixtures:
// 0x010002B4 / 0x010008A8 — #119 "[up-null] upload returned null" dump
// targets (Issue119UpNullGfxObjDumpTests).
// 0x010014C3 — the #113-saga Holtburg meeting-hall shell
// (Issue119UpNullGfxObjDumpTests.ShellModel_NoTexturedPolyIsDropped).
private static readonly uint[] KnownTrickyGfxObjIds = { 0x010002B4u, 0x010008A8u, 0x010014C3u };
// Setup ids reused from existing physics/conformance fixtures:
// 0x020019FF — the door setup (DoorBugTrajectoryReplayTests,
// DoorSetupGfxObjInspectionTests, DoorCollisionApparatusTests).
// 0x020005D8 / 0x020003F2 — Issue119TowerDumpTests fixtures.
private static readonly uint[] SetupIds = { 0x020019FFu, 0x020005D8u, 0x020003F2u };
private const uint HoltburgLandblock = 0xA9B40000u; // ConformanceDats.HoltburgLandblock
[Fact]
public void LiveExtraction_MatchesPakRoundTrip_OnFixtureIdSet() {
var datDir = ContentConformanceDats.ResolveDatDir();
if (datDir is null) return; // dats absent (CI) — skip, matching suite convention
using var dats = new DatCollection(datDir, DatAccessType.Read);
// The unified AcDream.Content.DatCollectionAdapter — same class the
// client and the bake tool use (MP1b review finding 7).
using var datReaderWriter = new DatCollectionAdapter(dats);
var logger = new TestConsoleLogger();
var sideStaged = new List<ObjectMeshData>();
var extractor = new MeshExtractor(datReaderWriter, logger, data => sideStaged.Add(data));
var gfxObjIds = BuildGfxObjIdSet(dats);
var setupIds = SetupIds.ToList();
var envCellIds = BuildEnvCellIdSet(dats, HoltburgLandblock, minCount: 5);
Assert.True(gfxObjIds.Count >= 10, $"fixture GfxObj id set unexpectedly small ({gfxObjIds.Count})");
Assert.True(setupIds.Count >= 3, $"fixture Setup id set unexpectedly small ({setupIds.Count})");
Assert.True(envCellIds.Count >= 5, $"fixture EnvCell id set unexpectedly small ({envCellIds.Count})");
var work = new List<(PakAssetType Type, uint FileId, ulong ExtractorId, bool IsSetup)>();
work.AddRange(gfxObjIds.Select(id => (PakAssetType.GfxObjMesh, id, (ulong)id, false)));
work.AddRange(setupIds.Select(id => (PakAssetType.SetupMesh, id, (ulong)id, true)));
// isSetup: false for EnvCell — matches the runtime's own request sites
// (WbMeshAdapter.IncrementRefCount/EnsureLoaded pass isSetup: false for
// every MeshRef id, incl. cell-geometry ids) and BakeRunner's call site.
// (Review finding 10 — the two call sites previously disagreed.)
work.AddRange(envCellIds.Select(id => (PakAssetType.EnvCellMesh, id, id | 0x1_0000_0000UL, false)));
// ---- LIVE extraction (golden) ----
var golden = new Dictionary<(PakAssetType, uint), ObjectMeshData>();
var extractionFailures = new List<string>();
foreach (var (type, fileId, extractorId, isSetup) in work) {
var data = extractor.PrepareMeshData(extractorId, isSetup);
if (data is null) {
extractionFailures.Add($"{type} 0x{fileId:X8}: live extraction returned null");
continue;
}
golden[(type, fileId)] = data;
}
Assert.True(extractionFailures.Count == 0,
$"{extractionFailures.Count} fixture ids failed LIVE extraction (fixture assumption broke): " +
string.Join(" | ", extractionFailures));
// ---- bake the SAME ids to a temp pak ----
var pakPath = Path.Combine(Path.GetTempPath(), $"acdream-equivtest-{System.Guid.NewGuid():N}.pak");
try {
var header = new PakHeader {
FormatVersion = 1,
PortalIteration = (uint)dats.Portal.Iteration!.CurrentIteration,
CellIteration = (uint)dats.Cell.Iteration!.CurrentIteration,
HighResIteration = (uint)dats.HighRes.Iteration!.CurrentIteration,
LanguageIteration = (uint)dats.Local.Iteration!.CurrentIteration,
BakeToolVersion = 1,
};
using (var writer = new PakWriter(pakPath, header)) {
foreach (var ((type, fileId), data) in golden) {
writer.AddBlob(PakKey.Compose(type, fileId), data);
}
writer.Finish();
}
// ---- read back and deep-compare ----
using var reader = new PakReader(pakPath);
var mismatches = new List<string>();
foreach (var ((type, fileId), expected) in golden) {
var key = PakKey.Compose(type, fileId);
if (!reader.TryReadObjectMeshData(key, out var actual)) {
mismatches.Add($"{type} 0x{fileId:X8}: pak read failed (missing or CRC mismatch)");
continue;
}
try {
ObjectMeshDataEquality.AssertEqual(expected, actual);
}
catch (Xunit.Sdk.XunitException ex) {
mismatches.Add($"{type} 0x{fileId:X8}: {ex.Message}");
}
}
Assert.True(mismatches.Count == 0,
$"{mismatches.Count}/{golden.Count} fixture ids mismatched between live extraction and pak round-trip:\n" +
string.Join("\n", mismatches));
}
finally {
if (File.Exists(pakPath)) File.Delete(pakPath);
}
}
/// <summary>
/// Known-tricky ids (#119/#113 dump fixtures) plus enough additional
/// GfxObjs (deterministically, the first N ids in dat order after the
/// tricky set) to reach at least 10 total.
/// </summary>
private static List<uint> BuildGfxObjIdSet(DatCollection dats) {
var ids = new List<uint>(KnownTrickyGfxObjIds);
var seen = new HashSet<uint>(ids);
foreach (var id in dats.GetAllIdsOfType<GfxObj>()) {
if (ids.Count >= 10) break;
if (seen.Add(id)) ids.Add(id);
}
return ids;
}
/// <summary>Walks the Holtburg landblock's LandBlockInfo.NumCells range (mirrors StipplingSurfaceEquivalenceTests' enumeration) to get at least <paramref name="minCount"/> real EnvCell ids.</summary>
private static List<uint> BuildEnvCellIdSet(DatCollection dats, uint landblockId, int minCount) {
var ids = new List<uint>();
var lbInfo = dats.Get<LandBlockInfo>(landblockId | 0xFFFEu);
Assert.True(lbInfo is not null, $"LandBlockInfo for landblock 0x{landblockId:X8} not found — fixture assumption broke");
Assert.True(lbInfo!.NumCells >= minCount,
$"landblock 0x{landblockId:X8} has only {lbInfo.NumCells} cells — fixture assumption broke (need >= {minCount})");
uint firstCellId = landblockId | 0x0100u;
for (uint offset = 0; offset < lbInfo.NumCells && ids.Count < minCount; offset++) {
uint envCellId = firstCellId + offset;
if (dats.Get<EnvCell>(envCellId) is not null) ids.Add(envCellId);
}
return ids;
}
}

145
tests/AcDream.Content.Tests/PakFormatTests.cs Normal file
View file

@ -0,0 +1,145 @@
using System.IO;
using AcDream.Content.Pak;
namespace AcDream.Content.Tests;
public class PakFormatTests {
[Fact]
public void Header_Size_Is64Bytes() {
Assert.Equal(64, PakHeader.Size);
}
[Fact]
public void TocEntry_Size_Is24Bytes() {
Assert.Equal(24, PakTocEntry.Size);
}
[Fact]
public void Header_Magic_IsAcpkLittleEndian() {
// 'A'=0x41 'C'=0x43 'P'=0x50 'K'=0x4B — little-endian dword reads
// back as 0x4B504341 per the normative spec.
Assert.Equal(0x4B504341u, PakHeader.MagicValue);
}
[Fact]
public void Header_WriteThenRead_RoundTripsEveryField() {
var header = new PakHeader {
FormatVersion = 1,
PortalIteration = 111,
CellIteration = 222,
HighResIteration = 333,
LanguageIteration = 444,
TocOffset = 0x1_0000_0002UL,
TocCount = 777,
BakeToolVersion = 1,
};
using var ms = new MemoryStream();
header.WriteTo(ms);
Assert.Equal(PakHeader.Size, ms.Length);
ms.Position = 0;
var readBack = PakHeader.ReadFrom(ms);
Assert.Equal(PakHeader.MagicValue, readBack.Magic);
Assert.Equal(header.FormatVersion, readBack.FormatVersion);
Assert.Equal(header.PortalIteration, readBack.PortalIteration);
Assert.Equal(header.CellIteration, readBack.CellIteration);
Assert.Equal(header.HighResIteration, readBack.HighResIteration);
Assert.Equal(header.LanguageIteration, readBack.LanguageIteration);
Assert.Equal(header.TocOffset, readBack.TocOffset);
Assert.Equal(header.TocCount, readBack.TocCount);
Assert.Equal(header.BakeToolVersion, readBack.BakeToolVersion);
}
[Fact]
public void Header_ReadFrom_Span_RoundTrips() {
var header = new PakHeader {
FormatVersion = 1,
PortalIteration = 5,
CellIteration = 6,
HighResIteration = 7,
LanguageIteration = 8,
TocOffset = 999,
TocCount = 3,
BakeToolVersion = 1,
};
Span<byte> buf = stackalloc byte[PakHeader.Size];
header.WriteTo(buf);
var readBack = PakHeader.ReadFrom((ReadOnlySpan<byte>)buf);
Assert.Equal(header.CellIteration, readBack.CellIteration);
Assert.Equal(header.TocOffset, readBack.TocOffset);
}
[Fact]
public void Header_ReservedBytes_AreZero() {
var header = new PakHeader { FormatVersion = 1, BakeToolVersion = 1 };
Span<byte> buf = stackalloc byte[PakHeader.Size];
header.WriteTo(buf);
// offset 40, length 24 per the normative layout
for (int i = 40; i < 64; i++) {
Assert.Equal(0, buf[i]);
}
}
[Fact]
public void Header_FieldOffsets_MatchNormativeLayout() {
var header = new PakHeader {
FormatVersion = 0x11111111,
PortalIteration = 0x22222222,
CellIteration = 0x33333333,
HighResIteration = 0x44444444,
LanguageIteration = 0x55555555,
TocOffset = 0x6666666677777777UL,
TocCount = 0x88888888,
BakeToolVersion = 0x99999999,
};
Span<byte> buf = stackalloc byte[PakHeader.Size];
header.WriteTo(buf);
Assert.Equal(PakHeader.MagicValue, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[0..4]));
Assert.Equal(0x11111111u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[4..8]));
Assert.Equal(0x22222222u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[8..12]));
Assert.Equal(0x33333333u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[12..16]));
Assert.Equal(0x44444444u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[16..20]));
Assert.Equal(0x55555555u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[20..24]));
Assert.Equal(0x6666666677777777UL, System.Buffers.Binary.BinaryPrimitives.ReadUInt64LittleEndian(buf[24..32]));
Assert.Equal(0x88888888u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[32..36]));
Assert.Equal(0x99999999u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[36..40]));
}
[Fact]
public void TocEntry_WriteThenRead_RoundTrips() {
var entry = new PakTocEntry {
Key = PakKey.Compose(PakAssetType.GfxObjMesh, 0x010002B4u),
Offset = 0x4000,
Length = 12345,
Crc32 = 0xDEADBEEF,
};
Span<byte> buf = stackalloc byte[PakTocEntry.Size];
entry.WriteTo(buf);
var readBack = PakTocEntry.ReadFrom((ReadOnlySpan<byte>)buf);
Assert.Equal(entry.Key, readBack.Key);
Assert.Equal(entry.Offset, readBack.Offset);
Assert.Equal(entry.Length, readBack.Length);
Assert.Equal(entry.Crc32, readBack.Crc32);
}
[Fact]
public void TocEntry_FieldOffsets_MatchNormativeLayout() {
var entry = new PakTocEntry {
Key = 0x1111111122222222UL,
Offset = 0x3333333344444444UL,
Length = 0x55555555,
Crc32 = 0x66666666,
};
Span<byte> buf = stackalloc byte[PakTocEntry.Size];
entry.WriteTo(buf);
Assert.Equal(0x1111111122222222UL, System.Buffers.Binary.BinaryPrimitives.ReadUInt64LittleEndian(buf[0..8]));
Assert.Equal(0x3333333344444444UL, System.Buffers.Binary.BinaryPrimitives.ReadUInt64LittleEndian(buf[8..16]));
Assert.Equal(0x55555555u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[16..20]));
Assert.Equal(0x66666666u, System.Buffers.Binary.BinaryPrimitives.ReadUInt32LittleEndian(buf[20..24]));
}
}

75
tests/AcDream.Content.Tests/PakKeyTests.cs Normal file
View file

@ -0,0 +1,75 @@
using AcDream.Content.Pak;
namespace AcDream.Content.Tests;
public class PakKeyTests {
[Theory]
[InlineData(PakAssetType.GfxObjMesh, 0u)]
[InlineData(PakAssetType.GfxObjMesh, 0x01000001u)]
[InlineData(PakAssetType.SetupMesh, 0x020019FFu)]
[InlineData(PakAssetType.EnvCellMesh, 0xA9B40100u)]
[InlineData(PakAssetType.GfxObjMesh, 0xFFFFFFFFu)] // max fileId
[InlineData(PakAssetType.EnvCellMesh, 0xFFFFFFFFu)]
public void ComposeDecompose_RoundTrips(PakAssetType type, uint fileId) {
ulong key = PakKey.Compose(type, fileId);
var (decodedType, decodedFileId) = PakKey.Decompose(key);
Assert.Equal(type, decodedType);
Assert.Equal(fileId, decodedFileId);
}
[Fact]
public void Compose_LowFourBytesReserved() {
// Low 24 bits are reserved (zero in v1) — fileId << 24 must not spill
// into them, and the reserved region must actually read back as zero.
ulong key = PakKey.Compose(PakAssetType.GfxObjMesh, 0xFFFFFFFFu);
Assert.Equal(0u, (uint)(key & 0xFFFFFFu));
}
[Fact]
public void Compose_TypeOccupiesTopByte() {
ulong key = PakKey.Compose(PakAssetType.SetupMesh, 0u);
Assert.Equal((byte)PakAssetType.SetupMesh, (byte)(key >> 56));
}
[Theory]
[InlineData(PakAssetType.GfxObjMesh, 1)]
[InlineData(PakAssetType.SetupMesh, 2)]
[InlineData(PakAssetType.EnvCellMesh, 3)]
public void AssetType_NumericValuesAreStable(PakAssetType type, byte expected) {
// These values are a wire format — pin them so a future refactor can't
// silently renumber the enum and corrupt existing paks.
Assert.Equal(expected, (byte)type);
}
[Fact]
public void KeyOrdering_MatchesTypeThenFileIdOrdering() {
// Ascending key order must equal ascending (type, fileId) tuple order —
// this is what makes the TOC's binary search over raw u64 keys valid.
var pairs = new (PakAssetType Type, uint FileId)[] {
(PakAssetType.GfxObjMesh, 0u),
(PakAssetType.GfxObjMesh, 1u),
(PakAssetType.GfxObjMesh, 0xFFFFFFFFu),
(PakAssetType.SetupMesh, 0u),
(PakAssetType.SetupMesh, 0x020019FFu),
(PakAssetType.EnvCellMesh, 0u),
(PakAssetType.EnvCellMesh, 0xA9B40100u),
};
var keys = pairs.Select(p => PakKey.Compose(p.Type, p.FileId)).ToArray();
// keys[] as generated must already be strictly ascending since pairs[]
// is in ascending tuple order.
for (int i = 1; i < keys.Length; i++) {
Assert.True(keys[i] > keys[i - 1],
$"key[{i}]=0x{keys[i]:X16} should be > key[{i - 1}]=0x{keys[i - 1]:X16} " +
$"for tuple order ({pairs[i - 1]}) < ({pairs[i]})");
}
// Sorting the keys numerically must reproduce the same order as sorting
// the tuples lexicographically by (Type, FileId).
var numericSorted = keys.OrderBy(k => k).ToArray();
var tupleSorted = pairs.OrderBy(p => (byte)p.Type).ThenBy(p => p.FileId)
.Select(p => PakKey.Compose(p.Type, p.FileId)).ToArray();
Assert.Equal(tupleSorted, numericSorted);
}
}

478
tests/AcDream.Content.Tests/PakRoundTripTests.cs Normal file
View file

@ -0,0 +1,478 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Numerics;
using AcDream.Content.Pak;
namespace AcDream.Content.Tests;
public class PakRoundTripTests : IDisposable {
private readonly List<string> _tempFiles = new();
private string NewTempPakPath() {
var path = Path.Combine(Path.GetTempPath(), $"acdream-paktest-{Guid.NewGuid():N}.pak");
_tempFiles.Add(path);
return path;
}
public void Dispose() {
foreach (var f in _tempFiles) {
try { if (File.Exists(f)) File.Delete(f); } catch { /* best effort cleanup */ }
}
}
private static ObjectMeshData MakeSyntheticData(uint fileId, int vertexCount) {
var vertices = new VertexPositionNormalTexture[vertexCount];
for (int i = 0; i < vertexCount; i++) {
vertices[i] = new VertexPositionNormalTexture(
new Vector3(i, i * 2, i * 3),
new Vector3(0, 0, 1),
new Vector2(i * 0.1f, i * 0.2f));
}
return new ObjectMeshData {
ObjectId = fileId,
IsSetup = false,
Vertices = vertices,
DIDDegrade = fileId + 1,
};
}
private static (PakAssetType Type, uint FileId, ObjectMeshData Data)[] MakeBlobSet(int n) {
var result = new (PakAssetType, uint, ObjectMeshData)[n];
for (int i = 0; i < n; i++) {
var type = (PakAssetType)((i % 3) + 1);
uint fileId = 0x0100_0000u + (uint)i;
result[i] = (type, fileId, MakeSyntheticData(fileId, i + 1));
}
return result;
}
private static PakHeader WritePak(string path, (PakAssetType Type, uint FileId, ObjectMeshData Data)[] blobs) {
var header = new PakHeader {
FormatVersion = 1,
PortalIteration = 10,
CellIteration = 20,
HighResIteration = 30,
LanguageIteration = 40,
BakeToolVersion = 1,
};
using var writer = new PakWriter(path, header);
foreach (var (type, fileId, data) in blobs) {
writer.AddBlob(PakKey.Compose(type, fileId), data);
}
writer.Finish();
return header;
}
[Fact]
public void WriteThenOpen_HeaderFieldsMatch() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(5);
var written = WritePak(path, blobs);
using var reader = new PakReader(path);
Assert.Equal(written.FormatVersion, reader.Header.FormatVersion);
Assert.Equal(written.PortalIteration, reader.Header.PortalIteration);
Assert.Equal(written.CellIteration, reader.Header.CellIteration);
Assert.Equal(written.HighResIteration, reader.Header.HighResIteration);
Assert.Equal(written.LanguageIteration, reader.Header.LanguageIteration);
Assert.Equal(written.BakeToolVersion, reader.Header.BakeToolVersion);
Assert.Equal((uint)blobs.Length, reader.Header.TocCount);
}
[Fact]
public void WriteThenOpen_EveryKeyFound() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(20);
WritePak(path, blobs);
using var reader = new PakReader(path);
foreach (var (type, fileId, _) in blobs) {
Assert.True(reader.ContainsKey(PakKey.Compose(type, fileId)),
$"key for type={type} fileId=0x{fileId:X8} should be found");
}
}
[Fact]
public void WriteThenOpen_BlobsDeserializeToDeepEqualObjects() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(8);
WritePak(path, blobs);
using var reader = new PakReader(path);
foreach (var (type, fileId, expected) in blobs) {
var key = PakKey.Compose(type, fileId);
Assert.True(reader.TryReadObjectMeshData(key, out var actual), $"expected key 0x{key:X16} to read successfully");
ObjectMeshDataEquality.AssertEqual(expected, actual);
}
}
[Fact]
public void MissingKey_ReturnsFalse() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(3);
WritePak(path, blobs);
using var reader = new PakReader(path);
var missingKey = PakKey.Compose(PakAssetType.GfxObjMesh, 0xFFFF_FFFEu);
Assert.False(reader.ContainsKey(missingKey));
Assert.False(reader.TryReadObjectMeshData(missingKey, out var data));
Assert.Null(data);
}
[Fact]
public void CorruptedBlob_CrcMismatch_TreatedAsMissing() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(4);
WritePak(path, blobs);
// Flip one byte inside the FIRST blob's region (right after the 64-byte header).
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.Position = PakHeader.Size + 4; // a few bytes into the first blob's payload
int b = fs.ReadByte();
fs.Position = PakHeader.Size + 4;
fs.WriteByte((byte)(b ^ 0xFF));
}
using var reader = new PakReader(path);
var key = PakKey.Compose(blobs[0].Type, blobs[0].FileId);
Assert.False(reader.TryReadObjectMeshData(key, out var data),
"a CRC-mismatched blob must be treated as missing");
Assert.Null(data);
}
[Fact]
public void CorruptedBlob_DoesNotAffectOtherBlobs() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(4);
WritePak(path, blobs);
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.Position = PakHeader.Size + 4;
int b = fs.ReadByte();
fs.Position = PakHeader.Size + 4;
fs.WriteByte((byte)(b ^ 0xFF));
}
using var reader = new PakReader(path);
// blobs[1..] should still read fine.
for (int i = 1; i < blobs.Length; i++) {
var key = PakKey.Compose(blobs[i].Type, blobs[i].FileId);
Assert.True(reader.TryReadObjectMeshData(key, out var actual), $"blob {i} should be unaffected by corruption in blob 0");
ObjectMeshDataEquality.AssertEqual(blobs[i].Data, actual);
}
}
[Fact]
public void Blobs_Are64ByteAligned() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(6);
WritePak(path, blobs);
using var reader = new PakReader(path);
foreach (var (type, fileId, _) in blobs) {
var offset = reader.GetBlobOffsetForTest(PakKey.Compose(type, fileId));
Assert.True(offset % 64 == 0, $"blob offset {offset} for type={type} fileId=0x{fileId:X8} must be 64-byte aligned");
}
}
[Fact]
public void TocBinarySearch_MatchesLinearScan() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(50);
WritePak(path, blobs);
using var reader = new PakReader(path);
var allKeys = blobs.Select(b => PakKey.Compose(b.Type, b.FileId)).ToArray();
foreach (var key in allKeys) {
bool binarySearchFound = reader.ContainsKey(key);
bool linearScanFound = reader.DebugLinearScanContainsKey(key);
Assert.Equal(linearScanFound, binarySearchFound);
}
// Also verify a handful of keys NOT present agree between both paths.
var absentKeys = new[] {
PakKey.Compose(PakAssetType.GfxObjMesh, 0xDEAD_0000u),
PakKey.Compose(PakAssetType.SetupMesh, 0xDEAD_0001u),
PakKey.Compose(PakAssetType.EnvCellMesh, 0xDEAD_0002u),
};
foreach (var key in absentKeys) {
Assert.Equal(reader.DebugLinearScanContainsKey(key), reader.ContainsKey(key));
Assert.False(reader.ContainsKey(key));
}
}
[Fact]
public void EmptyPak_OpensCleanly_NoKeysFound() {
var path = NewTempPakPath();
WritePak(path, Array.Empty<(PakAssetType, uint, ObjectMeshData)>());
using var reader = new PakReader(path);
Assert.Equal(0u, reader.Header.TocCount);
Assert.False(reader.ContainsKey(PakKey.Compose(PakAssetType.GfxObjMesh, 1)));
}
// ---- format-version enforcement (review finding 2) ---------------------
[Fact]
public void Writer_StampsFormatVersion_IgnoringTemplate() {
// The default-0 footgun: a caller building a header template without
// setting FormatVersion must still produce a CURRENT-version pak.
var path = NewTempPakPath();
using (var writer = new PakWriter(path, new PakHeader { BakeToolVersion = 1 })) {
writer.AddBlob(PakKey.Compose(PakAssetType.GfxObjMesh, 1), MakeSyntheticData(1, 1));
writer.Finish();
}
using var reader = new PakReader(path);
Assert.Equal(PakFormat.CurrentFormatVersion, reader.Header.FormatVersion);
}
[Theory]
[InlineData(0u)]
[InlineData(2u)]
public void Reader_RejectsWrongFormatVersion(uint wrongVersion) {
var path = NewTempPakPath();
WritePak(path, MakeBlobSet(2));
// Patch the header's formatVersion dword (offset 4) in place.
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.Position = 4;
Span<byte> buf = stackalloc byte[4];
System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(buf, wrongVersion);
fs.Write(buf);
}
var ex = Assert.Throws<InvalidDataException>(() => new PakReader(path));
Assert.Contains($"version {wrongVersion}", ex.Message);
Assert.Contains($"version {PakFormat.CurrentFormatVersion}", ex.Message);
}
// ---- reader robustness (review finding 3) -------------------------------
[Fact]
public void CorruptTocEntry_TreatedAsMissing_SiblingsUnaffected_NoThrow() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(4);
WritePak(path, blobs);
// Patch the FIRST victim entry's length field (entry offset +16) to a
// value that runs past the file end.
var victimKey = PakKey.Compose(blobs[0].Type, blobs[0].FileId);
long entryPos = FindTocEntryPosition(path, victimKey);
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.Position = entryPos + 16;
Span<byte> buf = stackalloc byte[4];
System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(buf, 0x7FFF_FFF0u);
fs.Write(buf);
}
using var reader = new PakReader(path); // must NOT throw — corrupt entry = missing
Assert.False(reader.ContainsKey(victimKey));
Assert.False(reader.TryReadObjectMeshData(victimKey, out var data));
Assert.Null(data);
for (int i = 1; i < blobs.Length; i++) {
var key = PakKey.Compose(blobs[i].Type, blobs[i].FileId);
Assert.True(reader.TryReadObjectMeshData(key, out var sibling), $"sibling blob {i} should be unaffected");
ObjectMeshDataEquality.AssertEqual(blobs[i].Data, sibling);
}
}
[Fact]
public void TruncatedPak_RefusedAtOpen() {
var path = NewTempPakPath();
WritePak(path, MakeBlobSet(4));
// Chop the file mid-TOC: the header claims 4 entries the file no
// longer holds — a structural fault, refused at open.
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.SetLength(fs.Length - PakTocEntry.Size - 4);
}
var ex = Assert.Throws<InvalidDataException>(() => new PakReader(path));
Assert.Contains("truncated", ex.Message);
}
[Fact]
public void HalfWrittenPak_UnfinalizedHeader_RefusedAtOpen() {
var path = NewTempPakPath();
// Simulate a bake crash between the placeholder-header write and
// Finish(): current-version header with TocOffset still 0, blob bytes
// behind it.
using (var fs = new FileStream(path, FileMode.Create, FileAccess.Write)) {
new PakHeader { FormatVersion = PakFormat.CurrentFormatVersion }.WriteTo(fs);
var junk = new byte[256];
new Random(42).NextBytes(junk);
fs.Write(junk);
}
var ex = Assert.Throws<InvalidDataException>(() => new PakReader(path));
Assert.Contains("unfinalized", ex.Message);
}
[Fact]
public void MalformedBlobBehindValidCrc_TreatedAsMissing_SiblingsUnaffected() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(3);
WritePak(path, blobs);
// Corrupt the FIRST blob's STRUCTURE (vertices count:i32 at blob
// offset 9 -> -1) and then RE-COMPUTE the CRC over the tampered bytes
// so the CRC tripwire passes — only the deserialization catch can
// save the read now.
var victimKey = PakKey.Compose(blobs[0].Type, blobs[0].FileId);
long entryPos = FindTocEntryPosition(path, victimKey);
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
// Read the victim entry to get offset+length.
fs.Position = entryPos;
var entryBuf = new byte[PakTocEntry.Size];
fs.ReadExactly(entryBuf);
var entry = PakTocEntry.ReadFrom((ReadOnlySpan<byte>)entryBuf);
// Tamper: vertices count -> -1 (ObjectId u64 + IsSetup byte = offset 9).
fs.Position = (long)entry.Offset + 9;
Span<byte> negOne = stackalloc byte[4];
System.Buffers.Binary.BinaryPrimitives.WriteInt32LittleEndian(negOne, -1);
fs.Write(negOne);
// Recompute CRC over the tampered blob region.
fs.Position = (long)entry.Offset;
var blobBytes = new byte[entry.Length];
fs.ReadExactly(blobBytes);
uint newCrc = Crc32.Compute(blobBytes);
// Patch the TOC entry's crc32 field (entry offset +20).
fs.Position = entryPos + 20;
Span<byte> crcBuf = stackalloc byte[4];
System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(crcBuf, newCrc);
fs.Write(crcBuf);
}
using var reader = new PakReader(path);
Assert.False(reader.TryReadObjectMeshData(victimKey, out var data),
"a structurally-malformed blob behind a matching CRC must be treated as missing");
Assert.Null(data);
// Second read: still missing, no throw (verdict cached).
Assert.False(reader.TryReadObjectMeshData(victimKey, out _));
for (int i = 1; i < blobs.Length; i++) {
var key = PakKey.Compose(blobs[i].Type, blobs[i].FileId);
Assert.True(reader.TryReadObjectMeshData(key, out var sibling), $"sibling blob {i} should be unaffected");
ObjectMeshDataEquality.AssertEqual(blobs[i].Data, sibling);
}
}
// ---- writer disposal safety (review finding 5) ---------------------------
[Fact]
public void WriterDisposedAfterAddBlobException_ReleasesFileHandle() {
var path = NewTempPakPath();
var data = MakeSyntheticData(1, 1);
var key = PakKey.Compose(PakAssetType.GfxObjMesh, 1);
var writer = new PakWriter(path, new PakHeader { BakeToolVersion = 1 });
writer.AddBlob(key, data);
Assert.Throws<ArgumentException>(() => writer.AddBlob(key, data)); // duplicate key mid-AddBlob
writer.Dispose();
// The stream must be closed even after the AddBlob exception: the
// file is deletable (no leaked/locked handle).
File.Delete(path);
Assert.False(File.Exists(path));
}
// ---- on-disk TOC sortedness (review finding 8) ---------------------------
[Fact]
public void OnDiskToc_IsSortedAscendingByKey_RegardlessOfAddOrder() {
var path = NewTempPakPath();
// Add blobs in DESCENDING key order — the on-disk TOC must still come
// out ascending (the reader's binary-search precondition, asserted
// here against the raw bytes, not through the reader).
var blobs = MakeBlobSet(12).OrderByDescending(b => PakKey.Compose(b.Type, b.FileId)).ToArray();
WritePak(path, blobs);
var fileBytes = File.ReadAllBytes(path);
var header = PakHeader.ReadFrom((ReadOnlySpan<byte>)fileBytes);
Assert.Equal((uint)blobs.Length, header.TocCount);
ulong previousKey = 0;
for (uint i = 0; i < header.TocCount; i++) {
int pos = checked((int)((long)header.TocOffset + i * PakTocEntry.Size));
var entry = PakTocEntry.ReadFrom(fileBytes.AsSpan(pos, PakTocEntry.Size));
Assert.True(entry.Key > previousKey || i == 0,
$"TOC entry {i} key 0x{entry.Key:X16} is not strictly greater than its predecessor 0x{previousKey:X16}");
previousKey = entry.Key;
}
}
// ---- corruption logged once (review finding 8) ----------------------------
[Fact]
public void CorruptBlob_RepeatedReads_LogExactlyOnce() {
var path = NewTempPakPath();
var blobs = MakeBlobSet(2);
WritePak(path, blobs);
// Flip a byte in the first blob (plain CRC corruption).
using (var fs = new FileStream(path, FileMode.Open, FileAccess.ReadWrite)) {
fs.Position = PakHeader.Size + 4;
int b = fs.ReadByte();
fs.Position = PakHeader.Size + 4;
fs.WriteByte((byte)(b ^ 0xFF));
}
var victimKey = PakKey.Compose(blobs[0].Type, blobs[0].FileId);
var originalError = Console.Error;
var capture = new StringWriter();
try {
Console.SetError(capture);
using var reader = new PakReader(path);
// Hammer the corrupt entry through BOTH public paths, repeatedly.
Assert.False(reader.TryReadObjectMeshData(victimKey, out _));
Assert.False(reader.TryReadObjectMeshData(victimKey, out _));
Assert.False(reader.ContainsKey(victimKey));
Assert.False(reader.ContainsKey(victimKey));
Assert.False(reader.TryReadObjectMeshData(victimKey, out _));
}
finally {
Console.SetError(originalError);
}
string logged = capture.ToString();
int occurrences = CountOccurrences(logged, $"0x{victimKey:X16}");
Assert.True(occurrences == 1,
$"expected exactly ONE [pak-corrupt] line for key 0x{victimKey:X16} across 5 reads, got {occurrences}:\n{logged}");
}
private static int CountOccurrences(string haystack, string needle) {
int count = 0, index = 0;
while ((index = haystack.IndexOf(needle, index, StringComparison.Ordinal)) >= 0) {
count++;
index += needle.Length;
}
return count;
}
// ---- helpers -------------------------------------------------------------
/// <summary>Locates the on-disk file position of the TOC entry for <paramref name="key"/> by raw parsing.</summary>
private static long FindTocEntryPosition(string path, ulong key) {
using var fs = new FileStream(path, FileMode.Open, FileAccess.Read);
var headerBuf = new byte[PakHeader.Size];
fs.ReadExactly(headerBuf);
var header = PakHeader.ReadFrom((ReadOnlySpan<byte>)headerBuf);
var entryBuf = new byte[PakTocEntry.Size];
for (uint i = 0; i < header.TocCount; i++) {
long pos = (long)header.TocOffset + i * PakTocEntry.Size;
fs.Position = pos;
fs.ReadExactly(entryBuf);
var entry = PakTocEntry.ReadFrom((ReadOnlySpan<byte>)entryBuf);
if (entry.Key == key) return pos;
}
throw new InvalidOperationException($"TOC entry for key 0x{key:X16} not found");
}
}

63
tests/AcDream.Core.Net.Tests/Messages/AutonomousPositionTests.cs
View file

@ -122,6 +122,69 @@ public class AutonomousPositionTests
Assert.Equal(0, body[52]);
}
[Fact]
public void Build_TimestampOrder_MatchesAutonomousPositionPackPack()
{
// AutonomousPositionPack::Pack (0x00516af0, confirmed via Ghidra
// decompile-by-address during this slice 2026-06-30): after
// Position::Pack (32 bytes), four u16 timestamps in order
// instance_timestamp, server_control_timestamp, teleport_timestamp,
// force_position_ts — then a CONTACT-ONLY byte (no longjump bit;
// that bit only exists in MoveToStatePack), then ALIGN_PTR.
var body = AutonomousPosition.Build(
gameActionSequence: 8,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0x1111,
serverControlSequence: 0x2222,
teleportSequence: 0x3333,
forcePositionSequence: 0x4444);
// 12 (envelope) + 32 (Position) = 44.
int tsOffset = 44;
ushort instance = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset));
ushort serverControl = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 2));
ushort teleport = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 4));
ushort forcePosition = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 6));
Assert.Equal((ushort)0x1111, instance);
Assert.Equal((ushort)0x2222, serverControl);
Assert.Equal((ushort)0x3333, teleport);
Assert.Equal((ushort)0x4444, forcePosition);
}
[Fact]
public void Build_ContactByte_IsContactOnly_NoLongjumpBit()
{
// contact != 0 -> byte = 1 (bool cast, not an OR'd bitmask like MTS).
var bodyOnGround = AutonomousPosition.Build(
gameActionSequence: 9,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
lastContact: 1);
Assert.Equal(1, bodyOnGround[52]);
var bodyAirborne = AutonomousPosition.Build(
gameActionSequence: 10,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
lastContact: 0);
Assert.Equal(0, bodyAirborne[52]);
}
[Fact]
public void Build_ContainsIdentityRotation_AfterPosition()
{

23
tests/AcDream.Core.Net.Tests/Messages/CreateObjectTests.cs
View file

@ -440,6 +440,21 @@ public sealed class CreateObjectTests
Assert.Equal(7.5f, p.Workmanship);
}
[Fact]
public void TryParse_MovementSequence_SurfacedFromTimestampBlock()
{
// L.2g S1 (DEV-6): index 1 of the 9-u16 PhysicsDesc timestamp block
// is ObjectMovement (ACE WorldObject_Networking.cs:412) — it seeds
// MotionSequenceGate's MOVEMENT_TS so post-spawn UpdateMotion events
// are judged against the entity's live sequence, not zero.
byte[] body = BuildMinimalCreateObjectWithWeenieHeader(
guid: 0x50000030u, name: "Runner", itemType: 0x10u,
movementSeq: 0x9000);
var parsed = CreateObject.TryParse(body);
Assert.NotNull(parsed);
Assert.Equal((ushort)0x9000, parsed!.Value.MovementSequence);
}
[Fact]
public void TryParse_MidTailFieldsSet_StillReachesIconOverlay()
{
@ -484,7 +499,8 @@ public sealed class CreateObjectTests
uint? validLocations = null,
uint? currentWieldedLocation = null,
uint? priority = null,
float? workmanship = null)
float? workmanship = null,
ushort movementSeq = 0)
{
var bytes = new List<byte>();
WriteU32(bytes, CreateObject.Opcode);
@ -496,11 +512,12 @@ public sealed class CreateObjectTests
bytes.Add(0);
bytes.Add(0);
// PhysicsData: physics flags = 0, then PhysicsState u32, then 9 seq stamps.
// PhysicsData: physics flags = 0, then PhysicsState u32, then 9 seq stamps
// (PhysicsTimeStamp enum order; index 1 = ObjectMovement).
WriteU32(bytes, 0);
WriteU32(bytes, physicsState);
for (int i = 0; i < 9; i++)
WriteU16(bytes, 0);
WriteU16(bytes, i == 1 ? movementSeq : (ushort)0);
Align4(bytes);
// Fixed WeenieHeader prefix per ACE SerializeCreateObject.

170
tests/AcDream.Core.Net.Tests/Messages/JumpActionTests.cs Normal file
View file

@ -0,0 +1,170 @@
using System;
using System.Buffers.Binary;
using System.Numerics;
using AcDream.Core.Net.Messages;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
/// <summary>
/// Golden-byte tests for the retail-faithful <see cref="JumpAction.Build"/>
/// layout, porting <c>JumpPack::Pack</c> (0x00516d10, decomp lines
/// ~284934-284963). Confirmed verbatim against the Ghidra decompile-by-address
/// bridge (http://127.0.0.1:8081/decompile_function?address=0x00516d10)
/// during this slice (2026-06-30):
///
/// <code>
/// extent (f32), velocity.x/y/z (f32 x3), Position::Pack (cellId + Frame),
/// instance_timestamp (u16), server_control_timestamp (u16),
/// teleport_timestamp (u16), force_position_ts (u16), ALIGN_PTR.
/// </code>
///
/// D4: retail does NOT pack an objectGuid or spellId. The pre-slice acdream
/// code wrote two spurious trailing <c>u32 0</c> fields and omitted Position
/// entirely — both are fixed here.
/// </summary>
public class JumpActionTests
{
[Fact]
public void Build_ProducesValidGameAction()
{
var body = JumpAction.Build(
gameActionSequence: 9,
extent: 0.5f,
velocity: new Vector3(1f, 2f, 3f),
cellId: 0xA9B40001u,
position: new Vector3(96f, 96f, 50f),
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
uint opcode = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0xF7B1u, opcode);
uint seq = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(4));
Assert.Equal(9u, seq);
uint actionType = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(8));
Assert.Equal(0xF61Bu, actionType);
}
[Fact]
public void Build_ExtentAndVelocity_FollowEnvelope()
{
var body = JumpAction.Build(
gameActionSequence: 1,
extent: 0.75f,
velocity: new Vector3(1.5f, -2.5f, 9.81f),
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
// 12-byte envelope, then extent(4), vx(4), vy(4), vz(4).
float extent = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(12));
float vx = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(16));
float vy = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(20));
float vz = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(24));
Assert.Equal(0.75f, extent);
Assert.Equal(1.5f, vx);
Assert.Equal(-2.5f, vy);
Assert.Equal(9.81f, vz);
}
[Fact]
public void Build_PositionFollowsVelocity_CellIdThenOriginThenQuaternion()
{
var body = JumpAction.Build(
gameActionSequence: 2,
extent: 0f,
velocity: Vector3.Zero,
cellId: 0xDEADBEEFu,
position: new Vector3(12.5f, 34.0f, 56.75f),
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
// 12 (envelope) + 4 (extent) + 12 (velocity) = offset 28 -> Position::Pack.
int positionOffset = 28;
uint cellId = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(positionOffset));
float x = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 4));
float y = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 8));
float z = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 12));
float qw = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 16));
float qx = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 20));
float qy = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 24));
float qz = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(positionOffset + 28));
Assert.Equal(0xDEADBEEFu, cellId);
Assert.Equal(12.5f, x);
Assert.Equal(34.0f, y);
Assert.Equal(56.75f, z);
Assert.Equal(1.0f, qw);
Assert.Equal(0.0f, qx);
Assert.Equal(0.0f, qy);
Assert.Equal(0.0f, qz);
}
[Fact]
public void Build_TimestampsFollowPosition_InRetailOrder()
{
var body = JumpAction.Build(
gameActionSequence: 3,
extent: 0f,
velocity: Vector3.Zero,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0x1111,
serverControlSequence: 0x2222,
teleportSequence: 0x3333,
forcePositionSequence: 0x4444);
// Position::Pack is 32 bytes (cellId + Frame). Timestamps start at
// 28 (extent/velocity/envelope) + 32 = 60.
int tsOffset = 60;
ushort instance = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset));
ushort serverControl = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 2));
ushort teleport = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 4));
ushort forcePosition = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 6));
Assert.Equal((ushort)0x1111, instance);
Assert.Equal((ushort)0x2222, serverControl);
Assert.Equal((ushort)0x3333, teleport);
Assert.Equal((ushort)0x4444, forcePosition);
}
[Fact]
public void Build_NoObjectGuidOrSpellId_JumpPackBodyLengthIs56()
{
// JumpPack::Pack body (everything AFTER the 12-byte GameAction
// envelope): extent(4) + velocity(12) + Position(32) +
// 4x u16 timestamps(8) = 56 bytes, already a multiple of 4 -> no
// align padding. Total wire length = 12 (envelope) + 56 = 68.
// Retail's JumpPack has NO objectGuid/spellId fields (D4) — the
// pre-slice code's two spurious trailing u32 writes are gone.
var body = JumpAction.Build(
gameActionSequence: 4,
extent: 0f,
velocity: Vector3.Zero,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
Assert.Equal(56, body.Length - 12);
Assert.Equal(68, body.Length);
Assert.Equal(0, body.Length % 4);
}
}

254
tests/AcDream.Core.Net.Tests/Messages/MoveToStateGoldenTests.cs Normal file
View file

@ -0,0 +1,254 @@
using System;
using System.Buffers.Binary;
using System.Numerics;
using AcDream.Core.Net.Messages;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
/// <summary>
/// Full-message golden-byte tests for the refactored <see cref="MoveToState.Build"/>
/// (D1 default-difference RawMotionState packing + D3 trailing byte), porting
/// <c>MoveToStatePack::Pack</c> (0x005168f0, decomp lines ~284694-284722).
/// Confirmed verbatim against the Ghidra decompile-by-address bridge during
/// this slice (2026-06-30):
///
/// <code>
/// MoveToStatePack::Pack:
/// RawMotionState::Pack(...)
/// Position::Pack(...)
/// instance_timestamp(u16), server_control_timestamp(u16),
/// teleport_timestamp(u16), force_position_ts(u16)
/// trailing byte = ((longjump_mode != 0) ? 0x02 : 0) | (contact != 0 ? 0x01 : 0)
/// ALIGN_PTR
/// </code>
/// </summary>
public class MoveToStateGoldenTests
{
private static readonly Vector3 Pos = new(96f, 96f, 50f);
private static readonly Quaternion Rot = Quaternion.Identity;
[Fact]
public void Build_DefaultRawMotionState_FlagsAreZero_EnvelopePlusPositionPlusTimestampsPlusTrailingByte()
{
var body = MoveToState.Build(
gameActionSequence: 1,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
// 12 (envelope) + 4 (flags=0, no fields) + 32 (Position) + 8 (timestamps)
// + 1 (trailing byte) = 57, aligned to 60.
Assert.Equal(60, body.Length);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.Equal(0u, flags);
uint cellId = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(16));
Assert.Equal(0xA9B40001u, cellId);
// trailing byte at 12+4+32+8 = 56: contact=true, longjump=false -> 0x01
Assert.Equal(0x01, body[56]);
}
[Fact]
public void Build_WalkForward_OmitsForwardSpeedDefault()
{
// Walk-forward at default speed 1.0 -> forward_speed bit OMITTED (D1 fix).
var state = new RawMotionState
{
CurrentHoldKey = HoldKey.None, // default, omitted
ForwardCommand = 0x45000005u, // WalkForward
ForwardHoldKey = HoldKey.None, // differs from Invalid -> set
ForwardSpeed = 1.0f, // default, omitted
};
var body = MoveToState.Build(
gameActionSequence: 2,
rawMotionState: state,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.Equal(0x0000000Cu, flags); // ForwardCommand | ForwardHoldKey only
// RawMotionState body = flags(4) + fwd_cmd(4) + fwd_holdkey(4) = 12.
uint cellId = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12 + 12));
Assert.Equal(0xA9B40001u, cellId);
}
[Fact]
public void Build_RunForward_IncludesHoldKeyAndSpeed()
{
var state = new RawMotionState
{
CurrentHoldKey = HoldKey.Run,
ForwardCommand = 0x44000007u, // RunForward
ForwardHoldKey = HoldKey.Run,
ForwardSpeed = 2.94f,
};
var body = MoveToState.Build(
gameActionSequence: 3,
rawMotionState: state,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.Equal(0x0000001Du, flags); // holdkey | fwd_cmd | fwd_holdkey | fwd_speed
// RawMotionState body = flags(4) + holdkey(4) + fwd_cmd(4) + fwd_holdkey(4) + fwd_speed(4) = 20.
uint cellId = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12 + 20));
Assert.Equal(0xA9B40001u, cellId);
}
[Fact]
public void Build_Sidestep_SetsSidestepBitsOnly()
{
var state = new RawMotionState
{
SidestepCommand = 0x6500000Fu, // SideStepRight
SidestepHoldKey = HoldKey.None,
SidestepSpeed = 1.0f, // default -> omitted
};
var body = MoveToState.Build(
gameActionSequence: 4,
rawMotionState: state,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.Equal(0x00000060u, flags); // SidestepCommand(0x20) | SidestepHoldKey(0x40)
}
[Fact]
public void Build_Turn_SetsTurnBitsOnly()
{
var state = new RawMotionState
{
TurnCommand = 0x6500000Du, // TurnRight
TurnHoldKey = HoldKey.None,
TurnSpeed = 1.0f, // default -> omitted
};
var body = MoveToState.Build(
gameActionSequence: 5,
rawMotionState: state,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.Equal(0x00000300u, flags); // TurnCommand(0x100) | TurnHoldKey(0x200)
}
[Theory]
[InlineData(false, false, 0x00)]
[InlineData(true, false, 0x01)]
[InlineData(false, true, 0x02)]
[InlineData(true, true, 0x03)]
public void Build_TrailingByte_AllFourContactLongjumpCombinations(bool contact, bool standingLongjump, byte expected)
{
// MoveToStatePack::Pack trailing byte:
// ((longjump_mode != 0) ? 0x02 : 0) | (contact != 0 ? 0x01 : 0)
var body = MoveToState.Build(
gameActionSequence: 6,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: contact,
standingLongjump: standingLongjump);
// flags(4) + Position(32) + timestamps(8) = 44; trailing byte at 12+44=56.
Assert.Equal(expected, body[56]);
}
[Fact]
public void Build_TimestampOrder_MatchesMoveToStatePackPack()
{
var body = MoveToState.Build(
gameActionSequence: 7,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0x1111,
serverControlSequence: 0x2222,
teleportSequence: 0x3333,
forcePositionSequence: 0x4444,
contact: true,
standingLongjump: false);
// 12 (envelope) + 4 (flags) + 32 (Position) = 48.
int tsOffset = 48;
ushort instance = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset));
ushort serverControl = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 2));
ushort teleport = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 4));
ushort forcePosition = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(tsOffset + 6));
Assert.Equal((ushort)0x1111, instance);
Assert.Equal((ushort)0x2222, serverControl);
Assert.Equal((ushort)0x3333, teleport);
Assert.Equal((ushort)0x4444, forcePosition);
}
[Fact]
public void Build_IsAlignedTo4Bytes()
{
var body = MoveToState.Build(
gameActionSequence: 8,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Pos,
rotation: Rot,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contact: true,
standingLongjump: false);
Assert.Equal(0, body.Length % 4);
}
}

108
tests/AcDream.Core.Net.Tests/Messages/MoveToStateTests.cs
View file

@ -2,26 +2,36 @@ using System;
using System.Buffers.Binary;
using System.Numerics;
using AcDream.Core.Net.Messages;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
/// <summary>
/// Envelope + structural tests for <see cref="MoveToState.Build"/>. Golden
/// byte-layout tests for the RawMotionState default-difference packing (D1)
/// and the trailing contact/longjump byte (D3) live in
/// <see cref="MoveToStateGoldenTests"/> and <see cref="RawMotionStatePackTests"/>.
///
/// D1/D3 refactor (2026-06-30): <c>Build</c> now takes a
/// <see cref="RawMotionState"/> snapshot (matching retail's
/// <c>CPhysicsObj::InqRawMotionState()</c>) instead of flat nullable
/// per-axis params, plus explicit <c>contact</c>/<c>standingLongjump</c>
/// booleans for the trailing byte — see <c>MoveToStatePack::Pack</c>
/// (0x005168f0).
/// </summary>
public class MoveToStateTests
{
private static readonly Vector3 Pos = new(96f, 96f, 50f);
[Fact]
public void Build_IdleState_ProducesValidGameAction()
{
var body = MoveToState.Build(
gameActionSequence: 1,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: new Vector3(96f, 96f, 50f),
position: Pos,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
@ -42,31 +52,33 @@ public class MoveToStateTests
}
[Fact]
public void Build_WalkForward_IncludesForwardCommandInFlags()
public void Build_WalkForward_DefaultSpeedOmitted_OnlyCommandAndHoldKeyFlagsSet()
{
// D1 fix: forward_speed == 1.0 (the retail default) is OMITTED from
// the flags, unlike the pre-slice presence-based packer which always
// set the ForwardSpeed bit whenever a caller supplied a value.
var state = new RawMotionState
{
ForwardCommand = 0x45000005u, // WalkForward
ForwardHoldKey = HoldKey.None, // differs from Invalid -> set
ForwardSpeed = 1.0f, // default -> omitted
};
var body = MoveToState.Build(
gameActionSequence: 2,
forwardCommand: 0x45000005u, // WalkForward
forwardSpeed: 1.0f,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: state,
cellId: 0xA9B40001u,
position: new Vector3(96f, 96f, 50f),
position: Pos,
rotation: Quaternion.Identity,
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
// After the 12-byte GameAction header comes RawMotionState.
// First u32 is the packed flags word. ForwardCommand flag = 0x4.
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12));
Assert.True((flags & 0x4u) != 0, "ForwardCommand flag (0x4) should be set");
// ForwardSpeed flag = 0x10
Assert.True((flags & 0x10u) != 0, "ForwardSpeed flag (0x10) should be set");
Assert.True((flags & 0x8u) != 0, "ForwardHoldKey flag (0x8) should be set");
Assert.False((flags & 0x10u) != 0, "ForwardSpeed flag (0x10) must be OMITTED at the retail default 1.0");
}
[Fact]
@ -74,13 +86,7 @@ public class MoveToStateTests
{
var body = MoveToState.Build(
gameActionSequence: 3,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
@ -94,19 +100,14 @@ public class MoveToStateTests
}
[Fact]
public void Build_IdleState_WorldPositionFollowsMotionState()
public void Build_IdleState_WorldPositionFollowsZeroFlagMotionState()
{
// With no motion state, flags = 0 and no conditional fields are written.
// So WorldPosition starts at offset 12 (envelope) + 4 (flags) = 16.
// With the default raw motion state, flags = 0 and no conditional
// fields are written. So WorldPosition starts at offset 12
// (envelope) + 4 (flags) = 16.
var body = MoveToState.Build(
gameActionSequence: 4,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: RawMotionState.Default,
cellId: 0xDEADBEEFu,
position: Vector3.Zero,
rotation: Quaternion.Identity,
@ -124,13 +125,7 @@ public class MoveToStateTests
{
var body = MoveToState.Build(
gameActionSequence: 5,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
@ -143,17 +138,11 @@ public class MoveToStateTests
}
[Fact]
public void Build_UsesExplicitAirborneContactByte()
public void Build_UsesExplicitAirborneContact()
{
var body = MoveToState.Build(
gameActionSequence: 7,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: null,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,
@ -161,23 +150,20 @@ public class MoveToStateTests
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0,
contactLongJump: 0);
contact: false);
// flags(4) + Position(32) + timestamps(8) = 44; trailing byte at 12+44=56.
Assert.Equal(0, body[56]);
}
[Fact]
public void Build_WithHoldKey_IncludesHoldKeyFlag()
{
var state = new RawMotionState { CurrentHoldKey = HoldKey.Run };
var body = MoveToState.Build(
gameActionSequence: 6,
forwardCommand: null,
forwardSpeed: null,
sidestepCommand: null,
sidestepSpeed: null,
turnCommand: null,
turnSpeed: null,
holdKey: 2u, // Run
rawMotionState: state,
cellId: 0xA9B40001u,
position: Vector3.Zero,
rotation: Quaternion.Identity,

63
tests/AcDream.Core.Net.Tests/Messages/PositionPackTests.cs Normal file
View file

@ -0,0 +1,63 @@
using System.Buffers.Binary;
using System.Numerics;
using AcDream.Core.Net.Messages;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
/// <summary>
/// Pins the shared WorldPosition/Position block byte order used by
/// <see cref="MoveToState"/>, <see cref="AutonomousPosition"/>, and
/// <see cref="JumpAction"/>: <c>Position::Pack</c> (0x005a9640) wraps
/// <c>cellId(u32)</c> then <c>Frame::Pack</c> (0x00535130) =
/// <c>origin.x/y/z(f32)</c> then <c>qw/qx/qy/qz(f32)</c>. Confirmed verbatim
/// against the Ghidra decompile-by-address bridge during this slice
/// (2026-06-30):
///
/// <code>
/// Position::Pack: objcell_id(u32), Frame::Pack(...)
/// Frame::Pack: m_fOrigin.x/y/z(f32 x3), qw(f32), qx(f32), qy(f32), qz(f32)
/// </code>
///
/// 32 bytes total (4 + 12 + 16). This was already correct pre-slice — these
/// tests lock the byte order with a golden-value assertion rather than
/// changing behavior.
/// </summary>
public class PositionPackTests
{
[Fact]
public void MoveToState_PositionBlock_OrderIsCellIdThenOriginThenQuaternion()
{
var body = MoveToState.Build(
gameActionSequence: 1,
rawMotionState: RawMotionState.Default,
cellId: 0xA9B40001u,
position: new Vector3(1.5f, 2.5f, 3.5f),
rotation: new Quaternion(0.1f, 0.2f, 0.3f, 0.9f), // X,Y,Z,W ctor order
instanceSequence: 0,
serverControlSequence: 0,
teleportSequence: 0,
forcePositionSequence: 0);
// No motion state -> flags(4) only before the Position block at offset 16.
int off = 12 + 4;
uint cellId = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(off));
float x = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 4));
float y = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 8));
float z = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 12));
float qw = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 16));
float qx = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 20));
float qy = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 24));
float qz = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(off + 28));
Assert.Equal(0xA9B40001u, cellId);
Assert.Equal(1.5f, x);
Assert.Equal(2.5f, y);
Assert.Equal(3.5f, z);
Assert.Equal(0.9f, qw);
Assert.Equal(0.1f, qx);
Assert.Equal(0.2f, qy);
Assert.Equal(0.3f, qz);
}
}

212
tests/AcDream.Core.Net.Tests/Messages/RawMotionStatePackTests.cs Normal file
View file

@ -0,0 +1,212 @@
using System.Buffers.Binary;
using AcDream.Core.Net.Messages;
using AcDream.Core.Net.Packets;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
/// <summary>
/// Golden-byte tests for <see cref="RawMotionStatePacker.Pack"/>, porting
/// retail's <c>RawMotionState::Pack</c> (0x0051ed10, decomp lines
/// ~293761-294013; bitfield layout <c>acclient.h RawMotionState::PackBitfield</c>,
/// line 46474). Confirmed verbatim against the Ghidra decompile-by-address
/// bridge (http://127.0.0.1:8081/decompile_function?address=0x0051ed10)
/// during this slice (2026-06-30).
///
/// <para>
/// Retail compares every field against its DEFAULT and only sets the
/// matching bit (and emits the field) when the live value DIFFERS. This is
/// the D1 fix — the old presence-based packer over-sent defaulted fields.
/// </para>
/// </summary>
public class RawMotionStatePackTests
{
private static byte[] Pack(RawMotionState state)
{
var w = new PacketWriter(64);
RawMotionStatePacker.Pack(w, state);
return w.ToArray();
}
[Fact]
public void Pack_DefaultState_EmitsOnlyZeroFlags()
{
// Every field equals its retail default -> flags dword is 0,
// no conditional fields, no actions. 4 bytes total.
var body = Pack(RawMotionState.Default);
Assert.Equal(new byte[] { 0x00, 0x00, 0x00, 0x00 }, body);
}
[Fact]
public void Pack_ShiftWalk_OmitsForwardSpeedAndCurrentHoldKey()
{
// Shift-walk: current_holdkey stays None (default omitted),
// forward_command = WalkForward (0x45000005), forward_holdkey =
// None (1) -- DIFFERS from default Invalid(0) so IS sent --
// forward_speed stays 1.0 (default, omitted). Rest default.
//
// Flags expected: ForwardCommand(0x004) | ForwardHoldKey(0x008) = 0x00C.
// Body: flags(u32) + forward_command(u32) + forward_holdkey(u32).
var state = new RawMotionState
{
CurrentHoldKey = HoldKey.None, // default -> omitted
ForwardCommand = 0x45000005u, // WalkForward -> differs -> set
ForwardHoldKey = HoldKey.None, // differs from Invalid -> set
ForwardSpeed = 1.0f, // default -> omitted (the D1 fix)
};
var body = Pack(state);
Assert.Equal(12, body.Length);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0x0000000Cu, flags);
uint fwdCommand = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(4));
Assert.Equal(0x45000005u, fwdCommand);
uint fwdHoldKey = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(8));
Assert.Equal(1u, fwdHoldKey); // HoldKey.None
byte[] expected =
{
0x0C, 0x00, 0x00, 0x00,
0x05, 0x00, 0x00, 0x45,
0x01, 0x00, 0x00, 0x00,
};
Assert.Equal(expected, body);
}
[Fact]
public void Pack_RunForward_SetsHoldKeyForwardCommandHoldKeyAndSpeed()
{
// Run-forward: current_holdkey = Run(2) (differs from None -> set),
// forward_command = RunForward-ish 0x44000007 (differs -> set),
// forward_holdkey = Run(2) (differs from Invalid -> set),
// forward_speed = 3.0 (differs from 1.0 -> set).
//
// Flags expected: CurrentHoldKey(0x001) | ForwardCommand(0x004) |
// ForwardHoldKey(0x008) | ForwardSpeed(0x010) = 0x01D.
var state = new RawMotionState
{
CurrentHoldKey = HoldKey.Run,
ForwardCommand = 0x44000007u,
ForwardHoldKey = HoldKey.Run,
ForwardSpeed = 3.0f,
};
var body = Pack(state);
Assert.Equal(20, body.Length);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0x0000001Du, flags);
byte[] expected =
{
0x1D, 0x00, 0x00, 0x00, // flags
0x02, 0x00, 0x00, 0x00, // current_holdkey = Run(2)
0x07, 0x00, 0x00, 0x44, // forward_command = 0x44000007
0x02, 0x00, 0x00, 0x00, // forward_holdkey = Run(2)
0x00, 0x00, 0x40, 0x40, // forward_speed = 3.0f (0x40400000 LE)
};
Assert.Equal(expected, body);
}
[Fact]
public void Pack_NonDefaultCurrentStyle_SetsStyleBitAndEmitsValue()
{
// current_style differs from 0x8000003D -> bit 0x002 set, value emitted
// immediately after the flags dword (bit order: holdkey, style, ...).
var state = new RawMotionState
{
CurrentStyle = 0x80000042u,
};
var body = Pack(state);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0x002u, flags);
uint style = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(4));
Assert.Equal(0x80000042u, style);
Assert.Equal(8, body.Length);
}
[Fact]
public void Pack_PopulatedActionsList_SetsNumActionsBitsAndEmitsPairs()
{
// num_actions occupies bits 11-15 (mask 0xF800) of the flags dword.
// Two actions -> num_actions = 2 -> bits = 2 << 11 = 0x1000.
// Each action emits u16 command then u16 (stamp & 0x7FFF) |
// (autonomous ? 0x8000 : 0) (decomp ~293998-294010).
var state = new RawMotionState
{
Actions = new[]
{
new RawMotionAction(Command: 0x0150, Stamp: 0x0001, Autonomous: false),
new RawMotionAction(Command: 0x0163, Stamp: 0x7FFF, Autonomous: true),
},
};
var body = Pack(state);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0x1000u, flags); // num_actions=2 << 11, no continuous-axis bits
// Body: flags(4) + action0(4) + action1(4) = 12 bytes.
Assert.Equal(12, body.Length);
ushort cmd0 = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(4));
ushort stamp0 = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(6));
Assert.Equal((ushort)0x0150, cmd0);
Assert.Equal((ushort)0x0001, stamp0); // autonomous=false -> 0x8000 bit clear
ushort cmd1 = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(8));
ushort stamp1 = BinaryPrimitives.ReadUInt16LittleEndian(body.AsSpan(10));
Assert.Equal((ushort)0x0163, cmd1);
Assert.Equal((ushort)0xFFFF, stamp1); // (0x7FFF & 0x7FFF) | 0x8000 = 0xFFFF
}
[Fact]
public void Pack_SidestepAndTurnNonDefault_SetExpectedBitsInOrder()
{
// sidestep_command(0x020), sidestep_holdkey(0x040), sidestep_speed(0x080),
// turn_command(0x100), turn_holdkey(0x200), turn_speed(0x400) all non-default.
var state = new RawMotionState
{
SidestepCommand = 0x44000009u,
SidestepHoldKey = HoldKey.Run,
SidestepSpeed = 1.248f,
TurnCommand = 0x4400000Du,
TurnHoldKey = HoldKey.Run,
TurnSpeed = 1.5f,
};
var body = Pack(state);
uint flags = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0));
Assert.Equal(0x000007E0u, flags); // 0x20|0x40|0x80|0x100|0x200|0x400
// Body order after flags: sidestep_command, sidestep_holdkey,
// sidestep_speed, turn_command, turn_holdkey, turn_speed.
uint ssCmd = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(4));
uint ssHold = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(8));
float ssSpeed = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(12));
uint turnCmd = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(16));
uint turnHold = BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(20));
float turnSpeed = BinaryPrimitives.ReadSingleLittleEndian(body.AsSpan(24));
Assert.Equal(0x44000009u, ssCmd);
Assert.Equal(2u, ssHold);
Assert.Equal(1.248f, ssSpeed);
Assert.Equal(0x4400000Du, turnCmd);
Assert.Equal(2u, turnHold);
Assert.Equal(1.5f, turnSpeed);
Assert.Equal(28, body.Length);
}
}

364
tests/AcDream.Core.Net.Tests/Messages/UpdateMotionTests.cs
View file

@ -1,6 +1,7 @@
using System;
using System.Buffers.Binary;
using AcDream.Core.Net.Messages;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
@ -303,6 +304,37 @@ public class UpdateMotionTests
Assert.Equal(1.25f, result.Value.MotionState.ForwardSpeed);
}
[Fact]
public void ParsesSequenceNumbersAndAutonomyFlag()
{
// L.2g S1 (DEV-6): the three staleness stamps + autonomy flag must
// survive parsing — retail gates every 0xF74C on them
// (INSTANCE_TS at dispatch, MOVEMENT_TS + SERVER_CONTROLLED_MOVE_TS
// in CPhysics::SetObjectMovement 0x00509690, which also stores
// last_move_was_autonomous).
var body = new byte[4 + 4 + 2 + 6 + 4 + 4];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x50001234u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x0102); p += 2; // instanceSeq
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x0304); p += 2; // movementSeq
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x0506); p += 2; // serverControlSeq
body[p++] = 1; // isAutonomous
p += 1; // Align(4) pad
body[p++] = 0; // movementType = Invalid
body[p++] = 0; // motionFlags
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2; // outer stance
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0u); p += 4; // no IMS flags
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal((ushort)0x0102, result!.Value.InstanceSequence);
Assert.Equal((ushort)0x0304, result.Value.MovementSequence);
Assert.Equal((ushort)0x0506, result.Value.ServerControlSequence);
Assert.True(result.Value.IsAutonomous);
}
[Fact]
public void ParsesMoveToObjectTargetGuidAndOrigin()
{
@ -351,4 +383,336 @@ public class UpdateMotionTests
Assert.Equal(7f, path.OriginZ);
Assert.Equal(1.25f, result.Value.MotionState.MoveToRunRate);
}
// ─────────────────────────────────────────────────────────────────
// R4-V3 (closes M7): mt 8 (TurnToObject) / mt 9 (TurnToHeading).
//
// Golden bytes assembled from ACE's own writers (V0-pins.md P6):
// MovementDataExtensions.Write (references/ACE/Source/ACE.Server/
// Network/Motion/MovementData.cs:184-229) writes the common header
// (movementType u8, motionFlags u8, currentStyle u16) then dispatches
// on MovementType to:
// TurnToObjectExtensions.Write (TurnToObject.cs:25-30):
// writer.WriteGuid(Target); // u32
// writer.Write(DesiredHeading); // f32 — the STANDALONE
// // "wire_heading" field
// writer.Write(TurnToParameters); // 3-dword UnPackNet form
// TurnToParametersExtensions.Write (TurnToParameters.cs:23-28):
// writer.Write((uint)MovementParams); // u32 bitfield
// writer.Write(Speed); // f32
// writer.Write(DesiredHeading); // f32 — TurnToParameters'
// // OWN desired_heading
// TurnToHeadingExtensions.Write (TurnToHeading.cs:18-21):
// writer.Write(TurnToParameters); // 3-dword UnPackNet form only
//
// P6's fixture caveat: ACE always populates field2 (TurnToObject.
// DesiredHeading) and field5 (TurnToParameters.DesiredHeading) from the
// SAME motion.DesiredHeading source, so a byte-faithful ACE capture
// would have field2 == field5. To prove the parser distinguishes the
// two fields by OFFSET (not by coincidentally-equal value), these
// fixtures hand-vary the two headings.
// ─────────────────────────────────────────────────────────────────
[Fact]
public void ParsesTurnToObject_GuidWireHeadingAndParams()
{
// Header (20 bytes) + guid (4) + wireHeading (4) + TurnToParameters (12) = 40.
var body = new byte[20 + 4 + 4 + 12];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80005678u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6; // MovementData header padding
body[p++] = 8; // TurnToObject
body[p++] = 0; // motionFlags
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80009999u); p += 4; // target guid
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 42.0f); p += 4; // standalone wire_heading (field2)
const uint flags = 0x1u | 0x2u | 0x200u; // can_walk | can_run | move_towards
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), flags); p += 4; // TurnToParameters.bitfield
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 1.5f); p += 4; // TurnToParameters.speed
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 199.0f); p += 4; // TurnToParameters.desired_heading (field5) — DELIBERATELY != field2
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal((byte)8, result!.Value.MotionState.MovementType);
Assert.True(result.Value.MotionState.IsServerControlledTurnTo);
Assert.False(result.Value.MotionState.IsServerControlledMoveTo);
Assert.NotNull(result.Value.MotionState.TurnToPath);
var path = result.Value.MotionState.TurnToPath!.Value;
Assert.Equal(0x80009999u, path.TargetGuid);
Assert.Equal(42.0f, path.WireHeading); // field2 — distinguished by OFFSET
Assert.Equal(flags, path.Bitfield);
Assert.Equal(1.5f, path.Speed);
Assert.Equal(199.0f, path.DesiredHeading); // field5 — distinct from field2
// The consumer feeds this straight into FromWireTurnTo (App-layer,
// out of scope here) — verify the fixture is round-trippable.
var mp = MovementParameters.FromWireTurnTo(path.Bitfield, path.Speed, path.DesiredHeading);
Assert.True(mp.CanRun);
Assert.Equal(1.5f, mp.Speed);
Assert.Equal(199.0f, mp.DesiredHeading);
}
[Fact]
public void ParsesTurnToObject_UnresolvableFallback_BothHeadingsSurvivedDistinctly()
{
// Retail's degrade-to-TurnToHeading fallback (decomp §2f case 8) only
// fires when GetObjectA(object_id) == 0 — a runtime/consumer-side
// resolution the wire parser has no visibility into. The parser's
// job is just to expose BOTH heading fields so the (future) V4/V5
// consumer can implement: "if unresolvable, params.DesiredHeading =
// wireHeading, then degrade to TurnToHeading". Confirm both survive
// even when they'd trigger the fallback (i.e. even when they differ).
var body = new byte[20 + 4 + 4 + 12];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x8000AAAAu); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 8;
body[p++] = 0;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xDEADBEEFu); p += 4; // unresolvable guid
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 270.0f); p += 4; // wire_heading — the fallback source
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x1u); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 1.0f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 0.0f); p += 4; // params.desired_heading (would be overwritten by wire_heading on fallback)
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
var path = result!.Value.MotionState.TurnToPath!.Value;
Assert.Equal(0xDEADBEEFu, path.TargetGuid);
Assert.Equal(270.0f, path.WireHeading);
Assert.Equal(0.0f, path.DesiredHeading);
Assert.NotEqual(path.WireHeading, path.DesiredHeading);
}
[Fact]
public void ParsesTurnToHeading_ThreeDwordFormOnly_NoGuidOrWireHeading()
{
// Header (20 bytes) + TurnToParameters (12) = 32. No guid, no
// standalone heading field — TurnToHeadingExtensions.Write emits
// ONLY the 3-dword UnPackNet form (TurnToHeading.cs:18-21).
var body = new byte[20 + 12];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x8000BBBBu); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 9; // TurnToHeading
body[p++] = 0;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2;
const uint flags = 0x2u | 0x800u; // can_run | set_hold_key
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), flags); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 2.0f); p += 4; // speed
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 315.0f); p += 4; // desired_heading
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal((byte)9, result!.Value.MotionState.MovementType);
Assert.True(result.Value.MotionState.IsServerControlledTurnTo);
Assert.NotNull(result.Value.MotionState.TurnToPath);
var path = result.Value.MotionState.TurnToPath!.Value;
Assert.Null(path.TargetGuid);
Assert.Null(path.WireHeading);
Assert.Equal(flags, path.Bitfield);
Assert.Equal(2.0f, path.Speed);
Assert.Equal(315.0f, path.DesiredHeading);
}
[Theory]
[InlineData(0u)] // no flags
[InlineData(0x1u | 0x2u)] // can_walk | can_run
[InlineData(0x10u)] // can_charge (fast-path bit)
[InlineData(0x3FFFFu)] // every A4 bit through 0x20000
public void ParsesTurnToHeading_FlagPermutations_BitfieldRoundTrips(uint bitfield)
{
var body = new byte[20 + 12];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80001111u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 9;
body[p++] = 0;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), bitfield); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 1.0f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 0.0f); p += 4;
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal(bitfield, result!.Value.MotionState.TurnToPath!.Value.Bitfield);
}
// ─────────────────────────────────────────────────────────────────
// R4-V3 deliverable B: mt 6/7 widened exposure. MoveToPathData already
// carries every UnPackNet field (V0/V1 shipped that); this proves the
// fixture round-trips end-to-end through MovementParameters.FromWire —
// i.e. that ALL seven UnPackNet fields (not just the three ad-hoc bool
// properties MoveToCanRun/MoveTowards/CanCharge) reach a consumer.
// ─────────────────────────────────────────────────────────────────
[Fact]
public void MoveToPositionPath_FeedsFromWire_AllSevenFieldsSurvive()
{
var body = new byte[20 + 16 + 28 + 4];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80002222u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 7; // MoveToPosition
body[p++] = 0;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xA8B4000Eu); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 11f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 22f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 33f); p += 4;
const uint flags = 0x1u | 0x2u | 0x4u | 0x8u | 0x10u | 0x200u | 0x400u; // incl. can_charge + use_spheres
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), flags); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 0.6f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 0.1f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 50.0f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 1.25f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 15.0f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 123.0f); p += 4;
BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(p), 2.75f); p += 4; // runRate
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
var path = result!.Value.MotionState.MoveToPath!.Value;
var mp = MovementParameters.FromWire(
flags,
path.DistanceToObject,
path.MinDistance,
path.FailDistance,
result.Value.MotionState.MoveToSpeed!.Value,
path.WalkRunThreshold,
path.DesiredHeading);
Assert.True(mp.CanWalk);
Assert.True(mp.CanRun);
Assert.True(mp.CanSidestep);
Assert.True(mp.CanWalkBackwards);
Assert.True(mp.CanCharge);
Assert.True(mp.MoveTowards);
Assert.True(mp.UseSpheres);
Assert.Equal(0.6f, mp.DistanceToObject);
Assert.Equal(0.1f, mp.MinDistance);
Assert.Equal(50.0f, mp.FailDistance);
Assert.Equal(1.25f, mp.Speed);
Assert.Equal(15.0f, mp.WalkRunThreshhold);
Assert.Equal(123.0f, mp.DesiredHeading);
Assert.Equal(2.75f, result.Value.MotionState.MoveToRunRate);
}
// ─────────────────────────────────────────────────────────────────
// R4-V3 deliverable C: the 0xF74C motionFlags sticky-guid trailer
// (mt=0/Invalid only — ACE MovementInvalid.Write gates the trailing
// guid on MotionFlags.StickToObject 0x1; decomp §2f case 0
// @0052455d). Cursor-honesty test: bytes AFTER the trailer must still
// parse correctly (i.e. the trailer's 4 bytes were actually consumed,
// not left dangling / double-read).
// ─────────────────────────────────────────────────────────────────
[Fact]
public void ParsesStickyGuidTrailer_WhenMotionFlagsBitSet()
{
// motionFlags byte1&0x1 (StickToObject) set; InterpretedMotionState
// flags = 0 (no fields), so the sticky guid dword immediately
// follows the packed flags dword.
var body = new byte[4 + 4 + 2 + 6 + 4 + 4 + 4];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80003333u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 0; // movementType = Invalid
body[p++] = 0x1; // motionFlags = StickToObject
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0u); p += 4; // no IMS flags
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80004444u); p += 4; // sticky object guid
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal(0x80004444u, result!.Value.MotionState.StickyObjectGuid);
}
[Fact]
public void SkipsStickyGuidTrailer_WhenMotionFlagsBitClear()
{
var body = new byte[4 + 4 + 2 + 6 + 4 + 4];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80005555u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 0; // movementType = Invalid
body[p++] = 0; // motionFlags = none
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x003D); p += 2;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0u); p += 4; // no IMS flags
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Null(result!.Value.MotionState.StickyObjectGuid);
}
[Fact]
public void ParsesStickyGuidTrailer_CursorHonesty_BytesAfterTrailerStillParseCorrectly()
{
// Sticky trailer with the ForwardCommand flag ALSO set, so there are
// bytes both BEFORE (forwardCommand u16) and the sticky dword AFTER
// the flags dword — the trailer must be read at the right offset
// (after ForwardCommand + its own 2-byte read), not glued onto the
// packed-flags dword itself. Cross-checks against ACE's actual field
// order: MovementInvalid.Write emits `State` (the whole
// InterpretedMotionState, incl. Commands list) THEN the sticky guid
// — decomp confirms the same order (UnPack first, sticky guid read
// after, r4-moveto-decomp.md:274-275).
var body = new byte[4 + 4 + 2 + 6 + 4 + 4 + 2 + 4];
int p = 0;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0xF74Cu); p += 4;
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80006666u); p += 4;
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2;
p += 6;
body[p++] = 0; // movementType = Invalid
body[p++] = 0x1; // motionFlags = StickToObject
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0); p += 2; // outer stance
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x2u); p += 4; // IMS flags = ForwardCommand only
BinaryPrimitives.WriteUInt16LittleEndian(body.AsSpan(p), 0x0007); p += 2; // ForwardCommand = RunForward
BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(p), 0x80007777u); p += 4; // sticky object guid — AFTER ForwardCommand
var result = UpdateMotion.TryParse(body);
Assert.NotNull(result);
Assert.Equal((ushort)0x0007, result!.Value.MotionState.ForwardCommand);
Assert.Equal(0x80007777u, result.Value.MotionState.StickyObjectGuid);
}
}

65
tests/AcDream.Core.Tests/Combat/CombatAnimationPlannerTests.cs
View file

@ -9,12 +9,12 @@ public sealed class CombatAnimationPlannerTests
[Theory]
[InlineData(0x10000058u, CombatAnimationKind.MeleeSwing)] // ThrustMed
[InlineData(0x1000005Bu, CombatAnimationKind.MeleeSwing)] // SlashHigh
[InlineData(0x1000017Du, CombatAnimationKind.MeleeSwing)] // OffhandDoubleThrustMed
[InlineData(0x1000018Eu, CombatAnimationKind.MeleeSwing)] // PunchFastLow
[InlineData(0x1000017Du, CombatAnimationKind.MeleeSwing)] // OffhandTripleSlashMed (DRW)
[InlineData(0x1000018Eu, CombatAnimationKind.CreatureAttack)] // AttackLow6 (DRW) — was mislabelled PunchFastLow under 2013 numbering
[InlineData(0x10000061u, CombatAnimationKind.MissileAttack)] // Shoot
[InlineData(0x100000D4u, CombatAnimationKind.MissileAttack)] // Reload
[InlineData(0x40000016u, CombatAnimationKind.MissileAttack)] // Reload (DRW SubState) — was the dead 2013 value 0x100000D4
[InlineData(0x10000062u, CombatAnimationKind.CreatureAttack)] // AttackHigh1
[InlineData(0x1000018Bu, CombatAnimationKind.CreatureAttack)] // AttackLow6
[InlineData(0x1000018Bu, CombatAnimationKind.CreatureAttack)] // AttackLow5 (DRW)
[InlineData(0x400000D3u, CombatAnimationKind.SpellCast)] // CastSpell
[InlineData(0x400000E0u, CombatAnimationKind.SpellCast)] // UseMagicStaff
[InlineData(0x10000051u, CombatAnimationKind.HitReaction)] // Twitch1
@ -30,11 +30,16 @@ public sealed class CombatAnimationPlannerTests
Assert.Equal(expected, CombatAnimationPlanner.ClassifyMotionCommand(command));
}
// These pin the RESOLVER (wire u16 -> full 32-bit) against the DRW enum,
// independent of the planner. wire 0x0170 is IssueSlashCommand = 0x09000170
// (class 0x09, UI command) — there is no Action-class (0x10) entry at that
// wire; the real OffhandSlashHigh is 0x10000173 (the 2013 decomp numbers it
// 0x10000170, +3 low). See docs/research/2026-06-26-ace-vs-2013-motion-command-gap.md.
[Theory]
[InlineData(0x0170, 0x10000170u)] // OffhandSlashHigh
[InlineData(0x017D, 0x1000017Du)] // OffhandDoubleThrustMed
[InlineData(0x018B, 0x1000018Bu)] // AttackLow6
[InlineData(0x018E, 0x1000018Eu)] // PunchFastLow
[InlineData(0x0170, 0x09000170u)] // IssueSlashCommand (UI class), NOT OffhandSlashHigh
[InlineData(0x017D, 0x1000017Du)] // OffhandTripleSlashMed
[InlineData(0x018B, 0x1000018Bu)] // AttackLow5
[InlineData(0x018E, 0x1000018Eu)] // AttackLow6
public void MotionCommandResolver_UsesNamedRetailLateCombatCommands(
ushort wireCommand,
uint expectedFullCommand)
@ -42,6 +47,50 @@ public sealed class CombatAnimationPlannerTests
Assert.Equal(expectedFullCommand, MotionCommandResolver.ReconstructFullCommand(wireCommand));
}
// #159 parity: the full wire -> resolve -> classify pipeline for the
// late-combat block, which ACE/DRW numbers +3 above the 2013 decomp.
// CombatAnimationMotionCommands is now derived directly from
// DatReaderWriter.Enums.MotionCommand, so these ACE wire values must both
// reconstruct to their DRW full value AND classify into the right kind.
// (Expected full/kind pairs cross-checked against the DRW MotionCommand
// enum, Chorizite.DatReaderWriter 2.1.7.)
[Theory]
[InlineData((ushort)0x0173, 0x10000173u, CombatAnimationKind.MeleeSwing)] // OffhandSlashHigh
[InlineData((ushort)0x0175, 0x10000175u, CombatAnimationKind.MeleeSwing)] // OffhandSlashLow
[InlineData((ushort)0x0176, 0x10000176u, CombatAnimationKind.MeleeSwing)] // OffhandThrustHigh
[InlineData((ushort)0x017E, 0x1000017Eu, CombatAnimationKind.MeleeSwing)] // OffhandTripleSlashHigh
[InlineData((ushort)0x0182, 0x10000182u, CombatAnimationKind.MeleeSwing)] // OffhandTripleThrustLow
[InlineData((ushort)0x0185, 0x10000185u, CombatAnimationKind.MeleeSwing)] // OffhandKick
[InlineData((ushort)0x0186, 0x10000186u, CombatAnimationKind.CreatureAttack)] // AttackHigh4
[InlineData((ushort)0x0188, 0x10000188u, CombatAnimationKind.CreatureAttack)] // AttackLow4
[InlineData((ushort)0x018C, 0x1000018Cu, CombatAnimationKind.CreatureAttack)] // AttackHigh6
[InlineData((ushort)0x018E, 0x1000018Eu, CombatAnimationKind.CreatureAttack)] // AttackLow6
[InlineData((ushort)0x018F, 0x1000018Fu, CombatAnimationKind.MeleeSwing)] // PunchFastHigh
[InlineData((ushort)0x0191, 0x10000191u, CombatAnimationKind.MeleeSwing)] // PunchFastLow
[InlineData((ushort)0x0197, 0x10000197u, CombatAnimationKind.MeleeSwing)] // OffhandPunchFastLow
[InlineData((ushort)0x019A, 0x1000019Au, CombatAnimationKind.MeleeSwing)] // OffhandPunchSlowLow
public void PlanFromWireCommand_LateCombatBlock_UsesAceDrwNumbering(
ushort wireCommand,
uint expectedFullCommand,
CombatAnimationKind expectedKind)
{
var plan = CombatAnimationPlanner.PlanFromWireCommand(wireCommand);
Assert.Equal(expectedFullCommand, plan.MotionCommand);
Assert.Equal(expectedKind, plan.Kind);
}
// #159: Reload is the DRW SubState 0x40000016 (wire 0x0016), not the dead
// 2013 value 0x100000D4 the planner used to hold (absent from DRW entirely).
[Fact]
public void PlanFromWireCommand_Reload_UsesDrwSubStateValue()
{
var plan = CombatAnimationPlanner.PlanFromWireCommand(0x0016);
Assert.Equal(0x40000016u, plan.MotionCommand);
Assert.Equal(CombatAnimationKind.MissileAttack, plan.Kind);
Assert.Equal(AnimationCommandRouteKind.SubState, plan.RouteKind);
}
[Fact]
public void PlanFromWireCommand_Swing_IsActionOverlay()
{

6
tests/AcDream.Core.Tests/Conformance/Issue119UpNullGfxObjDumpTests.cs
View file

@ -16,9 +16,11 @@ namespace AcDream.Core.Tests.Conformance;
/// invisible)` at startup (t5-gate-launch.log:33-34); the old tower shows
/// missing stair parts (visible in retail — user axiom). UploadGfxObjMeshData
/// returns null only when the PREPARE phase produced ZERO vertices
/// (ObjectMeshManager.cs:1780), so the upload is innocent — some extraction
/// (ObjectMeshManager.UploadGfxObjMeshData's empty-vertices guard), so the
/// upload is innocent — some extraction
/// gate dropped every polygon. This dump prints the raw dat facts per polygon
/// and replicates PrepareGfxObjMeshData's gates (ObjectMeshManager.cs:1040-1058)
/// and replicates MeshExtractor.PrepareGfxObjMeshData's gates (moved from
/// ObjectMeshManager in MP1a)
/// so the zeroing gate reads directly off the output.
/// </summary>
public sealed class Issue119UpNullGfxObjDumpTests

4
tests/AcDream.Core.Tests/Conformance/StipplingSurfaceEquivalenceTests.cs
View file

@ -16,8 +16,8 @@ namespace AcDream.Core.Tests.Conformance;
/// (0x2) and BASE1_CLIPMAP (0x4) are skipped (D3DPolyRender inner draw,
/// Ghidra 0x0059d4a0; default on @0x00820e30). acdream suppresses them at
/// BUILD time via Stippling.NoPos in all four extraction paths
/// (ObjectMeshManager.PrepareGfxObjMeshData:1046 + PrepareCellStructMeshData
/// :1394, CellMesh.Build:44, GfxObjMesh.Build:71).
/// (MeshExtractor.PrepareGfxObjMeshData + PrepareCellStructMeshData
/// [moved from ObjectMeshManager in MP1a], CellMesh.Build:44, GfxObjMesh.Build:71).
///
/// These criteria are equivalent ONLY if NoPos ⇔ untextured-surface holds on
/// the content. This sweep pins both directions across the populated

221
tests/AcDream.Core.Tests/Fixtures/issue185/0x01000AC5.gfxobj.json Normal file
View file

@ -0,0 +1,221 @@
{
"GfxObjId": 16779973,
"BoundingSphereOrigin": {
"X": -0.0486506,
"Y": -0.0466059,
"Z": 0.244318
},
"BoundingSphereRadius": 1.05416,
"ResolvedPolygons": [
{
"Id": 0,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 0,
"Y": -1,
"Z": 0
},
"D": -0.75
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": -0.25,
"Y": -0.75,
"Z": 0.2
},
{
"X": -0.25,
"Y": -0.75,
"Z": -0.4
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
}
]
},
{
"Id": 1,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": -1,
"Y": 0,
"Z": 0
},
"D": -0.25
},
"Vertices": [
{
"X": -0.25,
"Y": -0.75,
"Z": 0.2
},
{
"X": -0.25,
"Y": 0.75,
"Z": 0.2
},
{
"X": -0.25,
"Y": 0.75,
"Z": -0.4
},
{
"X": -0.25,
"Y": -0.75,
"Z": -0.4
}
]
},
{
"Id": 2,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 0,
"Y": 1,
"Z": 0
},
"D": -0.75
},
"Vertices": [
{
"X": -0.25,
"Y": 0.75,
"Z": 0.2
},
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
},
{
"X": -0.25,
"Y": 0.75,
"Z": -0.4
}
]
},
{
"Id": 3,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 1,
"Y": 0,
"Z": 0
},
"D": -0.25
},
"Vertices": [
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
}
]
},
{
"Id": 4,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": -0.62469506,
"Y": 0,
"Z": 0.78086877
},
"D": -0.31234753
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": -0.25,
"Y": 0.75,
"Z": 0.2
},
{
"X": -0.25,
"Y": -0.75,
"Z": 0.2
}
]
},
{
"Id": 5,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 0.62469506,
"Y": 0,
"Z": -0.78086877
},
"D": -0.15617374
},
"Vertices": [
{
"X": -0.25,
"Y": 0.75,
"Z": -0.4
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
},
{
"X": -0.25,
"Y": -0.75,
"Z": -0.4
}
]
}
]
}

226
tests/AcDream.Core.Tests/Fixtures/issue185/0x01000ACA.gfxobj.json Normal file
View file

@ -0,0 +1,226 @@
{
"GfxObjId": 16779978,
"BoundingSphereOrigin": {
"X": -0.125,
"Y": 0,
"Z": 0.3
},
"BoundingSphereRadius": 0.900576,
"ResolvedPolygons": [
{
"Id": 0,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 0,
"Y": -1,
"Z": 0
},
"D": -0.75
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": -0.5,
"Y": -0.75,
"Z": 1.78814E-08
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
}
]
},
{
"Id": 1,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 0,
"Y": 1,
"Z": 0
},
"D": -0.75
},
"Vertices": [
{
"X": -0.5,
"Y": 0.75,
"Z": 1.78814E-08
},
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
}
]
},
{
"Id": 2,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 1,
"Y": 0,
"Z": 0
},
"D": -0.25
},
"Vertices": [
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
}
]
},
{
"Id": 3,
"NumPoints": 4,
"SidesType": 0,
"Plane": {
"Normal": {
"X": -0.62469506,
"Y": 0,
"Z": 0.7808688
},
"D": -0.31234753
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 0.6
},
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
},
{
"X": -0.5,
"Y": 0.75,
"Z": 1.78814E-08
},
{
"X": -0.5,
"Y": -0.75,
"Z": 1.78814E-08
}
]
},
{
"Id": 4,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 7.947333E-09,
"Y": 0,
"Z": -1
},
"D": 2.1855065E-08
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
},
{
"X": -0.5,
"Y": -0.75,
"Z": 1.78814E-08
},
{
"X": -0.5,
"Y": 0.75,
"Z": 1.78814E-08
}
]
},
{
"Id": 5,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 1,
"Y": 0,
"Z": 0
},
"D": -0.25
},
"Vertices": [
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
},
{
"X": 0.25,
"Y": 0.75,
"Z": 0.6
}
]
},
{
"Id": 6,
"NumPoints": 3,
"SidesType": 0,
"Plane": {
"Normal": {
"X": 7.947333E-09,
"Y": 0,
"Z": -1
},
"D": 2.1855065E-08
},
"Vertices": [
{
"X": -0.5,
"Y": 0.75,
"Z": 1.78814E-08
},
{
"X": 0.25,
"Y": 0.75,
"Z": 2.38419E-08
},
{
"X": 0.25,
"Y": -0.75,
"Z": 2.38419E-08
}
]
}
]
}

2953
tests/AcDream.Core.Tests/Fixtures/l2g-observer-trace.log Normal file
View file

File diff suppressed because it is too large Load diff

386
tests/AcDream.Core.Tests/Input/PlayerMoveToCutoverTests.cs Normal file
View file

@ -0,0 +1,386 @@
using System;
using System.Numerics;
using AcDream.App.Input;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
using Position = AcDream.Core.Physics.Position;
namespace AcDream.Core.Tests.Input;
/// <summary>
/// R4-V5 — local-player MoveTo cutover: a <see cref="MoveToManager"/> bound
/// to the controller exactly the way <c>GameWindow.EnterPlayerModeNow</c>
/// binds it (Yaw-authoritative heading seams via the P5 bridge, Contact
/// transient bit, SimTimeSeconds clock) drives the player's body through
/// <see cref="PlayerMovementController.Update"/> with NO user input — the
/// manager's <c>_DoMotion</c> dispatches land in InterpretedState and the
/// controller's per-frame sections turn them into Yaw rotation + body
/// velocity. Also pins the TS-36 retirement: any input edge (movement key,
/// jump) cancels the moveto through the retail
/// InterruptCurrentMovement → CancelMoveTo chain, and a cancel never fires
/// the MoveToComplete completion seam (AD-27's deferred-Use contract).
/// </summary>
public class PlayerMoveToCutoverTests
{
private const uint NC = 0x8000003Du;
private const uint Ready = 0x41000003u;
private const uint Walk = 0x45000005u;
private const uint Run = 0x44000007u;
private const uint TurnRight = 0x6500000Du;
private sealed class Loader : IAnimationLoader
{
private readonly System.Collections.Generic.Dictionary<uint, Animation> _anims = new();
public void Register(uint id, Animation anim) => _anims[id] = anim;
public Animation? LoadAnimation(uint id) => _anims.TryGetValue(id, out var a) ? a : null;
}
private static Animation MakeAnim(int frames)
{
var anim = new Animation();
for (int f = 0; f < frames; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static MotionData MakeMd(uint animId)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData { AnimId = qid, LowFrame = 0, HighFrame = -1, Framerate = 30f });
return md;
}
private static AnimationSequencer MakeSequencer()
{
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(Vector3.One);
var loader = new Loader();
loader.Register(0x300u, MakeAnim(4));
loader.Register(0x301u, MakeAnim(6));
loader.Register(0x302u, MakeAnim(6));
loader.Register(0x303u, MakeAnim(6));
var mt = new MotionTable { DefaultStyle = (DRWMotionCommand)NC };
mt.StyleDefaults[(DRWMotionCommand)NC] = (DRWMotionCommand)Ready;
mt.Cycles[(int)((NC << 16) | (Ready & 0xFFFFFFu))] = MakeMd(0x300u);
mt.Cycles[(int)((NC << 16) | (Walk & 0xFFFFFFu))] = MakeMd(0x301u);
mt.Cycles[(int)((NC << 16) | (Run & 0xFFFFFFu))] = MakeMd(0x302u);
// The MoveToManager's aux-turn steering / TurnToHeading nodes
// dispatch TurnRight (adjust_motion normalizes TurnLeft into it) —
// without a table cycle the real sink's false return becomes a
// _DoMotion error and the manager cancels the moveto (retail
// dispatch-failure semantics), so the fixture needs one.
mt.Cycles[(int)((NC << 16) | (TurnRight & 0xFFFFFFu))] = MakeMd(0x303u);
return new AnimationSequencer(setup, mt, loader);
}
private static PhysicsEngine MakeFlatEngine()
{
var engine = new PhysicsEngine();
var heights = new byte[81];
Array.Fill(heights, (byte)50);
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = i * 1f;
var terrain = new TerrainSurface(heights, heightTable);
engine.AddLandblock(0xA9B4FFFFu, terrain, Array.Empty<CellSurface>(),
Array.Empty<PortalPlane>(), worldOffsetX: 0f, worldOffsetY: 0f);
return engine;
}
private sealed class Rig
{
public required PlayerMovementController Controller;
public required MoveToManager MoveTo;
public int MoveToCompleteCount;
public WeenieError LastCompleteError;
}
/// <summary>The EnterPlayerModeNow bind set, verbatim shape: real sink,
/// Yaw-authoritative heading seams (P5 bridge), Contact bit, false
/// isInterpolating, SimTimeSeconds clock, TS-36 interrupt binding.</summary>
private static Rig MakeRig() => MakeRig(out _);
private static Rig MakeRig(out AnimationSequencer seqOut)
{
var controller = new PlayerMovementController(MakeFlatEngine());
var seq = MakeSequencer();
seqOut = seq;
// Production (EnterPlayerModeNow) order: the sink binds BEFORE the
// initial SetPosition — SetPosition → StopCompletely needs the sink
// for its type-5 motion-table dispatch, the completable partner of
// the A9 pending_motions node (a null sink orphans it and the
// MoveToManager wait-for-anims gate never opens — the live stall).
controller.Motion.DefaultSink = new MotionTableDispatchSink(seq);
// #174: production wiring — HandleEnterWorld (strip + drain), not
// the bare sequence strip (which orphaned pending manager nodes).
controller.Motion.RemoveLinkAnimations = () => seq.Manager.HandleEnterWorld();
controller.Motion.InitializeMotionTables = () => seq.Manager.InitializeState();
controller.Motion.CheckForCompletedMotions = seq.Manager.CheckForCompletedMotions;
controller.SetPosition(new Vector3(96f, 96f, 50f), 0x0001);
controller.Yaw = 0f; // heading 90 = facing +X
var rig = new Rig { Controller = controller, MoveTo = null! };
var moveTo = new MoveToManager(
controller.Motion,
stopCompletely: () => controller.Motion.StopCompletely(),
getPosition: () => new Position(
controller.CellId, controller.Position, controller.BodyOrientation),
getHeading: () => MoveToMath.HeadingFromYaw(controller.Yaw),
setHeading: (h, _) => controller.Yaw = MoveToMath.YawFromHeading(h),
getOwnRadius: () => 0f,
getOwnHeight: () => 0f,
contact: () => controller.BodyInContact,
isInterpolating: () => false,
getVelocity: () => controller.BodyVelocity,
getSelfId: () => 0x5000000Au,
setTarget: (_, _, _, _) => { },
clearTarget: () => { },
getTargetQuantum: () => 0.0,
setTargetQuantum: _ => { },
curTime: () => controller.SimTimeSeconds);
moveTo.MoveToComplete = err =>
{
rig.MoveToCompleteCount++;
rig.LastCompleteError = err;
};
controller.MoveTo = moveTo;
controller.Motion.InterruptCurrentMovement =
() => moveTo.CancelMoveTo(WeenieError.ActionCancelled);
rig.MoveTo = moveTo;
return rig;
}
/// <summary>Stands in for the player sequencer's MotionDone feed (bound
/// in production via the R3-W2 MotionTableManager seam) — without it,
/// pending_motions never drains in this fixture and the manager's
/// wait-for-anims gates wedge.</summary>
private static void Drain(PlayerMovementController c)
{
while (c.Motion.MotionsPending())
c.Motion.MotionDone(0, true);
}
[Fact]
public void ServerMoveToPosition_WalksToArrival_WithNoUserInput()
{
var rig = MakeRig();
var c = rig.Controller;
var dest = new Vector3(104f, 96f, 50f); // 8 m dead ahead (heading 90)
// Mirrors the GameWindow wire path's P1 unpack store (00509730):
// a server moveto arrives with IsAutonomous=false, routing the
// per-tick pump's A3 dual dispatch to the interpreted branch.
rig.Controller.SetLastMoveWasAutonomous(false);
rig.MoveTo.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(c.CellId, dest, Quaternion.Identity),
Params = new MovementParameters { UseSpheres = false, DistanceToObject = 0.6f },
});
Drain(c);
Assert.True(rig.MoveTo.IsMovingTo());
for (int f = 0; f < 1200 && rig.MoveTo.IsMovingTo(); f++)
{
var result = c.Update(1f / 60f, new MovementInput());
// The #75 invariant, now by construction: manager-driven motion
// never registers as a user motion-state change, so no outbound
// MoveToState is built mid-moveto.
Assert.False(result.MotionStateChanged,
$"manager-driven frame {f} must not flag MotionStateChanged");
Drain(c);
}
Assert.False(rig.MoveTo.IsMovingTo(), "moveto must arrive within the frame budget");
float distLeft = Vector2.Distance(
new Vector2(c.Position.X, c.Position.Y), new Vector2(dest.X, dest.Y));
Assert.True(distLeft <= 1.0f,
$"body must stop at the arrival radius; {distLeft:F2} m left");
Assert.Equal(1, rig.MoveToCompleteCount);
Assert.Equal(WeenieError.None, rig.LastCompleteError);
Assert.Equal(Ready, c.Motion.InterpretedState.ForwardCommand);
}
[Fact]
public void ServerTurnToHeading_RotatesYaw_AndSnapsExact()
{
var rig = MakeRig();
var c = rig.Controller;
// Mirrors the GameWindow wire path's P1 unpack store (00509730):
// a server moveto arrives with IsAutonomous=false, routing the
// per-tick pump's A3 dual dispatch to the interpreted branch.
rig.Controller.SetLastMoveWasAutonomous(false);
rig.MoveTo.PerformMovement(new MovementStruct
{
Type = MovementType.TurnToHeading,
Params = new MovementParameters { DesiredHeading = 180f }, // South = -Y
});
Drain(c);
Assert.True(rig.MoveTo.IsMovingTo());
for (int f = 0; f < 600 && rig.MoveTo.IsMovingTo(); f++)
{
c.Update(1f / 60f, new MovementInput());
Drain(c);
}
Assert.False(rig.MoveTo.IsMovingTo(), "turn-to must complete within the frame budget");
// HandleTurnToHeading's arrival snap (the ONE heading snap in the
// family, 0052a146) writes through the Yaw seam: heading 180 → yaw
// -π/2 per the P5 bridge.
Assert.Equal(MoveToMath.YawFromHeading(180f), c.Yaw, 3);
Assert.Equal(1, rig.MoveToCompleteCount);
}
[Fact]
public void MovementKeyEdge_CancelsMoveTo_WithoutFiringComplete()
{
var rig = MakeRig();
var c = rig.Controller;
// Mirrors the GameWindow wire path's P1 unpack store (00509730):
// a server moveto arrives with IsAutonomous=false, routing the
// per-tick pump's A3 dual dispatch to the interpreted branch.
rig.Controller.SetLastMoveWasAutonomous(false);
rig.MoveTo.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(c.CellId, new Vector3(150f, 96f, 50f), Quaternion.Identity),
Params = new MovementParameters { UseSpheres = false },
});
Drain(c);
Assert.True(rig.MoveTo.IsMovingTo());
c.Update(1f / 60f, new MovementInput());
Drain(c);
Assert.True(rig.MoveTo.IsMovingTo());
// W press edge → DoMotion(ctor-default params, CancelMoveTo bit set)
// → InterruptCurrentMovement → CancelMoveTo(ActionCancelled).
var result = c.Update(1f / 60f, new MovementInput { Forward = true });
Assert.False(rig.MoveTo.IsMovingTo(), "user input must cancel the moveto (TS-36)");
Assert.Equal(0, rig.MoveToCompleteCount);
// The cancel-frame's state change IS user intent — it must go on
// the wire (the former !IsServerAutoWalking guard is gone).
Assert.True(result.MotionStateChanged);
}
[Fact]
public void LoginQueue_DrainsToEmpty_UnderProductionFeed()
{
// The second live stall (2026-07-03, [autowalk-gate] probe): ONE
// immortal Ready node in pending_motions — login SetPosition's
// StopCompletely fired before the sink bind, orphaning its A9 node
// (no completable partner). Head-pop-any relabels but never empties
// a queue with an orphan, and MotionsPending==true wedges every
// subsequent moveto. This pins the invariant: after login (rig
// construction, production bind order) the queue must reach EMPTY
// under the production completion feed.
var rig = MakeRig(out var seq);
var c = rig.Controller;
seq.MotionDoneTarget = (m, ok) => c.Motion.MotionDone(m, ok);
for (int f = 0; f < 300 && c.Motion.MotionsPending(); f++)
{
c.Update(1f / 60f, new MovementInput());
seq.Advance(1f / 60f);
}
Assert.False(c.Motion.MotionsPending(),
"login pending_motions must drain to empty under the production feed");
}
[Fact]
public void ServerMoveToPosition_ProductionCompletionFeed_WalksToArrival()
{
// The 2026-07-03 live wedge repro: same scenario as
// ServerMoveToPosition_WalksToArrival_WithNoUserInput, but the
// pending_motions queue drains the way PRODUCTION drains it — the
// sequencer's Advance() fires MotionDoneTarget → Motion.MotionDone
// (the TickAnimations R3-W2 bind) — instead of this suite's
// force-drain. Live symptom: the moveto armed (movingTo=True) but
// the body never moved; BeginTurnToHeading's wait-for-anims gate
// (MotionsPending) never opened because the player's queue never
// emptied (launch.log: pending=True on 92/94 player MOTIONDONE
// pops; remotes 0/40).
var rig = MakeRig(out var seq);
var c = rig.Controller;
seq.MotionDoneTarget = (m, ok) => c.Motion.MotionDone(m, ok);
var dest = new Vector3(104f, 96f, 50f); // 8 m dead ahead (heading 90)
// A few idle frames first — production always has render ticks
// between login (SetPosition → StopCompletely queues the A9 node
// with NO dispatch) and the first Use.
for (int f = 0; f < 30; f++)
{
c.Update(1f / 60f, new MovementInput());
seq.Advance(1f / 60f);
}
// Mirrors the GameWindow wire path's P1 unpack store (00509730):
// a server moveto arrives with IsAutonomous=false, routing the
// per-tick pump's A3 dual dispatch to the interpreted branch.
rig.Controller.SetLastMoveWasAutonomous(false);
rig.MoveTo.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(c.CellId, dest, Quaternion.Identity),
Params = new MovementParameters { UseSpheres = false, DistanceToObject = 0.6f },
});
Assert.True(rig.MoveTo.IsMovingTo());
for (int f = 0; f < 1200 && rig.MoveTo.IsMovingTo(); f++)
{
c.Update(1f / 60f, new MovementInput());
seq.Advance(1f / 60f);
}
string queueDump = string.Join(", ",
System.Linq.Enumerable.Select(c.Motion.PendingMotions, n => $"0x{n.Motion:X8}"));
Assert.False(rig.MoveTo.IsMovingTo(),
$"moveto wedged: pending_motions never drained under the production "
+ $"completion feed (queue: [{queueDump}])");
Assert.Equal(1, rig.MoveToCompleteCount);
}
[Fact]
public void JumpRelease_CancelsMoveTo()
{
var rig = MakeRig();
var c = rig.Controller;
// Mirrors the GameWindow wire path's P1 unpack store (00509730):
// a server moveto arrives with IsAutonomous=false, routing the
// per-tick pump's A3 dual dispatch to the interpreted branch.
rig.Controller.SetLastMoveWasAutonomous(false);
rig.MoveTo.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(c.CellId, new Vector3(150f, 96f, 50f), Quaternion.Identity),
Params = new MovementParameters { UseSpheres = false },
});
Drain(c);
Assert.True(rig.MoveTo.IsMovingTo());
// Charge one frame, release the next — jump() fires on the release
// edge and its interrupt site cancels the moveto (the exact
// silent-double-motion failure the TS-36 register row predicted).
c.Update(1f / 60f, new MovementInput { Jump = true });
c.Update(1f / 60f, new MovementInput());
Assert.False(rig.MoveTo.IsMovingTo(), "jump must cancel the moveto (TS-36)");
Assert.Equal(0, rig.MoveToCompleteCount);
}
}

202
tests/AcDream.Core.Tests/Input/W6EdgeDrivenMovementTests.cs Normal file
View file

@ -0,0 +1,202 @@
using System;
using System.Numerics;
using AcDream.App.Input;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
namespace AcDream.Core.Tests.Input;
/// <summary>
/// R3-W6 regression suite for the edge-driven local player — specifically
/// the "press W and stop instantly" bug (2026-07-03): the funnel's apply
/// pass let its own style dispatch's <c>ApplyMotion(style)</c> state-write
/// reset forward to Ready (raw 0051ea6c). The original W6 fix entry-cached
/// the axis fields; #161 replaced that with the TRUE retail mechanism —
/// the apply pass's <c>MovementParameters</c> carry
/// <c>ModifyInterpretedState = false</c> (retail's smeared bitfield store
/// at raw 305778, mask 0x37ff; ACE MotionInterp.cs:447), so NO dispatch in
/// the pass can write <c>InterpretedState</c> at all and live field reads
/// are retail semantics. These tests pin the user-visible invariant either
/// way: pressing W keeps you moving.
///
/// These tests bind the REAL <see cref="MotionTableDispatchSink"/> over a
/// real sequencer (a fake sink's return values can mask state-write gating
/// — the lesson that created this file).
/// </summary>
public class W6EdgeDrivenMovementTests
{
private const uint NC = 0x8000003Du;
private const uint Ready = 0x41000003u;
private const uint Walk = 0x45000005u;
private const uint Run = 0x44000007u;
private sealed class Loader : IAnimationLoader
{
private readonly System.Collections.Generic.Dictionary<uint, Animation> _anims = new();
public void Register(uint id, Animation anim) => _anims[id] = anim;
public Animation? LoadAnimation(uint id) => _anims.TryGetValue(id, out var a) ? a : null;
}
private static Animation MakeAnim(int frames)
{
var anim = new Animation();
for (int f = 0; f < frames; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static MotionData MakeMd(uint animId)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData { AnimId = qid, LowFrame = 0, HighFrame = -1, Framerate = 30f });
return md;
}
private static AnimationSequencer MakeSequencer()
{
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(Vector3.One);
var loader = new Loader();
loader.Register(0x300u, MakeAnim(4));
loader.Register(0x301u, MakeAnim(6));
loader.Register(0x302u, MakeAnim(6));
var mt = new MotionTable { DefaultStyle = (DRWMotionCommand)NC };
mt.StyleDefaults[(DRWMotionCommand)NC] = (DRWMotionCommand)Ready;
mt.Cycles[(int)((NC << 16) | (Ready & 0xFFFFFFu))] = MakeMd(0x300u);
mt.Cycles[(int)((NC << 16) | (Walk & 0xFFFFFFu))] = MakeMd(0x301u);
mt.Cycles[(int)((NC << 16) | (Run & 0xFFFFFFu))] = MakeMd(0x302u);
return new AnimationSequencer(setup, mt, loader);
}
private static PhysicsEngine MakeFlatEngine()
{
var engine = new PhysicsEngine();
var heights = new byte[81];
Array.Fill(heights, (byte)50);
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = i * 1f;
var terrain = new TerrainSurface(heights, heightTable);
engine.AddLandblock(0xA9B4FFFFu, terrain, Array.Empty<CellSurface>(),
Array.Empty<PortalPlane>(), worldOffsetX: 0f, worldOffsetY: 0f);
return engine;
}
private static PlayerMovementController MakeControllerWithRealSink(out AnimationSequencer seq)
{
var controller = new PlayerMovementController(MakeFlatEngine());
seq = MakeSequencer();
// The full W6 GameWindow bind set (EnterPlayerModeNow equivalent) —
// sink binds BEFORE SetPosition, matching the R4-V5 stall-fix order
// (SetPosition → StopCompletely needs the sink for its type-5
// dispatch, else its A9 pending_motions node is orphaned).
controller.Motion.DefaultSink = new MotionTableDispatchSink(seq);
var s = seq;
// #174: production wiring — HandleEnterWorld (strip + drain), not
// the bare sequence strip (which orphaned pending manager nodes).
controller.Motion.RemoveLinkAnimations = () => s.Manager.HandleEnterWorld();
controller.Motion.InitializeMotionTables = () => s.Manager.InitializeState();
controller.Motion.CheckForCompletedMotions = s.Manager.CheckForCompletedMotions;
controller.SetPosition(new Vector3(96f, 96f, 50f), 0x0001);
controller.Yaw = 0f;
return controller;
}
/// <summary>
/// The full apply pass the W6b live bug rode in on. Pre-R4-V5 the
/// trigger was <c>ApplyServerRunRate</c> (the ACE autonomous-echo tap);
/// V5's P1 gate drops that echo before it reaches the player, and the
/// tap is deleted — but the regression these tests pin lives in
/// <c>ApplyInterpretedMovement</c>'s pass-params state protection
/// (ModifyInterpretedState=false since #161), which any
/// apply_current_movement pass (HitGround re-apply, future R6 per-tick
/// order) still exercises. Same two statements the deleted tap ran.
/// </summary>
private static void RunApplyPass(PlayerMovementController controller, float forwardSpeed)
{
controller.Motion.InterpretedState.ForwardSpeed = forwardSpeed;
controller.Motion.apply_current_movement(cancelMoveTo: false, allowJump: false);
}
[Fact]
public void ApplyPass_WithRealSink_ForwardSelfHeals()
{
// The distilled bug: a full apply pass (style dispatch included)
// against the REAL sink must leave the interpreted forward exactly
// where it started — the style apply's Ready reset is re-applied
// over by the entry-cached fwd dispatch (retail self-heal).
var controller = MakeControllerWithRealSink(out _);
var input = new MovementInput { Forward = true, Run = true };
controller.Update(1f / 60f, input); // W press edge -> RunForward
Assert.Equal(Run, controller.Motion.InterpretedState.ForwardCommand);
// The live killer: a full apply pass mid-hold (was the ~10Hz
// UM-echo tap pre-V5; see RunApplyPass).
RunApplyPass(controller, 4.5f);
Assert.Equal(Run, controller.Motion.InterpretedState.ForwardCommand);
Assert.True(controller.Motion.get_state_velocity().Length() > 1f,
"state velocity must survive the apply pass");
}
[Fact]
public void HoldW_WithRealSink_AndEchoes_BodyKeepsMoving()
{
var controller = MakeControllerWithRealSink(out _);
var input = new MovementInput { Forward = true, Run = true };
float startX = 96f;
Vector3 pos = new(startX, 96f, 50f);
for (int f = 0; f < 120; f++)
{
if (f % 6 == 3)
RunApplyPass(controller, 4.5f); // ex-ACE-echo cadence
pos = controller.Update(1f / 60f, input).Position;
}
// 2 seconds of held-W running (post-fix ~9.5 m/s) must cover
// meters, not centimeters. Pre-fix this stalled at ~one tick of
// travel (the echo pass reset forward to Ready).
Assert.True(pos.X - startX > 5f,
$"expected sustained forward motion, got {pos.X - startX:F2} m");
}
[Fact]
public void ShiftToggle_MidHold_WalkRunTransitionSurvivesEcho()
{
var controller = MakeControllerWithRealSink(out _);
// Hold W at run for 30 frames.
for (int f = 0; f < 30; f++)
controller.Update(1f / 60f, new MovementInput { Forward = true, Run = true });
Assert.Equal(Run, controller.Motion.InterpretedState.ForwardCommand);
// Shift pressed (walk) — the set_hold_run edge demotes to walk.
for (int f = 0; f < 30; f++)
{
if (f == 10) RunApplyPass(controller, 1.0f); // apply pass mid-walk
controller.Update(1f / 60f, new MovementInput { Forward = true, Run = false });
}
Assert.Equal(Walk, controller.Motion.InterpretedState.ForwardCommand);
// Shift released — promote back to run; survives another echo.
for (int f = 0; f < 30; f++)
{
if (f == 10) RunApplyPass(controller, 4.5f);
controller.Update(1f / 60f, new MovementInput { Forward = true, Run = true });
}
Assert.Equal(Run, controller.Motion.InterpretedState.ForwardCommand);
}
}

270
tests/AcDream.Core.Tests/Lighting/LightManagerTests.cs
View file

@ -1,3 +1,4 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Lighting;
using Xunit;
@ -6,7 +7,7 @@ namespace AcDream.Core.Tests.Lighting;
public sealed class LightManagerTests
{
private static LightSource MakePoint(Vector3 pos, float range, uint ownerId = 0, bool lit = true)
private static LightSource MakePoint(Vector3 pos, float range, uint ownerId = 0, bool lit = true, uint cellId = 0)
=> new LightSource
{
Kind = LightKind.Point,
@ -14,6 +15,18 @@ public sealed class LightManagerTests
Range = range,
IsLit = lit,
OwnerId = ownerId,
CellId = cellId,
};
private static LightSource MakeDynamic(Vector3 pos, float range, uint cellId = 0)
=> new LightSource
{
Kind = LightKind.Point,
WorldPosition = pos,
Range = range,
IsLit = true,
IsDynamic = true,
CellId = cellId,
};
[Fact]
@ -176,6 +189,148 @@ public sealed class LightManagerTests
Assert.Equal(1f, mgr.PointSnapshot[1].WorldPosition.X, 3);
}
// ── Resident collection (#176 corrected reading, 2026-07-06) ───────────────
// Retail collects the pool from ALL RESIDENT EnvCells each frame:
// CEnvCell::add_dynamic_lights (0x0052d410) walks the WHOLE static
// CEnvCell::visible_cell_table — the loaded-cell registry add_visible_cell
// (0x0052de40) fills from each activated cell + its dat visible-cell list. It
// is NOT the per-frame portal flood; camera gaze cannot change the pool. The
// earlier flood-scoped port (c500912b) made the under-room portal purples
// enter/leave the pool as the camera turned — the #176 seam-floor blink.
[Fact]
public void PointSnapshot_ResidentCollection_CellTagDoesNotFilter()
{
var mgr = new LightManager();
mgr.Register(MakePoint(new Vector3(1, 0, 0), 5f, cellId: 0xAAAA0101u)); // "visible" room
mgr.Register(MakePoint(new Vector3(2, 0, 0), 5f, cellId: 0xAAAA0102u)); // under-room
mgr.Register(MakePoint(new Vector3(3, 0, 0), 5f, cellId: 0u)); // cell-less (viewer fill)
mgr.BuildPointLightSnapshot(Vector3.Zero);
// ALL resident lights are candidates. The under-room portal light reaching
// the corridor's pool is retail-correct — the live cdb capture
// (tools/cdb/issue176-floor-light.cdb) showed retail applying the
// intensity-100 purples to EVERY Hub cell; the faceted purple wedge is
// faithful, only its gaze-coupled blinking was ours.
Assert.Equal(3, mgr.PointSnapshot.Count);
}
[Fact]
public void PointSnapshot_OverCap_DynamicsNeverEvictedByNearerStatics()
{
var mgr = new LightManager();
// More statics than the cap, ALL nearer the player than every dynamic.
for (int i = 0; i < LightManager.MaxGlobalLights + 20; i++)
mgr.Register(MakePoint(new Vector3(i * 0.01f, 0, 0), 5f, ownerId: (uint)(i + 1)));
// 7 dynamics farther out (retail's dynamics live in their own 7-slot pool —
// Render::add_dynamic_light 0x0054d420 — statics can never crowd them out).
var dyns = new LightSource[7];
for (int i = 0; i < dyns.Length; i++)
{
dyns[i] = MakeDynamic(new Vector3(50f + i, 0, 0), range: 9f);
mgr.Register(dyns[i]);
}
mgr.BuildPointLightSnapshot(Vector3.Zero);
Assert.Equal(LightManager.MaxGlobalLights, mgr.PointSnapshot.Count);
foreach (var d in dyns)
Assert.Contains(d, mgr.PointSnapshot);
}
[Fact]
public void PointSnapshot_OverCap_KeepsNearestThePlayer()
{
var mgr = new LightManager();
// A big cluster far from the player (where a chase camera might sit) and
// one torch beside the player. Retail sorts by distance to
// Render::player_pos (insert_light 0x0054d1b0) — the near-player torch
// must survive the cap no matter how many far lights exist.
for (int i = 0; i < LightManager.MaxGlobalLights + 50; i++)
mgr.Register(MakePoint(new Vector3(200f + i * 0.05f, 0, 0), 5f, ownerId: (uint)(i + 1)));
var torch = MakePoint(new Vector3(2f, 0, 0), range: 15f, ownerId: 0xF00Du);
mgr.Register(torch);
mgr.BuildPointLightSnapshot(playerWorldPos: Vector3.Zero);
Assert.Contains(torch, mgr.PointSnapshot);
}
// ── Visible-cell scoping (A7.L1, 2026-07-09 — the Town Network starvation fix) ──
// BuildPointLightSnapshot's player-nearest cap sorts by raw Euclidean distance,
// which is not a reliable proxy for "same room" in a dense, maze-like hub: a
// fixture on the other side of a wall can be geometrically closer than the
// player's own room's torches. The Town Network fountain room (463 registered
// fixtures, cap 128) went dark because far-denser, closer-in-a-straight-line
// corridor fixtures won the cap over the room's own lights. Filtering candidacy
// by the frame's actual visible-cell set (the render already computes this)
// fixes it without touching the distance-sort anchor (still the PLAYER, per the
// #176 correction — camera anchoring is what caused the earlier flicker).
[Fact]
public void BuildPointLightSnapshot_VisibleCellScoping_RoomLightsSurviveOverEuclideanCloserInvisibleCell()
{
var mgr = new LightManager();
// A different, NOT-visible cell packed with fixtures that are, in raw
// straight-line distance, closer to the player than the room's own
// torches (e.g. a corridor on the other side of a wall).
const uint otherCellId = 0xAAAA0102u;
for (int i = 0; i < LightManager.MaxGlobalLights + 50; i++)
mgr.Register(MakePoint(new Vector3(1f + i * 0.001f, 1f, 0), range: 5f, ownerId: (uint)(i + 1), cellId: otherCellId));
// The player's own room: a handful of torches, each FARTHER in raw
// distance than every "other cell" fixture above, but the only cell
// actually visible from the player's viewpoint this frame.
const uint roomCellId = 0xAAAA0101u;
var roomTorches = new LightSource[5];
for (int i = 0; i < roomTorches.Length; i++)
{
roomTorches[i] = MakePoint(new Vector3(50f + i, 0, 0), range: 15f, cellId: roomCellId);
mgr.Register(roomTorches[i]);
}
var visibleCells = new HashSet<uint> { roomCellId };
mgr.BuildPointLightSnapshot(playerWorldPos: Vector3.Zero, visibleCells);
foreach (var torch in roomTorches)
Assert.Contains(torch, mgr.PointSnapshot);
}
[Fact]
public void BuildPointLightSnapshot_VisibleCellScoping_CellLessLightAlwaysIncluded()
{
// The viewer fill light (CellId==0) must survive scoping unconditionally —
// retail's per-frame add_dynamic_light(&viewer_light, ...) is unconditional
// (LightManager.UpdateViewerLight's doc comment).
var mgr = new LightManager();
var viewerFill = MakePoint(new Vector3(0, 0, 2), range: 15f, cellId: 0u);
mgr.Register(viewerFill);
var otherRoom = MakePoint(new Vector3(2, 0, 0), range: 5f, cellId: 0xBEEFu);
mgr.Register(otherRoom);
var visibleCells = new HashSet<uint> { 0xF00Du }; // neither light's cell
mgr.BuildPointLightSnapshot(Vector3.Zero, visibleCells);
Assert.Contains(viewerFill, mgr.PointSnapshot);
Assert.DoesNotContain(otherRoom, mgr.PointSnapshot);
}
[Fact]
public void BuildPointLightSnapshot_NoVisibleCellsArg_UnscopedLegacyBehavior()
{
// Outdoor / no-clipRoot callers omit visibleCells — every registered lit
// light stays a candidate, exactly the pre-A7.L1 behavior.
var mgr = new LightManager();
mgr.Register(MakePoint(new Vector3(1, 0, 0), 5f, cellId: 0xAAAAu));
mgr.Register(MakePoint(new Vector3(2, 0, 0), 5f, cellId: 0xBBBBu));
mgr.BuildPointLightSnapshot(Vector3.Zero);
Assert.Equal(2, mgr.PointSnapshot.Count);
}
[Fact]
public void SelectForObject_EmptySnapshot_ReturnsZero()
{
@ -256,4 +411,117 @@ public sealed class LightManagerTests
Assert.Equal(na, nb);
Assert.Equal(a[0], b[0]);
}
// ── SelectForCell — retail minimize_envcell_lighting (all dynamics on every cell) ──
[Fact]
public void SelectForCell_AppliesAllDynamicLights_EvenOutOfReach()
{
// Retail enables the WHOLE dynamic subset for every cell (cdb-verified: the same
// portal lights on every Facility Hub cell) — including ones that don't reach it,
// since the shader's range cutoff zeroes those. Static lights still cull by reach.
var snapshot = new[]
{
MakePoint(new Vector3(1, 0, 0), range: 5f), // 0: static, reaches
MakeDynamic(new Vector3(100, 0, 0), range: 5f), // 1: dynamic, FAR (out of reach)
MakeDynamic(new Vector3(2, 0, 0), range: 5f), // 2: dynamic, near
MakePoint(new Vector3(50, 0, 0), range: 5f), // 3: static, far (out of reach)
};
Span<int> sel = stackalloc int[LightManager.MaxLightsPerObject];
int n = LightManager.SelectForCell(snapshot, Vector3.Zero, radius: 1f, sel);
bool d1 = false, d2 = false, s0 = false, s3 = false;
for (int i = 0; i < n; i++)
{
if (sel[i] == 1) d1 = true;
if (sel[i] == 2) d2 = true;
if (sel[i] == 0) s0 = true;
if (sel[i] == 3) s3 = true;
}
Assert.True(d1, "the FAR dynamic light must still be applied — retail enables all dynamics");
Assert.True(d2, "the near dynamic light is applied");
Assert.True(s0, "the near static light reaches the cell → selected");
Assert.False(s3, "the far static light doesn't reach → not selected");
}
[Fact]
public void SelectForCell_SameDynamicSet_ForCellsFarApart_NoFlap()
{
// The stability retail has and we lacked: two cells far apart get the SAME dynamic
// set. A per-cell sphere-overlap cull of dynamics (the old SelectForObject path) let
// that set differ/flip as the flood shifted → the floor lighting FLAPPED (#176).
var snapshot = new[]
{
MakeDynamic(new Vector3(0, 0, 0), range: 5f),
MakeDynamic(new Vector3(100, 0, 0), range: 5f),
};
Span<int> a = stackalloc int[8];
Span<int> b = stackalloc int[8];
int na = LightManager.SelectForCell(snapshot, new Vector3(0, 0, 0), 1f, a);
int nb = LightManager.SelectForCell(snapshot, new Vector3(500, 0, 0), 1f, b);
Assert.Equal(2, na); // both dynamics on the near cell
Assert.Equal(2, nb); // both dynamics on the far cell too — identical, no flap
}
/// <summary>
/// #176/#177 (2026-07-06, corrected same day) — the end-state pin. The pool is
/// retail's RESIDENT collection anchored at the PLAYER: a light in range of an
/// object near the player is selected no matter where a chase camera sits,
/// because the camera is not an input to <c>BuildPointLightSnapshot</c> at all
/// (the two prior camera-coupled pools — nearest-camera cap, then frame-flood
/// scoping <c>c500912b</c> — were each a #176 flicker mechanism). Here the
/// player stands by the torch while 400 fixtures cluster 200 m away where a
/// camera might look: the torch must always survive the cap and light the
/// object. See <c>docs/research/2026-07-06-a7-per-cell-lighting-pseudocode.md</c>
/// (corrected §1.3) — <c>CEnvCell::visible_cell_table</c> is the resident-cell
/// registry, and <c>Render::insert_light</c> (0x0054d1b0) sorts by distance to
/// <c>Render::player_pos</c>.
/// </summary>
[Fact]
public void PointSnapshot_HubScaleLightCount_ObjectSelectionIsCameraInvariant()
{
var mgr = new LightManager();
// 400 fixtures clustered far away (in the direction a camera might sit),
// all in another cell. Under either old camera-coupled pool these could
// displace or gate the player-side torch; under the player anchor they are
// simply the farthest candidates.
const uint farRoom = 0xAAAA0102u;
for (int i = 0; i < 400; i++)
mgr.Register(MakePoint(new Vector3(200f + i * 0.05f, 0, 0), range: 5f, ownerId: (uint)(i + 1), cellId: farRoom));
// The target torch: beside the player, in the player's room.
const uint playerRoom = 0xAAAA0101u;
var torch = MakePoint(new Vector3(2f, 0, 0), range: 15f, ownerId: 0xF00DF00Du, cellId: playerRoom);
mgr.Register(torch);
Span<int> sel = stackalloc int[LightManager.MaxLightsPerObject];
// The player (the ONLY positional input) stands at the origin. Rebuild
// twice to mirror consecutive frames of a rotating camera — the pool and
// the selection must be identical (no camera input exists to vary).
mgr.BuildPointLightSnapshot(playerWorldPos: Vector3.Zero);
int n1 = LightManager.SelectForObject(mgr.PointSnapshot, new Vector3(0f, 0, 0), 6f, sel);
bool torchSelected1 = SelectedContains(mgr.PointSnapshot, sel, n1, torch);
mgr.BuildPointLightSnapshot(playerWorldPos: Vector3.Zero);
int n2 = LightManager.SelectForObject(mgr.PointSnapshot, new Vector3(0f, 0, 0), 6f, sel);
bool torchSelected2 = SelectedContains(mgr.PointSnapshot, sel, n2, torch);
Assert.True(torchSelected1,
"an in-range light beside the player was evicted from the pool — " +
"per-cell lighting would pop (the #176/#177 mechanism)");
Assert.True(torchSelected2, "consecutive same-player builds must select identically");
Assert.Equal(LightManager.MaxGlobalLights, mgr.PointSnapshot.Count); // cap applied to the far cluster
static bool SelectedContains(
System.Collections.Generic.IReadOnlyList<LightSource> snapshot,
Span<int> indices, int count, LightSource target)
{
for (int i = 0; i < count; i++)
if (ReferenceEquals(snapshot[indices[i]], target)) return true;
return false;
}
}
}

38
tests/AcDream.Core.Tests/Meshing/EntityHydrationRulesTests.cs Normal file
View file

@ -0,0 +1,38 @@
using AcDream.Core.Meshing;
using Xunit;
namespace AcDream.Core.Tests.Meshing;
/// <summary>
/// #79/#93 (2026-07-09) — the Town Network fountain room's only dat-authored
/// light (Setup 0x02000365, a ceiling fixture) never registered: its sole
/// visual part is a #136-class runtime-hidden marker, so it flattens to zero
/// mesh refs, and GameWindow.cs's hydration loop dropped the ENTIRE entity —
/// light included — whenever meshRefs was empty. Retail's light registration
/// (CObjCell::add_light, CEnvCell::UnPack) is entirely independent of a
/// fixture's own mesh visibility; the mesh-empty gate must not also swallow
/// a Setup's Lights.
/// </summary>
public class EntityHydrationRulesTests
{
[Fact]
public void ShouldKeepEntity_NoMeshNoLights_False()
{
Assert.False(EntityHydrationRules.ShouldKeepEntity(meshRefCount: 0, setupLightCount: 0));
}
[Fact]
public void ShouldKeepEntity_NoMeshWithLights_True()
{
// The exact fountain-room case: a mesh-less "light attach point" must
// still survive hydration so its Lights can be registered.
Assert.True(EntityHydrationRules.ShouldKeepEntity(meshRefCount: 0, setupLightCount: 1));
}
[Fact]
public void ShouldKeepEntity_HasMesh_TrueRegardlessOfLights()
{
Assert.True(EntityHydrationRules.ShouldKeepEntity(meshRefCount: 1, setupLightCount: 0));
Assert.True(EntityHydrationRules.ShouldKeepEntity(meshRefCount: 3, setupLightCount: 2));
}
}

69
tests/AcDream.Core.Tests/Physics/AnimationCommandRouterTests.cs
View file

@ -1,5 +1,6 @@
using AcDream.Core.Physics;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using Xunit;
namespace AcDream.Core.Tests.Physics;
@ -24,7 +25,13 @@ public sealed class AnimationCommandRouterTests
[Fact]
public void RouteWireCommand_SubState_UsesSetCycle()
{
var seq = MakeEmptySequencer();
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0)
// — GetObjectSequence also refuses substate==0, so the MotionTable
// needs both a StyleDefaults entry AND cycles for the style's default
// substate (Ready, installed by initialize_state) and for the routed
// Dead substate, or the whole dispatch chain silently no-ops and
// CurrentStyle/CurrentMotion stay at their zero defaults.
var seq = MakeRoutableSequencer();
var route = AnimationCommandRouter.RouteWireCommand(seq, NonCombat, 0x0011);
@ -59,8 +66,66 @@ public sealed class AnimationCommandRouterTests
return new AnimationSequencer(new Setup(), new MotionTable(), new NullAnimationLoader());
}
/// <summary>
/// R2-Q4: a MotionTable that can actually complete a SubState dispatch —
/// StyleDefaults[NonCombat]=Ready (required by initialize_state's
/// SetDefaultState) plus cycles for both Ready (the installed baseline)
/// and Dead (the substate this test routes to). One shared part/anim is
/// enough; RouteWireCommand only inspects CurrentStyle/CurrentMotion.
/// </summary>
private static AnimationSequencer MakeRoutableSequencer()
{
const uint Ready = 0x41000003u;
const uint Dead = 0x40000011u;
const uint AnimId = 0x03000001u;
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(System.Numerics.Vector3.One);
var mt = new MotionTable
{
DefaultStyle = (DatReaderWriter.Enums.MotionCommand)NonCombat,
};
mt.StyleDefaults[(DatReaderWriter.Enums.MotionCommand)NonCombat] =
(DatReaderWriter.Enums.MotionCommand)Ready;
int ReadyKey = (int)((NonCombat << 16) | (Ready & 0xFFFFFFu));
int DeadKey = (int)((NonCombat << 16) | (Dead & 0xFFFFFFu));
mt.Cycles[ReadyKey] = MakeMotionData(AnimId);
mt.Cycles[DeadKey] = MakeMotionData(AnimId);
var loader = new NullAnimationLoader();
loader.Register(AnimId, MakeAnim());
return new AnimationSequencer(setup, mt, loader);
}
private static MotionData MakeMotionData(uint animId)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData { AnimId = qid, LowFrame = 0, HighFrame = -1, Framerate = 30f });
return md;
}
private static Animation MakeAnim()
{
var anim = new Animation();
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame
{
Origin = System.Numerics.Vector3.Zero,
Orientation = System.Numerics.Quaternion.Identity,
});
anim.PartFrames.Add(pf);
return anim;
}
private sealed class NullAnimationLoader : IAnimationLoader
{
public Animation? LoadAnimation(uint id) => null;
private readonly System.Collections.Generic.Dictionary<uint, Animation> _anims = new();
public void Register(uint id, Animation anim) => _anims[id] = anim;
public Animation? LoadAnimation(uint id) => _anims.TryGetValue(id, out var a) ? a : null;
}
}

388
tests/AcDream.Core.Tests/Physics/AnimationSequencerCutoverTraceTests.cs Normal file
View file

@ -0,0 +1,388 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Numerics;
using System.Text;
using AcDream.Core.Physics;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using Xunit;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
namespace AcDream.Core.Tests.Physics;
// ─────────────────────────────────────────────────────────────────────────────
// R2-Q4 adapter-cutover trace conformance (r2-port-plan.md §3 Q4).
//
// These scenarios were CAPTURED against the PRE-cutover adapter (the legacy
// SetCycle/PlayAction with the fast-path, Fix B, stop-anim fallback, and G17
// gate) at commit aa65990a, then replayed against the PerformMovement-hosted
// adapter. Golden strings assert the post-Q4 behavior; every place the cutover
// INTENTIONALLY changed the outcome carries an `EXPECTED-DIFF(Q4)` comment
// with the pre-cutover value and the retail rationale. Everything without an
// annotation is byte-identical across the cutover — that is the parity bar.
//
// Snapshot format (Describe): comma-joined node list in queue order, each node
// `<animIdHex>@<framerate:F1>` with suffix `*` = first_cyclic, `^` = curr_anim;
// then ` | frame=<F1> vel=(x,y,z F2) om=(x,y,z F2) style=<X8> motion=<X8>
// mod=<F2>`.
// ─────────────────────────────────────────────────────────────────────────────
internal sealed class TraceLoader : IAnimationLoader
{
private readonly Dictionary<uint, Animation> _anims = new();
private readonly Dictionary<Animation, uint> _ids = new();
public void Register(uint id, Animation anim)
{
_anims[id] = anim;
_ids[anim] = id;
}
public Animation? LoadAnimation(uint id) =>
_anims.TryGetValue(id, out var a) ? a : null;
public uint IdOf(Animation anim) => _ids.TryGetValue(anim, out var id) ? id : 0;
}
public sealed class AnimationSequencerCutoverTraceTests
{
// Styles (FULL command words, as GameWindow passes them).
private const uint NC = 0x8000003Du; // NonCombat
private const uint Style2 = 0x8000004Cu; // synthetic second style
// Substates / cycles.
private const uint Ready = 0x41000003u;
private const uint Walk = 0x45000005u;
private const uint WalkBack = 0x45000006u;
private const uint Run = 0x44000007u;
private const uint Falling = 0x40000015u;
// Action / modifier class ids.
private const uint EmoteAction = 0x10000062u;
private const uint TurnMod = 0x6500000Du;
// Anim resource ids.
private const uint ReadyAnim = 0x100u; // 4 frames
private const uint WalkAnim = 0x101u; // 6 frames
private const uint RunAnim = 0x102u; // 6 frames
private const uint ReadyToWalkLink = 0x103u; // 2 frames
private const uint ReadyToRunLink = 0x104u; // 2 frames
private const uint WalkToReadyLink = 0x105u; // 3 frames
private const uint RunToReadyLink = 0x108u; // 3 frames
private const uint TurnModAnim = 0x109u; // 2 frames
private const uint ReadyToStyle2Link = 0x10Au; // 2 frames
private const uint ReadyToEmoteLink = 0x10Bu; // 5 frames
private const uint FallAnim = 0x10Cu; // 4 frames
private const uint Style2ReadyAnim = 0x107u; // 4 frames
private static Animation MakeAnim(int numFrames, int numParts = 1)
{
var anim = new Animation();
for (int f = 0; f < numFrames; f++)
{
var pf = new AnimationFrame((uint)numParts);
for (int p = 0; p < numParts; p++)
pf.Frames.Add(new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static MotionData MakeMd(uint animId, float framerate = 30f,
Vector3? velocity = null, Vector3? omega = null)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData
{
AnimId = qid,
LowFrame = 0,
HighFrame = -1,
Framerate = framerate,
});
if (velocity is { } v)
{
md.Velocity = v;
md.Flags |= DatReaderWriter.Enums.MotionDataFlags.HasVelocity;
}
if (omega is { } o)
{
md.Omega = o;
md.Flags |= DatReaderWriter.Enums.MotionDataFlags.HasOmega;
}
return md;
}
private static void AddLink(MotionTable mt, uint style, uint from, uint to, MotionData md)
{
int outer = (int)((style << 16) | (from & 0xFFFFFFu));
if (!mt.Links.TryGetValue(outer, out var cmd))
{
cmd = new MotionCommandData();
mt.Links[outer] = cmd;
}
cmd.MotionData[(int)to] = md;
}
private static (Setup, MotionTable, TraceLoader) BuildFixture()
{
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(Vector3.One);
var loader = new TraceLoader();
loader.Register(ReadyAnim, MakeAnim(4));
loader.Register(WalkAnim, MakeAnim(6));
loader.Register(RunAnim, MakeAnim(6));
loader.Register(ReadyToWalkLink, MakeAnim(2));
loader.Register(ReadyToRunLink, MakeAnim(2));
loader.Register(WalkToReadyLink, MakeAnim(3));
loader.Register(RunToReadyLink, MakeAnim(3));
loader.Register(TurnModAnim, MakeAnim(2));
loader.Register(ReadyToStyle2Link, MakeAnim(2));
loader.Register(ReadyToEmoteLink, MakeAnim(5));
loader.Register(FallAnim, MakeAnim(4));
loader.Register(Style2ReadyAnim, MakeAnim(4));
var mt = new MotionTable
{
DefaultStyle = (DRWMotionCommand)NC,
};
mt.StyleDefaults[(DRWMotionCommand)NC] = (DRWMotionCommand)Ready;
mt.StyleDefaults[(DRWMotionCommand)Style2] = (DRWMotionCommand)Ready;
int CycleKey(uint style, uint substate) => (int)((style << 16) | (substate & 0xFFFFFFu));
mt.Cycles[CycleKey(NC, Ready)] = MakeMd(ReadyAnim);
mt.Cycles[CycleKey(NC, Walk)] = MakeMd(WalkAnim, velocity: new Vector3(0f, 3.12f, 0f));
mt.Cycles[CycleKey(NC, Run)] = MakeMd(RunAnim, velocity: new Vector3(0f, 4.0f, 0f));
mt.Cycles[CycleKey(NC, Falling)] = MakeMd(FallAnim);
mt.Cycles[CycleKey(Style2, Ready)] = MakeMd(Style2ReadyAnim);
AddLink(mt, NC, Ready, Walk, MakeMd(ReadyToWalkLink));
AddLink(mt, NC, Ready, Run, MakeMd(ReadyToRunLink));
AddLink(mt, NC, Walk, Ready, MakeMd(WalkToReadyLink));
AddLink(mt, NC, Run, Ready, MakeMd(RunToReadyLink));
AddLink(mt, NC, Ready, EmoteAction, MakeMd(ReadyToEmoteLink));
AddLink(mt, NC, Ready, Style2, MakeMd(ReadyToStyle2Link));
// Modifier: styled key (styleMasked<<16 | low24).
int modKey = (int)((NC << 16) | (TurnMod & 0xFFFFFFu));
mt.Modifiers[modKey] = MakeMd(TurnModAnim, omega: new Vector3(0f, 0f, 1.5f));
return (setup, mt, loader);
}
private static string Describe(AnimationSequencer seq, TraceLoader loader)
{
var core = seq.Core;
var sb = new StringBuilder();
bool first = true;
for (var n = core.AnimList.First; n is not null; n = n.Next)
{
if (!first) sb.Append(',');
first = false;
uint id = n.Value.Anim is null ? 0u : loader.IdOf(n.Value.Anim);
sb.Append($"{id:X}@{n.Value.Framerate:F1}");
if (ReferenceEquals(n, core.FirstCyclicNode)) sb.Append('*');
if (ReferenceEquals(n, core.CurrAnimNode)) sb.Append('^');
}
var v = core.Velocity;
var o = core.Omega;
sb.Append($" | frame={core.FrameNumber:F1}");
sb.Append($" vel=({v.X:F2},{v.Y:F2},{v.Z:F2})");
sb.Append($" om=({o.X:F2},{o.Y:F2},{o.Z:F2})");
sb.Append($" style={seq.CurrentStyle:X8} motion={seq.CurrentMotion:X8} mod={seq.CurrentSpeedMod:F2}");
return sb.ToString();
}
private static AnimationSequencer NewSeq(out TraceLoader loader)
{
var (setup, mt, l) = BuildFixture();
loader = l;
return new AnimationSequencer(setup, mt, l);
}
// ── Scenarios ───────────────────────────────────────────────────────────
[Fact]
public void S1_SpawnIdle()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
Assert.Equal(
"100@30.0*^ | frame=0.0 vel=(0.00,0.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=41000003 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S2_IdleToWalk_LinkThenCycle()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
Assert.Equal(
"103@30.0^,101@30.0* | frame=0.0 vel=(0.00,3.12,0.00) om=(0.00,0.00,0.00) style=8000003D motion=45000005 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S2b_LinkDrain_FiresOneAnimDoneSentinel()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
// Drain the 2-frame link at fr=30: 2 frames / 30fps < 0.1s. Advance
// enough to cross into the cycle.
int animDone = 0;
for (int i = 0; i < 10; i++)
{
seq.Advance(0.02f);
foreach (var h in seq.ConsumePendingHooks())
if (h is DatReaderWriter.Types.AnimationDoneHook)
animDone++;
}
Assert.Equal(1, animDone);
}
[Fact]
public void S3_WalkToRun_CyclicToCyclic()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
seq.SetCycle(NC, Run, 2.0f);
// EXPECTED-DIFF(Q4): pre-cutover Fix B stripped every link leaving
// "102@60.0*^". The verbatim GetObjectSequence (Branch 2, no direct
// Walk->Run link in this fixture) routes the DOUBLE-HOP: Walk->Ready
// settle (105 at the OLD substate mod) + Ready->Run windup (104 at
// the new speed) + the Run cycle; the old Ready->Walk link (103)
// keeps draining first (pending-queue discipline). Rapid same-motion
// re-issues now collapse via remove_redundant_links (the retail
// Fix B), not an adapter locomotion special case.
Assert.Equal(
"103@30.0^,105@30.0,104@60.0,102@60.0* | frame=0.0 vel=(0.00,8.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=44000007 mod=2.00",
Describe(seq, loader));
}
[Fact]
public void S4_RunReSpeed_FastPath()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
seq.SetCycle(NC, Run, 2.0f);
seq.SetCycle(NC, Run, 2.5f);
// EXPECTED-DIFF(Q4): inherits S3's double-hop list; the re-speed
// itself is the verbatim Branch-2 fast path (change_cycle_speed
// scales ONLY first_cyclic..tail: 102 60->75; links untouched;
// velocity via subtract_motion(2.0)+combine_motion(2.5)).
Assert.Equal(
"103@30.0^,105@30.0,104@60.0,102@75.0* | frame=0.0 vel=(0.00,10.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=44000007 mod=2.50",
Describe(seq, loader));
}
[Fact]
public void S5_WalkBackward_RemapNegativeSpeed()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, WalkBack, 1.0f);
// Node list BYTE-IDENTICAL to pre-cutover: the reversed-key get_link
// resolves the Walk->Ready link (0x105) played in reverse (fr=-19.5 =
// 30 x -0.65 BackwardsFactor); cursor at the reverse starting frame
// (HighFrame+1 = 3).
// EXPECTED-DIFF(Q4), mirrors only: CurrentMotion now reads the
// POST-adjust_motion substate (45000005, was 45000006) and
// CurrentSpeedMod the signed mod (-0.65, was 1.00) - MotionState owns
// the state and retail's interpreted state is post-adjustment. The
// om=(-0.00,...) is IEEE negative zero from add_motion's
// zero-omega x negative-speed multiply (numerically equal to 0).
Assert.Equal(
"105@-19.5^,101@-19.5* | frame=3.0 vel=(0.00,-2.03,0.00) om=(-0.00,-0.00,-0.00) style=8000003D motion=45000005 mod=-0.65",
Describe(seq, loader));
}
[Fact]
public void S6_WalkBackToReady_StopSettleFallback()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, WalkBack, 1.0f);
seq.SetCycle(NC, Ready, 1.0f);
// EXPECTED-DIFF(Q4): pre-cutover the stop-anim low-byte fallback
// re-keyed the settle as 105@30 (forward). The verbatim get_link
// (SubstateMod=-0.65 routes the REVERSED-key branch) resolves the
// Ready->Walk windup (103) played in REVERSE (fr=-30) - retail's
// actual backward-walk settle. The old reversed link (105@-19.5,
// mid-drain) still drains first, unchanged from pre-cutover.
Assert.Equal(
"105@-19.5^,103@-30.0,100@30.0* | frame=3.0 vel=(0.00,0.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=41000003 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S7_EmoteAction_MidReady()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.PlayAction(EmoteAction, 1.0f);
Assert.Equal(
"10B@30.0^,100@30.0* | frame=0.0 vel=(0.00,0.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=41000003 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S8_LeaveGroundLinkStrip_FallingEngagesInstantly()
{
// EXPECTED-DIFF(R3-W4): the K-fix18 skipTransitionLink flag is
// DELETED. The instant-Falling engage is retail's own mechanism:
// MotionInterpreter.LeaveGround (0x00528b00) fires the
// RemoveLinkAnimations seam — bound to this sequencer's
// RemoveAllLinkAnimations (CPhysicsObj::RemoveLinkAnimations
// 0x0050fe20 → CSequence::remove_all_link_animations) — after the
// Falling dispatch. Same final state the flag produced.
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
seq.SetCycle(NC, Falling, 1.0f);
seq.RemoveAllLinkAnimations(); // = LeaveGround's seam firing
Assert.Equal(
"10C@30.0*^ | frame=0.0 vel=(0.00,0.00,0.00) om=(0.00,0.00,0.00) style=8000003D motion=40000015 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S9_TurnModifier()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(NC, Walk, 1.0f);
seq.PlayAction(TurnMod, 1.0f);
// EXPECTED-DIFF(Q4): pre-cutover PlayAction INSERTED the modifier's
// anim (109) before the cyclic tail - an acdream invention. Retail
// Branch 4 is PHYSICS-ONLY combine_motion (the AP-73 mechanism): the
// walk cycle's frames are untouched, the modifier contributes omega
// (0,0,1.5) and is tracked on the MotionState modifier stack.
Assert.Equal(
"103@30.0^,101@30.0* | frame=0.0 vel=(0.00,3.12,0.00) om=(0.00,0.00,1.50) style=8000003D motion=45000005 mod=1.00",
Describe(seq, loader));
}
[Fact]
public void S10_StyleChange()
{
var seq = NewSeq(out var loader);
seq.SetCycle(NC, Ready);
seq.SetCycle(Style2, Ready, 1.0f);
// EXPECTED-DIFF(Q4): pre-cutover switched cycles bare ("107@30.0*^").
// GetObjectSequence Branch 1 (style-change) plays the cross-style
// entry link (10A = Ready->Style2) before the target style's default
// cycle - retail's stance-transition animation.
Assert.Equal(
"10A@30.0^,107@30.0* | frame=0.0 vel=(0.00,0.00,0.00) om=(0.00,0.00,0.00) style=8000004C motion=41000003 mod=1.00",
Describe(seq, loader));
}
}

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

@ -224,32 +224,16 @@ public sealed class AnimationSequencerTests
}
[Fact]
public void HasCycle_PresentInTable_ReturnsTrue()
public void SetCycle_MissingCycle_LeavesSequenceAndStateUntouched()
{
// Phase L.1c followup (2026-04-28): regression guard for
// "torso on the ground" — caller (GameWindow MoveTo path) needs
// to query the table before SetCycle to avoid the
// ClearCyclicTail wipe on a missing cycle.
const uint Style = 0x003Cu; // HandCombat
const uint Motion = 0x0003u; // Ready
const uint AnimId = 0x03000001u;
var setup = Fixtures.MakeSetup(2);
var mt = Fixtures.MakeMtable(Style, Motion, AnimId);
var loader = new FakeLoader();
loader.Register(AnimId, Fixtures.MakeTwoFrameAnim(2, Vector3.Zero, Quaternion.Identity, Vector3.Zero, Quaternion.Identity));
var seq = new AnimationSequencer(setup, mt, loader);
// Caller passes the SAME shape SetCycle expects: full style with
// class byte (0x80000000) and full motion (0x40000000 / 0x10000000).
Assert.True(seq.HasCycle(0x8000003Cu, 0x41000003u));
}
[Fact]
public void HasCycle_MissingFromTable_ReturnsFalse()
{
const uint Style = 0x003Cu;
const uint ReadyMotion = 0x0003u;
// R2-Q5: HasCycle + the caller-side fallback chains are DELETED.
// The retail mechanism replacing the L.1c "torso on the ground"
// guard: GetObjectSequence (0x00522860) checks the cycle BEFORE any
// list surgery — a missing cycle leaves the sequence AND MotionState
// untouched, so whatever was playing (here the initialize_state
// default) keeps playing.
const uint Style = 0x8000003Cu; // HandCombat (full command)
const uint ReadyMotion = 0x41000003u;
const uint AnimId = 0x03000001u;
var setup = Fixtures.MakeSetup(2);
@ -258,9 +242,17 @@ public sealed class AnimationSequencerTests
loader.Register(AnimId, Fixtures.MakeTwoFrameAnim(2, Vector3.Zero, Quaternion.Identity, Vector3.Zero, Quaternion.Identity));
var seq = new AnimationSequencer(setup, mt, loader);
// RunForward (0x44000007) is NOT in the table — caller should
// see false and fall back to a known motion (WalkForward / Ready).
Assert.False(seq.HasCycle(0x8000003Cu, 0x44000007u));
seq.InitializeState();
Assert.Equal(ReadyMotion, seq.CurrentMotion);
int nodesBefore = seq.QueueCount;
// RunForward (0x44000007) is NOT in the table — the dispatch fails
// and nothing changes (no cyclic-tail wipe, no state overwrite).
seq.SetCycle(Style, 0x44000007u);
Assert.Equal(ReadyMotion, seq.CurrentMotion);
Assert.Equal(nodesBefore, seq.QueueCount);
Assert.True(seq.HasCurrentNode);
}
[Fact]
@ -333,13 +325,21 @@ public sealed class AnimationSequencerTests
[Fact]
public void SetCycle_WithTransitionLink_PrependLinkFrames()
{
// Two animations: link (2 frames at Y=1) and cycle (4 frames at X=1).
const uint Style = 0x003Du;
const uint IdleMotion = 0x0003u;
const uint WalkMotion = 0x0005u;
// R2-Q4: GetObjectSequence gates Branch 2 (cyclic substates) on the
// 0x40000000 class bit and Branch 1 (style change) on the top bit —
// bare low-word ids like the pre-cutover 0x0003/0x0005 never satisfy
// those gates and the dispatch silently fails. Tag Style/IdleMotion/
// WalkMotion with their class bits (masking to the low 24 bits for
// the cycle/link key hash is unaffected — CMotionTable keys on
// `id & 0xFFFFFF`).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x40000003u;
const uint WalkMotion = 0x40000005u;
const uint IdleAnim = 0x03000012u;
const uint CycleAnim = 0x03000010u;
const uint LinkAnim = 0x03000011u;
var idleAnim = Fixtures.MakeAnim(1, 1, Vector3.Zero, Quaternion.Identity);
var cycleAnim = Fixtures.MakeAnim(4, 1, new Vector3(1, 0, 0), Quaternion.Identity);
var linkAnim = Fixtures.MakeAnim(2, 1, new Vector3(0, 1, 0), Quaternion.Identity);
@ -352,15 +352,26 @@ public sealed class AnimationSequencerTests
fromMotion: IdleMotion,
toMotion: WalkMotion,
linkAnimId: LinkAnim);
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0) —
// route it at IdleMotion (the state this test "was already playing"
// before priming) and give IdleMotion its own cycle so the real
// SetCycle(Style, IdleMotion) priming call below actually dispatches.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int idleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[idleKey] = Fixtures.MakeMotionData(IdleAnim, framerate: 30f);
var loader = new FakeLoader();
loader.Register(IdleAnim, idleAnim);
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
// Prime the sequencer as if it was already playing IdleMotion.
SetCurrentMotion(seq, Style, IdleMotion);
// Prime the sequencer as if it was already playing IdleMotion — a
// real SetCycle call now that CurrentStyle/CurrentMotion are
// read-only mirrors of MotionState (R2-Q4; reflection SetValue no
// longer works, "Property set method not found").
seq.SetCycle(Style, IdleMotion);
seq.SetCycle(Style, WalkMotion);
@ -382,9 +393,13 @@ public sealed class AnimationSequencerTests
// link's starting pose at the link→cycle boundary. Symptoms: door
// swing-open flap (frame 0 = closed); player run-stop twitch
// (frame 0 = mid-stride).
const uint Style = 0x003Du;
const uint IdleMotion = 0x0003u;
const uint WalkMotion = 0x0005u;
// R2-Q4: class-bit-tagged ids (GetObjectSequence gates Branch 1/2 on
// the 0x80000000/0x40000000 bits) — masking to the low 24 bits for
// the cycle/link key hash is unaffected.
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x40000003u;
const uint WalkMotion = 0x40000005u;
const uint IdleAnim = 0x03000082u;
const uint CycleAnim = 0x03000080u;
const uint LinkAnim = 0x03000081u;
@ -402,6 +417,7 @@ public sealed class AnimationSequencerTests
// Cycle anim: single frame at Y=0 (the "open" / "idle" rest pose).
var cycleAnim = Fixtures.MakeAnim(1, 1, new Vector3(0, 0, 0), Quaternion.Identity);
var idleAnim = Fixtures.MakeAnim(1, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = Fixtures.MakeMtable(
@ -412,13 +428,23 @@ public sealed class AnimationSequencerTests
toMotion: WalkMotion,
linkAnimId: LinkAnim,
framerate: 30f);
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0)
// — route it at IdleMotion (the state we prime through below) with
// its own cycle so the priming SetCycle call actually dispatches.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int idleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[idleKey] = Fixtures.MakeMotionData(IdleAnim, framerate: 30f);
var loader = new FakeLoader();
loader.Register(IdleAnim, idleAnim);
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
SetCurrentMotion(seq, Style, IdleMotion);
// Prime the sequencer as if it was already playing IdleMotion — a
// real SetCycle call (reflection SetValue no longer works against
// the now-read-only CurrentStyle/CurrentMotion mirrors).
seq.SetCycle(Style, IdleMotion);
seq.SetCycle(Style, WalkMotion);
// Advance to _framePosition ≈ 2.5 — past the last integer frame (2)
@ -440,53 +466,71 @@ public sealed class AnimationSequencerTests
[Fact]
public void SetCycle_StopFromWalkBackward_FallsBackToWalkForwardStopLink()
{
// Stop-anim asymmetry: the Humanoid motion table only authors a
// "stop walking" link under WalkForward (low byte 0x05). Stopping
// from WalkBackward (0x06) without a fallback returns null linkData
// and the cycle snaps to Ready with no settle blend. Fix: when the
// primary GetLink lookup fails, retry with WalkBackward's low byte
// remapped to WalkForward.
const uint Style = 0x003Du;
const uint WalkForwardCmd = 0x0005u;
const uint WalkBackCmd = 0x0006u;
const uint ReadyCmd = 0x0003u;
// R2-Q4 EXPECTED-DIFF (mirrors AnimationSequencerCutoverTraceTests.
// S6_WalkBackToReady_StopSettleFallback): the pre-cutover adapter had
// an invented "stop-anim low-byte fallback" that re-keyed a
// WalkForward->Ready link when a WalkBackward->Ready lookup missed.
// Retail has no such fallback — CMotionTable.GetLink's verbatim
// reversed-key branch (Q0-pins A1) does the real job: adjust_motion
// remaps WalkBackward to WalkForward with a NEGATIVE SubstateMod, so
// stopping from it drives GetLink's "either speed negative -> swapped
// keys" path, which resolves the link stored FROM the style default
// (Ready) TO WalkForward and plays it IN REVERSE (the Ready->Walk
// windup run backward as a settle). The fixture below stores that
// link under Links[(style,Ready)][WalkForward] — the opposite
// direction from the old WalkForward->Ready fallback entry — because
// that's the key GetLink's reversed branch actually probes.
const uint Style = 0x8000003Du;
const uint WalkForwardCmd = 0x40000005u;
const uint WalkBackCmd = 0x40000006u;
const uint ReadyCmd = 0x40000003u;
const uint CycleAnim = 0x03000090u; // Ready cycle (Y=0)
const uint LinkAnim = 0x03000091u; // stop-link (Y=7)
const uint LinkAnim = 0x03000091u; // Ready->Walk windup (Y=7), played reversed as the settle
var cycleAnim = Fixtures.MakeAnim(1, 1, new Vector3(0, 0, 0), Quaternion.Identity);
var linkAnim = Fixtures.MakeAnim(4, 1, new Vector3(0, 7, 0), Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
// Table: Ready cycle + WalkForward→Ready link. NO WalkBackward→Ready link.
// Table: Ready cycle + Ready->WalkForward windup link (probed
// REVERSED by GetLink's swapped-key branch when settling out of a
// negative-SubstateMod substate). No forward WalkBackward cycle is
// needed — adjust_motion remaps WalkBackward to WalkForward with a
// negated + BackwardsFactor-scaled speed before dispatch ever sees it.
var mt = Fixtures.MakeMtable(
style: Style,
motion: ReadyCmd,
cycleAnimId: CycleAnim,
fromMotion: WalkForwardCmd,
toMotion: ReadyCmd,
fromMotion: ReadyCmd,
toMotion: WalkForwardCmd,
linkAnimId: LinkAnim,
framerate: 30f);
// WalkForward also needs a cycle — adjust_motion's WalkBackward remap
// dispatches WalkForward's cycle (with the negated/scaled speed) as
// part of entering "backward" motion below.
int walkKey = (int)((Style << 16) | (WalkForwardCmd & 0xFFFFFFu));
mt.Cycles[walkKey] = Fixtures.MakeMotionData(CycleAnim, framerate: 30f);
var loader = new FakeLoader();
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
// Simulate "we were walking backward" — substate = WalkBackward,
// substateSpeed = +1 (the original speedMod stored by SetCycle).
SetCurrentMotion(seq, Style, WalkBackCmd);
// Enter WalkBackward for real — SetCycle's adjust_motion head remaps
// this to WalkForward with SubstateMod = -0.65 (BackwardsFactor),
// which is what makes the SUBSEQUENT stop-to-Ready call route
// GetLink's reversed-key branch.
seq.SetCycle(Style, WalkBackCmd, 1.0f);
seq.SetCycle(Style, ReadyCmd);
// Advance a tiny dt — should land on link frame 0 (Y=7), not the
// cycle (Y=0). Without the fallback, linkData is null, only the
// Ready cycle is enqueued, and we read Y=0 immediately.
// Advance a tiny dt — should land on the reversed windup link
// (Y=7), not the Ready cycle (Y=0).
var transforms = seq.Advance(0.001f);
Assert.Single(transforms);
Assert.True(transforms[0].Origin.Y > 5f,
$"Stop-from-backward should fall back to WalkForward→Ready link "
+ $"(expect Y≈7 from link); got Y={transforms[0].Origin.Y} "
+ "(Y=0 means linkData was null and we snapped to Ready cycle).");
$"Stop-from-backward should resolve GetLink's reversed-key branch "
+ $"(expect Y≈7 from the reversed windup link); got Y={transforms[0].Origin.Y} "
+ "(Y=0 means the link didn't resolve and we snapped to the Ready cycle).");
}
[Fact]
@ -581,10 +625,14 @@ public sealed class AnimationSequencerTests
// with negated speed, so the animation plays in reverse.
// We verify this by checking CurrentMotion is still TurnLeft (the
// original command), but the sequencer internally uses TurnRight's anim.
// R2-Q4: Style needs the 0x80000000 top bit and TurnRight/TurnLeft the
// 0x40000000 cycle-class bit — GetObjectSequence's entry/branch gates
// (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity) test the
// FULL command word, not just the low 16 bits adjust_motion remaps.
const uint Style = 0x003Du; // NonCombat
const uint TurnRight = 0x0045000Du; // bit pattern for TurnRight in NonCombat
const uint TurnLeft = 0x0045000Eu; // bit pattern for TurnLeft
const uint Style = 0x8000003Du; // NonCombat
const uint TurnRight = 0x4045000Du; // bit pattern for TurnRight in NonCombat
const uint TurnLeft = 0x4045000Eu; // bit pattern for TurnLeft
const uint AnimId = 0x03000050u;
// 4-frame animation; each frame has a distinct Z-origin so we can tell
@ -600,6 +648,11 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0)
// — route the default straight at TurnRight (the only cycle this
// fixture defines) so initialize_state's baseline install succeeds
// and state.Style/Substate are non-zero before the explicit dispatch.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)TurnRight;
// Register TurnRight cycle (adjusted motion, not TurnLeft).
int cycleKey = (int)((Style << 16) | (TurnRight & 0xFFFFFFu));
@ -611,29 +664,47 @@ public sealed class AnimationSequencerTests
var seq = new AnimationSequencer(setup, mt, loader);
seq.SetCycle(Style, TurnLeft, speedMod: 1f);
// CurrentMotion should record the original TurnLeft command.
Assert.Equal(TurnLeft, seq.CurrentMotion);
// R2-Q4 EXPECTED-DIFF (mirrors AnimationSequencerCutoverTraceTests.
// S5_WalkBackward_RemapNegativeSpeed's "mirrors only" diff):
// CurrentMotion is now a GET-ONLY mirror of MotionState.Substate,
// and MotionState owns the POST-adjust_motion substate — retail's
// interpreted state IS the adjusted one (TurnRight played reversed),
// not the raw TurnLeft the caller passed in. Pre-cutover the adapter
// kept its own separate CurrentMotion field and never overwrote it
// with the adjusted id; that field no longer exists.
Assert.Equal(TurnRight, seq.CurrentMotion);
Assert.Equal(-1f, seq.CurrentSpeedMod, 3);
// Without swap: StartFrame=0, EndFrame=3 (original range preserved).
// GetStartFramePosition for negative speed = (EndFrame+1)-eps = (3+1)-eps ≈ 3.99999.
// The cursor starts near the HIGH end and counts DOWN toward StartFrame(=0).
// R1-P5 (2026-07-02): pre-cutover this pinned the ACE-fabricated
// epsilon boundary ((EndFrame+1)-eps ~= 3.99999). Retail's
// AnimSequenceNode.GetStartingFrame (0x00525c80) returns a BARE INT
// for reverse playback: HighFrame + 1 (gap map G1 — "NO epsilon").
// LowFrame=0, HighFrame=3 (no swap at append time; the swap only
// happens inside MultiplyFramerate for an in-place resign, which
// this path doesn't take), so the retail-exact start position is
// exactly 4.0, not "near but under" 4.0. The cursor starts at the
// boundary and counts DOWN toward LowFrame(=0) on the next Advance.
double pos = GetFramePosition(seq);
Assert.True(pos > 3.9 && pos < 4.0,
$"Expected framePosition near 3.99999 (reverse start near EndFrame+1) but got {pos}");
Assert.True(pos == 4.0,
$"Expected framePosition == 4 (bare-int reverse start = HighFrame+1, "
+ $"retail AnimSequenceNode.GetStartingFrame 0x00525c80 has NO epsilon — G1); got {pos}");
}
[Fact]
public void Advance_NegativeSpeed_FramePositionDecreases()
{
// Verify that a cycle loaded with negative framerate counts downward.
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
// R2-Q4: retail-mandatory StyleDefaults + the 0x40000000 cycle-class
// bit on Motion (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000003u;
const uint AnimId = 0x03000060u;
var anim = Fixtures.MakeAnim(8, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
// Register cycle with NEGATIVE framerate to simulate reverse playback.
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
@ -719,9 +790,11 @@ public sealed class AnimationSequencerTests
{
// Queue: [linkNode (2 frames, 10fps, non-looping)] → [cycleNode (4 frames, looping)]
// Advance enough to exhaust the link node, then verify we're in the cycle.
const uint Style = 0x003Du;
const uint IdleMotion = 0x0003u;
const uint WalkMotion = 0x0005u;
// R2-Q4: class-bit-tagged ids (see SetCycle_WithTransitionLink_PrependLinkFrames).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x40000003u;
const uint WalkMotion = 0x40000005u;
const uint IdleAnim = 0x03000082u;
const uint CycleAnim = 0x03000080u;
const uint LinkAnim = 0x03000081u;
@ -729,6 +802,7 @@ public sealed class AnimationSequencerTests
var linkAnim = Fixtures.MakeAnim(2, 1, new Vector3(0, 5, 0), Quaternion.Identity);
// Cycle anim: 4 frames, X=9 (distinct marker).
var cycleAnim = Fixtures.MakeAnim(4, 1, new Vector3(9, 0, 0), Quaternion.Identity);
var idleAnim = Fixtures.MakeAnim(1, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = Fixtures.MakeMtable(
@ -739,13 +813,22 @@ public sealed class AnimationSequencerTests
toMotion: WalkMotion,
linkAnimId: LinkAnim,
framerate: 10f);
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0)
// — route it at IdleMotion with its own cycle so the priming
// SetCycle call below actually dispatches.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int idleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[idleKey] = Fixtures.MakeMotionData(IdleAnim, framerate: 10f);
var loader = new FakeLoader();
loader.Register(IdleAnim, idleAnim);
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
SetCurrentMotion(seq, Style, IdleMotion);
// Prime as if already playing IdleMotion — real SetCycle call
// (reflection SetValue no longer works, see WithTransitionLink test).
seq.SetCycle(Style, IdleMotion);
seq.SetCycle(Style, WalkMotion);
// Link node is 2 frames at 10fps → 0.2s to exhaust.
@ -916,8 +999,11 @@ public sealed class AnimationSequencerTests
public void Advance_ForwardHookDoesNotFire_OnReversePlayback()
{
// A hook tagged Direction.Forward should NOT fire when playback is reversed.
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
// R2-Q4: class-bit-tagged ids + retail-mandatory StyleDefaults — the bare
// ids made this test pass VACUOUSLY (dispatch silently failed, no anim
// played, so "hook did not fire" held for the wrong reason).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000003u;
const uint AnimId = 0x03000103u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
@ -930,6 +1016,7 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData();
QualifiedDataId<Animation> qid = AnimId;
@ -944,7 +1031,10 @@ public sealed class AnimationSequencerTests
seq.ConsumePendingHooks();
// Reverse playback: cursor starts near frame 4 and counts down.
seq.Advance(0.15f);
// 0.25s at -10fps = -2.5 frames → crosses the 3→2 boundary, so the
// hooked frame IS reached (same advance as the Backward sibling test
// — the direction filter, not distance, is what's under test).
seq.Advance(0.25f);
var hooks = seq.ConsumePendingHooks();
// Forward-only hook on frame 2 should NOT fire on reverse playback.
@ -954,8 +1044,10 @@ public sealed class AnimationSequencerTests
[Fact]
public void Advance_BackwardHook_FiresOnReversePlayback()
{
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
// R2-Q4: retail-mandatory StyleDefaults + the 0x40000000 cycle-class
// bit on Motion (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000003u;
const uint AnimId = 0x03000104u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
@ -968,6 +1060,7 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData();
QualifiedDataId<Animation> qid = AnimId;
@ -990,13 +1083,17 @@ public sealed class AnimationSequencerTests
Assert.Contains(hooks, h => h is SoundHook sh && (uint)sh.Id == 0x0A000005u);
}
// ── PosFrames root motion (Phase E.1) ────────────────────────────────────
// ── PosFrames root motion (R1-P6: the wired Frame path, gap map G7) ───────
[Fact]
public void Advance_WithPosFrames_AccumulatesRootMotion()
public void Advance_WithRootMotionFrame_AccumulatesPosFrameDeltas()
{
// Animation with PosFrames flag and per-frame origin deltas should
// surface a non-zero root motion delta after Advance.
// R1-P6 (2026-07-02): root motion flows through retail's actual
// contract — CSequence::update(quantum, Frame*) (0x00525b80):
// every crossed integer frame combines the node's pos_frame into
// the caller-supplied Frame (update_internal 0x005255d0). The old
// adapter-side accumulator (ConsumeRootMotionDelta) is DELETED —
// this is the seam R6's per-tick order consumes.
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
const uint AnimId = 0x03000110u;
@ -1020,27 +1117,27 @@ public sealed class AnimationSequencerTests
var seq = new AnimationSequencer(setup, mt, loader);
seq.SetCycle(Style, Motion);
seq.ConsumeRootMotionDelta(); // clear
// Advance 0.25s → 2.5 frames → 2 crossings (0→1, 1→2) → 2 posFrame deltas applied.
seq.Advance(0.25f);
var (pos, _) = seq.ConsumeRootMotionDelta();
// Advance 0.25s @10fps → 2.5 frames → 2 crossings (0→1, 1→2), each
// combining +1 X of pos_frame origin into the supplied Frame.
var rootFrame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.Advance(0.25f, rootFrame);
// Each crossing adds +X origin → total X should be 2.
Assert.True(pos.X >= 1.8f && pos.X <= 2.2f,
$"Expected ~2.0 root motion X after 2 crossings, got {pos.X}");
// A subsequent consume with no advance should return zero (drained).
var (pos2, _) = seq.ConsumeRootMotionDelta();
Assert.Equal(Vector3.Zero, pos2);
Assert.True(rootFrame.Origin.X >= 1.8f && rootFrame.Origin.X <= 2.2f,
$"Expected ~2.0 root motion X after 2 crossings via the wired Frame, got {rootFrame.Origin.X}");
}
[Fact]
public void CurrentVelocity_ExposedFromMotionData_WhenHasVelocity()
{
// MotionData with HasVelocity flag should surface via CurrentVelocity.
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0) —
// without it, initialize_state's SetDefaultState fails, state.Style
// stays 0, and GetObjectSequence's entry guard rejects every
// dispatch. Route the default straight at Motion (the cycle this
// test cares about).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000003u;
const uint AnimId = 0x03000120u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
@ -1048,6 +1145,7 @@ public sealed class AnimationSequencerTests
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData
{
@ -1071,8 +1169,12 @@ public sealed class AnimationSequencerTests
[Fact]
public void CurrentVelocity_ScaledBySpeedMod()
{
const uint Style = 0x003Du;
const uint Motion = 0x0003u;
// R2-Q4: retail-mandatory StyleDefaults, and Motion needs its
// 0x40000000 cycle-class bit — the same-motion re-speed fast path
// (Branch 2, target==substate) still requires the class-bit gate to
// be reached in the first place.
const uint Style = 0x8000003Du;
const uint Motion = 0x40000003u;
const uint AnimId = 0x03000121u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
@ -1080,6 +1182,7 @@ public sealed class AnimationSequencerTests
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData
{
@ -1106,27 +1209,37 @@ public sealed class AnimationSequencerTests
// When a non-cyclic link node exhausts and we advance_to_next_animation,
// an AnimationDoneHook should be queued so consumers can react (e.g. UI
// wake-on-idle-complete).
const uint Style = 0x003Du;
const uint IdleMotion = 0x0003u;
const uint WalkMotion = 0x0005u;
// R2-Q4: class-bit-tagged ids (see SetCycle_WithTransitionLink_PrependLinkFrames).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x40000003u;
const uint WalkMotion = 0x40000005u;
const uint IdleAnim = 0x03000132u;
const uint CycleAnim = 0x03000130u;
const uint LinkAnim = 0x03000131u;
var linkAnim = Fixtures.MakeAnim(2, 1, Vector3.Zero, Quaternion.Identity);
var cycleAnim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
var idleAnim = Fixtures.MakeAnim(1, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = Fixtures.MakeMtable(
style: Style, motion: WalkMotion, cycleAnimId: CycleAnim,
fromMotion: IdleMotion, toMotion: WalkMotion, linkAnimId: LinkAnim,
framerate: 10f);
// R2-Q4: retail-mandatory StyleDefaults — route it at IdleMotion with
// its own cycle so the priming SetCycle call below actually dispatches.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int idleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[idleKey] = Fixtures.MakeMotionData(IdleAnim, framerate: 10f);
var loader = new FakeLoader();
loader.Register(IdleAnim, idleAnim);
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
SetCurrentMotion(seq, Style, IdleMotion);
// Prime as if already playing IdleMotion — real SetCycle call.
seq.SetCycle(Style, IdleMotion);
seq.SetCycle(Style, WalkMotion);
seq.ConsumePendingHooks();
@ -1144,8 +1257,11 @@ public sealed class AnimationSequencerTests
{
// A 10-frame cycle at 10 fps = 1.0s per loop. If we halve the playback
// rate (factor 0.5), advancing 1.0s should produce half a loop (5 frames).
const uint Style = 0x003Du;
const uint Motion = 0x0007u; // RunForward
// R2-Q4: Motion needs the 0x40000000 cycle-class bit — GetObjectSequence
// Branch 2 (and its same-motion fast re-speed path) never triggers on
// a bare low-word id (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000007u; // RunForward
const uint AnimId = 0x03000401u;
// Unique per-frame Z so we can tell where the cursor lands.
@ -1171,6 +1287,11 @@ public sealed class AnimationSequencerTests
Framerate = 10f,
});
mt.Cycles[cycleKey] = md;
// R2-Q4: the dispatch stack needs the retail-mandatory StyleDefaults
// entry (SetDefaultState 0x005230a0 requires StyleDefaults[DefaultStyle];
// GetObjectSequence refuses a zero style/substate). Real dat tables
// always carry it.
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
var loader = new FakeLoader();
loader.Register(AnimId, anim);
@ -1178,8 +1299,11 @@ public sealed class AnimationSequencerTests
var seq = new AnimationSequencer(setup, mt, loader);
seq.SetCycle(Style, Motion, speedMod: 1f);
// Halve the playback rate.
seq.MultiplyCyclicFramerate(0.5f);
// R2-Q4: halve the playback rate via the retail same-motion re-speed
// (GetObjectSequence Branch-2 fast path: change_cycle_speed +
// subtract_motion(old) + combine_motion(new), decomp §5) — the old
// MultiplyCyclicFramerate adapter composite is deleted.
seq.SetCycle(Style, Motion, speedMod: 0.5f);
// 10 frames at 5 fps = 2.0s per loop. Advance 1.0s → cursor ~= frame 5.
seq.Advance(1.0f);
@ -1187,7 +1311,8 @@ public sealed class AnimationSequencerTests
Assert.Single(frames);
Assert.InRange(frames[0].Origin.Z, 4f, 6f);
// Velocity also scales: originally (0,4,0), now (0,2,0).
// Velocity also scales: originally (0,4,0), now (0,2,0)
// (subtract_motion(1.0) + combine_motion(0.5) = ×0.5 net).
Assert.Equal(2f, seq.CurrentVelocity.Y, 1);
}
@ -1196,8 +1321,11 @@ public sealed class AnimationSequencerTests
{
// Changing speed mid-cycle must NOT reset the frame cursor — the
// animation keeps playing from where it was, just faster/slower.
const uint Style = 0x003Du;
const uint Motion = 0x0007u;
// R2-Q4: class-bit-tagged ids — the bare ids made this test pass
// VACUOUSLY (dispatch silently failed; "cursor unchanged" held
// because nothing moved at all).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000007u;
const uint AnimId = 0x03000402u;
var anim = new Animation();
@ -1213,6 +1341,9 @@ public sealed class AnimationSequencerTests
mt.DefaultStyle = (DRWMotionCommand)Style;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
mt.Cycles[cycleKey] = Fixtures.MakeMotionData(AnimId, framerate: 10f);
// R2-Q4: retail-mandatory StyleDefaults entry (see
// MultiplyCyclicFramerate_HalvesPlaybackRate).
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
var loader = new FakeLoader();
loader.Register(AnimId, anim);
@ -1222,7 +1353,9 @@ public sealed class AnimationSequencerTests
seq.Advance(0.3f); // cursor ~ frame 3
double before = GetFramePosition(seq);
seq.MultiplyCyclicFramerate(2.0f);
// R2-Q4: mid-cycle re-speed via the retail Branch-2 fast path — must
// not touch the cursor (change_cycle_speed scales framerates only).
seq.SetCycle(Style, Motion, speedMod: 2.0f);
double after = GetFramePosition(seq);
Assert.Equal(before, after, 5);
@ -1235,8 +1368,10 @@ public sealed class AnimationSequencerTests
// NOT reset the cursor — it should call MultiplyCyclicFramerate to
// keep the run loop smooth (retail behavior for a mid-run RunRate
// broadcast). Mirror of ACE MotionTable.cs:132-139 fast-path.
const uint Style = 0x003Du;
const uint Motion = 0x0007u;
// R2-Q4: Motion needs the 0x40000000 cycle-class bit — see
// CurrentVelocity_ExposedFromMotionData_WhenHasVelocity.
const uint Style = 0x8000003Du;
const uint Motion = 0x40000007u;
const uint AnimId = 0x03000403u;
var anim = Fixtures.MakeAnim(10, 1, Vector3.Zero, Quaternion.Identity);
@ -1267,14 +1402,17 @@ public sealed class AnimationSequencerTests
// surface as (0,4,0) at speedMod=1.0, (0,6,0) at 1.5×, (0,2,0) at
// 0.5×. The dead-reckoning integrator in TickAnimations reads
// CurrentVelocity each tick, so this has to be accurate.
const uint Style = 0x003Du;
const uint Motion = 0x0007u;
// R2-Q4: retail-mandatory StyleDefaults + the 0x40000000 cycle-class
// bit on Motion (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Du;
const uint Motion = 0x40000007u;
const uint AnimId = 0x03000405u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData { Flags = MotionDataFlags.HasVelocity, Velocity = new Vector3(0, 4, 0) };
@ -1310,8 +1448,10 @@ public sealed class AnimationSequencerTests
{
// Guard: the new speed-path must not break the classic
// "identical call = no state change" behavior.
const uint Style = 0x003Du;
const uint Motion = 0x0007u;
// R2-Q4: Motion needs the 0x40000000 cycle-class bit — see
// CurrentVelocity_ExposedFromMotionData_WhenHasVelocity.
const uint Style = 0x8000003Du;
const uint Motion = 0x40000007u;
const uint AnimId = 0x03000404u;
var anim = Fixtures.MakeAnim(10, 1, Vector3.Zero, Quaternion.Identity);
@ -1338,14 +1478,17 @@ public sealed class AnimationSequencerTests
// A turn cycle with MotionData.Omega = (0, 0, 1) rad/sec (yaw)
// should surface as CurrentOmega = (0, 0, 1) after SetCycle.
// Scales with speedMod exactly like Velocity.
const uint Style = 0x003Du;
const uint Motion = 0x000Du; // TurnRight
// R2-Q4: retail-mandatory StyleDefaults + the 0x40000000 cycle-class
// bit on Motion (see CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Du;
const uint Motion = 0x4000000Du; // TurnRight
const uint AnimId = 0x03000701u;
var anim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)Motion;
int cycleKey = (int)((Style << 16) | (Motion & 0xFFFFFFu));
var md = new MotionData { Flags = MotionDataFlags.HasOmega, Omega = new Vector3(0, 0, 1.0f) };
@ -1374,19 +1517,27 @@ public sealed class AnimationSequencerTests
// reads the cycle's run-speed and moves the entity smoothly.
// Crucial: otherwise remote entities would stutter at every stance
// transition while the link plays.
const uint Style = 0x003Du;
const uint IdleMotion = 0x0003u;
const uint WalkMotion = 0x0005u;
// R2-Q4: class-bit-tagged ids (see SetCycle_WithTransitionLink_PrependLinkFrames).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x40000003u;
const uint WalkMotion = 0x40000005u;
const uint IdleAnim = 0x03000603u;
const uint CycleAnim = 0x03000601u;
const uint LinkAnim = 0x03000602u;
var cycleAnim = Fixtures.MakeAnim(4, 1, Vector3.Zero, Quaternion.Identity);
var linkAnim = Fixtures.MakeAnim(2, 1, Vector3.Zero, Quaternion.Identity);
var idleAnim = Fixtures.MakeAnim(1, 1, Vector3.Zero, Quaternion.Identity);
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)WalkMotion;
// R2-Q4: retail-mandatory StyleDefaults (SetDefaultState 0x005230a0)
// — route it at IdleMotion (the state we prime through below).
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int idleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[idleKey] = Fixtures.MakeMotionData(IdleAnim, framerate: 10f);
int cycleKey = (int)((Style << 16) | (WalkMotion & 0xFFFFFFu));
var cycleMd = new MotionData { Flags = MotionDataFlags.HasVelocity, Velocity = new Vector3(0, 3.12f, 0) };
@ -1404,11 +1555,13 @@ public sealed class AnimationSequencerTests
mt.Links[linkOuter] = linkCmdData;
var loader = new FakeLoader();
loader.Register(IdleAnim, idleAnim);
loader.Register(CycleAnim, cycleAnim);
loader.Register(LinkAnim, linkAnim);
var seq = new AnimationSequencer(setup, mt, loader);
SetCurrentMotion(seq, Style, IdleMotion);
// Prime as if already playing IdleMotion — real SetCycle call.
seq.SetCycle(Style, IdleMotion);
seq.SetCycle(Style, WalkMotion);
// We just enqueued [link(0)][cycle(3.12 forward)]. Current node is
@ -1432,7 +1585,11 @@ public sealed class AnimationSequencerTests
// An Action-class command (mask 0x10) resolves via the Links dict
// keyed by (style, currentSubstate) → motion. Example: a ThrustMed
// attack while in SwordCombat stance.
const uint Style = 0x003Eu; // SwordCombat
// R2-Q4: Style needs the 0x80000000 top bit + a StyleDefaults entry
// (SetDefaultState 0x005230a0 is retail-mandatory — GetObjectSequence
// refuses style==0/substate==0, see
// CurrentVelocity_ExposedFromMotionData_WhenHasVelocity).
const uint Style = 0x8000003Eu; // SwordCombat
const uint IdleMotion = 0x41000003u; // Ready
const uint ActionMotion = 0x10000058u; // ThrustMed (Action class)
const uint IdleAnimId = 0x03000501u;
@ -1445,6 +1602,7 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int cycleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[cycleKey] = Fixtures.MakeMotionData(IdleAnimId, framerate: 10f);
@ -1478,7 +1636,9 @@ public sealed class AnimationSequencerTests
// values followed by Ready. Retail keeps currState.Substate at Ready
// while the action link drains, so the Ready echo must not abort the
// in-flight swing.
const uint Style = 0x003Du;
// R2-Q4: Style needs the 0x80000000 top bit + a StyleDefaults entry
// (see PlayAction_Action_ResolvesFromLinksDict).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x41000003u;
const uint AttackMotion = 0x10000052u;
const uint IdleAnimId = 0x03000503u;
@ -1486,6 +1646,7 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable { DefaultStyle = (DRWMotionCommand)Style };
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int cycleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[cycleKey] = Fixtures.MakeMotionData(IdleAnimId, framerate: 10f);
@ -1513,11 +1674,19 @@ public sealed class AnimationSequencerTests
[Fact]
public void PlayAction_Modifier_ResolvesFromModifiersDict()
{
// A Modifier-class command (mask 0x20) — like Jump (0x2500003B) —
// resolves from the Modifiers dict, first with style-specific key
// then with unstyled fallback. Empirically: the modifier's anim
// plays on top of the current cycle.
const uint Style = 0x003Du;
// R2-Q4 EXPECTED-DIFF (mirrors AnimationSequencerCutoverTraceTests.
// S9_TurnModifier): a Modifier-class command (mask 0x20) — like Jump
// (0x2500003B) or a turn-while-moving overlay — resolves from the
// Modifiers dict, first with style-specific key then with unstyled
// fallback (CMotionTable.GetObjectSequence Branch 4). Pre-cutover the
// adapter INSERTED the modifier's anim before the cyclic tail — an
// acdream invention. Retail Branch 4 is PHYSICS-ONLY combine_motion:
// the base cycle's anim list is untouched (no new nodes), and the
// modifier contributes velocity/omega on top of the cycle's own,
// tracked on the MotionState modifier stack (AP-73 mechanism).
// R2-Q4: Style needs the 0x80000000 top bit + a StyleDefaults entry
// (see PlayAction_Action_ResolvesFromLinksDict).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x41000003u;
const uint JumpMotion = 0x2500003Bu; // Modifier class
const uint IdleAnimId = 0x03000510u;
@ -1529,12 +1698,18 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int cycleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[cycleKey] = Fixtures.MakeMotionData(IdleAnimId, framerate: 10f);
// Modifier: (Style, Jump)
// Modifier: (Style, Jump) — carries an omega contribution (a jump
// kick's angular nudge) rather than an anim payload, since Branch 4
// never touches the anim list.
int modKey = (int)((Style << 16) | (JumpMotion & 0xFFFFFFu));
mt.Modifiers[modKey] = Fixtures.MakeMotionData(JumpAnimId, framerate: 10f);
var jumpMd = Fixtures.MakeMotionData(JumpAnimId, framerate: 10f);
jumpMd.Flags = MotionDataFlags.HasOmega;
jumpMd.Omega = new Vector3(0f, 0f, 2.5f);
mt.Modifiers[modKey] = jumpMd;
var loader = new FakeLoader();
loader.Register(IdleAnimId, idleAnim);
@ -1542,12 +1717,15 @@ public sealed class AnimationSequencerTests
var seq = new AnimationSequencer(setup, mt, loader);
seq.SetCycle(Style, IdleMotion);
int queueBefore = seq.QueueCount;
seq.PlayAction(JumpMotion);
var fr = seq.Advance(0.01f);
Assert.Single(fr);
Assert.Equal(77f, fr[0].Origin.Z, 1);
// No anim nodes inserted — the queue is unchanged from before the
// modifier fired.
Assert.Equal(queueBefore, seq.QueueCount);
// The modifier's omega is combined onto the sequence's physics.
Assert.Equal(2.5f, seq.CurrentOmega.Z, 3);
}
[Fact]
@ -1557,7 +1735,9 @@ public sealed class AnimationSequencerTests
// Action(0x10) | ChatEmote(0x02) | Mappable(0x01). Because the
// Action bit is set, they route through the Links-dict lookup just
// like attacks. Verifies the class-bit math.
const uint Style = 0x003Du;
// R2-Q4: Style needs the 0x80000000 top bit + a StyleDefaults entry
// (see PlayAction_Action_ResolvesFromLinksDict).
const uint Style = 0x8000003Du;
const uint IdleMotion = 0x41000003u;
const uint WaveMotion = 0x13000087u;
const uint IdleAnimId = 0x03000520u;
@ -1569,6 +1749,7 @@ public sealed class AnimationSequencerTests
var setup = Fixtures.MakeSetup(1);
var mt = new MotionTable();
mt.DefaultStyle = (DRWMotionCommand)Style;
mt.StyleDefaults[(DRWMotionCommand)Style] = (DRWMotionCommand)IdleMotion;
int cycleKey = (int)((Style << 16) | (IdleMotion & 0xFFFFFFu));
mt.Cycles[cycleKey] = Fixtures.MakeMotionData(IdleAnimId, framerate: 10f);
@ -1624,14 +1805,27 @@ public sealed class AnimationSequencerTests
// ── Helpers ──────────────────────────────────────────────────────────────
/// <summary>Expose _framePosition (double) via reflection (test-only).</summary>
/// <summary>
/// Expose the core CSequence's FrameNumber via reflection (test-only).
/// R1-P5 rehost (2026-07-02): _framePosition lived directly on
/// AnimationSequencer pre-cutover; it now lives on the private _core
/// (CSequence) field as the public FrameNumber. Two-hop reflection:
/// grab _core, then its FrameNumber field.
/// </summary>
private static double GetFramePosition(AnimationSequencer seq)
{
var field = typeof(AnimationSequencer)
.GetField("_framePosition",
var coreField = typeof(AnimationSequencer)
.GetField("_core",
System.Reflection.BindingFlags.NonPublic |
System.Reflection.BindingFlags.Instance);
return field is null ? -1.0 : (double)field.GetValue(seq)!;
var core = coreField?.GetValue(seq);
if (core is null) return -1.0;
var frameNumberField = core.GetType()
.GetField("FrameNumber",
System.Reflection.BindingFlags.Public |
System.Reflection.BindingFlags.Instance);
return frameNumberField is null ? -1.0 : (double)frameNumberField.GetValue(core)!;
}
/// <summary>

12
tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs
View file

@ -699,8 +699,13 @@ public class BSPQueryTests
// Regression guard for the FULL-HIT case in the same Path 5 branch.
// Sphere overlaps wall AND moves INTO it: moveDot < 0, cull does NOT
// reject, pos_hits_sphere returns 1, Path 5 takes the `if (hit0)`
// branch. With engine=null we fall through to the slide fallback
// (SetCollisionNormal + SetSlidingNormal + return Slid).
// branch. With engine=null we fall through to the real slide
// (CSphere::slide_sphere via Transition.SlideSphereInternal). No
// contact plane is seeded on this bare Transition, so the slide takes
// the wall-only branch (project out the into-wall displacement,
// return Slid) — and per retail it must NOT write the sliding normal
// (#137 mechanism 2; validate_transition 0x0050ac21 is the only
// in-transition writer).
var (root, resolved) = BuildSingleWallBsp();
var transition = new Transition();
@ -731,6 +736,9 @@ public class BSPQueryTests
Assert.Equal(TransitionState.Slid, state);
Assert.True(transition.CollisionInfo.CollisionNormalValid,
"Full hit should set the collision normal (slide fallback).");
Assert.False(transition.CollisionInfo.SlidingNormalValid,
"find_collisions must not write the sliding normal — retail's " +
"only in-transition writer is validate_transition (#137).");
Assert.False(transition.SpherePath.NegPolyHit,
"Full hit should NOT also fire NegPolyHit — that's the near-miss " +
"path only. Retail at acclient_2013_pseudo_c.txt:0053a647 returns " +

287
tests/AcDream.Core.Tests/Physics/CylSphereFamilyTests.cs Normal file
View file

@ -0,0 +1,287 @@
using System;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
using Plane = System.Numerics.Plane;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// Conformance tests for the retail <c>CCylSphere</c> collision family port
/// (2026-07-05) — dispatcher <c>0x0053b440</c> + <c>step_sphere_down</c>
/// <c>0x0053a9b0</c> + <c>step_sphere_up</c> <c>0x0053b310</c> +
/// <c>land_on_cylinder</c> <c>0x0053b3d0</c>. Pseudocode:
/// docs/research/2026-07-05-ccylsphere-collision-family-pseudocode.md.
///
/// <para>
/// The driving repro: the Holtburg town-network portal platform (stab
/// 0xC0A9B465, Setup 0x020019E3) registers a WIDE LOW cylinder
/// (r=2.597 m, h=0.256 m). Retail steps a grounded player UP ONTO its flat
/// top; the pre-port approximation could only radial-slide, so the player
/// orbited the rim forever (launch-137-repro.log, 2026-07-05). These tests
/// pin the three retail behaviors the family provides: grounded
/// step-up-onto-top, too-tall side slide, and the airborne top landing.
/// Synthetic cylinders only — no dat dependency.
/// </para>
/// </summary>
public class CylSphereFamilyTests
{
private readonly ITestOutputHelper _out;
public CylSphereFamilyTests(ITestOutputHelper output) => _out = output;
private const uint TestLandblockId = 0xA9B40000u;
private const uint TestCellId = TestLandblockId | 0x0001u; // landcell (0,0)
private const float SphereRadius = 0.48f; // retail player capsule radius
private const float SphereHeight = 1.20f;
private const float StepUpHeight = 0.60f;
private const float StepDownHeight = 0.04f;
// The live platform's registered shape ([cyl-test] launch-137-repro.log).
private const float PlatformRadius = 2.597f;
private const float PlatformHeight = 0.256f;
/// <summary>
/// The portal-platform repro: a grounded player walking into the wide low
/// cylinder must STEP UP onto its flat top (retail
/// grounded branch → step_sphere_up → CTransition::step_up, whose
/// step-down probe lands via step_sphere_down's top-disc contact plane) —
/// not slide around the rim.
/// </summary>
[Fact]
public void Grounded_WalkIntoWideLowCylinder_StepsUpOntoTop()
{
var engine = BuildEngine(out _);
RegisterCylinder(engine, entityId: 0xCAFEu,
worldPos: new Vector3(12f, 14f, 0f),
radius: PlatformRadius, height: PlatformHeight);
var body = MakeGroundedBody(new Vector3(12f, 10.4f, 0f));
Vector3 pos = body.Position;
uint cellId = TestCellId;
bool grounded = true;
var perTick = new Vector3(0f, 0.10f, 0f);
for (int tick = 0; tick < 40; tick++)
{
var result = engine.ResolveWithTransition(
pos, pos + perTick, cellId,
SphereRadius, SphereHeight, StepUpHeight, StepDownHeight,
grounded,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide,
movingEntityId: 0);
body.Position = result.Position;
pos = result.Position;
cellId = result.CellId;
grounded = result.IsOnGround;
}
_out.WriteLine($"final pos=({pos.X:F3},{pos.Y:F3},{pos.Z:F3}) grounded={grounded}");
// Rim contact is at Y ≈ 14 − 2.597 − 0.48 = 10.92. Pre-port the player
// pinned there (Z stayed 0, Y never passed the rim). Post-port the
// player must be standing ON the platform top.
Assert.True(pos.Y > 11.5f,
$"Player must advance past the rim contact (pre-port it pinned at Y≈10.9); got Y={pos.Y:F3}");
Assert.True(MathF.Abs(pos.Z - PlatformHeight) < 0.05f,
$"Player must stand ON the platform top (Z≈{PlatformHeight:F3}); got Z={pos.Z:F3}");
Assert.True(grounded, "Player must remain grounded after stepping onto the platform");
}
/// <summary>
/// A tall thin cylinder (the Holtburg torch shape, r=0.2 h=2.2 — #149)
/// exceeds step_up_height: the grounded dead-center approach must NOT
/// step up and must NOT pass through — retail slides (dead-center the
/// crease projection degenerates to a hard stop).
/// </summary>
[Fact]
public void Grounded_WalkIntoTallCylinder_BlocksBeforeAxis()
{
var engine = BuildEngine(out _);
RegisterCylinder(engine, entityId: 0xF00Du,
worldPos: new Vector3(12f, 14f, 0f),
radius: 0.2f, height: 2.2f);
var body = MakeGroundedBody(new Vector3(12f, 12.6f, 0f));
Vector3 pos = body.Position;
uint cellId = TestCellId;
bool grounded = true;
var perTick = new Vector3(0f, 0.10f, 0f);
for (int tick = 0; tick < 30; tick++)
{
var result = engine.ResolveWithTransition(
pos, pos + perTick, cellId,
SphereRadius, SphereHeight, StepUpHeight, StepDownHeight,
grounded,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide,
movingEntityId: 0);
body.Position = result.Position;
pos = result.Position;
cellId = result.CellId;
grounded = result.IsOnGround;
}
_out.WriteLine($"final pos=({pos.X:F3},{pos.Y:F3},{pos.Z:F3}) grounded={grounded}");
// Surface contact at Y = 14 − 0.2 − 0.48 = 13.32.
Assert.True(pos.Y < 13.4f,
$"Tall cylinder must block the dead-center approach; got Y={pos.Y:F3}");
Assert.True(pos.Z < 0.5f,
$"Player must NOT end up on top of a 2.2 m cylinder; got Z={pos.Z:F3}");
}
/// <summary>
/// Airborne landing: a falling sphere over the platform center must land
/// ON the flat top (land_on_cylinder → Collide re-test → branch-5
/// exact-TOI rest + top-disc contact plane), not fall through to the
/// terrain inside the footprint.
/// </summary>
[Fact]
public void Airborne_FallOntoWideCylinder_LandsOnTop()
{
var engine = BuildEngine(out _);
RegisterCylinder(engine, entityId: 0xCAFEu,
worldPos: new Vector3(12f, 14f, 0f),
radius: PlatformRadius, height: PlatformHeight);
Vector3 pos = new(12f, 14f, 1.0f); // 1 m above the base, over the center
uint cellId = TestCellId;
bool grounded = false;
var perTick = new Vector3(0f, 0f, -0.25f);
int landedTick = -1;
for (int tick = 0; tick < 20; tick++)
{
var result = engine.ResolveWithTransition(
pos, pos + perTick, cellId,
SphereRadius, SphereHeight, StepUpHeight, StepDownHeight,
grounded,
body: null,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide,
movingEntityId: 0);
pos = result.Position;
cellId = result.CellId;
grounded = result.IsOnGround;
if (grounded) { landedTick = tick; break; }
}
_out.WriteLine($"final pos=({pos.X:F3},{pos.Y:F3},{pos.Z:F3}) grounded={grounded} landedTick={landedTick}");
Assert.True(grounded, "Falling sphere must land (ground) on the platform top");
Assert.True(MathF.Abs(pos.Z - PlatformHeight) < 0.05f,
$"Landing must rest on the top disc (Z≈{PlatformHeight:F3}), not the terrain " +
$"(Z=0) inside the footprint; got Z={pos.Z:F3}");
}
/// <summary>
/// Ethereal cylinders stay fully passable through the caller's Layer-2
/// override (pc:276961-276989) — branch 1 detects, the override clears.
/// Guards the #150 door behavior against the branch-1 change from the
/// old early-OK consume.
/// </summary>
[Fact]
public void Grounded_EtherealCylinder_IsFullyPassable()
{
var engine = BuildEngine(out _);
RegisterCylinder(engine, entityId: 0xE7E7u,
worldPos: new Vector3(12f, 14f, 0f),
radius: 0.2f, height: 2.2f,
state: 0x4u); // ETHEREAL_PS, non-static
var body = MakeGroundedBody(new Vector3(12f, 12.6f, 0f));
Vector3 pos = body.Position;
uint cellId = TestCellId;
bool grounded = true;
var perTick = new Vector3(0f, 0.10f, 0f);
for (int tick = 0; tick < 30; tick++)
{
var result = engine.ResolveWithTransition(
pos, pos + perTick, cellId,
SphereRadius, SphereHeight, StepUpHeight, StepDownHeight,
grounded,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide,
movingEntityId: 0);
body.Position = result.Position;
pos = result.Position;
cellId = result.CellId;
grounded = result.IsOnGround;
}
_out.WriteLine($"final pos=({pos.X:F3},{pos.Y:F3},{pos.Z:F3})");
Assert.True(pos.Y > 14.5f,
$"Ethereal cylinder must not block (walked from 12.6 to past the axis); got Y={pos.Y:F3}");
}
// ───────────────────────────────────────────────────────────────
// Harness
// ───────────────────────────────────────────────────────────────
private static PhysicsEngine BuildEngine(out PhysicsDataCache cache)
{
cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
// Flat terrain at Z=0 across the whole landblock.
var heights = new byte[81];
var heightTable = new float[256]; // all zero → terrain Z = 0
engine.AddLandblock(
landblockId: TestLandblockId,
terrain: new TerrainSurface(heights, heightTable),
cells: Array.Empty<CellSurface>(),
portals: Array.Empty<PortalPlane>(),
worldOffsetX: 0f,
worldOffsetY: 0f);
return engine;
}
private static void RegisterCylinder(PhysicsEngine engine, uint entityId,
Vector3 worldPos, float radius, float height, uint state = 0u)
{
engine.ShadowObjects.Register(
entityId, gfxObjId: 0u,
worldPos, Quaternion.Identity, radius,
worldOffsetX: 0f, worldOffsetY: 0f, landblockId: TestLandblockId,
collisionType: ShadowCollisionType.Cylinder,
cylHeight: height,
state: state);
}
private static PhysicsBody MakeGroundedBody(Vector3 position)
{
var floorPlane = new Plane(Vector3.UnitZ, 0f);
var floorVerts = new[]
{
new Vector3(-100f, -100f, 0f),
new Vector3( 100f, -100f, 0f),
new Vector3( 100f, 100f, 0f),
new Vector3(-100f, 100f, 0f),
};
return new PhysicsBody
{
Position = position,
Orientation = Quaternion.Identity,
ContactPlaneValid = true,
ContactPlane = floorPlane,
ContactPlaneCellId = TestCellId,
WalkablePolygonValid = true,
WalkablePlane = floorPlane,
WalkableVertices = floorVerts,
WalkableUp = Vector3.UnitZ,
TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable,
};
}
}

149
tests/AcDream.Core.Tests/Physics/FramesStationaryFallTests.cs Normal file
View file

@ -0,0 +1,149 @@
using System;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// Conformance tests for the retail frames_stationary_fall (fsf) round-trip
/// (validate_transition 0x0050aa70 pc:272625-656; transition seed pc:280940-947;
/// ACE Transition.cs:1029-1061). Retires the TS-3 stub.
///
/// <para>
/// The ladder detects a gravity mover that CANNOT advance for successive frames — the
/// #182 airborne "stuck in the falling animation" wedge (a jump into a monster crowd
/// where the near-horizontal creature normal blocks upward motion). fsf escalates
/// 0→1→2→3 while blocked and resets to 0 the moment the mover advances; at fsf≥3 an
/// upward contact plane is manufactured so the mover stands on the obstacle. The counter
/// round-trips across frames through the Stationary* transient bits (seed→ladder→writeback).
/// The velocity "bleed on block" (fsf>1 → v=0) lives in handle_all_collisions (see
/// <see cref="HandleAllCollisionsTests"/>); this file proves the counter itself.
/// </para>
/// </summary>
public class FramesStationaryFallTests
{
private readonly ITestOutputHelper _out;
public FramesStationaryFallTests(ITestOutputHelper output) => _out = output;
private const uint Lb = 0xA9B40000u;
private const uint Cell = Lb | 0x0001u;
private const float R = 0.48f, H = 1.835f, StepUp = 0.60f, StepDown = 0.04f;
private static PhysicsEngine BuildEngine()
{
var engine = new PhysicsEngine { DataCache = new PhysicsDataCache() };
engine.AddLandblock(
landblockId: Lb,
terrain: new TerrainSurface(new byte[81], new float[256]), // flat terrain at Z=0
cells: Array.Empty<CellSurface>(),
portals: Array.Empty<PortalPlane>(),
worldOffsetX: 0f, worldOffsetY: 0f);
return engine;
}
// A creature body sphere at an ARBITRARY height (elevated well above the terrain so the
// airborne player never finds a floor and stays airborne — the crowd-jump geometry).
private static void RegisterCreatureAt(PhysicsEngine e, uint id, Vector3 center, float radius = R)
{
e.ShadowObjects.Register(
id, gfxObjId: 0u, center, Quaternion.Identity, radius,
worldOffsetX: 0f, worldOffsetY: 0f, landblockId: Lb,
collisionType: ShadowCollisionType.Sphere,
cylHeight: 0f, scale: 1f, state: 0u,
flags: EntityCollisionFlags.IsCreature, isStatic: false);
}
private static PhysicsBody AirborneBody(Vector3 pos) => new PhysicsBody
{
Position = pos,
Orientation = Quaternion.Identity,
State = PhysicsStateFlags.Gravity | PhysicsStateFlags.ReportCollisions,
TransientState = TransientStateFlags.None, // airborne: no Contact / no OnWalkable
};
private ResolveResult Push(PhysicsEngine engine, PhysicsBody body, Vector3 delta, uint cell)
=> engine.ResolveWithTransition(
body.Position, body.Position + delta, cell,
R, H, StepUp, StepDown, isOnGround: false, body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
[Fact]
public void AirborneJumpBlockedOverhead_FsfClimbsTo3_ThenResetsWhenAdvancing()
{
// The #182 airborne-stuck geometry, distilled: an airborne mover with a persistent
// UPWARD intent (a jump) into a creature directly overhead. The collision normal is
// vertical, so — unlike a purely-horizontal push, whose sliding normal absorbs the
// whole offset and aborts the sweep before the ladder — the up-intent survives every
// frame, the sweep runs, and fsf escalates 0→1→2→3 via the Stationary* bit round-trip.
var engine = BuildEngine();
RegisterCreatureAt(engine, 0xC0B0u, new Vector3(12f, 10f, 4.5f)); // directly overhead
// Start BELOW the creature so the first frames rise freely (fsf stays 0), then wedge.
var body = AirborneBody(new Vector3(12f, 10f, 1f));
uint cell = Cell;
var up = new Vector3(0f, 0f, 0.6f); // persistent jump intent
int firstFrameFsf = -1, maxFsf = 0;
for (int i = 0; i < 14; i++)
{
var r = Push(engine, body, up, cell);
body.Position = r.Position; cell = r.CellId;
if (i == 0) firstFrameFsf = body.FramesStationaryFall;
maxFsf = Math.Max(maxFsf, body.FramesStationaryFall);
_out.WriteLine($"frame{i,2}: z={body.Position.Z:F3} fsf={body.FramesStationaryFall} " +
$"ts=0x{(uint)body.TransientState:X} onGround={r.IsOnGround}");
}
// The first frame rose freely (well below the creature) — advancing keeps fsf at 0.
Assert.Equal(0, firstFrameFsf);
// Once wedged under the creature, fsf escalated to 3.
Assert.True(maxFsf == 3, $"fsf must escalate to 3 while the jump is blocked overhead; got {maxFsf}");
// At fsf 3 the ladder manufactured an upward contact plane → grounded on the obstacle
// (the retail "glide onto the crowd top").
Assert.True(body.ContactPlaneValid, "fsf≥3 should manufacture a contact plane");
Assert.True(body.ContactPlane.Normal.Z > 0.99f, "manufactured contact plane points up");
}
[Fact]
public void GroundedWallSlide_DoesNotAccumulateFsf()
{
// A GROUNDED mover pushed into an obstacle is not a "stuck fall" — retail keeps fsf=0
// (ACE _redo=1 via the OnWalkable path), so a grounded crowd-jam slides rather than
// getting its velocity zeroed. Guards against the fsf-zero breaking grounded wall-slide.
var engine = BuildEngine();
RegisterCreatureAt(engine, 0xC0C0u, new Vector3(12f, 11.5f, R)); // foot-height creature
var floor = new Plane(Vector3.UnitZ, 0f);
var verts = new[]
{
new Vector3(-100f, -100f, 0f), new Vector3(100f, -100f, 0f),
new Vector3(100f, 100f, 0f), new Vector3(-100f, 100f, 0f),
};
var body = new PhysicsBody
{
Position = new Vector3(12f, 10f, 0f),
Orientation = Quaternion.Identity,
State = PhysicsStateFlags.Gravity | PhysicsStateFlags.ReportCollisions,
ContactPlaneValid = true, ContactPlane = floor, ContactPlaneCellId = Cell,
WalkablePolygonValid = true, WalkablePlane = floor, WalkableVertices = verts,
WalkableUp = Vector3.UnitZ,
TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable,
};
uint cell = Cell;
int maxFsf = 0;
for (int i = 0; i < 40; i++)
{
var r = engine.ResolveWithTransition(
body.Position, body.Position + new Vector3(0f, 0.08f, 0f), cell,
R, H, StepUp, StepDown, isOnGround: true, body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
body.Position = r.Position; cell = r.CellId;
maxFsf = Math.Max(maxFsf, body.FramesStationaryFall);
}
_out.WriteLine($"grounded push maxFsf={maxFsf}");
Assert.Equal(0, maxFsf); // a grounded mover never accumulates a stuck-fall
}
}

111
tests/AcDream.Core.Tests/Physics/HandleAllCollisionsTests.cs Normal file
View file

@ -0,0 +1,111 @@
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// Conformance tests for <see cref="PhysicsObjUpdate.HandleAllCollisions"/> — the port of
/// retail <c>CPhysicsObj::handle_all_collisions</c> (0x00514780, pc:282647). This is the
/// velocity "bleed on block" decision: reflect (fsf≤1) vs zero (fsf&gt;1).
/// </summary>
public class HandleAllCollisionsTests
{
private static PhysicsBody Airborne(Vector3 v, int fsf = 0) => new PhysicsBody
{
State = PhysicsStateFlags.Gravity | PhysicsStateFlags.ReportCollisions,
TransientState = TransientStateFlags.None,
Velocity = v,
FramesStationaryFall = fsf,
};
[Fact]
public void Fsf0_AirborneWallHit_ReflectsIntoWallComponent()
{
var b = Airborne(new Vector3(3f, 0f, 0f)); // moving +X into a wall whose outward normal is -X
var n = new Vector3(-1f, 0f, 0f);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
// dot = 3*-1 = -3 < 0 → k = -(-3*(0.05+1)) = 3.15 → v += (-1,0,0)*3.15 → x = 3 - 3.15 = -0.15
Assert.Equal(-0.15f, b.Velocity.X, precision: 3);
}
[Fact]
public void Fsf0_MovingAwayFromSurface_DoesNotReflect()
{
var b = Airborne(new Vector3(0f, 0f, 2f)); // moving up, normal also up (already separating)
var n = new Vector3(0f, 0f, 1f);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.Equal(2f, b.Velocity.Z); // dot = +2 >= 0 → no reflection
}
[Fact]
public void Fsf2_ZeroesVelocity_TheAirborneStuckBleed()
{
// The #182 case: a straight-up jump blocked by a near-horizontal creature normal.
// At fsf>1 the whole velocity is zeroed so gravity resumes → the player falls/glides off.
var b = Airborne(new Vector3(0f, 0f, 18f), fsf: 2);
var n = new Vector3(-0.96f, -0.25f, -0.15f);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.Equal(Vector3.Zero, b.Velocity);
}
[Fact]
public void Fsf3_ZeroesVelocity_EvenWithoutCollisionNormal()
{
var b = Airborne(new Vector3(1f, 2f, 18f), fsf: 3);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: false, collisionNormal: default,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.Equal(Vector3.Zero, b.Velocity);
}
[Fact]
public void StayingOnWalkable_DoesNotReflect_CorridorWallSlidePreserved()
{
// Grounded before AND after → should_reflect is false → the tangential wall-slide
// velocity is preserved (retail's rule; the corridor shuffle, not a sticky bounce).
var b = new PhysicsBody
{
Velocity = new Vector3(3f, 0f, 0f),
TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable,
FramesStationaryFall = 0,
};
var n = new Vector3(-1f, 0f, 0f);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: true, prevOnWalkable: true, nowOnWalkable: true);
Assert.Equal(3f, b.Velocity.X);
}
[Fact]
public void Inelastic_ZeroesInsteadOfReflecting()
{
var b = Airborne(new Vector3(3f, 0f, 0f));
b.State |= PhysicsStateFlags.Inelastic; // spell projectile / missile
var n = new Vector3(-1f, 0f, 0f);
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: false);
Assert.Equal(Vector3.Zero, b.Velocity);
}
[Fact]
public void LandingReflects_RetailRuleRestored_NotSuppressed()
{
// prev airborne → now grounded (a landing). Retail reflects here too (AD-25 retired);
// at elasticity 0.05 the effect is a tiny, imperceptible deflection.
var b = Airborne(new Vector3(0f, 0f, -5f)); // falling
var n = new Vector3(0f, 0f, 1f); // floor normal up
PhysicsObjUpdate.HandleAllCollisions(b,
collisionNormalValid: true, collisionNormal: n,
prevContact: false, prevOnWalkable: false, nowOnWalkable: true);
// dot = -5 < 0 → k = -(-5*1.05) = 5.25 → v.z = -5 + 5.25 = 0.25 (tiny bounce)
Assert.Equal(0.25f, b.Velocity.Z, precision: 3);
}
}

78
tests/AcDream.Core.Tests/Physics/InWorldLinkGuardTests.cs Normal file
View file

@ -0,0 +1,78 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// R4-V5 door-swing fix (2026-07-03, register TS-40): CMotionInterp's
/// dispatch tails strip link animations for DETACHED objects only (retail
/// <c>if (physics_obj->cell == 0) RemoveLinkAnimations</c>, raw @305627).
/// The old proxy (<c>CellPosition.ObjCellId == 0</c>) was seeded only by
/// the local player's SnapToCell, so every REMOTE body read "detached" and
/// every dispatched transition link (door open/close swings, remote
/// walk↔run links) was stripped the same tick it was appended — the pose
/// snapped straight to the new cycle. These pin the corrected
/// <see cref="PhysicsBody.InWorld"/> guard polarity.
/// </summary>
public class InWorldLinkGuardTests
{
[Fact]
public void InWorldBody_DispatchKeepsTransitionLinks()
{
var body = new PhysicsBody
{
InWorld = true,
TransientState = TransientStateFlags.Contact
| TransientStateFlags.OnWalkable
| TransientStateFlags.Active,
};
var interp = new MotionInterpreter(body);
int strips = 0;
interp.RemoveLinkAnimations = () => strips++;
interp.DoInterpretedMotion(MotionCommand.WalkForward, new MovementParameters());
Assert.Equal(0, strips);
}
[Fact]
public void DetachedBody_DispatchStripsLinks_RetailGuard()
{
var body = new PhysicsBody
{
// InWorld left false — retail's pre-enter_world detached state.
TransientState = TransientStateFlags.Contact
| TransientStateFlags.OnWalkable
| TransientStateFlags.Active,
};
var interp = new MotionInterpreter(body);
int strips = 0;
interp.RemoveLinkAnimations = () => strips++;
interp.DoInterpretedMotion(MotionCommand.WalkForward, new MovementParameters());
Assert.Equal(1, strips);
}
[Fact]
public void RemoteShapedBody_StopCompletely_KeepsLinksToo()
{
// The other two guard sites (StopCompletely / StopInterpretedMotion)
// share the same InWorld polarity.
var body = new PhysicsBody
{
InWorld = true,
TransientState = TransientStateFlags.Contact
| TransientStateFlags.OnWalkable
| TransientStateFlags.Active,
};
var interp = new MotionInterpreter(body);
int strips = 0;
interp.RemoveLinkAnimations = () => strips++;
interp.StopCompletely();
Assert.Equal(0, strips);
}
}

518
tests/AcDream.Core.Tests/Physics/Issue137CorridorSeamInspectionTests.cs Normal file
View file

@ -0,0 +1,518 @@
using System;
using System.IO;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #137 corridor-seam inspection (2026-07-05, Facility Hub). Live probe
/// evidence (launch-175-verify2.log:42858): crossing corridor cells
/// 0x8A02016E → 0x8A02017A at world x≈85.25 records a wall hit with normal
/// (−1,0,0) — pointing straight back against the movement — after which the
/// stale sliding normal wedges all forward motion (ok=False hit=no, offset
/// projected to zero). Question this dump answers: does cell 0x8A02017A's
/// PHYSICS polygon set contain a portal-spanning polygon at its entry plane
/// (normal ≈ ±X at the portal's local X) — i.e., are portal-sealing polys in
/// our collision set where retail filters them?
/// </summary>
public class Issue137CorridorSeamInspectionTests
{
private readonly ITestOutputHelper _out;
public Issue137CorridorSeamInspectionTests(ITestOutputHelper output) => _out = output;
[Theory]
[InlineData(0x8A02016Eu)]
[InlineData(0x8A02017Au)]
[InlineData(0x8A02011Eu)] // the under-floor room the corridor's floor-portals lead to
[InlineData(0x8A020179u)] // the ramp corridor cell with the window (the #137 window-climb repro)
[InlineData(0x8A02017Eu)] // the cell beyond the window the player climbed into
public void CorridorCell_PhysicsPolysAndPortals_DatInspection(uint envCellId)
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var envCell = dats.Get<EnvCell>(envCellId);
Assert.NotNull(envCell);
_out.WriteLine($"=== EnvCell 0x{envCellId:X8} ===");
_out.WriteLine($" pos=({envCell!.Position.Origin.X:F2},{envCell.Position.Origin.Y:F2},{envCell.Position.Origin.Z:F2}) " +
$"rot=({envCell.Position.Orientation.X:F3},{envCell.Position.Orientation.Y:F3},{envCell.Position.Orientation.Z:F3},{envCell.Position.Orientation.W:F3})");
_out.WriteLine($" EnvironmentId=0x{envCell.EnvironmentId:X4} CellStructure={envCell.CellStructure}");
_out.WriteLine($" CellPortals={envCell.CellPortals.Count}");
foreach (var p in envCell.CellPortals)
_out.WriteLine($" portal poly={p.PolygonId} other=0x{p.OtherCellId:X4} flags={p.Flags}");
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell.EnvironmentId);
Assert.NotNull(environment);
Assert.True(environment!.Cells.TryGetValue(envCell.CellStructure, out var cs));
_out.WriteLine($" PhysicsPolygons={cs!.PhysicsPolygons.Count} (portal-relevant normals below)");
foreach (var (id, poly) in cs.PhysicsPolygons)
{
// Compute the face normal from the vertex fan (same math as
// PhysicsDataCache.ResolvePolygons).
var verts = poly.VertexIds;
if (verts.Count < 3) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[0], out var v0)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[1], out var v1)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[2], out var v2)) continue;
var n = System.Numerics.Vector3.Normalize(System.Numerics.Vector3.Cross(
v1.Origin - v0.Origin, v2.Origin - v0.Origin));
// Only print near-horizontal-normal polys (walls) — the seam wall
// candidates; floors/ceilings are noise here.
if (MathF.Abs(n.Z) > 0.3f) continue;
_out.WriteLine($" poly {id}: n=({n.X:F2},{n.Y:F2},{n.Z:F2}) v0=({v0.Origin.X:F2},{v0.Origin.Y:F2},{v0.Origin.Z:F2}) verts={verts.Count} sides={poly.SidesType} stip={poly.Stippling}");
}
// The portal polygons live in the VISUAL polygon set — print their
// ids so overlap with the physics set (same id space?) is visible.
_out.WriteLine($" VisualPolygons={cs.Polygons.Count}");
foreach (var p in envCell.CellPortals)
{
if (cs.Polygons.TryGetValue((ushort)p.PolygonId, out var vp))
{
_out.WriteLine($" portal-poly {p.PolygonId} IS in the visual set (verts={vp.VertexIds.Count})");
bool inPhysics = cs.PhysicsPolygons.ContainsKey((ushort)p.PolygonId);
_out.WriteLine($" portal-poly {p.PolygonId} in PHYSICS set: {inPhysics}");
}
}
}
/// <summary>
/// Mechanism-1 follow-up (2026-07-06): being in the CellStruct's
/// <c>PhysicsPolygons</c> TABLE does not mean the physics BSP ever tests a
/// polygon — retail's <c>BSPLEAF::sphere_intersects_poly</c> (0x0053d580)
/// iterates the LEAF's <c>in_polys</c> index list (leaf construction
/// 0x0053d4a0: <c>in_polys[i] = &amp;pack_poly[index]</c>), and our
/// BSPQuery walks the dat's PhysicsBSP leaves the same way. This dump
/// answers: do the physics-BSP LEAVES of the corridor cells reference the
/// portal polygons? If yes, retail's own BSP query would test them too
/// (→ the passable mechanism must be transit/approach-side — the cdb
/// question). If no, our collision is testing polys retail never reaches
/// (→ a desk-fixable acdream divergence).
/// </summary>
[Theory]
[InlineData(0x8A02016Eu)]
[InlineData(0x8A02017Au)]
public void CorridorCell_PhysicsBspLeafMembership_OfPortalPolys(uint envCellId)
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var envCell = dats.Get<EnvCell>(envCellId);
Assert.NotNull(envCell);
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell!.EnvironmentId);
Assert.NotNull(environment);
Assert.True(environment!.Cells.TryGetValue(envCell.CellStructure, out var cs));
var portalPolyIds = new System.Collections.Generic.HashSet<ushort>();
foreach (var p in envCell.CellPortals)
portalPolyIds.Add((ushort)p.PolygonId);
_out.WriteLine($"=== EnvCell 0x{envCellId:X8} — physics BSP leaf membership ===");
_out.WriteLine($" Env=0x{envCell.EnvironmentId:X4} struct={envCell.CellStructure} " +
$"portalPolyIds=[{string.Join(",", portalPolyIds)}] " +
$"physicsTable=[{string.Join(",", cs!.PhysicsPolygons.Keys)}]");
var root = cs.PhysicsBSP?.Root;
Assert.NotNull(root);
int leafCount = 0;
var leafPolyIds = new System.Collections.Generic.HashSet<ushort>();
var portalPolyLeafHits = new System.Collections.Generic.List<string>();
var stack = new System.Collections.Generic.Stack<(DatReaderWriter.Types.PhysicsBSPNode Node, string Path)>();
stack.Push((root!, "R"));
while (stack.Count > 0)
{
var (n, path) = stack.Pop();
if (n.Polygons is { Count: > 0 })
{
leafCount++;
foreach (var pid in n.Polygons)
{
leafPolyIds.Add(pid);
if (portalPolyIds.Contains(pid))
portalPolyLeafHits.Add($"poly {pid} in leaf@{path} (type={n.Type}, polys=[{string.Join(",", n.Polygons)}])");
}
}
if (n.PosNode is not null) stack.Push((n.PosNode, path + "+"));
if (n.NegNode is not null) stack.Push((n.NegNode, path + "-"));
}
_out.WriteLine($" BSP leaves-with-polys={leafCount} distinctLeafPolyIds=[{string.Join(",", leafPolyIds)}]");
var tableNotInLeaves = new System.Collections.Generic.List<ushort>();
foreach (var pid in cs.PhysicsPolygons.Keys)
if (!leafPolyIds.Contains(pid))
tableNotInLeaves.Add(pid);
_out.WriteLine($" physics-table polys NOT referenced by any BSP leaf: [{string.Join(",", tableNotInLeaves)}]");
if (portalPolyLeafHits.Count == 0)
{
_out.WriteLine(" >>> NO portal polygon is referenced by any physics-BSP leaf — " +
"retail's sphere_intersects_poly never tests them from this cell's BSP.");
}
else
{
foreach (var hit in portalPolyLeafHits)
_out.WriteLine($" >>> PORTAL POLY IN PHYSICS LEAF: {hit}");
}
}
/// <summary>
/// #137 window climb: the dat truth for the player's collision spheres.
/// Our InitPath places the head sphere at (sphereHeight − radius) = 0.72
/// (capsule top 1.2 m); retail collides with the Setup's SPHERE LIST
/// verbatim (CPhysicsObj::transition → init_sphere(GetNumSphere,
/// GetSphere, scale)). Print human Setup 0x02000001's spheres.
/// </summary>
[Fact]
public void HumanSetup_CollisionSpheres_DatTruth()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var setup = dats.Get<DatReaderWriter.DBObjs.Setup>(0x02000001u);
Assert.NotNull(setup);
_out.WriteLine($"Setup 0x02000001: Height={setup!.Height:F3} Radius={setup.Radius:F3} " +
$"StepUp={setup.StepUpHeight:F3} StepDown={setup.StepDownHeight:F3}");
_out.WriteLine($"Spheres ({setup.Spheres.Count}):");
foreach (var s in setup.Spheres)
_out.WriteLine($" origin=({s.Origin.X:F3},{s.Origin.Y:F3},{s.Origin.Z:F3}) r={s.Radius:F3}");
_out.WriteLine($"CylSpheres ({setup.CylSpheres.Count}):");
foreach (var c in setup.CylSpheres)
_out.WriteLine($" origin=({c.Origin.X:F3},{c.Origin.Y:F3},{c.Origin.Z:F3}) r={c.Radius:F3} h={c.Height:F3}");
}
/// <summary>
/// #137 window-climb geometry (2026-07-06): full world-space vertex dump
/// of the shaft cell 0x8A02017E (all physics polys) and 0x8A020179's
/// south-wall family — the opening's lintel/ceiling spans decide where
/// retail blocks the head.
/// </summary>
[Fact]
public void WindowShaft_FullPolyDump()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
foreach (var cellId in new[] { 0x8A02017Eu, 0x8A020179u })
{
var envCell = dats.Get<EnvCell>(cellId);
Assert.NotNull(envCell);
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell!.EnvironmentId);
Assert.True(environment!.Cells.TryGetValue(envCell.CellStructure, out var cs));
var rot = new System.Numerics.Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = System.Numerics.Matrix4x4.CreateFromQuaternion(rot)
* System.Numerics.Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
_out.WriteLine($"=== 0x{cellId:X8} full physics polys (world verts) ===");
foreach (var (id, poly) in cs!.PhysicsPolygons)
{
var verts = poly.VertexIds;
if (verts.Count < 3) continue;
var w = new System.Collections.Generic.List<System.Numerics.Vector3>();
foreach (var vid in verts)
if (cs.VertexArray.Vertices.TryGetValue((ushort)vid, out var v))
w.Add(System.Numerics.Vector3.Transform(v.Origin, world));
var n = System.Numerics.Vector3.Normalize(
System.Numerics.Vector3.Cross(w[1] - w[0], w[2] - w[0]));
// 017E: everything. 0179: south-wall family + ceilings only.
if (cellId == 0x8A020179u && MathF.Abs(n.Y) < 0.3f && n.Z > -0.3f) continue;
var vs = string.Join(" ", w.ConvertAll(p => $"({p.X:F2},{p.Y:F2},{p.Z:F2})"));
_out.WriteLine($" poly {id}: n=({n.X:F2},{n.Y:F2},{n.Z:F2}) verts={vs}");
}
}
}
/// <summary>
/// Mechanism-1 re-characterization (2026-07-06): the live hit normal
/// (−1.00, 0.03, −0.03) at world (85.253, −39.776, −5.992) matches NO
/// physics polygon of either corridor cell — 0x8A02016E (identity
/// rotation) and 0x8A02017A (180° Z) both have only ±Y-normal wall polys,
/// and the PortalSide portals to 0x011E (polys 1/3/5) are ±Y planes
/// 1.4 m north of the player's track, perpendicular to the +X run — the
/// pos_hits_sphere directional cull rejects them for this movement. This
/// sweep hunts the ACTUAL culprit: every physics poly of the seam cell +
/// all portal-adjacent neighbors, world-transformed, scored against the
/// hit point + normal.
/// </summary>
[Fact]
public void CorridorSeam_FindPolygonMatchingLiveHit()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
// Live evidence (launch-175-verify2.log:42858).
var hitPoint = new System.Numerics.Vector3(85.253f, -39.776f, -5.992f);
var hitNormal = new System.Numerics.Vector3(-1.00f, 0.03f, -0.03f);
hitNormal = System.Numerics.Vector3.Normalize(hitNormal);
const float sphereRadius = 0.48f;
// Seam cells + every portal-adjacent neighbor of both.
var cellIds = new System.Collections.Generic.HashSet<uint>
{
0x8A02016Eu, 0x8A02017Au,
};
foreach (var seed in new[] { 0x8A02016Eu, 0x8A02017Au })
{
var seedCell = dats.Get<EnvCell>(seed);
if (seedCell is null) continue;
foreach (var p in seedCell.CellPortals)
cellIds.Add(0x8A020000u | p.OtherCellId);
}
foreach (var cellId in cellIds)
{
var envCell = dats.Get<EnvCell>(cellId);
if (envCell is null) { _out.WriteLine($"cell 0x{cellId:X8}: NOT FOUND"); continue; }
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell.EnvironmentId);
if (environment is null || !environment.Cells.TryGetValue(envCell.CellStructure, out var cs))
continue;
var rot = new System.Numerics.Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = System.Numerics.Matrix4x4.CreateFromQuaternion(rot)
* System.Numerics.Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
var portalPolyIds = new System.Collections.Generic.HashSet<ushort>();
foreach (var p in envCell.CellPortals) portalPolyIds.Add((ushort)p.PolygonId);
foreach (var (id, poly) in cs!.PhysicsPolygons)
{
var verts = poly.VertexIds;
if (verts.Count < 3) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[0], out var v0)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[1], out var v1)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[2], out var v2)) continue;
var w0 = System.Numerics.Vector3.Transform(v0.Origin, world);
var w1 = System.Numerics.Vector3.Transform(v1.Origin, world);
var w2 = System.Numerics.Vector3.Transform(v2.Origin, world);
var n = System.Numerics.Vector3.Normalize(
System.Numerics.Vector3.Cross(w1 - w0, w2 - w0));
float align = System.Numerics.Vector3.Dot(n, hitNormal);
// |align|: the vertex-fan winding convention can flip the
// computed normal vs the physics plane's true facing — accept
// both signs (2026-07-06 sweep flaw fix).
if (MathF.Abs(align) < 0.95f) continue; // within ~18° of the recorded normal
// Plane distance from the hit point.
float d = -System.Numerics.Vector3.Dot(n, w0);
float dist = System.Numerics.Vector3.Dot(n, hitPoint) + d;
if (MathF.Abs(dist) > sphereRadius + 0.1f) continue;
// Rough proximity: hit point near the polygon's vertex span.
float minX = MathF.Min(w0.X, MathF.Min(w1.X, w2.X)) - 1f;
float maxX = MathF.Max(w0.X, MathF.Max(w1.X, w2.X)) + 1f;
float minY = MathF.Min(w0.Y, MathF.Min(w1.Y, w2.Y)) - 1f;
float maxY = MathF.Max(w0.Y, MathF.Max(w1.Y, w2.Y)) + 1f;
if (hitPoint.X < minX || hitPoint.X > maxX ||
hitPoint.Y < minY || hitPoint.Y > maxY) continue;
_out.WriteLine(
$">>> CANDIDATE cell=0x{cellId:X8} poly={id} " +
$"worldN=({n.X:F3},{n.Y:F3},{n.Z:F3}) align={align:F3} planeDist={dist:F3} " +
$"isPortalPoly={portalPolyIds.Contains(id)} " +
$"w0=({w0.X:F2},{w0.Y:F2},{w0.Z:F2}) w1=({w1.X:F2},{w1.Y:F2},{w1.Z:F2}) w2=({w2.X:F2},{w2.Y:F2},{w2.Z:F2}) " +
$"verts={verts.Count} sides={poly.SidesType} stip={poly.Stippling}");
}
}
_out.WriteLine("(sweep complete)");
}
/// <summary>
/// Entry-poly hunt: the synthetic reversed-movement collision normal is
/// produced by slide_sphere's opposing-normals branch, which needs an
/// INPUT collision normal anti-parallel to the grounded contact plane —
/// i.e., a DOWNWARD-facing polygon (lintel / arch underside). Those were
/// filtered out of the wall dump (|n.Z| &gt; 0.3). Sweep both corridor
/// cells for downward polys near the seam column and print where their
/// planes sit relative to the player's head sphere.
/// </summary>
[Fact]
public void CorridorSeam_DownwardPolysNearSeam()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
foreach (var cellId in new[] { 0x8A02016Eu, 0x8A02017Au })
{
var envCell = dats.Get<EnvCell>(cellId);
Assert.NotNull(envCell);
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell!.EnvironmentId);
Assert.NotNull(environment);
Assert.True(environment!.Cells.TryGetValue(envCell.CellStructure, out var cs));
var rot = new System.Numerics.Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = System.Numerics.Matrix4x4.CreateFromQuaternion(rot)
* System.Numerics.Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
_out.WriteLine($"=== 0x{cellId:X8} downward physics polys (n.Z < -0.3) ===");
foreach (var (id, poly) in cs!.PhysicsPolygons)
{
var verts = poly.VertexIds;
if (verts.Count < 3) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[0], out var v0)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[1], out var v1)) continue;
if (!cs.VertexArray.Vertices.TryGetValue((ushort)verts[2], out var v2)) continue;
var w0 = System.Numerics.Vector3.Transform(v0.Origin, world);
var w1 = System.Numerics.Vector3.Transform(v1.Origin, world);
var w2 = System.Numerics.Vector3.Transform(v2.Origin, world);
var n = System.Numerics.Vector3.Normalize(
System.Numerics.Vector3.Cross(w1 - w0, w2 - w0));
if (n.Z > -0.3f) continue;
// Only near the seam column the player crossed.
float minX = MathF.Min(w0.X, MathF.Min(w1.X, w2.X));
float maxX = MathF.Max(w0.X, MathF.Max(w1.X, w2.X));
if (maxX < 83.5f || minX > 87.0f) continue;
var allW = new System.Collections.Generic.List<System.Numerics.Vector3>();
foreach (var vid in verts)
if (cs.VertexArray.Vertices.TryGetValue((ushort)vid, out var vv))
allW.Add(System.Numerics.Vector3.Transform(vv.Origin, world));
float minZ = float.MaxValue, maxZ = float.MinValue, minY = float.MaxValue, maxY = float.MinValue;
foreach (var w in allW)
{
minZ = MathF.Min(minZ, w.Z); maxZ = MathF.Max(maxZ, w.Z);
minY = MathF.Min(minY, w.Y); maxY = MathF.Max(maxY, w.Y);
}
_out.WriteLine(
$" poly {id}: worldN=({n.X:F2},{n.Y:F2},{n.Z:F2}) x=[{minX:F2},{maxX:F2}] " +
$"y=[{minY:F2},{maxY:F2}] z=[{minZ:F2},{maxZ:F2}] verts={verts.Count} " +
$"sides={poly.SidesType} stip={poly.Stippling}");
}
}
_out.WriteLine("(downward sweep complete)");
}
/// <summary>
/// 2026-07-06 gate-session follow-up: seam crossings SUCCEED at
/// y≈−40.8..−41.2 and BLOCK at y≈−39.5..−39.8 (cell-transit log,
/// launch-137-corridor-gate.log). A y-dependent boundary with no physics
/// polygon culprit points at the PORTAL POLYGONS — if the doorway
/// openings don't span the full corridor width, the transit/membership
/// machinery only hands the sphere to the neighbor inside the portal
/// poly's span. Dump every portal polygon's world-space vertex extent.
/// </summary>
[Theory]
[InlineData(0x8A02016Eu)]
[InlineData(0x8A02017Au)]
public void CorridorCell_PortalPolygonWorldSpans(uint envCellId)
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var envCell = dats.Get<EnvCell>(envCellId);
Assert.NotNull(envCell);
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell!.EnvironmentId);
Assert.NotNull(environment);
Assert.True(environment!.Cells.TryGetValue(envCell.CellStructure, out var cs));
var rot = new System.Numerics.Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = System.Numerics.Matrix4x4.CreateFromQuaternion(rot)
* System.Numerics.Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
_out.WriteLine($"=== 0x{envCellId:X8} portal polygons (world spans) ===");
foreach (var p in envCell.CellPortals)
{
if (!cs!.Polygons.TryGetValue((ushort)p.PolygonId, out var poly))
{
_out.WriteLine($" portal poly {p.PolygonId} -> 0x{p.OtherCellId:X4} {p.Flags}: NOT in visual set");
continue;
}
var min = new System.Numerics.Vector3(float.MaxValue);
var max = new System.Numerics.Vector3(float.MinValue);
foreach (var vid in poly.VertexIds)
{
if (!cs.VertexArray.Vertices.TryGetValue((ushort)vid, out var v)) continue;
var w = System.Numerics.Vector3.Transform(v.Origin, world);
min = System.Numerics.Vector3.Min(min, w);
max = System.Numerics.Vector3.Max(max, w);
}
_out.WriteLine(
$" portal poly {p.PolygonId} -> 0x{p.OtherCellId:X4} [{p.Flags}] " +
$"x=[{min.X:F2},{max.X:F2}] y=[{min.Y:F2},{max.Y:F2}] z=[{min.Z:F2},{max.Z:F2}] " +
$"verts={poly.VertexIds.Count}");
}
}
}

500
tests/AcDream.Core.Tests/Physics/Issue137CorridorSeamReplayTests.cs Normal file
View file

@ -0,0 +1,500 @@
using System;
using System.IO;
using System.Numerics;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
using Plane = System.Numerics.Plane;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #137 corridor-seam replay (2026-07-06) — dat-backed reproduction of the
/// Facility Hub phantom hit (launch-175-verify2.log:42858): running +X down
/// the corridor, crossing 0x8A02016E → 0x8A02017A at x≈85.25, the live
/// client recorded `ok=True hit=yes n=(−1.00,0.03,−0.03)` with full advance,
/// persisted the sliding normal, and every later forward resolve absorbed to
/// zero (`ok=False hit=no`).
///
/// <para>
/// Dat facts pinned by <see cref="Issue137CorridorSeamInspectionTests"/>:
/// neither corridor cell (nor any portal-adjacent neighbor) has a physics
/// polygon whose plane matches that normal near the hit point — the recorded
/// normal is SYNTHETIC (the negated movement direction), which is exactly
/// what slide_sphere's opposing-normals branch records. Retail
/// (<c>CSphere::slide_sphere</c> 0x00537440 @0x0053762c) returns
/// COLLIDED_TS from that branch; our port returned OK — letting the step
/// complete with full advance and the synthetic normal persisted.
/// </para>
///
/// <para>
/// This replay drives the real engine over the real dat cells with the
/// live-log positions and player dimensions, and pins: the seam crossing
/// must complete WITHOUT persisting a sliding normal, and continued forward
/// running must keep advancing (no absorbing wedge).
/// </para>
/// </summary>
public class Issue137CorridorSeamReplayTests
{
private readonly ITestOutputHelper _out;
public Issue137CorridorSeamReplayTests(ITestOutputHelper output) => _out = output;
private const uint SeamCellWest = 0x8A02016Eu;
private const uint SeamCellEast = 0x8A02017Au;
private static string? FindDatDir()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(datDir) ? datDir : null;
}
/// <summary>
/// Hydrate the two seam cells + every portal-adjacent neighbor into a
/// PhysicsEngine, exactly as the streaming path does (CacheCellStruct
/// with the dat world transform).
/// </summary>
private static PhysicsEngine BuildCorridorEngine(DatCollection dats)
{
var engine = new PhysicsEngine();
engine.DataCache = new PhysicsDataCache();
var toLoad = new System.Collections.Generic.HashSet<uint> { SeamCellWest, SeamCellEast };
foreach (var seed in new[] { SeamCellWest, SeamCellEast })
{
var seedCell = dats.Get<EnvCell>(seed);
Assert.NotNull(seedCell);
foreach (var p in seedCell!.CellPortals)
toLoad.Add(0x8A020000u | p.OtherCellId);
}
// Expand three portal rings — the live collision cell array reaches
// cells three hops out (0x8A020166, the under-ramp room whose ceiling
// is the ramp slab's underside, is ring-3 in the 2026-07-06
// seam-shake trace; with only two rings the offline flood can never
// add it and the shake does not reproduce).
for (int ring = 0; ring < 3; ring++)
{
foreach (var known in new System.Collections.Generic.List<uint>(toLoad))
{
var cell = dats.Get<EnvCell>(known);
if (cell is null) continue;
foreach (var p in cell.CellPortals)
toLoad.Add(0x8A020000u | p.OtherCellId);
}
}
foreach (var cellId in toLoad)
{
var envCell = dats.Get<EnvCell>(cellId);
if (envCell is null) continue;
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell.EnvironmentId);
if (environment is null) continue;
if (!environment.Cells.TryGetValue(envCell.CellStructure, out var cs)) continue;
var rot = new Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = Matrix4x4.CreateFromQuaternion(rot)
* Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
engine.DataCache.CacheCellStruct(cellId, envCell, cs!, world);
}
return engine;
}
private static PhysicsBody GroundedBody()
{
var body = new PhysicsBody();
body.ContactPlaneValid = true;
// Corridor floor at world z = −6 → n·p + d = 0 with n = +Z, d = 6.
body.ContactPlane = new Plane(Vector3.UnitZ, 6f);
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
// The live session carried a walkable polygon (walkable=True on every
// [resolve] line) — seed the corridor floor slab so the transition's
// SetWalkable path runs like live.
body.WalkablePolygonValid = true;
body.WalkablePlane = new Plane(Vector3.UnitZ, 6f);
body.WalkableUp = Vector3.UnitZ;
body.WalkableVertices = new[]
{
new Vector3(75f, -41.67f, -6f),
new Vector3(85f, -41.67f, -6f),
new Vector3(85f, -38.33f, -6f),
new Vector3(75f, -38.33f, -6f),
};
return body;
}
private ResolveResult Resolve(PhysicsEngine engine, PhysicsBody body,
Vector3 from, Vector3 to, uint cellId)
=> engine.ResolveWithTransition(
currentPos: from,
targetPos: to,
cellId: cellId,
sphereRadius: 0.48f, // human player, PlayerMovementController:885
sphereHeight: 1.2f, // human player, PlayerMovementController:886
stepUpHeight: 0.4f, // PlayerMovementController defaults
stepDownHeight: 0.4f,
isOnGround: true,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
/// <summary>
/// 2026-07-06 seam-shake repro, snapshot-exact (probe session
/// launch-137-seam-probes.log + resolve-137-seam-capture.jsonl tick 4101,
/// repeated ×46): running WEST across the x=75 boundary
/// (0x8A02016E → 0x8A020165, the ramp cell) from (75.287, −40.035, −6)
/// toward (74.685, −39.988, −6), the resolve blocks with the SYNTHETIC
/// reversed-movement normal (0.997, −0.078, −0.002) and out==in — every
/// frame — the "shaking at the seam" report.
///
/// <para>
/// Probe-traced chain: the foot sphere (tangent to the floor) crosses
/// onto 0165's ramp floor; the ramp slab is double-faced and the
/// UNDERSIDE face (poly 0, n=(−0.03,0,−1)) grazes the sphere within the
/// hit threshold → recorded as a foot near-miss → neg-poly step-up
/// dispatch with a downward normal → the nested step-up's walkable probe
/// rejects the exactly-tangent ramp floor ([walkable-nearest]
/// gap=−0.0000 overlapsSphere=False) → StepUpSlide →
/// slide_sphere(downward normal vs up-facing contact plane) → the
/// opposing-normals branch → Collided → revert. Repeat.
/// </para>
/// </summary>
[Fact]
public void SeamShake_WestBoundary_SnapshotExact_Advances()
{
var datDir = FindDatDir();
if (datDir is null)
{
_out.WriteLine("SKIP: dat directory not found");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildCorridorEngine(dats);
// Body seeded EXACTLY from the capture's bodyBefore (tick 4101).
var body = new PhysicsBody();
body.ContactPlaneValid = true;
body.ContactPlane = new Plane(Vector3.UnitZ, 6f);
body.ContactPlaneCellId = SeamCellWest;
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
body.WalkablePolygonValid = true;
body.WalkablePlane = new Plane(Vector3.UnitZ, 6f);
body.WalkableUp = Vector3.UnitZ;
body.WalkableVertices = new[]
{
new Vector3(75f, -38.33333f, -6f),
new Vector3(75f, -41.66667f, -6f),
new Vector3(78.33333f, -41.66667f, -6f),
new Vector3(78.33333f, -38.33333f, -6f),
};
var from = new Vector3(75.28674f, -40.03537f, -6f);
var to = new Vector3(74.6854f, -39.988018f, -6f);
// Emit the same step-level probes the live session logged so the
// offline trace can be line-diffed against launch-137-seam-probes.log
// — the first divergent line names the state the replay is missing.
var probeBuffer = new System.IO.StringWriter();
var prevOut = Console.Out;
ResolveResult r1;
try
{
Console.SetOut(probeBuffer);
PhysicsDiagnostics.ProbeStepWalkEnabled = true;
PhysicsDiagnostics.ProbePushBackEnabled = true;
PhysicsDiagnostics.ProbeIndoorBspEnabled = true;
r1 = engine.ResolveWithTransition(
currentPos: from,
targetPos: to,
cellId: SeamCellWest,
sphereRadius: 0.48f,
sphereHeight: 1.2f,
stepUpHeight: 0.6f, // live Setup values from the capture
stepDownHeight: 1.5f,
isOnGround: true,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
}
finally
{
PhysicsDiagnostics.ProbeStepWalkEnabled = false;
PhysicsDiagnostics.ProbePushBackEnabled = false;
PhysicsDiagnostics.ProbeIndoorBspEnabled = false;
Console.SetOut(prevOut);
}
_out.WriteLine(probeBuffer.ToString());
_out.WriteLine($"r1: ok={r1.Ok} out=({r1.Position.X:F3},{r1.Position.Y:F3},{r1.Position.Z:F3}) " +
$"cell=0x{r1.CellId:X8} hit={r1.CollisionNormalValid} " +
$"n=({r1.CollisionNormal.X:F2},{r1.CollisionNormal.Y:F2},{r1.CollisionNormal.Z:F2}) " +
$"bodySliding={body.TransientState.HasFlag(TransientStateFlags.Sliding)}");
Assert.True(r1.Position.X < from.X - 0.3f,
$"The westward boundary crossing onto the ramp must advance " +
$"({from.X:F3} → {r1.Position.X:F3}, target {to.X:F3}); zero " +
$"advance with the reversed-movement normal = the seam shake.");
}
/// <summary>
/// #137 window-climb repro (2026-07-06 gate 2, launch-137-gate2.log):
/// running from the ramp top in 0x8A020179 into the corridor-end opening
/// (the portal to the 0x8A02017E shaft, wall plane world y=−41.67), the
/// player stepped INTO the niche — `in=(89.531,−41.506,−5.112) →
/// out=(90.209,−41.774,−5.209) cell=0x8A02017E` — ending with the head
/// (and camera) through the opening's roof. The opening is ~1.3 m tall
/// (z −5.2..−3.9); a 1.68 m character cannot fit — retail blocks entry
/// (the raised probe's HEAD sphere hits the lintel/ceiling). User axiom:
/// "should not be able to run into it".
/// </summary>
[Fact]
public void WindowOpening_HeadCannotFit_EntryBlocked()
{
var datDir = FindDatDir();
if (datDir is null)
{
_out.WriteLine("SKIP: dat directory not found");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildCorridorEngine(dats);
var body = new PhysicsBody();
body.ContactPlaneValid = true;
body.ContactPlane = new Plane(Vector3.UnitZ, 5.112f); // ramp-top level
body.ContactPlaneCellId = 0x8A020179u;
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
// Walk the live approach (ramp-top toward the corridor-end opening)
// so the engine self-accumulates its contact-plane/walkable state,
// then push into the opening for several held-key frames (the live
// climb happened under a held key, not a single resolve).
var pos = new Vector3(88.60f, -41.10f, -5.05f);
uint cell = 0x8A020179u;
ResolveResult r = default;
bool probeFrames = Env.GetEnvironmentVariable("ACDREAM_TEST_WINDOW_PROBE") == "1";
for (int i = 0; i < 22; i++)
{
var dir = Vector3.Normalize(new Vector3(90.209f, -41.809f, 0f) - new Vector3(pos.X, pos.Y, 0f));
var step = new Vector3(dir.X, dir.Y, 0f) * 0.13f;
var probeBuffer = new System.IO.StringWriter();
var prevOut = Console.Out;
try
{
if (probeFrames && i >= 9)
{
Console.SetOut(probeBuffer);
PhysicsDiagnostics.ProbeStepWalkEnabled = true;
PhysicsDiagnostics.ProbeIndoorBspEnabled = true;
}
r = engine.ResolveWithTransition(
currentPos: pos,
targetPos: pos + step,
cellId: cell,
sphereRadius: 0.48f,
// #137: the corrected capsule top (dat Setup 0x02000001,
// head sphere center 1.350 → top 1.830; Height 1.835).
// The live climb happened under the old 1.2f (head top
// 1.2 m — no head collision at the lintel).
sphereHeight: 1.835f,
stepUpHeight: 0.6f,
stepDownHeight: 1.5f,
isOnGround: true,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
}
finally
{
if (probeFrames && i >= 9)
{
PhysicsDiagnostics.ProbeStepWalkEnabled = false;
PhysicsDiagnostics.ProbeIndoorBspEnabled = false;
Console.SetOut(prevOut);
}
}
if (probeFrames && i >= 9 && i <= 10)
_out.WriteLine(probeBuffer.ToString());
_out.WriteLine($"r{i}: ok={r.Ok} out=({r.Position.X:F3},{r.Position.Y:F3},{r.Position.Z:F3}) " +
$"cell=0x{r.CellId:X8} hit={r.CollisionNormalValid} " +
$"n=({r.CollisionNormal.X:F2},{r.CollisionNormal.Y:F2},{r.CollisionNormal.Z:F2})");
pos = r.Position;
cell = r.CellId;
Assert.NotEqual(0x8A02017Eu, r.CellId);
Assert.True(r.Position.Y > -41.6f,
$"A 1.68 m character must not enter the 1.3 m-tall opening " +
$"(wall plane y=−41.67); frame {i} got Y={r.Position.Y:F3} " +
$"cell=0x{r.CellId:X8} (live bug: ended at −41.774 inside " +
$"0x8A02017E, head through the roof).");
}
}
/// <summary>
/// The window-climb's placement half, pinned at the exact site: at the
/// step-up's raised position on the alcove sill (foot −5.019), the HEAD
/// sphere (center −3.339, span −3.82..−2.86) pokes ~6 cm past the south
/// wall plane into the SOLID rock above the alcove ceiling (0x8A020179's
/// lintel band, polys 14/15 at y=−41.67 z∈[−3.90,−3.00]). Retail's
/// step-down placement insert (CTransition::step_down 0x0050b3b3 →
/// placement transitional_insert → BSPTREE::sphere_intersects_solid
/// 0x0053d5f0) REJECTS — that's what makes the 0.7 m sill unclimbable.
/// Our placement passed (the live + offline climb), so our Path-1 solid
/// test misses the head-vs-solid overlap.
/// </summary>
[Fact]
public void WindowAlcove_RaisedPlacement_HeadInLintelSolid_Collides()
{
var datDir = FindDatDir();
if (datDir is null)
{
_out.WriteLine("SKIP: dat directory not found");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildCorridorEngine(dats);
var cell = engine.DataCache!.GetCellStruct(0x8A020179u);
Assert.NotNull(cell);
Assert.NotNull(cell!.BSP?.Root);
// The raised (post-sill-climb) pose from the offline repro's r9.
var footWorld = new Vector3(89.683f, -41.247f, -4.539f); // foot sphere CENTER
var headWorld = new Vector3(89.683f, -41.247f, -3.339f); // head sphere CENTER
var footLocal = Vector3.Transform(footWorld, cell.InverseWorldTransform);
var headLocal = Vector3.Transform(headWorld, cell.InverseWorldTransform);
var t = new Transition();
t.SpherePath.InitPath(
new Vector3(89.683f, -41.247f, -5.019f),
new Vector3(89.683f, -41.247f, -5.019f),
0x8A020179u, 0.48f, 1.2f);
t.SpherePath.InsertType = InsertType.Placement;
Matrix4x4.Decompose(cell.WorldTransform, out _, out var cellRot, out var cellOrigin);
var result = BSPQuery.FindCollisions(
cell.BSP!.Root,
cell.Resolved,
t,
new DatReaderWriter.Types.Sphere { Origin = footLocal, Radius = 0.48f },
new DatReaderWriter.Types.Sphere { Origin = headLocal, Radius = 0.48f },
footLocal,
Vector3.UnitZ,
1.0f,
cellRot,
engine,
worldOrigin: cellOrigin);
_out.WriteLine($"placement result={result} footLocal=({footLocal.X:F3},{footLocal.Y:F3},{footLocal.Z:F3}) " +
$"headLocal=({headLocal.X:F3},{headLocal.Y:F3},{headLocal.Z:F3})");
Assert.Equal(TransitionState.Collided, result);
}
/// <summary>
/// 2026-07-06 gate session repro (launch-137-corridor-gate.log): standing
/// at (84.851, −39.764, −6.000) — the foot sphere already straddling the
/// x=85 cell boundary by 0.33 m — the first move attempt toward
/// (85.453, −39.782) blocked with the synthetic reversed-movement normal
/// (−1.00, 0.03, −0.02), out==in, cp lost (cp=none), and repeated every
/// frame (the "shaking at the seam" report). The deeper straddle start is
/// what the original replay frame (84.638 → 85.253) didn't cover.
/// </summary>
[Fact]
public void SeamCrossing_FromDeepStraddleStart_Advances()
{
var datDir = FindDatDir();
if (datDir is null)
{
_out.WriteLine("SKIP: dat directory not found");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildCorridorEngine(dats);
var body = GroundedBody();
var from = new Vector3(84.851f, -39.764f, -6.000f);
var to = new Vector3(85.453f, -39.782f, -6.000f);
var r1 = Resolve(engine, body, from, to, SeamCellWest);
_out.WriteLine($"r1: ok={r1.Ok} out=({r1.Position.X:F3},{r1.Position.Y:F3},{r1.Position.Z:F3}) " +
$"cell=0x{r1.CellId:X8} hit={r1.CollisionNormalValid} " +
$"n=({r1.CollisionNormal.X:F2},{r1.CollisionNormal.Y:F2},{r1.CollisionNormal.Z:F2}) " +
$"bodySliding={body.TransientState.HasFlag(TransientStateFlags.Sliding)} " +
$"bodyCpValid={body.ContactPlaneValid}");
Assert.True(r1.Position.X > from.X + 0.2f,
$"The straddling-start seam crossing must advance " +
$"({from.X:F3} → {r1.Position.X:F3}); zero advance with a " +
$"reversed-movement normal = the 2026-07-06 seam shake.");
}
[Fact]
public void SeamCrossing_DoesNotPersistSyntheticSlidingNormal_AndRunContinues()
{
var datDir = FindDatDir();
if (datDir is null)
{
_out.WriteLine("SKIP: dat directory not found");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildCorridorEngine(dats);
var body = GroundedBody();
// ── The live hit frame verbatim (launch-175-verify2.log:42858) ──
var from = new Vector3(84.638f, -39.758f, -6.000f);
var to = new Vector3(85.253f, -39.776f, -6.000f);
var r1 = Resolve(engine, body, from, to, SeamCellWest);
_out.WriteLine($"r1: ok={r1.Ok} out=({r1.Position.X:F3},{r1.Position.Y:F3},{r1.Position.Z:F3}) " +
$"cell=0x{r1.CellId:X8} hit={r1.CollisionNormalValid} " +
$"n=({r1.CollisionNormal.X:F2},{r1.CollisionNormal.Y:F2},{r1.CollisionNormal.Z:F2}) " +
$"bodySliding={body.TransientState.HasFlag(TransientStateFlags.Sliding)} " +
$"slidingN=({body.SlidingNormal.X:F2},{body.SlidingNormal.Y:F2},{body.SlidingNormal.Z:F2})");
// The corridor is straight and open: the crossing must not leave the
// body carrying a sliding normal (there is no wall to slide on —
// Issue137CorridorSeamInspectionTests proved no polygon matches the
// live-recorded normal; retail's slide_sphere opposing branch returns
// COLLIDED and its validate handling never lets a synthetic
// reversed-movement normal survive a clean corridor run).
Assert.False(body.TransientState.HasFlag(TransientStateFlags.Sliding),
"Crossing the open corridor seam must not persist a sliding " +
"normal — the live wedge's entry state (#137 mechanism 2).");
// ── Keep running +X (the live session's held-W frames) ──────────
var pos = r1.Position;
var cell = r1.CellId;
for (int i = 0; i < 6; i++)
{
var step = new Vector3(0.13f, -0.004f, 0f); // ~run speed per tick, same heading
var r = Resolve(engine, body, pos, pos + step, cell);
_out.WriteLine($"r{i + 2}: ok={r.Ok} out=({r.Position.X:F3},{r.Position.Y:F3},{r.Position.Z:F3}) " +
$"cell=0x{r.CellId:X8} hit={r.CollisionNormalValid} " +
$"bodySliding={body.TransientState.HasFlag(TransientStateFlags.Sliding)}");
Assert.True(r.Position.X > pos.X + 0.05f,
$"Forward run must keep advancing through the open corridor " +
$"(frame {i + 2}: {pos.X:F3} → {r.Position.X:F3}) — zero advance " +
$"= the #137 absorbing wedge.");
pos = r.Position;
cell = r.CellId;
}
}
}

343
tests/AcDream.Core.Tests/Physics/Issue137SlidingNormalLifecycleTests.cs Normal file
View file

@ -0,0 +1,343 @@
using System;
using System.Collections.Generic;
using System.Numerics;
using DatReaderWriter.Enums;
using DatReaderWriter.Types;
using AcDream.Core.Physics;
using Xunit;
using Plane = System.Numerics.Plane;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #137 mechanism 2 — the sliding-normal absorbing wedge (2026-07-06).
///
/// <para>
/// Retail's in-transition <c>collision_info.sliding_normal</c> has exactly ONE
/// writer besides the per-frame seed: <c>CTransition::validate_transition</c>
/// (0x0050ac21-ac30, "if collision_normal_valid → set_sliding_normal"). The
/// BSP collision layer NEVER writes it — <c>BSPTREE::find_collisions</c>'
/// Contact branch dispatches full hits to <c>step_sphere_up</c> (foot,
/// 0x0053a719) / <c>BSPTREE::slide_sphere</c> (head, 0x0053a697), and
/// <c>CSphere::slide_sphere</c> (0x00537440) slides IN-FRAME via
/// <c>add_offset_to_check_pos</c> without touching sliding_normal
/// (grep-verified: zero sliding_normal references between 0x005155 and
/// 0x00841f in acclient_2013_pseudo_c.txt). ACE mirrors this: the only
/// SetSlidingNormal call sites are CollisionInfo.cs:58 (the setter) and
/// Transition.cs:1027 (validate). The body-side persistence
/// (<c>CPhysicsObj::SetPositionInternal</c> 0x005154c2, SLIDING_TS bit-4 sync
/// at 0x005154e1) runs only on transition SUCCESS.
/// </para>
///
/// <para>
/// acdream's BSPQuery Contact branch carried stub fallbacks
/// (SetCollisionNormal + SetSlidingNormal + return Slid) instead of the real
/// slide. The leaked sliding normal survived to the transition end, the
/// unconditional body writeback persisted it, and the next frame's seed
/// projected an exactly-anti-parallel push to zero — aborting at step 0
/// BEFORE any collision test could refresh the state. Live shape: the
/// Facility Hub corridor phantom (launch-175-verify2.log:42858 — one wall
/// hit at the 0x8A02016E→0x8A02017A seam, then endless ok=False hit=no
/// zero-advance resolves; strafe escapes).
/// </para>
/// </summary>
public class Issue137SlidingNormalLifecycleTests
{
// =========================================================================
// Site-level pins — BSPQuery.FindCollisions Contact branch must not write
// the transition's sliding normal (retail: only validate_transition does).
// =========================================================================
/// <summary>
/// Contact foot-sphere FULL HIT with the step-up recursion unavailable
/// (engine=null / step-up already in progress) must dispatch the real
/// sphere slide — never the SetSlidingNormal stub.
///
/// <para>
/// Retail: a blocked step-up funnels to <c>SPHEREPATH::step_up_slide</c> →
/// <c>CSphere::slide_sphere</c> (ACE SpherePath.cs:316 → Sphere.cs:558) —
/// in-frame slide, no sliding_normal write. Face-on into a vertical wall
/// while grounded: the crease projection (cross(wallN, floorN)) has no
/// component along the movement, the slide offset is degenerate
/// (&lt; F_EPSILON), and slide_sphere returns COLLIDED_TS (0x00537735).
/// </para>
/// </summary>
[Fact]
public void ContactFootFullHit_StepUpUnavailable_RealSlide_NoSlidingNormalWrite()
{
var (root, resolved) = BSPStepUpFixtures.TallWall();
// Grounded mover pushing face-on (+X) into the 5 m wall at x=0.5
// (normal −X). Sphere center reach 0.35+0.2=0.55 penetrates the wall.
var from = new Vector3(0.10f, 0f, BSPStepUpFixtures.SphereRadius);
var to = new Vector3(0.35f, 0f, BSPStepUpFixtures.SphereRadius);
var t = BSPStepUpFixtures.MakeGroundedTransition(from, to);
var localSphere = new DatReaderWriter.Types.Sphere
{
Origin = to,
Radius = BSPStepUpFixtures.SphereRadius,
};
var result = BSPQuery.FindCollisions(
root, resolved, t, localSphere, null,
from, Vector3.UnitZ, 1.0f);
Assert.False(t.CollisionInfo.SlidingNormalValid,
"find_collisions must not write collision_info.sliding_normal — " +
"retail's only in-transition writer is validate_transition " +
"(0x0050ac21). A sliding normal leaked here survives to the body " +
"writeback and absorbs the next frame's forward offset (#137).");
Assert.True(t.CollisionInfo.CollisionNormalValid,
"The real slide records the collision normal (CSphere::slide_sphere " +
"→ set_collision_normal).");
Assert.Equal(TransitionState.Collided, result);
}
/// <summary>
/// Contact HEAD-sphere FULL HIT must dispatch <c>BSPTREE::slide_sphere</c>
/// (retail 0x0053a697; ACE BSPTree.cs:202 → 310-316: the real
/// <c>Sphere.SlideSphere</c> on GlobalSphere[0]) — never the stub.
/// The corridor phantom's portal-side polys span head height; this is the
/// path that recorded the (−1,0,0) normal the wedge absorbed on.
/// </summary>
[Fact]
public void ContactHeadFullHit_RealSlide_NoSlidingNormalWrite()
{
// Raised wall: z ∈ [0.6, 5] at x=0.5, normal −X. The foot sphere
// (center z=0.2, r=0.2 → z-span [0, 0.4]) passes under it; the head
// sphere (center z=0.8 → z-span [0.6, 1.0]) fully hits it.
var resolved = new Dictionary<ushort, ResolvedPolygon>();
var floorVerts = new[]
{
new Vector3(-2f, -1f, 0f), new Vector3(2f, -1f, 0f),
new Vector3(2f, 1f, 0f), new Vector3(-2f, 1f, 0f),
};
resolved[1] = new ResolvedPolygon
{
Vertices = floorVerts,
Plane = new Plane(Vector3.UnitZ, 0f),
NumPoints = 4,
SidesType = CullMode.None,
};
var wallNormal = new Vector3(-1f, 0f, 0f);
var wallVerts = new[]
{
new Vector3(0.5f, -1f, 0.6f),
new Vector3(0.5f, -1f, 5f),
new Vector3(0.5f, 1f, 5f),
new Vector3(0.5f, 1f, 0.6f),
};
resolved[2] = new ResolvedPolygon
{
Vertices = wallVerts,
Plane = new Plane(wallNormal, 0.5f), // n·p + d = 0 at x=0.5
NumPoints = 4,
SidesType = CullMode.None,
};
var leaf = new PhysicsBSPNode
{
Type = BSPNodeType.Leaf,
BoundingSphere = new DatReaderWriter.Types.Sphere { Origin = new Vector3(0f, 0f, 2.5f), Radius = 10f },
};
leaf.Polygons.Add(1);
leaf.Polygons.Add(2);
var from = new Vector3(0.10f, 0f, BSPStepUpFixtures.SphereRadius);
var to = new Vector3(0.35f, 0f, BSPStepUpFixtures.SphereRadius);
var t = BSPStepUpFixtures.MakeGroundedTransition(from, to);
var footSphere = new DatReaderWriter.Types.Sphere
{
Origin = to,
Radius = BSPStepUpFixtures.SphereRadius,
};
var headSphere = new DatReaderWriter.Types.Sphere
{
Origin = new Vector3(to.X, to.Y, 0.8f),
Radius = BSPStepUpFixtures.SphereRadius,
};
var result = BSPQuery.FindCollisions(
leaf, resolved, t, footSphere, headSphere,
from, Vector3.UnitZ, 1.0f);
Assert.False(t.CollisionInfo.SlidingNormalValid,
"Head full hit must go through the real BSPTREE::slide_sphere — " +
"no sliding_normal write at the BSP layer (retail 0x0053a697).");
Assert.True(t.CollisionInfo.CollisionNormalValid);
Assert.Equal(TransitionState.Collided, result);
}
/// <summary>
/// <c>CSphere::slide_sphere</c>'s opposing-normals branch (collision
/// normal anti-parallel to the contact plane — e.g. a ceiling-facing
/// normal while grounded) records the REVERSED displacement as the
/// collision normal and returns <b>COLLIDED_TS</b> — retail 0x00537440
/// @0x005375d7-0x0053762c: <c>*normal = −gDelta; normalize;
/// set_collision_normal; return 2</c>. Our port returned OK (its comment
/// even claimed "retail returns OK here"), letting the step complete
/// as-is with a synthetic reversed-movement collision normal — the exact
/// signature of the live corridor hit (`hit=yes n=(−1.00,0.03,−0.03)` =
/// the negated run direction, matching NO dat polygon).
/// </summary>
[Fact]
public void SlideSphere_OpposingNormals_ReturnsCollided_WithReversedDisplacementNormal()
{
var t = new Transition();
t.SpherePath.InitPath(
new Vector3(0f, 0f, 0.2f), new Vector3(0.3f, 0f, 0.2f),
0xA9B40001u, BSPStepUpFixtures.SphereRadius);
t.CollisionInfo.SetContactPlane(new Plane(Vector3.UnitZ, 0f), 0xA9B40001u, false);
// Make gDelta exactly (0.4, 0, 0): currPos = check sphere − (0.4,0,0).
var currPos = t.SpherePath.GlobalSphere[0].Origin - new Vector3(0.4f, 0f, 0f);
// Downward collision normal vs the +Z contact plane → cross ≈ 0
// (parallel), dot = −1 < 0 (opposing) → the reverse branch.
var result = t.SlideSphereInternal(new Vector3(0f, 0f, -1f), currPos);
Assert.Equal(TransitionState.Collided, result);
Assert.True(t.CollisionInfo.CollisionNormalValid);
Assert.True(t.CollisionInfo.CollisionNormal.X < -0.99f,
$"Collision normal must be the normalized reversed displacement " +
$"(−1,0,0); got ({t.CollisionInfo.CollisionNormal.X:F3}," +
$"{t.CollisionInfo.CollisionNormal.Y:F3},{t.CollisionInfo.CollisionNormal.Z:F3}).");
}
// =========================================================================
// Engine-level lifecycle pin — the retail persist/absorb/clear cycle at a
// REAL wall. Guards the fix against regressing wall behavior, and
// documents where retail CLEARS the body's sliding state (the successful
// transition's writeback, when no step re-records a collision).
// =========================================================================
private const uint CellId = 0xA9B40157u;
private static PhysicsEngine BuildWallEngine()
{
var (wallRoot, wallResolved) = BSPStepUpFixtures.TallWall();
var cell = new CellPhysics
{
BSP = new PhysicsBSPTree { Root = wallRoot },
WorldTransform = Matrix4x4.Identity,
InverseWorldTransform = Matrix4x4.Identity,
Resolved = wallResolved,
CellBSP = new CellBSPTree
{
Root = new CellBSPNode { Type = BSPNodeType.Leaf },
},
};
var engine = new PhysicsEngine();
engine.DataCache = new PhysicsDataCache();
// Flat terrain strip so the outdoor fall-through has something to
// sample if it ever fires (same shape as FindEnvCollisionsMultiCellTests).
var heights = new byte[81];
Array.Fill(heights, (byte)0);
engine.AddLandblock(0xA9B4FFFFu, new TerrainSurface(heights, BuildHeightTable()),
Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(),
worldOffsetX: 0f, worldOffsetY: 0f);
engine.DataCache.RegisterCellStructForTest(CellId, cell);
return engine;
}
private static float[] BuildHeightTable()
{
var ht = new float[256];
for (int i = 0; i < 256; i++) ht[i] = i * 1.0f;
return ht;
}
private static PhysicsBody GroundedBody()
{
var body = new PhysicsBody();
body.ContactPlaneValid = true;
body.ContactPlane = new Plane(Vector3.UnitZ, 0f);
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
return body;
}
private ResolveResult ResolveForward(PhysicsEngine engine, PhysicsBody body,
Vector3 from, Vector3 to)
=> engine.ResolveWithTransition(
currentPos: from,
targetPos: to,
cellId: CellId,
sphereRadius: BSPStepUpFixtures.SphereRadius,
sphereHeight: 0f, // single sphere — keeps the scenario deterministic
stepUpHeight: 0.04f, // cannot scale the 5 m wall
stepDownHeight: 0.04f,
isOnGround: true,
body: body);
/// <summary>
/// The full retail lifecycle at a real wall:
/// (1) a blocked face-on push persists the validate-recorded sliding
/// normal via the SUCCESS writeback (SetPositionInternal bit-4 sync,
/// 0x005154e1);
/// (2) the next exactly-anti-parallel push is absorbed by the seed
/// (get_object_info 0x00511d44 → adjust_offset projects to zero →
/// find_transitional_position's step-0 small-offset abort) — the
/// retail cache semantics: "still pressed against this wall";
/// (3) an oblique push escapes along the wall tangent, the step runs
/// without re-recording a collision, and the successful writeback
/// CLEARS the body's sliding state (sliding_normal_valid==0 → bit
/// 4 cleared).
/// </summary>
[Fact]
public void WallLifecycle_PersistOnBlock_AbsorbExactAntiParallel_ClearOnEscape()
{
var engine = BuildWallEngine();
var body = GroundedBody();
// ── 1. Face-on +X into the wall at x=0.5 (normal −X) ─────────────
var r1 = ResolveForward(engine, body,
from: new Vector3(0.10f, 0f, 0f),
to: new Vector3(0.35f, 0f, 0f));
Assert.True(body.TransientState.HasFlag(TransientStateFlags.Sliding),
"A blocked push must persist the validate-recorded sliding normal " +
"(retail SetPositionInternal 0x005154c2 on transition success).");
Assert.True(body.SlidingNormal.X < -0.9f,
$"Persisted normal should face the mover (−X); got {body.SlidingNormal}.");
Assert.True(r1.Position.X + BSPStepUpFixtures.SphereRadius
<= 0.5f + PhysicsGlobals.EPSILON * 20f,
$"The 5 m wall must block the sphere; reach={r1.Position.X + BSPStepUpFixtures.SphereRadius:F4}.");
// ── 2. Exactly-anti-parallel push again: absorbed frame ──────────
var r2 = ResolveForward(engine, body,
from: r1.Position,
to: r1.Position + new Vector3(0.15f, 0f, 0f));
Assert.False(r2.Ok,
"The seeded sliding normal projects the exactly-anti-parallel " +
"offset to zero → step-0 abort (retail find_transitional_position " +
"0050bfb7/0050c0ef). Faithful absorbed frame at a REAL wall.");
Assert.True(body.TransientState.HasFlag(TransientStateFlags.Sliding),
"A failed transition leaves the body's sliding state untouched " +
"(retail: SetPositionInternal never runs on failure).");
// ── 3. Oblique push escapes and CLEARS the persisted state ───────
var r3 = ResolveForward(engine, body,
from: r2.Position,
to: r2.Position + new Vector3(0.10f, 0.15f, 0f));
Assert.True(r3.Ok, "Oblique push must escape along the wall tangent.");
Assert.True(r3.Position.Y > r2.Position.Y + 0.05f,
$"Expected tangential advance along +Y; got Y={r3.Position.Y:F4} " +
$"(from {r2.Position.Y:F4}).");
Assert.False(body.TransientState.HasFlag(TransientStateFlags.Sliding),
"A successful transition whose steps re-record no collision must " +
"CLEAR the body's sliding state (retail SetPositionInternal " +
"0x005154e1: bit 4 synced from the transition's final " +
"sliding_normal_valid, which each step clears before its insert).");
Assert.Equal(Vector3.Zero, body.SlidingNormal);
}
}

265
tests/AcDream.Core.Tests/Physics/Issue175HubDoorPoseInspectionTests.cs Normal file
View file

@ -0,0 +1,265 @@
using System;
using System.IO;
using System.Linq;
using System.Numerics;
using AcDream.Core.Physics;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using DatReaderWriter.Types;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
using Placement = DatReaderWriter.Enums.Placement;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #175 (2026-07-05) — read-only dat inspection for the Facility Hub door
/// (Setup 0x02000C9D, guid 0x78A020C7 in the live session). User report:
/// the door's COLLISION sits displaced to the far side of the VISUAL panel
/// (embed from one side deep enough to camera-clip; a phantom wall on the
/// other side that can push the player out of use radius).
///
/// Hypothesis under test: collision registers from the Setup's
/// PlacementFrames (ShadowShapeBuilder.FromSetup — Resting|Default|first)
/// while the rendered panel poses from the motion table's default/closed
/// state through the sequencer; retail tests the part's LIVE pose
/// (CPhysicsPart), so a door whose placement frame differs from its
/// motion-table closed pose shows exactly this offset. This test dumps both
/// poses so the divergence (or its absence) is a dat fact, not a theory.
///
/// SKIP when the dat directory is absent (CI); local runs have it.
/// </summary>
public class Issue175HubDoorPoseInspectionTests
{
private readonly ITestOutputHelper _out;
public Issue175HubDoorPoseInspectionTests(ITestOutputHelper output) => _out = output;
private const uint HubDoorSetupId = 0x02000C9Du;
[Fact]
public void HubDoorSetup_PlacementVsMotionPose_DatInspection()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var setup = dats.Get<Setup>(HubDoorSetupId);
Assert.NotNull(setup);
_out.WriteLine($"=== Setup 0x{HubDoorSetupId:X8} ===");
_out.WriteLine($" Flags = {setup!.Flags} (0x{(uint)setup.Flags:X8})");
_out.WriteLine($" Parts = {setup.Parts.Count}");
for (int i = 0; i < setup.Parts.Count; i++)
_out.WriteLine($" [{i}] gfxObj=0x{setup.Parts[i]:X8}");
_out.WriteLine($" DefaultAnimation = 0x{setup.DefaultAnimation:X8}");
_out.WriteLine($" DefaultScript = 0x{setup.DefaultScript:X8}");
_out.WriteLine($" DefaultMotionTable = 0x{setup.DefaultMotionTable:X8}");
_out.WriteLine($" CylSpheres={setup.CylSpheres.Count} Spheres={setup.Spheres.Count} Radius={setup.Radius:F3}");
foreach (var c in setup.CylSpheres)
_out.WriteLine($" cyl r={c.Radius:F3} h={c.Height:F3} origin=({c.Origin.X:F3},{c.Origin.Y:F3},{c.Origin.Z:F3})");
_out.WriteLine($" PlacementFrames = {setup.PlacementFrames.Count}");
foreach (var kv in setup.PlacementFrames)
{
_out.WriteLine($" [{kv.Key}] frames={kv.Value.Frames.Count}");
for (int i = 0; i < kv.Value.Frames.Count; i++)
{
var f = kv.Value.Frames[i];
_out.WriteLine(
$" part[{i}] pos=({f.Origin.X:F3},{f.Origin.Y:F3},{f.Origin.Z:F3}) " +
$"rot=({f.Orientation.X:F3},{f.Orientation.Y:F3},{f.Orientation.Z:F3},{f.Orientation.W:F3})");
}
}
// Part 0's physics BSP bounds — where the slab actually is in
// PART-LOCAL space (composed with the poses above for world).
foreach (uint gfxId in setup.Parts.Distinct())
{
var gfx = dats.Get<GfxObj>(gfxId);
_out.WriteLine($"=== GfxObj 0x{gfxId:X8} ===");
if (gfx is null) { _out.WriteLine(" NULL"); continue; }
var root = gfx.PhysicsBSP?.Root;
_out.WriteLine($" PhysicsBSP.Root = {(root is null ? "NULL" : "non-null")}");
if (root?.BoundingSphere is { } bs)
_out.WriteLine($" BSP bounds = ({bs.Origin.X:F3},{bs.Origin.Y:F3},{bs.Origin.Z:F3}) r={bs.Radius:F3}");
if (gfx.PhysicsPolygons is { } pp && gfx.VertexArray?.Vertices is { } verts)
{
float minX = float.MaxValue, maxX = float.MinValue;
float minY = float.MaxValue, maxY = float.MinValue;
float minZ = float.MaxValue, maxZ = float.MinValue;
foreach (var poly in pp.Values)
foreach (var vid in poly.VertexIds)
{
if (!verts.TryGetValue((ushort)vid, out var sv)) continue;
minX = Math.Min(minX, sv.Origin.X); maxX = Math.Max(maxX, sv.Origin.X);
minY = Math.Min(minY, sv.Origin.Y); maxY = Math.Max(maxY, sv.Origin.Y);
minZ = Math.Min(minZ, sv.Origin.Z); maxZ = Math.Max(maxZ, sv.Origin.Z);
}
_out.WriteLine($" Physics AABB (part-local) = X[{minX:F3},{maxX:F3}] Y[{minY:F3},{maxY:F3}] Z[{minZ:F3},{maxZ:F3}]");
}
}
// The motion-table default (closed) pose, if the setup names one:
// frame 0 of the default style's default cycle — what the sequencer
// renders for an idle closed door.
if (setup.DefaultMotionTable != 0)
{
var mt = dats.Get<MotionTable>(setup.DefaultMotionTable);
_out.WriteLine($"=== MotionTable 0x{setup.DefaultMotionTable:X8} ===");
if (mt is null) { _out.WriteLine(" NULL"); return; }
_out.WriteLine($" DefaultStyle = 0x{(uint)mt.DefaultStyle:X8}");
if (mt.Cycles.TryGetValue((int)mt.DefaultStyle, out var defCycle)
&& defCycle.Anims.Count > 0)
{
var animRef = defCycle.Anims[0];
_out.WriteLine($" default cycle anim[0] id=0x{animRef.AnimId:X8} lo={animRef.LowFrame} hi={animRef.HighFrame}");
var anim = dats.Get<Animation>(animRef.AnimId);
if (anim is not null && anim.PartFrames.Count > 0)
{
var f0 = anim.PartFrames[Math.Clamp((int)animRef.LowFrame, 0, anim.PartFrames.Count - 1)];
for (int i = 0; i < f0.Frames.Count; i++)
{
var f = f0.Frames[i];
_out.WriteLine(
$" anim frame0 part[{i}] pos=({f.Origin.X:F3},{f.Origin.Y:F3},{f.Origin.Z:F3}) " +
$"rot=({f.Orientation.X:F3},{f.Orientation.Y:F3},{f.Orientation.Z:F3},{f.Orientation.W:F3})");
}
}
else
{
_out.WriteLine(" anim NULL or no PartFrames");
}
}
else
{
_out.WriteLine(" no default-style cycle");
}
}
else
{
_out.WriteLine("=== no DefaultMotionTable on the setup ===");
}
}
/// <summary>
/// #175 derivation conformance — REAL-DAT pin for
/// <see cref="AcDream.Core.Physics.Motion.MotionTablePose.DefaultStatePartFrames"/>.
/// The first cut of the derivation looked up <c>Cycles[DefaultStyle]</c>
/// with the bare style word; the dictionary is keyed by the COMBINED
/// <c>(style &lt;&lt; 16) | substate</c> word (CMotionTable.cs:683), so it
/// always missed and the #175 fix silently no-oped. This pin loads the
/// human motion table (0x09000001 — guaranteed present, default state
/// NonCombat/Ready) and asserts the derivation actually resolves a pose.
/// </summary>
[Fact]
public void MotionTablePose_DefaultState_ResolvesOnRealTable()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
if (!Directory.Exists(datDir))
{
_out.WriteLine($"SKIP: dat directory not found at {datDir}");
return;
}
using var dats = new DatCollection(datDir, DatAccessType.Read);
var mt = dats.Get<MotionTable>(0x09000001u);
Assert.NotNull(mt);
var pose = AcDream.Core.Physics.Motion.MotionTablePose.DefaultStatePartFrames(
mt!, id => dats.Get<Animation>(id));
Assert.NotNull(pose);
_out.WriteLine($"human MT default pose parts={pose!.Count} " +
$"part0=({pose[0].Origin.X:F3},{pose[0].Origin.Y:F3},{pose[0].Origin.Z:F3})");
Assert.True(pose.Count >= 1);
}
// ── #175 fix pins: ShadowShapeBuilder partPoseOverride ──────────────
private static Setup MakeTwoPartSetup()
{
var setup = new Setup();
setup.Parts.Add(0x01000001u);
setup.Parts.Add(0x01000002u);
var placement = new AnimationFrame(2);
placement.Frames.Clear();
placement.Frames.Add(new Frame { Origin = new Vector3(0.88f, -0.44f, 1.37f),
Orientation = new Quaternion(0f, 0f, -0.966f, 0.259f) });
placement.Frames.Add(new Frame { Origin = new Vector3(-0.88f, -0.44f, 1.37f),
Orientation = new Quaternion(0f, 0f, -0.259f, 0.966f) });
setup.PlacementFrames[Placement.Default] = placement;
return setup;
}
/// <summary>
/// With a motion-table pose override, the BSP part shapes must use it —
/// the closed pose, not the ajar placement pose (the #175 offset).
/// </summary>
[Fact]
public void FromSetup_PartPoseOverride_ReplacesPlacementFrames()
{
var setup = MakeTwoPartSetup();
var closed = new[]
{
new Frame { Origin = new Vector3(0.85f, 0f, 1.37f), Orientation = Quaternion.Identity },
new Frame { Origin = new Vector3(-0.85f, 0f, 1.37f), Orientation = Quaternion.Identity },
};
var shapes = ShadowShapeBuilder.FromSetup(
setup, entScale: 1f, hasPhysicsBsp: _ => true, partPoseOverride: closed);
Assert.Equal(2, shapes.Count);
Assert.Equal(new Vector3(0.85f, 0f, 1.37f), shapes[0].LocalPosition);
Assert.Equal(Quaternion.Identity, shapes[0].LocalRotation);
Assert.Equal(new Vector3(-0.85f, 0f, 1.37f), shapes[1].LocalPosition);
}
/// <summary>
/// Null override (no motion table) keeps the pre-#175 placement-frame
/// behavior — landblock statics and table-less entities unchanged.
/// </summary>
[Fact]
public void FromSetup_NoOverride_KeepsPlacementFrames()
{
var setup = MakeTwoPartSetup();
var shapes = ShadowShapeBuilder.FromSetup(
setup, entScale: 1f, hasPhysicsBsp: _ => true);
Assert.Equal(2, shapes.Count);
Assert.Equal(new Vector3(0.88f, -0.44f, 1.37f), shapes[0].LocalPosition);
Assert.Equal(new Quaternion(0f, 0f, -0.966f, 0.259f), shapes[0].LocalRotation);
}
/// <summary>
/// A short override (fewer frames than parts) falls back to placement
/// frames — a mismatched motion table must not misplace collision.
/// </summary>
[Fact]
public void FromSetup_ShortOverride_FallsBackPerPart()
{
var setup = MakeTwoPartSetup();
var shortOverride = new[]
{
new Frame { Origin = new Vector3(0.85f, 0f, 1.37f), Orientation = Quaternion.Identity },
};
var shapes = ShadowShapeBuilder.FromSetup(
setup, entScale: 1f, hasPhysicsBsp: _ => true, partPoseOverride: shortOverride);
Assert.Equal(2, shapes.Count);
Assert.Equal(new Vector3(0.85f, 0f, 1.37f), shapes[0].LocalPosition); // override
Assert.Equal(new Vector3(-0.88f, -0.44f, 1.37f), shapes[1].LocalPosition); // placement fallback
}
}

157
tests/AcDream.Core.Tests/Physics/Issue176177SeamTransitLagTests.cs Normal file
View file

@ -0,0 +1,157 @@
using System;
using System.IO;
using System.Numerics;
using AcDream.Core.Physics;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #176/#177 membership half: production [cell-transit] lines
/// (launch-137-gate2.log) fire 0.1–0.6 m PAST the portal plane in the travel
/// direction (016E→017A at x=85.33–85.47 vs the plane at x=85.00), while the
/// dat CellBSP volumes partition EXACTLY at the plane
/// (Issue176177DungeonSeamInspectionTests.SeamCells_CellBspContainment) —
/// retail's center-only point_in_cell flips at the plane. The render root
/// (viewer cell) resolves through the same machinery; while it lags, the
/// portal flood correctly refuses the boundary portal the eye has already
/// crossed and the whole forward chain drops (the purple seam flash /
/// stair pop). This replay measures OUR resolver's flip point across the
/// x=85 seam in a controlled run.
/// </summary>
public class Issue176177SeamTransitLagTests
{
private const uint SeamCellWest = 0x8A02016Eu; // x 75..85
private const uint SeamCellEast = 0x8A02017Au; // x 85..88.33
private readonly ITestOutputHelper _out;
public Issue176177SeamTransitLagTests(ITestOutputHelper output) => _out = output;
private static string? ResolveDatDir()
{
var datDir = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile),
"Documents", "Asheron's Call");
return Directory.Exists(datDir) ? datDir : null;
}
private static PhysicsEngine BuildEngine(DatCollection dats)
{
var engine = new PhysicsEngine();
engine.DataCache = new PhysicsDataCache();
var toLoad = new System.Collections.Generic.HashSet<uint> { SeamCellWest, SeamCellEast };
for (int ring = 0; ring < 3; ring++)
{
foreach (var known in new System.Collections.Generic.List<uint>(toLoad))
{
var cell = dats.Get<EnvCell>(known);
if (cell is null) continue;
foreach (var p in cell.CellPortals)
toLoad.Add(0x8A020000u | p.OtherCellId);
}
}
foreach (var cellId in toLoad)
{
var envCell = dats.Get<EnvCell>(cellId);
if (envCell is null) continue;
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell.EnvironmentId);
if (environment is null) continue;
if (!environment.Cells.TryGetValue(envCell.CellStructure, out var cs)) continue;
var rot = new Quaternion(
envCell.Position.Orientation.X, envCell.Position.Orientation.Y,
envCell.Position.Orientation.Z, envCell.Position.Orientation.W);
var world = Matrix4x4.CreateFromQuaternion(rot)
* Matrix4x4.CreateTranslation(
envCell.Position.Origin.X, envCell.Position.Origin.Y, envCell.Position.Origin.Z);
engine.DataCache.CacheCellStruct(cellId, envCell, cs!, world);
}
return engine;
}
private static PhysicsBody GroundedBody()
{
var body = new PhysicsBody();
body.ContactPlaneValid = true;
body.ContactPlane = new Plane(Vector3.UnitZ, 6f);
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
body.WalkablePolygonValid = true;
body.WalkablePlane = new Plane(Vector3.UnitZ, 6f);
body.WalkableUp = Vector3.UnitZ;
body.WalkableVertices = new[]
{
new Vector3(75f, -41.67f, -6f),
new Vector3(85f, -41.67f, -6f),
new Vector3(85f, -38.33f, -6f),
new Vector3(75f, -38.33f, -6f),
};
return body;
}
/// <summary>
/// Run +X across the x=85 seam at run-speed tick steps (13.5 cm/tick ≈
/// 4 m/s at 30 Hz) and record where ResolveWithTransition's CellId flips.
/// Retail (center-only point_in_cell, exact-partition CellBSP) flips on
/// the first tick whose END position is past x=85.00 — any flip later
/// than one step past the plane is OUR lag.
/// </summary>
[Theory]
[InlineData(+1)] // west → east across x=85
[InlineData(-1)] // east → west back across
public void RunAcrossSeam_CellFlipPosition(int direction)
{
var datDir = ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var engine = BuildEngine(dats);
var body = GroundedBody();
const float step = 0.135f;
float startX = direction > 0 ? 83.8f : 86.2f;
uint cell = direction > 0 ? SeamCellWest : SeamCellEast;
var pos = new Vector3(startX, -40f, -6f);
float? flipX = null;
for (int tick = 0; tick < 26; tick++)
{
var target = pos + new Vector3(direction * step, 0f, 0f);
var r = engine.ResolveWithTransition(
currentPos: pos,
targetPos: target,
cellId: cell,
sphereRadius: 0.48f,
sphereHeight: 1.835f,
stepUpHeight: 0.4f,
stepDownHeight: 0.4f,
isOnGround: true,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
bool flipped = r.CellId != cell;
_out.WriteLine($"tick={tick,2} pos=({r.Position.X:F3},{r.Position.Y:F3},{r.Position.Z:F3}) " +
$"cell=0x{r.CellId:X8} ok={r.Ok}{(flipped ? " <<< FLIP" : "")}");
if (flipped && flipX is null)
flipX = r.Position.X;
cell = r.CellId;
pos = r.Position;
if (direction > 0 && pos.X > 86.4f) break;
if (direction < 0 && pos.X < 83.6f) break;
}
Assert.NotNull(flipX);
float lag = direction > 0 ? flipX!.Value - 85.00f : 85.00f - flipX!.Value;
_out.WriteLine($"flip at x={flipX:F3} → lag past the plane = {lag:F3} m " +
$"(one-tick quantization bound = {step:F3} m)");
// Diagnostic, not a pin: the finding is the printed lag. A lag beyond
// one tick step is the divergence under investigation.
}
}

150
tests/AcDream.Core.Tests/Physics/Issue180CorridorSweepHysteresisReplayTests.cs Normal file
View file

@ -0,0 +1,150 @@
using System;
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Tests.Conformance;
using DatReaderWriter;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #180 residual — the camera-sweep SAWTOOTH in the Facility Hub corridor
/// (0x8A020164), root-caused to a dead <c>BSPQuery.AdjustToPlane</c>:
/// acdream (via ACE's misdecoded port) had the PerfectClip exact-contact
/// machinery structurally inverted so it ALWAYS failed, and every PathClipped
/// camera stop reverted to the previous transition-step boundary instead of
/// the contact point. Live signature (launch-180-verify.log): the stateful
/// sought re-extends ~3 mm/frame, the sweep passes silently until the step
/// containing the contact, then clips a whole step (~0.27 m) back — a ~19 Hz
/// sawtooth; the pre-stateful camera flipped 1-step vs 2-step backoffs
/// (pulledIn 0.27 ↔ 0.53) — the ORIGINAL #176 stripe strobe.
///
/// This replay walks sweep targets along the exact captured ray
/// (pivot → the [flap-sweep] in= of idx 28882) across the wall behind the
/// spawn camera, against the REAL cell BSP. It pins the retail-faithful
/// stop behavior (BSPTREE::adjust_to_plane 0x00539bf0, pseudocode
/// docs/research/2026-07-06-adjust-to-plane-pseudocode.md):
///
/// 1. targets short of first touch pass unclipped (the wall plane is
/// genuinely ~1.61 m out along this ray: dist(center,plane) &gt; r);
/// 2. every target past first touch CONTACTS (no silent pass-through
/// band — pre-fix, targets embedded up to ~0.25 m passed);
/// 3. the clipped eye is the CONSTANT surface-contact point (pre-fix it
/// tracked the target one step back: eyeBack = s − ~0.27).
/// </summary>
public class Issue180CorridorSweepHysteresisReplayTests
{
private readonly ITestOutputHelper _out;
public Issue180CorridorSweepHysteresisReplayTests(ITestOutputHelper output) => _out = output;
private const float ViewerSphereRadius = 0.3f; // retail viewer_sphere (acclient :93314)
private const uint FacilityHubLandblock = 0x8A020000u;
private const uint CorridorCell = 0x8A020164u;
// [flap-cam] player=(70.58,-40.16,-5.90) (parked spawn) + PivotHeight 1.5.
private static readonly Vector3 Pivot = new(70.58f, -40.16f, -4.40f);
// [flap-sweep] idx 28882: the captured in= that clipped (the sawtooth's deep edge).
private static readonly Vector3 THit = new(70.366051f, -38.628315f, -3.935829f);
private static (PhysicsEngine, PhysicsDataCache) BuildCorridorEngine(DatCollection dats)
{
var cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
for (uint low = 0x0100u; low <= 0x01FFu; low++)
{
uint id = FacilityHubLandblock | low;
try { ConformanceDats.LoadEnvCell(dats, cache, id); }
catch (InvalidOperationException) { /* cell id not present in this dungeon */ }
}
var heights = new byte[81];
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = -1000f;
engine.AddLandblock(FacilityHubLandblock, new TerrainSurface(heights, heightTable),
Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(), 0f, 0f);
return (engine, cache);
}
/// <summary>Mirror of PhysicsCameraCollisionProbe.SweepEye's transition call.</summary>
private static ResolveResult SweepViewer(PhysicsEngine engine, Vector3 pivot, Vector3 desiredEye, uint cellId)
{
uint startCell = cellId;
if ((cellId & 0xFFFFu) >= 0x0100u)
{
var (pivotCell, found) = engine.AdjustPosition(cellId, pivot);
if (found) startCell = pivotCell;
}
Vector3 begin = pivot - new Vector3(0f, 0f, ViewerSphereRadius);
Vector3 end = desiredEye - new Vector3(0f, 0f, ViewerSphereRadius);
return engine.ResolveWithTransition(
currentPos: begin,
targetPos: end,
cellId: startCell,
sphereRadius: ViewerSphereRadius,
sphereHeight: 0f,
stepUpHeight: 0f,
stepDownHeight: 0f,
isOnGround: false,
body: null,
moverFlags: ObjectInfoState.IsViewer | ObjectInfoState.PathClipped
| ObjectInfoState.FreeRotate | ObjectInfoState.PerfectClip,
movingEntityId: 0);
}
[Fact]
public void ClippedStop_IsTheContactPoint_NotAStepBoundary()
{
var datDir = ConformanceDats.ResolveDatDir();
if (datDir is null) { _out.WriteLine("SKIP: dats unavailable"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
var (engine, _) = BuildCorridorEngine(dats);
Vector3 dir = Vector3.Normalize(THit - Pivot);
var clippedEyeBacks = new List<float>();
for (float s = 1.20f; s <= 1.75f; s += 0.025f)
{
Vector3 target = Pivot + dir * s;
var r = SweepViewer(engine, Pivot, target, CorridorCell);
Vector3 eye = r.Position + new Vector3(0f, 0f, ViewerSphereRadius);
float eyeBack = Vector3.Distance(Pivot, eye);
_out.WriteLine(FormattableString.Invariant(
$"s={s:F3} eyeBack={eyeBack:F3} collNorm={r.CollisionNormalValid}"));
if (s <= 1.55f)
{
// (1) Short of first touch (~1.61 m): the sweep must reach the target.
Assert.False(r.CollisionNormalValid,
$"s={s:F3}: no wall within reach, sweep must not clip");
Assert.True(MathF.Abs(eyeBack - s) < 0.01f,
$"s={s:F3}: unclipped sweep must reach the target, got eyeBack={eyeBack:F3}");
}
else if (s >= 1.65f)
{
// (2) Past first touch: every target must contact — the pre-fix
// defect passed targets embedded up to ~0.25 m unclipped.
Assert.True(r.CollisionNormalValid,
$"s={s:F3}: target past the wall must clip");
clippedEyeBacks.Add(eyeBack);
}
}
// (3) The clipped stop is the constant surface-contact point. Pre-fix the
// stop tracked the target one step back (eyeBack = s − ~0.27, spread
// ≈ 0.10 m over this range); retail's adjust_to_plane commits the
// last-clear time within a 0.02 window of the contact.
Assert.True(clippedEyeBacks.Count >= 4, "expected several clipped samples");
float min = float.MaxValue, max = float.MinValue;
foreach (var e in clippedEyeBacks) { min = MathF.Min(min, e); max = MathF.Max(max, e); }
Assert.True(max - min < 0.03f,
$"clipped stops must be one contact point, got spread {max - min:F3} m ({min:F3}..{max:F3})");
}
}

110
tests/AcDream.Core.Tests/Physics/Issue182CrowdJumpTests.cs Normal file
View file

@ -0,0 +1,110 @@
using System;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// End-to-end (Core) proof of the #182 airborne-stuck fix: a jump velocity blocked by a
/// creature BLEEDS to zero within a few frames so gravity can resume — the player falls /
/// glides off instead of hanging in the falling animation. Chains the same steps the
/// PlayerMovementController per-frame loop runs, minus the App layer:
/// integrate (UpdatePhysicsInternal + gravity) → ResolveWithTransition → apply →
/// handle_all_collisions (PhysicsObjUpdate).
/// Before the rebuild the velocity persisted (only an airborne-only reflect that barely
/// touched +Z against a near-horizontal normal); now fs>1 zeros it.
/// </summary>
public class Issue182CrowdJumpTests
{
private readonly ITestOutputHelper _out;
public Issue182CrowdJumpTests(ITestOutputHelper output) => _out = output;
private const uint Lb = 0xA9B40000u;
private const uint Cell = Lb | 0x0001u;
private const float R = 0.48f, H = 1.835f, StepUp = 0.60f, StepDown = 0.04f;
private const float Dt = 1f / 30f; // one physics quantum
private static PhysicsEngine BuildEngine()
{
var engine = new PhysicsEngine { DataCache = new PhysicsDataCache() };
engine.AddLandblock(Lb, new TerrainSurface(new byte[81], new float[256]),
Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(), 0f, 0f);
return engine;
}
private static void RegisterCreatureAt(PhysicsEngine e, uint id, Vector3 c)
=> e.ShadowObjects.Register(id, 0u, c, Quaternion.Identity, R,
0f, 0f, Lb, ShadowCollisionType.Sphere, 0f, 1f, 0u,
EntityCollisionFlags.IsCreature, isStatic: false);
[Fact]
public void BlockedJump_VelocityBleedsToZero_ThenGravityResumes()
{
var engine = BuildEngine();
RegisterCreatureAt(engine, 0xC0B0u, new Vector3(12f, 10f, 4.5f)); // creature overhead
var body = new PhysicsBody
{
Position = new Vector3(12f, 10f, 3.0f),
Orientation = Quaternion.Identity,
State = PhysicsStateFlags.Gravity | PhysicsStateFlags.ReportCollisions,
TransientState = TransientStateFlags.None, // airborne
Velocity = new Vector3(0f, 0f, 12f), // a jump: moving straight up
};
uint cell = Cell;
bool bled = false;
for (int frame = 0; frame < 20; frame++)
{
// 1) integrate velocity + gravity into a candidate (mirrors the controller's §4).
var pre = body.Position;
body.calc_acceleration();
body.UpdatePhysicsInternal(Dt);
var post = body.Position;
bool candidateMoved = post != pre; // retail candidate != m_position gate
// 2) resolve the candidate against the crowd.
var r = engine.ResolveWithTransition(pre, post, cell, R, H, StepUp, StepDown,
isOnGround: false, body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide);
// 3) apply + contact determination (mirrors the controller's SetPositionInternal).
bool prevOnWalkable = body.OnWalkable;
body.Position = r.Position;
cell = r.CellId;
if (r.IsOnGround && body.Velocity.Z <= 0f)
{
body.TransientState |= TransientStateFlags.Contact | TransientStateFlags.OnWalkable;
body.calc_acceleration();
if (body.Velocity.Z < 0f) body.Velocity = new Vector3(body.Velocity.X, body.Velocity.Y, 0f);
}
else
{
body.TransientState &= ~(TransientStateFlags.Contact | TransientStateFlags.OnWalkable);
body.calc_acceleration();
}
// 4) handle_all_collisions: reflect (fsf<=1) or zero (fsf>1) — but ONLY when the
// candidate moved (retail skips SetPositionInternal otherwise), so gravity can
// rebuild the velocity after the bleed instead of it being re-zeroed each frame.
if (candidateMoved)
PhysicsObjUpdate.HandleAllCollisions(body,
r.CollisionNormalValid, r.CollisionNormal,
prevContact: false, prevOnWalkable, nowOnWalkable: body.OnWalkable);
_out.WriteLine($"frame{frame,2}: z={body.Position.Z:F3} vz={body.Velocity.Z:F3} " +
$"fsf={body.FramesStationaryFall}");
// The upward jump velocity must collapse to ~0 (or reverse to falling) within a few
// frames of being blocked — the bleed. Before the fix it persisted near +12.
if (frame >= 1 && frame <= 6 && body.Velocity.Z <= 0.5f)
bled = true;
}
Assert.True(bled, "the blocked jump velocity must bleed to ~0 within a few frames (fsf>1 → v=0)");
// After bleeding, gravity has taken over — the body is no longer being shoved upward.
Assert.True(body.Velocity.Z <= 0.5f, $"velocity should not persist upward; got vz={body.Velocity.Z:F3}");
}
}

192
tests/AcDream.Core.Tests/Physics/Issue185OutdoorStairsSeamReplayTests.cs Normal file
View file

@ -0,0 +1,192 @@
using System;
using System.IO;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
using Plane = System.Numerics.Plane;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #185 outdoor-stairs phantom (2026-07-08) — dat-free reproduction of the
/// house-on-stilts staircase jam. The stairs are a continuous, COPLANAR
/// 38.7° ramp built from stacked step-box objects (gfxObj 0x01000AC5); the
/// tread quads abut at 0.5 m seams that fall on object boundaries. Walking
/// up, at one seam the grounded forward move loses its contact plane and the
/// step-down recovery cannot reach the coplanar (at-level) continuation, so
/// <c>EdgeSlideAfterStepDownFailed</c> → <c>PrecipiceSlide</c> fabricates the
/// tread-edge normal <c>(0,±0.78,±0.62)</c>, which <c>SetSlidingNormal</c>
/// horizontalises to <c>(0,±1,0)</c> — absorbing the +Y up-stairs motion into
/// a pure sideways slide (the #137 / TS-4 family). A jump's +Z clears it.
///
/// <para>
/// Fixtures captured live this session: the player pins at world
/// <c>(131.71, 77.914, 61.485)</c> with <c>slidingNormal=(0,1,0)</c> and a
/// re-fabricated <c>collisionNormal=(0,0.78,0.62)</c>; the tread the player is
/// grounded on has world verts <c>(132.75,77.495,61.015)…</c>. The step-box
/// geometry is hydrated from the captured gfxobj dump
/// (<c>Fixtures/issue185/0x01000AC5.gfxobj.json</c>) so the test is
/// self-contained (no dat) and CI-runnable.
/// </para>
///
/// <para>
/// The step origins march +0.5 world-Y / +0.4 world-Z (matching every observed
/// <c>[resolve-bldg]</c> origin: 75.2/75.7/76.2/76.7/77.2). The player's tread
/// (k=4) is pinned to origin <c>(132.0, 77.245, 60.415)</c> by the captured
/// walkable verts. k=0..7 are registered to span the jam seam + the
/// continuation the player must climb onto.
/// </para>
/// </summary>
public class Issue185OutdoorStairsSeamReplayTests
{
private readonly ITestOutputHelper _out;
public Issue185OutdoorStairsSeamReplayTests(ITestOutputHelper output) => _out = output;
private const uint StairCellId = 0xF682002Cu; // outdoor landcell (low16 = 0x2C < 0x100)
private const uint StairLandblock = 0xF6820000u;
private const uint StepGfxObjId = 0x01000AC5u;
private const int StepCount = 8;
// A +90°-about-Z-rotated step-box maps its local tread normal
// (-0.625,0,0.781) → world (0,-0.625,0.781) (the captured tread plane).
private static readonly Quaternion StepRot =
Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 2f);
// k=4 tread lands at the captured walkable verts when the step origin is
// (132.0, 77.245, 60.415); step k origin = this + k·(0, 0.5, 0.4), k−4 offset.
private static readonly Vector3 Step0Origin = new(132.0f, 75.245f, 58.815f);
private static PhysicsEngine BuildStairEngine()
{
var cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
// Hydrate the step-box collision geometry from the captured dump.
var dumpPath = Path.Combine(SolutionRoot(), "tests", "AcDream.Core.Tests",
"Fixtures", "issue185", "0x01000AC5.gfxobj.json");
Assert.True(File.Exists(dumpPath), $"Missing fixture: {dumpPath}");
var physics = GfxObjDumpSerializer.Hydrate(GfxObjDumpSerializer.Read(dumpPath));
cache.RegisterGfxObjForTest(StepGfxObjId, physics);
float bspR = physics.BoundingSphere?.Radius ?? 1.06f;
// Stub landblock (terrain far below Z=61) so the outdoor context resolves
// without the player's grounding ever seeing terrain — it stands on the treads.
var heights = new byte[81];
var heightTable = new float[256];
for (int i = 0; i < 256; i++) heightTable[i] = -1000f;
engine.AddLandblock(
landblockId: StairLandblock,
terrain: new TerrainSurface(heights, heightTable),
cells: Array.Empty<CellSurface>(),
portals: Array.Empty<PortalPlane>(),
worldOffsetX: 0f,
worldOffsetY: 0f);
for (int k = 0; k < StepCount; k++)
{
var origin = Step0Origin + new Vector3(0f, 0.5f * k, 0.4f * k);
engine.ShadowObjects.Register(
entityId: 0xF6820100u + (uint)k,
gfxObjId: StepGfxObjId,
worldPos: origin,
rotation: StepRot,
radius: bspR,
worldOffsetX: 0f,
worldOffsetY: 0f,
landblockId: StairLandblock,
collisionType: ShadowCollisionType.BSP,
scale: 1.0f,
seedCellId: StairCellId);
}
return engine;
}
private static PhysicsBody GroundedOnTread()
{
var tread = new Plane(new Vector3(0f, -0.62469506f, 0.78086877f), 0.765995f);
return new PhysicsBody
{
Position = new Vector3(131.72375f, 77.49132f, 61.146755f),
Orientation = Quaternion.Identity,
ContactPlaneValid = true,
ContactPlane = tread,
ContactPlaneCellId = StairCellId,
WalkablePolygonValid = true,
WalkablePlane = tread,
WalkableUp = Vector3.UnitZ,
WalkableVertices = new[]
{
new Vector3(132.75f, 77.495f, 61.015f),
new Vector3(131.25f, 77.495f, 61.015f),
new Vector3(131.25f, 76.995f, 60.615f),
new Vector3(132.75f, 76.995f, 60.615f),
},
TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable,
};
}
/// <summary>
/// Drive a held-forward run up the ramp (flat +Y target each tick, physics
/// climbs Z via contact projection — as the movement controller sends it).
/// The player must climb PAST the tread seam (Y &gt; 78.1); pre-fix it pins
/// at ~77.9 and persists a horizontal sliding normal = the wedge.
/// </summary>
[Fact]
public void OutdoorStairs_ForwardRun_ClimbsPastSeam_NoWedge()
{
var engine = BuildStairEngine();
var body = GroundedOnTread();
var pos = body.Position;
uint cell = StairCellId;
ResolveResult r = default;
for (int i = 0; i < 12; i++)
{
var target = new Vector3(pos.X, pos.Y + 0.2f, pos.Z); // flat +Y; physics climbs
r = engine.ResolveWithTransition(
currentPos: pos,
targetPos: target,
cellId: cell,
sphereRadius: 0.48f,
sphereHeight: 1.835f,
stepUpHeight: 0.6f,
stepDownHeight: 1.5f,
isOnGround: true,
body: body,
moverFlags: ObjectInfoState.IsPlayer | ObjectInfoState.EdgeSlide,
movingEntityId: 0x01000000u);
_out.WriteLine(
$"f{i}: out=({r.Position.X:F3},{r.Position.Y:F3},{r.Position.Z:F3}) cell=0x{r.CellId:X8} " +
$"cnV={r.CollisionNormalValid} cn=({r.CollisionNormal.X:F2},{r.CollisionNormal.Y:F2},{r.CollisionNormal.Z:F2}) " +
$"sliding={body.TransientState.HasFlag(TransientStateFlags.Sliding)} " +
$"sN=({body.SlidingNormal.X:F2},{body.SlidingNormal.Y:F2},{body.SlidingNormal.Z:F2})");
pos = r.Position;
cell = r.CellId;
body.Position = pos;
}
Assert.True(pos.Y > 78.10f,
$"Player must climb past the tread seam (reached Y={pos.Y:F3}); pinned at ~77.9 = the " +
$"#185 fabricated-precipice wedge (PrecipiceSlide horizontal sliding normal absorbs +Y).");
Assert.False(body.TransientState.HasFlag(TransientStateFlags.Sliding),
"A continuous walkable ramp seam must not persist a horizontal sliding normal (#137 family).");
}
private static string SolutionRoot()
{
var dir = AppContext.BaseDirectory;
while (!string.IsNullOrEmpty(dir))
{
if (File.Exists(Path.Combine(dir, "AcDream.slnx")))
return dir;
dir = Path.GetDirectoryName(dir);
}
throw new InvalidOperationException(
"Could not locate AcDream.slnx from " + AppContext.BaseDirectory);
}
}

197
tests/AcDream.Core.Tests/Physics/Issue186ConnectorCellGeometryInspectionTests.cs Normal file
View file

@ -0,0 +1,197 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Numerics;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #186 diagnostic (report-only): dump the render-shell + collision geometry of the
/// connecting-room grey-flap cells (0xF6820116 player room, 0xF6820117 next room,
/// 0xF6820118 the connector root where the frame greys). Answers: is 0118 a CLOSED
/// shell (walls/floor/ceiling covering every direction bar the portal apertures) or a
/// bare connector? And does it carry collision geometry (so the camera sweep would
/// hard-stop) or none (so the boom coasts to a degenerate spot)? Skips without the dat.
/// </summary>
public class Issue186ConnectorCellGeometryInspectionTests
{
private readonly ITestOutputHelper _out;
public Issue186ConnectorCellGeometryInspectionTests(ITestOutputHelper output) => _out = output;
private static string? DatDir()
{
var d = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile), "Documents", "Asheron's Call");
return Directory.Exists(d) ? d : null;
}
[Fact]
public void Dump_ConnectorCells_ShellAndCollision()
{
var datDir = DatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
foreach (uint cellId in new[] { 0xF6820116u, 0xF6820117u, 0xF6820118u })
{
var env = dats.Get<EnvCell>(cellId);
if (env is null) { _out.WriteLine($"cell 0x{cellId:X8}: EnvCell NOT FOUND"); continue; }
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | env.EnvironmentId);
environment!.Cells.TryGetValue(env.CellStructure, out var cs);
var portals = env.CellPortals?.Select(p => $"0x{(0xF6820000u | p.OtherCellId):X8}") ?? Enumerable.Empty<string>();
_out.WriteLine($"=== cell 0x{cellId:X8} envId=0x{env.EnvironmentId:X4} struct={env.CellStructure} " +
$"pos=({env.Position.Origin.X:F2},{env.Position.Origin.Y:F2},{env.Position.Origin.Z:F2}) ===");
_out.WriteLine($" CellPortals -> [{string.Join(",", portals)}] VisibleCells={env.VisibleCells?.Count ?? 0}");
if (cs is null) { _out.WriteLine(" CellStruct: NULL"); continue; }
int renderPolys = cs.Polygons?.Count ?? 0;
int physPolys = cs.PhysicsPolygons?.Count ?? 0;
bool physBsp = cs.PhysicsBSP?.Root is not null;
bool cellBsp = cs.CellBSP?.Root is not null;
_out.WriteLine($" renderPolys={renderPolys} physicsPolys={physPolys} physicsBSP={(physBsp ? "YES" : "NO")} cellBSP={(cellBsp ? "YES" : "NO")}");
// Render-shell normal coverage: bucket each render poly's local normal by
// dominant axis to see whether the shell encloses (has +/-X,+/-Y,+/-Z faces).
if (cs.Polygons is not null && cs.VertexArray?.Vertices is not null)
{
var buckets = new Dictionary<string, int>();
foreach (var poly in cs.Polygons.Values)
{
var n = PolyNormal(poly, cs.VertexArray);
if (n is null) continue;
buckets.TryGetValue(DomAxis(n.Value), out int c);
buckets[DomAxis(n.Value)] = c + 1;
}
_out.WriteLine(" render-shell normal buckets: " +
string.Join(" ", buckets.OrderBy(k => k.Key).Select(k => $"{k.Key}={k.Value}")));
}
}
}
/// <summary>
/// #186 root-cause probe (report-only): for every portal of the three connector
/// cells, reproduce acdream's RENDER side test (centroid-derived InsideSide,
/// GameWindow.cs:7425-7438 + PortalVisibilityBuilder.cs:857-864) and compare it to
/// the dat <c>PortalSide</c> bit that retail's PView::InitCell (0x005a4b70) and
/// acdream's own PHYSICS path (CellTransit.cs:190) use. Evaluates each at the live
/// retail/acdream grey-pose eye. The retail cdb trace proved retail ADMITS 0118->0116
/// at this eye; acdream CULLs it. This dump shows whether the centroid InsideSide
/// disagrees with the dat PortalSide for 0118->0116 (the fix) and AGREES elsewhere
/// (so the fix is surgical, not a global side-test change).
/// </summary>
[Fact]
public void PortalSide_CentroidVsDatBit_AtGreyEye()
{
var datDir = DatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
// Live grey-pose eye (fresh HEAD capture + retail cdb trace both ~here).
var eyeWorld = new Vector3(135.51f, 83.32f, 69.16f);
var disagreements = new List<string>(); // portals where centroid != dat bit
bool sawConnectorBackPortal = false; // the 0118->0116 case
bool connectorCentroidCulls = false, connectorDatAdmits = false;
foreach (uint cellId in new[] { 0xF6820116u, 0xF6820117u, 0xF6820118u })
{
var env = dats.Get<EnvCell>(cellId);
if (env is null) { _out.WriteLine($"cell 0x{cellId:X8}: EnvCell NOT FOUND"); continue; }
var environment = dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | env.EnvironmentId);
if (environment is null || !environment.Cells.TryGetValue(env.CellStructure, out var cs) || cs is null)
{ _out.WriteLine($"cell 0x{cellId:X8}: no CellStruct"); continue; }
var origin = new Vector3(env.Position.Origin.X, env.Position.Origin.Y, env.Position.Origin.Z);
var orient = new Quaternion(env.Position.Orientation.X, env.Position.Orientation.Y,
env.Position.Orientation.Z, env.Position.Orientation.W);
var world = Matrix4x4.CreateFromQuaternion(orient) * Matrix4x4.CreateTranslation(origin);
Matrix4x4.Invert(world, out var inverse);
var localEye = Vector3.Transform(eyeWorld, inverse);
// Centroid = AABB center over ALL cell verts (GameWindow.cs:7373-7394).
var bmin = new Vector3(float.MaxValue); var bmax = new Vector3(float.MinValue);
foreach (var kv in cs.VertexArray!.Vertices)
{ var p = new Vector3(kv.Value.Origin.X, kv.Value.Origin.Y, kv.Value.Origin.Z);
bmin = Vector3.Min(bmin, p); bmax = Vector3.Max(bmax, p); }
var centroid = (bmin + bmax) * 0.5f;
_out.WriteLine($"=== cell 0x{cellId:X8} localEye=({localEye.X:F2},{localEye.Y:F2},{localEye.Z:F2}) ===");
foreach (var portal in env.CellPortals!)
{
if (!cs.Polygons!.TryGetValue(portal.PolygonId, out var poly) || poly.VertexIds is null || poly.VertexIds.Count < 3)
{ _out.WriteLine($" p->0x{portal.OtherCellId:X4}: no poly"); continue; }
Vector3 V(int k) { var v = cs.VertexArray.Vertices[(ushort)poly.VertexIds[k]]; return new Vector3(v.Origin.X, v.Origin.Y, v.Origin.Z); }
var p0 = V(0); var p1 = V(1); var p2 = V(2);
var normal = Vector3.Normalize(Vector3.Cross(p1 - p0, p2 - p0));
float d = -Vector3.Dot(normal, p0);
float centroidDot = Vector3.Dot(normal, centroid) + d;
int centroidInside = centroidDot >= 0 ? 0 : 1;
ushort flags = (ushort)portal.Flags;
bool portalSide = (flags & 0x2) == 0; // PortalInfo.cs:44 / CellPortal.cs:24
int datInside = portalSide ? 1 : 0; // mapping derived from retail InitCell + physics CellTransit
float eyeDot = Vector3.Dot(normal, localEye) + d;
const float eps = 0.01f;
bool admitCentroid = centroidInside == 0 ? eyeDot >= -eps : eyeDot <= eps;
bool admitDat = datInside == 0 ? eyeDot >= -eps : eyeDot <= eps;
if (centroidInside != datInside)
disagreements.Add($"0x{cellId & 0xFFFF:X4}->0x{portal.OtherCellId:X4}");
if (cellId == 0xF6820118u && portal.OtherCellId == 0x0116)
{
sawConnectorBackPortal = true;
connectorCentroidCulls = !admitCentroid;
connectorDatAdmits = admitDat;
}
string flag = centroidInside != datInside ? " <<< DISAGREE" : "";
string verdict = admitCentroid != admitDat ? $" centroid={(admitCentroid ? "ADMIT" : "CULL")} dat={(admitDat ? "ADMIT" : "CULL")}" : "";
_out.WriteLine($" p->0x{portal.OtherCellId:X4} flags=0x{flags:X2} PortalSide={portalSide,-5} " +
$"centroidInside={centroidInside} datInside={datInside} eyeDot={eyeDot,7:F3} " +
$"admit[centroid={admitCentroid,-5} dat={admitDat,-5}]{flag}{verdict}");
}
}
// Root cause + fix pins (the retail cdb trace is the oracle: retail draws 0116
// from the 0118 root at this eye; acdream's centroid rule culled it → grey).
Assert.True(sawConnectorBackPortal, "0xF6820118->0116 portal not found in the dat");
Assert.True(connectorCentroidCulls, "the OLD centroid rule should CULL 0118->0116 at the grey eye (the bug)");
Assert.True(connectorDatAdmits, "the dat PortalSide bit should ADMIT 0118->0116 at the grey eye (the fix, matches retail)");
// Surgical: the ONLY portal across these three cells where the centroid rule
// disagrees with the dat bit is the one #186 breaks. If this list ever grows,
// the centroid→dat-bit switch is no longer a no-op for the working portals.
Assert.Equal(new[] { "0x0118->0x0116" }, disagreements.ToArray());
}
private static Vector3? PolyNormal(DatReaderWriter.Types.Polygon poly, DatReaderWriter.Types.VertexArray va)
{
if (poly.VertexIds is null || poly.VertexIds.Count < 3) return null;
if (!va.Vertices.TryGetValue((ushort)poly.VertexIds[0], out var a)) return null;
if (!va.Vertices.TryGetValue((ushort)poly.VertexIds[1], out var b)) return null;
if (!va.Vertices.TryGetValue((ushort)poly.VertexIds[2], out var c)) return null;
var n = Vector3.Cross(
new Vector3(b.Origin.X, b.Origin.Y, b.Origin.Z) - new Vector3(a.Origin.X, a.Origin.Y, a.Origin.Z),
new Vector3(c.Origin.X, c.Origin.Y, c.Origin.Z) - new Vector3(a.Origin.X, a.Origin.Y, a.Origin.Z));
return n.LengthSquared() < 1e-9f ? (Vector3?)null : Vector3.Normalize(n);
}
private static string DomAxis(Vector3 n)
{
float ax = MathF.Abs(n.X), ay = MathF.Abs(n.Y), az = MathF.Abs(n.Z);
if (ax >= ay && ax >= az) return n.X >= 0 ? "+X" : "-X";
if (ay >= ax && ay >= az) return n.Y >= 0 ? "+Y" : "-Y";
return n.Z >= 0 ? "+Z" : "-Z";
}
}

168
tests/AcDream.Core.Tests/Physics/Issue188FadingDoorMotionTableInspectionTests.cs Normal file
View file

@ -0,0 +1,168 @@
using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using DatReaderWriter;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Options;
using DatReaderWriter.Types;
using Xunit;
using Xunit.Abstractions;
using Env = System.Environment;
namespace AcDream.Core.Tests.Physics;
/// <summary>
/// #188 root-cause evidence (report-only): decode the REAL dat MotionTable
/// for the "Pedestal Weak Spot" fading-wall entity identified live
/// (guid 0x7C95B03B, MotionTableId 0x090000F9, Setup 0x02000D55). CONFIRMED:
/// its open cycle carries EtherealHook + TransparentPartHook + SoundTableHook
/// — a translucency-fade effect, not part-transform motion — and acdream has
/// no registered <see cref="IAnimationHookSink"/> that consumes Transparent/
/// NoDraw/Ethereal/ReplaceObject/Scale hooks (only Particle/Lighting/Audio are
/// wired). Kept as a reusable decoder for any future "why doesn't this
/// animate" question — swap the MotionTableId.
/// </summary>
public class Issue188FadingDoorMotionTableInspectionTests
{
private readonly ITestOutputHelper _out;
public Issue188FadingDoorMotionTableInspectionTests(ITestOutputHelper output) => _out = output;
private static string? DatDir()
{
var d = Env.GetEnvironmentVariable("ACDREAM_DAT_DIR")
?? Path.Combine(Env.GetFolderPath(Env.SpecialFolder.UserProfile), "Documents", "Asheron's Call");
return Directory.Exists(d) ? d : null;
}
[Fact]
public void Reflect_DatReaderWriter_HookTypes()
{
// Dump the DatReaderWriter assembly's hook-related type shapes so the
// real data-walk test below uses correct field names (no guessing).
var asm = typeof(MotionTable).Assembly;
_out.WriteLine($"assembly: {asm.FullName}");
foreach (var t in asm.GetTypes().Where(t => t.Name.Contains("Hook", StringComparison.OrdinalIgnoreCase)))
{
_out.WriteLine($"=== type {t.FullName} (base={t.BaseType?.Name}) ===");
foreach (var p in t.GetProperties(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly))
_out.WriteLine($" [prop] {p.PropertyType.Name} {p.Name}");
foreach (var f in t.GetFields(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly))
_out.WriteLine($" [field] {f.FieldType.Name} {f.Name}");
}
void DumpMembers(Type t, string label)
{
_out.WriteLine($"=== {label} ({t.FullName}) ===");
foreach (var p in t.GetProperties(BindingFlags.Public | BindingFlags.Instance))
_out.WriteLine($" [prop] {p.PropertyType} {p.Name}");
foreach (var f in t.GetFields(BindingFlags.Public | BindingFlags.Instance))
_out.WriteLine($" [field] {f.FieldType} {f.Name}");
}
DumpMembers(typeof(MotionData), "MotionData");
DumpMembers(asm.GetTypes().First(t => t.Name == "AnimData"), "AnimData");
DumpMembers(typeof(Animation), "Animation");
var frameType = asm.GetTypes().FirstOrDefault(t => t.Name is "AnimationFrame" or "AnimFrame");
if (frameType is not null) DumpMembers(frameType, frameType.Name);
var qdiType = asm.GetTypes().FirstOrDefault(t => t.Name.StartsWith("QualifiedDataId"));
if (qdiType is not null) DumpMembers(qdiType, qdiType.Name);
}
[Fact]
public void Dump_PedestalWeakSpot_MotionTable_HookContents()
{
var datDir = DatDir();
if (datDir is null) { _out.WriteLine("SKIP: no dat dir"); return; }
using var dats = new DatCollection(datDir, DatAccessType.Read);
const uint MotionTableId = 0x090000F9u; // live-captured from the Pedestal Weak Spot entity
var mtable = dats.Get<MotionTable>(MotionTableId);
if (mtable is null) { _out.WriteLine($"MotionTable 0x{MotionTableId:X8} NOT FOUND"); return; }
_out.WriteLine($"MotionTable 0x{MotionTableId:X8}: DefaultStyle=0x{(uint)mtable.DefaultStyle:X8}");
var allMotionData = new List<(string source, MotionData md)>();
foreach (var kv in mtable.Cycles) allMotionData.Add(($"Cycles[{kv.Key:X}]", kv.Value));
foreach (var kv in mtable.Modifiers) allMotionData.Add(($"Modifiers[{kv.Key:X}]", kv.Value));
foreach (var linkKv in mtable.Links)
foreach (var innerKv in linkKv.Value.MotionData)
allMotionData.Add(($"Links[{linkKv.Key:X}][{innerKv.Key:X}]", innerKv.Value));
_out.WriteLine($"total MotionData entries: {allMotionData.Count}");
var animIdsSeen = new HashSet<uint>();
var hookTypesSeen = new SortedSet<string>();
foreach (var (source, md) in allMotionData)
{
if (md?.Anims is null) continue;
foreach (var animData in md.Anims)
{
uint animId = GetAnimId(animData);
if (animId == 0 || !animIdsSeen.Add(animId)) continue;
var anim = dats.Get<Animation>(animId);
if (anim is null) { _out.WriteLine($" [{source}] anim 0x{animId:X8} NOT FOUND"); continue; }
int frameCount = 0, hookCount = 0;
int frameIdx = 0;
foreach (var frame in GetFrames(anim))
{
frameCount++;
foreach (var hook in GetHooks(frame))
{
hookCount++;
hookTypesSeen.Add(hook.GetType().Name);
// Dump every field's actual VALUE for this specific hook instance
// (not just the type) -- what alpha/duration retail authored.
var fieldDump = string.Join(" ", hook.GetType()
.GetFields(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly)
.Select(f => $"{f.Name}={f.GetValue(hook)}"));
_out.WriteLine($" frame[{frameIdx}] {hook.GetType().Name}: {fieldDump}");
}
frameIdx++;
}
_out.WriteLine($" [{source}] anim 0x{animId:X8}: frames={frameCount} hooks={hookCount}");
}
}
_out.WriteLine($"=== DISTINCT HOOK TYPES ACROSS ENTIRE TABLE: {(hookTypesSeen.Count == 0 ? "(none)" : string.Join(", ", hookTypesSeen))} ===");
}
private static object? GetMember(object obj, string name)
{
var t = obj.GetType();
var prop = t.GetProperty(name, BindingFlags.Public | BindingFlags.Instance);
if (prop is not null) return prop.GetValue(obj);
var field = t.GetField(name, BindingFlags.Public | BindingFlags.Instance);
return field?.GetValue(obj);
}
private static uint GetAnimId(object animData)
{
var val = GetMember(animData, "AnimId") ?? GetMember(animData, "Id");
if (val is null) return 0;
var dataId = GetMember(val, "DataId") ?? GetMember(val, "Id");
return dataId switch { uint u => u, int i => (uint)i, ulong ul => (uint)ul, _ => 0 };
}
private static IEnumerable<object> GetFrames(Animation anim)
{
var frames = (GetMember(anim, "PartFrames") ?? GetMember(anim, "Frames")) as IEnumerable;
if (frames is null) yield break;
foreach (var f in frames)
if (f is not null) yield return f;
}
private static IEnumerable<object> GetHooks(object frame)
{
var hooks = GetMember(frame, "Hooks") as IEnumerable;
if (hooks is null) yield break;
foreach (var h in hooks)
if (h is not null) yield return h;
}
}

209
tests/AcDream.Core.Tests/Physics/Motion/AnimSequenceNodeTests.cs Normal file
View file

@ -0,0 +1,209 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R1-P1 — verbatim <c>AnimSequenceNode</c> (Phase R plan, gap-map items
/// G1/G2/G16/G18). Oracle: r1-csequence-decomp.md §25-28 (ctors 0x00525d30 /
/// 0x00525f90, set_animation_id 0x00525d60, get_starting_frame 0x00525c80,
/// get_ending_frame 0x00525cb0, multiply_framerate 0x00525be0, get_pos_frame
/// 0x005247b0 / 0x00525c10).
///
/// KEY RETAIL SEMANTICS UNDER TEST:
/// - boundary pair is DIRECTION-AWARE and returns BARE INTS with NO epsilon
/// (ACE's epsilon subtraction is an ACE fabrication — P0-pins.md);
/// - multiply_framerate SWAPS low/high on a negative factor;
/// - set_animation_id clamps in a fixed order (high&lt;0 → num−1;
/// low≥num → num−1; high≥num → num−1; low&gt;high → high=low).
/// </summary>
public class AnimSequenceNodeTests
{
private sealed class FakeLoader : IAnimationLoader
{
private readonly Animation? _anim;
public FakeLoader(Animation? anim) => _anim = anim;
public Animation? LoadAnimation(uint id) => _anim;
}
private static Animation MakeAnim(int numFrames, bool posFrames = false)
{
var anim = new Animation();
for (int f = 0; f < numFrames; f++)
{
var pf = new AnimationFrame(1u);
pf.Frames.Add(new Frame { Origin = new Vector3(f, 0, 0), Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
if (posFrames)
anim.PosFrames.Add(new Frame { Origin = new Vector3(0, f, 0), Orientation = Quaternion.Identity });
}
return anim;
}
[Fact]
public void DefaultCtor_RetailDefaults()
{
// 0x00525d30: framerate=30f, low=-1, high=-1, anim=null.
var n = new AnimSequenceNode();
Assert.Equal(30f, n.Framerate);
Assert.Equal(-1, n.LowFrame);
Assert.Equal(-1, n.HighFrame);
Assert.False(n.HasAnim);
}
[Fact]
public void SetAnimationId_Zero_LeavesAnimNullAndFramesUnclamped()
{
// 0x00525d60: arg2==0 → anim=null; the clamp block is gated on
// anim != null, so low/high stay at their raw values.
var n = new AnimSequenceNode();
n.SetAnimationId(0, new FakeLoader(MakeAnim(10)));
Assert.False(n.HasAnim);
Assert.Equal(-1, n.LowFrame);
Assert.Equal(-1, n.HighFrame);
}
[Theory]
// low, high (pre-clamp), numFrames, expectedLow, expectedHigh
[InlineData(0, -1, 10, 0, 9)] // high<0 → num-1 ("play to end")
[InlineData(12, -1, 10, 9, 9)] // high<0 first, then low>=num → num-1
[InlineData(3, 15, 10, 3, 9)] // high>=num → num-1
[InlineData(15, 15, 10, 9, 9)] // both clamp to num-1
[InlineData(5, 2, 10, 5, 5)] // low>high after clamps → high=low
[InlineData(2, 7, 10, 2, 7)] // in-range untouched
public void SetAnimationId_ClampOrder(int low, int high, int numFrames, int expLow, int expHigh)
{
var n = new AnimSequenceNode { LowFrame = low, HighFrame = high };
n.SetAnimationId(0x0300ABCDu, new FakeLoader(MakeAnim(numFrames)));
Assert.True(n.HasAnim);
Assert.Equal(expLow, n.LowFrame);
Assert.Equal(expHigh, n.HighFrame);
}
[Theory]
// framerate, low, high, expectedStart, expectedEnd — BARE INTS, no epsilon
[InlineData(30f, 2, 7, 2, 8)] // forward: start=low, end=high+1
[InlineData(-30f, 2, 7, 8, 2)] // reverse: start=high+1, end=low
[InlineData(0f, 2, 7, 2, 8)] // zero framerate is NOT < 0 → forward
[InlineData(30f, 0, 0, 0, 1)] // single-frame forward
[InlineData(-30f, 0, 0, 1, 0)] // single-frame reverse
public void BoundaryPair_DirectionAware_BareInts(
float framerate, int low, int high, int expStart, int expEnd)
{
var n = new AnimSequenceNode { Framerate = framerate, LowFrame = low, HighFrame = high };
Assert.Equal(expStart, n.GetStartingFrame());
Assert.Equal(expEnd, n.GetEndingFrame());
}
[Fact]
public void MultiplyFramerate_Positive_NoSwap()
{
var n = new AnimSequenceNode { Framerate = 30f, LowFrame = 2, HighFrame = 7 };
n.MultiplyFramerate(2f);
Assert.Equal(60f, n.Framerate);
Assert.Equal(2, n.LowFrame);
Assert.Equal(7, n.HighFrame);
}
[Fact]
public void MultiplyFramerate_Negative_SwapsLowHigh()
{
// 0x00525be0: factor < 0 → swap(low_frame, high_frame), then
// framerate *= factor. Coupled with the direction-aware boundary
// pair (framerate now negative reads the swapped fields).
var n = new AnimSequenceNode { Framerate = 30f, LowFrame = 2, HighFrame = 7 };
n.MultiplyFramerate(-1f);
Assert.Equal(-30f, n.Framerate);
Assert.Equal(7, n.LowFrame);
Assert.Equal(2, n.HighFrame);
// Reverse playback boundaries against the SWAPPED fields:
// start = high_frame(2)+1 = 3?? — no: framerate<0 → start = high+1
// where high_frame is now 2 → 3; end = low_frame = 7.
Assert.Equal(3, n.GetStartingFrame());
Assert.Equal(7, n.GetEndingFrame());
}
[Fact]
public void MultiplyFramerate_DoubleNegative_RoundTrips()
{
var n = new AnimSequenceNode { Framerate = 30f, LowFrame = 2, HighFrame = 7 };
n.MultiplyFramerate(-1f);
n.MultiplyFramerate(-1f);
Assert.Equal(30f, n.Framerate);
Assert.Equal(2, n.LowFrame);
Assert.Equal(7, n.HighFrame);
}
[Fact]
public void GetPosFrame_NullAnim_ReturnsNull()
{
var n = new AnimSequenceNode();
Assert.Null(n.GetPosFrame(0));
}
[Fact]
public void GetPosFrame_OutOfRange_ReturnsNull()
{
// 0x00525c10: retail returns NULL out of range (ACE returns identity
// — an ACE-ism, gap G18: port the null).
var n = new AnimSequenceNode();
n.SetAnimationId(1, new FakeLoader(MakeAnim(3, posFrames: true)));
Assert.Null(n.GetPosFrame(-1));
Assert.Null(n.GetPosFrame(3));
Assert.NotNull(n.GetPosFrame(2));
}
[Fact]
public void GetPosFrame_DoubleOverload_Floors()
{
// 0x005247b0: floor(double) → int overload.
var n = new AnimSequenceNode();
n.SetAnimationId(1, new FakeLoader(MakeAnim(3, posFrames: true)));
var f = n.GetPosFrame(1.99);
Assert.NotNull(f);
Assert.Equal(1f, f!.Origin.Y); // frame index 1, not 2
}
[Fact]
public void GetPosFrame_AnimWithoutPosFrames_ReturnsNull()
{
var n = new AnimSequenceNode();
n.SetAnimationId(1, new FakeLoader(MakeAnim(3, posFrames: false)));
Assert.Null(n.GetPosFrame(0));
}
[Fact]
public void GetPartFrame_BoundsAndValue()
{
var n = new AnimSequenceNode();
n.SetAnimationId(1, new FakeLoader(MakeAnim(3)));
Assert.Null(n.GetPartFrame(-1));
Assert.Null(n.GetPartFrame(3));
var pf = n.GetPartFrame(2);
Assert.NotNull(pf);
Assert.Equal(2f, pf!.Frames[0].Origin.X);
}
[Fact]
public void CtorFromAnimData_CopiesThenClamps()
{
// 0x00525f90: copies framerate/low/high from AnimData then runs
// set_animation_id (which clamps against the resolved anim).
QualifiedDataId<Animation> qid = 0x03001234u;
var ad = new AnimData
{
AnimId = qid,
LowFrame = 0,
HighFrame = -1,
Framerate = 15f,
};
var n = new AnimSequenceNode(ad, new FakeLoader(MakeAnim(5)));
Assert.Equal(15f, n.Framerate);
Assert.Equal(0, n.LowFrame);
Assert.Equal(4, n.HighFrame); // -1 sentinel clamped to num-1
Assert.True(n.HasAnim);
}
}

1045
tests/AcDream.Core.Tests/Physics/Motion/CMotionTableTests.cs Normal file
View file

File diff suppressed because it is too large Load diff

142
tests/AcDream.Core.Tests/Physics/Motion/CSequencePhysicsTests.cs Normal file
View file

@ -0,0 +1,142 @@
using System;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.Types;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R1-P3 — <c>CSequence::apply_physics</c> (0x00524ab0) +
/// <c>Frame::rotate</c>/<c>grotate</c> (0x004525b0/0x005357a0) verbatim
/// (gap G7's math half). Oracle: r1-csequence-decomp.md §19 + raw decomp
/// reads of rotate/grotate this session.
///
/// KEY SEMANTICS:
/// - apply_physics takes MAGNITUDE from arg3 and SIGN from arg4
/// (copysign): origin += velocity·signed; rotate(omega·signed);
/// - rotate() maps the LOCAL rotation vector through the frame's
/// orientation to GLOBAL, then grotate premultiplies the axis-angle
/// quaternion (rotation applied in world space);
/// - grotate skips rotations with |v|² &lt; F_EPSILON² (0.000199999995²).
/// </summary>
public class CSequencePhysicsTests
{
private sealed class NullLoader : IAnimationLoader
{
public DatReaderWriter.DBObjs.Animation? LoadAnimation(uint id) => null;
}
private static void AssertVec(Vector3 expected, Vector3 actual, float tol = 1e-5f)
{
Assert.True((expected - actual).Length() < tol,
$"expected {expected}, got {actual}");
}
[Fact]
public void ApplyPhysics_PositiveSign_AddsVelocityTimesQuantum()
{
var seq = new CSequence(new NullLoader());
seq.SetVelocity(new Vector3(2, 0, 0));
var frame = new Frame { Origin = new Vector3(1, 1, 1), Orientation = Quaternion.Identity };
seq.ApplyPhysics(frame, quantum: 0.5, signSource: 1.0);
AssertVec(new Vector3(2, 1, 1), frame.Origin);
}
[Fact]
public void ApplyPhysics_CopySign_MagnitudeFromQuantum_SignFromSource()
{
// signed_quantum = copysign(fabs(quantum), sign_source): a NEGATIVE
// quantum with a POSITIVE sign source still moves forward; a
// negative sign source reverses.
var seq = new CSequence(new NullLoader());
seq.SetVelocity(new Vector3(2, 0, 0));
var f1 = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.ApplyPhysics(f1, quantum: -0.5, signSource: 1.0);
AssertVec(new Vector3(1, 0, 0), f1.Origin);
var f2 = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.ApplyPhysics(f2, quantum: 0.5, signSource: -1.0);
AssertVec(new Vector3(-1, 0, 0), f2.Origin);
}
[Fact]
public void ApplyPhysics_OmegaRotatesFrame_GlobalZ()
{
// omega = (0,0,π) for 0.5s → 90° about global Z: local +X maps to +Y.
var seq = new CSequence(new NullLoader());
seq.SetOmega(new Vector3(0, 0, MathF.PI));
var frame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.ApplyPhysics(frame, quantum: 0.5, signSource: 1.0);
AssertVec(new Vector3(0, 1, 0), Vector3.Transform(Vector3.UnitX, frame.Orientation));
}
[Fact]
public void GRotate_ComposesInGlobalSpace()
{
// Frame already rotated 90° about Z; grotate 90° about GLOBAL X.
// local +X: q maps it to +Y; global X-rot then maps +Y to +Z.
var frame = new Frame
{
Origin = Vector3.Zero,
Orientation = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 2f),
};
FrameOps.GRotate(frame, new Vector3(MathF.PI / 2f, 0, 0));
AssertVec(new Vector3(0, 0, 1), Vector3.Transform(Vector3.UnitX, frame.Orientation));
}
[Fact]
public void Rotate_LocalVector_MappedThroughOrientation()
{
// Frame rotated 90° about Z: a LOCAL X-axis rotation is a GLOBAL
// Y-axis rotation. rotate(local πX/2) on this frame must equal
// grotate(global πY/2).
var q0 = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 2f);
var viaLocal = new Frame { Origin = Vector3.Zero, Orientation = q0 };
FrameOps.Rotate(viaLocal, new Vector3(MathF.PI / 2f, 0, 0));
var viaGlobal = new Frame { Origin = Vector3.Zero, Orientation = q0 };
FrameOps.GRotate(viaGlobal, new Vector3(0, MathF.PI / 2f, 0));
AssertVec(
Vector3.Transform(Vector3.UnitX, viaGlobal.Orientation),
Vector3.Transform(Vector3.UnitX, viaLocal.Orientation));
AssertVec(
Vector3.Transform(Vector3.UnitZ, viaGlobal.Orientation),
Vector3.Transform(Vector3.UnitZ, viaLocal.Orientation));
}
[Fact]
public void GRotate_TinyRotation_Skipped()
{
// |v|² < F_EPSILON² → no-op (0x005357a0 early return).
var frame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
FrameOps.GRotate(frame, new Vector3(1e-5f, 0, 0));
Assert.Equal(Quaternion.Identity, frame.Orientation);
}
[Fact]
public void ApplyPhysics_ZeroPhysics_NoChange()
{
var seq = new CSequence(new NullLoader());
var frame = new Frame
{
Origin = new Vector3(3, 4, 5),
Orientation = Quaternion.CreateFromAxisAngle(Vector3.UnitY, 0.3f),
};
var beforeO = frame.Origin;
var beforeQ = frame.Orientation;
seq.ApplyPhysics(frame, 1.0, 1.0);
Assert.Equal(beforeO, frame.Origin);
Assert.Equal(beforeQ, frame.Orientation);
}
}

323
tests/AcDream.Core.Tests/Physics/Motion/CSequenceTests.cs Normal file
View file

@ -0,0 +1,323 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R1-P2 — verbatim <c>CSequence</c> container + list surgery (gap-map
/// G10/G11/G12/G14/G15/G20). Oracle: r1-csequence-decomp.md §1-§17, §20,
/// §24 (ctor 0x005249f0, clear 0x005255b0, clear_animations 0x00524dc0,
/// clear_physics 0x00524d50, remove_cyclic_anims 0x00524e40,
/// remove_link_animations 0x00524be0, remove_all_link_animations
/// 0x00524ca0, apricot 0x00524b40, append_animation 0x00525510,
/// set/combine/subtract physics 0x00524880-0x00524900,
/// multiply_cyclic_animation_fr 0x00524940, placement family
/// 0x00524970-0x005249d0).
///
/// KEY RETAIL SEMANTICS UNDER TEST:
/// - append_animation slides first_cyclic to the JUST-APPENDED node on
/// EVERY call (G10) and seeds curr_anim=head + frame_number=starting
/// only when curr_anim was null;
/// - remove_cyclic_anims snaps a removed curr_anim BACK to the previous
/// node at its get_ending_frame() (or 0.0 when none);
/// - remove_link_animations snaps a removed curr_anim FORWARD to
/// first_cyclic at its get_starting_frame();
/// - apricot trims consumed head nodes bounded by curr_anim AND
/// first_cyclic;
/// - clear (0x005255b0 raw body) resets placement_frame/id too — the
/// "2-instruction clear" note in the gap map was wrong, the raw body
/// is authority;
/// - physics accumulators live on the SEQUENCE (replace/combine/subtract);
/// - multiply_cyclic_animation_fr touches node framerates ONLY (G13).
/// </summary>
public class CSequenceTests
{
private sealed class MapLoader : IAnimationLoader
{
private readonly Dictionary<uint, Animation> _map = new();
public void Add(uint id, Animation anim) => _map[id] = anim;
public Animation? LoadAnimation(uint id) => _map.TryGetValue(id, out var a) ? a : null;
}
private static Animation MakeAnim(int numFrames)
{
var anim = new Animation();
for (int f = 0; f < numFrames; f++)
{
var pf = new AnimationFrame(1u);
pf.Frames.Add(new Frame { Origin = new Vector3(f, 0, 0), Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static AnimData Ad(uint animId, int low = 0, int high = -1, float framerate = 30f)
{
QualifiedDataId<Animation> qid = animId;
return new AnimData { AnimId = qid, LowFrame = low, HighFrame = high, Framerate = framerate };
}
private static (CSequence seq, MapLoader loader) NewSeq(params (uint id, int frames)[] anims)
{
var loader = new MapLoader();
foreach (var (id, frames) in anims)
loader.Add(id, MakeAnim(frames));
return (new CSequence(loader), loader);
}
// ── append_animation (G10) ──────────────────────────────────────────
[Fact]
public void Append_First_SeedsCurrAnimAndFrameNumber()
{
var (seq, _) = NewSeq((1u, 10));
seq.AppendAnimation(Ad(1u, low: 3));
Assert.Equal(1, seq.Count);
Assert.NotNull(seq.CurrAnim);
Assert.Same(seq.CurrAnim, seq.FirstCyclic);
Assert.Equal(3.0, seq.FrameNumber); // head.get_starting_frame()
}
[Fact]
public void Append_SlidesFirstCyclicToNewTail_EveryCall()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5), (3u, 4));
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
seq.AppendAnimation(Ad(3u));
Assert.Equal(3, seq.Count);
Assert.Equal(4 - 1, seq.FirstCyclic!.HighFrame); // the LAST appended (anim 3, 4 frames)
Assert.Equal(10 - 1, seq.CurrAnim!.HighFrame); // curr stays at head (anim 1)
Assert.Equal(0.0, seq.FrameNumber);
}
[Fact]
public void Append_UnresolvableAnim_Discarded()
{
var (seq, _) = NewSeq((1u, 10));
seq.AppendAnimation(Ad(999u)); // not in loader
Assert.Equal(0, seq.Count);
Assert.Null(seq.CurrAnim);
Assert.False(seq.HasAnims());
}
// ── remove_cyclic_anims (G11) ───────────────────────────────────────
[Fact]
public void RemoveCyclicAnims_CurrOutsideTail_KeepsCurr_FirstCyclicToNewTail()
{
// A (link) + B (cycle): first_cyclic == B, curr == A (head).
var (seq, _) = NewSeq((1u, 10), (2u, 5));
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
seq.RemoveCyclicAnims();
Assert.Equal(1, seq.Count); // B deleted
Assert.Equal(9, seq.CurrAnim!.HighFrame); // still A
Assert.Same(seq.CurrAnim, seq.FirstCyclic); // first_cyclic = new tail (A)
}
[Fact]
public void RemoveCyclicAnims_CurrInsideTail_SnapsBackToPrevAtEndingFrame()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5));
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
seq.SetCurrAnimForTest(1); // curr = B (index 1, inside cyclic tail)
seq.RemoveCyclicAnims();
Assert.Equal(1, seq.Count);
Assert.Equal(9, seq.CurrAnim!.HighFrame); // snapped back to A
Assert.Equal(10.0, seq.FrameNumber); // A.get_ending_frame() = high+1 = 10
}
[Fact]
public void RemoveCyclicAnims_SingleNode_EmptiesAndZeroes()
{
var (seq, _) = NewSeq((1u, 10));
seq.AppendAnimation(Ad(1u));
seq.RemoveCyclicAnims();
Assert.Equal(0, seq.Count);
Assert.Null(seq.CurrAnim);
Assert.Null(seq.FirstCyclic);
Assert.Equal(0.0, seq.FrameNumber);
}
// ── remove_link_animations / remove_all_link_animations (G11) ──────
[Fact]
public void RemoveLinkAnimations_RemovesPredecessorsOfFirstCyclic()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5), (3u, 4));
seq.AppendAnimation(Ad(1u)); // A
seq.AppendAnimation(Ad(2u)); // B
seq.AppendAnimation(Ad(3u)); // C = first_cyclic
seq.RemoveLinkAnimations(1); // removes B (immediate predecessor)
Assert.Equal(2, seq.Count);
Assert.Equal(9, seq.CurrAnim!.HighFrame); // A untouched (curr was A)
Assert.Equal(3, seq.FirstCyclic!.HighFrame); // C untouched
}
[Fact]
public void RemoveLinkAnimations_CurrRemoved_SnapsForwardToFirstCyclicStart()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5));
seq.AppendAnimation(Ad(1u)); // A (curr)
seq.AppendAnimation(Ad(2u)); // B = first_cyclic
seq.RemoveLinkAnimations(1); // removes A == curr
Assert.Equal(1, seq.Count);
Assert.Same(seq.FirstCyclic, seq.CurrAnim);
Assert.Equal(0.0, seq.FrameNumber); // B.get_starting_frame() = low = 0
}
[Fact]
public void RemoveAllLinkAnimations_RemovesEverythingBeforeFirstCyclic()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5), (3u, 4));
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
seq.AppendAnimation(Ad(3u)); // first_cyclic
seq.RemoveAllLinkAnimations();
Assert.Equal(1, seq.Count);
Assert.Same(seq.FirstCyclic, seq.CurrAnim);
Assert.Equal(3, seq.CurrAnim!.HighFrame);
}
// ── apricot (G11/G19) ───────────────────────────────────────────────
[Fact]
public void Apricot_HeadIsCurr_NoOp()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5));
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
seq.Apricot();
Assert.Equal(2, seq.Count);
}
[Fact]
public void Apricot_TrimsConsumedHeads_StopsAtCurr()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5), (3u, 4));
seq.AppendAnimation(Ad(1u)); // A (consumed)
seq.AppendAnimation(Ad(2u)); // B (curr)
seq.AppendAnimation(Ad(3u)); // C = first_cyclic
seq.SetCurrAnimForTest(1); // curr = B
seq.Apricot();
Assert.Equal(2, seq.Count); // A trimmed
Assert.Equal(4, seq.CurrAnim!.HighFrame); // B still curr
}
[Fact]
public void Apricot_BoundedByFirstCyclic_EvenIfCurrBeyond()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5), (3u, 4));
seq.AppendAnimation(Ad(1u)); // A
seq.AppendAnimation(Ad(2u)); // B
seq.AppendAnimation(Ad(3u)); // C = first_cyclic = curr target
seq.SetCurrAnimForTest(2); // curr = C
seq.Apricot();
Assert.Equal(1, seq.Count); // A and B trimmed; stops at first_cyclic
Assert.Equal(3, seq.CurrAnim!.HighFrame);
}
// ── physics accumulators (G12) ──────────────────────────────────────
[Fact]
public void Physics_SetCombineSubtract()
{
var (seq, _) = NewSeq();
seq.SetVelocity(new Vector3(1, 2, 3));
seq.SetOmega(new Vector3(0, 0, 1));
seq.CombinePhysics(new Vector3(1, 0, 0), new Vector3(0, 0, 0.5f));
Assert.Equal(new Vector3(2, 2, 3), seq.Velocity);
Assert.Equal(new Vector3(0, 0, 1.5f), seq.Omega);
seq.SubtractPhysics(new Vector3(2, 2, 3), new Vector3(0, 0, 1.5f));
Assert.Equal(Vector3.Zero, seq.Velocity);
Assert.Equal(Vector3.Zero, seq.Omega);
}
// ── multiply_cyclic_animation_fr (G13) ──────────────────────────────
[Fact]
public void MultiplyCyclicFramerate_TouchesOnlyCyclicTailFramerates()
{
var (seq, _) = NewSeq((1u, 10), (2u, 5));
seq.AppendAnimation(Ad(1u, framerate: 30f)); // A (link, pre-cyclic after next append)
seq.AppendAnimation(Ad(2u, framerate: 30f)); // B = first_cyclic
seq.MultiplyCyclicAnimationFramerate(2f);
Assert.Equal(30f, seq.CurrAnim!.Framerate); // A untouched
Assert.Equal(60f, seq.FirstCyclic!.Framerate); // B scaled
// Velocity/Omega untouched (retail scales those via
// subtract/combine_motion in R2, never here).
Assert.Equal(Vector3.Zero, seq.Velocity);
}
// ── clear family (G20 corrected) ────────────────────────────────────
[Fact]
public void Clear_WipesAnimsPhysicsAndPlacement()
{
var (seq, _) = NewSeq((1u, 10));
seq.AppendAnimation(Ad(1u));
seq.SetVelocity(new Vector3(1, 1, 1));
var pf = new AnimationFrame(1u);
seq.SetPlacementFrame(pf, 0x65u);
seq.Clear();
Assert.Equal(0, seq.Count);
Assert.Null(seq.CurrAnim);
Assert.Equal(0.0, seq.FrameNumber);
Assert.Equal(Vector3.Zero, seq.Velocity);
Assert.Null(seq.PlacementFrame); // raw 0x005255b0 resets placement too
Assert.Equal(0u, seq.PlacementFrameId);
}
// ── placement + accessors (G14) ─────────────────────────────────────
[Fact]
public void GetCurrAnimframe_PlacementFallback_WhenNoCurrAnim()
{
var (seq, _) = NewSeq();
var pf = new AnimationFrame(1u);
seq.SetPlacementFrame(pf, 0x65u);
Assert.Same(pf, seq.GetCurrAnimframe());
}
[Fact]
public void GetCurrAnimframe_FlooredFrameLookup()
{
var (seq, _) = NewSeq((1u, 10));
seq.AppendAnimation(Ad(1u));
seq.FrameNumber = 2.9;
var frame = seq.GetCurrAnimframe();
Assert.NotNull(frame);
Assert.Equal(2f, frame!.Frames[0].Origin.X); // frame index 2
Assert.Equal(2, seq.GetCurrFrameNumber());
}
}

269
tests/AcDream.Core.Tests/Physics/Motion/CSequenceUpdateTests.cs Normal file
View file

@ -0,0 +1,269 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Enums;
using DatReaderWriter.Types;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R1-P4 — the frame-advance core: <c>update_internal</c> (0x005255d0),
/// <c>update</c> (0x00525b80), <c>advance_to_next_animation</c>
/// (0x005252b0), <c>execute_hooks</c> (0x00524830) — gaps
/// G3/G4/G5/G6/G8/G9/G19.
///
/// Skeleton per the ACE-verified structure (P0-pins.md): overshoot →
/// clamp to the RAW high/low frame + leftover carry + animDone →
/// per-crossed-frame pose/physics/hook loop → AnimDone gate
/// (list HEAD != first_cyclic) → advance (pose-out both directions,
/// forward wraps to first_cyclic, reverse wraps to the LIST TAIL) →
/// carry the leftover (P0 pin) → loop. NO safety cap, NO boundary
/// epsilon.
/// </summary>
public class CSequenceUpdateTests
{
private sealed class MapLoader : IAnimationLoader
{
private readonly Dictionary<uint, Animation> _map = new();
public void Add(uint id, Animation anim) => _map[id] = anim;
public Animation? LoadAnimation(uint id) => _map.TryGetValue(id, out var a) ? a : null;
}
private sealed class RecordingHookQueue : IAnimHookQueue
{
public readonly List<string> Events = new();
public void AddAnimHook(AnimationHook hook)
=> Events.Add($"hook:{((TaggedHook)hook).Tag}:{hook.Direction}");
public void AddAnimDoneHook() => Events.Add("ANIMDONE");
}
/// <summary>Hook subclass carrying a test tag (frame index).</summary>
private sealed class TaggedHook : AnimationHook
{
public string Tag = "";
public override AnimationHookType HookType => (AnimationHookType)0;
}
/// <summary>numFrames frames; one Forward-direction tagged hook per frame.</summary>
private static Animation MakeAnim(int numFrames, bool posFrames = false, string hookPrefix = "f")
{
var anim = new Animation();
for (int f = 0; f < numFrames; f++)
{
var pf = new AnimationFrame(1u);
pf.Frames.Add(new Frame { Origin = new Vector3(f, 0, 0), Orientation = Quaternion.Identity });
pf.Hooks.Add(new TaggedHook { Tag = $"{hookPrefix}{f}", Direction = AnimationHookDir.Both });
anim.PartFrames.Add(pf);
if (posFrames)
anim.PosFrames.Add(new Frame { Origin = new Vector3(1, 0, 0), Orientation = Quaternion.Identity });
}
return anim;
}
private static AnimData Ad(uint animId, float framerate = 30f, int low = 0, int high = -1)
{
QualifiedDataId<Animation> qid = animId;
return new AnimData { AnimId = qid, LowFrame = low, HighFrame = high, Framerate = framerate };
}
private static (CSequence seq, RecordingHookQueue hooks) Cyclic(int frames, float framerate = 30f)
{
var loader = new MapLoader();
loader.Add(1u, MakeAnim(frames));
var seq = new CSequence(loader);
var hooks = new RecordingHookQueue();
seq.HookObj = hooks;
seq.AppendAnimation(Ad(1u, framerate));
return (seq, hooks);
}
// ── forward advance basics (G3) ─────────────────────────────────────
[Fact]
public void Forward_SingleTick_AdvancesOneFrame_FiresExitedFrameHook()
{
var (seq, hooks) = Cyclic(5);
seq.Update(1.0 / 30.0, null);
Assert.Equal(1.0, seq.FrameNumber, 9);
Assert.Equal(new[] { "hook:f0:Both" }, hooks.Events);
}
[Fact]
public void Forward_ExactBoundaryLanding_NoAdvance()
{
// Boundary test is STRICT (>): landing exactly at high_frame+0.0
// integer positions must NOT advance (the G3 bug class: acdream's
// old epsilon-shifted boundary reclassified these).
var (seq, hooks) = Cyclic(5);
seq.FrameNumber = 3.5;
seq.Update(0.5 / 30.0, null); // lands exactly at 4.0 == high_frame
Assert.Equal(4.0, seq.FrameNumber, 9);
Assert.Equal(new[] { "hook:f3:Both" }, hooks.Events); // crossed 3→4
Assert.DoesNotContain("ANIMDONE", hooks.Events);
}
[Fact]
public void Forward_CyclicWrap_NoAnimDone_RestartsAtStartingFrame()
{
// Single cyclic node: overshoot wraps to itself via first_cyclic;
// head == first_cyclic → NO AnimDoneHook (G5's structural gate).
var (seq, hooks) = Cyclic(3);
seq.FrameNumber = 2.0;
seq.Update(1.0 / 30.0, null); // 2→3 > high(2) → clamp, advance, wrap
Assert.Equal(0.0, seq.FrameNumber, 9);
Assert.DoesNotContain("ANIMDONE", hooks.Events);
Assert.Same(seq.FirstCyclic, seq.CurrAnim);
}
// ── multi-node fast-forward + the P0-pinned carry (G3/G5) ───────────
[Fact]
public void Forward_LinkToCycle_FiresAnimDone_AndCarriesLeftover()
{
// link (2 frames) + cycle (4 frames): a 0.1s tick (3 frames at
// 30fps) exhausts the link (2 frames) and carries 1 frame of time
// into the cycle. Retail order: link's crossed-frame hooks →
// AnimDoneHook (head != first_cyclic) → cycle's crossed hooks.
var loader = new MapLoader();
loader.Add(1u, MakeAnim(2, hookPrefix: "link"));
loader.Add(2u, MakeAnim(4, hookPrefix: "cyc"));
var seq = new CSequence(loader);
var hooks = new RecordingHookQueue();
seq.HookObj = hooks;
seq.AppendAnimation(Ad(1u)); // link — first_cyclic slides…
seq.AppendAnimation(Ad(2u)); // …to the cycle
seq.Update(0.1, null); // 3 frames of time
// link: FrameNumber 0→3, clamp to high(1), leftover = 1 frame;
// crossing fires link f0 only (floor(1)>0), then AnimDone, then
// advance → cycle at starting(0); carry 1/30 → cycle 0→1 fires cyc f0.
Assert.Equal(new[] { "hook:link0:Both", "ANIMDONE", "hook:cyc0:Both" }, hooks.Events);
Assert.Equal(1.0, seq.FrameNumber, 6); // the carry (P0 pin) — zeroing would leave 0.0
Assert.Same(seq.FirstCyclic, seq.CurrAnim); // now inside the cycle
}
// ── reverse playback (G3/G9) ────────────────────────────────────────
[Fact]
public void Reverse_DescendingHooks_BackwardDirection()
{
// Natively-reverse node (framerate −30): seeded at starting =
// high+1 = 5. Each tick fires the hook of the frame being LEFT
// (the pre-tick floor index), descending; the very first tick's
// index (5 = high+1) is OOB → null part frame → no hook, exactly
// the retail structure.
var (seq, hooks) = Cyclic(5, framerate: -30f);
Assert.Equal(5.0, seq.FrameNumber, 9); // get_starting_frame = high+1
seq.Update(1.0 / 30.0, null); // 5→4 (leaves OOB index 5 — nothing)
seq.Update(1.0 / 30.0, null); // 4→3 (leaves frame 4)
seq.Update(1.0 / 30.0, null); // 3→2 (leaves frame 3)
Assert.Equal(2.0, seq.FrameNumber, 9);
Assert.Equal(new[] { "hook:f4:Both", "hook:f3:Both" }, hooks.Events);
}
[Fact]
public void Reverse_AdvanceWrapsToListTail()
{
// Two nodes A(reverse),B(forward): exhausting A backward wraps
// curr_anim to the LIST TAIL (B) — retail's asymmetric wrap (G9).
var loader = new MapLoader();
loader.Add(1u, MakeAnim(3, hookPrefix: "a"));
loader.Add(2u, MakeAnim(4, hookPrefix: "b"));
var seq = new CSequence(loader);
var hooks = new RecordingHookQueue();
seq.HookObj = hooks;
seq.AppendAnimation(Ad(1u, framerate: -30f)); // A — curr seeds here
seq.AppendAnimation(Ad(2u)); // B = first_cyclic = tail
seq.FrameNumber = 0.5; // mid-window of A
seq.Update(0.02, null); // frametime = −0.6 → crosses low(0)
// After the reverse advance, curr must have left A via the TAIL
// wrap (B), whatever the carry then does within B.
Assert.NotNull(seq.CurrAnim);
Assert.Equal(3, seq.CurrAnim!.HighFrame); // B (4 frames → high 3)
}
// ── stationary / degenerate (G8 + else-branch) ──────────────────────
[Fact]
public void ZeroFramerate_PhysicsOnlyAndReturn()
{
var (seq, hooks) = Cyclic(3, framerate: 0f);
seq.SetVelocity(new Vector3(2, 0, 0));
var frame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.Update(0.5, frame);
// frametime == 0 → apply_physics(frame, elapsed, elapsed) then return.
Assert.Equal(1.0f, frame.Origin.X, 5);
Assert.Empty(hooks.Events);
Assert.Equal(0.0, seq.FrameNumber, 9);
}
[Fact]
public void EmptyList_Update_AppliesAccumulatedPhysics()
{
// update (0x00525b80): empty anim_list + frame != null →
// apply_physics(frame, elapsed, elapsed) — free-fall/knockback
// with no animation (G8).
var seq = new CSequence(new MapLoader());
seq.SetVelocity(new Vector3(0, 3, 0));
var frame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.Update(2.0, frame);
Assert.Equal(6.0f, frame.Origin.Y, 5);
}
// ── root motion into the caller Frame (G7 wiring half) ──────────────
[Fact]
public void Forward_PosFrames_CombinedIntoCallerFrame()
{
// Each crossed frame combines the node's pos_frame into the caller
// Frame (retail root motion): 2 crossed frames → +2 X.
var loader = new MapLoader();
loader.Add(1u, MakeAnim(5, posFrames: true));
var seq = new CSequence(loader);
seq.AppendAnimation(Ad(1u));
var frame = new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity };
seq.Update(2.0 / 30.0, frame); // crosses frames 0 and 1
Assert.Equal(2.0f, frame.Origin.X, 5);
Assert.Equal(2.0, seq.FrameNumber, 9);
}
// ── update entry contract (G19) ─────────────────────────────────────
[Fact]
public void Update_RunsApricot_TrimmingConsumedLinkNodes()
{
// After the link→cycle advance, apricot (called by update) frees
// the consumed link node.
var loader = new MapLoader();
loader.Add(1u, MakeAnim(2, hookPrefix: "link"));
loader.Add(2u, MakeAnim(4, hookPrefix: "cyc"));
var seq = new CSequence(loader);
seq.AppendAnimation(Ad(1u));
seq.AppendAnimation(Ad(2u));
Assert.Equal(2, seq.Count);
seq.Update(0.1, null); // exhausts the link, advances into the cycle
Assert.Equal(1, seq.Count); // link trimmed by apricot
Assert.Same(seq.FirstCyclic, seq.CurrAnim);
}
}

133
tests/AcDream.Core.Tests/Physics/Motion/ConstraintManagerTests.cs Normal file
View file

@ -0,0 +1,133 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5 conformance — <see cref="ConstraintManager"/> (retail 0x00556090-…).
/// The leash-band taper + the 90 % IsFullyConstrained jump gate (port-plan §2b/§2c).
/// </summary>
public sealed class ConstraintManagerTests
{
private static (R5Host host, ConstraintManager cm) Setup()
{
var world = new Dictionary<uint, R5Host>();
var host = new R5Host(10u, world);
return (host, new ConstraintManager(host));
}
private static Position Anchor(float x) => new(1u, new Vector3(x, 0f, 0f), Quaternion.Identity);
[Fact]
public void ConstrainTo_InitializesOffsetToCurrentDistanceFromAnchor()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
cm.ConstrainTo(Anchor(5f), startDistance: 2f, maxDistance: 10f);
Assert.True(cm.IsConstrained);
Assert.Equal(5f, cm.ConstraintPosOffset, 3); // distance(anchor(5,0,0), self(0,0,0))
}
[Fact]
public void IsFullyConstrained_TrueOnlyBeyond90PercentOfMax()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
cm.ConstrainTo(Anchor(8f), 2f, 10f); // offset 8, 90% of 10 = 9 → 8 < 9
Assert.False(cm.IsFullyConstrained());
cm.ConstrainTo(Anchor(9.5f), 2f, 10f); // offset 9.5 > 9
Assert.True(cm.IsFullyConstrained());
}
[Fact]
public void IsFullyConstrained_FalseWhenNotConstrainedYet()
{
var (_, cm) = Setup();
Assert.False(cm.IsFullyConstrained()); // max 0 → 0 < 0 is false
}
[Fact]
public void AdjustOffset_InBand_AppliesLinearTaper()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
host.InContact = true;
cm.ConstrainTo(Anchor(5f), startDistance: 2f, maxDistance: 10f); // offset 5 in (2,10)
var frame = new MotionDeltaFrame { Origin = new Vector3(1f, 0f, 0f) };
cm.AdjustOffset(frame, 0.1);
// taper = (10-5)/(10-2) = 5/8 = 0.625.
Assert.Equal(0.625f, frame.Origin.X, 3);
Assert.Equal(0.625f, cm.ConstraintPosOffset, 3); // recomputed = |offset|
}
[Fact]
public void AdjustOffset_PastMax_HardClampsToZero()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
host.InContact = true;
cm.ConstrainTo(Anchor(20f), 2f, 10f); // offset 20 >= max 10
var frame = new MotionDeltaFrame { Origin = new Vector3(1f, 0f, 0f) };
cm.AdjustOffset(frame, 0.1);
Assert.Equal(Vector3.Zero, frame.Origin);
}
[Fact]
public void AdjustOffset_BelowStart_PassesThrough()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
host.InContact = true;
cm.ConstrainTo(Anchor(1f), startDistance: 2f, maxDistance: 10f); // offset 1 < start 2
var frame = new MotionDeltaFrame { Origin = new Vector3(1f, 0f, 0f) };
cm.AdjustOffset(frame, 0.1);
Assert.Equal(1f, frame.Origin.X, 3); // unscaled
Assert.Equal(1f, cm.ConstraintPosOffset, 3);
}
[Fact]
public void AdjustOffset_Airborne_SkipsClampButStillTracksLength()
{
var (host, cm) = Setup();
host.SetOrigin(Vector3.Zero);
host.InContact = false; // airborne
cm.ConstrainTo(Anchor(20f), 2f, 10f); // would clamp if grounded
var frame = new MotionDeltaFrame { Origin = new Vector3(3f, 4f, 0f) };
cm.AdjustOffset(frame, 0.1);
Assert.Equal(new Vector3(3f, 4f, 0f), frame.Origin); // untouched while airborne
Assert.Equal(5f, cm.ConstraintPosOffset, 3); // |(3,4,0)| = 5, still updated
}
[Fact]
public void AdjustOffset_NotConstrained_IsNoOp()
{
var (host, cm) = Setup();
var frame = new MotionDeltaFrame { Origin = new Vector3(7f, 0f, 0f) };
cm.AdjustOffset(frame, 0.1);
Assert.Equal(new Vector3(7f, 0f, 0f), frame.Origin);
}
[Fact]
public void UnConstrain_ClearsFlag()
{
var (host, cm) = Setup();
cm.ConstrainTo(Anchor(5f), 2f, 10f);
cm.UnConstrain();
Assert.False(cm.IsConstrained);
}
}

217
tests/AcDream.Core.Tests/Physics/Motion/InterpretedMotionStateActionFifoTests.cs Normal file
View file

@ -0,0 +1,217 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R3-W1 — action FIFO discipline + <c>ApplyMotion</c>/<c>RemoveMotion</c>
/// field effects on <see cref="InterpretedMotionState"/> (closes J2). Oracle:
/// docs/research/named-retail/acclient_2013_pseudo_c.txt — verbatim bodies
/// quoted in MotionInterpreter.cs doc comments:
/// <c>InterpretedMotionState::AddAction</c> (0x0051e9e0), <c>RemoveAction</c>
/// (0x0051ead0), <c>GetNumActions</c> (0x0051eb00), <c>ApplyMotion</c>
/// (0x0051ea40), <c>RemoveMotion</c> (0x0051e790).
/// </summary>
public sealed class InterpretedMotionStateActionFifoTests
{
[Fact]
public void Default_HasEmptyActionsAndZeroCount()
{
var ims = InterpretedMotionState.Default();
Assert.Empty(ims.Actions);
Assert.Equal(0u, ims.GetNumActions());
}
// ── AddAction / RemoveAction / GetNumActions FIFO discipline ──────────
[Fact]
public void AddAction_AppendsInOrder_GetNumActionsCounts()
{
var ims = InterpretedMotionState.Default();
ims.AddAction(0x1000004Bu, 1.0f, 1, autonomous: false);
ims.AddAction(0x10000050u, 1.5f, 2, autonomous: true);
Assert.Equal(2u, ims.GetNumActions());
Assert.Equal((ushort)0x004Bu, ims.Actions[0].Command);
Assert.Equal((ushort)0x0050u, ims.Actions[1].Command);
}
[Fact]
public void RemoveAction_PopsHeadFirst_FifoOrder()
{
var ims = InterpretedMotionState.Default();
ims.AddAction(0x1000004Bu, 1.0f, 1, autonomous: false);
ims.AddAction(0x10000050u, 1.5f, 2, autonomous: true);
uint first = ims.RemoveAction();
uint second = ims.RemoveAction();
Assert.Equal(0x004Bu, first);
Assert.Equal(0x0050u, second);
Assert.Equal(0u, ims.GetNumActions());
}
[Fact]
public void RemoveAction_Empty_ReturnsZero()
{
var ims = InterpretedMotionState.Default();
Assert.Equal(0u, ims.RemoveAction());
}
[Fact]
public void GetNumActions_DefaultStruct_NoNullRef()
{
// Defensive: a bare default(InterpretedMotionState) (bypassing
// .Default()) must not NRE on GetNumActions/Actions/RemoveAction —
// the lazy-list field starts null.
InterpretedMotionState bare = default;
Assert.Equal(0u, bare.GetNumActions());
Assert.Empty(bare.Actions);
Assert.Equal(0u, bare.RemoveAction());
}
// ── DoMotion's depth-cap gate consumes this directly (documentation) ──
[Fact]
public void GetNumActions_SixQueued_MeetsDoMotionDepthCapThreshold()
{
// DoMotion (0x00528d20 @306159) rejects with 0x45 when an
// action-class motion arrives AND GetNumActions() >= 6. W1 only
// proves the counter is correct; the gate itself lands in W5.
var ims = InterpretedMotionState.Default();
for (uint i = 0; i < 6; i++)
ims.AddAction(0x10000000u + i, 1.0f, i, false);
Assert.Equal(6u, ims.GetNumActions());
Assert.True(ims.GetNumActions() >= 6);
}
// ── ApplyMotion field effects (0x0051ea40) ─────────────────────────────
[Fact]
public void ApplyMotion_TurnRight_SetsTurnCommandAndSpeed()
{
var ims = InterpretedMotionState.Default();
var p = new MovementParameters { Speed = 1.5f };
ims.ApplyMotion(0x6500000du, p);
Assert.Equal(0x6500000du, ims.TurnCommand);
Assert.Equal(1.5f, ims.TurnSpeed);
}
[Fact]
public void ApplyMotion_SideStepRight_SetsSideStepCommandAndSpeed()
{
var ims = InterpretedMotionState.Default();
var p = new MovementParameters { Speed = 1.248f };
ims.ApplyMotion(0x6500000fu, p);
Assert.Equal(0x6500000fu, ims.SideStepCommand);
Assert.Equal(1.248f, ims.SideStepSpeed);
}
[Fact]
public void ApplyMotion_ForwardClassMotion_SetsForwardCommandAndSpeed()
{
// Unlike RawMotionState::ApplyMotion, InterpretedMotionState's
// forward-class branch has NO RunForward exclusion — every
// forward-class id (bit 0x40000000) writes forward_command.
var ims = InterpretedMotionState.Default();
var p = new MovementParameters { Speed = 2.94f };
ims.ApplyMotion(0x44000007u, p); // RunForward
Assert.Equal(0x44000007u, ims.ForwardCommand);
Assert.Equal(2.94f, ims.ForwardSpeed);
}
[Fact]
public void ApplyMotion_StyleClassMotion_ResetsForwardToReady_SetsCurrentStyle()
{
var ims = InterpretedMotionState.Default();
ims.ForwardCommand = 0x45000005u;
var p = new MovementParameters();
ims.ApplyMotion(0x80000042u, p);
Assert.Equal(0x41000003u, ims.ForwardCommand);
Assert.Equal(0x80000042u, ims.CurrentStyle);
}
[Fact]
public void ApplyMotion_ActionClassMotion_AddsAction()
{
var ims = InterpretedMotionState.Default();
var p = new MovementParameters { Speed = 1.0f, ActionStamp = 7u, Autonomous = true };
ims.ApplyMotion(0x1000004Bu, p);
Assert.Equal(1u, ims.GetNumActions());
var a = ims.Actions[0];
Assert.Equal((ushort)0x004Bu, a.Command);
Assert.Equal(1.0f, a.Speed);
Assert.Equal((ushort)7u, a.Stamp);
Assert.True(a.Autonomous);
}
// ── RemoveMotion field effects (0x0051e790) ────────────────────────────
[Fact]
public void RemoveMotion_TurnRightExact_ClearsTurnCommand()
{
var ims = InterpretedMotionState.Default();
ims.TurnCommand = 0x6500000du;
ims.RemoveMotion(0x6500000du);
Assert.Equal(0u, ims.TurnCommand);
}
[Fact]
public void RemoveMotion_TurnLeftExact_DoesNotMatchTurnBranch_FallsThroughToStyleCheck()
{
// Asymmetric vs RawMotionState::RemoveMotion: InterpretedMotionState
// only exact-matches 0x6500000d (TurnRight) for the turn branch, NOT
// 0x6500000e (TurnLeft) — verbatim per the raw decomp.
var ims = InterpretedMotionState.Default();
ims.TurnCommand = 0x6500000eu;
ims.RemoveMotion(0x6500000eu);
// Falls through: bit 0x40000000 clear, arg2 (0x6500000e) is not
// negative and != current_style (0x8000003D default) -> no-op.
Assert.Equal(0x6500000eu, ims.TurnCommand); // untouched
}
[Fact]
public void RemoveMotion_SideStepRightExact_ClearsSideStepCommand()
{
var ims = InterpretedMotionState.Default();
ims.SideStepCommand = 0x6500000fu;
ims.RemoveMotion(0x6500000fu);
Assert.Equal(0u, ims.SideStepCommand);
}
[Fact]
public void RemoveMotion_ForwardClassMotion_MatchingCommand_ResetsToReady()
{
var ims = InterpretedMotionState.Default();
ims.ForwardCommand = 0x45000005u;
ims.ForwardSpeed = 3.0f;
ims.RemoveMotion(0x45000005u);
Assert.Equal(0x41000003u, ims.ForwardCommand);
Assert.Equal(1f, ims.ForwardSpeed);
}
[Fact]
public void RemoveMotion_StyleClassMotion_MatchingCurrentStyle_ResetsToNonCombat()
{
var ims = InterpretedMotionState.Default();
ims.CurrentStyle = 0x80000042u;
ims.RemoveMotion(0x80000042u);
Assert.Equal(0x8000003du, ims.CurrentStyle);
}
}

97
tests/AcDream.Core.Tests/Physics/Motion/Issue174LinkStripDrainTests.cs Normal file
View file

@ -0,0 +1,97 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.Core.Tests.Physics.Motion;
// ─────────────────────────────────────────────────────────────────────────────
// #174 pin (2026-07-05): the RemoveLinkAnimations seam must be retail
// CPhysicsObj::RemoveLinkAnimations 0x0050fe20 — a TAILCALL to
// CPartArray::HandleEnterWorld 0x00517d70 → MotionTableManager::
// HandleEnterWorld 0x0051bdd0: CSequence::remove_all_link_animations PLUS a
// full pending_animations drain (`while (head) AnimationDone(0)`), each pop
// relaying MotionDone → CMotionInterp pops its pending_motions node in
// lockstep.
//
// The pre-fix binding was the bare sequence strip: every LeaveGround (jump)
// removed the link animations that queued MotionTableManager nodes were
// counting down on, orphaning them (NumAnims > 0, animations gone). Both
// queues then dammed permanently — MotionsPending() never drained at rest —
// and BeginTurnToHeading/BeginMoveForward (retail 0x00529b90 motions_pending
// gate) starved every armed moveto: ACE's walk-to-door mt-6 armed but the
// body never walked; the close-range Use turn never completed so the
// deferred action was silently eaten. Live evidence: launch-174-autowalk.log
// (last player pending=False at the first MovementJump press; old jump
// motions still completing at rest minutes later).
// ─────────────────────────────────────────────────────────────────────────────
public class Issue174LinkStripDrainTests
{
private readonly ITestOutputHelper _out;
public Issue174LinkStripDrainTests(ITestOutputHelper output) => _out = output;
/// <summary>
/// The jam repro: queue motions (link + cycle nodes land in BOTH the
/// interp's pending_motions and the manager's pending_animations), then
/// fire the LeaveGround-side seam. With the retail HandleEnterWorld
/// binding both queues drain to empty; the pre-fix bare-strip binding
/// left both non-empty forever.
/// </summary>
[Fact]
public void RemoveLinkAnimationsSeam_DrainsBothQueues()
{
var h = new RemoteChaseHarness(_out);
// Drive a motion burst — walk, run, stop — the shape a player's
// pre-jump input produces. Each successful dispatch pairs an interp
// node with a manager node.
var p = new MovementParameters();
h.Interp.DoMotion(MotionCommand.WalkForward, p);
h.Interp.set_hold_run(true, interrupt: false);
h.Interp.StopMotion(MotionCommand.WalkForward, p);
Assert.True(h.Interp.MotionsPending(),
"precondition: the burst must leave pending interp nodes");
Assert.NotEmpty(h.Seq.Manager.PendingAnimations);
// The LeaveGround seam (retail CMotionInterp::LeaveGround 0x00528b00
// fires CPhysicsObj::RemoveLinkAnimations).
h.Interp.RemoveLinkAnimations!.Invoke();
Assert.False(h.Interp.MotionsPending(),
"HandleEnterWorld's drain must pop every pending interp node " +
"(retail: each AnimationDone(0) relays MotionDone)");
Assert.Empty(h.Seq.Manager.PendingAnimations);
}
/// <summary>
/// The post-jump livability pin: after the seam fires mid-activity, a
/// NEW moveto-style dispatch must be able to queue and complete — the
/// #174 symptom was that BeginTurnToHeading's motions_pending gate never
/// re-opened after a jump, permanently starving armed movetos.
/// </summary>
[Fact]
public void AfterSeamDrain_NewMotionsQueueAndComplete()
{
var h = new RemoteChaseHarness(_out);
var p = new MovementParameters();
// Pre-jump activity, then the jump's LeaveGround strip+drain.
h.Interp.DoMotion(MotionCommand.WalkForward, p);
h.Interp.RemoveLinkAnimations!.Invoke();
Assert.False(h.Interp.MotionsPending());
// A fresh dispatch (the armed moveto's turn) queues...
h.Interp.DoMotion(MotionCommand.TurnRight, p);
Assert.True(h.Interp.MotionsPending());
// ...and the normal completion path (the manager's queue feeding
// MotionDone) drains it — the gate re-opens.
while (h.Seq.Manager.PendingAnimations.GetEnumerator() is var e && e.MoveNext())
h.Seq.Manager.AnimationDone(success: true);
h.Seq.Manager.CheckForCompletedMotions();
Assert.False(h.Interp.MotionsPending(),
"the normal AnimationDone → MotionDone chain must drain the new node");
}
}

33
tests/AcDream.Core.Tests/Physics/Motion/MotionNodeTests.cs Normal file
View file

@ -0,0 +1,33 @@
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R3-W1 — <c>CMotionInterp::MotionNode</c> shape pin. Oracle:
/// acclient.h:53293 (struct #5857). W2 consumes this as the
/// <c>pending_motions</c> element type; W1 only ports the shape.
/// </summary>
public sealed class MotionNodeTests
{
[Fact]
public void Ctor_StoresAllThreeFields()
{
var node = new MotionNode(ContextId: 7u, Motion: 0x41000003u, JumpErrorCode: 0x48u);
Assert.Equal(7u, node.ContextId);
Assert.Equal(0x41000003u, node.Motion);
Assert.Equal(0x48u, node.JumpErrorCode);
}
[Fact]
public void Equality_IsValueBased()
{
var a = new MotionNode(1u, 2u, 3u);
var b = new MotionNode(1u, 2u, 3u);
var c = new MotionNode(1u, 2u, 4u);
Assert.Equal(a, b);
Assert.NotEqual(a, c);
}
}

145
tests/AcDream.Core.Tests/Physics/Motion/MotionStateTests.cs Normal file
View file

@ -0,0 +1,145 @@
using System.Linq;
using AcDream.Core.Physics.Motion;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R2-Q1 — verbatim <c>MotionState</c> (gap H2). Oracle:
/// r2-motiontable-decomp.md §13 (ctor 0x00525fd0, add_modifier_no_check
/// 0x00525ff0, add_modifier 0x00526340, remove_modifier 0x00526040,
/// clear_modifiers 0x00526070, add_action 0x005260a0, clear_actions
/// 0x005260f0, remove_action_head 0x00526120) + §14 (one node struct,
/// two independent chains: modifier PUSH-FRONT STACK vs action TAIL-APPEND
/// FIFO) + Q0-pins A4-#5 (deep-copy ctor clones both chains — re_modify's
/// snapshot is a termination bound, never shared state).
/// </summary>
public class MotionStateTests
{
[Fact]
public void Defaults_MatchRetailCtor()
{
var ms = new MotionState();
Assert.Equal(0u, ms.Style);
Assert.Equal(0u, ms.Substate);
Assert.Equal(1f, ms.SubstateMod);
Assert.Empty(ms.Modifiers);
Assert.Empty(ms.Actions);
}
[Fact]
public void Modifiers_ArePushFrontStack()
{
var ms = new MotionState();
ms.AddModifierNoCheck(0x0Du, 1.0f);
ms.AddModifierNoCheck(0x0Fu, 1.5f);
// Newest first — retail pushes onto modifier_head.
Assert.Equal(new uint[] { 0x0Fu, 0x0Du }, ms.Modifiers.Select(m => m.Motion).ToArray());
}
[Fact]
public void Actions_AreTailAppendFifo()
{
var ms = new MotionState();
ms.AddAction(0x62u, 1.0f);
ms.AddAction(0x63u, 1.25f);
Assert.Equal(new uint[] { 0x62u, 0x63u }, ms.Actions.Select(a => a.Motion).ToArray());
}
[Fact]
public void AddModifier_RejectsDuplicate()
{
var ms = new MotionState();
Assert.True(ms.AddModifier(0x0Du, 1.0f));
Assert.False(ms.AddModifier(0x0Du, 2.0f)); // already present → caller must stop-then-re-add
Assert.Single(ms.Modifiers);
Assert.Equal(1.0f, ms.Modifiers.First().SpeedMod); // original untouched
}
[Fact]
public void AddModifier_RefusesCurrentSubstate()
{
var ms = new MotionState { Substate = 0x45000005u };
Assert.False(ms.AddModifier(0x45000005u, 1.0f));
Assert.Empty(ms.Modifiers);
}
[Fact]
public void AddModifierNoCheck_SkipsBothGuards()
{
var ms = new MotionState { Substate = 0x45000005u };
ms.AddModifierNoCheck(0x45000005u, 1.0f);
ms.AddModifierNoCheck(0x45000005u, 2.0f); // duplicate allowed too
Assert.Equal(2, ms.Modifiers.Count());
}
[Fact]
public void RemoveModifier_ByNodeIdentity()
{
var ms = new MotionState();
ms.AddModifierNoCheck(0x0Du, 1.0f);
ms.AddModifierNoCheck(0x0Fu, 1.5f);
var target = ms.Modifiers.First(m => m.Motion == 0x0Du);
ms.RemoveModifier(target);
Assert.Single(ms.Modifiers);
Assert.Equal(0x0Fu, ms.Modifiers.First().Motion);
}
[Fact]
public void RemoveActionHead_PopsFifo_ReturnsMotion_ZeroWhenEmpty()
{
var ms = new MotionState();
ms.AddAction(0x62u, 1f);
ms.AddAction(0x63u, 1f);
Assert.Equal(0x62u, ms.RemoveActionHead());
Assert.Equal(0x63u, ms.RemoveActionHead());
Assert.Equal(0u, ms.RemoveActionHead()); // empty → 0 (retail returns 0)
Assert.Empty(ms.Actions);
// Tail cleared with the last pop — a fresh append works normally.
ms.AddAction(0x64u, 1f);
Assert.Equal(new uint[] { 0x64u }, ms.Actions.Select(a => a.Motion).ToArray());
}
[Fact]
public void ClearModifiers_And_ClearActions_AreIndependentChains()
{
var ms = new MotionState();
ms.AddModifierNoCheck(0x0Du, 1f);
ms.AddAction(0x62u, 1f);
ms.ClearModifiers();
Assert.Empty(ms.Modifiers);
Assert.Single(ms.Actions);
ms.ClearActions();
Assert.Empty(ms.Actions);
}
[Fact]
public void DeepCopy_ClonesChains_NoSharedState()
{
// A4-#5: re_modify's snapshot is a DEEP copy used as a termination
// bound — mutating the original must not touch the snapshot.
var ms = new MotionState { Style = 0x8000003Du, Substate = 0x44000007u, SubstateMod = 2.85f };
ms.AddModifierNoCheck(0x0Du, 1.5f);
ms.AddAction(0x62u, 1f);
var snap = new MotionState(ms);
ms.ClearModifiers();
ms.RemoveActionHead();
ms.Substate = 0x41000003u;
Assert.Equal(0x8000003Du, snap.Style);
Assert.Equal(0x44000007u, snap.Substate);
Assert.Equal(2.85f, snap.SubstateMod);
Assert.Single(snap.Modifiers);
Assert.Equal(0x0Du, snap.Modifiers.First().Motion);
Assert.Single(snap.Actions);
}
}

167
tests/AcDream.Core.Tests/Physics/Motion/MotionTableDispatchSinkTests.cs Normal file
View file

@ -0,0 +1,167 @@
using System.Linq;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R2-Q5 — <see cref="MotionTableDispatchSink"/>: the funnel's dispatches go
/// straight into <see cref="AnimationSequencer.PerformMovement"/> (no axis
/// collection, no priority pick, no fallback chain — GetObjectSequence
/// 0x00522860 + is_allowed decide) with the TurnApplied/TurnStopped
/// ObservedOmega seam.
/// </summary>
public class MotionTableDispatchSinkTests
{
private const uint NC = 0x8000003Du;
private const uint Ready = 0x41000003u;
private const uint Walk = 0x45000005u;
private const uint TurnRight = 0x6500000Du;
private const uint ReadyAnim = 0x200u;
private const uint WalkAnim = 0x201u;
private sealed class Loader : IAnimationLoader
{
private readonly System.Collections.Generic.Dictionary<uint, Animation> _anims = new();
public void Register(uint id, Animation anim) => _anims[id] = anim;
public Animation? LoadAnimation(uint id) => _anims.TryGetValue(id, out var a) ? a : null;
}
private static Animation MakeAnim(int frames)
{
var anim = new Animation();
for (int f = 0; f < frames; f++)
{
var pf = new AnimationFrame(1);
pf.Frames.Add(new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static MotionData MakeMd(uint animId, Vector3? omega = null)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData { AnimId = qid, LowFrame = 0, HighFrame = -1, Framerate = 30f });
if (omega is { } o)
{
md.Omega = o;
md.Flags |= DatReaderWriter.Enums.MotionDataFlags.HasOmega;
}
return md;
}
private static AnimationSequencer MakeSequencer(bool withTurnModifier = true)
{
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(Vector3.One);
var loader = new Loader();
loader.Register(ReadyAnim, MakeAnim(4));
loader.Register(WalkAnim, MakeAnim(6));
var mt = new MotionTable { DefaultStyle = (DRWMotionCommand)NC };
mt.StyleDefaults[(DRWMotionCommand)NC] = (DRWMotionCommand)Ready;
mt.Cycles[(int)((NC << 16) | (Ready & 0xFFFFFFu))] = MakeMd(ReadyAnim);
mt.Cycles[(int)((NC << 16) | (Walk & 0xFFFFFFu))] = MakeMd(WalkAnim);
if (withTurnModifier)
{
mt.Modifiers[(int)((NC << 16) | (TurnRight & 0xFFFFFFu))] =
MakeMd(ReadyAnim, omega: new Vector3(0f, 0f, 1.2f));
}
return new AnimationSequencer(setup, mt, loader);
}
[Fact]
public void ApplyMotion_CycleClass_InstallsSubstate_LazyInitialized()
{
var seq = MakeSequencer();
var sink = new MotionTableDispatchSink(seq);
// Fresh sequencer: the first dispatch lazily runs initialize_state
// (retail lazy-create, r3-motioninterp-decomp §6g) then installs
// the requested substate.
sink.ApplyMotion(Walk, 2.0f);
Assert.Equal(Walk, seq.CurrentMotion);
Assert.Equal(2.0f, seq.CurrentSpeedMod);
// Locomotion velocity synthesis ran in the passthrough (AP-75).
Assert.Equal(MotionInterpreter.WalkAnimSpeed * 2.0f, seq.CurrentVelocity.Y, 3);
}
[Fact]
public void ApplyMotion_Turn_Branch4Modifier_FiresTurnApplied_NoCycleChange()
{
var seq = MakeSequencer();
uint? turnMotion = null;
float turnSpeed = 0f;
var sink = new MotionTableDispatchSink(seq)
{
TurnApplied = (m, s) => { turnMotion = m; turnSpeed = s; },
};
sink.ApplyMotion(Walk, 1.0f);
sink.ApplyMotion(TurnRight, 1.5f);
// The AP-73 mechanism for real: substate cycle untouched, the turn
// is a MotionState modifier with its dat omega combined.
Assert.Equal(Walk, seq.CurrentMotion);
Assert.Equal((TurnRight, 1.5f), (turnMotion!.Value, turnSpeed));
Assert.Equal(1.2f * 1.5f, seq.CurrentOmega.Z, 3);
}
[Fact]
public void StopMotion_Turn_FiresTurnStopped_UnwindsModifierPhysics()
{
var seq = MakeSequencer();
bool stopped = false;
var sink = new MotionTableDispatchSink(seq) { TurnStopped = () => stopped = true };
sink.ApplyMotion(Walk, 1.0f);
sink.ApplyMotion(TurnRight, 1.5f);
sink.StopMotion(TurnRight);
Assert.True(stopped);
// StopSequenceMotion Case B (0x00522fc0): subtract_motion of the dat
// omega + modifier unlinked.
Assert.Equal(0f, seq.CurrentOmega.Z, 3);
}
[Fact]
public void StopMotion_CurrentSubstate_ReDrivesToStyleDefault()
{
var seq = MakeSequencer();
var sink = new MotionTableDispatchSink(seq);
sink.ApplyMotion(Walk, 1.0f);
sink.StopMotion(Walk);
// StopSequenceMotion Case A: stopping the active cycle re-drives
// GetObjectSequence toward the style default (Ready).
Assert.Equal(Ready, seq.CurrentMotion);
}
[Fact]
public void ApplyMotion_MissingEverywhere_NoOp_DefaultKeepsPlaying()
{
var seq = MakeSequencer(withTurnModifier: false);
var sink = new MotionTableDispatchSink(seq);
sink.ApplyMotion(Walk, 1.0f);
// 0x44000007 RunForward: no cycle, no modifier -> dispatch fails,
// sequence + state untouched (no fallback chain — H4/H5).
sink.ApplyMotion(0x44000007u, 2.0f);
Assert.Equal(Walk, seq.CurrentMotion);
Assert.Equal(1.0f, seq.CurrentSpeedMod);
}
}

1018
tests/AcDream.Core.Tests/Physics/Motion/MotionTableManagerTests.cs Normal file
View file

File diff suppressed because it is too large Load diff

295
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerArrivalAndProgressTests.cs Normal file
View file

@ -0,0 +1,295 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>HandleMoveToPosition</c> Phase 2 (<c>00529d80</c>, raw
/// 307283-307331) and <c>CheckProgressMade</c> (<c>005290f0</c>, raw
/// 306385-306431), per r4-moveto-decomp.md §6b/§5b: arrival predicate
/// (chase <c>dist &lt;= DistanceToObject</c> vs flee
/// <c>dist &gt;= MinDistance</c>), fail-distance (<see cref="WeenieError.YouChargedTooFar"/>
/// 0x3D), and the 1-second / 0.25-units-per-second progress window (BOTH
/// incremental AND overall rates).
/// </summary>
public sealed class MoveToManagerArrivalAndProgressTests
{
// ── CheckProgressMade — the progress-clock table (§5b) ─────────────────
[Fact]
public void CheckProgressMade_WithinOneSecondWindow_AlwaysTrue_TooSoonToJudge()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { UseSpheres = false });
h.Advance(0.5); // < 1.0s since PreviousDistanceTime
Assert.True(h.Manager.CheckProgressMade(currentDistance: 19.9f));
}
[Fact]
public void CheckProgressMade_ExactlyOneSecond_StillTooSoon_Inclusive()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { UseSpheres = false });
h.Advance(1.0); // elapsed <= 1.0 -> still true (§5b: "elapsed <= 1.0 -> return 1")
Assert.True(h.Manager.CheckProgressMade(currentDistance: 19.9f));
}
[Fact]
public void CheckProgressMade_AfterWindow_SufficientIncrementalAndOverallRate_True()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { UseSpheres = false });
// PreviousDistance/OriginalDistance seeded to 20 at t=0.
h.Advance(2.0); // 2s elapsed
// Closed 1 unit/s over 2s = 2 units closed -> rate 1.0 >= 0.25 both ways.
bool progress = h.Manager.CheckProgressMade(currentDistance: 18f);
Assert.True(progress);
Assert.Equal(0u, h.Manager.FailProgressCount);
Assert.Equal(18f, h.Manager.PreviousDistance, 2); // incremental checkpoint advanced
}
[Fact]
public void CheckProgressMade_InsufficientIncrementalRate_False_CheckpointDoesNotAdvance()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { UseSpheres = false });
h.Advance(2.0);
// Closed only 0.1 unit over 2s -> rate 0.05 < 0.25 -> no progress;
// checkpoint (PreviousDistance) must NOT advance.
bool progress = h.Manager.CheckProgressMade(currentDistance: 19.9f);
Assert.False(progress);
Assert.Equal(20f, h.Manager.PreviousDistance, 2); // unchanged
}
[Fact]
public void CheckProgressMade_GoodIncrementalButBadOverallRate_False()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { UseSpheres = false });
// OriginalDistance/OriginalDistanceTime were seeded to (20, t=0) by
// BeginMoveForward and NEVER move again except on arrival/retarget —
// only PreviousDistance (the incremental checkpoint) advances on a
// passing tick. Simulate a long slow crawl: many small incremental
// passes that each individually clear 0.25/s over their own 1s+
// window, but the OVERALL rate since t=0 stays under 0.25/s because
// the total elapsed time dominates.
h.Advance(2.0);
Assert.True(h.Manager.CheckProgressMade(19f)); // incremental 0.5/s since t=0 — overall also 0.5/s here, still passes.
// Now advance a huge amount of time with only a tiny further close —
// incremental since the LAST checkpoint (t=2, dist=19) is healthy
// relative to its own short window, but overall since t=0 (dist 20)
// over the huge elapsed time is far under 0.25/s.
h.Advance(200.0);
bool progress = h.Manager.CheckProgressMade(18.9f); // incremental: 0.1/200s -> fails incremental too in this construction; assert false either way (both gates must independently pass).
Assert.False(progress);
}
[Fact]
public void CheckProgressMade_MovingAway_UsesOpeningDistance()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
// pure-away move: MoveTowards=false, MoveAway=true, MinDistance large
// so get_command picks WalkForward+movingAway.
var p = new MovementParameters { MoveTowards = false, MoveAway = true, MinDistance = 50f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
Assert.True(h.Manager.MovingAway);
h.Advance(2.0);
// Distance to the (now-behind) target GREW from ~20 to 25 -> opening
// at 2.5/s -> progress (moving_away: progress = curr - previous).
bool progress = h.Manager.CheckProgressMade(25f);
Assert.True(progress);
}
// ── Arrival predicate (§6b Phase 2) — chase vs flee ────────────────────
[Fact]
public void HandleMoveToPosition_Chase_ArrivesWhenDistLessOrEqualDto()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 5f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
// Walk the mover to within DistanceToObject and let enough time pass
// for CheckProgressMade to evaluate true.
h.WorldPosition = new Position(1u, new Vector3(16f, 0f, 0f), Quaternion.Identity); // dist=4 <= dto(5)
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
// Arrival -> node popped, CurrentCommand cleared, BeginNextNode ran
// (queue now empty, non-sticky) -> CleanUp + StopCompletely ->
// MovementTypeState back to Invalid.
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void HandleMoveToPosition_Chase_NotArrivedYet_StaysActive()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
h.WorldPosition = new Position(1u, new Vector3(5f, 0f, 0f), Quaternion.Identity); // dist=15, still far
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
}
[Fact]
public void HandleMoveToPosition_Flee_ArrivesWhenDistGreaterOrEqualMinDistance()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { MoveTowards = false, MoveAway = true, MinDistance = 10f, UseSpheres = false };
// Start close (dist=5 < MinDistance=10) so get_command picks
// WalkForward+movingAway (pure-away band, §5c).
h.Manager.MoveToPosition(new Position(1u, new Vector3(5f, 0f, 0f), Quaternion.Identity), p);
Assert.True(h.Manager.MovingAway);
h.DrainPendingMotions();
// Mover has fled to distance 12 (>= MinDistance 10) -> arrived.
h.WorldPosition = new Position(1u, new Vector3(-7f, 0f, 0f), Quaternion.Identity); // dist to (5,0,0) = 12
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
// ── Fail-distance (§6b, WeenieError.YouChargedTooFar) ──────────────────
[Fact]
public void HandleMoveToPosition_ProgressMadeButOverFailDistance_CancelsAsYouChargedTooFar()
{
// §6b Phase 2 ordering: the fail_distance check lives INSIDE the
// "CheckProgressMade == true, but not yet arrived" branch — a
// no-progress tick never reaches it at all (that tick only
// increments FailProgressCount). So the fail-distance trigger
// requires: progress WAS made (rate >= 0.25 both ways) toward the
// target, arrival not yet reached, AND total displacement from
// StartingPosition exceeds FailDistance — e.g. the mover overshot
// past the target along a path that looped far from the start.
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, FailDistance = 5f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
// Mover advanced to (8,0,0): 12 units closed toward the target over
// 2s (rate 6/s, passes both incremental+overall) but has traveled
// 8 units from StartingPosition(0,0,0) — over FailDistance(5) —
// while still 12 units short of arrival (dto=0.6).
h.WorldPosition = new Position(1u, new Vector3(8f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void HandleMoveToPosition_NoProgressButWithinFailDistance_StaysActive_NoCancel()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, FailDistance = 100f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
h.WorldPosition = new Position(1u, new Vector3(0f, 1f, 0f), Quaternion.Identity); // 1 unit from start, well under FailDistance
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
}
// ── FailProgressCount write-only bookkeeping (§8, do-not-invent) ───────
[Fact]
public void FailProgressCount_IncrementsOnStall_ButNoGiveUpThresholdExists()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, FailDistance = float.MaxValue, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
// Stall many times (no progress, not interpolating, not animating) —
// FailProgressCount should climb with NO cap and NO resulting
// cancellation, since the counter is write-only in retail (§8).
for (int i = 0; i < 20; i++)
{
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
}
Assert.True(h.Manager.FailProgressCount >= 20);
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState); // still active, no give-up
}
[Fact]
public void FailProgressCount_NotIncremented_WhenInterpolating()
{
var h = new MoveToManagerHarness { IsInterpolatingValue = true };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, FailDistance = float.MaxValue, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
h.DrainPendingMotions();
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(0u, h.Manager.FailProgressCount);
}
}

147
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerAuxTurnTests.cs Normal file
View file

@ -0,0 +1,147 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>HandleMoveToPosition</c> Phase 1 aux-turn steering
/// (<c>00529d80</c>, raw 307187-307280) per r4-moveto-decomp.md §6b: the
/// 20°/340° deadband, direction pick (diff ≥ 180 → TurnLeft else TurnRight),
/// no-redundant-reissue, and the "stop aux while animating" branch.
/// </summary>
public sealed class MoveToManagerAuxTurnTests
{
/// <summary>Drives a manager into an active MoveToPosition (heading
/// already settled so BeginMoveForward runs on the first BeginNextNode),
/// then drains the interp's pending_motions queue via a synthetic
/// MotionDone callback — standing in for "the WalkForward/RunForward
/// animation-table dispatch cycle has started/completed" the way a real
/// AnimationSequencer would signal it. Without this, MotionsPending()
/// stays true forever (BeginMoveForward's own _DoMotion dispatch
/// enqueues a node that nothing else in this bare harness ever pops),
/// and HandleMoveToPosition's Phase 1 would perpetually take the
/// "animating, stop aux" branch — never exercising the deadband/turn
/// logic this test file targets.</summary>
private static MoveToManagerHarness ArmMoving(float initialHeading, Vector3 targetXY)
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = initialHeading;
var p = new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, targetXY, Quaternion.Identity), p);
h.DrainPendingMotions();
return h;
}
[Fact]
public void WithinDeadband_NoAuxTurnIssued()
{
// Target due east (heading 90); mover already facing 85 -> diff 5,
// inside [0,20] deadband.
var h = ArmMoving(initialHeading: 90f, targetXY: new Vector3(20f, 0f, 0f));
h.Heading = 85f; // simulate drift after the initial turn-to-face completed
h.Manager.HandleMoveToPosition();
Assert.Equal(0u, h.Manager.AuxCommand);
}
[Fact]
public void JustOutsideDeadband_Positive_IssuesTurnRight()
{
var h = ArmMoving(initialHeading: 90f, targetXY: new Vector3(20f, 0f, 0f));
h.Heading = 40f; // diff = 90-40 = 50 -> outside [0,20]∪[340,360)
h.Manager.HandleMoveToPosition();
Assert.Equal(MotionCommand.TurnRight, h.Manager.AuxCommand);
}
[Fact]
public void DiffAtOrAbove180_IssuesTurnLeft()
{
var h = ArmMoving(initialHeading: 90f, targetXY: new Vector3(20f, 0f, 0f));
h.Heading = 300f; // diff = 90-300 = -210 -> +360 = 150... need >=180 for TurnLeft; pick 260.
h.Heading = 260f; // diff = 90-260=-170 -> +360=190 (>=180) -> TurnLeft
h.Manager.HandleMoveToPosition();
Assert.Equal(MotionCommand.TurnLeft, h.Manager.AuxCommand);
}
[Fact]
public void DeadbandUpperBoundary_340_NoTurn()
{
var h = ArmMoving(initialHeading: 0f, targetXY: new Vector3(0f, 20f, 0f)); // target heading 0
h.Heading = 20f; // diff = 0-20=-20 -> +360=340 -> boundary INCLUSIVE (diff >= 340)
h.Manager.HandleMoveToPosition();
Assert.Equal(0u, h.Manager.AuxCommand);
}
[Fact]
public void DeadbandLowerBoundary_20_NoTurn()
{
var h = ArmMoving(initialHeading: 0f, targetXY: new Vector3(0f, 20f, 0f)); // target heading 0
h.Heading = -20f % 360f; // normalize below
h.Heading = 340f; // diff = 0-340 = -340 -> +360=20 -> boundary INCLUSIVE (diff <= 20)
h.Manager.HandleMoveToPosition();
Assert.Equal(0u, h.Manager.AuxCommand);
}
[Fact]
public void NoRedundantReissue_SameDirectionTwice_DoesNotRedispatch()
{
var h = ArmMoving(initialHeading: 90f, targetXY: new Vector3(20f, 0f, 0f));
h.Heading = 40f; // outside deadband -> TurnRight
h.Manager.HandleMoveToPosition();
uint firstAux = h.Manager.AuxCommand;
Assert.Equal(MotionCommand.TurnRight, firstAux);
// Drain the interp's pending_motions queue (the TurnRight dispatch
// just enqueued a node) so Phase 1's "not animating" branch runs
// again on the second tick — otherwise MotionsPending() would stay
// true and Phase 1 would take the "animating, stop aux" branch
// instead of exercising the redundant-reissue guard this test
// targets.
h.DrainPendingMotions();
int stopCallsBefore = h.StopCompletelyCalls; // unrelated counter, just for isolation
// Second tick, still outside deadband, same direction -> _DoMotion
// should NOT be re-issued (turn != AuxCommand test fails since
// AuxCommand already equals TurnRight) — assert AuxCommand is
// unchanged (still TurnRight) as the observable proxy.
h.Manager.HandleMoveToPosition();
Assert.Equal(MotionCommand.TurnRight, h.Manager.AuxCommand);
Assert.Equal(stopCallsBefore, h.StopCompletelyCalls);
}
[Fact]
public void AnimatingMotionsPending_StopsAuxTurn_DoesNotStartNew()
{
var h = ArmMoving(initialHeading: 90f, targetXY: new Vector3(20f, 0f, 0f));
h.Heading = 40f;
h.Manager.HandleMoveToPosition();
Assert.Equal(MotionCommand.TurnRight, h.Manager.AuxCommand);
// Simulate an animation-table motion still pending by queueing a
// node onto the REAL MotionInterpreter's pending_motions.
h.Interp.AddToQueue(0, MotionCommand.WalkForward, 0);
Assert.True(h.Interp.MotionsPending());
h.Manager.HandleMoveToPosition();
Assert.Equal(0u, h.Manager.AuxCommand);
}
}

157
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerBeginMoveForwardTests.cs Normal file
View file

@ -0,0 +1,157 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>MoveToManager::BeginMoveForward</c> (<c>00529a00</c>, raw
/// 306957-307042) per r4-moveto-decomp.md §4c: dispatched motion id / hold
/// key, the write-back to the STORED params, and the progress-clock seed.
/// Also exercises the run→walk demote inside <c>WalkRunThreshhold</c> (the
/// R3 visual-pass expected-diff this closes).
/// </summary>
public sealed class MoveToManagerBeginMoveForwardTests
{
[Fact]
public void FarFromTarget_CanRunCanWalk_DispatchesRunForward()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f; // already facing target — no aux turn needed
var p = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f };
// Distance far beyond threshold+dto -> Run.
h.Manager.MoveToPosition(new Position(1u, new Vector3(100f, 0f, 0f), Quaternion.Identity), p);
// MoveToPosition's node plan queues [TurnToHeading(face)] first since
// heading(0->target)=90 != current heading is not tested here (we
// set Heading=90 already so diff=0, GetCommand still picks motion
// because distance is huge, so a turn node is queued anyway — but
// since diff==0 the queued turn will complete immediately in
// BeginNextNode's synchronous dispatch, landing directly on
// BeginMoveForward).
// ForwardCommand (post-adjust_motion, dispatched to the interp) is
// RunForward; CurrentCommand (the manager's OWN field) stores the
// PRE-adjust command GetCommand chose — get_command's own body only
// ever returns WalkForward/WalkBackward/0 (§5c) — the Run promotion
// happens downstream, inside adjust_motion (_DoMotion §7a), and is
// never written back into CurrentCommand.
Assert.Equal(MotionCommand.RunForward, h.ForwardCommand);
Assert.Equal(HoldKey.Run, h.Manager.Params.HoldKeyToApply);
Assert.Equal(MotionCommand.WalkForward, h.Manager.CurrentCommand);
}
[Fact]
public void WithinWalkRunThreshold_DemotesToWalk()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f };
// dist - dto = 10 - 0.6 = 9.4 <= 15 -> walk.
h.Manager.MoveToPosition(new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity), p);
Assert.Equal(MotionCommand.WalkForward, h.ForwardCommand);
Assert.Equal(HoldKey.None, h.Manager.Params.HoldKeyToApply);
}
[Fact]
public void CanCharge_FastPathWins_RunsEvenWhenClose()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f, CanCharge = true };
h.Manager.MoveToPosition(new Position(1u, new Vector3(2f, 0f, 0f), Quaternion.Identity), p);
Assert.Equal(MotionCommand.RunForward, h.ForwardCommand);
Assert.Equal(HoldKey.Run, h.Manager.Params.HoldKeyToApply);
}
[Fact]
public void HoldKeyWriteBack_ToStoredParams_NotJustLocalCopy()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
var p = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f, HoldKeyToApply = HoldKey.Invalid };
h.Manager.MoveToPosition(new Position(1u, new Vector3(100f, 0f, 0f), Quaternion.Identity), p);
Assert.Equal(HoldKey.Run, h.Manager.Params.HoldKeyToApply);
}
[Fact]
public void ProgressClockSeeded_PreviousAndOriginalEqualCurrentDistance()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.CurTime = 5.0;
// UseSpheres defaults true on a fresh MovementParameters, and
// MoveToPosition's own params (copied into Params BEFORE
// BeginMoveForward runs) drive GetCurrentDistance's use_spheres
// branch: cylinder distance = center distance - ownRadius(0.5) -
// targetRadius(0, position moves always zero SoughtObjectRadius).
var p = new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
Assert.Equal(20f, h.Manager.PreviousDistance, 2);
Assert.Equal(20f, h.Manager.OriginalDistance, 2);
Assert.Equal(5.0, h.Manager.PreviousDistanceTime, 3);
Assert.Equal(5.0, h.Manager.OriginalDistanceTime, 3);
}
[Fact]
public void ProgressClockSeeded_UseSpheresDefault_UsesCylinderDistance()
{
var h = new MoveToManagerHarness { OwnRadius = 0.5f };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.CurTime = 5.0;
var p = new MovementParameters { DistanceToObject = 0.6f }; // UseSpheres=true (default)
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), p);
// center distance 20 - ownRadius 0.5 - targetRadius 0 (position
// moves zero SoughtObjectRadius, §3c) = 19.5.
Assert.Equal(19.5f, h.Manager.PreviousDistance, 2);
Assert.Equal(19.5f, h.Manager.OriginalDistance, 2);
}
[Fact]
public void CancelMoveToBit_ClearedOnLocalParams_DoesNotSelfCancel()
{
// If the 0x8000 CancelMoveTo bit were NOT cleared on the local
// params passed into _DoMotion, InterruptCurrentMovement-style
// cancellation logic downstream could tear down THIS moveto before
// it starts. We assert the observable effect: the manager is still
// MovingTo after BeginMoveForward dispatches.
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
Assert.True(h.Manager.IsMovingTo());
}
[Fact]
public void NoPhysicsObj_CancelsWithNoPhysicsObjectCode()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
Assert.True(h.Manager.IsMovingTo());
h.Manager.HasPhysicsObj = false;
h.Manager.BeginMoveForward();
Assert.False(h.Manager.IsMovingTo());
}
}

123
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerCompletionSeamTests.cs Normal file
View file

@ -0,0 +1,123 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V5 — the <c>MoveToComplete</c> CLIENT-ADDITION seam contract (see the
/// seam's doc on <see cref="MoveToManager.MoveToComplete"/>): fires with
/// <see cref="WeenieError.None"/> on NATURAL COMPLETION (the
/// <see cref="MoveToManager.BeginNextNode"/> empty-queue exits, both sticky
/// and non-sticky, plus <c>CleanUpAndCallWeenie</c>'s instant-success path)
/// and NEVER on <see cref="MoveToManager.CancelMoveTo"/>. The App layer's
/// AD-27 re-anchor (deferred Use/PickUp re-send on arrival) depends on
/// exactly this split: arrival fires the deferred action once; a user-input
/// cancel must not.
/// </summary>
public sealed class MoveToManagerCompletionSeamTests
{
/// <summary>Arms a position move 5 m dead ahead (heading 90 = +X,
/// facing it) and drives the scripted body to arrival via UseTime.</summary>
private static MoveToManagerHarness DriveToArrival()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(
new Position(1u, new Vector3(5f, 0f, 0f), Quaternion.Identity),
new MovementParameters { UseSpheres = false, DistanceToObject = 0.6f });
h.DrainPendingMotions();
for (int i = 0; i < 200 && h.Manager.IsMovingTo(); i++)
{
h.Tick();
var cur = h.WorldPosition.Frame.Origin;
h.WorldPosition = new Position(
1u, cur + new Vector3(0.2f, 0f, 0f), Quaternion.Identity);
h.Manager.UseTime();
h.DrainPendingMotions();
}
Assert.False(h.Manager.IsMovingTo(),
"scripted drive must reach arrival within the tick budget");
return h;
}
[Fact]
public void NaturalArrival_FiresMoveToComplete_OnceWithNone()
{
var h = DriveToArrival();
Assert.Single(h.MoveToCompleteCalls);
Assert.Equal(WeenieError.None, h.MoveToCompleteCalls[0]);
}
[Fact]
public void AfterArrival_ExtraUseTimeTicks_DoNotRefire()
{
var h = DriveToArrival();
for (int i = 0; i < 10; i++)
{
h.Tick();
h.Manager.UseTime();
}
Assert.Single(h.MoveToCompleteCalls);
}
[Fact]
public void CancelMoveTo_DoesNotFireMoveToComplete()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(
new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
new MovementParameters { UseSpheres = false });
Assert.True(h.Manager.IsMovingTo());
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.False(h.Manager.IsMovingTo());
Assert.Empty(h.MoveToCompleteCalls);
}
[Fact]
public void StickyCompletion_FiresMoveToComplete_AfterStickToHandoff()
{
// In-range sticky object move: MoveToObject arms the tracker; the
// first Ok callback finds the target already inside
// DistanceToObject, so no motion nodes are needed and BeginNextNode
// lands straight on the empty-queue STICKY exit — StickTo gets the
// pre-CleanUp tlid/radius/height, then the completion seam fires.
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToObject(
objectId: 0x1000u, topLevelId: 0x1000u, radius: 0.5f, height: 1f,
new MovementParameters { Sticky = true, DistanceToObject = 5f });
h.DrainPendingMotions();
var target = new Position(1u, new Vector3(1f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(
new TargetInfo(0x1000u, TargetStatus.Ok, target, target));
h.DrainPendingMotions();
// Some builds need the turn/settle nodes ticked through first.
for (int i = 0; i < 50 && h.Manager.IsMovingTo(); i++)
{
h.Tick();
h.Manager.UseTime();
h.DrainPendingMotions();
}
Assert.False(h.Manager.IsMovingTo());
Assert.Single(h.StickToCalls);
Assert.Equal((0x1000u, 0.5f, 1f), h.StickToCalls[0]);
Assert.Single(h.MoveToCompleteCalls);
Assert.Equal(WeenieError.None, h.MoveToCompleteCalls[0]);
}
}

154
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerEndToEndTableDriveTests.cs Normal file
View file

@ -0,0 +1,154 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — scripted end-to-end table drive (r4-port-plan.md §3 V2 test
/// list): positions fed per tick -> expected node pops + dispatched motion
/// ids/hold keys, including the run-to-walk demote as the mover closes to
/// within <c>WalkRunThreshhold</c> of the target — the exact R3 visual-pass
/// expected-diff this closes ("auto-walk-at-run walk-pace legs (R4)").
/// </summary>
public sealed class MoveToManagerEndToEndTableDriveTests
{
[Fact]
public void ChaseSequence_TurnFirst_ThenRun_ThenDemoteToWalk_ThenArrive()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f; // facing NORTH; target is due EAST -> a turn-to-face node is required first.
var p = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(100f, 0f, 0f), Quaternion.Identity), p);
// Step 1: node plan = [TurnToHeading(90), MoveToPosition]. Heading
// diff (0->90) is large -> BeginTurnToHeading armed a real turn
// (not the "already there" early-out).
Assert.Equal(2, System.Linq.Enumerable.Count(h.Manager.PendingActions));
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
h.DrainPendingMotions();
// Step 2: the turn completes (heading snaps to 90 via
// HandleTurnToHeading's arrival branch) -> BeginNextNode pops to the
// MoveToPosition node -> BeginMoveForward dispatches. Far from the
// target (100 units, minus threshold 15 well exceeded) -> RunForward.
h.Heading = 91f; // "passed" 90
h.Manager.HandleTurnToHeading();
h.DrainPendingMotions();
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
Assert.Single(h.Manager.PendingActions);
Assert.Equal(MotionCommand.RunForward, h.ForwardCommand);
Assert.Equal(HoldKey.Run, h.Manager.Params.HoldKeyToApply);
// Step 3: close the distance to just inside the walk/run threshold.
// Phase 2 of HandleMoveToPosition doesn't re-run get_command; only
// BeginMoveForward does (dispatched once per node, on arm) — so the
// walk-demote re-evaluation requires a fresh moveto issue. Route it
// through PerformMovement (NOT a direct MoveToPosition call) — this
// is the retail-faithful re-issue shape (§3a: cancel current +
// unstick FIRST, THEN dispatch) and avoids stacking a stale node
// onto the still-populated queue the way a bare second
// MoveToPosition call would (MoveToPosition itself does not drain;
// only PerformMovement's CancelMoveTo call does).
h.WorldPosition = new Position(1u, new Vector3(90f, 0f, 0f), Quaternion.Identity); // 10 units from target
h.Heading = 90f; // already facing it
var pClose = new MovementParameters { DistanceToObject = 0.6f, WalkRunThreshhold = 15f, UseSpheres = false };
h.Manager.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(100f, 0f, 0f), Quaternion.Identity),
Params = pClose,
});
// PerformMovement's CancelMoveTo (§3a) stops the in-flight motion
// FIRST, which itself enqueues a pending_motions node -- so
// BeginTurnToHeading's wait-for-anims gate (§4d) defers the "already
// facing it" early-out to the NEXT drain, not synchronously inside
// this call. Drain twice: once for the cancel's own stop dispatch,
// once more for whatever BeginTurnToHeading/BeginMoveForward issues
// once armed.
h.DrainPendingMotions();
h.Manager.BeginNextNode(); // re-check the head node now that anims have drained
h.DrainPendingMotions();
Assert.Single(h.Manager.PendingActions); // the stale queue was drained by PerformMovement's CancelMoveTo; the "already facing it" turn completed instantly once anims cleared.
// dist=10, dto=0.6 -> dist-dto=9.4 <= 15 -> WALK.
Assert.Equal(MotionCommand.WalkForward, h.ForwardCommand);
Assert.Equal(HoldKey.None, h.Manager.Params.HoldKeyToApply);
// Step 4: arrive.
h.WorldPosition = new Position(1u, new Vector3(99.7f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Empty(h.Manager.PendingActions);
}
[Fact]
public void FleeSequence_WalksBackward_InsideMinBand_ArrivesWhenFarEnough()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, new Vector3(3f, 0f, 0f), Quaternion.Identity);
h.Heading = 270f; // facing the threat (target) which is behind at origin -- WalkBackward needs no turn.
// towards_and_away band: dist(3) inside [MinDistance(5)... wait need
// dist < min for the inside-band WalkBackward pick]. Use MinDistance
// 5 with mover at distance 3 from the target (origin) -> inside
// band -> WalkBackward, no turn node queued (§5d asymmetry).
var p = new MovementParameters { MoveTowards = true, MoveAway = true, MinDistance = 5f, DistanceToObject = 8f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, Vector3.Zero, Quaternion.Identity), p);
Assert.True(h.Manager.MovingAway);
Assert.Equal(MotionCommand.WalkBackward, h.Manager.CurrentCommand); // pre-adjust id (get_command's own return)
// adjust_motion normalizes WalkBackward -> WalkForward with a
// negative BackwardsFactor-scaled speed, dispatched as ForwardCommand.
Assert.Equal(MotionCommand.WalkForward, h.ForwardCommand);
Assert.True(h.ForwardSpeed < 0f);
h.DrainPendingMotions();
// Flee to distance 6 (>= MinDistance 5) -> arrived.
h.WorldPosition = new Position(1u, new Vector3(6f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
h.Manager.HandleMoveToPosition();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void TurnToObjectSequence_DeferredStart_ThenRetargetIgnored_ThenArrivesOnHeadingPass()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
const uint targetId = 0x5000CCCCu;
h.Manager.TurnToObject(targetId, targetId, new MovementParameters());
Assert.Empty(h.Manager.PendingActions); // deferred (§3d)
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity); // heading 90
h.Manager.HandleUpdateTarget(new TargetInfo(targetId, TargetStatus.Ok, target, target));
Assert.True(h.Manager.Initialized);
Assert.Single(h.Manager.PendingActions);
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
h.DrainPendingMotions();
// Retarget while running: TurnToObject gets no handling (heading frozen).
var target2 = new Position(1u, new Vector3(0f, 10f, 0f), Quaternion.Identity); // heading 0
h.Manager.HandleUpdateTarget(new TargetInfo(targetId, TargetStatus.Ok, target2, target2));
var soughtBefore = h.Manager.SoughtPosition;
Assert.Equal(soughtBefore, h.Manager.SoughtPosition); // sanity: unchanged by its own read
// Complete the turn toward the ORIGINAL (frozen) heading (90), not target2's.
h.Heading = 91f;
h.Manager.HandleTurnToHeading();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Equal(90f, h.Heading, 2); // snapped to the frozen heading, unaffected by the retarget.
}
}

158
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerHandleUpdateTargetTests.cs Normal file
View file

@ -0,0 +1,158 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>HandleUpdateTarget</c> (<c>0052a7d0</c>, raw 307802-307867,
/// decomp §6d): the P4 TargetTracker feed's deferred-start lifecycle
/// (Initialized=false = the first callback vs true = an in-flight retarget),
/// context/target-id filtering, self-target instant success, NoObject vs
/// ObjectGone status handling, and the retarget progress-clock reset.
/// </summary>
public sealed class MoveToManagerHandleUpdateTargetTests
{
private const uint TargetId = 0x50004444u;
private static MoveToManagerHarness ArmMoveToObject(float ownRadius = 0.5f, float ownHeight = 2f)
{
var h = new MoveToManagerHarness { OwnRadius = ownRadius, OwnHeight = ownHeight };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
h.Manager.MoveToObject(TargetId, TargetId, radius: 1f, height: 2f, new MovementParameters());
return h;
}
[Fact]
public void IgnoresUpdate_ForADifferentTarget()
{
var h = ArmMoveToObject();
var wrongTargetPos = new Position(1u, new Vector3(5f, 5f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x59999999u, TargetStatus.Ok, wrongTargetPos, wrongTargetPos));
Assert.False(h.Manager.Initialized);
Assert.Empty(h.Manager.PendingActions);
}
[Fact]
public void FirstCallback_NonOkStatus_CancelsAsNoObject()
{
var h = ArmMoveToObject();
var pos = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.ExitWorld, pos, pos));
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void FirstCallback_OkStatus_BuildsNodePlan_SetsInitialized()
{
var h = ArmMoveToObject();
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target, target));
Assert.True(h.Manager.Initialized);
Assert.NotEmpty(h.Manager.PendingActions);
}
[Fact]
public void FirstCallback_OrdinaryTarget_DoesNotFireMoveToComplete()
{
// MoveToObject's OWN self-target branch (§3b) already short-circuits
// via CleanUp+StopCompletely BEFORE any HandleUpdateTarget ever
// fires for a same-id target — so HandleUpdateTarget's self-target
// instant-success path (§6d: "top_level_object_id ==
// physics_obj->id") is reachable only in the deferred-start window,
// and is covered by construction in
// MoveToManagerNodePlanTests.MoveToObject_SelfTarget_*
// (MoveToObject never even reaches SetTarget for a self-id, so the
// callback path is dead in practice — retail's redundant guard).
// This test isolates the ORDINARY path: MoveToComplete's only
// trigger is CleanUpAndCallWeenie, never a plain node-plan build.
var h = ArmMoveToObject();
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target, target));
Assert.Empty(h.MoveToCompleteCalls);
}
[Fact]
public void Retarget_NonOkStatus_CancelsAsObjectGone()
{
var h = ArmMoveToObject();
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target, target));
Assert.True(h.Manager.Initialized);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.ExitWorld, target, target));
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void Retarget_UpdatesPositions_ResetsProgressClock_DoesNotRequeueNodes()
{
var h = ArmMoveToObject();
var target1 = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target1, target1));
int nodeCountAfterFirst = System.Linq.Enumerable.Count(h.Manager.PendingActions);
Assert.True(nodeCountAfterFirst > 0);
h.Advance(3.0); // simulate time passing, progress clock advanced by BeginMoveForward
var target2 = new Position(1u, new Vector3(20f, 5f, 0f), Quaternion.Identity);
var interp2 = new Position(1u, new Vector3(19f, 5f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target2, interp2));
Assert.Equal(target2, h.Manager.CurrentTargetPosition);
Assert.Equal(interp2, h.Manager.SoughtPosition);
Assert.Equal(float.MaxValue, h.Manager.PreviousDistance);
Assert.Equal(float.MaxValue, h.Manager.OriginalDistance);
// Node count unchanged by the retarget itself (no requeue) — the
// running MoveToPosition node keeps steering toward the moved
// CurrentTargetPosition on its own next tick.
Assert.Equal(nodeCountAfterFirst, System.Linq.Enumerable.Count(h.Manager.PendingActions));
}
[Fact]
public void Retarget_TurnToObject_GetsNoRetargetHandling_HeadingFrozen()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
h.Manager.TurnToObject(TargetId, TargetId, new MovementParameters());
var target1 = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity); // heading 90
h.Manager.TurnToObject_Internal(target1); // first callback (direct, mirrors deferred-start call shape)
Assert.True(h.Manager.Initialized);
var soughtAfterFirst = h.Manager.SoughtPosition;
// A retarget-shaped HandleUpdateTarget call for a TurnToObject
// manager: since Initialized is already true, this takes the
// "retarget" branch, which only updates state for MoveToObject —
// TurnToObject gets NO handling at all (decomp §6d note).
var target2 = new Position(1u, new Vector3(0f, 10f, 0f), Quaternion.Identity); // heading 0
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target2, target2));
Assert.Equal(soughtAfterFirst, h.Manager.SoughtPosition); // untouched
}
[Fact]
public void NoPhysicsObj_CancelsWithNoPhysicsObjectCode()
{
var h = ArmMoveToObject();
h.Manager.HasPhysicsObj = false;
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(TargetId, TargetStatus.Ok, target, target));
Assert.False(h.Manager.IsMovingTo());
}
}

100
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerLifecycleTests.cs Normal file
View file

@ -0,0 +1,100 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>MoveToManager</c> construction / <c>InitializeLocalVariables</c>
/// (<c>00529250</c>, raw 306490-306534) / <c>Destroy</c> (<c>005294b0</c>) /
/// <c>is_moving_to</c> (<c>00529220</c>). Per r4-moveto-decomp.md §1: the ctor
/// zeroes the FLAGS WORD + context_id only (NOT ACE's A2/A3 full-struct-reset
/// transposition — scalar param fields keep stale values since every entry
/// point copies all ten fields anyway), resets both progress-clock pairs to
/// FLT_MAX/now, and resets Sought/CurrentTarget positions but NOT
/// StartingPosition.
/// </summary>
public sealed class MoveToManagerLifecycleTests
{
[Fact]
public void FreshManager_MovementTypeIsInvalid()
{
var h = new MoveToManagerHarness();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.False(h.Manager.IsMovingTo());
}
[Fact]
public void FreshManager_ProgressClocksAreFltMax()
{
var h = new MoveToManagerHarness();
Assert.Equal(float.MaxValue, h.Manager.PreviousDistance);
Assert.Equal(float.MaxValue, h.Manager.OriginalDistance);
}
[Fact]
public void FreshManager_BitfieldFlagsAllClear_ScalarsUntouchedByCtorReset()
{
// InitializeLocalVariables clears ONLY the bitfield + context_id.
// The scalar fields (DistanceToObject etc.) are NOT part of that
// clear — but since Params starts as `new MovementParameters()`
// (retail ctor defaults), the scalars already hold their defaults
// here; the "stale values survive InitializeLocalVariables" claim is
// exercised by MoveToManagerCancelAndCleanupTests (a scalar surviving
// a CleanUp/InitializeLocalVariables round-trip after being changed
// by an entry point).
var h = new MoveToManagerHarness();
Assert.False(h.Manager.Params.CanWalk);
Assert.False(h.Manager.Params.CanRun);
Assert.False(h.Manager.Params.MoveTowards);
Assert.False(h.Manager.Params.CancelMoveTo);
Assert.Equal(0u, h.Manager.Params.ContextId);
}
[Fact]
public void FreshManager_SoughtPositionAndCurrentTargetAreIdentityFrameAtCellZero()
{
// NOT default(Position) — default(Quaternion) is the ZERO
// quaternion, not identity. Retail resets to a genuine identity
// frame (decomp §1c) at cell id 0.
var h = new MoveToManagerHarness();
var expected = new Position(0u, System.Numerics.Vector3.Zero, System.Numerics.Quaternion.Identity);
Assert.Equal(expected, h.Manager.SoughtPosition);
Assert.Equal(expected, h.Manager.CurrentTargetPosition);
Assert.Equal(0f, MoveToMath.GetHeading(h.Manager.SoughtPosition.Frame.Orientation));
}
[Fact]
public void FreshManager_PendingActionsEmpty()
{
var h = new MoveToManagerHarness();
Assert.Empty(h.Manager.PendingActions);
}
[Fact]
public void Destroy_DrainsPendingActions_ThenReInitializes()
{
var h = new MoveToManagerHarness();
h.Manager.AddMoveToPositionNode();
h.Manager.AddTurnToHeadingNode(90f);
Assert.Equal(2, System.Linq.Enumerable.Count(h.Manager.PendingActions));
h.Manager.Destroy();
Assert.Empty(h.Manager.PendingActions);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void IsMovingTo_TrueAfterMoveToPosition_FalseAfterCancel()
{
var h = new MoveToManagerHarness();
h.Manager.MoveToPosition(new Position(1u, new System.Numerics.Vector3(10f, 0f, 0f), System.Numerics.Quaternion.Identity), new MovementParameters());
Assert.True(h.Manager.IsMovingTo());
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.False(h.Manager.IsMovingTo());
}
}

306
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerNodePlanTests.cs Normal file
View file

@ -0,0 +1,306 @@
using System.Linq;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — node-plan goldens for each movement type. Per r4-moveto-decomp.md
/// §3c (MoveToPosition), §6f (MoveToObject_Internal), §3e (TurnToHeading),
/// §6g (TurnToObject_Internal): the SHAPE of <c>pending_actions</c> right
/// after the entry point (deferred moves) or the internal builder (object
/// moves, first target callback) runs.
/// </summary>
public sealed class MoveToManagerNodePlanTests
{
// ── MoveToPosition (§3c): [TurnToHeading(face)] → [MoveToPosition] ────
[Fact]
public void MoveToPosition_NeedsMotion_QueuesTurnThenMove()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
// Target due east (+X) -> heading 90. Far enough that get_command
// says motion is needed (default DistanceToObject=0.6).
h.Manager.MoveToPosition(new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity), new MovementParameters());
var nodes = h.Manager.PendingActions.ToList();
Assert.Equal(2, nodes.Count);
Assert.Equal(MovementType.TurnToHeading, nodes[0].Type);
Assert.Equal(90f, nodes[0].Heading, 2);
Assert.Equal(MovementType.MoveToPosition, nodes[1].Type);
}
[Fact]
public void MoveToPosition_AlreadyInRange_NoMotionNodesQueued()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
// Target within default DistanceToObject (0.6) -> get_command idles.
h.Manager.MoveToPosition(new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity), new MovementParameters());
Assert.Empty(h.Manager.PendingActions);
}
[Fact]
public void MoveToPosition_UseFinalHeading_AppendsAbsoluteFinalTurnNode()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
var p = new MovementParameters { UseFinalHeading = true, DesiredHeading = 270f };
h.Manager.MoveToPosition(new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity), p);
var nodes = h.Manager.PendingActions.ToList();
// Turn-to-face(90) -> MoveToPosition -> Turn-to-final(270, ABSOLUTE).
Assert.Equal(3, nodes.Count);
Assert.Equal(MovementType.TurnToHeading, nodes[2].Type);
Assert.Equal(270f, nodes[2].Heading, 2);
}
[Fact]
public void MoveToPosition_UseFinalHeadingOnly_NoMotionNeeded_QueuesOnlyFinalTurn()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
var p = new MovementParameters { UseFinalHeading = true, DesiredHeading = 45f };
// Already in range -> no move/turn-to-face nodes, only the final turn.
h.Manager.MoveToPosition(new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity), p);
var nodes = h.Manager.PendingActions.ToList();
Assert.Single(nodes);
Assert.Equal(MovementType.TurnToHeading, nodes[0].Type);
Assert.Equal(45f, nodes[0].Heading, 2);
}
[Fact]
public void MoveToPosition_ClearsStickyBit_EvenIfArgumentRequestedIt()
{
var h = new MoveToManagerHarness();
var p = new MovementParameters { Sticky = true };
h.Manager.MoveToPosition(new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity), p);
Assert.False(h.Manager.Params.Sticky);
}
[Fact]
public void MoveToPosition_MovementTypeAndStartingPositionSet()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(2u, new Vector3(1f, 2f, 3f), Quaternion.Identity);
// Distance 10 (> default DistanceToObject 0.6) so the move plan
// actually queues motion and MovementTypeState stays MoveToPosition
// instead of completing instantly via the empty-queue BeginNextNode
// path (see MoveToPosition_AlreadyInRange_NoMotionNodesQueued for
// that degenerate case).
h.Manager.MoveToPosition(new Position(2u, new Vector3(1f, 12f, 3f), Quaternion.Identity), new MovementParameters());
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
Assert.Equal(h.WorldPosition, h.Manager.StartingPosition);
}
// ── TurnToHeading (§3e): ONE node, immediate BeginNextNode ─────────────
[Fact]
public void TurnToHeading_QueuesExactlyOneNode_WithDesiredHeading()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 123f });
var nodes = h.Manager.PendingActions.ToList();
// BeginNextNode ran immediately and BeginTurnToHeading may have
// already popped the node if heading matched (it won't here — 123
// != 0), so the node should still be present as "in flight" (its
// dispatch doesn't remove it — only arrival does). We assert via
// CurrentCommand instead of raw queue count, since BeginNextNode
// does run synchronously.
Assert.Equal(MovementType.TurnToHeading, h.Manager.MovementTypeState);
Assert.NotEqual(0u, h.Manager.CurrentCommand);
Assert.Single(nodes);
Assert.Equal(123f, nodes[0].Heading, 2);
}
[Fact]
public void TurnToHeading_ClearsStickyBit()
{
var h = new MoveToManagerHarness();
h.Manager.TurnToHeading(new MovementParameters { Sticky = true, DesiredHeading = 45f });
Assert.False(h.Manager.Params.Sticky);
}
[Fact]
public void TurnToHeading_AlreadyFacingTarget_BeginNextNodeCompletesImmediately()
{
var h = new MoveToManagerHarness();
h.Heading = 90f;
// DesiredHeading == current heading -> BeginTurnToHeading's
// "already there" branch pops + BeginNextNode -> empty queue,
// non-sticky -> CleanUp + StopCompletely -> back to Invalid.
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Empty(h.Manager.PendingActions);
Assert.True(h.StopCompletelyCalls >= 1);
}
// ── MoveToObject deferred start (§3b + §6f via HandleUpdateTarget) ─────
[Fact]
public void MoveToObject_NoNodesQueuedUntilTargetCallback()
{
var h = new MoveToManagerHarness();
h.Manager.MoveToObject(objectId: 0x50002222u, topLevelId: 0x50002222u, radius: 1f, height: 2f, new MovementParameters());
Assert.Empty(h.Manager.PendingActions);
Assert.Equal(MovementType.MoveToObject, h.Manager.MovementTypeState);
Assert.False(h.Manager.Initialized);
Assert.Single(h.SetTargetCalls);
Assert.Equal((0u, 0x50002222u, 0.5f, 0.0), h.SetTargetCalls[0]);
}
[Fact]
public void MoveToObject_PreservesStickyBit_UnlikePositionMoves()
{
var h = new MoveToManagerHarness();
var p = new MovementParameters { Sticky = true };
h.Manager.MoveToObject(0x50002222u, 0x50002222u, 1f, 2f, p);
Assert.True(h.Manager.Params.Sticky);
}
[Fact]
public void MoveToObject_FirstTargetCallback_BuildsNodePlanViaInternal()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
h.Manager.MoveToObject(0x50002222u, 0x50002222u, radius: 0.5f, height: 2f, new MovementParameters());
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x50002222u, TargetStatus.Ok, target, target));
Assert.True(h.Manager.Initialized);
var nodes = h.Manager.PendingActions.ToList();
Assert.Equal(2, nodes.Count);
Assert.Equal(MovementType.TurnToHeading, nodes[0].Type);
Assert.Equal(90f, nodes[0].Heading, 2);
Assert.Equal(MovementType.MoveToPosition, nodes[1].Type);
}
[Fact]
public void MoveToObject_UseFinalHeading_RelativeToInterpolatedHeading()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
var p = new MovementParameters { UseFinalHeading = true, DesiredHeading = 10f };
h.Manager.MoveToObject(0x50002222u, 0x50002222u, 0.5f, 2f, p);
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity); // heading 90
h.Manager.HandleUpdateTarget(new TargetInfo(0x50002222u, TargetStatus.Ok, target, target));
var nodes = h.Manager.PendingActions.ToList();
Assert.Equal(3, nodes.Count);
// RELATIVE: iHeading(90) + desired(10) = 100 -- unlike MoveToPosition's absolute form.
Assert.Equal(100f, nodes[2].Heading, 2);
}
[Fact]
public void MoveToObject_SelfTarget_CleansUpImmediately_NoSetTarget()
{
var h = new MoveToManagerHarness();
h.Manager.MoveToObject(h.SelfId, h.SelfId, 1f, 2f, new MovementParameters());
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Empty(h.SetTargetCalls);
}
// ── TurnToObject deferred start (§3d + §6g) ────────────────────────────
[Fact]
public void TurnToObject_NoNodesQueuedUntilTargetCallback()
{
var h = new MoveToManagerHarness();
h.Manager.TurnToObject(0x50003333u, 0x50003333u, new MovementParameters());
Assert.Empty(h.Manager.PendingActions);
Assert.False(h.Manager.Initialized);
Assert.Single(h.SetTargetCalls);
}
[Fact]
public void TurnToObject_FirstCallback_QueuesExactlyOneTurnNode_FacingObject()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f; // already facing north — target due EAST forces an actual turn to queue.
// DesiredHeading is clobbered (§3d quirk) — it should NOT appear in
// the final node heading; the final heading is purely "face the
// object" (soughtHeading is 0 for a fresh manager).
h.Manager.TurnToObject(0x50003333u, 0x50003333u, new MovementParameters { DesiredHeading = 200f });
var target = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity); // heading 90 (east)
h.Manager.TurnToObject_Internal(target);
var nodes = h.Manager.PendingActions.ToList();
Assert.Single(nodes);
Assert.Equal(MovementType.TurnToHeading, nodes[0].Type);
Assert.Equal(90f, nodes[0].Heading, 2); // face-the-object (east), NOT 200
Assert.True(h.Manager.Initialized);
}
[Fact]
public void TurnToObject_FirstCallback_AlreadyFacingObject_CompletesImmediately()
{
// When soughtHeading(0) + targetHeading already equals the current
// heading, BeginTurnToHeading's "already there" branch consumes the
// node on the SAME call — the queue is empty by the time
// TurnToObject_Internal returns, but the manager still passed
// through Initialized=true and the CleanUp/StopCompletely tail.
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
h.Manager.TurnToObject(0x50003333u, 0x50003333u, new MovementParameters());
var target = new Position(1u, new Vector3(0f, 10f, 0f), Quaternion.Identity); // heading 0 (north) — already facing it.
h.Manager.TurnToObject_Internal(target);
Assert.Empty(h.Manager.PendingActions);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void TurnToObject_SelfTarget_CleansUpImmediately()
{
var h = new MoveToManagerHarness();
h.Manager.TurnToObject(h.SelfId, h.SelfId, new MovementParameters());
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Empty(h.SetTargetCalls);
}
[Fact]
public void TurnToObject_StopCompletelyOnlyWhenBitSet()
{
var h1 = new MoveToManagerHarness();
h1.Manager.TurnToObject(0x50003333u, 0x50003333u, new MovementParameters { StopCompletelyFlag = false });
Assert.Equal(0, h1.StopCompletelyCalls);
var h2 = new MoveToManagerHarness();
h2.Manager.TurnToObject(0x50003333u, 0x50003333u, new MovementParameters { StopCompletelyFlag = true });
Assert.Equal(1, h2.StopCompletelyCalls);
}
}

295
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerStickyAndCancelTests.cs Normal file
View file

@ -0,0 +1,295 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>BeginNextNode</c>'s sticky handoff (<c>00529cb0</c>, raw
/// 307123-307171, decomp §4b) and <c>CancelMoveTo</c>
/// (<c>00529930</c>, raw 306886-306940, decomp §7c) including the
/// reentrancy invariant (r4-port-plan.md §4: CancelMoveTo →
/// CleanUpAndCallWeenie → StopCompletely → InterruptCurrentMovement →
/// CancelMoveTo no-ops on Invalid).
/// </summary>
public sealed class MoveToManagerStickyAndCancelTests
{
// ── Sticky handoff (§4b) — read BEFORE CleanUp, then StickTo ───────────
[Fact]
public void StickyArrival_ReadsRadiusHeightTlidBeforeCleanUp_ThenCallsStickTo()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
var p = new MovementParameters { Sticky = true };
h.Manager.MoveToObject(0x50005555u, 0x50005555u, radius: 1.5f, height: 2.5f, p);
Assert.True(h.Manager.Params.Sticky); // preserved by MoveToObject (§3b)
var target = new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity); // inside default dto -> arrives instantly
h.Manager.HandleUpdateTarget(new TargetInfo(0x50005555u, TargetStatus.Ok, target, target));
Assert.Single(h.StickToCalls);
Assert.Equal((0x50005555u, 1.5f, 2.5f), h.StickToCalls[0]);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // CleanUp ran
}
[Fact]
public void NonStickyArrival_NoStickToCall_JustCleanUpAndStop()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
var p = new MovementParameters { Sticky = false };
h.Manager.MoveToObject(0x50005555u, 0x50005555u, radius: 1.5f, height: 2.5f, p);
var target = new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x50005555u, TargetStatus.Ok, target, target));
Assert.Empty(h.StickToCalls);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void MoveToPosition_NeverSticks_EvenIfRequested()
{
// §3c: MoveToPosition force-clears the sticky bit — so even an
// arrival that WOULD have stuck (had it been an object move) just
// completes plainly.
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 0f;
var p = new MovementParameters { Sticky = true, DistanceToObject = 0.6f, UseSpheres = false };
h.Manager.MoveToPosition(new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity), p); // already in range -> instant complete
Assert.Empty(h.StickToCalls);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void StickyHandoff_UsesSoughtRadiusHeight_NotOwnRadiusHeight()
{
var h = new MoveToManagerHarness { OwnRadius = 99f, OwnHeight = 99f };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
var p = new MovementParameters { Sticky = true };
h.Manager.MoveToObject(0x50006666u, 0x50006666u, radius: 3f, height: 4f, p);
var target = new Position(1u, new Vector3(0.1f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x50006666u, TargetStatus.Ok, target, target));
Assert.Equal((0x50006666u, 3f, 4f), h.StickToCalls[0]); // the TARGET's radius/height, not the mover's own.
}
// ── CancelMoveTo (§7c) — drain + CleanUp + Stop; reentrancy ────────────
[Fact]
public void CancelMoveTo_OnInvalidState_IsANoOp()
{
var h = new MoveToManagerHarness();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.Equal(0, h.StopCompletelyCalls); // no-op: never even called StopCompletely
Assert.Equal(0, h.ClearTargetCalls);
}
[Fact]
public void CancelMoveTo_DrainsPendingActions()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
Assert.NotEmpty(h.Manager.PendingActions);
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.Empty(h.Manager.PendingActions);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void CancelMoveTo_ErrorArgument_NeverReadInBody_SameBehaviorForAnyCode()
{
// §7c: the WeenieError arg is NEVER read — every code produces
// identical observable behavior (drain + CleanUp + Stop).
var h1 = new MoveToManagerHarness();
h1.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h1.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
h1.Manager.CancelMoveTo(WeenieError.YouChargedTooFar);
var h2 = new MoveToManagerHarness();
h2.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h2.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
h2.Manager.CancelMoveTo(WeenieError.NoObject);
Assert.Equal(h1.Manager.MovementTypeState, h2.Manager.MovementTypeState);
Assert.Equal(h1.StopCompletelyCalls, h2.StopCompletelyCalls);
}
[Fact]
public void CancelMoveTo_ClearsTarget_ForObjectMoves()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToObject(0x50007777u, 0x50007777u, 1f, 2f, new MovementParameters());
Assert.Single(h.SetTargetCalls);
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.Equal(1, h.ClearTargetCalls);
}
[Fact]
public void CancelMoveTo_DoesNotClearTarget_ForPositionMoves()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
h.Manager.CancelMoveTo(WeenieError.ActionCancelled);
Assert.Equal(0, h.ClearTargetCalls); // TopLevelObjectId is 0 for a position move -> the clear_target gate never fires.
}
[Fact]
public void Reentrancy_StopCompletelyCallback_ReenteringCancelMoveTo_NoOps()
{
// r4-port-plan.md §4 reentrancy invariant: the StopCompletely tail
// of CancelMoveTo/CleanUpAndCallWeenie can re-enter
// InterruptCurrentMovement -> CancelMoveTo (this is exactly what
// happens in production: MotionInterpreter.StopCompletely()
// invokes InterruptCurrentMovement, which V5 binds to
// entity.MoveTo.CancelMoveTo). This must no-op because CleanUp
// already reset movement_type to Invalid BEFORE StopCompletely
// runs. Wire the reentrant callback DIRECTLY (bypassing the shared
// harness, which doesn't expose this seam post-construction) to
// prove the invariant against the real CancelMoveTo/CleanUp
// ordering.
var interp = new MotionInterpreter();
var body = new PhysicsBody { TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable | TransientStateFlags.Active };
interp.PhysicsObj = body;
Position worldPosition = new(1u, Vector3.Zero, Quaternion.Identity);
int stopCompletelyCalls = 0;
int reentrantCancelCalls = 0;
MoveToManager? mgr = null;
mgr = new MoveToManager(
interp,
stopCompletely: () =>
{
stopCompletely_body();
},
getPosition: () => worldPosition,
getHeading: () => 0f,
setHeading: (h, send) => { },
getOwnRadius: () => 0.5f,
getOwnHeight: () => 2f,
contact: () => true,
isInterpolating: () => false,
getVelocity: () => Vector3.Zero,
getSelfId: () => 0x50000001u,
setTarget: (a, b, c, d) => { },
clearTarget: () => { },
getTargetQuantum: () => 0.0,
setTargetQuantum: q => { });
void stopCompletely_body()
{
stopCompletelyCalls++;
// Re-enter: exactly the retail chain
// interp.StopCompletely() -> InterruptCurrentMovement?.Invoke()
// -> entity.MoveTo.CancelMoveTo(ActionCancelled) (V5 binding).
reentrantCancelCalls++;
mgr!.CancelMoveTo(WeenieError.ActionCancelled);
}
mgr.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
int stopCallsAfterArm = stopCompletelyCalls; // MoveToPosition's own unconditional stop (§3c) — 1 call, no reentrancy (MovementTypeState was already Invalid before this call started, so its OWN reentrant CancelMoveTo-from-StopCompletely no-ops too).
mgr.CancelMoveTo(WeenieError.ActionCancelled);
// CancelMoveTo's own StopCompletely fires exactly once more (its
// reentrant CancelMoveTo call finds MovementTypeState already
// Invalid — CleanUp ran first — so it no-ops and does NOT trigger a
// THIRD StopCompletely call).
Assert.Equal(stopCallsAfterArm + 1, stopCompletelyCalls);
Assert.Equal(2, reentrantCancelCalls); // one from MoveToPosition's own stop, one from CancelMoveTo's stop
Assert.Equal(MovementType.Invalid, mgr.MovementTypeState);
}
[Fact]
public void CleanUpAndCallWeenie_FiresMoveToComplete_WithGivenError()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
h.Manager.CleanUpAndCallWeenie(WeenieError.None);
Assert.Single(h.MoveToCompleteCalls);
Assert.Equal(WeenieError.None, h.MoveToCompleteCalls[0]);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void CleanUpAndCallWeenie_Ordering_MovementTypeAlreadyInvalid_WhenStopCompletelyFires()
{
// §7e: CleanUpAndCallWeenie = CleanUp() THEN StopCompletely() —
// reentrancy-safe ordering (the same ordering CancelMoveTo uses).
// Directly observe MovementTypeState AT THE MOMENT StopCompletely
// is invoked by wiring a probe into the seam.
var interp = new MotionInterpreter();
var body = new PhysicsBody { TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable | TransientStateFlags.Active };
interp.PhysicsObj = body;
Position worldPosition = new(1u, Vector3.Zero, Quaternion.Identity);
MovementType? stateDuringStopCompletely = null;
MoveToManager? mgr = null;
mgr = new MoveToManager(
interp,
stopCompletely: () => stateDuringStopCompletely = mgr!.MovementTypeState,
getPosition: () => worldPosition,
getHeading: () => 0f,
setHeading: (h, send) => { },
getOwnRadius: () => 0.5f,
getOwnHeight: () => 2f,
contact: () => true,
isInterpolating: () => false,
getVelocity: () => Vector3.Zero,
getSelfId: () => 0x50000001u,
setTarget: (a, b, c, d) => { },
clearTarget: () => { },
getTargetQuantum: () => 0.0,
setTargetQuantum: q => { });
mgr.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
mgr.CleanUpAndCallWeenie(WeenieError.None);
Assert.Equal(MovementType.Invalid, stateDuringStopCompletely);
}
[Fact]
public void CleanUp_StopsCurrentAndAuxCommands_ClearsTargetForObjectMoves_ThenReinitializes()
{
var h = new MoveToManagerHarness();
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToObject(0x50008888u, 0x50008888u, 1f, 2f, new MovementParameters());
var target = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x50008888u, TargetStatus.Ok, target, target));
Assert.NotEqual(0u, h.Manager.CurrentCommand);
h.Manager.CleanUp();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Equal(1, h.ClearTargetCalls);
Assert.Equal(0u, h.Manager.CurrentCommand);
}
}

138
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerTestHarness.cs Normal file
View file

@ -0,0 +1,138 @@
using System;
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — shared scripted fake interp-sink/provider harness for
/// <see cref="MoveToManager"/> conformance tests (r4-port-plan.md §3 V2:
/// "Use a scripted fake interp-sink/provider harness — NO real sequencer
/// needed; the manager drives the interp seams; assert the call sequences
/// + state"). Wraps a REAL <see cref="MotionInterpreter"/> bound to a
/// minimal always-grounded <see cref="PhysicsBody"/> (so
/// <c>_DoMotion</c>/<c>_StopMotion</c>'s <c>adjust_motion</c> +
/// <c>DoInterpretedMotion</c>/<c>StopInterpretedMotion</c> chain runs for
/// real, dispatch treated as always-succeeding since no
/// <see cref="IInterpretedMotionSink"/> is wired — matching
/// <c>DoInterpretedMotion</c>'s documented null-sink posture), and exposes
/// every <see cref="MoveToManager"/> ctor seam as a mutable, inspectable
/// field so tests can script position/heading/contact/target-tracker
/// behavior and assert on call sequences.
/// </summary>
internal sealed class MoveToManagerHarness
{
public readonly MotionInterpreter Interp = new();
public readonly PhysicsBody Body = new();
/// <summary>Scripted world position + cell (defaults to cell 1, origin).</summary>
public Position WorldPosition = new(1u, Vector3.Zero, Quaternion.Identity);
/// <summary>Scripted compass heading, degrees (P5 convention).</summary>
public float Heading;
/// <summary>Records every <c>SetHeading(heading, send)</c> call.</summary>
public readonly List<(float Heading, bool Send)> SetHeadingCalls = new();
public float OwnRadius = 0.5f;
public float OwnHeight = 2.0f;
public bool ContactValue = true;
public bool IsInterpolatingValue;
public Vector3 Velocity = Vector3.Zero;
public uint SelfId = 0x50000001u;
/// <summary>Records every <c>StopCompletely()</c> call (count only —
/// retail's <c>CPhysicsObj::StopCompletely</c> takes no args at this
/// seam level).</summary>
public int StopCompletelyCalls;
public readonly List<(uint ContextId, uint ObjectId, float Radius, double Quantum)> SetTargetCalls = new();
public int ClearTargetCalls;
public double TargetQuantum;
public readonly List<double> SetTargetQuantumCalls = new();
public int UnstickCalls;
public readonly List<(uint Tlid, float Radius, float Height)> StickToCalls = new();
public readonly List<WeenieError> MoveToCompleteCalls = new();
/// <summary>Scripted clock — advances by <see cref="TickSeconds"/> only
/// when a test calls <see cref="Tick"/>; reading <c>CurTime</c> alone
/// (e.g. multiple reads within one manager call) does NOT advance it,
/// matching retail's <c>Timer::cur_time</c> being a stable snapshot for
/// the duration of one dispatch.</summary>
public double CurTime;
public const double TickSeconds = 1.0 / 30.0;
public readonly MoveToManager Manager;
public MoveToManagerHarness()
{
Interp.PhysicsObj = Body;
Body.TransientState = TransientStateFlags.Contact | TransientStateFlags.OnWalkable | TransientStateFlags.Active;
Manager = new MoveToManager(
Interp,
stopCompletely: () => StopCompletelyCalls++,
getPosition: () => WorldPosition,
getHeading: () => Heading,
setHeading: (h, send) => { SetHeadingCalls.Add((h, send)); Heading = h; },
getOwnRadius: () => OwnRadius,
getOwnHeight: () => OwnHeight,
contact: () => ContactValue,
isInterpolating: () => IsInterpolatingValue,
getVelocity: () => Velocity,
getSelfId: () => SelfId,
setTarget: (ctx, obj, radius, quantum) => SetTargetCalls.Add((ctx, obj, radius, quantum)),
clearTarget: () => ClearTargetCalls++,
getTargetQuantum: () => TargetQuantum,
setTargetQuantum: q => { TargetQuantum = q; SetTargetQuantumCalls.Add(q); },
curTime: () => CurTime);
Manager.StickTo = (tlid, radius, height) => StickToCalls.Add((tlid, radius, height));
Manager.MoveToComplete = err => MoveToCompleteCalls.Add(err);
Manager.Unstick = () => UnstickCalls++;
}
/// <summary>Advance the scripted clock by one physics tick (1/30 s).</summary>
public void Tick() => CurTime += TickSeconds;
/// <summary>Advance the scripted clock by an arbitrary amount.</summary>
public void Advance(double seconds) => CurTime += seconds;
/// <summary>
/// Drains the REAL <see cref="MotionInterpreter"/>'s
/// <c>pending_motions</c> queue via synthetic <c>MotionDone</c>
/// callbacks — standing in for "the dispatched motion's animation-table
/// cycle finished", which a live <c>AnimationSequencer</c>/
/// <c>MotionTableManager</c> would signal in production. Every
/// <c>_DoMotion</c>/<c>_StopMotion</c> call that succeeds enqueues a
/// node (retail <c>AddToQueue</c>, decomp's <c>DoInterpretedMotion</c>
/// body); without draining, <see cref="MotionInterpreter.MotionsPending"/>
/// stays true forever in this bare harness, which would wedge
/// <see cref="MoveToManager.BeginTurnToHeading"/>'s wait-for-anims gate
/// and <see cref="MoveToManager.HandleMoveToPosition"/> Phase 1's
/// "animating, stop aux" branch permanently. Call after any manager
/// method that dispatches a motion, before asserting on the NEXT tick's
/// behavior.
/// </summary>
public void DrainPendingMotions()
{
while (Interp.MotionsPending())
Interp.MotionDone(0, true);
}
/// <summary>Current interpreted forward command — the observable proxy
/// for "what motion did MoveToManager just dispatch via _DoMotion",
/// since <see cref="MotionInterpreter.DoInterpretedMotion(uint,MovementParameters)"/>
/// writes through to <see cref="InterpretedMotionState.ApplyMotion"/>
/// when <c>ModifyInterpretedState</c> is set (default true).</summary>
public uint ForwardCommand => Interp.InterpretedState.ForwardCommand;
public uint TurnCommand => Interp.InterpretedState.TurnCommand;
public float ForwardSpeed => Interp.InterpretedState.ForwardSpeed;
}

240
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerTurnToHeadingTests.cs Normal file
View file

@ -0,0 +1,240 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>BeginTurnToHeading</c> (<c>00529b90</c>, raw 307046-307120,
/// decomp §4d) and <c>HandleTurnToHeading</c> (<c>0052a0c0</c>, raw
/// 307442-307517, decomp §6c) — the direction-pick table (TurnRight ≤180 vs
/// TurnLeft &gt;180), the "already there" early-outs, the
/// <c>MotionsPending</c> wait gate, the arrival snap
/// (<see cref="MoveToMath.HeadingGreater"/> + the ONE <c>set_heading</c> in
/// the whole family), and the PreviousHeading DIFF-seed quirk.
/// </summary>
public sealed class MoveToManagerTurnToHeadingTests
{
// ── BeginTurnToHeading direction pick (§4d) ────────────────────────────
[Theory]
[InlineData(0f, 90f, MotionCommand.TurnRight)] // diff=90 <=180 -> TurnRight
[InlineData(0f, 170f, MotionCommand.TurnRight)] // diff=170 <=180 -> TurnRight
[InlineData(0f, 190f, MotionCommand.TurnLeft)] // diff=190 >180 -> TurnLeft
[InlineData(0f, 270f, MotionCommand.TurnLeft)] // diff=270 >180 -> TurnLeft
public void DirectionPick_Table(float currentHeading, float targetHeading, uint expectedTurn)
{
var h = new MoveToManagerHarness();
h.Heading = currentHeading;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = targetHeading });
Assert.Equal(expectedTurn, h.Manager.CurrentCommand);
}
[Fact]
public void DirectionPick_ExactlyAt180_TurnRight_NotStrictlyGreater()
{
// diff > 180 is the TurnLeft gate (strict); exactly 180 stays TurnRight.
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 180f });
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
}
[Fact]
public void AlreadyThere_DiffLessThanOrEqualEpsilon_PopsImmediately_NoDispatch()
{
var h = new MoveToManagerHarness();
h.Heading = 90f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
Assert.Equal(0u, h.Manager.CurrentCommand);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.Empty(h.Manager.PendingActions);
}
[Fact]
public void AlreadyThere_WrappedNearFullCircle_PopsImmediately()
{
// diff > 180 branch's OWN "already there" check: diff + eps >= 360.
var h = new MoveToManagerHarness();
h.Heading = 0.0001f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 0f });
// diff computed via HeadingDiff(0, 0.0001, TurnRight) ~ -0.0001 -> wraps to ~359.9999
// which is > 180 -> TurnLeft branch -> diff+eps >= 360 check.
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void WaitsForPendingAnimations_BeforeArmingTurn()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
// Simulate an in-flight animation-table motion BEFORE the turn is armed.
h.Interp.AddToQueue(0, MotionCommand.WalkForward, 0);
Assert.True(h.Interp.MotionsPending());
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
// BeginNextNode -> BeginTurnToHeading saw MotionsPending() true and
// returned WITHOUT dispatching — CurrentCommand stays 0, the node
// stays queued.
Assert.Equal(0u, h.Manager.CurrentCommand);
Assert.Single(h.Manager.PendingActions);
Assert.Equal(MovementType.TurnToHeading, h.Manager.MovementTypeState);
}
[Fact]
public void EmptyQueue_CancelsWithNoPhysicsObjectCode()
{
var h = new MoveToManagerHarness();
// Calling BeginTurnToHeading directly with no queued node -> CancelMoveTo(NoPhysicsObject, per A10).
h.Manager.BeginTurnToHeading();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void PreviousHeadingSeededWithDiff_NotAHeading()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
// The quirk: PreviousHeading stores the REMAINING DIFF (90), not the
// target heading value coincidentally equal to it here — verify via
// a case where they'd differ.
Assert.Equal(90f, h.Manager.PreviousHeading, 2);
}
[Fact]
public void PreviousHeadingSeed_DiffersFromTargetHeading_ProvingItsADiffNotAHeading()
{
var h = new MoveToManagerHarness();
h.Heading = 30f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
// diff = HeadingDiff(90, 30, TurnRight) = 60 -- NOT 90 (the target
// heading) and NOT 30 (current heading) -- proves PreviousHeading
// stores the DIFF.
Assert.Equal(60f, h.Manager.PreviousHeading, 2);
}
// ── HandleTurnToHeading (§6c): arrival snap + progress test ────────────
[Fact]
public void HandleTurnToHeading_NotCurrentlyTurning_ReArmsViaBeginTurnToHeading()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
h.DrainPendingMotions(); // clear the dispatch so a bare HandleTurnToHeading call doesn't hit the "still turning" path unexpectedly
// Force CurrentCommand to something that isn't a turn (simulating an
// external interrupt that cleared it without popping the node) —
// exercised via CancelMoveTo would drop everything, so instead just
// confirm the normal flow already armed a turn command.
Assert.True(h.Manager.CurrentCommand is MotionCommand.TurnRight or MotionCommand.TurnLeft);
}
[Fact]
public void HandleTurnToHeading_Arrival_SnapsHeadingAndSendsTrue()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
h.DrainPendingMotions();
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
// Advance heading to just past the target (heading_greater says we
// passed it) -- simulates the turn animation having rotated us there.
h.Heading = 91f;
h.Manager.HandleTurnToHeading();
// The ONE heading snap in the whole family: SetHeading(90, send:true).
Assert.Contains((90f, true), h.SetHeadingCalls);
Assert.Equal(90f, h.Heading, 2); // snapped to the EXACT node heading, not 91.
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // queue drained -> complete.
}
[Fact]
public void HandleTurnToHeading_StillTurning_RotationalProgress_ResetsFailCounter()
{
// The first post-BeginTurnToHeading tick compares the LIVE heading
// (still 0, unmoved) against PreviousHeading's quirk-seeded DIFF
// value (170, not a heading) — HeadingDiff(0,170,TurnRight)=190,
// outside (eps,180), so tick 1 reads as NO progress (a numeric
// artifact of the seed, not a real stall) and FailProgressCount
// increments once. From tick 2 onward PreviousHeading holds a REAL
// heading and steady rotation reads as genuine progress.
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 170f });
h.DrainPendingMotions();
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
Assert.Equal(170f, h.Manager.PreviousHeading, 2); // diff-seeded (quirk)
h.Manager.HandleTurnToHeading(); // tick 1 (heading unmoved) -- the seed artifact tick
Assert.Equal(1u, h.Manager.FailProgressCount);
Assert.Equal(0f, h.Manager.PreviousHeading, 2);
h.Heading = 90f; // tick 2: rotated 90 deg toward the 170 target, hasn't passed it.
h.Manager.HandleTurnToHeading();
Assert.Equal(0u, h.Manager.FailProgressCount); // reset by genuine progress
Assert.Equal(90f, h.Manager.PreviousHeading, 2); // updated to the live heading
}
[Fact]
public void HandleTurnToHeading_NoRotationalProgress_IncrementsFailCounter_WhenNotAnimating()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 170f });
h.DrainPendingMotions();
// Heading did not move at all -> HeadingDiff(0, 170, TurnRight):
// seeded PreviousHeading was 170; live heading still 0 -> diff =
// HeadingDiff(0, 170, TurnRight) = -170 -> +360 = 190; the progress
// window is (eps,180) exclusive on the high end -- 190 fails it ->
// no progress -> counter increments (not interpolating, not animating).
h.Manager.HandleTurnToHeading();
Assert.Equal(1u, h.Manager.FailProgressCount);
}
[Fact]
public void HandleTurnToHeading_TurnLeftDirection_UsesMirroredHeadingDiff()
{
var h = new MoveToManagerHarness();
h.Heading = 0f;
// diff = HeadingDiff(190,0,TurnRight) = 190 > 180 -> TurnLeft chosen.
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 190f });
h.DrainPendingMotions();
Assert.Equal(MotionCommand.TurnLeft, h.Manager.CurrentCommand);
// Rotate counter-clockwise (heading decreasing toward the target
// from the TurnLeft direction) -- heading_greater(-, node.Heading=190, TurnLeft)
// needs the mirror-aware diff test to register progress correctly.
h.Heading = 350f; // moved 10 deg counter-clockwise from 0 (i.e. toward 190 the "left" way)
h.Manager.HandleTurnToHeading();
// Just verifying no crash / a sane FailProgressCount either way —
// the mirror's behavioral effect is dead in retail (§8, P3
// adjudication: the mirror only affects fail_progress_count
// reset-vs-increment, which is write-only) so this is a smoke test
// for the TurnLeft code path executing without throwing.
Assert.True(h.Manager.FailProgressCount is 0 or 1);
}
}

150
tests/AcDream.Core.Tests/Physics/Motion/MoveToManagerUseTimeGateTests.cs Normal file
View file

@ -0,0 +1,150 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V2 — <c>UseTime</c> (<c>0052a780</c>, raw 307776-307798, decomp §6a):
/// the three-gate tick matrix (grounded / node-exists / object-move
/// initialized), including the uninitialized type-6 stall case from the
/// port plan's V2 test list.
/// </summary>
public sealed class MoveToManagerUseTimeGateTests
{
[Fact]
public void NoNodeQueued_UseTimeIsANoOp()
{
var h = new MoveToManagerHarness();
// Fresh manager: no active move, no nodes.
h.Manager.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
[Fact]
public void NotGrounded_ContactFalse_UseTimeDoesNothing_EvenWithNodesQueued()
{
var h = new MoveToManagerHarness { ContactValue = false };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f; // face the target so BeginMoveForward runs (no turn-to-face node needed)
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters());
h.DrainPendingMotions();
uint commandBefore = h.Manager.CurrentCommand;
// Move the mover without letting UseTime process it (Contact=false blocks the gate).
h.WorldPosition = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity);
h.Advance(5.0);
h.Manager.UseTime();
// State machine did not advance -- still the same command, same type.
Assert.Equal(commandBefore, h.Manager.CurrentCommand);
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
}
[Fact]
public void Grounded_MoveToPositionNode_DispatchesToHandleMoveToPosition()
{
var h = new MoveToManagerHarness { ContactValue = true };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f; // face the target so BeginMoveForward runs (no turn-to-face node needed)
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false });
h.DrainPendingMotions();
// Arrived: move the mover close to the TARGET (20,0,0), well within
// DistanceToObject, and advance time so CheckProgressMade evaluates
// true and the arrival branch pops.
h.WorldPosition = new Position(1u, new Vector3(19.7f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
h.Manager.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // HandleMoveToPosition ran and completed the move.
}
[Fact]
public void Grounded_TurnToHeadingNode_DispatchesToHandleTurnToHeading()
{
var h = new MoveToManagerHarness { ContactValue = true };
h.Heading = 0f;
h.Manager.TurnToHeading(new MovementParameters { DesiredHeading = 90f });
h.DrainPendingMotions();
Assert.Equal(MotionCommand.TurnRight, h.Manager.CurrentCommand);
h.Heading = 91f; // "passed" the target
h.Manager.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // HandleTurnToHeading ran and completed the turn.
}
[Fact]
public void ObjectMove_UninitializedType6_StallsUntilFirstTargetCallback()
{
// The port plan's named "uninitialized type-6 stall" case: a
// MoveToObject manager with TopLevelObjectId != 0 and
// MovementTypeState != Invalid, but Initialized still false (no
// HandleUpdateTarget callback has arrived yet) -- and CRITICALLY,
// no node is queued yet either (MoveToObject defers node-building
// to the first callback, §3b), so UseTime's node-exists gate (gate
// 2) already blocks it. This test proves the stall holds even if a
// node WERE somehow present (defense in depth for gate 3).
var h = new MoveToManagerHarness { ContactValue = true };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Manager.MoveToObject(0x5000AAAAu, 0x5000AAAAu, 1f, 2f, new MovementParameters());
Assert.False(h.Manager.Initialized);
Assert.Empty(h.Manager.PendingActions); // gate 2 alone already stalls it
h.Manager.UseTime();
// No crash, no state change -- the manager is still waiting.
Assert.Equal(MovementType.MoveToObject, h.Manager.MovementTypeState);
Assert.False(h.Manager.Initialized);
}
[Fact]
public void ObjectMove_Initialized_PassesGate3_ProcessesNormally()
{
var h = new MoveToManagerHarness { ContactValue = true };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f; // face the target so the internal node plan skips the turn-to-face step
h.Manager.MoveToObject(0x5000BBBBu, 0x5000BBBBu, radius: 0.5f, height: 2f, new MovementParameters { UseSpheres = false });
var target = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity);
h.Manager.HandleUpdateTarget(new TargetInfo(0x5000BBBBu, TargetStatus.Ok, target, target));
Assert.True(h.Manager.Initialized);
h.DrainPendingMotions();
h.WorldPosition = new Position(1u, new Vector3(19.5f, 0f, 0f), Quaternion.Identity); // within DistanceToObject default 0.6
h.Advance(2.0);
h.Manager.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // completed via UseTime -> HandleMoveToPosition.
}
[Fact]
public void NonObjectMove_TopLevelIdZero_Gate3AlwaysPasses_RegardlessOfInitialized()
{
// Gate 3: (top_level_object_id == 0 || movement_type == Invalid) ||
// initialized. Position/heading moves never set TopLevelObjectId,
// so the FIRST disjunct alone always satisfies gate 3 -- Initialized
// staying false (as it does for MoveToPosition/TurnToHeading, per
// §3c/§3e's notes) never blocks them.
var h = new MoveToManagerHarness { ContactValue = true };
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
h.Manager.MoveToPosition(new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity), new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false });
h.DrainPendingMotions();
Assert.Equal(0u, h.Manager.TopLevelObjectId);
Assert.False(h.Manager.Initialized);
h.WorldPosition = new Position(1u, new Vector3(19.7f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
h.Manager.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState); // gate 3 passed via the first disjunct.
}
}

91
tests/AcDream.Core.Tests/Physics/Motion/MoveToMathCylinderDistanceTests.cs Normal file
View file

@ -0,0 +1,91 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>Position::cylinder_distance</c>, the pure-math shape per
/// r4-moveto-decomp.md §5a (<c>MoveToManager::GetCurrentDistance</c>,
/// <c>005291b0</c>): edge-to-edge distance between two vertical cylinders
/// (own radius/height, target radius/height, both positions). Object moves
/// (use_spheres set on the wire) use this; position moves use plain
/// Euclidean <c>Position::distance</c> (§5a: "position moves use center
/// distance" — <see cref="MoveToMath.CylinderDistance"/> is the object-move
/// variant only; center distance is <c>Vector3.Distance</c>, already
/// available, not re-ported here).
///
/// <para>
/// The retail signature's exact combination math for radius/height beyond
/// "edge-to-edge, own+target cylinders" is not spelled out in the raw (BN
/// garbles the x87 plumbing) — ported per the PDB argument ORDER
/// (own radius/height, own position, target radius/height, target
/// position) with the standard cylinder-distance shape: horizontal
/// (planar) distance minus the sum of the two radii (clamped at 0), since
/// that is the only shape consistent with "edge-to-edge" and with
/// <c>distance_to_object</c>'s ctor default of 0.6 (melee range from
/// surface to surface, not center to center).
/// </para>
/// </summary>
public sealed class MoveToMathCylinderDistanceTests
{
[Fact]
public void TwoCylinders_HorizontallySeparated_SubtractsBothRadii()
{
// centers 10 units apart on X, radii 1 and 2 → edge distance = 10-1-2=7
float d = MoveToMath.CylinderDistance(
ownRadius: 1f, ownHeight: 2f, ownPos: Vector3.Zero,
targetRadius: 2f, targetHeight: 2f, targetPos: new Vector3(10f, 0f, 0f));
Assert.Equal(7f, d, 3);
}
[Fact]
public void TwoCylinders_Overlapping_ClampsAtZero_NoNegativeDistance()
{
// centers 1 unit apart, radii 5 and 5 → would be -9, clamps to 0
float d = MoveToMath.CylinderDistance(
ownRadius: 5f, ownHeight: 2f, ownPos: Vector3.Zero,
targetRadius: 5f, targetHeight: 2f, targetPos: new Vector3(1f, 0f, 0f));
Assert.Equal(0f, d, 3);
}
[Fact]
public void TwoCylinders_ZeroRadii_ReducesToCenterDistance()
{
float d = MoveToMath.CylinderDistance(
ownRadius: 0f, ownHeight: 2f, ownPos: Vector3.Zero,
targetRadius: 0f, targetHeight: 2f, targetPos: new Vector3(3f, 4f, 0f));
Assert.Equal(5f, d, 3); // 3-4-5 triangle
}
[Fact]
public void TwoCylinders_IgnoresVerticalSeparation_PlanarOnly()
{
// Same X/Y, large Z separation — cylinder_distance in retail's own
// callers (GetCurrentDistance) is used for horizontal arrival gates;
// the Z axis is height, not part of the radial edge-to-edge gap.
float d1 = MoveToMath.CylinderDistance(
ownRadius: 1f, ownHeight: 2f, ownPos: new Vector3(0, 0, 0),
targetRadius: 1f, targetHeight: 2f, targetPos: new Vector3(5f, 0f, 0f));
float d2 = MoveToMath.CylinderDistance(
ownRadius: 1f, ownHeight: 2f, ownPos: new Vector3(0, 0, 50f),
targetRadius: 1f, targetHeight: 2f, targetPos: new Vector3(5f, 0f, -50f));
Assert.Equal(d1, d2, 3);
Assert.Equal(3f, d1, 3); // 5 - 1 - 1
}
[Fact]
public void SamePosition_ZeroDistance_ClampsNotNegative()
{
float d = MoveToMath.CylinderDistance(
ownRadius: 0.5f, ownHeight: 2f, ownPos: Vector3.Zero,
targetRadius: 0.5f, targetHeight: 2f, targetPos: Vector3.Zero);
Assert.Equal(0f, d, 3);
}
}

164
tests/AcDream.Core.Tests/Physics/Motion/MoveToMathHeadingDiffTests.cs Normal file
View file

@ -0,0 +1,164 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>heading_diff</c> (<c>0x00528fb0</c>), PINNED by direct
/// disassembly of the PDB-matched retail binary (see
/// docs/research/2026-07-03-r4-moveto/ghidra-confirmations.md §P3 — this is
/// the strongest evidence tier in the whole R4 pin set, one level above a
/// Ghidra decompile). Verbatim body:
/// <code>
/// d = h1 - h2;
/// if (fabs(h1 - h2) &lt; F_EPSILON) d = 0;
/// if (d &lt; -F_EPSILON) d += 360;
/// if (F_EPSILON &lt; d &amp;&amp; turnCmd != TurnRight) d = 360 - d; // the mirror
/// return d;
/// </code>
/// F_EPSILON = 0.000199999995f. The mirror gates on the turn command being
/// NOT TurnRight (0x6500000d) — TurnLeft (and any other command) measures
/// the COMPLEMENTARY angle. This contradicts r4-moveto-decomp.md §5g's
/// "arg3 UNUSED" claim, which the Ghidra pin overrides (adjudicated in
/// V0-pins.md).
/// </summary>
public sealed class MoveToMathHeadingDiffTests
{
private const float Eps = 0.000199999995f;
private const uint TurnRight = MotionCommand.TurnRight;
private const uint TurnLeft = MotionCommand.TurnLeft;
// ── basic subtraction, TurnRight (no mirror) ───────────────────────────
[Fact]
public void TurnRight_SimplePositiveDiff_NoWrap()
{
float d = MoveToMath.HeadingDiff(90f, 30f, TurnRight);
Assert.Equal(60f, d, 3);
}
[Fact]
public void TurnRight_NegativeDiff_WrapsBy360()
{
// h1 - h2 = 30 - 90 = -60 → wraps to 300
float d = MoveToMath.HeadingDiff(30f, 90f, TurnRight);
Assert.Equal(300f, d, 3);
}
[Fact]
public void TurnRight_ZeroDiff_IsZero()
{
float d = MoveToMath.HeadingDiff(45f, 45f, TurnRight);
Assert.Equal(0f, d, 3);
}
// ── epsilon boundary (both sides) ──────────────────────────────────────
[Fact]
public void EpsilonBoundary_ExactlyAtEpsilon_NotSnappedToZero()
{
// fabs(d) < EPSILON is a STRICT less-than — exactly at epsilon does
// NOT snap to zero.
float d = MoveToMath.HeadingDiff(Eps, 0f, TurnRight);
Assert.NotEqual(0f, d);
Assert.Equal(Eps, d, 6);
}
[Fact]
public void EpsilonBoundary_JustBelowEpsilon_SnapsToZero()
{
float d = MoveToMath.HeadingDiff(Eps * 0.5f, 0f, TurnRight);
Assert.Equal(0f, d);
}
[Fact]
public void EpsilonBoundary_NegativeJustBelowNegEpsilon_WrapsBy360()
{
// d = -Eps * 1.5 < -Eps → wraps
float raw = -Eps * 1.5f;
float d = MoveToMath.HeadingDiff(raw, 0f, TurnRight);
Assert.Equal(raw + 360f, d, 3);
}
[Fact]
public void EpsilonBoundary_NegativeExactlyAtNegEpsilon_DoesNotWrap()
{
// d < -EPSILON is STRICT — exactly -EPSILON does not wrap.
float d = MoveToMath.HeadingDiff(-Eps, 0f, TurnRight);
Assert.Equal(-Eps, d, 6);
}
// ── the mirror (TurnLeft / not-TurnRight) ──────────────────────────────
[Fact]
public void TurnLeft_PositiveDiffAboveEpsilon_MirroredTo360MinusD()
{
float d = MoveToMath.HeadingDiff(90f, 30f, TurnLeft);
// raw = 60; mirror: 360 - 60 = 300
Assert.Equal(300f, d, 3);
}
[Fact]
public void TurnLeft_NegativeDiff_WrapsThenMirrors()
{
// h1-h2 = 30-90 = -60 → wraps to 300 → mirror gate (300 > EPS, not
// TurnRight) → 360 - 300 = 60
float d = MoveToMath.HeadingDiff(30f, 90f, TurnLeft);
Assert.Equal(60f, d, 3);
}
[Fact]
public void TurnLeft_ZeroDiff_MirrorGateDoesNotFire_StaysZero()
{
// d == 0 does not satisfy `d > EPSILON`, so the mirror never fires
// regardless of turn command.
float d = MoveToMath.HeadingDiff(45f, 45f, TurnLeft);
Assert.Equal(0f, d);
}
[Fact]
public void TurnLeft_AtEpsilonBoundary_MirrorGateIsStrictGreaterThan()
{
// d > EPSILON is STRICT: exactly at EPSILON does NOT mirror.
float d = MoveToMath.HeadingDiff(Eps, 0f, TurnLeft);
Assert.Equal(Eps, d, 6);
}
[Fact]
public void TurnLeft_JustAboveEpsilon_Mirrors()
{
float raw = Eps * 2f;
float d = MoveToMath.HeadingDiff(raw, 0f, TurnLeft);
Assert.Equal(360f - raw, d, 3);
}
[Fact]
public void AnyNonTurnRightCommand_AlsoMirrors()
{
// The gate is "!= TurnRight", not "== TurnLeft" — any other command
// (e.g. 0, WalkForward) also triggers the mirror.
float d = MoveToMath.HeadingDiff(90f, 30f, 0u);
Assert.Equal(300f, d, 3);
float d2 = MoveToMath.HeadingDiff(90f, 30f, MotionCommand.WalkForward);
Assert.Equal(300f, d2, 3);
}
// ── 360-wrap combined with the mirror ──────────────────────────────────
[Fact]
public void TurnRight_FullCircleInputs_NormalizeCorrectly()
{
float d = MoveToMath.HeadingDiff(350f, 10f, TurnRight);
Assert.Equal(340f, d, 3);
}
[Fact]
public void TurnLeft_FullCircleInputs_MirroredAfterNormalize()
{
// raw = 350-10 = 340 (no wrap needed, positive); mirror: 360-340=20
float d = MoveToMath.HeadingDiff(350f, 10f, TurnLeft);
Assert.Equal(20f, d, 3);
}
}

82
tests/AcDream.Core.Tests/Physics/Motion/MoveToMathHeadingGreaterTests.cs Normal file
View file

@ -0,0 +1,82 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>heading_greater</c> (<c>00528f60</c>, raw 306281-306323), per
/// r4-moveto-decomp.md §5f:
/// <code>
/// if (fabs(a - b) &gt; 180) greater = (b &gt; a); // wrapped case: compare flipped
/// else greater = (a &gt; b);
/// if (turnCmd == TurnRight) return greater;
/// return !greater; // TurnLeft: inverted
/// </code>
/// "Has the turn passed the target heading" — direction-aware, wrap-aware.
/// </summary>
public sealed class MoveToMathHeadingGreaterTests
{
private const uint TurnRight = MotionCommand.TurnRight;
private const uint TurnLeft = MotionCommand.TurnLeft;
[Fact]
public void TurnRight_UnwrappedCase_SimpleGreater()
{
Assert.True(MoveToMath.HeadingGreater(90f, 30f, TurnRight));
Assert.False(MoveToMath.HeadingGreater(30f, 90f, TurnRight));
}
[Fact]
public void TurnRight_WrappedCase_ComparisonFlips()
{
// |350 - 10| = 340 > 180 → wrapped: greater = (b > a) = (10 > 350) = false
Assert.False(MoveToMath.HeadingGreater(350f, 10f, TurnRight));
// |10 - 350| = 340 > 180 → wrapped: greater = (b > a) = (350 > 10) = true
Assert.True(MoveToMath.HeadingGreater(10f, 350f, TurnRight));
}
[Fact]
public void TurnRight_ExactlyAt180Delta_UnwrappedBranch()
{
// fabs(a-b) > 180 is STRICT — exactly 180 uses the unwrapped branch.
// a=200,b=20: fabs=180, not >180 → greater = (a>b) = true
Assert.True(MoveToMath.HeadingGreater(200f, 20f, TurnRight));
}
[Fact]
public void TurnLeft_InvertsTheUnwrappedResult()
{
Assert.False(MoveToMath.HeadingGreater(90f, 30f, TurnLeft));
Assert.True(MoveToMath.HeadingGreater(30f, 90f, TurnLeft));
}
[Fact]
public void TurnLeft_InvertsTheWrappedResult()
{
Assert.True(MoveToMath.HeadingGreater(350f, 10f, TurnLeft));
Assert.False(MoveToMath.HeadingGreater(10f, 350f, TurnLeft));
}
[Fact]
public void EqualHeadings_NotGreater_TurnRight()
{
Assert.False(MoveToMath.HeadingGreater(45f, 45f, TurnRight));
}
[Fact]
public void EqualHeadings_InvertedToTrue_TurnLeft()
{
// greater=false for equal headings; TurnLeft inverts → true.
Assert.True(MoveToMath.HeadingGreater(45f, 45f, TurnLeft));
}
[Fact]
public void AnyNonTurnRightCommand_AlsoInverts()
{
// The retail gate is `== TurnRight` (not `!= TurnRight` as in
// heading_diff) — every OTHER command, not just TurnLeft, inverts.
Assert.False(MoveToMath.HeadingGreater(90f, 30f, 0u));
Assert.False(MoveToMath.HeadingGreater(90f, 30f, MotionCommand.WalkForward));
}
}

127
tests/AcDream.Core.Tests/Physics/Motion/MoveToMathPositionHeadingTests.cs Normal file
View file

@ -0,0 +1,127 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>Position::heading</c> / <c>Frame::get_heading</c> /
/// <c>Frame::set_heading</c>, per V0-pins.md §P5 (PINNED — compass degrees,
/// 0 = North (+Y), 90 = East (+X), CLOCKWISE, [0,360); identity quaternion
/// faces heading 0):
/// <code>
/// heading(from, to) = (450 - atan2Deg(dy, dx)) % 360
/// </code>
/// Golden cardinals: N(0,+1)→0, E(+1,0)→90, S(0,-1)→180, W(-1,0)→270.
///
/// <para>
/// <b>The packer-reuse trap (V0-pins §P5 correction):</b> acdream's
/// outbound packer (<c>GameWindow.YawToAcQuaternion</c>) is wire-correct at
/// the QUATERNION level but its internal scalar intermediate
/// (<c>headingDeg = 180 - yawDeg</c>) is holtburger's shifted convention,
/// NOT retail's wire convention. <see cref="MoveToMath.GetHeading"/> must
/// use the CORRECT scalar bridge from acdream yaw (yaw=0 faces +X, per
/// <c>PlayerMovementController.cs:1022-1025</c>): <c>heading = (90 -
/// yawDeg) mod 360</c> — NOT <c>180 - yawDeg</c>.
/// </para>
/// </summary>
public sealed class MoveToMathPositionHeadingTests
{
private const float Tol = 0.01f;
// ── PositionHeading: the four cardinal offsets ─────────────────────────
[Fact]
public void North_PlusY_IsZero()
{
float h = MoveToMath.PositionHeading(Vector3.Zero, new Vector3(0f, 1f, 0f));
Assert.Equal(0f, h, 2);
}
[Fact]
public void East_PlusX_Is90()
{
float h = MoveToMath.PositionHeading(Vector3.Zero, new Vector3(1f, 0f, 0f));
Assert.Equal(90f, h, 2);
}
[Fact]
public void South_MinusY_Is180()
{
float h = MoveToMath.PositionHeading(Vector3.Zero, new Vector3(0f, -1f, 0f));
Assert.Equal(180f, h, 2);
}
[Fact]
public void West_MinusX_Is270()
{
float h = MoveToMath.PositionHeading(Vector3.Zero, new Vector3(-1f, 0f, 0f));
Assert.Equal(270f, h, 2);
}
[Fact]
public void Heading_IsAlways_InZeroToThreeSixtyRange()
{
// NE diagonal
float h = MoveToMath.PositionHeading(Vector3.Zero, new Vector3(1f, 1f, 0f));
Assert.InRange(h, 0f, 360f);
Assert.Equal(45f, h, 2);
}
[Fact]
public void Heading_IgnoresZ_HorizontalOnly()
{
float h1 = MoveToMath.PositionHeading(new Vector3(0, 0, 5f), new Vector3(1f, 0f, -10f));
float h2 = MoveToMath.PositionHeading(new Vector3(0, 0, -3f), new Vector3(1f, 0f, 100f));
Assert.Equal(h1, h2, 2);
Assert.Equal(90f, h1, 2);
}
// ── GetHeading: extracts heading from a body orientation quaternion ────
[Fact]
public void GetHeading_IdentityQuaternion_FacesHeadingZero()
{
// Identity quaternion → acdream yaw = 0 → +X-facing in our
// convention, which decodes to AC heading 90 per the corrected
// scalar bridge... BUT the identity quaternion in acdream's body
// frame corresponds to yaw = -PI/2 relative to +Y-forward (see
// PlayerMovementController.cs:1025: Orientation = AxisAngle(Yaw -
// PI/2)). GetHeading must invert that exact convention: identity
// orientation (no rotation applied) means Yaw=PI/2 was baked in,
// which is heading 0 — matching P5's "identity quaternion faces
// heading 0" pin.
float h = MoveToMath.GetHeading(Quaternion.Identity);
Assert.Equal(0f, h, 1);
}
[Fact]
public void GetHeading_SetHeading_RoundTrips_Cardinals()
{
foreach (float heading in new[] { 0f, 90f, 180f, 270f, 45f, 359f })
{
var q = MoveToMath.SetHeading(Quaternion.Identity, heading);
float back = MoveToMath.GetHeading(q);
float diff = MathF.Abs(back - heading);
if (diff > 180f) diff = 360f - diff;
Assert.True(diff < 0.5f, $"heading {heading} round-tripped to {back}");
}
}
[Fact]
public void SetHeading_North_ProducesForwardVectorFacingPlusY()
{
var q = MoveToMath.SetHeading(Quaternion.Identity, 0f);
var forward = Vector3.Transform(new Vector3(0f, 1f, 0f), q);
Assert.True(forward.Y > 0.9f, $"expected +Y forward, got {forward}");
}
[Fact]
public void SetHeading_East_ProducesForwardVectorFacingPlusX()
{
var q = MoveToMath.SetHeading(Quaternion.Identity, 90f);
var forward = Vector3.Transform(new Vector3(0f, 1f, 0f), q);
Assert.True(forward.X > 0.9f, $"expected +X forward, got {forward}");
}
}

341
tests/AcDream.Core.Tests/Physics/Motion/MovementManagerTests.cs Normal file
View file

@ -0,0 +1,341 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5-V5 — <see cref="MovementManager"/> facade conformance (retail struct
/// acclient.h /* 3463 */; methods 0x00524000-0x00524790, decomp extract
/// <c>docs/research/2026-07-03-r5-managers/r5-movementmanager-decomp.md</c>).
/// The facade is pure relay/ownership — these tests pin the retail call
/// shapes: which child each method touches, the lazy MakeMoveToManager
/// create, the PerformMovement type dispatch, and null-tolerance before the
/// moveto manager exists. Behavior of the children themselves is covered by
/// the MotionInterpreter / MoveToManager suites (UNMODIFIED by R5-V5).
/// </summary>
public sealed class MovementManagerTests
{
/// <summary>Non-creature weenie: silences the MotionInterpreter's
/// HitGround/LeaveGround creature gates (retail IsCreature vtable
/// +0x2c) so a test can isolate the facade's MOVETO relay leg.</summary>
private sealed class NonCreatureWeenie : IWeenieObject
{
public bool InqJumpVelocity(float extent, out float vz) { vz = 0f; return false; }
public bool InqRunRate(out float rate) { rate = 1f; return false; }
public bool CanJump(float extent) => false;
bool IWeenieObject.IsCreature() => false;
}
/// <summary>Facade over the shared MoveToManagerHarness: the harness's
/// REAL MotionInterpreter is the minterp child; the harness's REAL
/// seam-scripted MoveToManager arrives via <see cref="MovementManager.MoveToFactory"/>
/// (the acdream stand-in for retail's physics_obj/weenie_obj
/// backpointers that MakeMoveToManager constructs from).</summary>
private static (MovementManager Mm, MoveToManagerHarness H, int[] FactoryCalls) MakeFacade()
{
var h = new MoveToManagerHarness();
var factoryCalls = new int[1];
var mm = new MovementManager(h.Interp)
{
MoveToFactory = () => { factoryCalls[0]++; return h.Manager; },
};
return (mm, h, factoryCalls);
}
// ── MakeMoveToManager — 0x00524000 ──────────────────────────────────────
[Fact]
public void MakeMoveToManager_CreatesViaFactory_ExactlyOnce()
{
var (mm, h, calls) = MakeFacade();
Assert.Null(mm.MoveTo);
mm.MakeMoveToManager();
Assert.Same(h.Manager, mm.MoveTo);
Assert.Equal(1, calls[0]);
// Retail: no-op if already present.
mm.MakeMoveToManager();
Assert.Same(h.Manager, mm.MoveTo);
Assert.Equal(1, calls[0]);
}
[Fact]
public void MakeMoveToManager_WithoutFactory_IsANoOp()
{
var mm = new MovementManager(new MotionInterpreter());
mm.MakeMoveToManager();
Assert.Null(mm.MoveTo);
}
// ── PerformMovement — 0x005240d0 (the type-1..9 two-way dispatch) ───────
[Fact]
public void PerformMovement_InterpTypes_RouteToMinterp_NotMoveTo()
{
var (mm, h, calls) = MakeFacade();
var result = mm.PerformMovement(new MovementStruct
{
Type = MovementType.InterpretedCommand,
Motion = MotionCommand.WalkForward,
Speed = 1f,
ModifyInterpretedState = true,
});
Assert.Equal(WeenieError.None, result);
Assert.Equal(MotionCommand.WalkForward, h.Interp.InterpretedState.ForwardCommand);
// Types 1-5 never touch the moveto side (jump table 0x0052415c).
Assert.Equal(0, calls[0]);
Assert.Null(mm.MoveTo);
}
[Fact]
public void PerformMovement_MoveToTypes_LazyCreate_AndRouteToMoveTo()
{
var (mm, h, calls) = MakeFacade();
var result = mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
// Retail cases 5-8 (types 6-9): MakeMoveToManager first, delegate,
// and the MoveToManager path's return is NOT propagated (@0052414f
// `return 0`) — the facade reports None regardless.
Assert.Equal(WeenieError.None, result);
Assert.Equal(1, calls[0]);
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
}
[Fact]
public void PerformMovement_InvalidAndOutOfRangeTypes_Fail0x47()
{
var (mm, _, calls) = MakeFacade();
// Retail head: (type - 1) > 8 → 0x47. Type 0 underflows unsigned →
// always > 8; anything above 9 fails the same check.
Assert.Equal(WeenieError.GeneralMovementFailure,
mm.PerformMovement(new MovementStruct { Type = MovementType.Invalid }));
Assert.Equal(WeenieError.GeneralMovementFailure,
mm.PerformMovement(new MovementStruct { Type = (MovementType)10 }));
Assert.Equal(0, calls[0]);
}
[Fact]
public void PerformMovement_MoveToType_WithoutFactory_Fails0x47()
{
// acdream-only guard for the unreachable-in-production ordering
// (a type-6..9 event before the bind sites set MoveToFactory):
// retail would MoveToManager::Create here; without a factory the
// facade reports the same 0x47 the range check uses.
var mm = new MovementManager(new MotionInterpreter());
Assert.Equal(WeenieError.GeneralMovementFailure,
mm.PerformMovement(new MovementStruct { Type = MovementType.TurnToHeading }));
}
// ── UseTime — 0x005242f0 (moveto only; never lazy-creates) ──────────────
[Fact]
public void UseTime_BeforeMoveToExists_IsANoOp_AndDoesNotCreate()
{
var (mm, _, calls) = MakeFacade();
mm.UseTime();
Assert.Equal(0, calls[0]);
Assert.Null(mm.MoveTo);
}
[Fact]
public void UseTime_RelaysToMoveTo()
{
// The MoveToManagerUseTimeGateTests arrival shape, driven through
// the facade: grounded, facing the target, arrived — one UseTime
// completes the move.
var (mm, h, _) = MakeFacade();
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters { DistanceToObject = 0.6f, UseSpheres = false },
});
h.DrainPendingMotions();
h.WorldPosition = new Position(1u, new Vector3(19.7f, 0f, 0f), Quaternion.Identity);
h.Advance(2.0);
mm.UseTime();
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
}
// ── HitGround — 0x00524300 (minterp FIRST, then moveto) ────────────────
[Fact]
public void HitGround_RelaysToMinterp_AndToleratesNullMoveTo()
{
var (mm, h, _) = MakeFacade();
h.Body.State |= PhysicsStateFlags.Gravity; // CMotionInterp::HitGround gates on state & 0x400
bool minterpHit = false;
h.Interp.RemoveLinkAnimations = () => minterpHit = true;
mm.HitGround(); // MoveTo still null — retail's if-present guard
Assert.True(minterpHit);
}
[Fact]
public void HitGround_RelaysMinterpFirst_ThenMoveTo()
{
var (mm, h, _) = MakeFacade();
h.Body.State |= PhysicsStateFlags.Gravity;
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
h.DrainPendingMotions();
// Order pin: the FIRST RemoveLinkAnimations firing belongs to the
// minterp leg (CMotionInterp::HitGround invokes it before any
// dispatch), at which point the moveto leg's BeginNextNode
// re-dispatch has NOT happened yet — the pending queue is still
// drained. Later firings (the moveto dispatch's own TS-40
// detached-strip at the DoInterpretedMotion tail runs AFTER its
// enqueue) must not overwrite the recording — ??= keeps the first.
bool? queueEmptyAtMinterpLeg = null;
h.Interp.RemoveLinkAnimations =
() => queueEmptyAtMinterpLeg ??= !h.Interp.MotionsPending();
mm.HitGround();
Assert.True(queueEmptyAtMinterpLeg); // minterp leg ran first
Assert.True(h.Interp.MotionsPending()); // a re-dispatch landed after it
}
[Fact]
public void HitGround_ReachesMoveTo_WhenMinterpLegIsGated()
{
// Isolate the MOVETO leg: a non-creature weenie makes
// CMotionInterp::HitGround a retail no-op (IsCreature gate), so any
// re-dispatched pending motion can only come from
// MoveToManager::HitGround → BeginNextNode.
var (mm, h, _) = MakeFacade();
h.Interp.WeenieObj = new NonCreatureWeenie();
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
h.DrainPendingMotions();
mm.HitGround();
Assert.True(h.Interp.MotionsPending());
}
// ── HandleExitWorld — 0x00524350 (minterp ONLY) ─────────────────────────
[Fact]
public void HandleExitWorld_DrainsMinterp_AndDoesNotTouchMoveTo()
{
var (mm, h, _) = MakeFacade();
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
h.Heading = 90f;
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
Assert.True(h.Interp.MotionsPending()); // the arm's dispatch is queued
mm.HandleExitWorld();
Assert.False(h.Interp.MotionsPending());
// Retail HandleExitWorld does NOT touch moveto_manager — the armed
// move survives (its teardown is CancelMoveTo / exit-world at the
// CPhysicsObj layer, not here).
Assert.Equal(MovementType.MoveToPosition, h.Manager.MovementTypeState);
}
// ── CancelMoveTo — 0x005241b0 / IsMovingTo — 0x00524260 ────────────────
[Fact]
public void CancelMoveTo_NullTolerant_AndRelaysToMoveTo()
{
var (mm, h, _) = MakeFacade();
mm.CancelMoveTo(WeenieError.ActionCancelled); // no moveto yet — no throw
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = new Position(1u, new Vector3(20f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
Assert.True(mm.IsMovingTo());
mm.CancelMoveTo(WeenieError.ActionCancelled);
Assert.Equal(MovementType.Invalid, h.Manager.MovementTypeState);
Assert.False(mm.IsMovingTo());
Assert.True(h.StopCompletelyCalls > 0);
}
[Fact]
public void IsMovingTo_FalseBeforeMoveToExists()
{
var (mm, _, _) = MakeFacade();
Assert.False(mm.IsMovingTo());
}
// ── HandleUpdateTarget — 0x00524790 (→ moveto) ──────────────────────────
[Fact]
public void HandleUpdateTarget_NullTolerant_AndFeedsMoveToDeferredStart()
{
var (mm, h, _) = MakeFacade();
var info = new TargetInfo
{
ObjectId = 0x5000AAAAu,
Status = TargetStatus.Ok,
TargetPosition = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity),
InterpolatedPosition = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity),
};
mm.HandleUpdateTarget(info); // no moveto yet — no throw
// The V2 "uninitialized type-6 stall": MoveToObject defers its node
// build to the FIRST HandleUpdateTarget delivery.
h.ContactValue = true;
h.WorldPosition = new Position(1u, Vector3.Zero, Quaternion.Identity);
mm.PerformMovement(new MovementStruct
{
Type = MovementType.MoveToObject,
ObjectId = 0x5000AAAAu,
TopLevelId = 0x5000AAAAu,
Pos = new Position(1u, new Vector3(10f, 0f, 0f), Quaternion.Identity),
Params = new MovementParameters(),
});
Assert.False(h.Manager.Initialized);
mm.HandleUpdateTarget(info);
Assert.True(h.Manager.Initialized);
}
}

186
tests/AcDream.Core.Tests/Physics/Motion/MovementParametersFromWireTests.cs Normal file
View file

@ -0,0 +1,186 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>MovementParameters::UnPackNet</c> (<c>0x0052ac50</c>, raw
/// 308118-308205) factory semantics, per
/// docs/research/2026-07-03-r4-moveto/r4-moveto-decomp.md §2g: the 7-dword
/// MoveTo wire form is <c>bitfield, distance_to_object, min_distance,
/// fail_distance, speed, walk_run_threshhold, desired_heading</c> — the SAME
/// field order <c>UpdateMotion.TryParseMoveToPayload</c> already reads off
/// the wire (UpdateMotion.cs:328-341). The A4 bitfield masks
/// (W0-pins.md §A4) decode into the named bool properties; every bit not
/// present on the wire bitfield resolves to false (UnPackNet fully
/// overwrites the bitfield — no ctor-default bits survive).
/// </summary>
public sealed class MovementParametersFromWireTests
{
[Fact]
public void FromWire_AllBitsSet_EveryFlagTrue()
{
var p = MovementParameters.FromWire(
bitfield: 0x3FFFFu, // every A4 bit through 0x20000
distanceToObject: 1f,
minDistance: 2f,
failDistance: 3f,
speed: 4f,
walkRunThreshhold: 5f,
desiredHeading: 6f);
Assert.True(p.CanWalk);
Assert.True(p.CanRun);
Assert.True(p.CanSidestep);
Assert.True(p.CanWalkBackwards);
Assert.True(p.CanCharge);
Assert.True(p.FailWalk);
Assert.True(p.UseFinalHeading);
Assert.True(p.Sticky);
Assert.True(p.MoveAway);
Assert.True(p.MoveTowards);
Assert.True(p.UseSpheres);
Assert.True(p.SetHoldKey);
Assert.True(p.Autonomous);
Assert.True(p.ModifyRawState);
Assert.True(p.ModifyInterpretedState);
Assert.True(p.CancelMoveTo);
Assert.True(p.StopCompletelyFlag);
Assert.True(p.DisableJumpDuringLink);
}
[Fact]
public void FromWire_ZeroBitfield_EveryFlagFalse_NoCtorDefaultsSurvive()
{
var p = MovementParameters.FromWire(
bitfield: 0u,
distanceToObject: 1f, minDistance: 2f, failDistance: 3f,
speed: 4f, walkRunThreshhold: 5f, desiredHeading: 6f);
Assert.False(p.CanWalk);
Assert.False(p.CanRun);
Assert.False(p.CanSidestep);
Assert.False(p.CanWalkBackwards);
Assert.False(p.CanCharge);
Assert.False(p.MoveTowards);
Assert.False(p.UseSpheres);
Assert.False(p.SetHoldKey);
Assert.False(p.ModifyRawState);
Assert.False(p.ModifyInterpretedState);
Assert.False(p.CancelMoveTo);
Assert.False(p.StopCompletelyFlag);
}
[Fact]
public void FromWire_CanChargeBit_DecodesIndependently()
{
// The wire bitfield carries can_charge 0x10 — the walk-vs-run answer
// (feedback_autowalk_cancharge_bit). Verify it round-trips on its own.
var p = MovementParameters.FromWire(
bitfield: 0x10u,
distanceToObject: 0f, minDistance: 0f, failDistance: 0f,
speed: 0f, walkRunThreshhold: 0f, desiredHeading: 0f);
Assert.True(p.CanCharge);
Assert.False(p.CanWalk);
Assert.False(p.CanRun);
}
[Theory]
[InlineData(0x1u)]
[InlineData(0x2u)]
[InlineData(0x4u)]
[InlineData(0x8u)]
[InlineData(0x10u)]
[InlineData(0x20u)]
[InlineData(0x40u)]
[InlineData(0x80u)]
[InlineData(0x100u)]
[InlineData(0x200u)]
[InlineData(0x400u)]
[InlineData(0x800u)]
[InlineData(0x1000u)]
[InlineData(0x2000u)]
[InlineData(0x4000u)]
[InlineData(0x8000u)]
[InlineData(0x10000u)]
[InlineData(0x20000u)]
public void FromWire_SingleBitMaskRoundTrips(uint mask)
{
var p = MovementParameters.FromWire(
bitfield: mask,
distanceToObject: 0f, minDistance: 0f, failDistance: 0f,
speed: 0f, walkRunThreshhold: 0f, desiredHeading: 0f);
Assert.Equal(mask, ToBitfield(p));
}
[Fact]
public void FromWire_ScalarFields_CopiedInWireOrder()
{
var p = MovementParameters.FromWire(
bitfield: 0u,
distanceToObject: 1.5f,
minDistance: 2.5f,
failDistance: 3.5f,
speed: 4.5f,
walkRunThreshhold: 5.5f,
desiredHeading: 6.5f);
Assert.Equal(1.5f, p.DistanceToObject);
Assert.Equal(2.5f, p.MinDistance);
Assert.Equal(3.5f, p.FailDistance);
Assert.Equal(4.5f, p.Speed);
Assert.Equal(5.5f, p.WalkRunThreshhold);
Assert.Equal(6.5f, p.DesiredHeading);
}
[Fact]
public void FromWireTurnTo_ThreeDwordForm_LeavesDistanceFieldsAtDefault()
{
// TurnToObject/TurnToHeading wire form (0xc bytes, 3 dwords):
// bitfield, speed, desired_heading only. distance_to_object /
// min_distance / fail_distance / walk_run_threshhold are NOT on
// this wire form — the factory overload must not touch them
// (they keep the MovementParameters ctor defaults).
var p = MovementParameters.FromWireTurnTo(
bitfield: 0x2u, // can_run
speed: 2f,
desiredHeading: 90f);
Assert.True(p.CanRun);
Assert.Equal(2f, p.Speed);
Assert.Equal(90f, p.DesiredHeading);
// ctor defaults, untouched by the 3-dword form:
Assert.Equal(0.6f, p.DistanceToObject);
Assert.Equal(0f, p.MinDistance);
Assert.Equal(float.MaxValue, p.FailDistance);
Assert.Equal(15f, p.WalkRunThreshhold);
}
private static uint ToBitfield(MovementParameters p)
{
uint bitfield = 0;
if (p.CanWalk) bitfield |= 0x1;
if (p.CanRun) bitfield |= 0x2;
if (p.CanSidestep) bitfield |= 0x4;
if (p.CanWalkBackwards) bitfield |= 0x8;
if (p.CanCharge) bitfield |= 0x10;
if (p.FailWalk) bitfield |= 0x20;
if (p.UseFinalHeading) bitfield |= 0x40;
if (p.Sticky) bitfield |= 0x80;
if (p.MoveAway) bitfield |= 0x100;
if (p.MoveTowards) bitfield |= 0x200;
if (p.UseSpheres) bitfield |= 0x400;
if (p.SetHoldKey) bitfield |= 0x800;
if (p.Autonomous) bitfield |= 0x1000;
if (p.ModifyRawState) bitfield |= 0x2000;
if (p.ModifyInterpretedState) bitfield |= 0x4000;
if (p.CancelMoveTo) bitfield |= 0x8000;
if (p.StopCompletelyFlag) bitfield |= 0x10000;
if (p.DisableJumpDuringLink) bitfield |= 0x20000;
return bitfield;
}
}

340
tests/AcDream.Core.Tests/Physics/Motion/MovementParametersGetCommandTests.cs Normal file
View file

@ -0,0 +1,340 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>MovementParameters::get_command</c> (<c>0x0052aa00</c>, raw
/// 307946-308012), verbatim per
/// docs/research/2026-07-03-r4-moveto/r4-moveto-decomp.md §5c. Covers the
/// command/moving_away pick (plain-towards / plain-away / towards_and_away
/// delegate) crossed with the walk-vs-run HoldKey cascade, INCLUDING the
/// CanCharge 0x10 fast-path ACE dropped (feedback_autowalk_cancharge_bit)
/// and the walk_run_threshhold ≤-vs-&lt; edge (retail: dist - dto ≤
/// threshold → walk; the raw's `test ah,0x41` is the inclusive ≤ reading,
/// §5c @308003).
/// </summary>
public sealed class MovementParametersGetCommandTests
{
// ── plain TOWARDS (move_towards set, move_away clear) ─────────────────
[Fact]
public void PlainTowards_DistGreaterThanDto_WalkForward_NotMovingAway()
{
var p = new MovementParameters { DistanceToObject = 0.6f };
// move_towards=true (default), move_away=false (default)
p.GetCommand(dist: 5f, headingDiff: 0f, out uint motion, out HoldKey holdKey, out bool movingAway);
Assert.Equal(MotionCommand.WalkForward, motion);
Assert.False(movingAway);
}
[Fact]
public void PlainTowards_DistNotGreaterThanDto_Idle()
{
var p = new MovementParameters { DistanceToObject = 0.6f };
p.GetCommand(dist: 0.6f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(0u, motion);
Assert.False(movingAway);
}
[Fact]
public void PlainTowards_DistLessThanDto_Idle()
{
var p = new MovementParameters { DistanceToObject = 0.6f };
p.GetCommand(dist: 0.1f, headingDiff: 0f, out uint motion, out _, out _);
Assert.Equal(0u, motion);
}
// ── pure AWAY (move_away set, move_towards clear) ─────────────────────
[Fact]
public void PureAway_DistLessThanMinDistance_WalkForward_MovingAway()
{
var p = new MovementParameters
{
MoveTowards = false,
MoveAway = true,
MinDistance = 5f,
};
p.GetCommand(dist: 2f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(MotionCommand.WalkForward, motion);
Assert.True(movingAway);
}
[Fact]
public void PureAway_DistNotLessThanMinDistance_Idle()
{
var p = new MovementParameters
{
MoveTowards = false,
MoveAway = true,
MinDistance = 5f,
};
p.GetCommand(dist: 5f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(0u, motion);
Assert.False(movingAway);
}
// ── towards_and_away delegate (both move_towards AND move_away set) ───
[Fact]
public void TowardsAndAway_DistGreaterThanDto_DelegatesToWalkForwardTowards()
{
var p = new MovementParameters
{
MoveTowards = true,
MoveAway = true,
DistanceToObject = 0.6f,
MinDistance = 0.2f,
};
p.GetCommand(dist: 5f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(MotionCommand.WalkForward, motion);
Assert.False(movingAway);
}
[Fact]
public void TowardsAndAway_InsideMinBand_WalkBackwards_MovingAway()
{
var p = new MovementParameters
{
MoveTowards = true,
MoveAway = true,
DistanceToObject = 0.6f,
MinDistance = 0.2f,
};
// dist - min_distance < epsilon → inside the min band
p.GetCommand(dist: 0.2f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(MotionCommand.WalkBackward, motion);
Assert.True(movingAway);
}
[Fact]
public void TowardsAndAway_InsideDeadband_Idle()
{
var p = new MovementParameters
{
MoveTowards = true,
MoveAway = true,
DistanceToObject = 0.6f,
MinDistance = 0.2f,
};
// strictly inside [min, dto] — neither band fires
p.GetCommand(dist: 0.4f, headingDiff: 0f, out uint motion, out _, out _);
Assert.Equal(0u, motion);
}
// ── neither towards nor away (both clear) — falls to plain-towards path ──
[Fact]
public void NeitherTowardsNorAway_FallsToPlainTowardsBranch()
{
var p = new MovementParameters
{
MoveTowards = false,
MoveAway = false,
DistanceToObject = 0.6f,
};
p.GetCommand(dist: 5f, headingDiff: 0f, out uint motion, out _, out bool movingAway);
Assert.Equal(MotionCommand.WalkForward, motion);
Assert.False(movingAway);
}
// ── walk-vs-run HoldKey cascade ────────────────────────────────────────
[Fact]
public void HoldKey_CanChargeSet_AlwaysRun_FastPath()
{
// THE fast-path ACE dropped: can_charge (0x10) short-circuits
// straight to HoldKey_Run regardless of distance/threshold.
var p = new MovementParameters
{
CanCharge = true,
CanRun = false, // even with can_run CLEAR
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
p.GetCommand(dist: 0.6f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.Run, holdKey);
}
[Fact]
public void HoldKey_CanRunClear_AlwaysWalk_RegardlessOfDistance()
{
var p = new MovementParameters
{
CanCharge = false,
CanRun = false,
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
p.GetCommand(dist: 1000f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.None, holdKey);
}
[Fact]
public void HoldKey_CanRunSet_CanWalkClear_AlwaysRun_WalkIncapable()
{
// can_walk clear → the "close enough to walk" branch is skipped
// entirely; walk-incapable movers always run when can_run is set.
var p = new MovementParameters
{
CanCharge = false,
CanRun = true,
CanWalk = false,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
p.GetCommand(dist: 0.6f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.Run, holdKey);
}
[Fact]
public void HoldKey_CanRunAndCanWalk_WithinThreshold_Walk()
{
var p = new MovementParameters
{
CanCharge = false,
CanRun = true,
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
// dist - dto = 10 <= 15 → walk
p.GetCommand(dist: 10.6f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.None, holdKey);
}
[Fact]
public void HoldKey_CanRunAndCanWalk_BeyondThreshold_Run()
{
var p = new MovementParameters
{
CanCharge = false,
CanRun = true,
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
// dist - dto = 15.1 > 15 → run
p.GetCommand(dist: 15.7f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.Run, holdKey);
}
[Fact]
public void HoldKey_ThresholdEdge_ExactlyAtThreshold_IsInclusive_Walk()
{
// retail: (dist - distance_to_object) <= walk_run_threshhold → WALK.
// The raw's `test ah,0x41` after `fcom` renders as an inclusive
// "not greater than" (≤) — the boundary itself walks, not runs.
var p = new MovementParameters
{
CanCharge = false,
CanRun = true,
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
// dist - dto = exactly 15.0
p.GetCommand(dist: 15.6f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.None, holdKey);
}
[Fact]
public void HoldKey_ThresholdEdge_JustOverThreshold_Run()
{
var p = new MovementParameters
{
CanCharge = false,
CanRun = true,
CanWalk = true,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
// dist - dto = 15.0 + epsilon
p.GetCommand(dist: 15.600001f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.Run, holdKey);
}
[Fact]
public void HoldKey_CanChargeSet_OverridesWalkIncapableAndThreshold()
{
// CanCharge fast-path wins even when every other flag would say walk.
var p = new MovementParameters
{
CanCharge = true,
CanRun = true,
CanWalk = true,
WalkRunThreshhold = 1000f, // would otherwise force walk
DistanceToObject = 0.6f,
};
p.GetCommand(dist: 0.6f, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(HoldKey.Run, holdKey);
}
// ── the four capability quadrants × plain-towards distance bands ──────
[Theory]
// (canRun, canWalk, canCharge, distBeyondThreshold) → expected HoldKey
[InlineData(true, true, false, false, HoldKey.None)] // both capable, close → walk
[InlineData(true, true, false, true, HoldKey.Run)] // both capable, far → run
[InlineData(true, false, false, false, HoldKey.Run)] // run-only, close → still run (no walk branch)
[InlineData(true, false, false, true, HoldKey.Run)] // run-only, far → run
[InlineData(false, true, false, false, HoldKey.None)] // walk-only → always walk
[InlineData(false, true, false, true, HoldKey.None)] // walk-only, far → still walk
[InlineData(false, false, false, false, HoldKey.None)] // neither capable, no charge → walk (falls through)
[InlineData(false, false, true, false, HoldKey.Run)] // can_charge alone → run regardless
public void HoldKey_FourCapabilityQuadrants_MatchRetailCascade(
bool canRun, bool canWalk, bool canCharge, bool distBeyondThreshold, HoldKey expected)
{
var p = new MovementParameters
{
CanRun = canRun,
CanWalk = canWalk,
CanCharge = canCharge,
WalkRunThreshhold = 15f,
DistanceToObject = 0.6f,
};
float dist = distBeyondThreshold ? 20f : 5f; // 20-0.6=19.4>15 ; 5-0.6=4.4<=15
p.GetCommand(dist, headingDiff: 0f, out _, out HoldKey holdKey, out _);
Assert.Equal(expected, holdKey);
}
}

67
tests/AcDream.Core.Tests/Physics/Motion/MovementParametersGetDesiredHeadingTests.cs Normal file
View file

@ -0,0 +1,67 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>MovementParameters::get_desired_heading</c> (<c>0x0052aad0</c>),
/// PINNED by direct Ghidra decompile of <c>patchmem.gpr</c> (see
/// docs/research/2026-07-03-r4-moveto/ghidra-confirmations.md §P2 — fetched
/// live during V0, ACE-shaped constants CONFIRMED exact):
/// <code>
/// forward|run + towards → 0 forward|run + away → 180
/// backward + towards → 180 backward + away → 0
/// any other command → 0
/// </code>
/// </summary>
public sealed class MovementParametersGetDesiredHeadingTests
{
[Theory]
[InlineData(false, 0f)] // RunForward, towards → 0
[InlineData(true, 180f)] // RunForward, away → 180
public void RunForward_FourQuadrant(bool movingAway, float expected)
{
var p = new MovementParameters();
float h = p.GetDesiredHeading(MotionCommand.RunForward, movingAway);
Assert.Equal(expected, h);
}
[Theory]
[InlineData(false, 0f)] // WalkForward, towards → 0
[InlineData(true, 180f)] // WalkForward, away → 180
public void WalkForward_FourQuadrant(bool movingAway, float expected)
{
var p = new MovementParameters();
float h = p.GetDesiredHeading(MotionCommand.WalkForward, movingAway);
Assert.Equal(expected, h);
}
[Theory]
[InlineData(false, 180f)] // WalkBackward, towards → 180 (face the target while backing up)
[InlineData(true, 0f)] // WalkBackward, away → 0
public void WalkBackward_FourQuadrant(bool movingAway, float expected)
{
var p = new MovementParameters();
float h = p.GetDesiredHeading(MotionCommand.WalkBackward, movingAway);
Assert.Equal(expected, h);
}
[Theory]
[InlineData(false)]
[InlineData(true)]
public void UnknownCommand_DefaultsToZero(bool movingAway)
{
var p = new MovementParameters();
float h = p.GetDesiredHeading(MotionCommand.TurnRight, movingAway);
Assert.Equal(0f, h);
}
[Fact]
public void ZeroCommand_DefaultsToZero()
{
var p = new MovementParameters();
Assert.Equal(0f, p.GetDesiredHeading(0u, movingAway: false));
Assert.Equal(0f, p.GetDesiredHeading(0u, movingAway: true));
}
}

112
tests/AcDream.Core.Tests/Physics/Motion/MovementParametersTests.cs Normal file
View file

@ -0,0 +1,112 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R3-W1 — <c>MovementParameters</c> ctor-default pins. Oracle:
/// docs/research/2026-07-02-r3-motioninterp/W0-pins.md §A4 (bitfield 0x1EE0F
/// expansion) + r3-motioninterp-decomp.md §0 (scalar ctor, raw 300510-300534,
/// 0x00524380). Every flag asserted individually against the retail
/// 0x1EE0F default so a future bit-numbering slip fails loudly, plus the two
/// ACE-divergence traps (CanCharge, WalkRunThreshhold) get dedicated tests.
/// </summary>
public sealed class MovementParametersTests
{
[Fact]
public void Ctor_SetFlags_MatchRetail0x1EE0FExpansion()
{
var p = new MovementParameters();
// Bits SET in 0x1EE0F: 0x1,0x2,0x4,0x8,0x200,0x400,0x800,0x2000,0x4000,0x8000,0x10000
Assert.True(p.CanWalk); // 0x1
Assert.True(p.CanRun); // 0x2
Assert.True(p.CanSidestep); // 0x4
Assert.True(p.CanWalkBackwards); // 0x8
Assert.True(p.MoveTowards); // 0x200
Assert.True(p.UseSpheres); // 0x400
Assert.True(p.SetHoldKey); // 0x800
Assert.True(p.ModifyRawState); // 0x2000
Assert.True(p.ModifyInterpretedState); // 0x4000
Assert.True(p.CancelMoveTo); // 0x8000
Assert.True(p.StopCompletelyFlag); // 0x10000
}
[Fact]
public void Ctor_ClearFlags_MatchRetail0x1EE0FExpansion()
{
var p = new MovementParameters();
// Bits CLEAR in 0x1EE0F: 0x10,0x20,0x40,0x80,0x100,0x1000,0x20000
Assert.False(p.CanCharge); // 0x10 — ACE-divergence trap
Assert.False(p.FailWalk); // 0x20
Assert.False(p.UseFinalHeading); // 0x40
Assert.False(p.Sticky); // 0x80
Assert.False(p.MoveAway); // 0x100
Assert.False(p.Autonomous); // 0x1000
Assert.False(p.DisableJumpDuringLink); // 0x20000
}
[Fact]
public void Ctor_Bitfield_ReconstitutesExactly0x1EE0F()
{
var p = new MovementParameters();
uint bitfield = 0;
if (p.CanWalk) bitfield |= 0x1;
if (p.CanRun) bitfield |= 0x2;
if (p.CanSidestep) bitfield |= 0x4;
if (p.CanWalkBackwards) bitfield |= 0x8;
if (p.CanCharge) bitfield |= 0x10;
if (p.FailWalk) bitfield |= 0x20;
if (p.UseFinalHeading) bitfield |= 0x40;
if (p.Sticky) bitfield |= 0x80;
if (p.MoveAway) bitfield |= 0x100;
if (p.MoveTowards) bitfield |= 0x200;
if (p.UseSpheres) bitfield |= 0x400;
if (p.SetHoldKey) bitfield |= 0x800;
if (p.Autonomous) bitfield |= 0x1000;
if (p.ModifyRawState) bitfield |= 0x2000;
if (p.ModifyInterpretedState) bitfield |= 0x4000;
if (p.CancelMoveTo) bitfield |= 0x8000;
if (p.StopCompletelyFlag) bitfield |= 0x10000;
if (p.DisableJumpDuringLink) bitfield |= 0x20000;
Assert.Equal(0x1EE0Fu, bitfield);
}
[Fact]
public void Ctor_ScalarDefaults_MatchRetail()
{
var p = new MovementParameters();
Assert.Equal(0f, p.MinDistance);
Assert.Equal(0.6f, p.DistanceToObject);
Assert.Equal(float.MaxValue, p.FailDistance);
Assert.Equal(0f, p.DesiredHeading);
Assert.Equal(1f, p.Speed);
// ACE-divergence trap: retail is 15.0, NOT ACE's 1.0.
Assert.Equal(15f, p.WalkRunThreshhold);
Assert.Equal(0u, p.ContextId);
Assert.Equal(HoldKey.Invalid, p.HoldKeyToApply);
Assert.Equal(0u, p.ActionStamp);
}
[Fact]
public void Ctor_CanCharge_DefaultsFalse_NotAceTrue()
{
// Dedicated regression test for the single highest-risk ACE trap:
// ACE's MovementParameters.cs:58 sets CanCharge = true at construction.
// Retail's 0x1EE0F has bit 0x10 CLEAR.
var p = new MovementParameters();
Assert.False(p.CanCharge);
}
[Fact]
public void Ctor_WalkRunThreshhold_Is15_NotAce1()
{
var p = new MovementParameters();
Assert.Equal(15f, p.WalkRunThreshhold);
}
}

84
tests/AcDream.Core.Tests/Physics/Motion/MovementParametersTowardsAndAwayTests.cs Normal file
View file

@ -0,0 +1,84 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <c>MovementParameters::towards_and_away</c> (<c>0x0052a9a0</c>,
/// raw 307917-307942), verbatim per r4-moveto-decomp.md §5d. Three bands:
/// beyond <c>distance_to_object</c> → WalkForward towards; inside the
/// <c>min_distance</c> epsilon band → WalkBackwards away (no turn, unlike
/// the pure-away branch in §5c which uses WalkForward+turn-around); strictly
/// between → idle (cmd 0).
/// </summary>
public sealed class MovementParametersTowardsAndAwayTests
{
[Fact]
public void DistGreaterThanDto_WalkForward_Towards()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
p.TowardsAndAway(dist: 5f, out uint cmd, out bool movingAway);
Assert.Equal(MotionCommand.WalkForward, cmd);
Assert.False(movingAway);
}
[Fact]
public void DistExactlyAtDto_NotGreater_FallsToMinBandCheck()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
// dist == dto is NOT > dto, so falls through to the min-band test;
// 0.6 - 0.2 = 0.4, not < epsilon → idle.
p.TowardsAndAway(dist: 0.6f, out uint cmd, out _);
Assert.Equal(0u, cmd);
}
[Fact]
public void InsideMinDistanceEpsilonBand_WalkBackwards_Away()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
// dist - min_distance < 0.000199999995f
p.TowardsAndAway(dist: 0.2f, out uint cmd, out bool movingAway);
Assert.Equal(MotionCommand.WalkBackward, cmd);
Assert.True(movingAway);
}
[Fact]
public void InsideMinDistanceEpsilonBand_JustBelowEpsilon_StillWalkBackwards()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
p.TowardsAndAway(dist: 0.2f + 0.0001f, out uint cmd, out bool movingAway);
Assert.Equal(MotionCommand.WalkBackward, cmd);
Assert.True(movingAway);
}
[Fact]
public void StrictlyBetweenMinAndDto_Idle()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
p.TowardsAndAway(dist: 0.4f, out uint cmd, out bool movingAway);
Assert.Equal(0u, cmd);
Assert.False(movingAway);
}
[Fact]
public void JustOutsideMinBand_NotYetIdle_Idle()
{
var p = new MovementParameters { DistanceToObject = 0.6f, MinDistance = 0.2f };
// dist - min = 0.0003, just over epsilon (0.0002) → NOT in the min band → idle
p.TowardsAndAway(dist: 0.2003f, out uint cmd, out _);
Assert.Equal(0u, cmd);
}
}

108
tests/AcDream.Core.Tests/Physics/Motion/MovementStructWideningTests.cs Normal file
View file

@ -0,0 +1,108 @@
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <see cref="MovementStruct"/> widening per r4-moveto-decomp.md §0
/// (acclient.h:38069, struct #4067):
/// <code>
/// struct __cppobj MovementStruct
/// {
/// MovementTypes::Type type;
/// unsigned int motion; // types 1-4 only
/// unsigned int object_id; // types 6, 8
/// unsigned int top_level_id; // types 6, 8
/// Position pos; // type 7
/// float radius; // type 6
/// float height; // type 6
/// MovementParameters *params; // types 1-4, 6-9
/// };
/// </code>
/// Additive-only (M11, mechanical) — no consumer wires these fields yet;
/// this test just pins the shape exists and round-trips.
/// </summary>
public sealed class MovementStructWideningTests
{
[Fact]
public void ObjectId_TopLevelId_RoundTrip()
{
var mvs = new MovementStruct
{
Type = MovementType.MoveToObject,
ObjectId = 0x50001234u,
TopLevelId = 0x50005678u,
};
Assert.Equal(0x50001234u, mvs.ObjectId);
Assert.Equal(0x50005678u, mvs.TopLevelId);
}
[Fact]
public void Pos_RoundTrips_WorldPositionAndCell()
{
var pos = new Position(0x12340001u, new Vector3(10f, 20f, 3f), Quaternion.Identity);
var mvs = new MovementStruct
{
Type = MovementType.MoveToPosition,
Pos = pos,
};
Assert.Equal(pos, mvs.Pos);
Assert.Equal(0x12340001u, mvs.Pos.ObjCellId);
Assert.Equal(new Vector3(10f, 20f, 3f), mvs.Pos.Frame.Origin);
}
[Fact]
public void Radius_Height_RoundTrip()
{
var mvs = new MovementStruct
{
Type = MovementType.MoveToObject,
Radius = 0.75f,
Height = 1.8f,
};
Assert.Equal(0.75f, mvs.Radius);
Assert.Equal(1.8f, mvs.Height);
}
[Fact]
public void Params_HoldsMovementParametersReference()
{
var p = new MovementParameters { CanCharge = true };
var mvs = new MovementStruct
{
Type = MovementType.TurnToHeading,
Params = p,
};
Assert.Same(p, mvs.Params);
}
[Fact]
public void ExistingFields_Type_Motion_StillPresent_NoRegression()
{
// The pre-R4 fields (Type/Motion/Speed/Autonomous/ModifyInterpretedState/
// ModifyRawState) must survive the widening untouched — R4 is
// additive-only per the plan (M11, "no consumer changes").
var mvs = new MovementStruct
{
Type = MovementType.RawCommand,
Motion = 0x45000005u,
Speed = 1.5f,
Autonomous = true,
ModifyInterpretedState = true,
ModifyRawState = false,
};
Assert.Equal(MovementType.RawCommand, mvs.Type);
Assert.Equal(0x45000005u, mvs.Motion);
Assert.Equal(1.5f, mvs.Speed);
Assert.True(mvs.Autonomous);
Assert.True(mvs.ModifyInterpretedState);
Assert.False(mvs.ModifyRawState);
}
}

33
tests/AcDream.Core.Tests/Physics/Motion/MovementTypeWideningTests.cs Normal file
View file

@ -0,0 +1,33 @@
using AcDream.Core.Physics;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R4-V1 — <see cref="MovementType"/> widening to retail's full
/// <c>MovementTypes::Type</c> enum (acclient.h:2856, enum #229):
/// <code>
/// Invalid=0, RawCommand=1, InterpretedCommand=2, StopRawCommand=3,
/// StopInterpretedCommand=4, StopCompletely=5, MoveToObject=6,
/// MoveToPosition=7, TurnToObject=8, TurnToHeading=9
/// </code>
/// Mechanical, additive-only pin (M11) — the 1-5 values must not shift
/// (they're already load-bearing in <c>MotionInterpreter.PerformMovement</c>'s
/// switch).
/// </summary>
public sealed class MovementTypeWideningTests
{
[Theory]
[InlineData(MovementType.Invalid, 0)]
[InlineData(MovementType.RawCommand, 1)]
[InlineData(MovementType.InterpretedCommand, 2)]
[InlineData(MovementType.StopRawCommand, 3)]
[InlineData(MovementType.StopInterpretedCommand, 4)]
[InlineData(MovementType.StopCompletely, 5)]
[InlineData(MovementType.MoveToObject, 6)]
[InlineData(MovementType.MoveToPosition, 7)]
[InlineData(MovementType.TurnToObject, 8)]
[InlineData(MovementType.TurnToHeading, 9)]
public void EnumValues_MatchRetailMovementTypesTypeTable(MovementType value, int expected)
=> Assert.Equal(expected, (int)value);
}

114
tests/AcDream.Core.Tests/Physics/Motion/PositionManagerFacadeTests.cs Normal file
View file

@ -0,0 +1,114 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5 conformance — <see cref="PositionManager"/> facade (retail
/// 0x00555160-0x005553d0). Lazy sub-manager creation + fan-out. (Test class is
/// suffixed "Facade" to read distinctly from the renamed
/// <c>RemoteMotionCombiner</c> combiner tests.)
/// </summary>
public sealed class PositionManagerFacadeTests
{
private static (R5Host self, R5Host target, PositionManager pm) Setup()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world);
var target = new R5Host(20u, world);
return (self, target, new PositionManager(self));
}
[Fact]
public void UnStick_BeforeAnyStick_IsNoOp()
{
var (_, _, pm) = Setup();
pm.UnStick(); // no sticky manager yet — must not throw
Assert.Null(pm.Sticky);
Assert.Equal(0u, pm.GetStickyObjectId());
}
[Fact]
public void StickTo_LazilyCreatesSticky_AndForwards()
{
var (self, target, pm) = Setup();
pm.StickTo(target.Id, radius: 0.5f, height: 1.0f);
Assert.NotNull(pm.Sticky);
Assert.Equal(target.Id, pm.GetStickyObjectId());
}
[Fact]
public void IsFullyConstrained_FalseWhenNoConstraintManager()
{
var (_, _, pm) = Setup();
Assert.False(pm.IsFullyConstrained());
Assert.Null(pm.Constraint);
}
[Fact]
public void ConstrainTo_LazilyCreatesConstraint()
{
var (self, _, pm) = Setup();
self.SetOrigin(Vector3.Zero);
pm.ConstrainTo(new Position(1u, new Vector3(5f, 0f, 0f), Quaternion.Identity), 2f, 10f);
Assert.NotNull(pm.Constraint);
Assert.True(pm.Constraint!.IsConstrained);
}
[Fact]
public void HandleUpdateTarget_ForwardsToSticky()
{
var (self, target, pm) = Setup();
pm.StickTo(target.Id, 0.5f, 1.0f);
var tp = new Position(1u, new Vector3(2f, 0f, 0f), Quaternion.Identity);
pm.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
Assert.True(pm.Sticky!.Initialized);
}
[Fact]
public void AdjustOffset_ChainsStickyThenConstraint()
{
var (self, target, pm) = Setup();
self.Radius = 0.5f;
self.MinterpMaxSpeed = 1.0f;
self.InContact = true;
// Sticky toward +X: produces an offset the constraint then tapers.
pm.StickTo(target.Id, 0.5f, 1.0f);
target.SetOrigin(new Vector3(5f, 0f, 0f));
var tp = new Position(1u, new Vector3(5f, 0f, 0f), Quaternion.Identity);
pm.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
// Arm a constraint whose band tapers by 0.5.
self.SetOrigin(Vector3.Zero);
pm.ConstrainTo(new Position(1u, new Vector3(6f, 0f, 0f), Quaternion.Identity),
startDistance: 2f, maxDistance: 10f); // offset 6 → taper (10-6)/(10-2)=0.5
var frame = new MotionDeltaFrame();
pm.AdjustOffset(frame, quantum: 0.1);
// Sticky writes +0.5 X; constraint tapers by 0.5 → 0.25.
Assert.Equal(0.25f, frame.Origin.X, 3);
}
[Fact]
public void UseTime_DrivesStickyTimeout()
{
var (self, target, pm) = Setup();
self.CurTime = 100.0;
pm.StickTo(target.Id, 0.5f, 1.0f); // deadline 101
// Strictly past the deadline (retail 0x00555626 keeps the stick AT
// the deadline; teardown is `>` — ACE too).
self.CurTime = 101.001;
pm.UseTime();
Assert.Equal(0u, pm.GetStickyObjectId()); // unstuck
}
}

98
tests/AcDream.Core.Tests/Physics/Motion/R5ManagerHarness.cs Normal file
View file

@ -0,0 +1,98 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5 conformance harness — a scriptable <see cref="IPhysicsObjHost"/> fake
/// backed by a shared <see cref="World"/> so <see cref="GetObjectA"/> resolves
/// OTHER hosts (the cross-entity seam the voyeur round-trip needs). Each host
/// lazily owns a <see cref="TargetManager"/> and a <see cref="PositionManager"/>
/// (the two R5 managers under test), and records every
/// <see cref="HandleUpdateTarget"/> the managers fan out so tests can assert on
/// delivery.
///
/// <para>Position/velocity/radius/contact/max-speed and both clocks are mutable
/// fields tests drive directly (retail's <c>CPhysicsObj</c> accessors). The
/// <c>set_target</c>/<c>clear_target</c>/<c>add_voyeur</c>/<c>remove_voyeur</c>/
/// <c>receive_target_update</c> seams forward to the owned
/// <see cref="TargetManager"/> exactly as retail's <c>CPhysicsObj</c> does.</para>
/// </summary>
internal sealed class R5Host : IPhysicsObjHost
{
public readonly Dictionary<uint, R5Host> World;
public R5Host(uint id, Dictionary<uint, R5Host> world)
{
Id = id;
World = world;
World[id] = this;
}
// ── scriptable CPhysicsObj state ───────────────────────────────────────
public uint Id { get; }
public Position Position { get; set; } = new(1u, Vector3.Zero, Quaternion.Identity);
public Vector3 Velocity { get; set; } = Vector3.Zero;
public float Radius { get; set; } = 0.5f;
public bool InContact { get; set; } = true;
public float? MinterpMaxSpeed { get; set; } = 1.0f;
public double CurTime { get; set; }
public double PhysicsTimerTime { get; set; }
/// <summary>Set to false to simulate a target that isn't currently
/// resolvable (out of streaming view) — <see cref="GetObjectA"/> returns
/// null for it even while it's in <see cref="World"/>.</summary>
public bool Resolvable { get; set; } = true;
// ── owned R5 managers ──────────────────────────────────────────────────
private TargetManager? _targetManager;
public TargetManager TargetManager => _targetManager ??= new TargetManager(this);
public TargetManager? TargetManagerOrNull => _targetManager;
private PositionManager? _positionManager;
public PositionManager PositionManager => _positionManager ??= new PositionManager(this);
// ── recorded fan-outs ──────────────────────────────────────────────────
public readonly List<TargetInfo> HandleUpdateTargetCalls = new();
public int InterruptCurrentMovementCalls;
// ── IPhysicsObjHost ────────────────────────────────────────────────────
public IPhysicsObjHost? GetObjectA(uint id)
=> World.TryGetValue(id, out var h) && h.Resolvable ? h : null;
public void HandleUpdateTarget(TargetInfo info)
{
HandleUpdateTargetCalls.Add(info);
// Retail CPhysicsObj::HandleUpdateTarget also fans to the position
// manager's sticky sub-manager (context 0). Mirror that so sticky tests
// that rely on the full CPhysicsObj fan-out see the callback.
if (info.ContextId == 0)
_positionManager?.HandleUpdateTarget(info);
}
public void InterruptCurrentMovement() => InterruptCurrentMovementCalls++;
public void SetTarget(uint contextId, uint objectId, float radius, double quantum)
=> TargetManager.SetTarget(contextId, objectId, radius, quantum);
public void ClearTarget() => _targetManager?.ClearTarget();
public void ReceiveTargetUpdate(TargetInfo info) => _targetManager?.ReceiveUpdate(info);
public void AddVoyeur(uint watcherId, float radius, double quantum)
=> TargetManager.AddVoyeur(watcherId, radius, quantum);
public void RemoveVoyeur(uint watcherId) => _targetManager?.RemoveVoyeur(watcherId);
// ── test helpers ───────────────────────────────────────────────────────
public void SetOrigin(Vector3 origin)
=> Position = new Position(Position.ObjCellId, origin, Position.Frame.Orientation);
public void AdvanceClocks(double seconds)
{
CurTime += seconds;
PhysicsTimerTime += seconds;
}
}

244
tests/AcDream.Core.Tests/Physics/Motion/RawMotionStateActionFifoTests.cs Normal file
View file

@ -0,0 +1,244 @@
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R3-W1 — action FIFO discipline + <c>ApplyMotion</c>/<c>RemoveMotion</c>
/// field effects on <see cref="RawMotionState"/> (closes J2). Oracle:
/// docs/research/named-retail/acclient_2013_pseudo_c.txt — verbatim bodies
/// quoted in RawMotionState.cs doc comments:
/// <c>RawMotionState::AddAction</c> (0x0051e840), <c>RemoveAction</c>
/// (0x0051e8a0), <c>ApplyMotion</c> (0x0051eb60), <c>RemoveMotion</c>
/// (0x0051e6e0).
/// </summary>
public sealed class RawMotionStateActionFifoTests
{
// ── AddAction / RemoveAction / GetNumActions FIFO discipline ──────────
[Fact]
public void AddAction_AppendsInOrder()
{
var raw = new RawMotionState();
raw.AddAction(0x1000004Bu, 1.0f, 1, autonomous: false);
raw.AddAction(0x10000050u, 1.5f, 2, autonomous: true);
Assert.Equal(2, raw.Actions.Count);
Assert.Equal((ushort)0x004Bu, raw.Actions[0].Command); // widened to ushort on wire, verified below
Assert.Equal((ushort)0x0050u, raw.Actions[1].Command);
}
[Fact]
public void RemoveAction_PopsHeadFirst_FifoOrder()
{
var raw = new RawMotionState();
raw.AddAction(0x1000004Bu, 1.0f, 1, autonomous: false);
raw.AddAction(0x10000050u, 1.5f, 2, autonomous: true);
uint first = raw.RemoveAction();
uint second = raw.RemoveAction();
Assert.Equal(0x004Bu, first); // head popped first (FIFO)
Assert.Equal(0x0050u, second);
Assert.Empty(raw.Actions);
}
[Fact]
public void RemoveAction_Empty_ReturnsZero()
{
var raw = new RawMotionState();
Assert.Equal(0u, raw.RemoveAction());
}
[Fact]
public void AddAction_StoresSpeedStampAutonomous()
{
var raw = new RawMotionState();
raw.AddAction(0x1000004Bu, speed: 2.5f, actionStamp: 0x7FFFu, autonomous: true);
var a = raw.Actions[0];
Assert.Equal(2.5f, a.Speed);
Assert.Equal((ushort)0x7FFFu, a.Stamp);
Assert.True(a.Autonomous);
}
// ── ApplyMotion field effects (0x0051eb60) ─────────────────────────────
[Fact]
public void ApplyMotion_TurnRight_SetsTurnCommandAndSpeed_HonorsSetHoldKeyBit()
{
var raw = new RawMotionState();
var p = new MovementParameters { Speed = 1.5f, SetHoldKey = true };
raw.ApplyMotion(0x6500000du, p); // TurnRight
Assert.Equal(0x6500000du, raw.TurnCommand);
Assert.Equal(1.5f, raw.TurnSpeed);
Assert.Equal(HoldKey.Invalid, raw.TurnHoldKey); // SetHoldKey bit set -> Invalid
}
[Fact]
public void ApplyMotion_TurnRight_SetHoldKeyClear_UsesHoldKeyToApply()
{
var raw = new RawMotionState();
var p = new MovementParameters { Speed = 1.5f, SetHoldKey = false, HoldKeyToApply = HoldKey.Run };
raw.ApplyMotion(0x6500000du, p);
Assert.Equal(HoldKey.Run, raw.TurnHoldKey);
}
[Fact]
public void ApplyMotion_SideStepRight_SetsSidestepCommandAndSpeed()
{
var raw = new RawMotionState();
var p = new MovementParameters { Speed = 1.248f, SetHoldKey = true };
raw.ApplyMotion(0x6500000fu, p); // SideStepRight
Assert.Equal(0x6500000fu, raw.SidestepCommand);
Assert.Equal(1.248f, raw.SidestepSpeed);
Assert.Equal(HoldKey.Invalid, raw.SidestepHoldKey);
}
[Fact]
public void ApplyMotion_ForwardClassMotion_SetsForwardCommandAndSpeed()
{
// WalkForward = 0x45000005 has bit 0x40000000 set (forward-class)
// and is NOT 0x44000007 (RunForward) -> the write branch fires.
var raw = new RawMotionState();
var p = new MovementParameters { Speed = 1.0f, SetHoldKey = true };
raw.ApplyMotion(0x45000005u, p);
Assert.Equal(0x45000005u, raw.ForwardCommand);
Assert.Equal(1.0f, raw.ForwardSpeed);
Assert.Equal(HoldKey.Invalid, raw.ForwardHoldKey);
}
[Fact]
public void ApplyMotion_RunForwardExactId_ForwardClassButExcluded_NoWrite()
{
// Verbatim retail quirk (0x0051eb60): arg2 == 0x44000007 (RunForward)
// with the forward-class bit (0x40000000) set falls through BOTH
// inner branches — no field write occurs. Port verbatim, not fixed.
var raw = new RawMotionState();
var before = raw.ForwardCommand;
var p = new MovementParameters { Speed = 3.0f };
raw.ApplyMotion(0x44000007u, p);
Assert.Equal(before, raw.ForwardCommand); // untouched
Assert.Equal(1.0f, raw.ForwardSpeed); // untouched (still ctor default)
}
[Fact]
public void ApplyMotion_StyleClassMotion_SetsCurrentStyleAndResetsForwardToReady()
{
// High bit set (>= 0x80000000) and current_style differs -> style branch.
var raw = new RawMotionState { ForwardCommand = 0x45000005u };
var p = new MovementParameters();
raw.ApplyMotion(0x80000042u, p);
Assert.Equal(0x41000003u, raw.ForwardCommand); // reset to Ready
Assert.Equal(0x80000042u, raw.CurrentStyle);
}
[Fact]
public void ApplyMotion_StyleClassMotion_SameAsCurrentStyle_NoOp()
{
var raw = new RawMotionState { CurrentStyle = 0x80000042u, ForwardCommand = 0x45000005u };
var p = new MovementParameters();
raw.ApplyMotion(0x80000042u, p);
// current_style already equals arg2 -> the style branch's condition
// (current_style != arg2) is false, so forward_command is untouched.
Assert.Equal(0x45000005u, raw.ForwardCommand);
Assert.Equal(0x80000042u, raw.CurrentStyle);
}
[Fact]
public void ApplyMotion_ActionClassMotion_AddsAction()
{
// Outside turn/sidestep range, bit 0x40000000 clear, arg2 >= 0
// (not style-class), bit 0x10000000 set -> AddAction.
var raw = new RawMotionState();
var p = new MovementParameters { Speed = 1.0f, ActionStamp = 42u, Autonomous = true };
raw.ApplyMotion(0x1000004Bu, p); // Jumpup action id
Assert.Single(raw.Actions);
var a = raw.Actions[0];
Assert.Equal((ushort)0x004Bu, a.Command);
Assert.Equal(1.0f, a.Speed);
Assert.Equal((ushort)42u, a.Stamp);
Assert.True(a.Autonomous);
}
// ── RemoveMotion field effects (0x0051e6e0) ────────────────────────────
[Fact]
public void RemoveMotion_TurnRange_ClearsTurnCommand()
{
var raw = new RawMotionState { TurnCommand = 0x6500000du };
raw.RemoveMotion(0x6500000du);
Assert.Equal(0u, raw.TurnCommand);
}
[Fact]
public void RemoveMotion_TurnLeftRange_ClearsTurnCommand()
{
var raw = new RawMotionState { TurnCommand = 0x6500000eu };
raw.RemoveMotion(0x6500000eu);
Assert.Equal(0u, raw.TurnCommand);
}
[Fact]
public void RemoveMotion_SidestepRange_ClearsSidestepCommand()
{
var raw = new RawMotionState { SidestepCommand = 0x6500000fu };
raw.RemoveMotion(0x6500000fu);
Assert.Equal(0u, raw.SidestepCommand);
}
[Fact]
public void RemoveMotion_ForwardClassMotion_MatchingCommand_ResetsToReady()
{
var raw = new RawMotionState { ForwardCommand = 0x45000005u, ForwardSpeed = 3.0f };
raw.RemoveMotion(0x45000005u);
Assert.Equal(0x41000003u, raw.ForwardCommand);
Assert.Equal(1f, raw.ForwardSpeed);
}
[Fact]
public void RemoveMotion_ForwardClassMotion_NonMatchingCommand_NoOp()
{
var raw = new RawMotionState { ForwardCommand = 0x45000005u, ForwardSpeed = 3.0f };
raw.RemoveMotion(0x44000007u); // different forward-class id
Assert.Equal(0x45000005u, raw.ForwardCommand); // untouched
Assert.Equal(3.0f, raw.ForwardSpeed);
}
[Fact]
public void RemoveMotion_StyleClassMotion_MatchingCurrentStyle_ResetsToNonCombat()
{
var raw = new RawMotionState { CurrentStyle = 0x80000042u };
raw.RemoveMotion(0x80000042u);
Assert.Equal(0x8000003du, raw.CurrentStyle); // reset to NonCombat
}
[Fact]
public void RemoveMotion_StyleClassMotion_NonMatchingCurrentStyle_NoOp()
{
var raw = new RawMotionState { CurrentStyle = 0x80000042u };
raw.RemoveMotion(0x80000099u); // different style id
Assert.Equal(0x80000042u, raw.CurrentStyle); // untouched
}
}

105
tests/AcDream.Core.Tests/Physics/Motion/RemoteChaseDrainBisectTests.cs Normal file
View file

@ -0,0 +1,105 @@
using System;
using System.Linq;
using System.Text;
using AcDream.Core.Physics;
using Xunit;
using Xunit.Abstractions;
namespace AcDream.Core.Tests.Physics.Motion;
// ─────────────────────────────────────────────────────────────────────────────
// #170 drain-chain conformance: a stance-change UM's completion must flow
// CSequence link-anim completion → AnimDone hook → ConsumePendingHooks →
// MotionTableManager.AnimationDone countdown → MotionDoneTarget →
// CMotionInterp.MotionDone pop, fully emptying BOTH queues (retail cdb
// invariant: add_to_queue == MotionDone).
//
// History: the first harness run wedged here EXACTLY like the live #170
// signature ([drainq] q=[0x8000003C ...] stuck) — because the harness body
// was unseeded (InWorld=false), so the TS-40 detached-object guard stripped
// every dispatched transition link while the manager kept counting its ticks.
// With the live-faithful RemoteMotion construction the chain drains in ~1 s.
// Kept as the regression pin for that whole chain (and as the canonical
// demonstration of what a link-strip-without-tick-zeroing wedge looks like).
// ─────────────────────────────────────────────────────────────────────────────
public sealed class RemoteChaseDrainBisectTests
{
private readonly ITestOutputHelper _out;
public RemoteChaseDrainBisectTests(ITestOutputHelper output) => _out = output;
[Fact]
public void StanceChange_DrainChain_TickByTick()
{
var h = new RemoteChaseHarness();
// settle spawn
for (int i = 0; i < 30; i++) h.Tick();
DumpState(h, "pre-stance");
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
DumpState(h, "post-UM (t=0)");
for (int i = 1; i <= 90; i++)
{
TickWithHookTrace(h, i);
if (i % 6 == 0 || i <= 3)
DumpState(h, $"tick {i} (t={i / 60f:F2})");
if (!h.Interp.MotionsPending() && h.Seq.Manager.PendingAnimations.Any() == false)
{
DumpState(h, $"DRAINED at tick {i}");
return; // chain healthy
}
}
DumpState(h, "END — still wedged");
Assert.Fail("drain chain wedged after stance UM — see output for where");
}
private void TickWithHookTrace(RemoteChaseHarness h, int i)
{
// Replicate RemoteChaseHarness.Tick but with hook visibility: we call
// the same phases, intercepting the hook list.
h.Now += RemoteChaseHarness.Dt;
h.Mgr.UseTime();
if (h.Body.OnWalkable)
h.Body.set_local_velocity(h.Interp.get_state_velocity(), false);
h.Seq.Advance(RemoteChaseHarness.Dt);
var hooks = h.Seq.ConsumePendingHooks();
if (hooks.Count > 0)
{
var sb = new StringBuilder();
sb.Append(FormattableString.Invariant($"tick {i}: hooks=["));
for (int k = 0; k < hooks.Count; k++)
{
if (k > 0) sb.Append(", ");
sb.Append(hooks[k]?.GetType().Name ?? "null");
}
sb.Append(']');
_out.WriteLine(sb.ToString());
}
for (int k = 0; k < hooks.Count; k++)
{
if (hooks[k] is DatReaderWriter.Types.AnimationDoneHook)
h.Seq.Manager.AnimationDone(success: true);
}
h.Seq.Manager.UseTime();
}
private void DumpState(RemoteChaseHarness h, string tag)
{
var mgrQ = string.Join(" ", h.Seq.Manager.PendingAnimations
.Select(p => FormattableString.Invariant($"(0x{p.Motion:X8},t={p.NumAnims})")));
var core = h.Seq.Core;
var seqList = new StringBuilder();
for (var n = core.AnimList.First; n is not null; n = n.Next)
{
if (seqList.Length > 0) seqList.Append(',');
seqList.Append(FormattableString.Invariant($"fr={n.Value.Framerate:F0}"));
if (ReferenceEquals(n, core.FirstCyclicNode)) seqList.Append('*');
if (ReferenceEquals(n, core.CurrAnimNode)) seqList.Append('^');
}
_out.WriteLine(FormattableString.Invariant(
$"[{tag}] interpPending={h.Interp.MotionsPending()} mgrQ=[{mgrQ}] counter={h.Seq.Manager.AnimationCounter} seq=[{seqList}] frame={core.FrameNumber:F1} substate=0x{h.Seq.Manager.State.Substate:X8} style=0x{h.Seq.Manager.State.Style:X8}"));
}
}

960
tests/AcDream.Core.Tests/Physics/Motion/RemoteChaseEndToEndHarnessTests.cs Normal file
View file

@ -0,0 +1,960 @@
using System;
using System.Collections.Generic;
using System.Numerics;
using System.Text;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Types;
using Xunit;
using Xunit.Abstractions;
using DRWMotionCommand = DatReaderWriter.Enums.MotionCommand;
using CorePosition = AcDream.Core.Physics.Position;
namespace AcDream.Core.Tests.Physics.Motion;
// ─────────────────────────────────────────────────────────────────────────────
// #170 "sustain the run" — full-stack remote-chase harness.
//
// The R4-V2 MoveToManagerHarness scripts Heading directly (setHeading writes
// the scalar) and drains pending_motions synthetically, so the two legs where
// the live #170 residual actually lives have ZERO coverage:
//
// 1. the PHYSICAL turn: _DoMotion(TurnRight) → MotionTableDispatchSink.
// TurnApplied → ObservedOmega → per-tick quaternion integration →
// MoveToMath.GetHeading → HandleTurnToHeading's HeadingGreater test;
// 2. the REAL drain: MotionTableManager pending_animations countdown fed by
// CSequence AnimDone hooks (link-anim completions), popping
// CMotionInterp.pending_motions via the MotionDoneTarget seam.
//
// This harness wires a real MotionInterpreter + AnimationSequencer +
// MotionTableDispatchSink + MoveToManager EXACTLY like GameWindow's
// EnsureRemoteMotionBindings (GameWindow.cs:4251) and ticks them in
// GameWindow.TickAnimations' per-entity order for the grounded branch=MOVETO
// path (GameWindow.cs:9697 HandleTargetting → 9994 TickRemoteMoveTo →
// 10024 get_state_velocity refresh → 10050 manual omega integration →
// 10247 Sequencer.Advance → 10306 AnimationDone per AnimDoneHook →
// 10309 Manager.UseTime). Wire events (aggro stance UM, mt-6 arms, attack
// UMs) replay the exact live sequence captured in launch-drainq.log
// (2026-07-04, guid 0x80000BE5, Mite Scamp chasing the fleeing player).
//
// Retail acceptance bar (live cdb, 2026-07-04 session): BeginMoveForward ≈
// MoveToObject arms (21/22), pending_motions add == MotionDone exactly, the
// chase turn completes within a couple of seconds and the run SUSTAINS
// between attack swings.
// ─────────────────────────────────────────────────────────────────────────────
internal sealed class ChaseLoader : IAnimationLoader
{
private readonly Dictionary<uint, Animation> _anims = new();
public void Register(uint id, Animation anim) => _anims[id] = anim;
public Animation? LoadAnimation(uint id) =>
_anims.TryGetValue(id, out var a) ? a : null;
}
/// <summary>
/// The full-stack per-entity pipeline replica. Field-for-field mirror of the
/// GameWindow wiring for one grounded remote NPC (branch=MOVETO), plus a
/// scripted stand-in for the TargetManager voyeur delivery (SetTarget →
/// synchronous first delivery + one delivery per quantum thereafter — the
/// live cadence observed in launch-drainq.log: HandleUpdateTarget directly
/// after the arm, then sparse).
/// </summary>
internal sealed class RemoteChaseHarness
{
// Styles / substates (full command words, as the wire produces them).
public const uint NonCombat = 0x8000003Du;
public const uint Combat = 0x8000003Cu; // the aggro stance in the live capture
public const uint Ready = 0x41000003u;
public const uint Walk = 0x45000005u;
public const uint Run = 0x44000007u;
public const uint TurnRight = 0x6500000Du;
public const uint AttackAction = 0x10000063u; // one of the live scamp swings
public const uint CreatureGuid = 0x80000BE5u;
public const uint PlayerGuid = 0x5000000Au;
public const float Dt = 1f / 60f;
// R5-V3 (#171): setup cylsphere radii for the sticky/UseSpheres scenarios
// (GameWindow threads the real values via GetSetupCylinder; these are
// creature-typical stand-ins).
public const float OwnRadius = 0.3f;
public const float StickyTargetRadius = 0.5f;
// Field-for-field mirror of GameWindow's RemoteMotion construction
// (GameWindow.cs:592-618): Contact+OnWalkable+Active, InWorld=true (the
// R4-V5 door fix — without it the interp's detached-object guard strips
// every dispatched transition link), and the R4-V5 #160 RemoteWeenie
// (null weenie degrades run-rate to 1.0).
public readonly PhysicsBody Body = new()
{
State = PhysicsStateFlags.ReportCollisions,
TransientState = TransientStateFlags.Contact
| TransientStateFlags.OnWalkable
| TransientStateFlags.Active,
InWorld = true,
};
public readonly MotionInterpreter Interp;
public readonly AnimationSequencer Seq;
public readonly MotionTableDispatchSink Sink;
/// <summary>R5-V5: GameWindow's RemoteMotion.Movement twin — the ONE
/// per-entity MovementManager facade owning Interp + the MoveToManager
/// (retail CPhysicsObj::movement_manager).</summary>
public readonly MovementManager Movement;
/// <summary>The moveto child view (RemoteMotion.MoveTo twin) — non-null
/// after the ctor's MakeMoveToManager, kept so test bodies read
/// unchanged.</summary>
public MoveToManager Mgr => Movement.MoveTo!;
/// <summary>R5-V3 (#171): the creature's PositionManager facade — the
/// EntityPhysicsHost-owned twin (GameWindow binds MoveToManager.StickTo/
/// Unstick + MotionInterpreter.UnstickFromObject to it and drives
/// AdjustOffset/UseTime per tick).</summary>
public readonly PositionManager Pm;
private readonly CreatureHost _creatureHost;
private readonly TargetHost _playerHost;
/// <summary>GameWindow's RemoteMotion.ObservedOmega twin.</summary>
public Vector3 ObservedOmega;
/// <summary>Scripted player (chase target) world position.</summary>
public Vector3 PlayerPos;
public Vector3 PlayerVelocity;
// Scripted targeting stand-in (GameWindow: EntityPhysicsHost/TargetManager).
private bool _targetArmed;
private double _lastDeliveryTime = double.NegativeInfinity;
private double _quantum = 0.5;
public double Now;
// Counters (the live-probe equivalents).
public int BeginTurnBlocked;
public int BeginTurnUnblocked;
public int RunInstalls; // substate transitions INTO RunForward/Walk fwd
public int TicksInRun;
public int TicksInWalkFwd;
public int TotalTicks;
public int MaxRunStreak;
private int _runStreak;
private uint _prevSubstate;
public readonly List<string> Trace = new();
private readonly ITestOutputHelper? _log;
public RemoteChaseHarness(ITestOutputHelper? log = null)
{
_log = log;
var (setup, mtable, loader) = BuildFixture();
Seq = new AnimationSequencer(setup, mtable, loader);
// ── GameWindow spawn path (OnLiveEntitySpawnedLocked ~3781) ──
Seq.InitializeState();
Seq.SetCycle(NonCombat, Ready);
Body.Orientation = MoveToMath.SetHeading(Quaternion.Identity, 0f); // face North
Interp = new MotionInterpreter(Body)
{
WeenieObj = new RemoteWeenie(),
};
// ── EnsureRemoteMotionBindings (GameWindow.cs:4251) verbatim ──
Sink = new MotionTableDispatchSink(Seq)
{
TurnApplied = (turnMotion, turnSpeed) =>
{
float signed = (turnMotion & 0xFFu) == 0x0E
? -MathF.Abs(turnSpeed)
: turnSpeed;
ObservedOmega = new Vector3(0f, 0f, -(MathF.PI / 2f) * signed);
},
TurnStopped = () => ObservedOmega = Vector3.Zero,
};
Interp.DefaultSink = Sink;
// #174: production binds the seam to Manager.HandleEnterWorld
// (strip + full queue drain, retail 0x0050fe20 → 0x0051bdd0) —
// the bare sequence strip orphaned pending manager nodes.
Interp.RemoveLinkAnimations = () => Seq.Manager.HandleEnterWorld();
Interp.InitializeMotionTables = () => Seq.Manager.InitializeState();
Interp.CheckForCompletedMotions = Seq.Manager.CheckForCompletedMotions;
// ── R5-V5: the MovementManager facade owns Interp + the moveto —
// GameWindow's RemoteMotion ctor + EnsureRemoteMotionBindings
// factory shape verbatim (sticky binds inside the factory;
// MakeMoveToManager after the host/Pm exist). ──
Movement = new MovementManager(Interp)
{
MoveToFactory = () =>
{
var mtm = new MoveToManager(
Interp,
stopCompletely: () => Interp.StopCompletely(),
getPosition: () => new CorePosition(1u, Body.Position, Body.Orientation),
getHeading: () => MoveToMath.GetHeading(Body.Orientation),
setHeading: (h, _) => Body.Orientation =
MoveToMath.SetHeading(Body.Orientation, h),
getOwnRadius: () => OwnRadius,
getOwnHeight: () => 1f,
contact: () => Body.OnWalkable,
isInterpolating: () => false,
getVelocity: () => Body.Velocity,
getSelfId: () => CreatureGuid,
setTarget: (ctx, tlid, radius, q) =>
{
_targetArmed = tlid == PlayerGuid;
// TargetManager delivers the FIRST info synchronously on
// SetTarget (live log: HandleUpdateTarget printed directly
// after the arm, same network phase).
DeliverTargetInfo();
},
clearTarget: () => _targetArmed = false,
getTargetQuantum: () => _quantum,
setTargetQuantum: q => _quantum = q,
curTime: () => Now);
// R5-V3 (#171) sticky seam binds (BeginNextNode arrival
// StickTo @0x00529d3a, PerformMovement-head Unstick).
mtm.StickTo = (tlid, radius, height) => Pm.StickTo(tlid, radius, height);
mtm.Unstick = Pm.UnStick;
return mtm;
},
};
// TS-36: interrupt_current_movement → MovementManager::CancelMoveTo
// (the facade relay 0x005241b0) — EnsureRemoteMotionBindings twin.
Interp.InterruptCurrentMovement =
() => Movement.CancelMoveTo(WeenieError.ActionCancelled);
// ── R5-V3 (#171): the PositionManager/sticky wiring — GameWindow's
// V3 additions verbatim: host-owned facade + the UM-funnel-head
// unstick_from_object bind; then MakeMoveToManager (0x00524000)
// invokes the factory above, mirroring the production bind order. ──
_playerHost = new TargetHost(this);
_creatureHost = new CreatureHost(this);
Pm = new PositionManager(_creatureHost);
Movement.MakeMoveToManager();
Interp.UnstickFromObject = Pm.UnStick;
// ── The anim-loop MotionDone binding (GameWindow.cs:10266) ──
Seq.MotionDoneTarget = (m, ok) => Interp.MotionDone(m, ok);
_prevSubstate = Seq.Manager.State.Substate;
}
// ── Wire events ─────────────────────────────────────────────────────────
/// <summary>mt-0 UM (funnel apply): interrupt + unstick head, then
/// MoveToInterpretedState — GameWindow.cs:4893 + 5008.</summary>
public void UmInterpreted(uint stance, uint forward, float forwardSpeed = 1f,
params InboundMotionAction[] actions)
{
Interp.InterruptCurrentMovement?.Invoke();
Interp.UnstickFromObject?.Invoke();
var ims = new InboundInterpretedState
{
CurrentStyle = stance,
ForwardCommand = forward,
ForwardSpeed = forwardSpeed,
SideStepCommand = 0u,
SideStepSpeed = 1f,
TurnCommand = 0u,
TurnSpeed = 1f,
};
if (actions.Length > 0)
ims.Actions = new List<InboundMotionAction>(actions);
Interp.MoveToInterpretedState(ims, Sink);
}
/// <summary>mt-6 UM (MoveToObject arm): interrupt + unstick head, then the
/// RouteServerMoveTo MovementStruct — GameWindow.cs:4483-4508. Params match
/// the live scamp chase (spd 2.08, threshold 15, object distance 0.6).</summary>
public void UmMoveToObject(
float speed = 2.08f,
float distanceToObject = 0.6f,
float walkRunThreshold = 15f,
bool sticky = false,
bool useSpheres = false,
float targetRadius = 0f,
float targetHeight = 0f,
uint wireStance = 0u)
{
Interp.InterruptCurrentMovement?.Invoke();
Interp.UnstickFromObject?.Invoke();
// R5-V4a: the unpack_movement HEAD style-on-change (GameWindow's
// routing-head mirror — 0x00524440 @00524502-0052452c): fires for
// EVERY movement type, BEFORE the type routing, on CHANGE only.
if (wireStance != 0u)
{
uint wireStyle = 0x80000000u | wireStance;
if (Interp.InterpretedState.CurrentStyle != wireStyle)
Interp.DoMotion(wireStyle, new MovementParameters());
}
var mp = new MovementParameters
{
CanWalk = true,
CanRun = true,
CanCharge = true,
CanSidestep = false,
CanWalkBackwards = false,
Speed = speed,
DistanceToObject = distanceToObject,
WalkRunThreshhold = walkRunThreshold,
FailDistance = float.MaxValue,
// R5-V3 (#171): ACE arms every melee chase Sticky + UseSpheres
// (Monster_Navigation.cs:406-419; UseSpheres is the ACE default).
Sticky = sticky,
UseSpheres = useSpheres,
};
var ms = new MovementStruct
{
Type = MovementType.MoveToObject,
ObjectId = PlayerGuid,
TopLevelId = PlayerGuid,
Pos = new CorePosition(1u, PlayerPos, Quaternion.Identity),
Params = mp,
// R5-V3: the RouteServerMoveTo radius threading twin — retail
// reads the TARGET's PartArray radius/height at the call site.
Radius = targetRadius,
Height = targetHeight,
};
// R5-V5: RouteServerMoveTo twin — through the facade
// (MovementManager::PerformMovement 0x005240d0).
Movement.PerformMovement(ms);
}
private void DeliverTargetInfo()
{
if (!_targetArmed) return;
_lastDeliveryTime = Now;
var pos = new CorePosition(1u, PlayerPos, Quaternion.Identity);
var info = new TargetInfo
{
ObjectId = PlayerGuid,
Status = TargetStatus.Ok,
TargetPosition = pos,
InterpolatedPosition = pos,
};
// R5-V3 fan order (EntityPhysicsHost.HandleUpdateTarget — retail
// CPhysicsObj::HandleUpdateTarget 0x00512bc0): the MovementManager
// relay (@0x00512bf0 → moveto) first, then PositionManager (the
// sticky consumer).
Movement.HandleUpdateTarget(info);
Pm.HandleUpdateTarget(info);
}
// ── R5-V3 (#171): the IPhysicsObjHost twins of GameWindow's
// EntityPhysicsHost (creature side) and ResolvePhysicsHost's minimal
// target host (player side). ──
private sealed class CreatureHost : IPhysicsObjHost
{
private readonly RemoteChaseHarness _h;
public CreatureHost(RemoteChaseHarness h) => _h = h;
public uint Id => CreatureGuid;
public CorePosition Position => new(1u, _h.Body.Position, _h.Body.Orientation);
public Vector3 Velocity => _h.Body.Velocity;
public float Radius => OwnRadius;
public bool InContact => _h.Body.OnWalkable;
public float? MinterpMaxSpeed => _h.Interp.GetMaxSpeed();
public double CurTime => _h.Now;
public double PhysicsTimerTime => _h.Now;
public IPhysicsObjHost? GetObjectA(uint id)
=> id == PlayerGuid ? _h._playerHost : null;
public void HandleUpdateTarget(TargetInfo info)
{
_h.Movement.HandleUpdateTarget(info);
_h.Pm.HandleUpdateTarget(info);
}
public void InterruptCurrentMovement()
=> _h.Movement.CancelMoveTo(WeenieError.ActionCancelled);
public void SetTarget(uint contextId, uint objectId, float radius, double quantum)
{
// The scripted TargetManager stand-in — StickyManager::StickTo
// subscribes at quantum 0.5 (0x00555710) with a synchronous first
// delivery (the AddVoyeur immediate snapshot).
_h._targetArmed = objectId == PlayerGuid;
_h._quantum = quantum;
_h.DeliverTargetInfo();
}
public void ClearTarget() => _h._targetArmed = false;
public void ReceiveTargetUpdate(TargetInfo info) { }
public void AddVoyeur(uint watcherId, float radius, double quantum) { }
public void RemoveVoyeur(uint watcherId) { }
}
private sealed class TargetHost : IPhysicsObjHost
{
private readonly RemoteChaseHarness _h;
public TargetHost(RemoteChaseHarness h) => _h = h;
public uint Id => PlayerGuid;
public CorePosition Position => new(1u, _h.PlayerPos, Quaternion.Identity);
public Vector3 Velocity => _h.PlayerVelocity;
public float Radius => StickyTargetRadius;
public bool InContact => true;
public float? MinterpMaxSpeed => null;
public double CurTime => _h.Now;
public double PhysicsTimerTime => _h.Now;
public IPhysicsObjHost? GetObjectA(uint id) => null;
public void HandleUpdateTarget(TargetInfo info) { }
public void InterruptCurrentMovement() { }
public void SetTarget(uint contextId, uint objectId, float radius, double quantum) { }
public void ClearTarget() { }
public void ReceiveTargetUpdate(TargetInfo info) { }
public void AddVoyeur(uint watcherId, float radius, double quantum) { }
public void RemoveVoyeur(uint watcherId) { }
}
// ── The per-tick pipeline (GameWindow.TickAnimations order) ────────────
public void Tick()
{
Now += Dt;
TotalTicks++;
// Player (chase target) moves per its scripted velocity.
PlayerPos += PlayerVelocity * Dt;
// 1. Voyeur delivery (player host HandleTargetting → this entity's
// HandleUpdateTarget; GameWindow.cs:8094 runs before the per-remote
// loop, 9697 in-loop).
if (_targetArmed && Now - _lastDeliveryTime >= _quantum)
DeliverTargetInfo();
// 2. MovementManager drive (TickRemoteMoveTo — the R5-V5 facade
// relay, MovementManager::UseTime 0x005242f0).
Movement.UseTime();
// 3. get_state_velocity → body velocity (the d2ccc80e refresh,
// GameWindow.cs:10024).
if (Body.OnWalkable)
Body.set_local_velocity(Interp.get_state_velocity(), false);
// 4. Manual omega integration (GameWindow.cs:10050-10058 verbatim).
if (ObservedOmega.LengthSquared() > 1e-8f)
{
float omegaMag = ObservedOmega.Length();
var axis = ObservedOmega / omegaMag;
float angle = omegaMag * Dt;
var deltaRot = Quaternion.CreateFromAxisAngle(axis, angle);
Body.Orientation = Quaternion.Normalize(
Quaternion.Multiply(Body.Orientation, deltaRot));
}
// 5. R5-V3 (#171): the sticky steer — GameWindow's legacy-branch slot
// (retail UpdatePositionInternal PositionManager::adjust_offset
// @0x00512d0e, composed BEFORE the velocity integration). Origin is
// mover-local; the rotation carries a RELATIVE heading (identity =
// untouched = no turn).
var pmDelta = new MotionDeltaFrame();
Pm.AdjustOffset(pmDelta, Dt);
if (pmDelta.Origin != Vector3.Zero)
Body.Position += Vector3.Transform(pmDelta.Origin, Body.Orientation);
if (!pmDelta.Orientation.IsIdentity)
Body.Orientation = MoveToMath.SetHeading(
Body.Orientation,
MoveToMath.GetHeading(Body.Orientation) + pmDelta.GetHeading());
// 5b. Position integration (UpdatePhysicsInternal, simplified: grounded,
// no gravity participation for this scenario).
Body.Position += Body.Velocity * Dt;
// 5c. R5-V3: PositionManager::UseTime (retail UpdateObjectInternal
// tail @0x005159b3) — the sticky 1 s lease watchdog.
Pm.UseTime();
// 6. Anim loop (GameWindow.cs:10247-10309): advance, drain AnimDone
// hooks into the manager countdown, zero-tick sweep.
Seq.Advance(Dt);
var hooks = Seq.ConsumePendingHooks();
for (int i = 0; i < hooks.Count; i++)
{
if (hooks[i] is DatReaderWriter.Types.AnimationDoneHook)
Seq.Manager.AnimationDone(success: true);
}
Seq.Manager.UseTime();
// ── Observables ──
uint substate = Seq.Manager.State.Substate;
if (substate == Run) TicksInRun++;
if (substate == Walk) TicksInWalkFwd++;
bool inFwd = substate == Run || substate == Walk;
if (inFwd)
{
_runStreak++;
if (_runStreak > MaxRunStreak) MaxRunStreak = _runStreak;
}
else
{
_runStreak = 0;
}
if (inFwd && _prevSubstate != Run && _prevSubstate != Walk)
RunInstalls++;
_prevSubstate = substate;
}
public float Heading => MoveToMath.GetHeading(Body.Orientation);
public float DistToPlayer => Vector3.Distance(Body.Position, PlayerPos);
public void Snapshot(string tag)
{
string line = FormattableString.Invariant(
$"t={Now,6:F2} {tag,-14} mt={Mgr.MovementTypeState,-14} substate=0x{Seq.Manager.State.Substate:X8} heading={Heading,6:F1} dist={DistToPlayer,6:F2} pending={Interp.MotionsPending()} omega.Z={ObservedOmega.Z,6:F3}");
Trace.Add(line);
_log?.WriteLine(line);
}
// ── Fixture ─────────────────────────────────────────────────────────────
private static Animation MakeAnim(int numFrames)
{
var anim = new Animation();
for (int f = 0; f < numFrames; f++)
{
var pf = new AnimationFrame(1u);
pf.Frames.Add(new Frame { Origin = Vector3.Zero, Orientation = Quaternion.Identity });
anim.PartFrames.Add(pf);
}
return anim;
}
private static MotionData MakeMd(uint animId, float framerate = 30f,
Vector3? velocity = null, Vector3? omega = null)
{
var md = new MotionData();
QualifiedDataId<Animation> qid = animId;
md.Anims.Add(new AnimData
{
AnimId = qid,
LowFrame = 0,
HighFrame = -1,
Framerate = framerate,
});
if (velocity is { } v)
{
md.Velocity = v;
md.Flags |= DatReaderWriter.Enums.MotionDataFlags.HasVelocity;
}
if (omega is { } o)
{
md.Omega = o;
md.Flags |= DatReaderWriter.Enums.MotionDataFlags.HasOmega;
}
return md;
}
private static void AddLink(MotionTable mt, uint style, uint from, uint to, MotionData md)
{
int outer = (int)((style << 16) | (from & 0xFFFFFFu));
if (!mt.Links.TryGetValue(outer, out var cmd))
{
cmd = new MotionCommandData();
mt.Links[outer] = cmd;
}
cmd.MotionData[(int)to] = md;
}
/// <summary>
/// Two-stance creature table shaped like the Mite Scamp's: NonCombat +
/// Combat styles (default substate Ready in both), Walk/Run cycles with
/// entry/exit links (15 frames @30fps = 0.5 s links, the realistic stop/
/// start durations), a stance-transition link, an attack action link, and
/// a global TurnRight physics-only modifier.
/// </summary>
private static (Setup, MotionTable, ChaseLoader) BuildFixture()
{
const uint ReadyAnimNC = 0x200u;
const uint ReadyAnimC = 0x201u;
const uint WalkAnim = 0x202u;
const uint RunAnim = 0x203u;
const uint ReadyToWalk = 0x204u;
const uint WalkToReady = 0x205u;
const uint ReadyToRun = 0x206u;
const uint RunToReady = 0x207u;
const uint StanceLink = 0x208u; // NonCombat.Ready → Combat (draw)
const uint AttackLink = 0x209u; // Combat.Ready → attack swing
const uint TurnAnim = 0x20Au;
var setup = new Setup();
setup.Parts.Add(0x01000000u);
setup.DefaultScale.Add(Vector3.One);
var loader = new ChaseLoader();
loader.Register(ReadyAnimNC, MakeAnim(30));
loader.Register(ReadyAnimC, MakeAnim(30));
loader.Register(WalkAnim, MakeAnim(30));
loader.Register(RunAnim, MakeAnim(30));
loader.Register(ReadyToWalk, MakeAnim(15));
loader.Register(WalkToReady, MakeAnim(15));
loader.Register(ReadyToRun, MakeAnim(15));
loader.Register(RunToReady, MakeAnim(15));
loader.Register(StanceLink, MakeAnim(15));
loader.Register(AttackLink, MakeAnim(45)); // 1.5 s swing
loader.Register(TurnAnim, MakeAnim(30));
var mt = new MotionTable { DefaultStyle = (DRWMotionCommand)NonCombat };
mt.StyleDefaults[(DRWMotionCommand)NonCombat] = (DRWMotionCommand)Ready;
mt.StyleDefaults[(DRWMotionCommand)Combat] = (DRWMotionCommand)Ready;
static int CycleKey(uint style, uint substate)
=> (int)((style << 16) | (substate & 0xFFFFFFu));
mt.Cycles[CycleKey(NonCombat, Ready)] = MakeMd(ReadyAnimNC);
mt.Cycles[CycleKey(Combat, Ready)] = MakeMd(ReadyAnimC);
foreach (uint style in new[] { NonCombat, Combat })
{
mt.Cycles[CycleKey(style, Walk)] =
MakeMd(WalkAnim, velocity: new Vector3(0f, 3.12f, 0f));
mt.Cycles[CycleKey(style, Run)] =
MakeMd(RunAnim, velocity: new Vector3(0f, 4.0f, 0f));
AddLink(mt, style, Ready, Walk, MakeMd(ReadyToWalk));
AddLink(mt, style, Walk, Ready, MakeMd(WalkToReady));
AddLink(mt, style, Ready, Run, MakeMd(ReadyToRun));
AddLink(mt, style, Run, Ready, MakeMd(RunToReady));
}
AddLink(mt, NonCombat, Ready, Combat, MakeMd(StanceLink));
AddLink(mt, Combat, Ready, NonCombat, MakeMd(StanceLink));
AddLink(mt, Combat, Ready, AttackAction, MakeMd(AttackLink));
// Global (unstyled) TurnRight modifier — physics-only in Branch 4.
mt.Modifiers[(int)(TurnRight & 0xFFFFFFu)] = MakeMd(TurnAnim);
return (setup, mt, loader);
}
}
public sealed class RemoteChaseEndToEndHarnessTests
{
private readonly ITestOutputHelper _out;
public RemoteChaseEndToEndHarnessTests(ITestOutputHelper output) => _out = output;
private const float Dt = RemoteChaseHarness.Dt;
private static int Seconds(float s) => (int)MathF.Round(s / Dt);
/// <summary>
/// The core chase cycle: aggro stance change, one mt-6 arm at a target
/// 90° off the creature's facing, 15 m away, stationary. Retail bar: the
/// stance links play out (~1 s), the chase turn starts, completes at the
/// turn rate (90° at π/2·2.08 rad/s ≈ 0.5 s), and BeginMoveForward
/// installs the forward cycle. Total budget: 4 s of ticks is generous.
/// </summary>
[Theory]
[InlineData(90f)] // target to the East → TurnRight path
[InlineData(270f)] // target to the West → TurnLeft path
[InlineData(170f)] // near-reversal → long right turn
public void SingleArm_TurnCompletes_AndForwardInstalls(float bearingDeg)
{
var h = new RemoteChaseHarness(_out);
float rad = (90f - bearingDeg) * MathF.PI / 180f; // compass → math angle
h.PlayerPos = new Vector3(MathF.Cos(rad), MathF.Sin(rad), 0f) * 15f;
h.PlayerVelocity = Vector3.Zero;
// settle spawn state
for (int i = 0; i < Seconds(0.5f); i++) h.Tick();
h.Snapshot("spawned");
// aggro: stance UM (the live capture's mt-0 stance=0x3C fwd=Ready)
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
for (int i = 0; i < Seconds(1.5f); i++) h.Tick();
h.Snapshot("post-stance");
// the arm
h.UmMoveToObject();
h.Snapshot("armed");
int installTick = -1;
for (int i = 0; i < Seconds(6f); i++)
{
h.Tick();
if (installTick < 0
&& (h.Seq.Manager.State.Substate == RemoteChaseHarness.Run
|| h.Seq.Manager.State.Substate == RemoteChaseHarness.Walk))
{
installTick = i;
h.Snapshot("fwd-install");
}
if (i % Seconds(0.5f) == 0) h.Snapshot("tick");
}
h.Snapshot("end");
Assert.True(installTick >= 0,
$"forward cycle never installed within 6 s of the arm (bearing {bearingDeg}°); " +
$"final: mt={h.Mgr.MovementTypeState} substate=0x{h.Seq.Manager.State.Substate:X8} " +
$"heading={h.Heading:F1} pending={h.Interp.MotionsPending()} omega.Z={h.ObservedOmega.Z:F3}");
Assert.True(installTick <= Seconds(4f),
$"forward cycle took {installTick * Dt:F2} s to install (bearing {bearingDeg}°) — " +
"retail installs within the turn duration (~1-2 s)");
}
/// <summary>
/// The live failure scenario: the player FLEES at 4 m/s and ACE re-arms
/// mt-6 every 2 s (launch-drainq.log cadence). Retail bar: BeginMoveForward
/// ≈ one per arm (21/22 in the live cdb trace) and the run is SUSTAINED —
/// the forward substate holds for most of the chase.
/// </summary>
[Fact]
public void FleeingTarget_RunSustainedAcrossRearms()
{
var h = new RemoteChaseHarness(_out);
h.PlayerPos = new Vector3(0f, 10f, 0f); // dead ahead, 10 m
h.PlayerVelocity = new Vector3(0f, 4f, 0f); // fleeing straight away
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
for (int i = 0; i < Seconds(1.5f); i++) h.Tick();
int arms = 0;
int chaseTicks = Seconds(12f);
for (int i = 0; i < chaseTicks; i++)
{
if (i % Seconds(2f) == 0)
{
h.UmMoveToObject();
arms++;
h.Snapshot($"arm#{arms}");
}
h.Tick();
if (i % Seconds(1f) == 0) h.Snapshot("tick");
}
h.Snapshot("end");
int fwdTicks = h.TicksInRun + h.TicksInWalkFwd;
float fwdFraction = fwdTicks / (float)chaseTicks;
_out.WriteLine(FormattableString.Invariant(
$"arms={arms} installs={h.RunInstalls} fwdTicks={fwdTicks}/{chaseTicks} ({fwdFraction:P0}) maxStreak={h.MaxRunStreak * Dt:F2}s"));
Assert.True(h.RunInstalls >= arms - 1,
$"run installed only {h.RunInstalls}× across {arms} arms — " +
"retail reinstalls per arm (21/22)");
Assert.True(fwdFraction > 0.5f,
$"forward substate held only {fwdFraction:P0} of the chase — the run is not " +
"sustained (live #170 symptom: short bursts + idle glide)");
}
/// <summary>
/// Attack interleave: mid-chase, an attack UM (mt-0, action list carrying
/// the swing, fwd=Ready — the wire shape from the live capture) interrupts
/// the moveto (retail-faithful), the swing plays, and the next mt-6 re-arm
/// must reinstall the run. Also asserts the #170 drain criterion:
/// pending_motions fully empties after the swing (add == done — the retail
/// cdb invariant).
/// </summary>
[Fact]
public void AttackUm_ThenRearm_RunReinstalls_AndQueueDrains()
{
var h = new RemoteChaseHarness(_out);
h.PlayerPos = new Vector3(0f, 12f, 0f);
h.PlayerVelocity = Vector3.Zero;
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
for (int i = 0; i < Seconds(1.5f); i++) h.Tick();
h.UmMoveToObject();
for (int i = 0; i < Seconds(3f); i++) h.Tick();
h.Snapshot("chasing");
// the swing: interrupt + action (stamp 1, autonomous false)
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready, 1f,
new InboundMotionAction(RemoteChaseHarness.AttackAction, Stamp: 1,
Autonomous: false, Speed: 1f));
for (int i = 0; i < Seconds(2.5f); i++) h.Tick();
h.Snapshot("post-swing");
Assert.False(h.Interp.MotionsPending(),
"pending_motions did not fully empty after the swing — the #170 " +
"residual (retail: add_to_queue == MotionDone exactly)");
// the player breaks away (out of attack range), then ACE re-arms —
// the run must come back
h.PlayerPos += new Vector3(0f, 10f, 0f);
h.UmMoveToObject();
int installTick = -1;
for (int i = 0; i < Seconds(5f); i++)
{
h.Tick();
if (installTick < 0
&& (h.Seq.Manager.State.Substate == RemoteChaseHarness.Run
|| h.Seq.Manager.State.Substate == RemoteChaseHarness.Walk))
{
installTick = i;
}
}
h.Snapshot("post-rearm");
Assert.True(installTick >= 0,
$"run did not reinstall after the post-swing re-arm; " +
$"mt={h.Mgr.MovementTypeState} substate=0x{h.Seq.Manager.State.Substate:X8} " +
$"pending={h.Interp.MotionsPending()}");
}
// ── R5-V3 (#171): sticky melee scenarios ────────────────────────────────
private static float AbsHeadingDiff(float a, float b)
{
float d = MathF.Abs(a - b) % 360f;
return d > 180f ? 360f - d : d;
}
/// <summary>
/// The #171 fix's core: ACE arms melee chases Sticky+UseSpheres with the
/// target's real radii; on arrival BeginNextNode hands off to
/// PositionManager::StickTo (0x00529d3a) and StickyManager::adjust_offset
/// (0x00555430) holds a 0.3 m edge gap + live facing against a strafing
/// target — for the 1 s lease, which is set ONCE at StickTo and NOT
/// refreshed by target updates (retail 0x00555710/0x00555610): a stick
/// not re-issued by a fresh server arm tears itself down.
/// </summary>
[Fact]
public void StickyArrival_TracksStrafingTarget_ThenLeaseExpires()
{
var h = new RemoteChaseHarness(_out);
h.PlayerPos = new Vector3(0f, 10f, 0f); // dead ahead (North)
h.PlayerVelocity = Vector3.Zero;
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
for (int i = 0; i < Seconds(1.5f); i++) h.Tick();
h.UmMoveToObject(sticky: true, useSpheres: true,
targetRadius: RemoteChaseHarness.StickyTargetRadius, targetHeight: 1.2f);
int stickTick = -1;
for (int i = 0; i < Seconds(8f) && stickTick < 0; i++)
{
h.Tick();
if (h.Pm.GetStickyObjectId() == RemoteChaseHarness.PlayerGuid)
stickTick = i;
}
h.Snapshot("stuck");
Assert.True(stickTick >= 0,
$"sticky never armed within 8 s of the arm; mt={h.Mgr.MovementTypeState} " +
$"dist={h.DistToPlayer:F2}");
// Arrival cleaned the moveto BEFORE the handoff (BeginNextNode reads
// Sought* pre-CleanUp; CleanUp resets movement_type to Invalid).
Assert.Equal(MovementType.Invalid, h.Mgr.MovementTypeState);
// The target strafes — the follower must track gap AND facing
// (adjust_offset resolves the LIVE target via GetObjectA per tick).
h.PlayerVelocity = new Vector3(2f, 0f, 0f);
for (int i = 0; i < Seconds(0.8f); i++) h.Tick();
h.Snapshot("strafed");
Assert.Equal(RemoteChaseHarness.PlayerGuid, h.Pm.GetStickyObjectId()); // inside the lease
float gap = MoveToMath.CylinderDistanceNoZ(
RemoteChaseHarness.OwnRadius, h.Body.Position,
RemoteChaseHarness.StickyTargetRadius, h.PlayerPos);
Assert.True(MathF.Abs(gap - StickyManager.StickyRadius) < 0.1f,
$"stick gap {gap:F2} m — expected ≈{StickyManager.StickyRadius:F1} m (StickyRadius)");
float bearing = MoveToMath.PositionHeading(h.Body.Position, h.PlayerPos);
Assert.True(AbsHeadingDiff(h.Heading, bearing) < 5f,
$"facing {h.Heading:F1}° vs bearing {bearing:F1}° — sticky facing not tracking");
// Lease expiry: >1 s since StickTo with no re-arm → the UseTime
// watchdog drops the stick (retail parity — ACE re-arms each attack
// cycle, renewing the stick server-side).
h.PlayerVelocity = Vector3.Zero;
for (int i = 0; i < Seconds(0.5f); i++) h.Tick();
Assert.Equal(0u, h.Pm.GetStickyObjectId());
}
/// <summary>
/// The pack-melee reshuffle cycle: every fresh server arm
/// (PerformMovement) tears the previous stick down at the HEAD
/// (unstick_from_object → PositionManager::UnStick — the retail
/// PerformMovement:414 + UM-funnel-head sites), then the new chase
/// re-arrives and re-sticks.
/// </summary>
[Fact]
public void NextPerformMovement_Unsticks_ThenRearrivalResticks()
{
var h = new RemoteChaseHarness(_out);
h.PlayerPos = new Vector3(0f, 8f, 0f);
h.PlayerVelocity = Vector3.Zero;
h.UmInterpreted(RemoteChaseHarness.Combat, RemoteChaseHarness.Ready);
for (int i = 0; i < Seconds(1.5f); i++) h.Tick();
h.UmMoveToObject(sticky: true, useSpheres: true,
targetRadius: RemoteChaseHarness.StickyTargetRadius, targetHeight: 1.2f);
for (int i = 0; i < Seconds(8f); i++)
{
h.Tick();
if (h.Pm.GetStickyObjectId() != 0u) break;
}
Assert.Equal(RemoteChaseHarness.PlayerGuid, h.Pm.GetStickyObjectId());
// The target breaks away; ACE re-arms the chase — the arm must
// UNSTICK immediately (stale stick torn down before the new moveto).
h.PlayerPos += new Vector3(0f, 8f, 0f);
h.UmMoveToObject(sticky: true, useSpheres: true,
targetRadius: RemoteChaseHarness.StickyTargetRadius, targetHeight: 1.2f);
Assert.Equal(0u, h.Pm.GetStickyObjectId());
Assert.Equal(MovementType.MoveToObject, h.Mgr.MovementTypeState);
// ...and the new chase re-arrives and re-sticks.
int restick = -1;
for (int i = 0; i < Seconds(8f) && restick < 0; i++)
{
h.Tick();
if (h.Pm.GetStickyObjectId() == RemoteChaseHarness.PlayerGuid)
restick = i;
}
Assert.True(restick >= 0,
$"chase did not re-stick after the re-arm; mt={h.Mgr.MovementTypeState} " +
$"dist={h.DistToPlayer:F2}");
}
/// <summary>
/// R5-V4a: the unpack-head style-on-change — a chase arm (mt-6) whose UM
/// carries a CHANGED stance applies the stance FIRST (retail
/// unpack_movement @00524502-0052452c dispatches DoMotion(style) before
/// the movement-type switch), so the creature draws into Combat and THEN
/// runs — instead of chasing in the old NonCombat stance until the next
/// mt-0 UM. Closes the RetailObserverTraceConformanceTests "S3 wires the
/// unpack-level style-on-change" exclusion's production gap.
/// </summary>
[Fact]
public void ChaseArm_WithStanceChange_AppliesStanceBeforeTheChase()
{
var h = new RemoteChaseHarness(_out);
h.PlayerPos = new Vector3(0f, 12f, 0f);
h.PlayerVelocity = Vector3.Zero;
// settle in NonCombat — NO prior stance UM (the pre-V4 gap: nothing
// but an mt-0 could change the stance).
for (int i = 0; i < Seconds(0.5f); i++) h.Tick();
Assert.Equal(RemoteChaseHarness.NonCombat, h.Seq.Manager.State.Style);
// the arm carries the Combat stance in its UM header (mt-6).
h.UmMoveToObject(wireStance: RemoteChaseHarness.Combat & 0xFFFFu);
// the stance adopts at the head — before any chase motion completes.
Assert.Equal(RemoteChaseHarness.Combat, h.Interp.InterpretedState.CurrentStyle);
// ...and the chase still installs its forward cycle normally, now in
// the Combat style family.
int installTick = -1;
for (int i = 0; i < Seconds(6f) && installTick < 0; i++)
{
h.Tick();
if (h.Seq.Manager.State.Substate == RemoteChaseHarness.Run
|| h.Seq.Manager.State.Substate == RemoteChaseHarness.Walk)
installTick = i;
}
Assert.True(installTick >= 0,
$"forward cycle never installed after the stance-carrying arm; " +
$"mt={h.Mgr.MovementTypeState} substate=0x{h.Seq.Manager.State.Substate:X8}");
Assert.Equal(RemoteChaseHarness.Combat, h.Seq.Manager.State.Style);
}
}

247
tests/AcDream.Core.Tests/Physics/Motion/StickyManagerTests.cs Normal file
View file

@ -0,0 +1,247 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5 conformance — <see cref="StickyManager"/> (retail 0x00555400-0x00555866).
/// Lifecycle (StickTo/UnStick/timeout/HandleUpdateTarget) + the decoded
/// <c>adjust_offset</c> steering math (port-plan §2a).
/// </summary>
public sealed class StickyManagerTests
{
private static (R5Host self, R5Host target, StickyManager sticky) Setup(
uint targetId = 20u, float targetRadius = 0.5f)
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world);
var target = new R5Host(targetId, world);
var sticky = new StickyManager(self);
return (self, target, sticky);
}
private static StickyManager StuckAndInitialized(
R5Host self, R5Host target, Vector3 targetOrigin, float targetRadius = 0.5f)
{
var sticky = new StickyManager(self);
sticky.StickTo(target.Id, targetRadius, targetHeight: 1.0f);
target.SetOrigin(targetOrigin);
var tp = new Position(1u, targetOrigin, Quaternion.Identity);
sticky.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
return sticky;
}
[Fact]
public void StickTo_SetsTargetAndTimeout_AndSubscribesVoyeurOnTarget()
{
var (self, target, sticky) = Setup();
self.CurTime = 100.0;
sticky.StickTo(target.Id, targetRadius: 0.5f, targetHeight: 2.0f);
Assert.Equal(target.Id, sticky.TargetId);
Assert.Equal(0.5f, sticky.TargetRadius);
Assert.False(sticky.Initialized);
Assert.Equal(101.0, sticky.StickyTimeoutTime); // now + StickyTime(1.0)
// set_target(0, target, 0.5, 0.5) → watcher subscribes ON the target.
Assert.NotNull(target.TargetManagerOrNull);
Assert.True(target.TargetManager.VoyeurTable!.ContainsKey(self.Id));
}
[Fact]
public void HandleUpdateTarget_Ok_MarksInitializedAndCachesPosition()
{
var (self, target, sticky) = Setup();
sticky.StickTo(target.Id, 0.5f, 1.0f);
var tp = new Position(1u, new Vector3(3f, 0f, 0f), Quaternion.Identity);
sticky.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
Assert.True(sticky.Initialized);
Assert.Equal(new Vector3(3f, 0f, 0f), sticky.TargetPosition.Frame.Origin);
}
[Fact]
public void HandleUpdateTarget_ForeignObject_Ignored()
{
var (self, target, sticky) = Setup();
sticky.StickTo(target.Id, 0.5f, 1.0f);
var tp = new Position(1u, Vector3.Zero, Quaternion.Identity);
sticky.HandleUpdateTarget(new TargetInfo(999u, TargetStatus.Ok, tp, tp));
Assert.False(sticky.Initialized);
Assert.Equal(target.Id, sticky.TargetId); // still stuck to the real target
}
[Fact]
public void HandleUpdateTarget_NonOkStatus_TearsDown()
{
var (self, target, sticky) = Setup();
sticky.StickTo(target.Id, 0.5f, 1.0f);
int interruptsBefore = self.InterruptCurrentMovementCalls;
var tp = new Position(1u, Vector3.Zero, Quaternion.Identity);
sticky.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.ExitWorld, tp, tp));
Assert.Equal(0u, sticky.TargetId);
Assert.False(sticky.Initialized);
Assert.Equal(interruptsBefore + 1, self.InterruptCurrentMovementCalls);
}
[Fact]
public void UseTime_BeforeDeadline_KeepsStick()
{
var (self, target, sticky) = Setup();
self.CurTime = 100.0;
sticky.StickTo(target.Id, 0.5f, 1.0f); // deadline 101.0
self.CurTime = 100.9;
sticky.UseTime();
Assert.Equal(target.Id, sticky.TargetId);
}
[Fact]
public void UseTime_PastDeadline_UnsticksAndInterrupts()
{
var (self, target, sticky) = Setup();
self.CurTime = 100.0;
sticky.StickTo(target.Id, 0.5f, 1.0f); // deadline 101.0
// AT the deadline the stick survives — retail 0x00555626 tears down
// strictly AFTER it (`test ah,0x41`: C0|C3 = less-or-equal keeps;
// ACE `>` too). The R5-V1 pin of `>=` was the wrong value.
self.CurTime = 101.0;
sticky.UseTime();
Assert.Equal(target.Id, sticky.TargetId);
int interruptsBefore = self.InterruptCurrentMovementCalls;
self.CurTime = 101.001;
sticky.UseTime();
Assert.Equal(0u, sticky.TargetId);
Assert.Equal(interruptsBefore + 1, self.InterruptCurrentMovementCalls);
}
[Fact]
public void ReStick_TearsDownPreviousBeforeSettingNew()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world);
var a = new R5Host(20u, world);
var b = new R5Host(21u, world);
var sticky = new StickyManager(self);
sticky.StickTo(a.Id, 0.5f, 1.0f);
int interruptsBefore = self.InterruptCurrentMovementCalls;
sticky.StickTo(b.Id, 0.5f, 1.0f);
Assert.Equal(b.Id, sticky.TargetId);
Assert.Equal(interruptsBefore + 1, self.InterruptCurrentMovementCalls); // old stick torn down
}
[Fact]
public void AdjustOffset_NotInitialized_IsNoOp()
{
var (self, target, sticky) = Setup();
sticky.StickTo(target.Id, 0.5f, 1.0f); // no HandleUpdateTarget → not initialized
var frame = new MotionDeltaFrame { Origin = new Vector3(9f, 9f, 9f) };
sticky.AdjustOffset(frame, 0.1);
Assert.Equal(new Vector3(9f, 9f, 9f), frame.Origin); // untouched
}
[Fact]
public void AdjustOffset_SteersTowardTarget_ClampedToStep()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world) { Radius = 0.5f, MinterpMaxSpeed = 1.0f };
var target = new R5Host(20u, world);
var sticky = StuckAndInitialized(self, target, new Vector3(5f, 0f, 0f));
var frame = new MotionDeltaFrame();
sticky.AdjustOffset(frame, quantum: 0.1);
// dir = +X (east); speed = 1.0 * 5 = 5; delta = 5 * 0.1 = 0.5 (< dist 3.7).
Assert.Equal(0.5f, frame.Origin.X, 3);
Assert.Equal(0f, frame.Origin.Y, 3);
Assert.Equal(0f, frame.Origin.Z, 3); // horizontal-only
// heading toward +X (east) = 90° compass.
Assert.Equal(90f, frame.GetHeading(), 1);
}
[Fact]
public void AdjustOffset_TooClose_BacksOff_SignedDistance()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world) { Radius = 0.5f, MinterpMaxSpeed = 1.0f };
var target = new R5Host(20u, world);
// centerDist 0.9, cyl = 0.9-0.5-0.5 = -0.1, minus 0.3 → dist = -0.4.
var sticky = StuckAndInitialized(self, target, new Vector3(0.9f, 0f, 0f));
var frame = new MotionDeltaFrame();
sticky.AdjustOffset(frame, quantum: 0.1);
// delta = 5*0.1 = 0.5 >= |dist|=0.4 → delta = dist = -0.4; dir +X * -0.4 → back off (-X).
Assert.Equal(-0.4f, frame.Origin.X, 3);
}
[Fact]
public void AdjustOffset_DeepOverlap_BacksOff_RateLimited()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world) { Radius = 0.5f, MinterpMaxSpeed = 1.0f };
var target = new R5Host(20u, world);
// centerDist 0.1 → cyl = 0.1-0.5-0.5 = -0.9, minus 0.3 → dist = -1.2
// (overlap DEEPER than one tick's step).
var sticky = StuckAndInitialized(self, target, new Vector3(0.1f, 0f, 0f));
var frame = new MotionDeltaFrame();
sticky.AdjustOffset(frame, quantum: 0.1);
// delta = 5*0.1 = 0.5 < |dist|=1.2 — ACE's literal branch kept +0.5
// here (INWARD: the #171 gate-3 runaway-to-center; 1661 probe ticks,
// all inward, equilibrium at centers-coincident). The sign pin backs
// off rate-limited: dir +X × −0.5.
Assert.Equal(-0.5f, frame.Origin.X, 3);
}
[Fact]
public void AdjustOffset_UsesCachedPosition_WhenTargetUnresolvable()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world) { Radius = 0.5f, MinterpMaxSpeed = 1.0f };
var target = new R5Host(20u, world);
var sticky = new StickyManager(self);
sticky.StickTo(target.Id, 0.5f, 1.0f);
// Cache a position via HandleUpdateTarget, then make the target vanish.
var tp = new Position(1u, new Vector3(4f, 0f, 0f), Quaternion.Identity);
sticky.HandleUpdateTarget(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
target.Resolvable = false; // GetObjectA(target) → null → fall back to cached
var frame = new MotionDeltaFrame();
sticky.AdjustOffset(frame, quantum: 0.1);
Assert.Equal(0.5f, frame.Origin.X, 3); // still steers toward cached (4,0,0)
}
[Fact]
public void AdjustOffset_NoMinterp_UsesFallbackSpeed()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world) { Radius = 0.5f, MinterpMaxSpeed = null };
var target = new R5Host(20u, world);
var sticky = StuckAndInitialized(self, target, new Vector3(50f, 0f, 0f));
var frame = new MotionDeltaFrame();
sticky.AdjustOffset(frame, quantum: 0.1);
// fallback speed 15 → delta = 15 * 0.1 = 1.5 (dist ≈ 49 → not clamped).
Assert.Equal(1.5f, frame.Origin.X, 3);
}
}

255
tests/AcDream.Core.Tests/Physics/Motion/TargetManagerTests.cs Normal file
View file

@ -0,0 +1,255 @@
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Physics.Motion;
using Xunit;
namespace AcDream.Core.Tests.Physics.Motion;
/// <summary>
/// R5 conformance — <see cref="TargetManager"/> voyeur system (retail
/// 0x0051a370-0x0051ad90). Watcher role (SetTarget/ReceiveUpdate/timeout),
/// watched role (AddVoyeur/HandleTargetting/CheckAndUpdateVoyeur), and the full
/// cross-entity round-trip (port-plan §2d/§2e). Replaces the AP-79 adapter.
/// </summary>
public sealed class TargetManagerTests
{
private static (R5Host self, R5Host target, Dictionary<uint, R5Host> world) TwoHosts()
{
var world = new Dictionary<uint, R5Host>();
var self = new R5Host(10u, world);
var target = new R5Host(20u, world);
return (self, target, world);
}
// ── watcher role ───────────────────────────────────────────────────────
[Fact]
public void SetTarget_SubscribesOnTarget_AndReceivesImmediateSnapshot()
{
var (self, target, _) = TwoHosts();
target.SetOrigin(new Vector3(3f, 0f, 0f));
self.TargetManager.SetTarget(0, target.Id, radius: 1.0f, quantum: 0.0);
// Watcher subscribed on the target.
Assert.True(target.TargetManager.VoyeurTable!.ContainsKey(self.Id));
// Immediate Ok snapshot fanned to the watcher's host.
Assert.Single(self.HandleUpdateTargetCalls);
Assert.Equal(TargetStatus.Ok, self.HandleUpdateTargetCalls[0].Status);
Assert.Equal(target.Id, self.HandleUpdateTargetCalls[0].ObjectId);
Assert.Equal(new Vector3(3f, 0f, 0f),
self.HandleUpdateTargetCalls[0].InterpolatedPosition.Frame.Origin);
Assert.Equal(TargetStatus.Ok, self.TargetManager.TargetInfo!.Value.Status);
}
[Fact]
public void SetTarget_Zero_SynthesizesTimedOut_LeavesTargetInfoNull()
{
var (self, _, _) = TwoHosts();
self.TargetManager.SetTarget(contextId: 7, objectId: 0, radius: 1.0f, quantum: 0.0);
Assert.Null(self.TargetManager.TargetInfo);
Assert.Single(self.HandleUpdateTargetCalls);
Assert.Equal(TargetStatus.TimedOut, self.HandleUpdateTargetCalls[0].Status);
Assert.Equal(7u, self.HandleUpdateTargetCalls[0].ContextId);
}
[Fact]
public void ClearTarget_UnsubscribesFromTarget()
{
var (self, target, _) = TwoHosts();
self.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
Assert.True(target.TargetManager.VoyeurTable!.ContainsKey(self.Id));
self.TargetManager.ClearTarget();
Assert.Null(self.TargetManager.TargetInfo);
Assert.False(target.TargetManager.VoyeurTable!.ContainsKey(self.Id));
}
[Fact]
public void ReceiveUpdate_ForWrongObject_Ignored()
{
var (self, target, _) = TwoHosts();
self.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
int before = self.HandleUpdateTargetCalls.Count;
var p = new Position(1u, Vector3.Zero, Quaternion.Identity);
self.TargetManager.ReceiveUpdate(new TargetInfo(999u, TargetStatus.Ok, p, p));
Assert.Equal(before, self.HandleUpdateTargetCalls.Count);
}
[Fact]
public void ReceiveUpdate_ExitWorld_ClearsTarget()
{
var (self, target, _) = TwoHosts();
self.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
var p = new Position(1u, Vector3.Zero, Quaternion.Identity);
self.TargetManager.ReceiveUpdate(new TargetInfo(target.Id, TargetStatus.ExitWorld, p, p));
Assert.Null(self.TargetManager.TargetInfo); // cleared
Assert.False(target.TargetManager.VoyeurTable!.ContainsKey(self.Id)); // unsubscribed
}
[Fact]
public void ReceiveUpdate_ComputesInterpolatedHeadingTowardTarget()
{
var (self, target, _) = TwoHosts();
self.SetOrigin(Vector3.Zero);
self.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
var tp = new Position(1u, new Vector3(0f, 5f, 0f), Quaternion.Identity);
self.TargetManager.ReceiveUpdate(new TargetInfo(target.Id, TargetStatus.Ok, tp, tp));
// self→target interp position (0,5,0) normalized = +Y.
var heading = self.TargetManager.TargetInfo!.Value.InterpolatedHeading;
Assert.Equal(0f, heading.X, 3);
Assert.Equal(1f, heading.Y, 3);
}
[Fact]
public void HandleTargetting_UndefinedTarget_TimesOutAfter10Seconds()
{
var (self, target, _) = TwoHosts();
target.Resolvable = false; // no immediate snapshot → status stays Undefined
self.CurTime = 0;
self.PhysicsTimerTime = 0;
self.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
Assert.Equal(TargetStatus.Undefined, self.TargetManager.TargetInfo!.Value.Status);
self.AdvanceClocks(11.0);
self.TargetManager.HandleTargetting();
Assert.Equal(TargetStatus.TimedOut, self.TargetManager.TargetInfo!.Value.Status);
Assert.Contains(self.HandleUpdateTargetCalls, c => c.Status == TargetStatus.TimedOut);
}
// ── watched role + gates ────────────────────────────────────────────────
[Fact]
public void HandleTargetting_Throttles_Within500ms()
{
var (self, target, _) = TwoHosts();
var w = new TargettedVoyeurInfo(self.Id, radius: 0.1f, quantum: 0.0);
// seed a voyeur directly + advance so a sweep WOULD send if not throttled.
target.TargetManager.AddVoyeur(self.Id, 0.1f, 0.0);
target.SetOrigin(new Vector3(10f, 0f, 0f)); // far past radius
target.PhysicsTimerTime = 0.3; // < 0.5 throttle
int before = self.HandleUpdateTargetCalls.Count;
target.TargetManager.HandleTargetting();
Assert.Equal(before, self.HandleUpdateTargetCalls.Count); // throttled, no sweep
}
[Fact]
public void CheckAndUpdateVoyeur_SendsOnlyPastRadius()
{
var (self, target, _) = TwoHosts();
// self must have a matching target_info for ReceiveUpdate to record.
self.TargetManager.SetTarget(0, target.Id, radius: 1.0f, quantum: 0.0);
int afterSubscribe = self.HandleUpdateTargetCalls.Count; // includes immediate snapshot
// small move → within radius → no send
target.SetOrigin(new Vector3(0.5f, 0f, 0f));
target.AdvanceClocks(1.0);
target.TargetManager.HandleTargetting();
Assert.Equal(afterSubscribe, self.HandleUpdateTargetCalls.Count);
// large move → past radius → send
target.SetOrigin(new Vector3(2f, 0f, 0f));
target.AdvanceClocks(1.0);
target.TargetManager.HandleTargetting();
Assert.Equal(afterSubscribe + 1, self.HandleUpdateTargetCalls.Count);
var last = self.HandleUpdateTargetCalls[^1];
Assert.Equal(TargetStatus.Ok, last.Status);
Assert.Equal(2f, last.InterpolatedPosition.Frame.Origin.X, 3);
}
[Fact]
public void GetInterpolatedPosition_DeadReckonsWithVelocity()
{
var (_, target, _) = TwoHosts();
target.SetOrigin(new Vector3(1f, 2f, 0f));
target.Velocity = new Vector3(10f, 0f, 0f);
var p = target.TargetManager.GetInterpolatedPosition(quantum: 0.5);
Assert.Equal(new Vector3(6f, 2f, 0f), p.Frame.Origin); // 1 + 10*0.5 = 6
}
[Fact]
public void AddVoyeur_Existing_UpdatesInPlace_NoResend()
{
var (self, target, _) = TwoHosts();
target.SetOrigin(Vector3.Zero);
target.TargetManager.AddVoyeur(self.Id, radius: 1.0f, quantum: 0.0);
var voyeur = target.TargetManager.VoyeurTable![self.Id];
Assert.Equal(Vector3.Zero, voyeur.LastSentPosition.Frame.Origin);
target.SetOrigin(new Vector3(5f, 0f, 0f));
target.TargetManager.AddVoyeur(self.Id, radius: 2.5f, quantum: 0.3); // existing → update only
Assert.Equal(2.5f, voyeur.Radius);
Assert.Equal(0.3, voyeur.Quantum);
Assert.Equal(Vector3.Zero, voyeur.LastSentPosition.Frame.Origin); // NOT re-sent
}
[Fact]
public void RemoveVoyeur_RemovesEntry()
{
var (self, target, _) = TwoHosts();
target.TargetManager.AddVoyeur(self.Id, 1.0f, 0.0);
Assert.True(target.TargetManager.RemoveVoyeur(self.Id));
Assert.False(target.TargetManager.VoyeurTable!.ContainsKey(self.Id));
Assert.False(target.TargetManager.RemoveVoyeur(self.Id)); // already gone
}
[Fact]
public void NotifyVoyeurOfEvent_BroadcastsToAll_NoDistanceGate()
{
var world = new Dictionary<uint, R5Host>();
var target = new R5Host(20u, world);
var w1 = new R5Host(10u, world);
var w2 = new R5Host(11u, world);
// both watch the target (each gets a target_info via SetTarget)
w1.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
w2.TargetManager.SetTarget(0, target.Id, 1.0f, 0.0);
int w1Before = w1.HandleUpdateTargetCalls.Count;
int w2Before = w2.HandleUpdateTargetCalls.Count;
target.TargetManager.NotifyVoyeurOfEvent(TargetStatus.Teleported);
Assert.Equal(w1Before + 1, w1.HandleUpdateTargetCalls.Count);
Assert.Equal(w2Before + 1, w2.HandleUpdateTargetCalls.Count);
Assert.Equal(TargetStatus.Teleported, w1.HandleUpdateTargetCalls[^1].Status);
}
// ── full round-trip ─────────────────────────────────────────────────────
[Fact]
public void RoundTrip_WatcherTracksMovingTarget()
{
var (self, target, _) = TwoHosts();
target.SetOrigin(Vector3.Zero);
// Watcher sets target with a 1.0 radius (moveto-style, quantum 0).
self.TargetManager.SetTarget(0, target.Id, radius: 1.0f, quantum: 0.0);
Assert.Single(self.HandleUpdateTargetCalls); // immediate snapshot at (0,0,0)
// Target walks to (3,0,0); its per-tick HandleTargetting notices the
// drift and pushes an update the watcher receives.
target.SetOrigin(new Vector3(3f, 0f, 0f));
target.AdvanceClocks(1.0);
target.TargetManager.HandleTargetting();
Assert.Equal(2, self.HandleUpdateTargetCalls.Count);
Assert.Equal(new Vector3(3f, 0f, 0f),
self.HandleUpdateTargetCalls[^1].InterpolatedPosition.Frame.Origin);
// The watcher's cached target position tracks the target.
Assert.Equal(3f, self.TargetManager.TargetInfo!.Value.InterpolatedPosition.Frame.Origin.X, 3);
}
}

Some files were not shown because too many files have changed in this diff Show more