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.