acdream/docs/research/2026-05-19-indoor-walking-phase2-pickup-prompt.md

# Indoor walking Phase 2 shipped — fresh-session pickup prompt

**Status:** Indoor walking Phase 1 (Cluster A — BSP cluster) + Phase 2 (Portal-based cell tracking) both merged to `main` at `1af49b7` on 2026-05-19. 18 commits between them; `dotnet build` + `dotnet test` green; visual-verified by user (walls block from inside, multi-room navigation works, walking out through a door works).

This doc is the start-of-session brief for whoever picks up the next phase.

---

## What landed on main

**Indoor walking Phase 1 — BSP cluster** (commits `27d7de1` … `1f11ba9`):

- `[indoor-bsp]` + `[cell-cache]` diagnostic probes (`ACDREAM_PROBE_INDOOR_BSP` / `ACDREAM_PROBE_CELL_CACHE`).
- `WorldPicker` cell-BSP occlusion via new `CellBspRayOccluder` → **closes #86** (click selection no longer penetrates walls).
- Phase D's `ResolveOutdoorCellId` → `ResolveCellId` rename + AABB-based indoor cell promotion (partial fix for #84 — un-stuck the spawn-in-building case; the wall-pass-through portion stayed open until Phase 2).

**Indoor walking Phase 2 — Portal-based cell tracking** (commits `1969c55` … `eb0f772`):

- Extended `CellPhysics` with `CellBSP` (third BSP for point-in-cell), `Portals` (from `envCell.CellPortals`), `PortalPolygons` (resolved visible polys), `VisibleCellIds`. Deleted Phase D's `LocalAabbMin/Max` + `TryFindContainingCell`.
- New `CellTransit` static class — ports retail's `CObjCell::find_cell_list` family: `FindTransitCellsSphere` (indoor portal-neighbour walk), `AddAllOutsideCells` (24m landcell grid), `FindCellList` (top-level BFS driver), `CheckBuildingTransit` (outdoor→indoor entry via `BuildingObj` portals).
- `BSPQuery.PointInsideCellBsp` retyped from `PhysicsBSPNode?` → `CellBSPNode?` (was dead code; safe retype).
- New `BuildingPhysics` cache + `CacheBuilding` / `GetBuilding` on `PhysicsDataCache`. GameWindow caches each `LandBlockInfo.Buildings` entry at landblock-load.
- `PhysicsEngine.ResolveCellId`: indoor seeds delegate to `CellTransit.FindCellList`; outdoor seeds keep terrain-grid resolution + hook `CheckBuildingTransit` for outdoor→indoor entry.
- **Critical production fix** at `3ffe1e4`: pass `sp.GlobalSphere[0].Origin` (foot sphere CENTER) instead of `sp.CheckPos` (entity reference at the feet) to `ResolveCellId`. Without this fix the test point was always 0.02m below cell floor due to the +0.02f Z-bump → portal traversal never engaged in production.
- **Indoor walkable-plane synthesis** at `eb0f772`: when the indoor cell-BSP returns OK (no wall collision), find the floor poly under the player and call `ValidateWalkable` with the indoor plane instead of falling through to outdoor terrain. Closes the "stuck in falling animation" bug.

**Closed:** ISSUES.md #84, #85, #86, #87 all fully resolved.

**Filed for follow-up:**
- **#88** — Indoor static objects vibrate (bookshelves, open furnaces). Pre-existing; user spotted during Phase 2 testing.
- **#89** — Port `BSPQuery.SphereIntersectsCellBsp` for retail-faithful `CheckBuildingTransit`. Currently uses radius-less `PointInsideCellBsp`; entry fires ~0.5m later than retail.

**Diagnostic infrastructure that persists:**
- `[indoor-bsp]` — per cell-BSP `FindCollisions` call. Toggle: `ACDREAM_PROBE_INDOOR_BSP=1` or DebugPanel.
- `[cell-cache]` — per cached EnvCell at landblock load. Toggle: `ACDREAM_PROBE_CELL_CACHE=1`.
- `[cell-transit]` — every player CellId change. Toggle: `ACDREAM_PROBE_CELL=1`.
- `[check-bldg]` — per portal lookup inside `CheckBuildingTransit`. Gated on `ACDREAM_PROBE_INDOOR_BSP` (reused).

