W1: Third-person character controller and camera

Simulation (src/sim/):
- SimGround holds the terrain heightfield (bilinear heights, normals)
  and axis-aligned box solids, with support, body-overlap, point and
  ray queries. The island generator and building will fill it.
- Movement steps a player per tick: walk, sprint (forward only),
  crouch (lower body, slower, no jump), jump with exact constant-gravity
  integration, air control, step-up onto ledges up to STEP_HEIGHT,
  ground snapping on downhill walks, slopes over MAX_SLOPE_DEGREES that
  block walking and jumping uphill and make players slide (speed capped),
  ceiling bumps, sliding along walls, and fall damage from impact speed.
- Gravity now applies on ticks with no command. on_ground and crouching
  are part of the state hash. New movement numbers are in Tuning.
- Fixed the strafe direction: right is forward x up in Godot's frame,
  (-cos yaw, 0, sin yaw). Documented the look convention.

Client (src/client/):
- CameraRig places an over-the-shoulder camera with an eased
  aim-down-sights blend (closer, narrower FOV), casting against the same
  SimGround: pivot to shoulder, shoulder back, then a straight line from
  the pivot, with a final clearance pull-in so the near plane never
  enters geometry.
- InputSettings: mouse sensitivity, aim sensitivity scale and invert-Y,
  clamped and saved to user://settings.cfg. PlayerCamera applies both.

Tests: 46 new across movement, ground queries, camera and settings,
including a 24,480-view scripted camera sweep through five arenas (wall,
corridor, low roof, corner, steep bank) that checks the eye and every
near-plane corner stay out of geometry with a clear line to the pivot.
The hash test now flips a high stick bit, because a 1/127 nudge to an
airborne player moves them less than the hash's millimetre.
Capture scenarios camera, camera_wall and camera_aim.

Closes #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 20:24:02 -05:00
co-authored by Claude Opus 5.5
parent 68635d5fba
commit 70e88cec8a
29 changed files with 1213 additions and 23 deletions
+92
View File
@@ -0,0 +1,92 @@
## Over-the-shoulder third-person camera placement, with collision and aim-down-sights.
## Pure logic: it reads the same SimGround the simulation uses, so the camera can't see
## through anything the player can't walk through. PlayerCamera applies the result.
class_name CameraRig
extends RefCounted
const PIVOT_HEIGHT: float = 1.6
const CROUCH_PIVOT_HEIGHT: float = 1.05
const SHOULDER: float = 0.6
const AIM_SHOULDER: float = 0.8
const DISTANCE: float = 3.4
const AIM_DISTANCE: float = 1.8
const FOV: float = 72.0
const AIM_FOV: float = 48.0
## Clearance kept between the camera and any surface, larger than the near plane's
## half-extent so the near plane never cuts into geometry.
const MARGIN: float = 0.25
const NEAR: float = 0.05
## Minimum distance from any surface, enough to keep the whole near plane outside it.
const CLEARANCE: float = 0.1
const CLEAR_STEPS: int = 16
## Seconds to move most of the way between hip and aim.
const AIM_BLEND_SECONDS: float = 0.12
## 0 at the hip, 1 fully aimed. Advanced by `update_aim`.
var aim_blend: float = 0.0
## Eases aim_blend towards aiming or not over `delta` seconds.
func update_aim(aiming: bool, delta: float) -> void:
var target: float = 1.0 if aiming else 0.0
var rate: float = 1.0 - exp(-delta * 3.0 / AIM_BLEND_SECONDS)
aim_blend = lerpf(aim_blend, target, rate)
if absf(aim_blend - target) < 0.001:
aim_blend = target
## The look direction for a yaw and pitch, matching the simulation's convention that
## forward at yaw 0 is +z and positive pitch looks up.
static func look_direction(yaw: float, pitch: float) -> Vector3:
return Vector3(sin(yaw) * cos(pitch), sin(pitch), cos(yaw) * cos(pitch))
## The point the camera orbits, above the player's feet.
static func pivot(feet: Vector3, crouching: bool) -> Vector3:
return feet + Vector3.UP * (CROUCH_PIVOT_HEIGHT if crouching else PIVOT_HEIGHT)
## Solves the camera transform for a player. The camera looks along the aim direction
## from behind and to the right of the pivot, pulled in where geometry is in the way.
func solve(feet: Vector3, yaw: float, pitch: float, crouching: bool, ground: SimGround) -> Transform3D:
var look: Vector3 = look_direction(yaw, pitch)
var right: Vector3 = Vector3(-cos(yaw), 0.0, sin(yaw))
var shoulder: float = lerpf(SHOULDER, AIM_SHOULDER, aim_blend)
var distance: float = lerpf(DISTANCE, AIM_DISTANCE, aim_blend)
var origin: Vector3 = pivot(feet, crouching)
var beside: Vector3 = _cast(ground, origin, origin + right * shoulder)
var eye: Vector3 = _cast(ground, beside, beside - look * distance)
# The two legs can each be clear while the camera ends up over a wall top, where the
# wall hides the player. Keep a clear straight line back to the pivot as well.
eye = _cast(ground, origin, eye)
eye = _clear(ground, eye, origin)
var basis: Basis = Basis.looking_at(look, Vector3.UP if absf(look.y) < 0.999 else Vector3.FORWARD)
return Transform3D(basis, eye)
func fov() -> float:
return lerpf(FOV, AIM_FOV, aim_blend)
## Moves from `from` towards `to`, stopping MARGIN short of the first surface.
static func _cast(ground: SimGround, from: Vector3, to: Vector3) -> Vector3:
var length: float = from.distance_to(to)
if length <= 0.0:
return from
var direction: Vector3 = (to - from) / length
# Cast MARGIN past the end, so an end point just short of a wall is pulled in too.
var reach: float = length + MARGIN
var hit: float = ground.raycast(from, from + direction * reach)
return from + direction * clampf(hit * reach - MARGIN, 0.0, length)
## A ray can graze a surface it never hits. If the eye ended up within the near plane's
## clearance of anything, slide it back towards `safe` until it's clear.
static func _clear(ground: SimGround, eye: Vector3, safe: Vector3) -> Vector3:
var point: Vector3 = eye
for step: int in CLEAR_STEPS:
if not ground.point_inside(point, CLEARANCE):
return point
point = eye.lerp(safe, float(step + 1) / CLEAR_STEPS)
return safe