acdream/docs/research/2026-05-25-a6-door-cyl-investigation-handoff.md

A6.P6 / A6.P7 — Door cylinder + slab interaction handoff

Date: 2026-05-25 PM Status: A6.P5 cellSet fix shipped (3b1ae83). A6.P6 cyl step-over shipped (3d4e63f). Residual symptom remains: sphere can't slide tangentially past the door's foot cylinder when the cyl's radial collision normal dominates the slide direction. Three fix options identified; user picked "investigate retail first" — that's this session's work.

---

TL;DR

Walking into a closed cottage door from outside in acdream:

Before A6.P5	After A6.P5 only	After A6.P6 too
Sphere walks through (cellSet didn't include door)	Sphere blocks BUT cyl phantom radial-pushes sphere AWAY from target (~10 cm push-out at door center)	Sphere stops at current position when cyl fires — no more push-out, but also can't slide tangentially past the cyl on some headings

A6.P5 made the door reliably visible from all approach angles (closed the cellSet bug); A6.P6 routed Contact-grounded cyl collisions through step-over instead of radial push. Both retail-anchored. But the residual "can't slide past cyl on certain headings" still happens because:

1. The door has two collision shapes: a tiny foot cylinder (r=0.10, h=0.20) and the big slab BSP.
2. Our FindObjCollisions tests shapes in registration order. The cyl gets tested FIRST. When cyl fires, FindObjCollisions returns immediately — slab BSP never tested in that iteration.
3. The cyl's collision normal is radial (away from cyl axis). For a sphere wanting to move SE past a door at world (132.6, 17.1), the cyl-radial normal is roughly (0.86, 0.51, 0). The slide tangent from that normal points mostly south — INTO the slab. Slab then blocks (in a downstream iteration). Net: sphere doesn't move.
4. If the slab's clean (0, +1, 0) normal were used instead, the slide tangent would be pure east. Sphere would slide cleanly along the door. This is what retail does visibly.

So the question is: how does retail end up with the slab's normal driving the slide, when retail also has the cyl AND tests it?

---

What today shipped (DO NOT redo this)

A6.P5 — cellSet portal expansion fix (commit 3b1ae83)

• File: src/AcDream.Core/Physics/CellTransit.cs
• Function: FindTransitCellsSphere exit-portal branch + BuildCellSetAndPickContaining
• Change: exit portals contribute exitOutside = true by topology, not by sphere-plane overlap.
• Retail anchor: CObjCell::find_cell_list at acclient_2013_pseudo_c.txt:308742-308869.
• Tests: CellTransitTests.A6P5_BuildCellSetFromIndoorStart_ReachesDoorOutdoorCell + A6P5_BuildCellSetFromAlcove_AlsoReachesDoorOutdoorCell. Both pass.
• Fixture: tests/AcDream.Core.Tests/Fixtures/door-bug/over-penetration-capture.jsonl (3 records from the 17 MB live capture).

A6.P6 — cyl step-over for Contact movers (commit 3d4e63f)

• File: src/AcDream.Core/Physics/TransitionTypes.cs
• Function: CylinderCollision — added Contact-grounded branch
• Change: when oi.Contact && !sp.StepUp && !sp.StepDown && engine != null and cyl height fits step-up-height, attempt DoStepUp(collisionNormal, engine). On failure → StepUpSlide(this). On step-fail, behavior changes from radial push to tangent-along-crease.
• Retail anchor: CCylSphere::intersects_sphere at acclient_2013_pseudo_c.txt:324626-324641 (Contact branch dispatches step_sphere_up) + CCylSphere::step_sphere_up at acclient_2013_pseudo_c.txt:324516-324538.
• Tests: all A6P5_* + Path 5 tests + door directional tests pass in isolation. Full Core suite 17 failures (same as A6.P5 baseline) — diff is documented static-leak flakiness.

Probes added (still in place — useful for next session)

• ACDREAM_PROBE_CELLSET=1 → [cellset-build] line per BuildCellSetAndPickContaining call.
• ACDREAM_PROBE_BUILDING=1 → [cyl-test] + [bsp-test] (existing).
• ACDREAM_PROBE_RESOLVE=1 → [resolve] (existing).
• ACDREAM_CAPTURE_RESOLVE=<path> → JSONL capture for replay.

Captures from today (gitignored, on disk)

• door-stuck-capture.jsonl (17 MB, 8483 records) — the original phantom reproduction.
• door-phantom-capture.jsonl (13 MB, ~7000 records) — captured with cyl/bsp probes ON post-A6.P5.
• door-a6p6-v2.launch.log (UTF-16) + door-a6p6-v2.utf8.log — most recent diagnostic launch with all 3 probes on after A6.P6 fix landed. Shows residual cyl phantom (12+ resolves with cn=(0.86, 0.51, 0) attributed to door entity 0x000F4245).

---

The remaining symptom (what to fix)

User walks into a closed cottage door (Setup 0x020019FF, entity at world ≈ (132.6, 17.1, 94.1)). When the sphere ends up at certain angles to the door (NE / SE of the cyl center), the cyl's slide "blocks" the sphere from making tangential progress along the slab face.

Specific evidence from door-a6p6-v2.utf8.log (line ~23553):

[resolve-bldg] obj=0x000F4245 ... hitPoly: plane=(0.000,0.000,-1.000,-1.236)  ← slab BOTTOM hit, but culled (no Z motion)
[cyl-test] obj=0x000F4245 ... result=Slid                                      ← cyl fired
[resolve] in=(132.777,17.724) tgt=(133.044,17.400) out=(132.777,17.724)
          hit=yes n=(0.86,0.51,0.00) obj=0x000F4245 nObj=9

The cn=(0.86, 0.51, 0) is the cyl's radial normal (sphere is NE of cyl axis). The slide direction is perpendicular = (0.51, -0.86, 0) ≈ mostly south = into the slab. Slab blocks in subsequent iteration. Net: out == in.

Counts from the latest launch (~7K resolves):

• 117 hit=yes attributed to door entity 0x000F4245
• 99 hit=yes attributed to cottage GfxObj 0xA9B47900
• 350 cyl-tests result=Slid (out of 1623 total cyl tests)
• 12 resolves with cn=(0.86, 0.51, 0) on the door — the "phantom slide direction" pattern

---

The three options (user picked #2-investigation first)

Option 1: BSP-first per-entity test order (smallest fix)

Within an entity's shapes, test BSP shapes before Cylinder shapes. If BSP fires, skip the cyl. The slab's clean (0, ±1, 0) normal drives the slide → sphere slides smoothly along door face.

• ~10 lines in FindObjCollisions (sort nearbyObjs per-entity).
• Retail-faithful behaviorally; whether it's retail-faithful architecturally is uncertain (see Option 2 research).

Option 2: Port retail's per-physobj dispatch (architectural)

Restructure ShadowObjectRegistry to group shapes by entity. Implement retail's CPhysicsObj::FindObjCollisions dispatch including the state & 0x10000 branch logic (acclient_2013_pseudo_c.txt:276861).

• Large change; touches many files.
• True retail-faithful architecture. But behaviorally may end up producing the same outcome as Option 1 if our state flag mapping is correct.

Option 3: Door-cyl-as-informational

Hypothesis: retail's door cyl is for click-target / sound trigger / foot-slip prevention for non-player entities, NOT a physics blocker for the standard player. Skip registering it as a collision shape on entities that also have a BSP.

• Needs retail research to confirm.
• Risk: breaks foot-slip prevention for small entities.

---

Retail investigation needed (THIS SESSION's main work)

The fundamental question: what does retail do with the door's cyl that produces clean sliding past it? Two specific things to read + test:

Investigation 1: What does state & 0x10000 mean?

Retail's CPhysicsObj::FindObjCollisions at acclient_2013_pseudo_c.txt:276861:

if (((this->state & 0x10000) == 0 || ebp_1 != 0) || eax_12 != 0) {
    // iterate cylspheres + spheres
} else {
    // iterate BSP parts via CPartArray::FindObjCollisions
}

Door state at spawn = 0x00010008. Bit 0x10000 (bit 16) IS set. So condition state & 0x10000 == 0 is FALSE. The branch depends on ebp_1 and eax_12.

Investigation steps:

1. Grep acclient_2013_pseudo_c.txt for what assigns to ebp_1 and what eax_12 is computed from. Identify which mover/target state bits drive the branch.
2. Search docs/research/named-retail/acclient.h for state flag bit definitions (look for constants 0x10000, OBJECT_USES_PHYSICS_BSP or similar around the OBJECTINFO / PhysicsObj state field).
3. Determine which branch fires for: closed door (state 0x10008) + grounded player.
4. If cyl branch fires for our case: how does retail block player from passing through the door without the BSP test?
5. If BSP branch fires: why? What state condition is off in our replica?

Cross-reference with ACE's PhysicsObj.FindObjCollisions — references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs. ACE might have cleaner names for the same logic.

Investigation 2: What does the door's cyl actually DO in retail?

Concrete experiment using cdb on the live retail client:

1. Attach cdb to retail acclient.exe (toolchain in CLAUDE.md "Retail debugger toolchain" section).
2. Set breakpoint on CCylSphere::collides_with_sphere (acclient address 0x53a880) with action: log entity id + sphere position + result. Use qd after ~5000 hits to detach.
3. Walk retail player into a closed cottage door from outside, trying to slide along it.
4. Capture trace. Look for:
   • Does the door cyl ever fire collides_with_sphere returning 1? If yes → cyl IS active in retail.
   • If no → cyl is somehow excluded from physics in retail (Option 3 plausible).
5. Set breakpoint on BSPTREE::find_collisions for the same scenario. Determine if BSP slab is tested.

Investigation 3: Inspect Setup parsing differences

Compare what our ShadowShapeBuilder.FromSetup produces from Setup 0x020019FF vs what retail's PhysicsObj constructs from the same Setup:

1. dotnet test --filter "FullyQualifiedName~DoorSetupGfxObjInspectionTests" --logger "console;verbosity=detailed" for our parse.
2. Inspect retail's PhysicsObj creation flow (acclient.exe around the PhysicsObj constructor + part_array initialization). Look for filtering: does retail include the Setup's cyl in its physics shape list, or is there a flag-driven include/exclude?

---

Files to read FIRST next session

File / location	What to find
docs/research/named-retail/acclient_2013_pseudo_c.txt:276776+	CPhysicsObj::FindObjCollisions (the dispatch + state flag branch)
docs/research/named-retail/acclient_2013_pseudo_c.txt:324558	CCylSphere::intersects_sphere (the per-cyl dispatch for state & 3)
docs/research/named-retail/acclient_2013_pseudo_c.txt:324516	CCylSphere::step_sphere_up (our A6.P6 anchor; verify our port matches)
docs/research/named-retail/acclient.h	OBJECTINFO state bit constants (esp. 0x10000)
references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs	ACE's port — cleaner names
docs/research/named-retail/acclient_2013_pseudo_c.txt:308916	CObjCell::find_obj_collisions (per-cell shadow iteration, calls CPhysicsObj::FindObjCollisions)

---

Tests to keep green (do NOT regress)

Run these in isolation when verifying any new fix:

dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --no-build -c Debug --filter "FullyQualifiedName=AcDream.Core.Tests.Physics.CellarUpTrajectoryReplayTests.LiveCompare_FirstCap_FixClosesCottageFloorCap|FullyQualifiedName=AcDream.Core.Tests.Physics.DoorBugTrajectoryReplayTests.Directional_OutsideIn_SouthApproach_BlocksAtSlabSouthFace|FullyQualifiedName=AcDream.Core.Tests.Physics.DoorBugTrajectoryReplayTests.Directional_InsideOut_NorthApproach_BlocksAtSlabNorthFace|FullyQualifiedName=AcDream.Core.Tests.Physics.DoorBugTrajectoryReplayTests.CornerSlide_AlcoveEastToCottageNorth_ShouldBlock|FullyQualifiedName=AcDream.Core.Tests.Physics.DoorBugTrajectoryReplayTests.Geometric_DoorSlabAtSphereHeight_OverlapsInZ|FullyQualifiedName=AcDream.Core.Tests.Physics.DoorBugTrajectoryReplayTests.InsideOut_Tick3254_WithCottageWalls_ShouldBlock|FullyQualifiedName~BSPQueryTests.FindCollisions_Path5|FullyQualifiedName~CellTransitTests.A6P5|FullyQualifiedName~DoorCollisionApparatusTests.Apparatus_DeadCenter"

Expected: all 14 pass.

Full Core suite has 17 documented flaky-in-full-run failures — those are the static-leak flakiness CLAUDE.md describes, not regressions.

---

Things NOT to do (do-not-retry list)

1. Don't reverse cyl/BSP iteration order globally. Cross-entity ordering should follow registration sequence (matches retail per-cell shadow_object_list). Only within-entity ordering needs adjustment.
2. Don't disable the door cyl unconditionally. Foot-slipping matters for small entities even if not for the player.
3. Don't enlarge EPSILON in slide-back-off math to "give more margin." The 11mm residual penetration is a separate issue (SlideSphere preserves currPos.Y which may already be slightly penetrating); changing epsilon would mask other bugs.
4. Don't add per-call workarounds in CylinderCollision (like "if entity has a sibling BSP, return OK"). Per CLAUDE.md no-workarounds rule — fix the architectural issue, not the symptom.
5. Don't break A6.P6 step-over for non-door cyls (tree trunks, rock pillars, NPCs). Whatever fix lands must keep cyl-only entities blocking correctly.

---

Open issue tracking

Add to docs/ISSUES.md after this handoff:

- door-cyl-residual-block: After A6.P5 + A6.P6, sphere can still be
  blocked at NE/SE headings approaching a closed cottage door because
  the cyl's radial collision normal drives the slide direction into
  the slab. Three fix options outlined in
  docs/research/2026-05-25-a6-door-cyl-investigation-handoff.md;
  pending retail investigation to pick the retail-faithful path.
  Severity: M1.5 polish (does not block "kill a drudge" demo).

---

Pickup prompt for next session

A6.P6 / A6.P7 — door-cyl residual block investigation.

Read first (in this order):
  1. docs/research/2026-05-25-a6-door-cyl-investigation-handoff.md
     (full context: what landed, what's still broken, the 3 fix options,
     do-not-retry list)
  2. docs/research/named-retail/acclient_2013_pseudo_c.txt:276776
     (CPhysicsObj::FindObjCollisions — the state-flag dispatch)
  3. docs/research/named-retail/acclient_2013_pseudo_c.txt:324558
     (CCylSphere::intersects_sphere — the cyl dispatch)

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A6.P7 — retail investigation for door cyl + slab
                 collision interaction.

The session's main work: retail investigation. NOT implementation.
Specific questions to answer (cite retail line numbers in the report):

  1. What does state bit 0x10000 mean? Closed cottage doors have it
     set (state = 0x00010008). Retail's FindObjCollisions branches on
     `((state & 0x10000) == 0 || ebp_1 != 0) || eax_12 != 0`. What are
     ebp_1 and eax_12? Which branch fires for a closed door + grounded
     player? (Cross-reference references/ACE/Source/ACE.Server/Physics/
     PhysicsObj.cs for cleaner names.)

  2. Does the door cyl actually fire collides_with_sphere in retail
     when player slides along the door? Set a cdb breakpoint on
     CCylSphere::collides_with_sphere (acclient address 0x53a880),
     walk a retail player into the cottage door, observe. If cyl
     fires: how does retail produce smooth sliding past it? If cyl
     doesn't fire: by what mechanism is it excluded?

  3. Compare our ShadowShapeBuilder.FromSetup output vs retail's
     PhysicsObj shape list for Setup 0x020019FF. Where do they
     diverge?

Deliverable: a short report (~2-3 pages) covering the 3 questions with
retail line numbers + cdb trace excerpts. Then propose which of the
3 fix options (BSP-first per-entity / per-physobj dispatch port /
door-cyl-informational) is the most retail-faithful, justified by
the research.

DO NOT implement the fix this session — the brainstorming-only
discipline applies. After the report, the next session will pick
the implementation approach + execute via writing-plans → executing-plans.

Do-not-retry list (in handoff doc) — read it before starting.

Tests to keep green if any code changes happen: see handoff doc.

Reproduction setup ready to relaunch with diagnostics if needed:
  ACDREAM_PROBE_BUILDING=1 ACDREAM_PROBE_RESOLVE=1 ACDREAM_PROBE_CELLSET=1
  ACDREAM_CAPTURE_RESOLVE=<path>.jsonl