Godot Character Controllers

When implementing character movement, follow these patterns for responsive and polished controllers.

CharacterBody2D Platformer

Basic Platformer Movement

extends CharacterBody2D

@export var speed := 300.0
@export var jump_velocity := -400.0
@export var gravity := 980.0

func _physics_process(delta: float) -> void:
    # Apply gravity
    if not is_on_floor():
        velocity.y += gravity * delta

    # Handle jump
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity

    # Get horizontal input
    var direction := Input.get_axis("move_left", "move_right")

    if direction:
        velocity.x = direction * speed
    else:
        velocity.x = move_toward(velocity.x, 0, speed)

    move_and_slide()

Advanced Platformer with Coyote Time and Jump Buffering

extends CharacterBody2D

@export var speed := 300.0
@export var acceleration := 2000.0
@export var friction := 1500.0
@export var air_friction := 200.0
@export var jump_velocity := -400.0
@export var gravity := 980.0
@export var max_fall_speed := 600.0

# Coyote time (allows jumping shortly after leaving platform)
@export var coyote_time := 0.1
var coyote_timer := 0.0

# Jump buffering (registers jump input before landing)
@export var jump_buffer_time := 0.1
var jump_buffer_timer := 0.0

# Variable jump height
@export var jump_cut_multiplier := 0.5
var is_jumping := false

func _physics_process(delta: float) -> void:
    var was_on_floor := is_on_floor()

    # Coyote time
    if was_on_floor:
        coyote_timer = coyote_time
    else:
        coyote_timer -= delta

    # Jump buffer
    if Input.is_action_just_pressed("jump"):
        jump_buffer_timer = jump_buffer_time
    else:
        jump_buffer_timer -= delta

    # Apply gravity
    if not is_on_floor():
        velocity.y += gravity * delta
        velocity.y = min(velocity.y, max_fall_speed)

    # Handle jump
    if jump_buffer_timer > 0 and coyote_timer > 0:
        velocity.y = jump_velocity
        is_jumping = true
        jump_buffer_timer = 0
        coyote_timer = 0

    # Variable jump height - cut jump short if button released
    if is_jumping and not Input.is_action_pressed("jump") and velocity.y < 0:
        velocity.y *= jump_cut_multiplier
        is_jumping = false

    if is_on_floor():
        is_jumping = false

    # Horizontal movement with acceleration
    var direction := Input.get_axis("move_left", "move_right")

    if direction:
        velocity.x = move_toward(velocity.x, direction * speed, acceleration * delta)
    else:
        var current_friction = friction if is_on_floor() else air_friction
        velocity.x = move_toward(velocity.x, 0, current_friction * delta)

    move_and_slide()

Wall Jump and Wall Slide

extends CharacterBody2D

@export var wall_slide_speed := 50.0
@export var wall_jump_velocity := Vector2(300, -350)
@export var wall_jump_time := 0.15  # Time player can't control after wall jump

var wall_jump_timer := 0.0
var wall_direction := 0

func _physics_process(delta: float) -> void:
    wall_jump_timer -= delta

    # Detect wall
    wall_direction = 0
    if is_on_wall():
        wall_direction = get_wall_normal().x

    # Wall slide
    if is_on_wall() and not is_on_floor() and velocity.y > 0:
        velocity.y = min(velocity.y, wall_slide_speed)

    # Wall jump
    if Input.is_action_just_pressed("jump") and is_on_wall() and not is_on_floor():
        velocity = Vector2(wall_direction * wall_jump_velocity.x, wall_jump_velocity.y)
        wall_jump_timer = wall_jump_time

    # Normal movement (disabled briefly after wall jump)
    if wall_jump_timer <= 0:
        var direction := Input.get_axis("move_left", "move_right")
        if direction:
            velocity.x = direction * speed

    # Apply gravity and move
    if not is_on_floor():
        velocity.y += gravity * delta

    move_and_slide()

Dash Mechanic

extends CharacterBody2D

@export var dash_speed := 800.0
@export var dash_duration := 0.15
@export var dash_cooldown := 0.5

var is_dashing := false
var dash_timer := 0.0
var dash_cooldown_timer := 0.0
var dash_direction := Vector2.ZERO

func _physics_process(delta: float) -> void:
    dash_cooldown_timer -= delta

    # Start dash
    if Input.is_action_just_pressed("dash") and dash_cooldown_timer <= 0 and not is_dashing:
        start_dash()

    # During dash
    if is_dashing:
        dash_timer -= delta
        velocity = dash_direction * dash_speed

        if dash_timer <= 0:
            is_dashing = false
            velocity = dash_direction * speed  # Keep some momentum
    else:
        # Normal movement
        apply_normal_movement(delta)

    move_and_slide()

