diff --git a/docs/ISSUES.md b/docs/ISSUES.md index d96a360..bae6f7c 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -282,29 +282,77 @@ slopes shows matching shading. --- -## #83 — Walking up stairs broken +## #83 — Indoor multi-Z walking broken (cellars, 2nd floors, intermittent falling-stuck) -**Status:** OPEN -**Severity:** HIGH (blocks vertical indoor traversal) +**Status:** OPEN — foundation work landed 2026-05-19, root-cause fix deferred to a follow-up investigation phase +**Severity:** HIGH (blocks vertical indoor traversal + degrades single-floor cases) **Filed:** 2026-05-19 -**Component:** physics, movement +**Component:** physics, movement, resolver -**Description:** When the player tries to walk up stairs inside a -building, movement is broken — gets stuck, gets bounced, or fails to -ascend. +**Description:** Walking UP stairs in single-floor houses works +(grounded step-up routes through retail-faithful `BSPQuery.FindWalkableInternal` +via `StepSphereDown`). Walking DOWN into cellars fails ("ground blocking" — +can't descend). Walking on 2nd floors works partially but intermittently +gets stuck in the falling animation. "Phantom collisions" / invisible +obstacles in rooms persist. The original title "Walking up stairs broken" +was misleading per user's clarification 2026-05-19. -**Root cause / status:** The retail physics has explicit step-up logic -(`CPhysicsObj::step_up` etc.) ported into `PhysicsEngine` for outdoor -terrain ramps. For indoor stairs (EnvCell CellStruct geometry composed -of polygons), the step-up resolver may not be examining cell BSP -correctly, OR cell BSP and cell mesh disagree on stair Z values. +**Partial fix landed 2026-05-19 (6 commits `ff548b9` → `f845b22`).** +Foundation work: extended `BSPQuery.FindWalkableInternal` to expose the +hit polygon's dictionary key id; added thin public wrapper +`BSPQuery.FindWalkableSphere` over the existing retail-faithful BSP +walkable-finder (acclient_2013_pseudo_c.txt:326211 / :326793); refactored +`Transition.TryFindIndoorWalkablePlane` to route through that wrapper +instead of its Phase-2 linear first-match XY scan; added `[indoor-walkable]` +runtime-toggleable probe line for diagnostic visibility. 5 new unit tests ++ 1 integration test, 9 pre-existing IndoorWalkablePlane tests updated +to the new signature. -**Files:** -- `src/AcDream.Core/Physics/PhysicsEngine.cs` -- `src/AcDream.Core/Physics/TransitionTypes.cs` (cell BSP query path). +**Foundation work did NOT fix the user-reported bugs.** Visual verification +2026-05-19: cellar descent FAIL, 2nd-floor walking FAIL (intermittent +falling-stuck), single-floor cottage REGRESSED to intermittent falling-stuck +(was stable before), phantom collisions PERSIST. The probe captured 1443 +MISS / 2 HIT over 1445 indoor-walkable calls — the BSP walker correctly +rejects the foot-sphere-tangent-to-floor case (sphere center is exactly +at `floorZ + radius` when grounded, so `PolygonHitsSpherePrecise` fails +the `|dist| > radius - epsilon` check by ~0.0002). -**Acceptance:** Walking forward at the base of an inn stairwell ascends -to the second floor without getting stuck. +**Root cause (deeper than originally diagnosed):** `Transition.TryFindIndoorWalkablePlane` +fundamentally exists as a Phase 2 commit `eb0f772` stop-gap to synthesize +a ContactPlane every frame when the indoor BSP returns OK. Retail doesn't +do this — retail RETAINS the previous frame's `ContactPlane` when the +collision dispatcher says "no collision." There is no retail analog of +`find_walkable` being called as a standing-still query — retail's +`find_walkable` only runs inside a downward sphere sweep +(`step_sphere_down`), where the sphere is moving and the overlap test +is meaningful. In our `TryFindIndoorWalkablePlane` flow, the sphere is +tangent (grounded), not moving — the algorithm correctly returns "no +overlap." The single-floor cottage worked previously because the OLD +linear scan ignored Z and falsely returned HIT for any XY-overlapping +walkable; the new BSP-walker correctly identifies "no overlap" and +falls through to the outdoor terrain backstop, which only happens to +produce sensible Z for single-floor outdoor-adjacent cases. + +**Files in the foundation work:** +- `src/AcDream.Core/Physics/BSPQuery.cs` — `FindWalkableInternal` signature extension, new `FindWalkableSphere` public wrapper +- `src/AcDream.Core/Physics/TransitionTypes.cs` — `TryFindIndoorWalkablePlane` refactor, `PointInPolygonXY` deletion, `[indoor-walkable]` probe +- `tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs` — 4 new unit tests +- `tests/AcDream.Core.Tests/Physics/TransitionTypesTests.cs` — new integration test +- `tests/AcDream.Core.Tests/Physics/IndoorWalkablePlaneTests.cs` — 9 tests updated to new signature + +**Next investigation phase (deferred):** Port retail's `ContactPlane` retention +mechanism so the resolver retains the previous frame's contact plane when +the BSP says "no collision," instead of re-synthesizing it per frame. The +proper fix likely eliminates `TryFindIndoorWalkablePlane` entirely. Needs +deep investigation of retail's `CTransition::transitional_insert` / +`CPhysicsObj::transition` / `LastKnownContactPlane` interactions. Foundation +work (BSP walker + probe + tests) remains useful regardless of approach. + +**Acceptance:** Walk down stairs into a cellar without getting stuck. +Walk on a 2nd floor without intermittent falling-stuck. Single-floor +cottage walking remains stable (no regression). + +**Handoff:** [`docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md`](research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md). --- diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 9d5541b..0fc0d30 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1,6 +1,6 @@ # acdream — strategic roadmap -**Status:** Living document. Updated 2026-05-19. **Between phases.** **Since the last header update:** Indoor cell rendering Phase 1 (diagnostics) + Phase 2 (fix) shipped — root cause was a one-line WB bug at `ObjectMeshManager.cs:1223` (blind `TryGet` on GfxObj-prefixed stab ids threw `ArgumentOutOfRangeException` which WB's outer catch silently swallowed, causing 26/123 Holtburg cells to fail upload). Identified via diagnostic chain (5 `[indoor-*]` probes + a `ContinueWith` exception surfacer + a `ConsoleErrorLogger` injected into WB), fixed with a Setup-prefix guard. User visually confirmed floors render. Surfaced 9 pre-existing indoor bugs filed in `docs/ISSUES.md`. **Earlier:** C.1.5b shipped (issue #56 per-part transforms for multi-emitter PES + `EntityScriptActivator` extended to dat-hydrated EnvCell statics & exterior stabs — portal swirl, inn fireplace flames, cottage chimney smoke, spell-cast particles all match retail). post-A.5 polish completed (#52 lifestone, #54 JobKind, #53 Tier 1 cache); N.6 slice 1 shipped (gpu_us fix + radius=12 perf baseline, conclusion CPU dominates GPU 30–50×); C.1.5a shipped (portal PES wiring; surfaced #56 → resolved in C.1.5b). +**Status:** Living document. Updated 2026-05-19. **Between phases.** **Since the last header update:** Indoor walkable-plane BSP port FOUNDATION shipped (6 commits, `ff548b9` → `f845b22`) but visual verification failed — cellar descent, 2nd-floor walking, single-floor cottage regressions all confirm the shipped fix doesn't address the user-reported indoor bugs. Root cause now diagnosed as deeper than originally thought: `TryFindIndoorWalkablePlane` exists as a Phase 2 stop-gap that retail doesn't have an analog for. Retail retains ContactPlane state across frames; we re-synthesize per frame. Foundation work (BSP walker + probe + tests) remains useful; next phase needs to port retail's ContactPlane retention mechanism and likely eliminate `TryFindIndoorWalkablePlane` entirely. Handoff: [`docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md`](../research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md). ISSUES #83 remains OPEN with deeper diagnosis. **Earlier:** Indoor cell rendering Phase 1 (diagnostics) + Phase 2 (fix) shipped — root cause was a one-line WB bug at `ObjectMeshManager.cs:1223` (blind `TryGet` on GfxObj-prefixed stab ids threw `ArgumentOutOfRangeException` which WB's outer catch silently swallowed, causing 26/123 Holtburg cells to fail upload). Identified via diagnostic chain (5 `[indoor-*]` probes + a `ContinueWith` exception surfacer + a `ConsoleErrorLogger` injected into WB), fixed with a Setup-prefix guard. User visually confirmed floors render. Surfaced 9 pre-existing indoor bugs filed in `docs/ISSUES.md`. **Earlier:** C.1.5b shipped (issue #56 per-part transforms for multi-emitter PES + `EntityScriptActivator` extended to dat-hydrated EnvCell statics & exterior stabs — portal swirl, inn fireplace flames, cottage chimney smoke, spell-cast particles all match retail). post-A.5 polish completed (#52 lifestone, #54 JobKind, #53 Tier 1 cache); N.6 slice 1 shipped (gpu_us fix + radius=12 perf baseline, conclusion CPU dominates GPU 30–50×); C.1.5a shipped (portal PES wiring; surfaced #56 → resolved in C.1.5b). **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file. --- diff --git a/docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md b/docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md new file mode 100644 index 0000000..b9fc643 --- /dev/null +++ b/docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md @@ -0,0 +1,187 @@ +# Indoor walkable-plane BSP port — partial-ship handoff (2026-05-19) + +**Outcome:** Foundation shipped (6 commits). Visual verification FAILED. User-reported bugs (cellar descent, 2nd-floor walking, phantom collisions) remain unresolved. Root cause now diagnosed deeper than originally thought; next phase needs to port retail's `ContactPlane` retention mechanism. Foundation work (BSP walker + probe + tests) is useful regardless of the next approach. + +--- + +## TL;DR + +I diagnosed the wrong root cause initially. I assumed `TryFindIndoorWalkablePlane`'s linear first-match XY scan picking the wrong polygon was the bug, and built a retail-faithful BSP-walker replacement (`BSPQuery.FindWalkableSphere` wrapper over the existing `FindWalkableInternal` port of `BSPNODE::find_walkable` + `BSPLEAF::find_walkable`). The BSP walker is correct, but it returns MISS for the standing-grounded case (foot sphere tangent to floor → `PolygonHitsSpherePrecise` correctly rejects tangent contact by ~0.0002 epsilon). + +The actual root cause: **`TryFindIndoorWalkablePlane` shouldn't exist at all**. It was added as a Phase 2 commit `eb0f772` stop-gap to synthesize a `ContactPlane` every frame when the indoor BSP returns OK. Retail doesn't do this — retail RETAINS the previous frame's `ContactPlane` when the collision dispatcher reports no collision. There is no retail analog of `find_walkable` as a standing-still query. `find_walkable` only runs inside a downward sphere sweep (`step_sphere_down`), where the sphere is moving and the overlap test is meaningful. + +--- + +## What shipped (foundation) + +6 commits, `ff548b9` → `f845b22`. `dotnet build -c Debug` clean; 8 pre-existing test failures unchanged baseline; 5 new tests + 9 updated existing tests all pass. + +| # | SHA | Subject | +|---|---|---| +| 1 | `ff548b9` | `refactor(physics): expose hitPolyId from FindWalkableInternal` | +| 2 | `7f55e14` | `feat(physics): add BSPQuery.FindWalkableSphere wrapper` (+ 4 unit tests) | +| 3 | `86ecdf9` | `fix(physics): tighten FindWalkableSphere test assertions + header` (code review fix) | +| 4 | `91b29d1` | `fix(physics): route indoor walkable-plane synthesis through retail BSP walker` | +| 5 | `7c516ed` | `fix(physics): document adjustedCenter discard + restore wall-poly test` (code review fix) | +| 6 | `f845b22` | `feat(physics): add [indoor-walkable] probe line` | + +**Files touched:** +- `src/AcDream.Core/Physics/BSPQuery.cs` — `FindWalkableInternal` gained `ref ushort hitPolyId`; new public `FindWalkableSphere` wrapper. +- `src/AcDream.Core/Physics/TransitionTypes.cs` — `TryFindIndoorWalkablePlane` refactored from `static` linear scan to instance method routing through `FindWalkableSphere` with `WalkableAllowance` save/restore. `PointInPolygonXY` deleted. `[indoor-walkable]` probe added at the `FindEnvCollisions` callsite. +- `tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs` — 4 new `FindWalkableSphere` unit tests. +- `tests/AcDream.Core.Tests/Physics/TransitionTypesTests.cs` — new file, integration test for two-overlapping-floors + WalkableAllowance preservation. +- `tests/AcDream.Core.Tests/Physics/IndoorWalkablePlaneTests.cs` — 9 tests updated to new instance-method + sphereRadius signature with BSP fixtures; 2 `PointInPolygonXY` tests deleted; 1 new wall-poly integration test. + +--- + +## Visual verification — FAIL (user-driven, 2026-05-19) + +Launch flags: `ACDREAM_DEVTOOLS=1`, `ACDREAM_PROBE_INDOOR_BSP=1`. Log: `launch-walkable-fix-6.log` (latest run). + +User report verbatim: +> Cant walk down to the cellar. Looks like ground is blocking. +> I get stuck sometimes in a falling animation at random places. +> When I walk up on second floors. I get stuck sometimes on random places in falling animation. +> Lightning is still broken. +> Get phantom collison in rooms. +> NO change + +Result against acceptance scenarios: + +| Scenario | Pre-ship | Post-ship | Outcome | +|---|---|---|---| +| Cellar descent | "ground blocking" | "ground blocking" | **FAIL** — no change | +| 2nd-floor walking | "snaps back / invisible obstacles" | "intermittent falling-stuck" | **FAIL** — different symptom, still broken | +| Single-floor cottage walking | stable | "intermittent falling-stuck at random spots" | **REGRESSION** — degraded from stable to unstable | +| Phantom collisions in rooms | present | present | **PERSIST** | +| Indoor lightning (#79/#80/#81/#82) | broken | broken | unchanged (out of scope for this phase) | + +--- + +## Probe evidence (from launch 1) + +`[indoor-walkable]` probe captured 1445 calls in a Holtburg-area session. **1443 MISS / 2 HIT.** + +Sample HIT line: +``` +[indoor-walkable] cell=0xA9B40150 wpos=(132.258,16.524,94.480) probe=0.50 result=HIT poly=0x0000 wn=(0.000,0.000,1.000) wD=-94.020 dz=+0.46 +``` + +Sample MISS line: +``` +[indoor-walkable] cell=0xA9B40150 wpos=(132.258,16.524,94.500) probe=0.50 result=MISS +``` + +The 20mm Z oscillation between `94.480` (HIT) and `94.500` (MISS) is the smoking gun: +- World physics floor (after +0.02f cell-origin Z-bump in `PhysicsDataCache.CacheCellStruct`) is at `Z=94.020`. +- When foot center is at `Z=94.500` (= floor + radius), distance to plane = `0.48` = sphere radius. `PolygonHitsSpherePrecise` checks `|dist| > radius - epsilon` (line 117 of BSPQuery.cs). `0.48 > 0.4798` → **rejected by ~0.0002**. +- When foot center is at `Z=94.480` (= floor + 0.46), distance = `0.46 < 0.4798` → accepted, HIT. +- The resolver oscillates between these two positions as the indoor walkable plane and the outdoor terrain backstop alternate as the contact source. + +--- + +## Why the fix doesn't work — deeper diagnosis + +`TryFindIndoorWalkablePlane` exists only as a Phase 2 stop-gap (commit `eb0f772`). It was added because the indoor BSP collision branch in `FindEnvCollisions` returns OK when the player is grounded standing still, but the resolver then needed a `ContactPlane` to feed `ValidateWalkable`. Without a synthesized indoor plane, the code fell through to outdoor terrain backstop, which is BELOW the indoor floor by `+0.02f`, marking the player as floating → falling-stuck. The Phase 2 fix synthesized a plane from `cellPhysics.Resolved` via a linear XY scan. + +My Task 3 refactor swapped that linear scan for the retail-faithful BSP walker (`BSPQuery.FindWalkableInternal`). The BSP walker is correct — it implements `BSPNODE::find_walkable` + `BSPLEAF::find_walkable` faithfully. But in retail, this function is called from `BSPTREE::step_sphere_down` inside a movement sweep, where the sphere is moving downward. `walkable_hits_sphere` requires the sphere to overlap the plane (`|dist| < radius - eps`), which is satisfied during the sweep because the moving sphere penetrates the plane mid-sweep. In our standing-grounded use case, the sphere is tangent (foot resting on floor), not penetrating → no overlap → no walkable found → MISS. + +**Retail's actual flow for the standing-grounded case:** + +1. Player at rest on floor. ContactPlane retained from previous frame. +2. Frame tick. Gravity + movement applied. +3. `CTransition::transitional_insert` runs. +4. `find_collisions` Path 5 (Contact branch): `sphere_intersects_poly` test. + - If the sphere penetrates the floor (gravity moved it slightly down), `step_sphere_up` runs → `step_down` → `step_sphere_down` → `find_walkable` → finds the floor → `adjust_sphere_to_plane` snaps it up to tangent → ContactPlane updated. + - If the sphere does NOT penetrate (still tangent from last frame), Path 5 returns OK. **ContactPlane is NOT recomputed — it's retained from last frame.** +5. Player walks horizontally. Same as above — ContactPlane persists. + +Our acdream code: +- Per-frame `FindEnvCollisions` calls indoor BSP `FindCollisions`. +- Indoor BSP returns OK (no collision). +- We call `TryFindIndoorWalkablePlane` to RECOMPUTE the ContactPlane from scratch. This is the WRONG behavior — retail doesn't recompute. +- The recomputation fails (BSP walker can't handle tangent sphere) or succeeds with a slightly-off plane (linear scan returning the wrong polygon's Z). +- Either way: the ContactPlane is unstable frame-to-frame → resolver state oscillates → player gets stuck in falling animation. + +--- + +## Recommended next phase: ContactPlane retention + +Port retail's `ContactPlane` retention so the resolver retains the previous frame's plane when the BSP says "no collision," instead of re-synthesizing every frame. + +**Investigation targets (retail decomp):** +- `CTransition::transitional_insert` (acclient_2013_pseudo_c.txt:273137) — the main per-frame resolver entry. Note line 273165: `if (edi != OK_TS) this->sphere_path.neg_poly_hit = 0;` — only mutates state on non-OK results. +- `CPhysicsObj::transition` family — where `LastKnownContactPlane` is read/written. +- Search the decomp for `last_known_contact_plane` and `contact_plane_valid` to map the full lifecycle. +- `CTransition::check_walkable` (referenced at line 273202) — possibly involved in walkable persistence. + +**Likely shape of the fix:** +- In `Transition.FindEnvCollisions` (TransitionTypes.cs:1262), when indoor BSP returns OK, DO NOT call `TryFindIndoorWalkablePlane`. Instead, retain the existing `CollisionInfo.ContactPlane` (which was set by the previous frame's step-up or step-down). +- Only update the ContactPlane when an actual collision/step event occurs (Path 4 land, Path 5 step-up-success, Path 3 step-down-success). +- Outdoor terrain backstop remains for the outdoor case but is gated on `!IsIndoor(cellId)`. + +**Foundation work to keep:** +- `BSPQuery.FindWalkableSphere` wrapper — useful for any future "find a walkable plane indoors" query (e.g., spawn-placement, teleport-target verification). +- `FindWalkableInternal`'s `hitPolyId` ref param — same. +- `[indoor-walkable]` probe — keep, but expect it to fire less often once retention is in place (only when the sphere is actually penetrating). +- All 5 new tests + 9 updated tests — they verify the BSP walker's correctness, which is unchanged in the next phase. + +**Foundation work to delete (or refactor):** +- `Transition.TryFindIndoorWalkablePlane` — likely deleted entirely, OR kept as an out-of-band synthesis path for edge cases (initial spawn, cell-id promotion mid-frame) but no longer called per-frame from `FindEnvCollisions`. +- `INDOOR_WALKABLE_PROBE_DISTANCE` constant — deleted with `TryFindIndoorWalkablePlane`, or kept for the out-of-band use case. + +--- + +## What NOT to do + +- **Do not** add a sphere-offset hack to make `PolygonHitsSpherePrecise` accept tangent contact. That mis-aligns acdream's overlap semantics with retail's. The right answer is to not call `find_walkable` in the standing-still case at all. +- **Do not** revert the 6 foundation commits. They are correct retail-faithful ports; the BSP walker is needed for legitimate use cases (just not the one we wired it to). +- **Do not** widen the +0.02f Z-bump or try to compensate for it in the resolver. The bump is a render concern; it should remain transparent to physics. The bug is in the per-frame ContactPlane recompute, not the bump itself. + +--- + +## Quick reference for the next-session implementer + +**Spec to read first (this phase's, for context — but don't re-execute it):** +- `docs/superpowers/specs/2026-05-19-indoor-walkable-plane-bsp-port-design.md` (committed `165f67a`) +- `docs/superpowers/plans/2026-05-19-indoor-walkable-plane-bsp-port.md` (committed `e62d076`) + +**Code anchors:** +- [`src/AcDream.Core/Physics/TransitionTypes.cs:1262`](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1262) — `FindEnvCollisions` indoor branch. +- [`src/AcDream.Core/Physics/TransitionTypes.cs:1192`](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1192) — `TryFindIndoorWalkablePlane` (the thing to likely delete in the next phase). +- [`src/AcDream.Core/Physics/CollisionInfo`](../../src/AcDream.Core/Physics/) — search for `ContactPlane` write sites to map who currently sets it. +- [`src/AcDream.Core/Physics/SpherePath`](../../src/AcDream.Core/Physics/) — `LastKnownContactPlane`-style fields if any exist. + +**Retail decomp anchors:** +- `docs/research/named-retail/acclient_2013_pseudo_c.txt:273099` — `CTransition::step_up`. +- `docs/research/named-retail/acclient_2013_pseudo_c.txt:273137` — `CTransition::transitional_insert`. +- `docs/research/named-retail/acclient_2013_pseudo_c.txt:323565` — `BSPTREE::step_sphere_up`. +- `docs/research/named-retail/acclient_2013_pseudo_c.txt:326793` — `BSPLEAF::find_walkable` (already ported, behavior verified). + +**Visual verification scenarios (re-use for the next phase):** +1. Cellar descent (the primary failing scenario) +2. 2nd-floor walking +3. Single-floor cottage (regression check — must NOT degrade) +4. Phantom collisions (cascade check — if root cause is fixed, these should improve) + +**Launch command:** +```powershell +$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" +$env:ACDREAM_LIVE = "1" +$env:ACDREAM_TEST_HOST = "127.0.0.1" +$env:ACDREAM_TEST_PORT = "9000" +$env:ACDREAM_TEST_USER = "testaccount" +$env:ACDREAM_TEST_PASS = "testpassword" +$env:ACDREAM_DEVTOOLS = "1" +$env:ACDREAM_PROBE_INDOOR_BSP = "1" +dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "launch-next-phase.log" +``` + +--- + +## Session lessons (for future Claude) + +1. **Brainstorm a hypothesis-test before a full spec.** I diagnosed the wrong root cause and built 6 commits on it. A small spike (add the probe FIRST, capture a log, look at it before designing the fix) would have surfaced the 99.9% MISS rate immediately and pointed at the deeper issue. +2. **Tangent contact is the dominant grounded case.** Any test fixture designed to exercise `walkable_hits_sphere` MUST include the tangent case (`dist == radius`), not just penetrating cases. My unit tests used Z=0.4 with radius=0.48 (overlap = 0.4 < 0.4798, passes easily) — comfortable but unrepresentative. +3. **`find_walkable` is a sweep query, not a query.** It's only meaningful when called from `step_sphere_down`. Any caller using it as "stand here, find my floor" is misusing the algorithm. Retail doesn't have such a caller because retail retains ContactPlane across frames. +4. **The +0.02f cell-origin Z-bump is a render artifact bleeding into physics.** It creates a 20mm offset between visual and physics floors. This is fine when the resolver retains state but breaks when the resolver re-computes every frame. The bump is not the root cause but it amplifies the oscillation symptom.