diff --git a/docs/research/2026-05-21-open-items-pickup-prompt.md b/docs/research/2026-05-21-open-items-pickup-prompt.md new file mode 100644 index 0000000..77d230a --- /dev/null +++ b/docs/research/2026-05-21-open-items-pickup-prompt.md @@ -0,0 +1,307 @@ +# Open items pickup prompt — 2026-05-21 session aftermath + +After the 2026-05-21 collision-fix session, six discrete items remain. +This doc gives a fresh session the full landscape: how the items +relate, what depends on what, what order makes sense. + +The pasteable session-start prompt is at the bottom of this doc. + +## The landscape at a glance + +| # | Item | Domain | Depends on | M2-blocker? | +|---|---|---|---|:---:| +| A4 | Walls walk-through in vestibule cells — multi-cell BSP iteration | Collision | — | **YES** | +| stairs | Stairs walk-through — likely falls out of A4 | Collision | A4 | YES (if still broken after A4) | +| A2 | PHSP inversion — `polygon_hits_sphere` early-return logically inverted vs retail | Collision math | — | Low (subtle correctness only) | +| A3 | Synthesis removal — delete `TryFindIndoorWalkablePlane`, rely on retail CP retention | Architectural | A4 + A2 | No (cleanup, retail-faithful) | +| L-indoor | Lighting indoors broken | Rendering | — | No (M7 polish) | +| L-spotlight | Items projecting spotlight on walls | Rendering | — | No (M7 polish) | + +## Two domains, one critical-path chain + +The 6 items split cleanly: + +**Domain 1 — Collision (M2 critical path).** A4, stairs, A2, A3. +These block "kill a drudge" because dungeons have drudges and dungeons +have walls/stairs/floors that need to behave correctly. The dependency +chain is: + +``` + A4 (multi-cell iteration) + │ + ┌──────────┴──────────┐ + ▼ ▼ + stairs (verify A3 (remove + post-A4) synthesis, + relies on + A4 retention) + ▲ + │ + A2 (PHSP fix + — also useful + standalone) +``` + +A4 is the biggest user-visible win and it unblocks A3. A2 is a small +self-contained correctness fix that pairs naturally with A3. Stairs +are likely an A4 side-effect. + +**Domain 2 — Rendering (M7 polish).** L-indoor + L-spotlight. These +don't affect gameplay correctness — the world just looks wrong. +Different code paths (lighting, not physics), different files, +different domain knowledge. Best tackled in their own session, +ideally after collision is solid so the visual artifacts are easier +to isolate. + +## Why this order + +1. **A4 first.** Biggest user-visible improvement. Closes the + "vestibule cells don't block walls" gap by querying every cell + the sphere overlaps, not just the one cell the player's center + is in. Retail oracle: `CTransition::check_other_cells` at + `acclient_2013_pseudo_c.txt:272717-272798`. Existing + `CellTransit.FindCellList` already enumerates the right cells; + A4 wires that into `FindEnvCollisions`. Probably 1-2 days. + +2. **Verify stairs after A4.** If A4 closes vestibule walls, it + probably also closes stairs (same architectural gap — stairs + span cells). If stairs still walk-through after A4, investigate + per-cell physics-poly coverage for stair geometry as a separate + sub-issue. + +3. **A2.** One-line flip in `PolygonHitsSpherePrecise` + ([BSPQuery.cs:117](src/AcDream.Core/Physics/BSPQuery.cs:117)) plus + a unit test for the tangent boundary. Improves correctness across + every BSP query (walls, step-up, step-down). Pairs cleanly with A3. + +4. **A3.** Once A4 + A2 land, the architectural cleanup becomes safe. + Delete `TryFindIndoorWalkablePlane` (TransitionTypes.cs:1294) and + the synthesis call site. Retail's grounded path doesn't synthesize + CP — it retains via Mechanisms A/B/C (already in our code at + BSPQuery.cs:1615, TransitionTypes.cs:2618, TransitionTypes.cs:896). + The 2026-05-20 session tried A3 prematurely (Bug A) and reverted + because the doorway-exit case relied on multi-cell iteration that + wasn't there. A4 closes that gap. + +5. **Lighting (M7).** Separate session. Different domain. Defer until + M2 ships. + +## Per-item starter notes + +### A4 — multi-cell BSP iteration + +**Read first:** +- §"Phase A4" of `docs/research/2026-05-21-collision-fixes-shipped-handoff.md` +- `acclient_2013_pseudo_c.txt:272717-272798` (`check_other_cells`) +- [`src/AcDream.Core/Physics/TransitionTypes.cs:1407-1559`](src/AcDream.Core/Physics/TransitionTypes.cs:1407) (`FindEnvCollisions` — change site) +- [`src/AcDream.Core/Physics/CellTransit.cs`](src/AcDream.Core/Physics/CellTransit.cs) (helpers already exist) + +**Approach:** +- Extract a "cell_array" set from the player's current cell via the + existing CellTransit BFS. +- Iterate each cell, run `BSPQuery.FindCollisions` against each one. +- Combine results: any cell returning Collided/Adjusted halts; any + cell returning Slid is remembered; all OK = return OK. + +**Acceptance:** Walk into the Holtburg inn vestibule (cell `0xA9B40164`). +Walls in cell `0xA9B40157` should now block when the player's sphere +extends into them, even though the player's center is still in the +vestibule. + +### Stairs walk-through + +**Strategy:** verification-only, after A4. Launch with the same probe +set, walk up the inn stairs, watch the `[indoor-bsp]` results. If +stair hits fire correctly, done. If not, investigate the cell's +physics-poly data — stairs may be packed as static objects rather +than cell-structure polys. + +### A2 — PHSP inversion fix + +**Bug:** [`BSPQuery.cs:117`](src/AcDream.Core/Physics/BSPQuery.cs:117) +has `if (MathF.Abs(dist) > rad) return false;` — bails when sphere +is FAR from plane. Retail's `polygon_hits_sphere_slow_but_sure` at +`acclient_2013_pseudo_c.txt:322509-322517` does the opposite — bails +when sphere is OVERLAPPING plane. + +**Fix:** flip the comparison. New unit test for the tangent boundary +(sphere center at `radius` distance from plane → continue, not +reject). + +**Caveat:** doesn't fix walkable synthesis on its own — +`AdjustSphereToPlane` also rejects at the tangent boundary (strict +`<` check on interp). The two together gate the synthesis. Fixing A2 +alone changes which side of the boundary the rejection happens on +but doesn't close the gap. Pair with A3 for the full benefit. + +**Read first:** +- §"Phase A2" of `docs/research/2026-05-21-collision-fixes-shipped-handoff.md` +- `docs/research/2026-05-21-walk-miss-capture-findings.md` (the + smoking-gun analysis of the 2 cm boundary) + +### A3 — synthesis removal + +**Bug:** retail's grounded path doesn't re-synthesize ContactPlane. +It retains via three mechanisms (Path 4 land, LKCP proximity restore, +post-OK step-down probe — all already in our code). Our +`TryFindIndoorWalkablePlane` runs every frame and is unfaithful. + +**Fix:** delete `TryFindIndoorWalkablePlane` ([TransitionTypes.cs:1294](src/AcDream.Core/Physics/TransitionTypes.cs:1294)) +and its call site. ~500 lines deleted. + +**Critical prerequisite:** A4 must ship first. The 2026-05-20 session +tried A3 prematurely (Bug A) and reverted because doorway transitions +caused free-fall — Mechanism C couldn't find a floor poly at the +threshold because the indoor cell's BSP had no coverage past the +doorway, and multi-cell iteration wasn't there to query the adjacent +cell. + +**Read first:** +- `docs/research/2026-05-20-indoor-walking-bug-a-handoff.md` + (Bug A's premise + reversion) +- §"Phase A3" of the 2026-05-21 handoff + +### L-indoor — lighting broken inside + +**Symptom:** lights inside buildings don't illuminate correctly. + +**Likely areas:** +- Cell-light association (which lights belong to which cell) +- Light visibility culling (visible-cells set + light bounds) +- Per-light projection matrix indoors + +**Domain:** rendering, not physics. Separate session. + +### L-spotlight — items projecting spotlight on walls + +**Symptom:** held items (torches, etc.) project spotlight effects +onto walls in unexpected directions. + +**Likely areas:** +- Per-entity light direction transform +- LightingHookSink owner-tracking + +**Domain:** rendering, not physics. Separate session. + +## CLAUDE.md rules to remember + +1. **Work-order autonomy.** You pick what to work on. Recommended + order above but adjust if you find something blocking. +2. **No workarounds, retail-faithful.** Same rule that drove A1 + through A1.7. If a fix starts to look like a band-aid, stop. +3. **Probe-first, design-second.** Already have rich probes + (`[indoor-bsp]`, `[cell-transit]`, `[cell-cache]`, + `[walk-miss]`, `[floor-polys]`, `[resolve-bldg]`). Capture before + theorizing. +4. **Visual verification is the acceptance test.** Walk the building + after each fix. +5. **Stop signals.** Three failed visual verifications in a session = + write a handoff, don't push for a fourth. +6. **Don't enable `ACDREAM_PROBE_RESOLVE` for live play.** It lagged + the client last session (400k+ lines at 30 Hz). +7. **Subagent policy: Sonnet for implementers, Opus only for + load-bearing review.** +8. **Worktrees.** Use the `superpowers:using-git-worktrees` skill to + create a fresh worktree branched from main before touching code. + +## Launch command (light probes only) + +```powershell +$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" +$env:ACDREAM_LIVE = "1" +$env:ACDREAM_TEST_HOST = "127.0.0.1" +$env:ACDREAM_TEST_PORT = "9000" +$env:ACDREAM_TEST_USER = "testaccount" +$env:ACDREAM_TEST_PASS = "testpassword" +$env:ACDREAM_DEVTOOLS = "1" +$env:ACDREAM_PROBE_INDOOR_BSP = "1" +$env:ACDREAM_PROBE_CELL = "1" +$env:ACDREAM_PROBE_CELL_CACHE = "1" +dotnet build -c Debug +dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | + Tee-Object -FilePath "launch.log" +``` + +UTF-16LE → UTF-8 conversion for grep: + +```powershell +Get-Content launch.log -Encoding Unicode | + Out-File launch.utf8.log -Encoding utf8 +``` + +--- + +## The pasteable session-start prompt + +Open a new Claude Code session in the main acdream worktree +(`C:\Users\erikn\source\repos\acdream`, branch `main` at SHA +`f80b537` or later). Then paste: + +--- + +``` +Pick up the acdream open-items cleanup. After the 2026-05-21 session, +6 items remain across collision + rendering. + +1. Read docs/research/2026-05-21-open-items-pickup-prompt.md FIRST. + It maps the 6 items, their dependencies, and the recommended + order (A4 → verify-stairs → A2 → A3 → lighting in a separate + session). Each item has its own "Read first" anchor list inside. + +2. Branch state: main is at f80b537 with all 2026-05-21 fixes + landed (A1, A1.5, A1.6, A1.7 + probe spike + handoff docs). + Build green, 1129-test baseline holds, four user-visible + improvements visually verified. Local main is ahead of + origin/main (origin at 7034be9); push only if explicitly asked. + +3. **Set up isolation FIRST.** Use the superpowers:using-git-worktrees + skill to create a fresh worktree from main. Don't work directly + in the parent worktree. The 2026-05-21 session's worktree + (claude/lucid-goldberg-1ba520) is identical to main and can be + removed. + +4. Recommended first phase: **A4 (multi-cell BSP iteration)**. It + has the biggest user-visible payoff (closes vestibule-cell wall + walk-through, likely closes stairs too) and unblocks A3 + architectural cleanup. Retail oracle is at + acclient_2013_pseudo_c.txt:272717-272798 (CTransition::check_other_cells). + Existing CellTransit helpers (FindCellList, FindTransitCellsSphere, + AddAllOutsideCells) already enumerate the right cells; A4's + work is wiring them into Transition.FindEnvCollisions. + +5. Use the superpowers:brainstorming skill before writing A4 code. + A4 is a real architectural change (multi-day, 2 files modified + + tests) and deserves its own spec + plan. Don't shortcut it. + +6. CLAUDE.md rules: + - No workarounds. Retail-faithful. + - Probe-first, design-second. + - Visual verification at Holtburg inn cell 0xA9B40164 vestibule + is the A4 acceptance test (walls in adjacent cell 0xA9B40157 + should block when the player straddles the boundary). + - Don't enable ACDREAM_PROBE_RESOLVE for live play (lags the + client). Use [indoor-bsp] + [cell-transit] + [cell-cache] only. + - Three failed visual verifications = handoff, not a fourth attempt. + +7. M2 ("kill a drudge") is the active milestone. A4 + stair + verification + A2 + A3 are all on the M2 critical path because + dungeons need walkable indoor space. Lighting is M7 polish; + defer. + +8. Launch command (light probes only): + $env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" + $env:ACDREAM_LIVE = "1" + $env:ACDREAM_TEST_HOST = "127.0.0.1" + $env:ACDREAM_TEST_PORT = "9000" + $env:ACDREAM_TEST_USER = "testaccount" + $env:ACDREAM_TEST_PASS = "testpassword" + $env:ACDREAM_DEVTOOLS = "1" + $env:ACDREAM_PROBE_INDOOR_BSP = "1" + $env:ACDREAM_PROBE_CELL = "1" + $env:ACDREAM_PROBE_CELL_CACHE = "1" + dotnet build -c Debug + dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | + Tee-Object -FilePath "launch.log" + +State the milestone + chosen phase in your first action. +```