func start_dash() -> void:
    is_dashing = true
    dash_timer = dash_duration
    dash_cooldown_timer = dash_cooldown

    # Get dash direction from input or facing direction
    var input_dir := Vector2(
        Input.get_axis("move_left", "move_right"),
        Input.get_axis("move_up", "move_down")
    )

    if input_dir != Vector2.ZERO:
        dash_direction = input_dir.normalized()
    else:
        dash_direction = Vector2.RIGHT if $Sprite2D.flip_h == false else Vector2.LEFT

CharacterBody3D Controllers

First Person Controller

extends CharacterBody3D

@export var speed := 5.0
@export var sprint_speed := 8.0
@export var jump_velocity := 4.5
@export var mouse_sensitivity := 0.002

var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")

@onready var head: Node3D = $Head
@onready var camera: Camera3D = $Head/Camera3D

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

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseMotion and Input.mouse_mode == Input.MOUSE_MODE_CAPTURED:
        # Rotate head (up/down)
        head.rotate_x(-event.relative.y * mouse_sensitivity)
        head.rotation.x = clamp(head.rotation.x, deg_to_rad(-90), deg_to_rad(90))

        # Rotate body (left/right)
        rotate_y(-event.relative.x * mouse_sensitivity)

    if event.is_action_pressed("ui_cancel"):
        Input.mouse_mode = Input.MOUSE_MODE_VISIBLE

func _physics_process(delta: float) -> void:
    # Gravity
    if not is_on_floor():
        velocity.y -= gravity * delta

    # Jump
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity

    # Movement
    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()

    var current_speed := sprint_speed if Input.is_action_pressed("sprint") else speed

    if direction:
        velocity.x = direction.x * current_speed
        velocity.z = direction.z * current_speed
    else:
        velocity.x = move_toward(velocity.x, 0, current_speed)
        velocity.z = move_toward(velocity.z, 0, current_speed)

    move_and_slide()

Third Person Controller

extends CharacterBody3D

@export var speed := 5.0
@export var sprint_speed := 8.0
@export var jump_velocity := 4.5
@export var rotation_speed := 10.0

var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
var target_rotation := 0.0

@onready var camera_pivot: Node3D = $CameraPivot
@onready var spring_arm: SpringArm3D = $CameraPivot/SpringArm3D
@onready var model: Node3D = $Model

