# Retail-faithful chase camera with dev-tools toggle **Date:** 2026-05-18 **Author:** Claude (with @erikn) **Phase:** ad-hoc rendering polish (not on the M2 critical path) **Status:** brainstormed → ready for plan ## Motivation `src/AcDream.App/Rendering/ChaseCamera.cs` is a rigid follow-cam: each frame `Position` is recomputed as a pure function of `playerPosition + yaw + Pitch + Distance + EyeHeight`. The character is welded to the camera, which makes movement feel mechanical (no lag, no overshoot, no slope-awareness). A `_trackedZ` hack pins camera Z during jumps as a workaround for the visual feel that retail's camera gets naturally from low-stiffness damping. The retail 2013 client uses a two-class chase camera (`CameraManager` + `CameraSet`, decomp at `docs/research/named-retail/acclient_2013_pseudo_c.txt:95505` and `:97643`) that: 1. **Exponentially damps both translation and rotation toward a target pose each frame.** Default stiffness 0.45 → ~7.5 % of the gap closed per 60 Hz frame → ~150 ms half-life. This is the dominant "alive" feel. 2. **Aligns the camera basis to the player's recent velocity vector** (5-frame moving average) instead of pure world-up. The camera tilts with the terrain when running up/down hills. 3. **Low-passes mouse-look deltas** within a 0.25 s window so high-DPI mice don't make the camera jitter. 4. **Integrates held-key offset adjustments** (Closer/Farther/Raise/ Lower) at a settable rate per frame so zoom/elevation transitions are smooth. 5. **Fades the player mesh** linearly from opaque at 0.45 m to fully transparent at 0.20 m when the camera approaches the pivot. 6. **Orbits independently of player yaw** — Rotate inputs spin `viewer_offset` around the pivot's Z-axis, the character's heading isn't touched. This spec ports all six behaviors as a new `RetailChaseCamera` class, controlled by a dev-tools toggle so the user can A/B against the existing legacy camera before we make retail the default. ## Architecture ``` ┌─ ChaseCamera ────────┐ │ (existing, legacy) │ └──────────────────────┘ ▲ │ ICamera │ CameraDiagnostics ─── flag ─► CameraController ──► renderer (View matrix) (static) │ │ ICamera ▼ ┌─ RetailChaseCamera ──┐ │ (new) │ └──────────────────────┘ ▲ │ per-frame inputs │ GameWindow (updates both, picks active) ``` ### Components **`AcDream.Core.Rendering.CameraDiagnostics`** (new static class) Owns the runtime-tunable knobs. Mirrors the `PhysicsDiagnostics` pattern (diagnostic owner classes per CLAUDE.md §"Code Structure Rules" rule 5). Initial values from env vars at process start; runtime-settable via property setters that the DebugPanel writes to. ```csharp public static class CameraDiagnostics { public static bool UseRetailChaseCamera { get; set; } = Environment.GetEnvironmentVariable("ACDREAM_RETAIL_CHASE") == "1"; public static bool AlignToSlope { get; set; } = Environment.GetEnvironmentVariable("ACDREAM_CAMERA_ALIGN_SLOPE") != "0"; public static float TranslationStiffness { get; set; } = 0.45f; public static float RotationStiffness { get; set; } = 0.45f; public static float MouseLowPassWindowSec { get; set; } = 0.25f; public static float CameraAdjustmentSpeed { get; set; } = 40.0f; } ``` Lives in `AcDream.Core` (math-relevant tunables don't need the GL/ window dependency). Defaults match retail's `CameraManager` constructor (decomp lines 95957–95988). **`AcDream.App.Rendering.RetailChaseCamera : ICamera`** (new) The retail-faithful camera. Owns per-frame state: - `_velocityRing[5]` — 5-frame velocity history for the slope-align moving average. Matches retail's `old_velocities[5]`. - `_velocityCount` — ring fill level (0..5). Until full, average uses the actual count. - `_dampedEye` (Vector3) — current damped camera world position. - `_dampedForward` (Vector3, unit-length) — current damped look direction. - `_initialised` — first-frame snap flag. - `_lastMouseDeltaX`, `_lastMouseDeltaY`, `_lastFilterTimeSec` — mouse low-pass state. User-tunable properties (independent of `CameraDiagnostics` — those are global, these are per-camera-instance settings the controller can clamp): - `Distance` (default 2.61, clamp [2, 40]) — length of `viewer_offset`. - `Pitch` (default 0.291 rad ≈ 16.7°, clamp [-0.7, 1.4]) — angle of `viewer_offset` above the heading-frame XY plane. - `YawOffset` (default 0) — orbit offset added on top of player yaw when slope-align is off OR when running stationary. - `PivotHeight` (default 1.5 m) — height of look-at anchor above the player's feet. - `Aspect`, `FovY` (from `ICamera`). **`AcDream.App.Rendering.CameraController`** (existing, extended) Carries both `Chase` and `RetailChase`. `Active` reads the flag and returns whichever is selected. `EnterChaseMode(legacy, retail)` takes both at once and tracks them in parallel. ### Data flow 1. **Process start** → `CameraDiagnostics` static initialisers read env vars; defaults applied if env unset. 2. **PlayerMode entry** (existing `EnterPlayerModeIfPossible` at `GameWindow.cs:9776`) — construct both cameras, hand to `CameraController.EnterChaseMode(legacy, retail)`. 3. **Per-frame** (existing tick at `GameWindow.cs:6390`) — pass the same `playerPosition`, `playerYaw`, `playerVelocity`, `isOnGround`, `dt` to *both* cameras' `Update()`. Inactive camera stays warm so toggle swaps are instant. 4. **View matrix** — renderer pulls `cameraController.Active.View`. 5. **Translucency** — `RetailChaseCamera.PlayerTranslucency` is read after `Update()` and applied to the player entity (mechanism TBD during impl — see "Open implementation questions" below). 6. **DebugPanel** — new "Chase camera" CollapsingHeader writes to `CameraDiagnostics` via `DebugVM` mirror properties; changes take effect on the next frame. ## Math (the retail-faithful update loop) Per-frame inputs: - `playerPos` (Vector3, world coords; Z up) - `playerYaw` (radians; 0 = +X, π/2 = +Y) - `playerVelocity` (Vector3, world space; Z component nonzero on slopes) - `isOnGround` (bool; currently unused but accepted for parity with the legacy camera signature — may be used for an extra-damping branch in a future iteration) - `dt` (seconds since last frame) **Step 1 — velocity history.** FIFO-push `playerVelocity` into `_velocityRing`. Bump `_velocityCount` to min(count+1, 5). **Step 2 — averaged velocity.** ``` avgVel = sum(_velocityRing[0.._velocityCount]) / _velocityCount ``` **Step 3 — heading vector.** ``` if CameraDiagnostics.AlignToSlope and ‖avgVel‖² > 1e-4: heading = normalize(avgVel) # tilts with terrain else: yaw = playerYaw + YawOffset heading = (cos(yaw), sin(yaw), 0) # flat fallback ``` Matches retail's `target_status & ALIGN_WITH_PLANE` branch (decomp :95644-95795) with the contact-plane fallback collapsed into the flat-fallback path (we don't have `contact_plane.N` exposed yet; the flat fallback is visually indistinguishable in the stationary case). **Step 4 — orthonormal basis** (heading-frame, slope-tilted): ``` forward = heading if |forward.Z| > 0.99: # heading is near-vertical (rare; airborne edge case) right = normalize(cross(forward, (1,0,0))) # use world +X as a tilt reference else: right = normalize(cross(forward, (0,0,1))) # standard up = cross(right, forward) # already unit (forward + right orthonormal) ``` **Step 5 — target pose.** ``` pivotWorld = playerPos + (0, 0, PivotHeight) viewer_offset = (0, -Distance*cos(Pitch), Distance*sin(Pitch)) # (right, forward, up) local targetEye = pivotWorld + right * viewer_offset.X + forward * viewer_offset.Y + up * viewer_offset.Z targetForward = normalize(pivotWorld - targetEye) # camera looks at pivot ``` The `viewer_offset` parameterization matches retail's default `(0, -2.5·scale, 0.75·scale)` when `Distance ≈ 2.61` and `Pitch ≈ 16.7°` (0.291 rad). **Step 6 — exponential damping** (two independent decay rates): ``` tAlpha = clamp(CameraDiagnostics.TranslationStiffness * dt * 10, 0, 1) rAlpha = clamp(CameraDiagnostics.RotationStiffness * dt * 10, 0, 1) if not _initialised: _dampedEye = targetEye _dampedForward = targetForward _initialised = true else: _dampedEye = lerp(_dampedEye, targetEye, tAlpha) _dampedForward = normalize(lerp(_dampedForward, targetForward, rAlpha)) ``` The normalized lerp of the forward unit vector is the standard small-step equivalent of quaternion slerp; at `rAlpha ≤ ~0.1` per frame (the working range) the difference from `Quaternion.Slerp` is below floating-point noise. This preserves retail's *independent* translation/rotation rates without quaternion handedness pitfalls. **Step 7 — view matrix.** ``` Position = _dampedEye View = Matrix4x4.CreateLookAt(_dampedEye, _dampedEye + _dampedForward, (0,0,1)) ``` The `up` reference passed to `CreateLookAt` is the world up, not the heading-frame up. This produces a camera that always has the horizon horizontal on screen — matches retail (the camera basis tilts pitch, but the screen's "up" stays world-up). **Step 8 — mouse low-pass filter** (separate entry point; `FilterMouseDelta(rawX, rawY, weight) → (outX, outY)`): ``` nowSec = stopwatch elapsed seconds if nowSec - _lastFilterTimeSec < CameraDiagnostics.MouseLowPassWindowSec: avgX = (_lastMouseDeltaX + rawX) * 0.5 avgY = (_lastMouseDeltaY + rawY) * 0.5 else: avgX = rawX avgY = rawY outX = rawX * (1 - weight) + avgX * weight # weight typically 0.5 outY = rawY * (1 - weight) + avgY * weight _lastMouseDeltaX = outX _lastMouseDeltaY = outY _lastFilterTimeSec = nowSec ``` Matches retail's `CameraSet::FilterMouseInput` (decomp :96250-96279). GameWindow's mouse-move handler calls this before feeding `dy` to `AdjustPitch` / `dx` to `YawOffset`. **Step 9 — auto-fade translucency.** ``` d = distance(_dampedEye, pivotWorld) if d >= 0.45: PlayerTranslucency = 0.0 elif d > 0.20: PlayerTranslucency = 1 - (0.20 - d) / (0.20 - 0.45) else: PlayerTranslucency = 1.0 ``` Matches retail's `CameraSet::UpdateCamera` distance check (decomp :97703-97725). Reading this property at 0 produces a fully opaque player; at 1 fully invisible. GameWindow applies it to the player entity's render path (see implementation question Q1). ## Continuous-key offset integration Retail integrates `viewer_offset += FlagsToVector(held_keys) * dt` each frame for Closer/Farther/Raise/Lower as held keys. Since acdream's existing input scheme is mouse-wheel = zoom (`AdjustDistance`) and RMB-orbit-mouse-Y = pitch (`AdjustPitch`), we don't have keyboard bindings for these. This spec adds four `InputAction`s, all default-unbound (no retail keymap entries for them yet — users wire them in Settings if wanted): - `CameraZoomIn` — `Distance -= adjSpeed * dt` - `CameraZoomOut` — `Distance += adjSpeed * dt` - `CameraRaise` — `Pitch += adjSpeed * dt * 0.02` (smaller multiplier; pitch in radians) - `CameraLower` — `Pitch -= adjSpeed * dt * 0.02` The wheel-driven `AdjustDistance(step)` and the RMB-mouse-Y-driven `AdjustPitch(delta)` keep working unchanged. The damping in step 6 makes the discrete step from a wheel scroll feel smooth automatically. ## DebugPanel UI New CollapsingHeader **"Chase camera"** in `DebugPanel.cs`, sitting between "Player Info" and "Performance", defaults open. Renders six controls bound to `DebugVM` mirror properties: ``` [ ] Use retail chase camera [env: ACDREAM_RETAIL_CHASE] [x] Align to slope [env: ACDREAM_CAMERA_ALIGN_SLOPE] Translation stiffness [====|====] 0.45 (slider 0.05 .. 1.0, step 0.01) Rotation stiffness [====|====] 0.45 (slider 0.05 .. 1.0, step 0.01) Mouse low-pass window [==|======] 0.25 s (slider 0.0 .. 0.5, step 0.01) Adjustment speed [=====|===] 40.0 (slider 10 .. 80, step 1) ``` `DebugVM` gets six new properties, each forwarding to a `CameraDiagnostics` static, matching the `ProbeResolveEnabled` mirror pattern. `IPanelRenderer` may need a `SliderFloat(label, ref value, min, max)` method if not already present. The ImGui backend wraps `ImGui.SliderFloat`; tests use a stub renderer. ## Files touched **New:** - `src/AcDream.Core/Rendering/CameraDiagnostics.cs` — static tunable owner. - `src/AcDream.App/Rendering/RetailChaseCamera.cs` — the camera class. - `tests/AcDream.Core.Tests/Rendering/CameraDiagnosticsTests.cs` — env-var parse + setter passthrough. - `tests/AcDream.Core.Tests/Rendering/RetailChaseCameraTests.cs` — math + damping + low-pass + fade tests. **Modified:** - `src/AcDream.App/Rendering/CameraController.cs` — carry both cameras, swap on flag. - `src/AcDream.App/Rendering/GameWindow.cs` — construct both at chase-entry; update both per frame; route mouse low-pass; apply `PlayerTranslucency`. ~30 LOC of new code spread across existing chase-camera call sites, no new feature body. - `src/AcDream.UI.Abstractions/Panels/Debug/DebugVM.cs` — six new mirror properties. - `src/AcDream.UI.Abstractions/Panels/Debug/DebugPanel.cs` — new CollapsingHeader. - `src/AcDream.UI.Abstractions/Input/InputAction.cs` (or wherever the enum lives) — four new actions. (Possibly: `src/AcDream.UI.Abstractions/Panels/IPanelRenderer.cs` if `SliderFloat` doesn't exist there yet.) If a new namespace `AcDream.Core.Rendering` doesn't exist, it's created fresh. `AcDream.Core` does not currently reference any GL/window/Silk types, so adding `CameraDiagnostics` (pure floats + bools) does not violate the layering rule (CLAUDE.md §"Code Structure Rules" rule 2). ## Tests Five test groups in `RetailChaseCameraTests`: **1. Heading-source fallbacks** — verify the slope-align toggle and the small-velocity fallback: - `StationaryAlignToSlope_HeadingMatchesPlayerYaw` — zero velocity → heading vector ≈ `(cos yaw, sin yaw, 0)`. - `MovingHorizontal_HeadingMatchesVelocity` — sustained `(1, 0, 0)` velocity over 5 frames → heading ≈ `(1, 0, 0)`. - `MovingUphill_HeadingHasPositiveZ` — velocity `(1, 0, 0.5)` over 5 frames → `heading.Z > 0`. - `SlopeAlignDisabled_IgnoresVelocity` — heading always falls back to flat yaw vector regardless of velocity. **2. 5-frame averaging** — verify the ring buffer: - `VelocityRing_AveragesLastN` — feed `[(1,0,0), (1,0,0), (2,0,0), (2,0,0), (3,0,0)]`, expect avg `(1.8, 0, 0)`. - `VelocityRing_FifoEvictsOldest` — feed 6 entries, ring still holds 5 with the first evicted. - `VelocityRing_PartialFillUsesActualCount` — feed 2 entries, avg divides by 2 not 5. **3. Damping** — verify alpha formula + first-frame snap + lerp: - `DampingAlpha_AtRetailDefault_ProducesSevenAndAHalfPercent` — stiffness=0.45, dt=1/60 → alpha ≈ 0.075. - `DampingAlpha_LargeDtClampsToOne` — stiffness=0.45, dt=1 → alpha = 1. - `FirstUpdate_SnapsToTarget` — initial Update with no prior state sets `_dampedEye = targetEye` exactly (no damping from a stale (0,0,0)). - `SecondUpdate_LerpsTowardTarget` — initial pose A, target pose B, alpha=0.5 → position = A + 0.5·(B-A). **4. Mouse low-pass** — verify averaging window: - `MouseDelta_WithinWindow_BlendedWithPrevious` — feed delta=10 at t=0, delta=20 at t=0.1 (window=0.25) → second output averages with the first. - `MouseDelta_BeyondWindow_PassesThrough` — feed delta=10 at t=0, delta=20 at t=0.5 → second output is unmodified. - `MouseDelta_WeightZero_OutputsRaw` — weight=0 → output = raw regardless of history. - `MouseDelta_WeightOne_OutputsAveraged` — weight=1 within window → output = average. **5. Auto-fade** — verify the linear ramp constants: - `Translucency_DistanceFar_IsZero` — d ≥ 0.45 → t = 0. - `Translucency_DistanceMid_RampsLinearly` — d=0.325 (midpoint) → t = 0.5. - `Translucency_DistanceNear_IsOne` — d ≤ 0.20 → t = 1. - `Translucency_AtThreshold_IsExact` — d = 0.45 → t = 0; d = 0.20 → t = 1. Plus a small `CameraDiagnosticsTests` covering env-var parsing (`UseRetailChaseCamera=1` reads as true, default false; `AlignToSlope=0` reads as false, default true). No visual / integration test; visual feel is the manual acceptance test (see below). ## Acceptance criteria 1. `dotnet build` green. 2. `dotnet test` green, with new tests covering the math above. 3. With `ACDREAM_RETAIL_CHASE=1` set (or the dev-tools toggle flipped on), running the client + walking in Holtburg produces noticeably smoother camera motion than the legacy camera: visible lag when turning, visible coast-and-settle when stopping, visible tilt-with-terrain on hill crests. 4. With the toggle OFF, behavior is identical to before this change (legacy `ChaseCamera` untouched). 5. Toggling the switch at runtime swaps cameras without snapping or crashing; the newly-active camera takes a few frames to ease into place from the warm state of the inactive camera. 6. Jumping with retail mode on produces the "see yourself rise above the camera" feedback *without* the `_trackedZ` hack — the existing hack stays in `ChaseCamera` (legacy) untouched. ## Open implementation questions The plan resolves these before coding: **Q1: Where does `PlayerTranslucency` apply?** The retail call is `CPhysicsObj::SetTranslucencyHierarchical(player, t)`. Need to find the acdream equivalent — likely a property on `WorldEntity` or its mesh-batch metadata. If absent, the plan adds a minimal `Translucency` property and threads it through the render path. If the change to `WorldEntity` is more than ~20 LOC, the auto-fade feature ships in a follow-up commit rather than blocking the main toggle. **Q2: Where does the player's world velocity come from?** `PlayerMovementController` has `BodyVelocity` (Vector3) at line 155. The chase-camera update call site at `GameWindow.cs:6390` already holds a reference to `_playerController`; threading `playerController. BodyVelocity` into the `RetailChaseCamera.Update` call is one extra argument. Confirm during impl. **Q3: `IPanelRenderer.SliderFloat`?** Quick check during impl — if not present, add it to `IPanelRenderer` + `ImGuiPanelRenderer` (one-line each). ## Out of scope / future work - **First-person ("InHead") mode toggle.** Retail's `SetInHead` collapses `viewer_offset` to `(0, 0.18, 0)`. We don't have a first- person mode yet; out of scope. - **Look-down mode (`ToggleLookDown`)** — retail's "look down at floor" mode for inventory drag/drop. Out of scope. - **Map mode (`ToggleMapMode`)** — retail's "top-down map view." Out of scope. - **Camera-vs-world collision.** Retail's per-frame update doesn't raycast world geometry (see investigation report 2026-05-18 in chat). The auto-fade handles "camera passes through player"; we don't attempt "camera collides with wall" — same as retail. - **Making retail the default.** Default stays off in this spec; flip in a follow-up commit after visual verification. - **Deleting legacy `ChaseCamera`.** Stays around for A/B comparison until retail mode is proven and made default; then a single cleanup commit deletes it + the `_trackedZ` hack. ## References - **Retail decomp:** `docs/research/named-retail/acclient_2013_pseudo_c.txt` lines 95505 (`CameraManager::UpdateCamera`), 97643 (`CameraSet::UpdateCamera`), 95957 (`CameraManager` constructor), 97916 (`CameraSet::SetDefaultOffsets`), 96250 (`CameraSet::FilterMouseInput`), 97103 (`CameraSet::Rotate`), 97350 (`CameraSet::Closer`). - **Retail symbols:** `docs/research/named-retail/symbols.json` — search for `CameraManager` / `CameraSet`. - **Investigation report:** chat transcript 2026-05-18 (the brainstorm preceding this spec). - **Existing legacy:** `src/AcDream.App/Rendering/ChaseCamera.cs`. - **Diagnostic owner pattern:** `src/AcDream.Core/Physics/PhysicsDiagnostics.cs`.