acdream/docs/research/2026-05-24-door-collision-task7-shipped-but-bug-remains.md

Door collision — Task 7 shipped, partial fix, deeper bug remains

Date: 2026-05-24 (evening, continuation of door collision investigation) Branch: claude/strange-albattani-3fc83c Status: A6.P4 architecture is correct. Multi-part registration works. The Holtburg door bug PARTIALLY fixed — center blocks, but off-center and inside-out still walk through. Root cause is downstream in the engine's grounded BSP collision path (Path 5 + step-up), NOT in the multi-part registration we just shipped.

---

TL;DR

Three commits shipped (composable foundation):

SHA	Title	What it does
e1d94d7	dat-inspection test	Confirmed door part 0x010044B5 has full 1.9×0.26×2.5 m BSP slab (6 Landblock polys). Hypothesis A from prior handoff was wrong.
3b7dc46	GetNearbyObjects dedup fix	Changed HashSet<uint> (entityId) → HashSet<ShadowEntry>. Multi-part shapes no longer silently dropped.
ca9341c	Task 7 live wiring	RegisterLiveEntityCollision uses ShadowShapeBuilder.FromSetup + RegisterMultiPart. Doors now register cyl+bsp instead of just cyl.

Live verification (visual user test):

Scenario	Result
Dead center, walk into closed door (outside)	✅ Blocks
50 cm off-center, walk into closed door (outside)	❌ Walks through
Inside walking out (closed door)	❌ Walks through
Use door → swing → walk through	✅ Works (ETHEREAL flip path)

Probe-instrumented live capture confirms multi-part registration works:

• Every door spawn shows [entity-source] shapes=cyl1+bsp1 — both shapes register.
• BSP part 0x010044B5 is visited 135 times for a single door at player approaches as close as distXY=0.415 m.
• cacheHit=True for every visit — the cache is populated.
• BUT: zero [resolve-bldg] attributions for the BSP shape (all 19 attributed hits show gfxObj=0x00000000 = the Cylinder shape).

So the BSP is being QUERIED but never produces an attributed hit. The sphere walks through despite the BSP geometry being present and visited.

---

What's in the tree right now

$ git log --oneline -8
ca9341c feat(phys): A6.P4 Task 7 — RegisterLiveEntityCollision uses ShadowShapeBuilder + RegisterMultiPart
3b7dc46 fix(phys): GetNearbyObjects dedup-by-entityId silently drops multi-part shadows
e1d94d7 test(phys): door setup + GfxObj dat-inspection — Hypothesis A falsified
c89df8e docs(handoff): door collision per-part BSP session handoff (2026-05-24)
1498697 diag(phys): [cyl-test] probe — log every Cylinder shadow collision test
3e5dc8c test(phys): Task 6 regression — Deregister clears _entityShapes cache
d5ffb03 feat(phys): UpdatePosition handles multi-part entities
fca0a13 feat(phys): ShadowObjectRegistry.RegisterMultiPart

Uncommitted (to commit next):

• src/AcDream.Core/Physics/TransitionTypes.cs — new [bsp-test] probe in the BSP collision dispatch, mirrors [cyl-test]. Fires when a BSP entry is visited, BEFORE the cache lookup. Distinguishes "cache miss → silent skip" from "queried but no hit." Gated on ACDREAM_PROBE_BUILDING=1.
• tests/AcDream.Core.Tests/Physics/DoorCollisionApparatusTests.cs — new test Apparatus_Grounded_50cmOffCenter_FrontApproach_DocumentsBug that attempts to reproduce the production bug with a grounded body + seeded ContactPlane. Currently fails because the apparatus's behavior diverges from production (apparatus blocks immediately at tick 0 with a Z+ normal from the synthetic floor; production walks through).

---

Path 5 vs Path 6 — the divergence

BSPQuery.FindCollisions dispatches to 6 paths based on ObjectInfo state. The crucial difference:

• Path 6 (Default) — fires when obj.State has no Contact flag. Calls SphereIntersectsPolyInternal and SetCollide on hit. Apparatus tests use this path (no body, isOnGround=false). They all PASS — the door's BSP blocks the sphere correctly.

• Path 5 (Contact branch) — fires when obj.State.HasFlag(Contact). Calls SphereIntersectsPolyInternal; on hit, calls StepSphereUp → DoStepUp → DoStepDown to attempt climbing over the obstacle. Returns OK if step succeeds, Slid if step fails. Production uses this path (player grounded → isOnGround=true → engine sets Contact flag at PhysicsEngine.cs:631). Production WALKS THROUGH.

So the bug is somewhere in Path 5's step-up logic. The leading hypothesis (not yet proven):

When the player is standing on flat ground in front of the door, step-up's DoStepDown probes 0.6 m downward from the sphere's current position. It finds the SAME flat ground extending to the OTHER SIDE of the door (Holtburg cottages have no Z change between exterior and interior floor — both at Z=94). find_walkable declares step-up SUCCESS, the BSP collision returns OK, and the sphere walks through the door.

The fix probably involves: step-up should reject if a forward probe at the lifted height STILL hits the same obstacle. The current DoStepDown probes only DOWNWARD; it doesn't verify that the forward motion at the lifted height is clear.

This is speculation — needs apparatus verification.

---

Why the apparatus didn't reproduce the bug

The grounded apparatus test (Apparatus_Grounded_50cmOffCenter_*) was supposed to fail in the same way as production (walk through). Instead it BLOCKED at tick 0 with normal=(0,0,1) — sphere position unchanged.

