FPS Controller

A first-person controller is four small systems on one body: mouse look, horizontal movement, jumping and crouching. Each runs in a few lines of player.gd. This section goes through them in the order the script runs them, explains the choices that are easy to get wrong, and shows the test that proves each one. The full script is in the zip; the code below is the part each idea needs.

CharacterBody3D, not RigidBody3D

A RigidBody3D is moved by the physics engine: you push it with forces and it slides, spins and bounces as the engine decides. That is right for a crate and wrong for a player, who expects to stop the moment the key comes up and never to tip over. A CharacterBody3D moves only when your code tells it to. You set velocity and call move_and_slide(), which moves the body, slides it along whatever it hits instead of stopping dead, and records whether it ended up on a floor, a wall or a ceiling. is_on_floor() then answers the question every jump and every gravity step needs. You get exact control over speed, and the engine still handles collision.

Yaw on the body, pitch on the head

Mouse look is two rotations. Left and right (yaw) turns the whole body, because the body's facing is what decides which way "forward" walks. Up and down (pitch) tilts only the Head node, which carries the camera. If pitch went on the body too, looking down would tip the capsule over and "forward" would point into the floor. Keeping each rotation on its own node also rules out roll, the sideways tilt of the horizon: the body only ever turns about y and the head only about x.

func look(screen_pixels: Vector2) -> void:
	rotation.y = wrapf(rotation.y - screen_pixels.x * mouse_sensitivity, -PI, PI)
	var limit := deg_to_rad(pitch_limit_degrees)
	head.rotation.x = clampf(head.rotation.x - screen_pixels.y * mouse_sensitivity, -limit, limit)

The script works out each new angle, clamps the pitch, then sets the angles. A common alternative is to call rotate_x() first and clamp the angle Godot reads back out of the rotated basis afterwards. In a test with that version, ordinary flicks of up to 1,200 pixels were clamped correctly, but one very large upward move of 100,000 pixels ended at -60.8° instead of 89°, because the angle read back had wrapped round. Clamping before setting has no such case. In the tests, a huge upward move stopped at exactly 89.000° and a huge downward one at -89.000°, and after 5,000 random mouse moves the body's x and z rotation and the head's y and z rotation were still exactly 0, with the camera's right-hand axis level to within 0.000000001.

Reading the mouse

The look code runs from _unhandled_input(), so a click that a button or a menu handles never captures the mouse. A click anywhere else captures the mouse, ui_cancel (Esc in every project) frees it, and mouse motion only turns the view while the mouse is captured.

func _unhandled_input(event: InputEvent) -> void:
	if event is InputEventMouseButton and event.pressed:
		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
	elif event.is_action_pressed(&"ui_cancel"):
		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
	elif event is InputEventMouseMotion and Input.mouse_mode == Input.MOUSE_MODE_CAPTURED:
		look(event.screen_relative)

It reads screen_relative, not relative. The InputEventMouseMotion docs say relative is scaled by the content scale factor that the project's stretch mode sets, so mouse sensitivity changes with the window size, and that screen_relative should be preferred for mouse aiming in captured mode. In a test project drawn at 640 x 360 and stretched to a 1280 x 720 window, a 100 pixel mouse move arrived as relative 50 and screen_relative 100. The controller's test feeds it an event with those two values and checks that the body turned 100 × 0.002 = 0.2 rad.

Splitting velocity in two

Each physics tick, the script treats the horizontal part of velocity (x and z) and the vertical part (y) separately. Gravity and jumping own y. The input owns x and z. Mixing them is the classic bug: replace the whole velocity with the input direction and you wipe out the falling speed every tick, so the player floats down at a crawl.

