acdream/docs/research/2026-05-25-door-bug-cdb-retail-trace-findings.md

Door bug — retail cdb trace + NegPolyHit dispatch findings

2026-05-25, continuation of door-collision investigation

TL;DR

cdb attached to retail at a Holtburg cottage door while user walked the inside-out off-center scenario. The smoking-gun trace identified the real collision-recording function: SPHEREPATH::set_neg_poly_hit fired hundreds of times during the walk; SPHEREPATH::set_collide, COLLISIONINFO::set_collision_normal, set_sliding_normal, add_object ALL fired zero times.

In our codebase, NegPolyHitDispatch exists but is never called from any production code path — it's dead code. The path.NegPolyHit flag is therefore never set. The downstream handler in Transition.TransitionalInsert was a stub that just cleared the flag.

Two-part fix attempted this session:

1. BSPQuery.FindCollisions Path 5 (Contact branch) restructured to call NegPolyHitDispatch when sphere 0 had a near-miss polygon set but didn't fully penetrate (mirrors retail's var_5c != 0 case at acclient_2013_pseudo_c.txt:0053a6ce-0053a6fb).

2. Transition.TransitionalInsert NegPolyHit handler rewritten to dispatch to step_up + step_up_slide (NegStepUp=true) or record collision normal + return Collided (NegStepUp=false).

Result: fix doesn't fully close the bug. User still squeezes through. Diagnostic [neg-poly-dispatch] probe shows ZERO hits in production — the BSP Path 5 changes don't surface NegPolyHit for this case.

Why the fix doesn't fire

Retail's BSPTREE::find_collisions calls vtable->sphere_intersects_poly(localspace_sphere, var_78_6, var_74_6, var_70_8) which:

• Returns eax_10: non-zero on full sphere-vs-poly hit
• Writes var_5c: closest polygon pointer, set EVEN ON NEAR-MISS (BSP traversal sets it when entering a leaf containing candidate polys, regardless of intersection)

So retail records "near miss" polygons during BSP traversal. The caller dispatches set_neg_poly_hit(1, var_5c + 0x20) when sphere 0 returned eax_10 == 0 but var_5c != 0.

Our SphereIntersectsPolyInternal only sets hitPoly on actual hits. Near-miss polygons are NOT recorded. So the Path 5 branch if (hitPoly0 is not null) is false → no NegPolyHitDispatch call → no NegPolyHit set → no dispatch in TransitionalInsert.

The deeper fix needed

Implement retail's "BSP traversal records closest near-miss polygon" behavior in SphereIntersectsPolyInternal (or a sibling). The function should return TWO outputs:

• bool hit — true if sphere fully penetrates a polygon
• ResolvedPolygon? closestPoly — set during traversal to the polygon that the sphere came closest to (in the BSP node walk), regardless of whether the full intersection test passed

This requires modifying the BSP recursion to track the "closest considered" polygon. Retail's sphere_intersects_poly likely tracks this as a side effect of testing each candidate polygon during the traversal.

Once that's in place, the existing Path 5 changes + TransitionalInsert NegPolyHit dispatch should fire correctly and produce the block.

What the cdb trace proved

Symbol	v1 hits	v2 hits	v3 hits
CPhysicsObj::FindObjCollisions	161,081	196,608	196,608
CCylSphere::collides_with_sphere	35,527	—	—
SPHEREPATH::set_collide	0	—	—
COLLISIONINFO::set_collision_normal	—	0	—
COLLISIONINFO::set_sliding_normal	—	0	—
COLLISIONINFO::add_object	—	0	—
BSPTREE::slide_sphere	—	—	0
CTransition::cliff_slide	—	—	0
SPHEREPATH::set_neg_poly_hit	—	—	303+ (fires)
CTransition::insert_into_cell	—	—	3,652

Retail records collisions almost exclusively via SPHEREPATH::set_neg_poly_hit during normal-grounded-motion. The COLLISIONINFO normal/sliding setters fire essentially never for walking-into-walls scenarios. Our investigation premise was wrong; the cdb data forced the correction.

Apparatus + scripts committed

• tools/cdb/door-inside-out.cdb — v1 (set_collide check)
• tools/cdb/door-inside-out-v2.cdb — v2 (COLLISIONINFO family)
• tools/cdb/door-inside-out-v3.cdb — v3 (wide net, found set_neg_poly_hit)
• tools/cdb/symbol-probe.cdb — verifies symbol resolution

Pickup prompt for next session

A6.P4 door inside-out: cdb trace + NegPolyHit dispatch landed
(BSPQuery.FindCollisions Path 5 + TransitionalInsert NegPolyHit
branch) but the fix doesn't fire because our SphereIntersectsPolyInternal
doesn't record near-miss polygons. Retail's sphere_intersects_poly
sets a "closest polygon" output even on non-hits via BSP traversal
side-effect; our equivalent only sets it on full hits.

  Read docs/research/2026-05-25-door-bug-cdb-retail-trace-findings.md

  State both altitudes:
    Currently working toward: M1.5 — Indoor world feels right
    Current phase: A6.P4 door bug — implement near-miss polygon
                   recording in SphereIntersectsPolyInternal.

  First move: read SphereIntersectsPolyInternal in
  src/AcDream.Core/Physics/BSPQuery.cs (the function used at the
  Path 5 entry). Identify where polygons are tested during BSP
  traversal. Add a "closestPoly" output param that's set to ANY
  polygon considered during traversal (not just hit polygons).
  Then the Path 5 branch `if (hitPoly0 is not null)` will fire on
  near-miss cases, NegPolyHitDispatch will set NegPolyHit, and the
  TransitionalInsert dispatch (already landed) will block the sphere.

  Retail oracle: BSPTREE::find_collisions + sphere_intersects_poly
  vtable call at acclient_2013_pseudo_c.txt:0053a630-0053a6fb.

  Visual verification: same scenario (Holtburg cottage door,
  inside-out, ~50cm off-center). Should block fully, no squeeze-through.
  Outside-in should still work. Issue #98 cellar cap must still pass.