acdream/docs/research/2026-08-10-settings-track-handoff.md

# Settings track handoff — retail Options panel campaign (fresh session)

Written 2026-08-10 at the close of Campaign CH (chat parity, CLOSED
USER-ACCEPTED the same day). The user pivoted the alpha program's settings
track: the target is **retail's four-tab Options panel**, not merely a
status-bar button over the existing F11 panel. The user supplied four
retail screenshots (transcribed below — the fresh session cannot see
them). Deep research REQUIRED before implementation, campaign-style.

## What the user showed (retail screenshots, transcribed)

The options button opens a tall panel with four tabs:
**Gameplay Options | Character | Chat | Config**, with Apply / Reset /
Defaults buttons at the bottom of (at least) the Character tab. Options
render as LED-style dots (lit green = on) beside labels, grouped under
gold section headers, with a scrollbar.

### Tab 1 — "Gameplay Options" (button list, no LEDs)
- Exit to Character Selection
- Exit Game
- Configure Keyboard
- Use Mouse Turning Settings
- In-Game Help Files
- Urgent Assistance
- Report Abuse

### Tab 2 — "Character" (scrolling LED option list; three screenshots)
**User Interface Behavior:** Keep Combat Targets in View · Salvage
Multiple Materials at Once · Use Main Pack as Default for Picking Up
Items.
**User Interface Display:** Vivid Targeting Indicator · Display 3D
Tooltips · Show Coordinates By the Radar · Side By Side Vitals · Display
Spell Durations · Disable Most Weather Effects · Disable Distance Fog ·
Always Daylight Outdoors · Disable House Restriction Effects · Use
Crafting Chance of Success Dialog · Confirm Use of Rare Gems · Display
Timestamps · Filter Language · Show Your Helm or Head Gear · Show Your
Cloak.
**Grouping:** Ignore Allegiance Requests · Ignore Fellowship Requests ·
Show Allegiance Logons · Share Fellowship Experience and Luminance ·
Share Fellowship Loot · Automatically Accept Fellowship Requests.
**Other Players:** Accept Corpse Looting Permissions · Attempt to
Deceive Other Players · Let Other Players Give You Items · Ignore All
Trade Requests · Drag Item to Player Opens Trade · Allow Others to See
Your Date of Birth · ...Your Age · ...Your Chess Rank · ...Your Fishing
Skill · ...Your Number of Deaths · ...Your Number of Titles.
**Character Behavior:** Run as Default Movement · Advanced Combat
Interface · Auto Target · Automatically Repeat Attacks · Use Charge
Attack · Lead Missile Targets · Use Fast Missiles.
**Chat:** Stay in Chat Mode After Sending a Message · Listen to
Allegiance Chat · Listen to General Chat · Listen to Trade Chat · Listen
to LFG Chat · Listen to Roleplay Chat · Listen to Society Chat · Listen
to PK death messages.

### Tabs 3+4 — "Chat" and "Config"
Not screenshotted. Research must derive their contents (Chat tab is
plausibly the per-window text-type filter blocks + opacity the CH
research already located in `gmChatOptionsUI`; Config is unknown —
plausibly video/audio/mouse).

## What already exists (do NOT re-derive)

- **The chat digest** (`claude-memory/project_chat_digest.md`) — START
  THERE. Campaign CH built most of the plumbing this campaign needs.
