erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(handoff): strategic pickup prompt for all 6 open items

Browse source 
After the 2026-05-21 session merged A1/A1.5/A1.6/A1.7 to main, six
discrete items remain. This doc maps them as a landscape rather than
single-phase:

- Collision (M2 critical path): A4 multi-cell BSP iteration → verify
  stairs → A2 PHSP inversion → A3 synthesis removal
- Rendering (M7 polish): indoor lighting + spotlight-projection bugs

The recommended order is A4 first (biggest user payoff, unblocks A3),
then stairs verification, A2 + A3 paired, lighting in a separate
session. A3 must NOT ship before A4 — that's the Bug A regression
from 2026-05-20.

Includes a pasteable session-start prompt that the user can box into
a fresh Claude Code session.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-20 15:10:23 +02:00
parent f80b53763f
commit fd9daddb37
1 changed files with 307 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

307
docs/research/2026-05-21-open-items-pickup-prompt.md Normal file
View file

@ -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.
```