# Door collision per-part BSP session — handoff

**Date:** 2026-05-24 (long session, multiple phases)
**Branch:** `claude/strange-albattani-3fc83c`
**Worktree:** `C:\Users\erikn\source\repos\acdream\.claude\worktrees\strange-albattani-3fc83c`

This handoff documents an A6.P4-driven session that:
1. Shipped A6.P4 slice 1 (real cleanup, didn't close #99)
2. Investigated why doors don't block (apparatus-first)
3. Brainstormed + speced a per-part BSP collision design
4. Shipped most of the implementation (Tasks 1-6 of 10)
5. Discovered Task 7's per-part BSP doesn't actually fix the door bug
6. Reverted Task 7 and paused for further investigation

---

## TL;DR

**Shipped (real commits):**
- `b49ed90` — A6.P4 slice 1: drop the `< 0x0100u` filter in
  `ShadowObjectRegistry.GetNearbyObjects`'s portalReachableCells loop,
  rename `indoorCellIds` → `portalReachableCells`. Real cleanup; the
  `FindCellSet`-already-includes-outdoor-cells discovery means doors at
  building thresholds should be reachable from indoor primary spheres
  via the exit-portal logic. But the user-visible #99 close was wrongly
  claimed in the commit message — see below.
- `d71ceab` — design spec: per-part BSP for server-spawned entities.
- `8d4f14c` — 10-task implementation plan.
- `ab4278c` — Task 1: ShadowShape record.
- `7f5c287` — Task 2: ShadowShapeBuilder.FromSetup + 7 unit tests.
- `1454eab` — Task 3: ShadowEntry adds LocalPosition + LocalRotation.
- `fca0a13` — Task 4: ShadowObjectRegistry.RegisterMultiPart + 6 tests +
  Deregister clears `_entityShapes` (Task 6 folded in).
- `d5ffb03` — Task 5: UpdatePosition recomposes multi-part transforms
  via `_entityShapes`.
- `3e5dc8c` — Task 6 regression test: stray UpdatePosition after
  Deregister is no-op.
- `1498697` — `[cyl-test]` diagnostic probe (broadly useful).

**Reverted (Task 7 staged, then `git restore`):** the
`RegisterLiveEntityCollision` refactor at `GameWindow.cs:3076`. Reverted
because visual verification showed the per-part BSP shape didn't actually
block the door — only the small Cylinder did, and even that only at
dead-center approach.

**Still pending:** Tasks 7-10 in the plan + the real fix for door
collision.

---

## What we learned (apparatus-first findings)

### Door Setup 0x020019FF shape inventory (live dump captured 2026-05-24)

```
[door-setup-dump] setupId=0x020019FF setupRadius=0.141 setupHeight=0.200
                  cylSpheres=0 spheres=1 parts=3 placementFrames=1
                  stepUp=0.090 stepDown=0.090
[door-setup-dump]   sphere[0] r=0.100 origin=(0.000,0.000,0.018)
[door-setup-dump]   part[0] gfxObj=0x010044B5
[door-setup-dump]   part[1] gfxObj=0x010044B6
[door-setup-dump]   part[2] gfxObj=0x010044B6
```

### Per-shape registration (post-Task-7-experiment)

With `ShadowShapeBuilder.FromSetup` running over Setup 0x020019FF in the
live launch, doors registered 2 shadows each:

1. `type=Cylinder radius=0.100 height=0.200 localPos=(0,0,0.018)` — from
   the Sphere converted to short Cylinder.
2. `type=BSP gfxObj=0x010044B5 radius=2.000 localPos=(-0.006,0.125,1.275)` —
   from part 0 (the frame). The other two parts (`0x010044B6` x2) have
   `BSP=null` → skipped.

### Collision behavior (visual verified by user, 2026-05-24)

| Scenario | Result |
|---|---|
| Cellar climb (#98 regression check) | ✅ Works |
| Door from outside, dead center | ⚠️ Partial — only the small Cylinder blocks; player stops at the center |
| Door from outside, ~50 cm off-center | ❌ Pass through |
| Door from outside (Use → swing) | ✅ Swing animation works, door opens |
| Indoor furniture (#91 regression check) | ✅ Works |
| Outdoor exterior wall (regression check) | ✅ Works |
| Door from inside walking out | ❌ Pass through |

### Diagnostic evidence

In 188K+ resolve lines from the launch:
- `Door 0xF4249 : 85 cyl-tests, 13 resolve hits attributed`
- `Door 0xF424F : 227 cyl-tests, 16 resolve hits attributed`
- **Zero `[resolve-bldg]` attributions for any door**

Conclusion: the per-part BSP at `0x010044B5` produces NO collision hits.
Either:
1. The PhysicsBSP at that GfxObj has no collision-bearing polygons
   (only visual polys), OR
2. Our world-to-part-local sphere transform is wrong, OR
3. The broadphase rejects it (unlikely with radius=2.0 default).

---

## Why this differs from M1 visual verification on 2026-05-13

The user remembers doors blocking on the M1 demo verification. That
demo was "open the inn door" — clicking + watching the swing animation.
The walking-through-an-open-door part was not deliberately tested. The
closed-door blocking was probably observed accidentally when the user
walked directly at a center-of-doorway cylinder; the 14 cm cylinder is
just wide enough to catch a sphere at exactly the centerline. Today's
careful off-center test exposed the gap.

So nothing regressed since 2026-05-13. The bug has been latent. Our
investigation just exposed it.

---

## Investigation gap to close before the next implementation attempt

The per-part BSP design IS retail-faithful in shape (matches
`CPhysicsObj::FindObjCollisions` → `CPartArray::FindObjCollisions` →
`CPhysicsPart::find_obj_collisions` → `CGfxObj::find_obj_collisions`).
But it didn't surface a working blocker for the cottage doors. Three
hypotheses, ranked by likelihood:

### Hypothesis A (most likely): Part 0x010044B5 has no collision-bearing PhysicsBSP polygons

The Setup defines visual parts. Some parts (especially decorative
hardware) may have a PhysicsBSP that's just the visual mesh's bounding
volume, with no walls or threshold polygons. The door's collision might
genuinely be just the small Cylinder by retail design, and retail
gets full doorway blocking from the **building's BSP** having a narrow
gap exactly the size of the door's Cylinder (~28 cm × 28 cm).

**How to verify:** Dump `0x010044B5`'s PhysicsBSP polygons via
`ACDREAM_DUMP_GFXOBJS=0x010044B5`. Inspect the polygons. If they're
just an axis-aligned bounding box matching the visual mesh, no useful
collision data exists at the part level.

### Hypothesis B: Building BSP has a wide doorway gap that retail's tiny cylinder doesn't fill

A retail building (e.g., cottage interior 0x020XXXXX) has its walls as
BSP polygons. The doorway is a gap. If the gap is ~2 m wide (visual
opening), the 28 cm cylinder doesn't span it — even retail wouldn't
block.

**How to verify:** Open RenderDoc on retail (or our client) and inspect
the cottage interior GfxObj BSP at the doorway. Measure the gap. If
it's narrow (~30 cm), the small cylinder fills it. If wide (~2 m), the
cylinder is decorative and the actual blocker must come from elsewhere.

### Hypothesis C: Retail uses a different collision mechanism entirely

Doors might use Setup.Radius / Setup.Height (the bounding cylinder
dimensions, 0.141 × 0.200 — slightly larger than our Sphere-derived
0.100 × 0.200) AS THE PRIMARY BLOCKER, not the Sphere. Or retail
overrides shape selection for `ItemType==Door` specifically.

**How to verify:** Attach cdb to a live retail client at a cottage
doorway, set a breakpoint on `CPhysicsObj::FindObjCollisions` for the
door's PhysicsObj, observe which shape branch fires.

---

## Recommended next-session approach

Per the project's "apparatus-first for physics divergences" rule
(`feedback_apparatus_for_physics_bugs.md`):

1. **Stop coding.** Don't try another fix without evidence.
2. **Dump 0x010044B5's PhysicsBSP** via `ACDREAM_DUMP_GFXOBJS=0x010044B5`.
   If it has zero floor-touching polygons → Hypothesis A confirmed.
3. **Attach cdb to retail** at a cottage doorway. Trace which shapes
   block the player. See `project_retail_debugger.md` for the toolchain.
4. **Cross-reference ACE source** for Door collision (if any) — search
   `references/ACE/Source/ACE.Server/Physics/` for door handling.
5. **Re-brainstorm** with the new evidence. The Task 1-6 infrastructure
   stays (it's correctly modeling retail's CPhysicsObj-per-entity
   with parts iterated for collision). Only the SHAPES we register
   need to change.

The infrastructure investment was not wasted. The architecture is right.
We just registered the wrong shapes from the door setup.

---

## What's in the tree right now

```
$ git log --oneline -15
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
1454eab feat(phys): ShadowEntry adds LocalPosition + LocalRotation
7f5c287 feat(phys): ShadowShapeBuilder.FromSetup
ab4278c feat(phys): add ShadowShape record (no callers yet)
8d4f14c docs(phys): implementation plan — per-part BSP for server-spawned entities
d71ceab docs(phys): design spec — per-part BSP collision for server-spawned entities
b49ed90 feat(phys): A6.P4 slice 1 — portal-reachable cellSet includes outdoor cells
b3ce505 fix(phys): A6.P3 #98 — gate outdoor shadow radial sweep on indoor primary cell
b55ae83 docs: A6.P3 #98 resolution + A6.P4 design + #99/#100 filed
3e3cd77 docs(handoff): A6.P4 pickup handoff — full session-resume artifact
```

All 49+ tests pass:
- 24 ShadowObjectRegistryTests
- 7 ShadowShapeBuilderTests
- 8 ShadowObjectRegistryMultiPartTests
- 11 CellarUpTrajectoryReplayTests

Pre-existing 6-8 baseline static-state-leakage failures in the broader
Physics suite are unchanged from prior sessions.

**No-commit state:** working tree is clean. `git status --short`
shows only untracked investigation logs (`a6-issue98-*.log`,
`launch-task7-*.log`, etc. — these accumulate from launches and don't
get committed).

---

## #99 status: still open

The A6.P4 slice 1 commit message claimed "Closes #99" but the visual
verification today proves that's premature. Slice 1 did a real cleanup
(removed a misleading filter) but didn't fully address the user-visible
door-block bug. Update `docs/ISSUES.md` accordingly (issue #99 remains
OPEN; the per-part BSP architecture is NEW infrastructure built today
that will support the eventual fix once we identify the right shapes).

---

## Pickup prompt for next session

```
Door collision still doesn't fully block in M1.5 Holtburg. Per-part BSP
infrastructure shipped 2026-05-24 (Tasks 1-6 of A6.P4 plan), but the
specific shapes we register from door setup 0x020019FF don't catch the
player. Need apparatus-first investigation:

  Read docs/research/2026-05-24-door-collision-session-handoff.md
  (this doc — recent session handoff)

  State both altitudes:
    Currently working toward: M1.5 — Indoor world feels right
    Current phase: A6.P4 — investigation phase to find the right door
                   collision shapes; per-part BSP infrastructure
                   already shipped; need to verify Hypothesis A/B/C
                   before any more implementation

  First moves (in order):
    1. Dump GfxObj 0x010044B5's PhysicsBSP via ACDREAM_DUMP_GFXOBJS.
       Does it have collision-bearing polygons or just visual?
    2. If yes → debug the per-part transform (likely Hypothesis B/C
       wrong); if no → confirm Hypothesis A and pivot strategy.
    3. Either way, attach cdb to retail at a cottage doorway to see
       what retail actually blocks with.

  DO NOT speculate-and-fix again. The session 2026-05-24 already
  burned a Task 7 attempt on a hypothesis that turned out wrong. The
  6 committed implementation tasks (Tasks 1-6) are correct and stay.
  Only Tasks 7-10 of the plan need to change once we know the right
  shapes.
```