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

M1.5 — Broken stairs (cyl-only multi-part entity) — investigation handoff

Date: 2026-05-25 PM Status: Filed as issue #101 (post-A6.P7 visual verification surfaced a NEW bug, not the closed door bug). Research-only next session. No implementation until we know what retail does at this exact stair location. Predecessor handoff: 2026-05-25-a6-door-cyl-investigation-handoff.md (closed by A6.P7 commit 888272a).

---

TL;DR

A6.P7 visual verification at Holtburg confirmed the cottage door is fixed. While exploring, the user found a different staircase that doesn't work — sphere can't climb at all. Captures show:

• Stairs are in cells 0xA9B40159 + 0xA9B4015A (NOT the cottage-cellar cells 0xA9B40143/146/147 that work post-A6.P3 cellar fix).
• Geometry is a multi-part entity 0x0040B500 (entityId; ~150 parts in the setup; 10 of them are stair-step cylinders).
• Each step is a separate cylinder (r=0.80m, h=0.80m) at Y=26.60, stepping up in X and Z (0.25 m per step, Z: 94.22 → 96.47).
• state=0x00000000 on each cyl part — no HAS_PHYSICS_BSP_PS flag, so A6.P7's dispatch gate (Transition.BspOnlyDispatch) does NOT skip them.
• The cyls fire 284 result=Slid with diagonal radial normals like (0.88, -0.47, 0) — the same phantom shape A6.P7 closed for the cottage door, but here the cause is per-cyl-without-BSP, not per-entity-with-both.
• Player Z stayed at 94.00 for the entire 4216-record capture — never gained altitude.

This is NOT a regression of A6.P7. The fix did exactly what retail does for entities with HAS_PHYSICS_BSP_PS. The stair bug is a separate class: cyl-only entities (no BSP) whose cyl geometry shouldn't physically block the player but does.

---

What today shipped (DO NOT redo)

A6.P7 — retail-binary cyl/BSP dispatch (commit 888272a)

• File: src/AcDream.Core/Physics/PhysicsBody.cs (added PhysicsStateFlags.HasPhysicsBsp = 0x00010000)
• File: src/AcDream.Core/Physics/TransitionTypes.cs (added Transition.BspOnlyDispatch(uint) predicate + per-entry guard at the cyl/sphere branch)
• Test: tests/AcDream.Core.Tests/Physics/A6P7DispatchRulesTests.cs (7 tests)
• Investigation: docs/research/2026-05-25-a6-door-cyl-retail-dispatch-investigation.md.
• Visual-verified at Holtburg cottage door 2026-05-25. Captures: launch-a6p7.log, launch-a6p7-v2.log — 1187 [cyl-skip-bsp], 0 [cyl-test] on the door, 30 axis-aligned hits, no phantom diagonals.

---

The new bug — captures + evidence

Captures (on disk, gitignored — DO NOT commit them; treat as live data)

• Working baseline (cellar stairs that work): stairs-working.jsonl (16.9 MB, ~22K records). Z range 90.95 ↔ 94.00 (full cellar climb). 12 cell transitions; only 23 hit=yes events; no diagonal normals; user ran up + down twice. Cells 0xA9B40143/146/147.
• Broken stairs: stairs-broken.jsonl (8.1 MB, 4216 records). Z stayed at 94.00 for the entire capture. Cells 0xA9B40159 + 0xA9B4015A. The player tried multiple approach angles; never climbed any step.
• Launch logs with probes: stairs-working.launch.log, stairs-broken.launch.log. Contain [cyl-test], [cyl-skip-bsp], [bsp-test], [resolve], [resolve-bldg] probe lines.

Reproduction

Login as +Acdream at Holtburg. The cellar stairs work (verified). The broken stairs the user found are at world XY around (110, 26), Z range 94 → 96. Walk west into them — sphere hits something diagonal and gets stuck oscillating between n=(0, 1, 0) and n=(0.87, -0.49, 0) slides.

Geometry summary (from stairs-broken.launch.log)

