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

#108-residual apparatus: vertical cellar-ascent viewer harness - membership/viewer layer EXONERATED

Browse source 
The handoff's 'eye-below-grade membership demote' diagnosis is REFUTED.
The harness drives the production stack headlessly per step of the
A9B4 corner-building cellar ascent (0x0174 -> 0x0175 -> 0x0171, path
fitted from the cellar-up live captures): FindCellList on the
foot-sphere center for the player pick + the PhysicsCameraCollisionProbe
SweepEye chain mirrored verbatim (AdjustPosition at pivot ->
ResolveWithTransition IsViewer|PathClipped|FreeRotate|PerfectClip ->
both fallbacks) with per-step branch attribution.

Result: 0 outdoor/null viewer resolutions while the eye is below grade,
0 sweep failures, 0 fallback branches, across boom distance {2.61, 5}
x damping lag {0, 0.3 m}. The viewer enters the main-floor room at eye
z 94.01 - exactly as the head pops above grade (the stairwell portal
sits AT grade), matching the user's report wording. The root is
INTERIOR for the whole grass window; #108-residual is render-side
(fix in the next commit). Tests stay as the healthy-layer
characterization pin.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-06-12 22:05:06 +02:00
parent bf965000da
commit 007af1391c
1 changed files with 344 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

344
tests/AcDream.Core.Tests/Physics/Issue108CellarAscentViewerReplayTests.cs Normal file
View file

@ -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;
/// <summary>
/// #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.
/// </summary>
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<uint, AcDream.Core.World.Cells.EnvCell> envCells)
BuildEngine(DatCollection dats)
{
var cache = new PhysicsDataCache();
var engine = new PhysicsEngine { DataCache = cache };
var envCells = new Dictionary<uint, AcDream.Core.World.Cells.EnvCell>();
// 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<DatReaderWriter.DBObjs.LandBlockInfo>(Lb | 0xFFFEu);
Assert.NotNull(lbInfo);
foreach (var building in lbInfo!.Buildings)
{
if (building.Portals.Count == 0) continue;
var portals = new List<BldPortalInfo>(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<CellSurface>(), Array.Empty<PortalPlane>(), 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 ──────────────────────────────────────────────────────
/// <summary>Stair-line feet Z for a path y (fitted from the capture bands).</summary>
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<Step>? 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<Step>();
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 ──────────────────────────────────────────────
/// <summary>
/// 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.
/// </summary>
[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) ---"));
}
/// <summary>Boom-distance + damping-lag sweep: how wide is the window across poses?</summary>
[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}"));
}
}
/// <summary>
/// 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.
/// </summary>
[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)");
}
}