func _physics_process(delta: float) -> void:
    # Gravity
    if not is_on_floor():
        velocity.y -= gravity * delta

    # Jump
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity

    # Get input direction relative to camera
    var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")

    # Transform input to camera space
    var camera_basis := camera_pivot.global_transform.basis
    var direction := (camera_basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
    direction.y = 0
    direction = direction.normalized()

    var current_speed := sprint_speed if Input.is_action_pressed("sprint") else speed

    if direction:
        velocity.x = direction.x * current_speed
        velocity.z = direction.z * current_speed

        # Rotate model to face movement direction
        target_rotation = atan2(direction.x, direction.z)
        model.rotation.y = lerp_angle(model.rotation.y, target_rotation, rotation_speed * delta)
    else:
        velocity.x = move_toward(velocity.x, 0, current_speed)
        velocity.z = move_toward(velocity.z, 0, current_speed)

    move_and_slide()

Smooth Camera Follow

extends Node3D

@export var target: Node3D
@export var offset := Vector3(0, 2, 5)
@export var follow_speed := 5.0
@export var rotation_speed := 3.0
@export var mouse_sensitivity := 0.003

var camera_rotation := Vector2.ZERO

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseMotion and Input.mouse_mode == Input.MOUSE_MODE_CAPTURED:
        camera_rotation.x -= event.relative.y * mouse_sensitivity
        camera_rotation.y -= event.relative.x * mouse_sensitivity
        camera_rotation.x = clamp(camera_rotation.x, deg_to_rad(-80), deg_to_rad(80))

func _physics_process(delta: float) -> void:
    if not target:
        return

    # Calculate desired position
    var target_pos := target.global_position

    # Apply rotation
    var offset_rotated := offset.rotated(Vector3.UP, camera_rotation.y)
    offset_rotated = offset_rotated.rotated(Vector3.RIGHT, camera_rotation.x)

    var desired_position := target_pos + offset_rotated

    # Smoothly interpolate position
    global_position = global_position.lerp(desired_position, follow_speed * delta)

    # Look at target
    look_at(target_pos, Vector3.UP)

Movement State Machine

State-Based Character Controller

extends CharacterBody2D

enum State { IDLE, RUN, JUMP, FALL, WALL_SLIDE, DASH }

var current_state: State = State.IDLE

@export var speed := 300.0
@export var jump_velocity := -400.0
@export var gravity := 980.0

func _physics_process(delta: float) -> void:
    match current_state:
        State.IDLE:
            process_idle(delta)
        State.RUN:
            process_run(delta)
        State.JUMP:
            process_jump(delta)
        State.FALL:
            process_fall(delta)
        State.WALL_SLIDE:
            process_wall_slide(delta)
        State.DASH:
            process_dash(delta)

    move_and_slide()

func change_state(new_state: State) -> void:
    # Exit current state
    match current_state:
        State.DASH:
            exit_dash()

    current_state = new_state

    # Enter new state
    match new_state:
        State.JUMP:
            enter_jump()
        State.DASH:
            enter_dash()

func process_idle(delta: float) -> void:
    apply_gravity(delta)
    velocity.x = move_toward(velocity.x, 0, speed * delta * 10)

    if not is_on_floor():
        change_state(State.FALL)
    elif Input.is_action_just_pressed("jump"):
        change_state(State.JUMP)
    elif Input.get_axis("move_left", "move_right") != 0:
        change_state(State.RUN)

func process_run(delta: float) -> void:
    apply_gravity(delta)

    var direction := Input.get_axis("move_left", "move_right")
    velocity.x = direction * speed

    if not is_on_floor():
        change_state(State.FALL)
    elif Input.is_action_just_pressed("jump"):
        change_state(State.JUMP)
    elif direction == 0:
        change_state(State.IDLE)

func apply_gravity(delta: float) -> void:
    if not is_on_floor():
        velocity.y += gravity * delta

Input Handling Best Practices

Input Buffer System

class_name InputBuffer
extends RefCounted

var buffer: Dictionary = {}
var buffer_times: Dictionary = {}

func _init() -> void:
    pass

func update(delta: float) -> void:
    for action in buffer_times.keys():
        buffer_times[action] -= delta
        if buffer_times[action] <= 0:
            buffer.erase(action)
            buffer_times.erase(action)

func add(action: String, duration: float = 0.1) -> void:
    buffer[action] = true
    buffer_times[action] = duration

func consume(action: String) -> bool:
    if buffer.has(action):
        buffer.erase(action)
        buffer_times.erase(action)
        return true
    return false

func has(action: String) -> bool:
    return buffer.has(action)

Action Queuing

extends CharacterBody2D

var action_queue: Array[String] = []
var max_queue_size := 3

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("attack"):
        queue_action("attack")
    elif event.is_action_pressed("special"):
        queue_action("special")

func queue_action(action: String) -> void:
    if action_queue.size() < max_queue_size:
        action_queue.append(action)

func process_action_queue() -> void:
    if action_queue.is_empty():
        return

    var next_action := action_queue[0]

    if can_perform_action(next_action):
        action_queue.pop_front()
        perform_action(next_action)

func can_perform_action(action: String) -> bool:
    # Check if current state allows this action
    return true

func perform_action(action: String) -> void:
    match action:
        "attack":
            do_attack()
        "special":
            do_special()

Common Gotchas

Floor Detection

# is_on_floor() is only valid AFTER move_and_slide()
func _physics_process(delta: float) -> void:
    # BAD: Checking before move_and_slide
    # if is_on_floor():  # This is stale from last frame

    move_and_slide()

    # GOOD: Check after move_and_slide
    if is_on_floor():
        # This is current
        pass

# For immediate floor check without moving
func is_grounded() -> bool:
    return test_move(global_transform, Vector3.DOWN * 0.1)

Snapping to Slopes

extends CharacterBody3D

func _physics_process(delta: float) -> void:
    # Enable floor snapping for slopes
    floor_snap_length = 0.5 if is_on_floor() else 0.0

    # Adjust floor max angle for steep slopes
    floor_max_angle = deg_to_rad(45)

    move_and_slide()

Delta Independence

# BAD: Frame-dependent movement
velocity.x += 10  # Faster at higher FPS

# GOOD: Delta-independent movement
velocity.x += acceleration * delta

# For velocity-based movement with move_and_slide
# velocity is already handled correctly by move_and_slide
velocity.x = speed  # This is fine, move_and_slide handles delta