Create a 3D Character Controller in Godot
4

A 3D character controller is the foundation of most 3D games and one of the three C's of game design: Character, Camera, and Controls. It's what defines how your character moves, jumps, and interacts with the game world.

In this free tutorial, you'll learn how to code a 3D third-person character controller in Godot 4, complete with smooth ground movement, jump and fall mechanics, and responsive controls perfect for third-person games.

It's a solid foundation you can study and build upon, whether you're making a platformer, an action-adventure game, or any other 3D game with a playable character.

Pre-requisites

This tutorial assumes that you have:

• Godot foundations
• Programming foundations
• Knowledge of Godot 3D basics

If you're just getting started, here are some resources to help you learn the basics of Godot and GDScript you'll need:

• Learn GDScript From Zero, an interactive app to learn the basics of code
• Your First 2D Game From Zero in Godot 4
• Your First 3D Game From Zero in Godot 4

code reference

Code checkpoints

Below you can find the complete code at different checkpoints in the video. You can use it to compare your code against it if you get stuck.

Coding the camera

Code Reference: res://player_3d.gd

This is the complete code for the res://player_3d.gd script at around 15:30 in the video:

extends CharacterBody3D

@export_group("Camera")
@export_range(0.0, 1.0) var mouse_sensitivity := 0.005
@export var tilt_upper_limit := PI / 3.0
@export var tilt_lower_limit := -PI / 6.0

var _camera_input_direction := Vector2.ZERO

@onready var _camera_pivot: Node3D = %CameraPivot


func _input(event: InputEvent) -> void:
	if event.is_action_pressed("ui_cancel"):
		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
	elif event.is_action_pressed("left_click"):
		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED


func _unhandled_input(event: InputEvent) -> void:
	var is_camera_motion := (
		event is InputEventMouseMotion and
		Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED
	)
	if is_camera_motion:
		_camera_input_direction = event.screen_relative * mouse_sensitivity