- **Wire, already working:** `SetSingleCharacterOption (0x0005)` codec +
  the six Hear-chat toggles (CH3); `RuntimeCharacterOptionsState`
  (Options1/Options2 words, `SetOptionBit`, seeded from every
  PlayerDescription); the membership-gate consumption of those bits.
  ACE's `CharacterOption.cs` maps option id → bit; `CharacterOptions1.Default
  = 0x50C4A54A` (verified; the register once carried a phantom mismatch —
  see `docs/research/2026-08-09-chat-side-channels-vs-ace.md` corrections).
- **Wire, known-missing:** the full-blob `SetCharacterOptions (0x01A1)`
  builder was DELETED at CH3 (the old one was malformed:
  `CharacterOptionDataFlag.CharacterOptions2 = 0x40` collides with
  `CharacterOptions1.AllowGive`; ACE's real layout is in
  `GameActionSetCharacterOptions.cs`). Retail's Apply button presumably
  sends the blob — the REAL builder must be ported. The per-window
  GameplayOptions blob (`0x1000008C`, elements `0x1000008B`) is stored by
  ACE as an opaque byte[] it never parses — acdream owns that format
  (research: `2026-08-09-chat-retail-window-shell.md` §4).
- **Decomp beachheads:** `gmChatOptionsUI::InitOptions @0x0049FC60` (the
  five per-window filter blocks, SetUserData ids 8/2/3/4/5, defaults);
  opacity options `0x10000080/0x10000081` (`ChatInterface::SetOpacity
  @0x004F3120` family — implemented in CH6c); `PlayerModule` option
  accessors (`InqChatWindowOption 0x1000007F`, `SetHearGeneralChat
  @0x005D35C0` writes options2 locally THEN notifies — the local-write
  pattern CH3/CH4 ported). The options panel class family
  (gmOptionsUI? gmGameplayOptionsUI? the tab host) is UNEXPLORED.
- **UI machinery, fully proven by CH6:** LayoutDesc import (incl.
  Resizebar grips, buttons, scrollbars, outline properties 0x21/0x22),
  `RetailWindowManager`/`UiRoot`, fixture generation
  (`RetailLayoutFixtureGenerator` — add layouts, commit fixtures, pin
  conformance), the retained-controller pattern
  (`ChatWindowController`/`FloatingChatWindowController` are the
  templates), the settings persistence seams
  (`RuntimeSettingsController`/`RuntimeSettingsTargets`, J4.4
  generation-gated command path).
- **The F11 panel** (`SettingsPanel`, UI.Abstractions) — the NON-retail
  developer/client surface: audio sliders, quality presets, keybind
  rebinding (modal capture), chat opacity sliders (CH6c), Hear-chat
  toggles (CH3). The user's original ask ("client settings, different
  from retail") coexists with the retail panel — how they split (retail
  panel = retail options; Config tab or F11 = acdream client settings?)
  is a DESIGN DECISION for the plan, made by Claude, reactable at the
  gate.
- **Keybinds:** `KeyBindings.RetailDefaults()` (the ONLY production
  table — `AcdreamCurrentDefaults()` is dead; #358's lesson),
  `InputDispatcher` modal capture, the F11 rebind UX. Retail's
  "Configure Keyboard" screen is unexplored decomp territory.
- **Status bar:** the retail toolbar exists (`RetailUiRuntime` mounts
  it); the options BUTTON on it (which authored element, what it opens)
  is unexplored.

## Research questions for the campaign's Opus lanes

1. **Panel structure:** which LayoutDesc(s) author the Options panel
   (tab host + four tab pages)? The class family in the decomp
   (grep gmOptionsUI / gmGameplayOptionsUI / gmCharacterOptionsUI /
   gmConfigOptionsUI / the tab control); how Apply/Reset/Defaults work
   (what each sends/restores, per tab or global); how the panel opens
   (the status-bar button element + any keybind).
2. **The Character tab's complete option map:** every row transcribed
   above → its storage (CharacterOptions1 bit / CharacterOptions2 bit /
   PlayerModule property id) → its wire (0x0005 single vs 0x01A1 blob) →
   ACE's handling (which bits ACE honors server-side vs stores-only) →
   acdream's current state (exists/ignored/missing). acclient.h +
   `PlayerModule`/`CharacterOptionsMapper` decomp + ACE enums.
3. **The Chat tab and Config tab contents** (no screenshots): derive
   from the decomp/LayoutDescs what retail shows there.
4. **The real 0x01A1 blob:** exact layout from ACE's reader + retail's
   builder; when retail sends blob vs single-option.
5. **Configure Keyboard:** retail's keymap UI + storage (the keymap
   file/wire?) — and the design call on reusing acdream's existing
   rebind UX vs porting retail's screen.
6. **Gameplay Options tab actions:** Exit to Character Selection (ties
   into the FUTURE pre-world flow — probably lands as Exit Game
   initially with a register row), Urgent Assistance / Report Abuse
   (server messages?), In-Game Help Files, Use Mouse Turning Settings.
7. **Which options have live acdream consumers today** (timestamps →
   chat; hear-chat → CH3 gate; run-as-default → movement; weather/fog/
   daylight → sky pipeline; helm/cloak → appearance) vs options whose
   subsystems don't exist yet (chess rank...) — the implement-vs-store
   split per row.

8. **Headless bot settings (user-directed 2026-08-10):** character
   options must be settable by bots too. DESIGN CONSTRAINT for the plan:
   the option map (option -> CharacterOptions1/2 bit or PlayerModule
   property -> wire) is RUNTIME-owned, exposed as a typed set-option
   command on the shared IGameRuntimeCommands surface; the graphical
   Options panel and the headless host are BOTH consumers of that one
   seam (CH3's hear-chat toggles are the proven precedent). The headless
   session config (K1 strict versioned JSON) gains an optional
   `characterOptions` block of declared desired values; at login, after
   the PlayerDescription seeds actual state, the host DIFFS declared vs
   actual and sends only changes through the shared command path
   (0x0005 per change or one 0x01A1 blob) — idempotent on reconnect.
   Presentation-only settings (opacity/audio/quality) stay graphical-only;
   the strict schema keeps them out of bot config by construction.
   Research: verify which options a bot can meaningfully hold and whether
   ACE rejects any option change from a logged-in session.

## Process (binding, from Campaign CH's five gate rounds)

- Model split: Opus research lanes → Fable (main loop) plans →
  Sonnet implements → dual-lens Opus review per slice, fixes applied;
  REJECT verdicts get focused re-reviews.
- Max 3-4 agents in parallel INCLUDING children; every agent prompt
  carries an explicit no-subagent clause; ONE implementer at a time on
  shared files; agents never launch the graphical client; the user runs
  connected gates.
- Ledger discipline: never blanket-replace "(this commit)" placeholders
  (anchor every replacement); post-amend SHAs recorded by the
  coordinator, not chased in the same commit.
- User gates are AXIOMS; screenshots must be transcribed into docs
  immediately (they don't survive sessions); honesty markers NEVER
  appear in user-visible text; decomp claims byte-verified (BN pooled
  strings, `sbb` idioms, and ~33-char previews are known artifact
  classes — sweep push-imm32 literals from the PDB-paired binary at
  `C:\Users\erikn\Downloads\acclient.exe`, `check_exe_pdb.py` MATCH
  first).
- SERIAL TREE OWNERSHIP: only ONE agent that builds/tests may run at a
  time (all agents share the one worktree; concurrent dotnet build/test
  collide on bin locks). Read-only research/review agents may overlap a
  builder EXCEPT at their end-of-run targeted test step — in practice,
  run reviews and implementers serially; overlap only pure-read research.
- ESCALATION ON REPEATED REVIEW FAILURE (user-directed 2026-08-10): if a
  slice fails review TWICE (two REJECT rounds, or a rework that fails its
  re-review), the main loop (Fable) takes over and fixes it directly —
  no third Sonnet dispatch. Two failures mean the contract or the
  mechanism is being misunderstood at the implementer tier; the fix needs
  the coordinator'''s full context.
- STALLED/YIELDED AGENTS: a watchdog-killed or early-yielding agent is
  resumed with SendMessage to its id — the transcript survives and it
  continues where it stopped (used twice in Campaign CH). Never redo its
  work from scratch before trying a resume.
- PERSIST WHAT TWO CONSUMERS NEED: review findings that feed both a fixer
  AND a re-reviewer go into a docs/research findings doc (committed)
  before dispatching either — notification text does not survive session
  restarts or compaction. Same for any diagnosis a later agent works from.
- VERIFY AGENT CLAIMS AT THE SEAMS: spot-check each agent'''s load-bearing
  claims against source before building on them (git log for SHAs, the
  cited file:line for mechanisms) — reported SHAs are stale-by-one after
  amends, and two review rounds this campaign found implementer summaries
  that overclaimed what shipped.
- `dotnet build` + FULL Release suite green per commit (baseline at
  handoff: 12,610/4/0 at `bcc34ee3`; plus the in-flight polish commit
  below). Register rows same-commit. CLAUDE.md campaign paragraph
  updated at close (see `feedback_claude_md_staleness`).

## In-flight at handoff

A post-gate polish agent (round-5 review S1-S3: per-block outline pass,
non-UiText outline plumbing, citation fix) was running when this handoff
was written — check `git log` for `fix(ui): round-5 review polish` and
collect/verify its landing first if absent.

## Carried tail (do not lose)

#360/#361 (command families), #366 (unseen-text indicator), #368
(headless thread affinity — separate session exists), #369 (floaty send
channel), AP-177 (SpewBox line lifetime), AP-190 (opacity ease),
AP-191 (transcript tag colors).