---

## How to start a fresh session

Copy the block below into a fresh Claude Code session in this repo. The model will load `CLAUDE.md` automatically and find the handoff docs on its own.

---

```
Pick up the acdream project. Indoor walking Phase 1 + Phase 2 just merged
to main at 1af49b7 (2026-05-19). Indoor walking is functionally complete:
walls block from inside, walking between rooms via doors works, walking
back outside through a door works.

1. Read docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md
   — that's the canonical record of what just shipped.

2. Read docs/ISSUES.md and note the open issues. The three follow-ups
   most-directly related to the just-shipped work:
   - #88: indoor static objects vibrate (bookshelves, furnaces)
   - #89: port BSPQuery.SphereIntersectsCellBsp for retail-faithful entry
   - #80: 2nd-floor goes very dark (pre-existing lighting issue, may be
     part of a broader Cluster B lighting phase)

3. **The user has set a focused track: indoor walking issues, collision,
   physics, and dungeons.** M2 (kill-a-drudge demo) is explicitly NOT
   the next direction. Stay on the indoor-experience track until they
   redirect.

   Candidates within that scope, ranked by my best guess at priority:

   A) **#83 — Walking up stairs broken**. Pure indoor/physics. The
      retail step-up logic (`CPhysicsObj::step_up`) doesn't yet handle
      indoor cell-BSP polys for stair geometry. Unblocks multi-floor
      cottages (the 2nd-floor darkness #80 also depends on actually
      reaching the 2nd floor) and dungeons (which are multi-level).
      Natural follow-on to Phase 2. ~3-5 days.

   B) **Dungeon stress test + adaptation**. Phase 2's portal traversal
      was developed and verified at Holtburg cottage (a small one-room
      building). Dungeons (Subway, Mite Burrow, Carved Stone) are
      multi-cell indoor spaces with complex portal graphs. Walk a
      character into a dungeon and see what breaks. Findings drive a
      follow-up scope. ~1-3 days for the test + variable for fixes.

   C) **#88 — Indoor object vibration** (bookshelves, open furnaces).
      Quality bug noticed during Phase 2 testing. Likely a per-frame
      transform recompute or EntityScriptActivator re-firing on cell
      changes (less likely after Phase 2 stabilized cell tracking but
      still possible). ~1-3 commits depending on root cause.

   D) **#89 — Port `BSPQuery.SphereIntersectsCellBsp`**. Retail-faithful
      entry timing for outdoor→indoor. Phase 2 ships with the documented
      ~0.5m late-entry approximation; this closes the gap. Pure physics
      polish. ~2-3 days.

   E) **Indoor lighting cluster** (closes #79/#80/#81/#82). Slightly
      adjacent — "indoor experience" but not strictly walking/collision.
      Worth considering once stairs (A) lands so you can actually reach
      the dark 2nd floor to verify lighting fixes. ~1-2 weeks.

   F) **#78 — Outdoor stabs visible through floor**. Visibility/stencil
      issue. Render side. Indoor-adjacent. ~3-5 days.

   My recommendation: **A (stairs)**. Reasons:
   - Pure indoor physics/collision — squarely in the user's stated track.
   - Unblocks both multi-floor cottages AND dungeons (B is gated on it).
   - Continues the natural arc from Phase 1 (walls) → Phase 2 (cell
     tracking) → Phase 3 (vertical movement / stairs).
   - The Phase 2 diagnostic infrastructure is still warm; reuse it.

4. CLAUDE.md rules apply:
   - No workarounds; fix root causes.
   - Use superpowers skills for major work (brainstorming → writing-plans
     → subagent-driven-development → finishing-a-development-branch).
   - Drive autonomously — Claude picks what to work on next; user reviews.
   - Visual verification by the user is the acceptance test for any
     rendering / collision / lighting fix.

5. The diagnostic infrastructure is ready for any indoor-cell-related
   investigation. Probes are runtime-toggleable via the DebugPanel
   ("Indoor: BSP collision" checkbox + the Cluster A render-side ones).

State the milestone and your chosen phase in the first action you take.
Then begin.
```