var input := Input.get_vector(&"move_left", &"move_right", &"move_forward", &"move_back")
# Turn the input by the body's yaw only. The head's pitch never tilts movement.
var direction := global_basis * Vector3(input.x, 0.0, input.y)
...
var target := Vector2(direction.x, direction.z) * target_speed
var rate := acceleration if is_on_floor() else air_acceleration
var horizontal := Vector2(velocity.x, velocity.z).move_toward(target, rate * delta)
velocity.x = horizontal.x
velocity.z = horizontal.y

Input.get_vector() turns four actions into one vector no longer than 1, which is why holding forward and right gives the same 5 m/s as forward alone (measured: 5.000 m/s, not 7.07). Multiplying by global_basis, the body's rotation, turns "forward on the keyboard" into "forward where the body faces": in the test, a player turned 90° to face -x walked at (-5, 0) m/s. The basis only holds yaw, so looking at the floor never slows you down. move_toward() moves the current horizontal velocity towards the target by at most rate × delta per tick, which gives a short, even acceleration: 5 m/s after 8 ticks, 0.133 s, against the 0.125 s that 5 / 40 predicts, the difference being one tick. Gravity comes from get_gravity(), so an Area3D that changes gravity in part of your level changes it for the player too.

Coyote time and jump buffering

A strict "only jump when is_on_floor()" feels broken in practice. Players press jump a moment after running off a ledge, because they see the edge late, and the game ignores them. Coyote time, named after the cartoon coyote who runs off a cliff and only falls when he looks down, keeps the jump valid for a short time after leaving the floor. Jump buffering covers the opposite mistake: jump pressed a moment before landing is remembered and fires on the tick you touch down. Both are one timer each.

func _update_jump(delta: float) -> void:
	if is_on_floor():
		_coyote_timer = coyote_time
	else:
		_coyote_timer -= delta
	if Input.is_action_just_pressed(&"jump"):
		_jump_buffer_timer = jump_buffer_time
		_try_jump()
	elif _jump_buffer_timer > 0.0:
		_jump_buffer_timer -= delta
		_try_jump()


func _try_jump() -> void:
	if is_on_floor() or _coyote_timer > 0.0:
		velocity.y = jump_velocity
		_coyote_timer = 0.0
		_jump_buffer_timer = 0.0

Setting both timers to 0 after a jump matters. The coyote timer would otherwise still be running for the first 0.12 s of the jump, and a second press in that time would jump again in mid-air. One test presses jump again 0.05 s after take-off and checks that the player did not jump; with the _coyote_timer = 0.0 line deleted, it jumped. The buffer timer would otherwise still hold the press that started the jump. Under a ceiling 1 cm above the head, the jump hits the ceiling and the player is back on the floor while the press is still buffered: one press gave one take-off, and with _jump_buffer_timer = 0.0 deleted it gave two. The tests walk the player off a 1 m box and press jump a set number of ticks after it left the floor: at 0.050, 0.100 and 0.117 s it jumped, at 0.133, 0.150 and 0.200 s it fell. They also drop it from 2 m and press jump before it lands: pressed 0.050 or 0.083 s early, it jumped on the landing tick; 0.133 or 0.150 s early, the press had expired. A second press 0.25 s into a jump changed nothing either. The jump itself peaked 1.071 m above the floor. The formula gives 4.5² / (2 × 9.8) = 1.033 m; the extra 3.8 cm is the step size, since the body moves a whole tick at a time, and it stays within one tick of travel (0.075 m).

Crouching with a headroom check

Crouching changes the capsule's height from 1.8 to crouch_height and moves the shape down by half the difference, so its bottom stays at the feet and the body does not drop. The camera follows at crouch_camera_speed, so the eye glides down instead of jumping. Standing up is where controllers usually go wrong: if you just grow the capsule back, a player under a low beam grows into it and gets pushed through the floor or out to the side. So before standing, the script sweeps a sphere through the space the standing capsule would fill, from the top of the crouched capsule up to the full height, using the HeadroomCheck node:

