GOAL (for Claude Code CLI): KAIVERSE 3rd-person camera + controls fix (browser kaiverse.js)

> Codex v9.10.64 · Tier 1.5 · Codex §Comprehensive Plans

> AI / low-credit: One control fix per session; render-only 3rd-person; on stop log Last worked / Next.

Status: OPEN. Owner-reported while flying. Browser kaiverse.js only (Tier 1.5 player ship + controls). Surgical, reversible, flag-gated; do NOT alter nsUpdateCamera first-person movement math — the 3rd-person view is an additive, render-only layer (see CLAUDE-CODE-HANDOFF.md SCOPE box). Hard-refresh to apply.

Workflow: the owner is the tester (he flies + reports), the architect writes these specs, you (CLI) implement. Eyeball-iterate: ship one small change, owner flies + reports, tune. Don't guess the feel — that's his call.

---

1. Controller B button = BACK / CANCEL (not "return to core")

B is hardwired to "return to core" — wrong. Make it context-dependent back/cancel:

• Any mode, if a menu / overlay / star-chart is open → B closes it (back out one level).
• If nothing is open → B does nothing (no surprise teleport-to-core).
• Leave the rest as-is: A = select nearest (fly) / jump (walk); Y = land (fly) / take off (walk); X = unused for now.
• (Return-to-core stays on the keyboard H.)

2. Throttle — make it DYNAMIC + analog + controller-driven (it feels "unreal")

The owner says the throttle speed is "way too unreal." Two fixes:

(a) Analog throttle from the controller. The throttle should be a smooth 0→1 driven by an analog control — right trigger (RT) as the primary throttle (light press = slow cruise, full press = full speed), and/or left-stick magnitude as it already half-does. Map it into NS.throttleT continuously, not in coarse D-pad steps. Keyboard/no-pad behavior stays as-is.

(b) Kill the "unreal" feel. Right now top speed / acceleration reads teleporty. Make world-speed dynamic and believable:

• The effective top speed should EASE in/out smoothly (no instant jump to max) — keep/strengthen the existing acceleration ramp + damping.
• It must scale with context: fast in open space, genuinely slow as you near a body's surface (the NMS scale illusion — this is already the proximity-deceleration block; tune it so the crawl near a surface feels real, the cruise in deep space feels fast-but-not-teleporty).
• Lower the raw max cruise speed if open-space flight still feels "unreal." Expose it as window.KAIVERSE_MAX_SPEED (and the analog curve) so the owner can A/B in the console.
• Do not change how thrust direction is derived — only the speed magnitude / smoothing / analog mapping.

3. 3rd-person camera — fix the GTA "reverse-cam" flip (the main issue)

Bug (owner's words): "when I move it makes me view forward, but then the camera view shows in front of where I'm going — like GTA when it looks at you moving toward the camera, then back to 3rd person, then back. It's not great." → The camera is oscillating between behind the ship and in front of it.

Cause: the chase camera is anchoring/recentering on the velocity vector (or flipping the offset sign), so when velocity and look-direction disagree, the camera swings to the front and snaps back. Classic velocity-based-recenter glitch.

Fix — anchor the camera to the LOOK/HEADING direction, never to velocity:

• Chase target position = shipPos − fwd * chaseDist + up * chaseHeight, where fwd is the look/flight forward (the same basis nsUpdateCamera already builds), up is the camera up. The camera always sits behind where the nose points — it can never cross to the front.
• Remove any "recenter behind velocity" logic. Do not use c.vel direction to place or orient the camera. Velocity only feeds the *pull-back distance* (faster = farther + slightly wider FOV), never the *angle*.
• Spring-damper LAG on the camera POSITION only (lerp NS._chasePos toward the target each frame) so it swings smoothly when you turn — but the target is always behind fwd, so it can't flip.
• cam.lookAt(shipPos) (look at the ship), camera up = the flight up. No sign flips.
• Render-only, restored each frame: apply the offset between a pre()/post() wrap around the render call; after render restore cam.position to the real ship position so next frame's movement starts from the ship, not the chase point. nsUpdateCamera movement stays byte-for-byte unchanged.
• Toggle, default first-person. Flag-gated (window.KAIVERSE_THIRDPERSON / a key).

Guardrails (verify after):

• Click-to-fly picking must raycast from the REAL ship position, not the pulled-back chase position (else clicks select the wrong body).
• Proximity bloom / atmosphere distance must sample the REAL ship position, not the chase camera (else effects fade from the wrong spot / the atmosphere wall returns).
• First-person feel unchanged when the toggle is OFF.

Acceptance (owner look-test)

1. B backs out of menus, never teleports to core.

2. Throttle responds analog to the trigger; open-space cruise feels fast-but-real, the approach to a surface slows to a believable crawl — no teleporty jumps.

3. In 3rd-person the camera stays smoothly behind the ship at all times — no flip to the front, no GTA reverse-cam, no snapping. Turning swings the camera around smoothly.

4. First-person (toggle off) is identical to before. Picking + proximity effects still correct.