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. Per CLAUDE.md's work-order autonomy rule, YOU pick the next phase.
   Candidates ranked by my best guess at priority:

   A) Indoor lighting cluster (closes #79/#80/#81/#82) — completes the
      "indoor feels right" visual story. The wall-blocking is done; the
      visible darkness on upper floors and broken atmospheric lighting
      indoors is the next thing the player notices. ~1-2 weeks.

   B) Continue M2 critical path — F.2 (Inventory panel), F.3 (Combat
      math + damage flow), F.5a (dev panels), L.1c (combat animation),
      L.1b (command router). Kill-a-drudge demo. ~6-10 weeks total but
      can be sliced per-phase.

   C) #88 indoor vibration — quick to fix once diagnosed; pre-existing
      annoyance. 1-3 commits depending on root cause.

   D) Triage docs/ISSUES.md to clear chronic-open items (#2 lightning,
      #4 sky horizon-glow, #28 aurora, #29 cloud thinness, #37 humanoid
      coat, #41 remote-motion blips). ~1 hour, surfaces what's actually
      blocking M2 vs nice-to-have.

   My recommendation: A. Indoor lighting closes the indoor-experience
   loop. The user explicitly mentioned darkness as a noticeable issue
   during Phase 2 testing, and the diagnostic infrastructure from
   Phase 2 is still warm. But pick based on your read of the codebase
   + recent commits.

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

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