# Session 2026-04-17 — Debug overlay → full-day retail-AC research + client bug-bash

## Timeline

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`.
4. **Evening** — Back to hands-on client debugging. Fixed three
   significant live-play bugs one after another: NPC clothing by-angle
   flicker, run-animation sync with retail observers, and jump animation.
   Shipped in `3308cdd` + `08ea2c0` + `6bce9b8`.

## What shipped today — seven 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 |
| `d951304` | memory: session handoff + permanent research index                 |   222  |
| `3308cdd` | fix(movement+anim+session): clothing dedup + motion wire + jump-skill |   272 |
| `08ea2c0` | feat(anim): motion-action-queue infrastructure + findings           |   128  |
| `6bce9b8` | fix(anim): **jump animation via Falling SubState**                  |    71  |

**Total ~26,800 lines added, 55+ new files.** All 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.
6. **Retail jumps are a SubState swap, not an Action.**
   `MotionCommand.Falling (0x40000015)` is a SubState cycle whose
   motion-table Links carry the leap-up AND landing transitions. No
   action-queue port was needed; `SetCycle(Falling)` while airborne
   + normal SetCycle on land gives retail-faithful jump animation.
   Costly lesson: I first tried Action (mask 0x10) + Modifier (mask
   0x20) routing and broke the character into a torso. Empirical
   motion-table dump is always worth more than my guesses.
7. **ACE's MovementData only computes ForwardSpeed for the
   WalkForward/WalkBackwards branch.** Sending `RunForward` directly
   leaves observers at `speed=0`. Correct wire format is
   `WalkForward + HoldKey.Run + ForwardSpeed=runRate` — ACE
   auto-upgrades to `RunForward` for broadcast. Our own client uses
   a separate LocalAnimationCommand to play the RunForward cycle
   locally while the wire stays WalkForward.
8. **Instance batching by GfxObjId alone is catastrophic for NPCs.**
   Every humanoid shares the same body GfxObjs; grouping them all
   into one DrawInstanced batch and using the first entry's texture
   for the whole batch meant whoever sorted first at a given camera
   angle "won" the palette. Fixed by keying instance groups on
   `(GfxObjId, PaletteHash XOR SurfaceOverridesHash)`.

## Client state at end of session

Client runs, connects to local ACE, in-world as `+Acdream`. Working:
- Player moves, turns, strafes, jumps, lands. Jump animation plays via
  Falling SubState. Run animation broadcasts correctly to retail
  observers (WalkForward + HoldKey.Run wire format).
- Holtburg NPCs render with correct clothing / palette, stable across
  camera angles (instance-batching dedup fix).
- Debug overlay: F1 help, F2 collision wireframes, F3 dump, F4/F5/F6
  panel toggles, F8/F9 sensitivity tuning.
- Mouse: per-mode sensitivity (Chase 0.15x, Fly/Orbit 1.0x), RMB
  free-orbit, wheel zoom.

Known small issues (non-blocking):
- Walk-backward animation's first step has a tiny jitter.
- Running → stopping has a slight twitch (missing SubState→Ready link
  blend).
- Some retail chars have legs through the ground (Z-offset bug —
  parked for later diagnosis).
- Jump feel is 95% retail, not 100%.

## 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) |
| Polish animation (backward jitter + stop twitch) | Link-cycle walker for SubState→Ready transitions |
| Remote-char feet in ground | Z-offset diagnosis (compare server-sent Z vs our terrain at observer XY) |

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.
- **Diagnostic dumps > guessing.** The jump-animation saga took 4
  launches + reverts before I added a diagnostic that dumped the
  actual Links dict contents. That one dump (revealing
  `Links[0x003D0007]` had an inner entry `0x40000015 Falling`)
  instantly showed the right approach. Trust empirical motion-table
  contents over any assumption about retail structure. Add dumps
  liberally when the code is non-cooperative; remove when verified.
- **Retail animation lexicon:** Style (mask 0x80), SubState (0x40),
  Modifier (0x20), Action (0x10). SubStates are looping cycles
  (Ready/Walk/Run/Falling/Crouch). Modifiers overlay on a cycle.
  Actions are transitions held in the Links dict (emotes, attacks).
  For any new animation: dump the motion table, find where the
  target motion lives, use SetCycle if it's in Cycles or the
  Links/Modifiers path if it's transitional.
- **Wire-format vs local-animation separation:** we now route the
  wire ForwardCommand separately from the local animation command
  (RunForward cycle locally, WalkForward+HoldKey.Run on wire).
  Matching ACE's broadcast expectations and retail client expectations
  simultaneously sometimes requires two independent command streams.