diff --git a/tests/AcDream.Core.Tests/Physics/Issue108CellarAscentViewerReplayTests.cs b/tests/AcDream.Core.Tests/Physics/Issue108CellarAscentViewerReplayTests.cs new file mode 100644 index 00000000..abd691a8 --- /dev/null +++ b/tests/AcDream.Core.Tests/Physics/Issue108CellarAscentViewerReplayTests.cs @@ -0,0 +1,344 @@ +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; + +/// +/// #108-residual vertical exit-walk harness (2026-06-12): the cellar-ascent +/// grass window. Climbing out of the Holtburg corner-building cellar +/// (0xA9B40174 room, floor z≈90 → 0x0175 staircase/lip → 0x0171 main floor at +/// z=94 = outdoor grade), the upstairs exit door is covered with grass until +/// the eye pops above grade. Punch/seal are exonerated (BR-2 experiment + +/// #117); the grass requires the frame to render through the OUTDOOR root — +/// i.e. the VIEWER-CELL resolution demotes to outdoor/null while the eye is +/// still below terrain grade inside the stairwell. +/// +/// This harness drives the PRODUCTION viewer-resolution stack headlessly per +/// step of a kinematic ascent (the #118 HouseExitWalkReplayTests pattern, +/// turned vertical): +/// player cell — CellTransit.FindCellList on the foot-sphere center (the +/// production controller pick), +/// viewer cell — the PhysicsCameraCollisionProbe.SweepEye chain mirrored +/// verbatim (CameraCornerSealReplayTests provenance): +/// AdjustPosition at the head pivot → ResolveWithTransition +/// (IsViewer|PathClipped|FreeRotate|PerfectClip, 0.3 m +/// viewer_sphere) → fallback 1 AdjustPosition at the sought +/// eye → fallback 2 (player_pos, cell 0). +/// Each step records WHICH branch produced the viewer cell, so a demote +/// self-attributes: +/// A. sweep Ok=false → fallback chain (AdjustPosition's SeenOutside +/// fall-through is an XY-only grid snap — no Z test — so an in-dirt +/// below-grade eye can return an OUTDOOR cell with found=true); +/// B. sweep end-cell pick demotes (exterior-portal straddle + containment +/// miss at the stopped eye); +/// C. the start-cell AdjustPosition at the pivot demotes; +/// D. all healthy here → the bug is upstream (App camera damping / +/// GameWindow TryGetCell consumption). +/// +/// Ascent path: fitted from the live captures (cellar-up-capture*.jsonl band +/// centroids, analyze_108_stairline.py): stairs at x≈153.9 ascending +Y, +/// z = 90.0 (y≤5.7) → 0.836·(y−5.73)+90.25 (stairs) → lip 93.25→94 over +/// y 9.3→10.4 → main floor 94.0. The boom (retail defaults: distance 2.61, +/// pitch 0.291, pivot feet+1.5) trails SOUTH into the stairwell — mid-stairs +/// the desired eye sits beyond the cellar's south wall (y≈4.87) and above its +/// ceiling: in no-cell dirt below grade. Stub terrain (−1000) — the membership +/// pick never reads terrain height (XY-column only), which is exactly the +/// mechanism under test. +/// +/// ── RESULT (2026-06-12): the MEMBERSHIP/VIEWER LAYER IS EXONERATED ────── +/// 0 grass-window steps, 0 sweep failures, 0 fallback branches across boom +/// distance {2.61, 5.0} × damping lag {0, 0.3 m}. The viewer resolves +/// 0x0174 → 0x0175 (eye z 93.65, below grade) → 0x0171 at eye z 94.01 — +/// the viewer enters the main-floor room EXACTLY as the head pops above +/// grade (the stairwell portal sits at grade), matching the user's wording. +/// The handoff's "it is MEMBERSHIP/VIEWER-side" diagnosis is therefore +/// REFUTED for the current pipeline; #108-residual is RENDER-side: the +/// landscape slice clips terrain by 2D NDC planes only ((nx,ny,0,dw) — +/// ClipFrame.cs:178, terrain_modern.vert:173), so terrain BETWEEN the eye +/// and the exit portal (the grade sheet at z≈94, which from a below-grade +/// eye projects into the aperture band at y 9.8–17) paints the doorway. +/// These tests stay as the characterization pin for the healthy layer. +/// +public class Issue108CellarAscentViewerReplayTests +{ + private readonly ITestOutputHelper _out; + public Issue108CellarAscentViewerReplayTests(ITestOutputHelper output) => _out = output; + + private const float ViewerSphereRadius = 0.3f; // retail viewer_sphere (acclient :93314) + private const float PivotHeight = 1.5f; // RetailChaseCamera.PivotHeight + private const float FootRadius = 0.48f; // player foot sphere + private const float BoomDistance = 2.61f; // retail viewer_offset length + private const float BoomPitch = 0.291f; // retail default pitch (16.7°) + private const float GradeZ = 94.0f; // cottage floor == door sill ≈ outdoor terrain grade + + private const uint Lb = 0xA9B40000u; // ConformanceDats.HoltburgLandblock + private const uint CellarRoom = Lb | 0x0174u; // floor z≈90.0 + private const uint MainFloor = Lb | 0x0171u; // z=94.0 + + // ── fixture ───────────────────────────────────────────────────────── + + private static (PhysicsEngine engine, PhysicsDataCache cache, + Dictionary envCells) + BuildEngine(DatCollection dats) + { + var cache = new PhysicsDataCache(); + var engine = new PhysicsEngine { DataCache = cache }; + var envCells = new Dictionary(); + + // Full A9B4 interior set (Issue112MembershipTests.LoadLandblockInteriors + // pattern) — the ascent's pick walk may reach cells outside the corner + // building's 0x016F-0x0175 range. + for (uint low = 0x0100u; low <= 0x01FFu; low++) + { + try { envCells[Lb | low] = ConformanceDats.LoadEnvCell(dats, cache, Lb | low); } + catch { } + } + + // Buildings exactly as production registers them (Issue112MembershipTests. + // RegisterBuildings provenance): portals → BldPortalInfo with sign-extended + // OtherPortalId; landcell id from the building Frame.Origin (retail + // row-major grid). + var lbInfo = dats.Get(Lb | 0xFFFEu); + Assert.NotNull(lbInfo); + foreach (var building in lbInfo!.Buildings) + { + if (building.Portals.Count == 0) continue; + var portals = new List(building.Portals.Count); + foreach (var bp in building.Portals) + portals.Add(new BldPortalInfo( + otherCellId: Lb | (uint)bp.OtherCellId, + otherPortalId: unchecked((short)bp.OtherPortalId), + flags: (ushort)bp.Flags)); + var transform = + Matrix4x4.CreateFromQuaternion(building.Frame.Orientation) * + Matrix4x4.CreateTranslation(building.Frame.Origin); + int gridX = (int)(building.Frame.Origin.X / 24f); + int gridY = (int)(building.Frame.Origin.Y / 24f); + uint landcellLow = (uint)(gridX * 8 + gridY + 1); + cache.CacheBuilding(Lb | landcellLow, portals, transform); + } + + var heights = new byte[81]; + var heightTable = new float[256]; + for (int i = 0; i < 256; i++) heightTable[i] = -1000f; + engine.AddLandblock(Lb, new TerrainSurface(heights, heightTable), + Array.Empty(), Array.Empty(), 0f, 0f); + + return (engine, cache, envCells); + } + + // ── the probe mirror (PhysicsCameraCollisionProbe.SweepEye, verbatim) ── + + private enum ViewerBranch { Sweep, AdjustFallback, NullFallback } + + private sealed record ViewerResolve( + Vector3 Eye, uint ViewerCellId, ViewerBranch Branch, + uint StartCell, bool PivotAdjustFound, ResolveResult Sweep); + + private static ViewerResolve ResolveViewer( + PhysicsEngine engine, Vector3 pivot, Vector3 desiredEye, uint cellId, Vector3 playerPos) + { + // update_viewer (pc:92775): no player cell → snap to player, viewer_cell null. + if (cellId == 0u) + return new ViewerResolve(playerPos, 0u, ViewerBranch.NullFallback, 0u, false, default); + + uint startCell = cellId; + bool pivotFound = false; + if ((cellId & 0xFFFFu) >= 0x0100u) + { + var (pivotCell, found) = engine.AdjustPosition(cellId, pivot); + pivotFound = found; + if (found) startCell = pivotCell; + } + + Vector3 begin = pivot - new Vector3(0f, 0f, ViewerSphereRadius); + Vector3 end = desiredEye - new Vector3(0f, 0f, ViewerSphereRadius); + + var r = 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); + + Vector3 eye = r.Position + new Vector3(0f, 0f, ViewerSphereRadius); + if (r.Ok) + return new ViewerResolve(eye, r.CellId, ViewerBranch.Sweep, startCell, pivotFound, r); + + var (eyeCell, eyeFound) = engine.AdjustPosition(cellId, desiredEye); + if (eyeFound) + return new ViewerResolve(desiredEye, eyeCell, ViewerBranch.AdjustFallback, startCell, pivotFound, r); + + return new ViewerResolve(playerPos, 0u, ViewerBranch.NullFallback, startCell, pivotFound, r); + } + + // ── the ascent ────────────────────────────────────────────────────── + + /// Stair-line feet Z for a path y (fitted from the capture bands). + private static float FeetZ(float y) + { + if (y < 5.73f) return 90.0f; + if (y < 9.30f) return MathF.Min(90.25f + 0.836f * (y - 5.73f), 93.25f); + if (y < 10.40f) return 93.25f + (y - 9.30f) * (0.75f / 1.10f); + return 94.0f; + } + + private sealed record Step( + int Index, Vector3 Feet, uint PlayerCell, + ViewerResolve Viewer, uint EyeContainedIn, bool EyeBelowGrade) + { + public bool ViewerOutdoorOrNull => + Viewer.ViewerCellId == 0u || (Viewer.ViewerCellId & 0xFFFFu) < 0x0100u; + } + + private List? RunAscent(float boomDistance, float pathLagMeters) + { + var datDir = ConformanceDats.ResolveDatDir(); + if (datDir is null) { _out.WriteLine("SKIP: dats unavailable"); return null; } + + using var dats = new DatCollection(datDir, DatAccessType.Read); + var (engine, _, envCells) = BuildEngine(dats); + + const float yStart = 5.2f, yEnd = 16.0f; + const float stepLen = 0.02f; // 2 cm/frame ≈ 1.2 m/s at 60 Hz + var fwd = new Vector3(0f, 1f, 0f); // facing up the stairs / at the exit door + float cosP = MathF.Cos(BoomPitch), sinP = MathF.Sin(BoomPitch); + + // Stairs run at x≈153.9; past the lip the real walk line bends to the + // exit-door approach at x≈155 (corner-seal capture S1: player + // (154.93, 16.45)) — walking straight north at 153.9 ends in the wall + // beside the 0x0170 doorway, which a live player cannot do. + static float FeetX(float y) => + y <= 10.4f ? 153.9f + : y >= 14.0f ? 155.0f + : 153.9f + (y - 10.4f) / (14.0f - 10.4f) * (155.0f - 153.9f); + + var steps = new List(); + uint playerCell = CellarRoom; + int count = (int)MathF.Round((yEnd - yStart) / stepLen); + + for (int i = 0; i <= count; i++) + { + float y = yStart + i * stepLen; + var feet = new Vector3(FeetX(y), y, FeetZ(y)); + + // production controller pick: foot-sphere CENTER, seeded with the carried cell + playerCell = CellTransit.FindCellList( + engine.DataCache!, feet + new Vector3(0f, 0f, FootRadius), FootRadius, playerCell); + + // boom target — optionally computed from a lagged path point to model the + // exponential damping trail (≈0.27 m at climb speed; 0 = converged target) + float yBoom = MathF.Max(yStart, y - pathLagMeters); + var boomFeet = new Vector3(FeetX(yBoom), yBoom, FeetZ(yBoom)); + var pivot = feet + new Vector3(0f, 0f, PivotHeight); + var boomPivot = boomFeet + new Vector3(0f, 0f, PivotHeight); + var desiredEye = boomPivot - fwd * (boomDistance * cosP) + + new Vector3(0f, 0f, boomDistance * sinP); + + var viewer = ResolveViewer(engine, pivot, desiredEye, playerCell, feet); + + uint containedIn = 0u; + foreach (var (id, env) in envCells) + if (env.PointInCell(viewer.Eye)) { containedIn = id; break; } + + steps.Add(new Step(i, feet, playerCell, viewer, + containedIn, viewer.Eye.Z < GradeZ - 0.05f)); + } + + return steps; + } + + private void DumpStep(Step s) + { + var v = s.Viewer; + string line = FormattableString.Invariant( + $"step={s.Index,3} feet=({s.Feet.X:F2},{s.Feet.Y:F2},{s.Feet.Z:F2}) pCell=0x{s.PlayerCell & 0xFFFFu:X4} start=0x{v.StartCell & 0xFFFFu:X4}{(v.PivotAdjustFound ? "" : "!")} branch={v.Branch} ok={v.Sweep.Ok} eye=({v.Eye.X:F2},{v.Eye.Y:F2},{v.Eye.Z:F2}) viewer=0x{v.ViewerCellId & 0xFFFFu:X4} eyeIn=0x{s.EyeContainedIn & 0xFFFFu:X4} belowGrade={(s.EyeBelowGrade ? "Y" : "n")}"); + if (s.EyeBelowGrade && s.ViewerOutdoorOrNull) line += " << GRASS-WINDOW"; + _out.WriteLine(line); + } + + // ── diagnostics + pins ────────────────────────────────────────────── + + /// + /// Full per-step table of the ascent at retail boom defaults (converged + /// boom, no lag). Read this first — the GRASS-WINDOW marks name the steps + /// where the production stack resolves an outdoor/null viewer with the eye + /// below grade, and the branch column attributes the demote site. + /// + [Fact] + public void Diagnostic_CellarAscent_PerStepTable() + { + var steps = RunAscent(BoomDistance, pathLagMeters: 0f); + if (steps is null) return; + + uint lastPlayer = 0; uint lastViewer = 0xFFFFFFFFu; var lastBranch = (ViewerBranch)(-1); + int suspicious = 0; + foreach (var s in steps) + { + bool grass = s.EyeBelowGrade && s.ViewerOutdoorOrNull; + if (grass) suspicious++; + if (s.PlayerCell != lastPlayer || s.Viewer.ViewerCellId != lastViewer + || s.Viewer.Branch != lastBranch || grass || s.Index % 50 == 0) + DumpStep(s); + lastPlayer = s.PlayerCell; lastViewer = s.Viewer.ViewerCellId; lastBranch = s.Viewer.Branch; + } + _out.WriteLine(FormattableString.Invariant( + $"--- {suspicious}/{steps.Count} steps in the grass window (viewer outdoor/null while eye below grade) ---")); + } + + /// Boom-distance + damping-lag sweep: how wide is the window across poses? + [Fact] + public void Diagnostic_CellarAscent_PoseSweep() + { + foreach (float dist in new[] { 2.61f, 5.0f }) + foreach (float lag in new[] { 0f, 0.30f }) + { + var steps = RunAscent(dist, lag); + if (steps is null) return; + int grass = steps.FindAll(s => s.EyeBelowGrade && s.ViewerOutdoorOrNull).Count; + int okFalse = steps.FindAll(s => !s.Viewer.Sweep.Ok).Count; + int fb = steps.FindAll(s => s.Viewer.Branch != ViewerBranch.Sweep).Count; + _out.WriteLine(FormattableString.Invariant( + $"dist={dist:F2} lag={lag:F2}: grassWindow={grass}/{steps.Count} sweepOkFalse={okFalse} fallbackBranch={fb}")); + } + } + + /// + /// THE PIN: while the eye is below terrain grade on the cellar ascent, the + /// viewer must resolve INTERIOR — an outdoor/null viewer cell roots the + /// frame at the landscape and sweeps grass across the exit door (#108). + /// Retail's viewer rides the stairwell cells here (the cellar camera works + /// in retail); below grade inside the building footprint there is no + /// legitimate outdoor viewer. + /// + [Fact] + public void CellarAscent_ViewerStaysInterior_WhileEyeBelowGrade() + { + var steps = RunAscent(BoomDistance, pathLagMeters: 0f); + if (steps is null) return; + + var failures = steps.FindAll(s => s.EyeBelowGrade && s.ViewerOutdoorOrNull); + if (failures.Count > 0) + { + _out.WriteLine($"--- {failures.Count} grass-window steps ---"); + foreach (var s in failures) DumpStep(s); + } + Assert.True(failures.Count == 0, + $"{failures.Count}/{steps.Count} ascent steps resolve an outdoor/null viewer cell while the eye " + + "is below grade — the #108 grass window (see output for the branch attribution)"); + } +}