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
+153
View File
@@ -0,0 +1,153 @@
## Command-driven player movement: walk, sprint, crouch, jump, gravity, slopes,
## step-up, sliding and fall damage. Deterministic: it depends only on the entity, the
## command and the ground.
class_name Movement
extends RefCounted
const DT: float = 1.0 / Tuning.TICK_RATE_HZ
## Advances one player by one tick. `command` may be null, meaning no input this tick:
## the player keeps looking the same way and stops trying to move, but still falls.
static func step(player: SimEntity, command: PlayerCommand, ground: SimGround) -> void:
var wish: Vector3 = Vector3.ZERO
var wants_jump: bool = false
player.crouching = false
if command != null:
player.yaw = command.yaw
player.pitch = command.pitch
player.crouching = command.is_pressed(PlayerCommand.BUTTON_CROUCH)
wants_jump = command.is_pressed(PlayerCommand.BUTTON_JUMP) and not player.crouching
wish = _wish_velocity(command, player.crouching)
var velocity: Vector3 = player.velocity
if player.on_ground:
velocity.x = wish.x
velocity.z = wish.z
velocity.y = 0.0
if wants_jump:
velocity.y = Tuning.JUMP_VELOCITY
player.on_ground = false
else:
velocity.x += (wish.x - velocity.x) * Tuning.AIR_CONTROL
velocity.z += (wish.z - velocity.z) * Tuning.AIR_CONTROL
velocity = _move_horizontally(player, velocity, ground)
_move_vertically(player, velocity, ground)
## Height of the player's body, which shrinks while crouching.
static func body_height(player: SimEntity) -> float:
return Tuning.CROUCH_HEIGHT if player.crouching else Tuning.PLAYER_HEIGHT
static func _wish_velocity(command: PlayerCommand, crouching: bool) -> Vector3:
var move: Vector2 = command.move_vector()
if move.length() > 1.0:
move = move.normalized()
var angle: float = command.yaw_radians()
var forward: Vector3 = Vector3(sin(angle), 0.0, cos(angle))
# Right is forward x up in Godot's right-handed, y-up frame.
var right: Vector3 = Vector3(-cos(angle), 0.0, sin(angle))
var speed: float = Tuning.WALK_SPEED
if crouching:
speed = Tuning.CROUCH_SPEED
elif command.is_pressed(PlayerCommand.BUTTON_SPRINT) and move.y > 0.0:
speed = Tuning.SPRINT_SPEED
return (right * move.x + forward * move.y) * speed
## Moves along x and z, sliding along whatever blocks the way. Returns the velocity with
## blocked components removed.
static func _move_horizontally(player: SimEntity, velocity: Vector3, ground: SimGround) -> Vector3:
var delta: Vector3 = Vector3(velocity.x, 0.0, velocity.z) * DT
if delta.is_zero_approx():
return velocity
var result: Vector3 = velocity
if _can_move_to(player, player.position + delta, ground):
player.position += delta
elif _can_move_to(player, player.position + Vector3(delta.x, 0.0, 0.0), ground):
player.position.x += delta.x
result.z = 0.0
elif _can_move_to(player, player.position + Vector3(0.0, 0.0, delta.z), ground):
player.position.z += delta.z
result.x = 0.0
else:
result.x = 0.0
result.z = 0.0
var size: float = Tuning.WORLD_SIZE_METRES
player.position.x = clampf(player.position.x, 0.0, size)
player.position.z = clampf(player.position.z, 0.0, size)
return result
static func _can_move_to(player: SimEntity, target: Vector3, ground: SimGround) -> bool:
var step: float = Tuning.STEP_HEIGHT if player.on_ground else 0.0
if ground.body_blocked(target, Tuning.PLAYER_RADIUS, body_height(player), step):
return false
# Moving uphill into terrain that's too steep is blocked, on foot or in the air, so
# nobody can climb a cliff by pushing into it. Downhill is always allowed.
var rise: float = ground.terrain_height(target.x, target.z) - player.position.y
if rise > 0.0 and not ground.walkable_terrain(target.x, target.z):
if not ground.support_is_solid(target.x, target.z, player.position.y + step):
return false
return true
static func _move_vertically(player: SimEntity, velocity: Vector3, ground: SimGround) -> void:
var feet: Vector3 = player.position
if player.on_ground:
var reach: float = feet.y + Tuning.STEP_HEIGHT
var support: float = ground.support_height(feet.x, feet.z, reach)
if support >= feet.y - Tuning.GROUND_SNAP:
player.position.y = support
player.velocity = Vector3(velocity.x, 0.0, velocity.z)
if not _walkable_support(ground, player.position):
player.on_ground = false
return
# Walked off a ledge: start falling from here.
player.on_ground = false
# Airborne. Exact integration under constant gravity.
var new_y: float = feet.y + velocity.y * DT - 0.5 * Tuning.GRAVITY * DT * DT
velocity.y -= Tuning.GRAVITY * DT
var head_room: Vector3 = Vector3(feet.x, new_y, feet.z)
if velocity.y > 0.0 and ground.body_blocked(head_room, Tuning.PLAYER_RADIUS, body_height(player), 0.0):
# Bumped a ceiling.
new_y = feet.y
velocity.y = 0.0
player.position.y = new_y
var support: float = ground.support_height(feet.x, feet.z, maxf(feet.y, new_y))
if new_y > support:
player.velocity = velocity
return
player.position.y = support
if _walkable_support(ground, player.position):
_land(player, -velocity.y)
velocity.y = 0.0
player.on_ground = true
else:
# Too steep to stand on: keep only the motion along the slope.
var normal: Vector3 = ground.terrain_normal(feet.x, feet.z)
var into: float = velocity.dot(normal)
if into < 0.0:
velocity -= normal * into
velocity = velocity.limit_length(Tuning.SLIDE_MAX_SPEED)
player.velocity = velocity
static func _walkable_support(ground: SimGround, feet: Vector3) -> bool:
if ground.support_is_solid(feet.x, feet.z, feet.y + 0.001):
return true
return ground.walkable_terrain(feet.x, feet.z)
## Applies fall damage for landing at `impact_speed` metres per second, downward.
static func _land(player: SimEntity, impact_speed: float) -> void:
if impact_speed <= 0.0:
return
var drop: float = impact_speed * impact_speed / (2.0 * Tuning.GRAVITY)
var excess: float = drop - Tuning.FALL_DAMAGE_SAFE_METRES
if excess > 0.0:
player.health = maxi(player.health - roundi(excess * Tuning.FALL_DAMAGE_PER_METRE), 0)