Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท 3D Games

A 3D Character Controller

Build 3D movement in Godot 4 with CharacterBody3D: camera-relative input, gravity, jumping, mouse look, SpringArm3D and acceleration, with Python stand-ins for the vector maths.

A 3D character controller is a CharacterBody3D plus a camera and a few lines of vector maths. It works like its 2D cousin: you set velocity and call move_and_slide(). What changes is that "forward" depends on where the character or camera is turned, and the camera must be steered with the mouse.

The Godot engine cannot run on this site, so scripts are read-only and the runnable blocks are Python stand-ins for the maths. Every stand-in is labelled.

The scene

flowchart TD
    P["CharacterBody3D: Player"] --> S["CollisionShape3D (CapsuleShape3D)"]
    P --> M["MeshInstance3D (model)"]
    P --> H["Node3D: Head"]
    H --> C["Camera3D"]

First-person layout: the body turns left and right, the head tilts up and down.

Splitting yaw (body) from pitch (head) keeps the body upright while the camera looks up and down.

Movement script (first person)

GDSCRIPT
extends CharacterBody3D

const SPEED := 5.0
const JUMP_VELOCITY := 4.5
const MOUSE_SENSITIVITY := 0.003
var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")

@onready var head: Node3D = $Head

func _ready() -> void:
	Input.mouse_mode = Input.MOUSE_MODE_CAPTURED

func _unhandled_input(event: InputEvent) -> void:
	if event is InputEventMouseMotion:
		rotate_y(-event.relative.x * MOUSE_SENSITIVITY)
		head.rotate_x(-event.relative.y * MOUSE_SENSITIVITY)
		head.rotation.x = clampf(head.rotation.x, deg_to_rad(-85), deg_to_rad(85))

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity.y -= gravity * delta          # in 3D, gravity pulls down along -Y
	elif Input.is_action_just_pressed("jump"):
		velocity.y = JUMP_VELOCITY

	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
	var direction := (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
	if direction:
		velocity.x = direction.x * SPEED
		velocity.z = direction.z * SPEED
	else:
		velocity.x = move_toward(velocity.x, 0, SPEED)
		velocity.z = move_toward(velocity.z, 0, SPEED)

	move_and_slide()

The key line is transform.basis * Vector3(input_dir.x, 0, input_dir.y). The input vector is in the character's own space (up on the stick means "-Z of me"); multiplying by the basis rotates it into world space. Pitch is clamped so the camera cannot flip over the top.

Python Stand-in (Python, not Godot): turning input into a world direction

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pressing forward with yaw 0 gives (0, -1), i.e. -Z. Turn 90 degrees and "forward" becomes -X. Normalizing keeps diagonal movement from being faster (about 1.41 times) than straight movement; Input.get_vector() already limits the length to 1 for the input itself.

Mouse look and pitch clamp

The mouse arrives as relative pixels. Multiply by a sensitivity, apply yaw to the body and pitch to the head, and clamp the pitch. Capturing the mouse hides the cursor and gives unlimited relative movement; release it with Input.mouse_mode = Input.MOUSE_MODE_VISIBLE when a menu opens.

Python Stand-in (Python, not Godot): accumulate mouse motion, clamp pitch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Moving the mouse up (negative dy) increases the pitch until the clamp stops it at 85 degrees; moving it back down is allowed immediately because the clamp only limits the value.

Third person: SpringArm3D

For a third-person camera, put a SpringArm3D under the character and the Camera3D at its end. The arm shortens when a wall is behind the character, so the camera never goes inside geometry. Rotate the arm with the mouse; rotate the model to face the movement direction with lerp_angle:

GDSCRIPT
@onready var model: Node3D = $Model
@onready var arm: SpringArm3D = $SpringArm3D

func _physics_process(delta: float) -> void:
	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
	var dir := Vector3(input_dir.x, 0, input_dir.y).rotated(Vector3.UP, arm.global_rotation.y)
	if dir.length() > 0.1:
		velocity.x = dir.x * SPEED
		velocity.z = dir.z * SPEED
		var target_yaw := atan2(-dir.x, -dir.z)
		model.rotation.y = lerp_angle(model.rotation.y, target_yaw, 10.0 * delta)
	move_and_slide()

lerp_angle takes the short way around the circle, avoiding the model spinning 350 degrees when it should turn 10.

Python Stand-in (Python, not Godot): lerp vs lerp_angle across the wrap-around

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Slopes, steps and floors

floor_max_angle (default 45 degrees) decides which slopes count as floor; steeper ones act as walls. floor_snap_length keeps the body glued to the ground while walking down ramps. Godot does not climb steps automatically: either build small ramps in the collision shape, or add a step-up check with a body test motion. Gravity and jump heights use meters per second: with gravity 9.8, JUMP_VELOCITY = 4.5 lifts about 1.03 m.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why split the first-person player into a body (yaw) and a head (pitch)?

    Yaw rotates the whole body around Y; pitch only tilts the head, so movement stays horizontal.
  2. 2. What does transform.basis * Vector3(input_dir.x, 0, input_dir.y) do?

    The basis holds the body's rotation, so multiplying turns 'forward relative to me' into a world-space direction.
  3. 3. What is SpringArm3D for?

    The arm casts a shape along its length and shortens when it hits geometry.
  4. 4. Why use lerp_angle instead of lerp for rotation?

    Plain lerp can turn almost a full circle when the angles straddle 0 and 360 degrees.

Summary

  • CharacterBody3D works like the 2D version: set velocity, call move_and_slide().
  • Rotate the local input direction with the body's basis to get camera-relative movement.
  • Yaw on the body, pitch (clamped) on the head; capture the mouse for look.
  • SpringArm3D for third-person cameras, lerp_angle for smooth turning.

Next: Lights, Shadows and Environment