func _physics_process(delta: float) -> void:
	_camera_pivot.rotation.x += _camera_input_direction.y
	_camera_pivot.rotation.x = clamp(_camera_pivot.rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot.rotation.y -= _camera_input_direction.x

	_camera_input_direction = Vector2.ZERO

Coding the ground movement

Code Reference: res://player_3d.gd

Here's the complete code for the res://player_3d.gd script at around 24:00 in the video:

extends CharacterBody3D

@export_group("Camera")
@export_range(0.0, 1.0) var mouse_sensitivity := 0.005
@export var tilt_upper_limit := PI / 3.0
@export var tilt_lower_limit := -PI / 8.0

@export_group("Movement")
@export var move_speed := 8.0
@export var acceleration := 20.0

var _camera_input_direction := Vector2.ZERO

@onready var _camera_pivot: Node3D = %CameraPivot
@onready var _camera: Camera3D = %Camera3D


func _input(event: InputEvent) -> void:
	if event.is_action_pressed("left_click"):
		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
	if event.is_action_pressed("ui_cancel"):
		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE


func _unhandled_input(event: InputEvent) -> void:
	var is_camera_motion := (
		event is InputEventMouseMotion and
		Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED
	)
	if is_camera_motion:
		_camera_input_direction = event.screen_relative * mouse_sensitivity


func _physics_process(delta: float) -> void:
	_camera_pivot.rotation.x += _camera_input_direction.y
	_camera_pivot.rotation.x = clamp(_camera_pivot.rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot.rotation.y -= _camera_input_direction.x

	_camera_input_direction = Vector2.ZERO

	var raw_input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
	var forward := _camera.global_basis.z
	var right := _camera.global_basis.x
	var move_direction := forward * raw_input.y + right * raw_input.x
	move_direction.y = 0.0
	move_direction = move_direction.normalized()

	velocity = velocity.move_toward(move_direction * move_speed, acceleration * delta)
	move_and_slide()

Animating the character skin

Code Reference: res://player_3d.gd

Here's the complete code for the res://player_3d.gd script at 28:20:

extends CharacterBody3D

@export_group("Movement")
@export var move_speed := 8.0
@export var acceleration := 20.0
@export var rotation_speed := 12.0

@export_group("Camera")
@export_range(0.0, 1.0) var mouse_sensitivity := 0.005
@export var tilt_upper_limit := PI / 3.0
@export var tilt_lower_limit := -PI / 8.0

var _camera_input_direction := Vector2.ZERO
var _last_movement_direction := Vector3.BACK

@onready var _camera_pivot: Node3D = %CameraPivot
@onready var _camera: Camera3D = %Camera3D
@onready var _skin: SophiaSkin = %SophiaSkin


func _input(event: InputEvent) -> void:
	if event.is_action_pressed("ui_cancel"):
		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
	elif event.is_action_pressed("left_click"):
		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED


func _unhandled_input(event: InputEvent) -> void:
	var is_camera_motion := (
		event is InputEventMouseMotion and
		Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED
	)
	if is_camera_motion:
		_camera_input_direction = event.screen_relative * mouse_sensitivity


func _physics_process(delta: float) -> void:
	_camera_pivot.rotation.x += _camera_input_direction.y
	_camera_pivot.rotation.x = clamp(_camera_pivot.rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot.rotation.y -= _camera_input_direction.x

	_camera_input_direction = Vector2.ZERO

	var raw_input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
	var forward := _camera.global_basis.z
	var right := _camera.global_basis.x
	var move_direction := forward * raw_input.y + right * raw_input.x
	move_direction.y = 0.0
	move_direction = move_direction.normalized()

	velocity = velocity.move_toward(move_direction * move_speed, acceleration * delta)

	move_and_slide()

	if move_direction.length() > 0.2:
		_last_movement_direction = move_direction
	var target_angle := Vector3.BACK.signed_angle_to(_last_movement_direction, Vector3.UP)
	_skin.global_rotation.y = lerp_angle(_skin.rotation.y, target_angle, rotation_speed * delta)

	var ground_speed := velocity.length()
	if ground_speed > 0.0:
		_skin.move()
	else:
		_skin.idle()

Adding jump and fall

Code Reference: res://player_3d.gd

Here's the complete code for the res://player_3d.gd script at the end of the video:

extends CharacterBody3D


@export_group("Movement")
@export var move_speed := 8.0
@export var acceleration := 20.0
@export var rotation_speed := 12.0
@export var jump_impulse := 12.0

@export_group("Camera")
@export_range(0.0, 1.0) var mouse_sensitivity := 0.005
@export var tilt_upper_limit := PI / 3.0
@export var tilt_lower_limit := -PI / 8.0

var _camera_input_direction := Vector2.ZERO
var _last_movement_direction := Vector3.BACK
var _gravity := -30.0

@onready var _camera_pivot: Node3D = %CameraPivot
@onready var _camera: Camera3D = %Camera3D
@onready var _skin: SophiaSkin = %SophiaSkin


func _input(event: InputEvent) -> void:
	if event.is_action_pressed("ui_cancel"):
		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
	elif event.is_action_pressed("left_click"):
		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED


func _unhandled_input(event: InputEvent) -> void:
	var is_camera_motion := (
		event is InputEventMouseMotion and
		Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED
	)
	if is_camera_motion:
		_camera_input_direction = event.screen_relative * mouse_sensitivity


func _physics_process(delta: float) -> void:
	_camera_pivot.rotation.x += _camera_input_direction.y
	_camera_pivot.rotation.x = clamp(_camera_pivot.rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot.rotation.y -= _camera_input_direction.x

	_camera_input_direction = Vector2.ZERO

	var raw_input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
	var forward := _camera.global_basis.z
	var right := _camera.global_basis.x
	var move_direction := forward * raw_input.y + right * raw_input.x
	move_direction.y = 0.0
	move_direction = move_direction.normalized()

	var y_velocity := velocity.y
	velocity.y = 0.0
	velocity = velocity.move_toward(move_direction * move_speed, acceleration * delta)
	velocity.y = y_velocity + _gravity * delta

	var is_starting_jump := Input.is_action_just_pressed("jump") and is_on_floor()
	if is_starting_jump:
		velocity.y += jump_impulse

	move_and_slide()

	if move_direction.length() > 0.2:
		_last_movement_direction = move_direction
	var target_angle := Vector3.BACK.signed_angle_to(_last_movement_direction, Vector3.UP)
	_skin.global_rotation.y = lerp_angle(_skin.rotation.y, target_angle, rotation_speed * delta)

	if is_starting_jump:
		_skin.jump()
	elif not is_on_floor() and velocity.y < 0:
		_skin.fall()
	elif is_on_floor():
		var ground_speed := velocity.length()
		if ground_speed > 0.0:
			_skin.move()
		else:
			_skin.idle()

faq/troubleshooting

Why use the CharacterBody3D node instead of the RigidBody3D node?

You can use either node as the base for your character controllers, and each has its strengths.

The CharacterBody3DCharacterBody3D node gives you direct control over movement. We often use this for a more arcade-style or traditional movement feel.

The RigidBody3DRigidBody3D node simulates more realistic physics, which can make characters feel floaty or harder to control precisely. With this node, instead of setting velocity directly, you apply forces to the body.

The upside is that it handles collisions and physics interactions automatically. It'll push other rigid bodies around, which is great when you want characters to interact with the environment in a more physical way.

The downside is that it doesn't come with all the precision and built-in features of the CharacterBody3DCharacterBody3D node.

You'll want to try both to see which fits your project better. I know development teams that mainly use rigid body physics for their characters, while at GDQuest we tend to prefer kinematic bodies like CharacterBody3DCharacterBody3D when they match the project's needs.

Can I use this controller for first-person games too?

Yes, absolutely! The movement logic is nearly identical between first-person and third-person views. In a first-person view, you just won't need to separate the camera pivot from the camera itself.

download files

This project comes with everything you need to focus on learning about coding a character controller:

• A game level
• Predefined input maps
• Sophia, our 3D animated mascot
• In the lesson_reference/ folder, you will find code checkpoints for different chapters of the video

Import the project in Godot 4.7+ to get started.

updates / code patches

• Added a bonus section about smoothing the camera rotation. You will learn how to remove the jitters that appear when you turn the character and the camera at the same time and look down at them.
• Added an errata for the mouse input code in the video.
• This tutorial was originally made with Godot 4.3 and was updated to Godot 4.7. Suggest an update.
• No errors reported. Report an error.

bonus

Smoothing the camera rotation to reduce jitters

If you turn the character and the camera at the same time and look down at them from a steep angle, you will see jitters on the character model. The problem is that the rotation of the camera and of the character model don't match. The character skin moves smoothly to the target angle using the lerp_angle() function, but the camera pivot immediately snaps to the new rotation based on mouse motion. The two combined make the character feel jittery.

The simplest way to address this is to adjust the camera pivot in the same way you adjusted the character skin, by storing a target rotation and interpolating the pivot toward it every frame:

@onready var _camera_pivot_target_rotation := _camera_pivot.rotation


func _physics_process(delta: float) -> void:
	_camera_pivot.rotation.x += _camera_input_direction.y
	_camera_pivot.rotation.x = clamp(_camera_pivot.rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot.rotation.y -= _camera_input_direction.x
	_camera_pivot_target_rotation.x += _camera_input_direction.y
	_camera_pivot_target_rotation.x = clamp(_camera_pivot_target_rotation.x, tilt_lower_limit, tilt_upper_limit)
	_camera_pivot_target_rotation.y -= _camera_input_direction.x
	_camera_pivot.rotation = _camera_pivot.rotation.lerp(_camera_pivot_target_rotation, 10.0 * delta)

	_camera_input_direction = Vector2.ZERO

	# ...

The _camera_pivot_target_rotation variable keeps track of the input and makes sure the tilt doesn't go beyond the limits, similar to how the pivot's rotation was controlled before. The difference is that the pivot now smoothly follows the target with lerp() instead of snapping to it.

The weight in the camera lerp, 10.0 * delta, controls how quickly the camera catches up to the target rotation. A higher value feels faster but can still cause jitters while a lower value feels smoother but makes controls heavier.

If you still see some small jitters or a lack of smoothness, for example on a screen with a high refresh rate, you can go one step further. To update the visuals every render frame, move the camera and character skin rotation code to _process(). You will find an example in the source project for this guide: res://lessons_reference/player_3d_template_v3.gd

Making the character stop more sharply so it feels more responsive

The character slides a bit when you release the movement keys. To make it stop more abruptly, you can add a stopping speed. When the character's velocity drops below this threshold and the player is not pressing any movement keys, set the velocity to zero:

@export var stopping_speed := 1.0


func _physics_process(delta: float) -> void:
	# ...
	if is_equal_approx(move_direction.length(), 0.0) and velocity.length() < stopping_speed:
		velocity = Vector3.ZERO
	# ...

This gives you snappier movement, which works well in fast-paced games where you need to quickly change direction or stop on a dime.