The blocker is multi-part entity entityId=0x0040B500. Ten of its parts are cylinders forming a staircase at Y=26.60:

Part	World XY	Z (cyl bottom)
0x40B5008C (part 140)	(108.72, 26.60)	96.47
0x40B5008D (part 141)	(108.97, 26.60)	96.22
0x40B5008E (part 142)	(109.22, 26.60)	95.97
0x40B5008F (part 143)	(109.47, 26.60)	95.72
0x40B50090 (part 144)	(109.72, 26.60)	95.47
0x40B50091 (part 145)	(109.97, 26.60)	95.22
0x40B50092 (part 146)	(110.22, 26.60)	94.97
0x40B50093 (part 147)	(110.47, 26.60)	94.72
0x40B50094 (part 148)	(110.72, 26.60)	94.47
0x40B50095 (part 149)	(110.97, 26.60)	94.22

Each cyl: radius=0.80, height=0.80, state=0x00000000. The entity also has a BSP part obj=0xB5008900 gfx=0x01000C16 radius=2.645 pos=(109.30, 26.30, 95.75) but it's effectively non-physics (hasPhys=False bspR=0.00 vAabbR=0.82) — the vAabbR here is the visual AABB radius being borrowed as a cylinder fallback because the underlying GfxObj has no physics BSP.

What's blocking the player

Sphere at (112.115, 25.995, 94.00) wants to move west. The closest cyl 0x40B50095 is at (110.97, 26.60, 94.22):

• distXY = 1.295m (just barely outside reach 0.80 + 0.48 = 1.28m)
• But during sub-stepping the sphere center crosses 1.28m → cyl overlaps
• Radial normal direction from cyl center to sphere: (0.884, -0.467, 0) — matches observed phantom hits (0.88, -0.47), (0.86, -0.51), etc.

The cyl is too tall (0.80m) to step over under A6.P6's grounded step-over check (step-up budget = 0.60m). Falls through to the wall-slide branch which produces the diagonal radial normal that drives the sphere's slide tangent into the perpendicular cell wall, then re-blocks. Net: stuck.

Why A6.P7 doesn't help

A6.P7 gates the cyl branch on (state & 0x10000) != 0. These stair cyls have state=0x00000000 — bit not set. Guard does NOT fire. Cyls are tested. Sphere blocks.

---

What this session needs — retail investigation

Mandate: report-only research, NO implementation. Use the /investigate skill. The fix design comes in a subsequent session once the retail behavior is settled.

Question 1 — What does retail DO at this exact staircase?

Use cdb. The toolchain in CLAUDE.md "Retail debugger toolchain" is ready. The matching binary + PDB are verified.

Concrete experiment:

1. Have the user run the retail acclient.exe (Microsoft AC official build v11.4186) at the same world location (cells 0xA9B40159 + 0xA9B4015A, XY ≈ (110, 26)). The user needs to be IN the building, AT the foot of these stairs.
2. Attach cdb with breakpoints:
   • acclient!CCylSphere::collides_with_sphere at 0x53a880 — counter $t0, log every 100 hits with the this pointer and the moving sphere's position, gc. Auto-detach after 5000.
   • acclient!CCylSphere::intersects_sphere (the dispatch from CPhysicsObj::FindObjCollisions cyl branch) — counter $t1, log entity address.
   • acclient!CObjCell::find_env_collisions — counter $t2. Tells us if retail uses cell BSP for stair collision.
   • acclient!CPartArray::FindObjCollisions — counter $t3. Confirms BSP dispatch path.
3. Have the user walk straight into the broken stairs from outside, then try to climb them. Capture 30 seconds.
4. Detach. Analyze:
   • Does CCylSphere::collides_with_sphere fire on the stair entity? If yes → retail's cyls ARE active here, and retail somehow handles them differently (different step-up threshold? cell-context-aware?). If no → retail's cyls are excluded by something we don't replicate.
   • Does CObjCell::find_env_collisions fire heavily? If yes → retail might be using cell BSP polygons for the stairs (and the entity cyls are decorative/click-targets only).

