# Session 2026-04-17 — Debug Overlay + Control Tuning

## Headline result

**On-screen HUD overlay and refined input controls for the dev client.**
- TTF-based font atlas rendered via stb_truetype
- Screen-space text + rect batcher (`TextRenderer`)
- Composite overlay with panels for position / heading / collision /
  FPS / compass / keybind help
- Per-mode mouse sensitivity (Chase, Fly, Orbit)
- RMB-held free-orbit around the player (no snap-back on release)
- Mouse-wheel zoom in chase mode
- Extended chase pitch range so mouse-Y moves both ways

## Files added

- `src/AcDream.App/Rendering/BitmapFont.cs` — TTF atlas (stb_truetype)
- `src/AcDream.App/Rendering/TextRenderer.cs` — 2D quad batcher for text + rects
- `src/AcDream.App/Rendering/DebugOverlay.cs` — composed HUD panels
- `src/AcDream.App/Rendering/Shaders/ui_text.{vert,frag}` — ortho-proj text shader
- `src/AcDream.App/Rendering/Shaders/debug_line.{vert,frag}` — wireframe shader
  (carried from yesterday's scenery-alignment session but not committed then)

## Files modified

- `src/AcDream.App/AcDream.App.csproj` — added `StbTrueTypeSharp` 1.26.12
- `src/AcDream.App/Rendering/Shader.cs` — added `SetVec2` / `SetVec4`
- `src/AcDream.App/Rendering/ChaseCamera.cs`
  - Added `YawOffset` for RMB free-orbit
  - Added `AdjustDistance` for mouse-wheel zoom
  - Widened pitch clamp from `[0.05, 1.4]` to `[-0.7, 1.4]`
    (mouse-Y now moves camera in both directions from neutral)
  - `DistanceMin=2f`, `DistanceMax=40f` zoom envelope
- `src/AcDream.App/Rendering/GameWindow.cs`
  - Field block: `_textRenderer`, `_debugFont`, `_debugOverlay`,
    `_sensChase/_sensFly/_sensOrbit`, `_rmbHeld`, `_lastFps`, `_lastFrameMs`
  - OnLoad: load Consolas → BitmapFont → TextRenderer → DebugOverlay
    (silently skips if no system font)
  - Keyboard: F1/F2/F4/F5/F6 panel toggles; F8/F9 sensitivity
    (multiplicative ×1.2 steps, per-mode)
  - Mouse: MouseDown / MouseUp track RMB; MouseMove routes to the
    active mode's sensitivity; RMB release does NOT snap YawOffset
  - OnRender: snapshot builder (player pos, heading, nearest-obj dist,
    colliding flag) passed to `DebugOverlay.Draw`

## Yesterday's scenery work (finally committed in this session's commit)

The untracked files show that yesterday's scenery-alignment fixes lived
on disk but hadn't been committed. This session's commit includes:
- `src/AcDream.Core/Physics/BSPQuery.cs` — `localToWorld` rotation params
- `src/AcDream.Core/Physics/PhysicsDataCache.cs` — `GfxObjVisualBounds`
- `src/AcDream.Core/Physics/ShadowObjectRegistry.cs` — `Scale` + debug iter
- `src/AcDream.Core/Physics/TransitionTypes.cs` — rewritten cylinder / BSP
- `src/AcDream.Core/World/SceneryGenerator.cs` — 64-cell, ACViewer OnRoad,
  baseLoc + set_heading rotation
- `src/AcDream.Core/World/WorldEntity.cs` — `Scale` field

## Sensitivity defaults (current)

| Mode  | Default | F8 step     | F9 step   |
|-------|---------|-------------|-----------|
| Chase | 0.15x   | ÷ 1.2       | × 1.2     |
| Fly   | 1.0x    | ÷ 1.2       | × 1.2     |
| Orbit | 1.0x    | ÷ 1.2       | × 1.2     |

Effective rate at chase 0.15x: `0.15 × 0.003 rad/px = 0.00045 rad/px`
≈ 0.026°/pixel. 1000 pixels → 26° rotation.

Fly at 1.0x is `0.003 rad/px` ≈ 0.172°/px.

## Keybinds (full, current)

| Key       | Action |
|-----------|--------|
| F1        | Toggle keybind help panel |
| F2        | Toggle collision wireframes |
| F3        | Console dump (pos + nearby objects) |
| F4        | Toggle HUD info panel |
| F5        | Toggle HUD stats panel |
| F6        | Toggle compass |
| F8 / F9   | Active-mode mouse sensitivity slower / faster |
| F         | Toggle fly camera |
| Tab       | Toggle player mode (live session only) |
| WASD      | Move (player mode) / fly |
| Space     | Jump (hold to charge, release to fire) |
| Shift     | Run |
| Mouse     | Turn character / look |
| Hold RMB  | Free-orbit camera around player (stays on release) |
| Wheel     | Zoom chase distance |
| Escape    | Exit fly / player / close window |

## Open issue (parked for follow-up)

User reports mouse "feels like you can only move one way" at low
sensitivity. Diagnosed + fixed: chase `PitchMin` was clamping at
`0.05f`, preventing any upward tilt. Widened to `-0.7f`. Needs
visual verification next session.

## Pickup for next session

**MAJOR TASK PARKED HERE**: user has asked for a deep investigation
+ port of the retail AC client's GUI subsystem. User explicitly
directed **Opus 4.7 with extra-high effort** for this work. The
agents are dispatched in this session and their output lives in
`docs/research/2026-04-17-retail-ui-*.md`. See that set of files
for the in-depth UI research + C# scaffold.

After the retail-UI port is in place:
1. Hook the retail chat window to the existing WorldSession message
   stream
2. Port the health/stamina/mana globes to real player stats (need
   `CharacterCreate`/`InqStats` wire parsing first)
3. Port the inventory panel (needs CreateObject item parsing)