# 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.