---

## Quick reference for the user

To start the new session: open a fresh Claude Code in the acdream repo and paste the boxed prompt above. Or just say:

> "Read `docs/research/2026-05-19-indoor-walking-phase2-pickup-prompt.md` and start on the next phase."

## Quick reference for the helper

Key files for the next phase (whichever path A/B/C/D you pick):

- **`docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md`** — the spec that just shipped. Reference for how Phase 2 was scoped.
- **`docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md`** — full Phase 2 evidence + commit list.
- **`docs/ISSUES.md`** — current OPEN items (note new #88 + #89 from Phase 2).
- **`docs/plans/2026-04-11-roadmap.md`** — shipped table; Indoor walking Phase 2 row is most recent.

If picking **Path A (#83 stairs — recommended)**:

- Retail oracle: `docs/research/named-retail/acclient_2013_pseudo_c.txt` — grep `step_up`, `step_sphere_up`, `find_walkable` for the existing logic. Our `BSPQuery` ports these for outdoor terrain at lines 1278+; the indoor analog needs the same flow against `cellPhysics.Resolved` floor-and-stair polys.
- Touchpoints likely: `src/AcDream.Core/Physics/TransitionTypes.cs` (where the new `TryFindIndoorWalkablePlane` lives — extend to handle step-up across vertical floor polys), `src/AcDream.Core/Physics/BSPQuery.cs::FindCollisions` Path 5/6 (which already handles outdoor step-up; needs indoor counterpart).
- Probe surface: `[indoor-bsp]` already captures every cell-BSP query; new probe `[step-up]` may be helpful.

If picking **Path B (dungeon stress test)**:

- Pick a small dungeon. Subway (`@0x0102 ...`) or Mite Burrow are good first targets — both are small enough to walk through quickly but complex enough to exercise multi-cell portal traversal.
- Run the launch with all indoor probes enabled (`ACDREAM_PROBE_INDOOR_BSP=1`, `ACDREAM_PROBE_CELL=1`, `ACDREAM_PROBE_CELL_CACHE=1`). Walk through every room. Note any wall-pass-through, stuck states, or cell-tracking failures.
- Findings drive scope. Probably uncovers stair issues (→ Path A) or sphere-vs-cell timing issues (→ #89).

If picking **Path C (#88 vibration)**:

- Likely candidates from the bug report: `EntityScriptActivator.OnCreate/OnRemove` re-firing on rapid CellId promotion/demotion (now less likely after Phase 2 stabilized cell tracking, but worth investigating); per-frame transform recompute drift on cell-static `WorldEntity` instances; particle-emitter offset accumulation.
- File this as a Phase rather than an issue if the root cause turns out to be the per-frame transform pipeline (multi-commit refactor).

If picking **Path E (indoor lighting)**:

- Start by re-reading the existing Cluster B sketches in the original Cluster A handoff:
  `docs/research/2026-05-19-indoor-followup-handoff.md` — section "The 9 follow-up issues" lists #79/#80/#81/#82 as Cluster B.
- Lighting code surfaces: `src/AcDream.App/Rendering/GameWindow.cs::UpdateSunFromSky` (indoor branch around line 8330+), `src/AcDream.App/Rendering/Shaders/mesh_modern.frag` (accumulateLights + indoor ambient), `src/AcDream.Core/Lighting/LightInfoLoader.cs`.
- Probe surface: there is no `[lighting]` probe yet — adding one will likely be the first commit in the brainstorm.
- **Note:** verify Path A (stairs) lands first or you can't reach the 2nd floor to test indoor lighting at altitude.