Diagnostic output:

[bsp-test] obj=0x000F424F gfx=0x010044B5 ... pos=(11.99,12.12,1.27)
           distXY=1.234 cacheHit=True
[resolve] in=(12.500,11.000,0.480) tgt=(12.500,11.100,0.480)
          out=(12.500,11.000,0.480) ok=True hit=yes n=(0,0,1) walkable=True

ACDREAM_DUMP_STEPUP=1 produced no stepup: ENTER lines, so DoStepUp was NOT called. The hit normal (0,0,1) came from somewhere else (likely the seeded walkable polygon or the synthetic floor interaction with the engine's terrain step-down).

The apparatus's stub terrain (Z=-1000) + synthetic walkable poly at Z=0 may be causing the engine to take a different code path than production's real Holtburg terrain. Reproducing production fully would require:

1. Real terrain heightmap covering the test landblock at Z=94
2. EnvCell or stab geometry near the test door
3. Proper cottage/cell setup so portal-reachable cells include the door's outdoor cell when player is indoor

This is significant apparatus investment. Worth it IF the bug requires multi-tick simulation in real geometry to surface. For now, the apparatus shows the broad shape: with proper grounded state + seeded body, the engine doesn't take the same path as the airborne (Path 6) test.

---

Recommended next steps (ranked)

Option A — Live diagnostic with ACDREAM_DUMP_STEPUP=1 (cheapest)

Relaunch with ACDREAM_PROBE_BUILDING=1 + ACDREAM_DUMP_STEPUP=1. Walk into a closed door off-center. The step-up dump will show:

• Whether DoStepUp fires at all when the BSP hits
• If so, what the input normal is
• Whether stepDown succeeds or fails

If stepDown succeeds (i.e., step-up climbs over the door), we've confirmed the hypothesis above and can target the fix.

Option B — Build a richer apparatus

Replace the stub terrain with a real heightmap-like surface at Z=94 spanning the test landblock. Replace the synthetic walkable poly with a proper terrain polygon at the door's world XY. This should let Path 5 run the SAME way as production. Then iterate on the fix locally in <500 ms.

Estimated effort: 1-2 hours of apparatus work.

Option C — Direct retail cdb trace

Attach cdb to a running retail client at a Holtburg cottage doorway, break on CTransition::step_up or CTransition::step_down, and observe how retail handles step-up against a door. Compare against acdream's behavior.

Estimated effort: 30 min - 2 hours depending on what we find.

Option D — Pivot to fix-and-verify

Hypothesis-based fix: in DoStepUp, reject step-up if the input collision normal is mostly horizontal AND the obstacle's bounding sphere height range significantly exceeds the step-up height. The door has BS radius 1.975 m centered at Z=1.275 → top of BS at Z=3.25, way above step-up=0.6. If we detect "this obstacle is too tall to step over," fall back to wall-slide.

Risk: might break stairs / ramps. Need apparatus to verify.

Recommendation

Option A first (~5 min, no code changes needed). If hypothesis confirmed, then Option D (with apparatus from Option B for regression testing).

---

Files touched this session (cumulative)

Committed:

• src/AcDream.Core/Physics/ShadowObjectRegistry.cs (dedup fix)
• src/AcDream.App/Rendering/GameWindow.cs (Task 7 wiring)
• tests/AcDream.Core.Tests/Physics/DoorSetupGfxObjInspectionTests.cs (NEW)
• tests/AcDream.Core.Tests/Physics/DoorCollisionApparatusTests.cs (NEW)
• docs/research/2026-05-24-door-dat-inspection-findings.md (NEW)

Uncommitted (this doc + 2 file changes):

• src/AcDream.Core/Physics/TransitionTypes.cs (added [bsp-test] probe)
• tests/AcDream.Core.Tests/Physics/DoorCollisionApparatusTests.cs (added grounded test scenario — fails for unrelated apparatus reasons but the probe wiring is sound)

Memory updated: feedback_dedup_keys_after_cardinality_change.md

---

Pickup prompt for next session

A6.P4 Task 7 shipped (RegisterLiveEntityCollision uses
ShadowShapeBuilder + RegisterMultiPart) and the foundation fix
(GetNearbyObjects dedup on full ShadowEntry instead of entityId).
Production verification: center blocks, but off-center + inside-out
still walk through closed doors. The multi-part registration is
correct (verified by live probes); the remaining bug is downstream
in BSPQuery Path 5's step-up logic.

  Read docs/research/2026-05-24-door-collision-task7-shipped-but-bug-remains.md

  State both altitudes:
    Currently working toward: M1.5 — Indoor world feels right
    Current phase: A6.P4 door collision — step-up misbehavior
                   investigation. Multi-part registration shipped;
                   step-up at thin tall obstacles is the remaining bug.

  Recommended first move: Option A from the findings doc — relaunch
  with ACDREAM_PROBE_BUILDING=1 + ACDREAM_DUMP_STEPUP=1, walk into
  a Holtburg cottage door off-center. The step-up dump will reveal
  whether DoStepUp is incorrectly succeeding for the door's BSP slab
  hit (the leading hypothesis: DoStepDown finds the same flat floor
  on the other side of the door, declaring step-up success).

  DO NOT re-investigate the multi-part registration or GetNearbyObjects
  dedup — both are confirmed working. Focus on the step-up path 5
  behavior for thin tall obstacles.