func _has_headroom() -> bool:
	var radius := (headroom.shape as SphereShape3D).radius
	headroom.position = Vector3(0.0, crouch_height - radius, 0.0)
	headroom.target_position = Vector3(0.0, _stand_height - crouch_height, 0.0)
	headroom.force_shapecast_update()
	return not headroom.is_colliding()

A ShapeCast3D moves a shape along a line and reports what it would hit. The ShapeCast3D docs say force_shapecast_update() works with enabled off, so the node costs nothing until the player tries to stand. exclude_parent is on by default, so the player's own capsule never counts. The sphere is 5 cm narrower than the capsule, so a wall you lean on stays 5 cm clear of it. In the test the player crouched flush against a wall, 0.0001 m from it, and stood up. Under a beam 1.3 m up, the test released crouch and the player stayed at 1.0 m; walking on, it stood up at z = -3.948, just past the first clear spot at -3.85 (the beam ends at -3.5, plus the sphere's 0.35 m radius). Standing, the same player stopped at the beam's face.

Head bob from distance, not time

A bob driven by a clock keeps bobbing at the same rate whether you creep or sprint, and has to be stopped by hand. This one adds the horizontal speed times delta to a distance counter only while you move on the ground, and works the camera offset out from that distance: one full up-and-down per step, one side-to-side sway per stride. In the tests, walking 9.7 m gave 12 sway reversals and sprinting 15.3 m gave 19, against 12.2 and 19.1 from 2 × distance / bob_stride. The vertical offset peaked at exactly bob_height, 0.04 m, and fell to 0 within a second of stopping, then stayed there. It moves the Camera3D, not the Head, so it never fights the crouch height. With head_bob off, the camera offset stayed exactly 0 while sprinting.

Input actions that come with the script

Input actions live in project.godot, and nobody copies another project's project.godot. So the script carries its actions and default keys in a constant, and ensure_input_actions() adds whichever ones are missing when the player starts, using the InputMap calls the docs list: has_action(), add_action() (dead zone 0.2 by default) and action_add_event().

static func ensure_input_actions() -> void:
	for action: StringName in DEFAULT_BINDINGS:
		if InputMap.has_action(action):
			continue
		InputMap.add_action(action)
		for keycode: Key in DEFAULT_BINDINGS[action]:
			var event := InputEventKey.new()
			event.physical_keycode = keycode
			InputMap.action_add_event(action, event)

The keys are physical key codes, which name a position on the keyboard rather than a letter, so on an AZERTY layout the same four keys under your left hand still move you. The test deletes crouch and move_forward, empties jump and binds it to J, then runs the function: crouch came back with Ctrl and C, a physical W press matched move_forward, and jump still had only J. It is static, so another script can call FPSController.ensure_input_actions() before any player exists.

How the demo plays itself

autopilot.gd drives the player the way a person would: it holds and releases the same actions with Input.action_press() and turns the view through the same look(). It decides by position, not time: sprint until 3.7 m into the bay, jump at 5.15 m, crouch from 12.2 m. To walk straight while the view glances to the side, it turns the wanted direction into the player's own axes and presses forward and strafe by the right amounts, which Input.get_vector() reads as an analogue stick. The eight bays are identical, so each time the player has gone one bay, the AutoPilot moves it back 22 m and nothing on screen changes. That is how a 4 second recording loops. The AutoPilot is a node in demo.tscn, not in player.tscn, so it never runs in your game, and in the demo any key or mouse button hands you the controls.

How it builds on the first 3D scene lesson

The first 3D scene lesson writes a short player.gd with the same core: Input.get_vector(), horizontal and vertical velocity kept apart, and move_and_slide(). It moves along world axes under a fixed camera and uses its own gravity of 18 with a jump of 5 m/s, which peaks at 0.69 m. This controller turns movement by the body's yaw instead, takes gravity from the project (9.8 by default), and adds everything a first-person game needs on top. Its capsule is the lesson's, 0.4 m by 1.8 m, so a level built for one works for the other.