Question 2 — What's the Setup ID? Compare retail's PhysicsObj construction

Our [resolve-bldg] lines show the entity is built from GfxObj 0x0100081A with hasPhys=False. What's the Setup ID for entity 0x0040B500? Trace through our streaming code to find which Setup emitted the 150-part build.

Steps:

1. Grep src/AcDream.App/Rendering/GameWindow.cs for the BuildInteriorEntitiesForStreaming path (CLAUDE.md says it hydrates EnvCell static objects with id 0x40xxxxxx).
2. Add a temporary [entity-source] probe that logs the Setup id when an entity gets registered. Or check existing diagnostic output — the gfxObj=0x0100081A is the part's GfxObj, but we need the parent Setup.
3. With the Setup id in hand, look up retail's behavior:
   • Decompile / grep docs/research/named-retail/acclient_2013_pseudo_c.txt for CPhysicsObj::InitPartArrayFromSetup or similar to see how retail builds the part_array from a Setup. Does retail include every part as a collision shape, or filter by some flag?

Question 3 — Why is vAabbR becoming a cylinder?

The [resolve-bldg] line shows gfxObj=0x0100081A hasPhys=False bspR=0.00 vAabbR=0.82. We registered a r=0.80 cyl. The 0.80 ≈ 0.82 match is suspicious — we're using the visual AABB radius as a fallback cyl radius when there's no physics BSP.

Steps:

1. Find the code path in our tree that does this fallback. Likely in src/AcDream.Core/Physics/ShadowShapeBuilder.cs FromSetup or in RegisterMultiPart. Look for cases where GfxObj.PhysicsBSP is null and a cyl is synthesized.
2. Cross-reference retail: does retail synthesize a cyl from visual bounds when physics is null? Or does retail skip such parts entirely for collision (visual-only)?
3. ACE check: references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs — how does ACE construct the part_array from a Setup with mixed physics/visual-only parts?

Question 4 — Cell BSP fallback

If retail's stairs are walked via cell BSP polygons (not entity cyls), what's in cell 0xA9B40159's BSP at this XY/Z? Is there a walkable polygon staircase that we're not iterating?

Steps:

1. Use ACDREAM_DUMP_CELLS=0xA9B40159,0xA9B4015A to dump the cell BSPs to JSON. (Confirm the env var path; see existing CellDump infra near issue #98's apparatus.)
2. Look for inclined polygons in the dump that form the staircase. If present → retail likely uses these for collision; our entity cyls are either a setup misinterpretation or redundant.

---

Files to read FIRST next session

Path	Why
docs/ISSUES.md (#101)	The filed issue with severity + acceptance
docs/research/2026-05-25-a6-door-cyl-retail-dispatch-investigation.md	A6.P7 background (closed; companion bug)
docs/research/named-retail/acclient_2013_pseudo_c.txt:276776	CPhysicsObj::FindObjCollisions
Setup dat reader path in src/AcDream.Core/Physics/ShadowShapeBuilder.cs	Cyl synthesis from Setup; the suspected fallback
src/AcDream.App/Rendering/GameWindow.cs::BuildInteriorEntitiesForStreaming	Entity hydration for EnvCell statics
references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs	ACE PartArray construction
references/ACE/Source/ACE.Server/Physics/Common/Setup.cs	ACE Setup → PartArray pipeline

---

Tests that must stay green

Same as A6.P7 list:

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|FullyQualifiedName~A6P7DispatchRulesTests"

Expected: 20/20 pass.

---

Things NOT to do (do-not-retry)

1. Don't lower step-up height to make A6.P6's grounded step-over fit the 0.80m cyl. Step-up budget = 0.60m is retail-faithful. Tweaking it would regress every other surface where 0.60m is correct (curbs, low ledges).
2. Don't extend A6.P7's BspOnlyDispatch to entities with state=0. That gate is retail-specific (HAS_PHYSICS_BSP_PS). Skipping cyls purely because peer parts exist with BSP would diverge from retail and break NPC cyl-only entities.
3. Don't disable cyl fallback when hasPhys=False without checking retail. Until we know how retail handles GfxObj with no physics BSP, "just skip the cyl" might break other content (small decorative items that DO collide in retail).
4. Don't add per-entity workarounds ("if entity id 0x0040B500, skip cyls"). Per CLAUDE.md no-workarounds rule.
5. Don't enlarge the sphere's step-up budget for tall cyls. Retail's threshold is what it is. If retail steps over 0.80m cyls in this scenario, the mechanism is something else.

---

Three fix-shape candidates (for the FOLLOWING session, not this one)

Listed in rough order of retail-faithfulness based on the limited evidence we have. The retail investigation will decide which is right.

1. Don't synthesize cyls from visual AABB when GfxObj.PhysicsBSP is null. Suppress at registration time in ShadowShapeBuilder.FromSetup. Retail-anchored: if retail's CPartArray doesn't include such parts in the collision list, our registration shouldn't either. The cell BSP would then be the only collision source.
2. Use cell BSP polygons for stair geometry; entity cyls are decorative-only for this entity class. Requires: (a) confirming cell 0xA9B40159 BSP has walkable stair polys, (b) ensuring our cell BSP query iterates them. Likely a no-op on our side once (1) is done.
3. Make step_sphere_up cyl-height-tolerant — if the sphere is on a walkable plane and a cyl is detected, attempt step-up even when cyl height > step-up budget IF a walkable surface exists at the top of the cyl. Retail-anchored ONLY if cdb shows retail does this on these specific stairs.

---

Pickup prompt for next session

A6 — Broken stairs cyl investigation (issue #101). Investigation-only session.

Read first (in this order):
  1. docs/research/2026-05-25-stairs-cyl-investigation-handoff.md
     (this file — full context, captures, geometry, do-not-retry list)
  2. docs/ISSUES.md #101
  3. docs/research/2026-05-25-a6-door-cyl-retail-dispatch-investigation.md
     (A6.P7 background — closed; companion bug)

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A6 — broken-stairs investigation (issue #101)

Session mandate: retail investigation, NOT implementation. Use the
/investigate skill. Specific questions (each must be answered with cited
evidence — retail line numbers, cdb traces, dat dumps):

  1. Does retail's CCylSphere::collides_with_sphere fire on the stair-step
     cylinders at cells 0xA9B40159/0xA9B4015A when a player walks in to
     climb them? If yes — how does retail walk past 0.80m-tall cyls? If
     no — what excludes them?

  2. What's the Setup ID for entity 0x0040B500? Trace from
     GameWindow.cs::BuildInteriorEntitiesForStreaming. Cross-reference how
     retail's CPhysicsObj::InitPartArrayFromSetup (or equivalent) builds
     the collision shape list — does retail include parts with
     hasPhys=False?

  3. Why does our ShadowShapeBuilder synthesize an r=0.80 cyl from
     vAabbR=0.82 when GfxObj.PhysicsBSP is null? Identify the code path.
     Does retail do this?

  4. Dump cell 0xA9B40159's BSP polygons (ACDREAM_DUMP_CELLS). Does the
     cell BSP have walkable stair polygons? If yes — retail's stair
     collision is the cell BSP, not the entity cyls.

Deliverable: a short report (~2-3 pages) covering the 4 questions with
retail line numbers, cdb trace excerpts, code citations. Then propose
which of the 3 fix-shape candidates is most retail-faithful (or a fifth
shape that emerges from the research).

DO NOT implement the fix this session. Save it for the session after.

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

Tests to keep green if any code changes happen (none expected this
session): see handoff doc.

Reproduction setup for the broken scenario:
  ACDREAM_PROBE_BUILDING=1 ACDREAM_PROBE_RESOLVE=1
  ACDREAM_CAPTURE_RESOLVE=<path>.jsonl
  walk to cells 0xA9B40159/A in Holtburg (XY ≈ 110, 26)