# Session 2026-04-17 — Debug overlay → full-day retail-AC research marathon

## Timeline (morning → afternoon)

1. **Morning** — Debug overlay (TTF atlas + text batcher + HUD panels)
   and input-control tuning (per-mode sensitivity, RMB free-orbit, wheel
   zoom, F8/F9 sensitivity). Shipped in commit `ff325ab`.
2. **Midday** — User requested a deep investigation of the retail AC
   client's GUI subsystem. Dispatched 6 parallel Opus-4.7 high-effort
   agents, produced a 30,000-word research bundle + C# UI scaffold.
   Shipped in commit `7230c15`.
3. **Afternoon** — User asked to research **all** remaining major AC
   subsystems (R1-R13) while they were AFK for 2 hours. Dispatched 13
   parallel Opus-4.7 agents, produced a 78,000-word research bundle +
   master synthesis + 5 C# port scaffolds + rewritten roadmap.
   Shipped in commit `3f913f1`.

## What shipped today — three commits on main

| Commit    | Title                                                      | Insert |
|-----------|------------------------------------------------------------|--------|
| `ff325ab` | feat(ui): debug overlay + refined input controls           | 2,725  |
| `7230c15` | docs+feat(ui): retail UI deep-dive research + C# scaffold  | 8,042  |
| `3f913f1` | docs+feat: 13 retail-AC deep-dives + scaffolds + roadmap   | 15,312 |

**Total 26,079 lines added, 262 deleted, 55 new files.** All three
commits green on build + 470 tests.

## Key files to know

### Research (the goldmine)

- **`docs/research/deepdives/00-master-synthesis.md`** — start here. Nav
  hub for all 13 deep-dive slices; has the dependency graph and phase
  sequencing (E/F/G/H).
- **`docs/research/deepdives/r01-…-r13-…`** — 13 subsystem deep-dives,
  78,000 words total, every claim cited.
- **`docs/research/retail-ui/00-master-synthesis.md`** — UI framework
  synthesis. 6 slice docs total, ~30,000 words.
- **`memory/project_retail_research_index.md`** — permanent quick-lookup
  index for all 20 research docs.

### C# scaffolds (what to build on)

- `src/AcDream.App/UI/` — retail-style widget toolkit (`UiRoot`,
  `UiElement`, `UiPanel`, `UiHost`, event types matching retail codes)
- `src/AcDream.Core/Items/ItemInstance.cs` — R6 inventory data model
- `src/AcDream.Core/Spells/SpellModel.cs` — R1 spell cast state machine
- `src/AcDream.Core/Combat/CombatModel.cs` — R2 damage math
- `src/AcDream.Core/Audio/AudioModel.cs` — R5 audio interfaces
- `src/AcDream.Core/Vfx/VfxModel.cs` — R4 particle data model

### Updated

- `docs/plans/2026-04-11-roadmap.md` — rewritten Phase E-H based on
  the deep-dive synthesis. Old Phase E renamed to J.

## Architectural headline findings

1. **Retail UI widgets live in `keystone.dll`**, not `acclient.exe`.
   We implement our own retained-mode toolkit with retail-faithful
   event codes (0x01 click, 0x15 drag, 0x3E drop, 0x201 WM_LBUTTONDOWN)
   and consume the same portal.dat fonts + sprites for visual identity.
2. **Of 94 GameEvents** (S→C, `0xF7B0` envelope), **zero are handled**
   in acdream today. Biggest network-protocol gap; blocks inventory,
   chat, quest tracking, allegiance.
3. **Motion hooks are the trigger source** for audio + VFX + combat
   timing. R3 motion-hook expansion is the prereq for "feel alive"
   (Phase E).
4. **Weather is 95% client-side** — deterministic from Portal Year
   server clock. No `SetWeather` opcode.
5. **Retail lighting is D3D fixed-function** with 8-light cap, NO
   attenuation inside Range, then hard cutoff. "Feels right" not
   physical.

## Pickup for next session

**"What should I do tomorrow?" table:**

| If you want to… | Build… |
|---|---|
| Make the world feel alive (footsteps, sword whooshes, spell auras) | Phase E — R3 motion hooks → R5 audio → R4 particles |
| Actually fight monsters | Phase F.3 combat math + F.1 GameEvent dispatcher |
| Cast a buff + recall to lifestone | Phase F.4 spell state machine + F.1 GameEvent |
| See a character sheet | Phase F.2 item model + F.5 attributes panel (UI slice 05) |
| Enter a dungeon | Phase G.3 dungeon streaming (R9) |
| See a sky | Phase G.1 weather/day-night (R12) |
| Create a character in-client | Phase H.4 CharCreate (R7) |

The **master synthesis** (`docs/research/deepdives/00-master-synthesis.md`
§10) recommends a specific week-by-week sequence if the user wants
one-thing-at-a-time focus.

## Session feedback / lessons

- **Opus-4.7 high-effort parallel agents** are the right tool for
  decompile-intensive research. 13-agent swarm for R1-R13 completed in
  ~13 minutes, producing ~78,000 words of grounded work. Cost is high
  but quality justifies it for load-bearing research.
- **keystone.dll is a landmine** for anyone trying to "port the UI
  faithfully" — the widget toolkit isn't in the decompile we have. Own-
  toolkit approach is the only viable path.
- **Network protocol atlas (R8)** is the single biggest unblocker —
  nearly every other system depends on opcodes we don't handle.