Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Nodes and Signals

Godot Input: Input Map, Actions and Events

Handle player input in Godot 4: define actions in the Input Map, poll with Input.is_action_pressed and get_vector, react to events in _input and _unhandled_input, gamepads, dead zones.

A game that cannot react to the player is just an animation. Godot's input system is built around actions: named things the player can do (jump, move_left, pause) that you map to keys, mouse buttons, gamepad buttons and sticks. Your code asks about actions, never about specific keys, so you can rebind controls, support a gamepad and keep scripts readable.

Godot is not available on this site, so GDScript is read-only. The Python stand-in maps raw key names to actions and builds a movement vector in the same way as Input.get_vector.

The Input Map

Open Project > Project Settings > Input Map. The built-in ui_* actions (ui_accept, ui_cancel, ui_left...) drive menus. To add your own:

  1. Type a name such as move_left in the "Add New Action" box and press Add.
  2. Click the + next to it, press the key (for example A), press OK. Add more events to the same action: the left arrow key, and a gamepad stick direction.
  3. Repeat for move_right, move_up, move_down, jump, shoot, pause.

Actions are stored in project.godot. One action can have many events, and the same physical key can serve different actions. Use physical key events (they match the key's position, so WASD stays under the left hand on a French keyboard) for movement.

You can also create them in code, which is handy for testing:

GDSCRIPT
func _ready() -> void:
    if not InputMap.has_action("dash"):
        InputMap.add_action("dash")
        var ev := InputEventKey.new()
        ev.physical_keycode = KEY_SHIFT
        InputMap.action_add_event("dash", ev)

Polling: ask every frame

The Input singleton answers "what is the state now?":

GDSCRIPT
if Input.is_action_pressed("move_right"):          # true while held
    velocity.x = speed
if Input.is_action_just_pressed("jump"):           # true on the frame it went down
    velocity.y = -jump_force
if Input.is_action_just_released("shoot"):         # true on the frame it was released
    stop_charging()

var strength := Input.get_action_strength("accelerate")   # 0.0 to 1.0 (analog)
var axis := Input.get_axis("move_left", "move_right")      # -1.0 to 1.0
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")

get_axis combines two actions into a number. get_vector combines four into a Vector2, normalizes it (diagonals are not faster) and applies the controller dead zone, so a stick resting slightly off-center does not move your character. It is the best way to read movement:

GDSCRIPT
extends CharacterBody2D

@export var speed := 240.0

func _physics_process(_delta: float) -> void:
    velocity = Input.get_vector("move_left", "move_right", "move_up", "move_down") * speed
    move_and_slide()

Use is_action_just_pressed for single events (jump, fire, interact) and is_action_pressed for continuous ones (move, hold to charge). Polling in _physics_process or _process is fine; one-off events can also use callbacks.

Events: be told when something happens

Godot sends each input as an InputEvent through a chain of callbacks:

  1. _input(event): every node first (before the UI).
  2. The UI (Control nodes) handle clicks, focus and key presses.
  3. _unhandled_input(event): events no UI node used.
  4. _unhandled_key_input(event) for keys only.
GDSCRIPT
func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("pause"):
        get_tree().paused = not get_tree().paused
        get_viewport().set_input_as_handled()      # stop it from reaching other nodes

    if event is InputEventMouseButton and event.pressed:
        if event.button_index == MOUSE_BUTTON_LEFT:
            print("click at ", event.position)

    if event is InputEventKey and event.pressed and not event.echo:
        print("key: ", OS.get_keycode_string(event.keycode))

Use _unhandled_input for gameplay so that clicking a button does not also make your character shoot. Use _input only when you need to see everything first. event.is_action_pressed("name") works for any event type. echo is true for key-repeat events from holding a key.

Other useful event classes: InputEventMouseMotion (with relative for camera look), InputEventScreenTouch and InputEventScreenDrag (touch), InputEventJoypadButton and InputEventJoypadMotion.

Mouse position and gamepads

GDSCRIPT
var screen_pos := get_viewport().get_mouse_position()
var world_pos := get_global_mouse_position()      # in 2D world coordinates (Node2D)
look_at(get_global_mouse_position())

Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)   # hide and lock the cursor (3D look)
Input.start_joy_vibration(0, 0.5, 0.5, 0.3)       # device, weak, strong, seconds

Dead zones are set per action in the Input Map (the default is 0.2 for analog actions). Gamepads work with no extra code when the actions include joypad events.

Remapping and saving controls

To let the player rebind, remove the old events and add a new one:

GDSCRIPT
func rebind(action: String, event: InputEvent) -> void:
    InputMap.action_erase_events(action)
    InputMap.action_add_event(action, event)

Save the events (for example with var_to_str or custom text) to user://controls.cfg using ConfigFile, and load them at startup. Because your game code only checks action names, nothing else changes.

Stand-in: key to action to movement vector

This is not Godot. It models the Input Map and get_vector: normalized diagonals and a dead zone on analog input.

Python Stand-in (Python): actions, get_vector and dead zone

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 d and s gives (0.707, 0.707), not (1, 1), which is why diagonals are not faster; a and d cancel to (0, 0).

Common mistakes

  • Hard-coding keys (event.keycode == KEY_W) instead of actions, which blocks gamepads and rebinding.
  • Using is_action_pressed for a jump (it fires every frame while held).
  • Handling gameplay in _input, so UI clicks also trigger gameplay. Use _unhandled_input.
  • Not normalizing diagonal movement: use get_vector.
  • Typos in an action name; Godot reports an error ("The InputMap action ... doesn't exist").

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which function is true only on the frame an action goes down?

    is_action_just_pressed fires once when the press starts, which suits jump or shoot.
  2. 2. Why prefer Input.get_vector for movement?

    get_vector combines four actions into a normalized Vector2 with a dead zone for sticks.
  3. 3. Where should gameplay input be handled so UI clicks do not also trigger it?

    _unhandled_input only receives events that no UI node consumed.
  4. 4. Why use actions instead of checking specific keys?

    Scripts that ask about actions work with any bound key or button.

Summary

  • Define named actions in Project Settings > Input Map and bind keys, buttons and sticks to them.
  • Poll with Input.is_action_pressed, is_action_just_pressed, get_axis and get_vector.
  • React to events with _unhandled_input (gameplay) or _input (everything first); set_input_as_handled stops propagation.
  • Mouse, touch and gamepads share the same event system.
  • Remap controls with InputMap functions and save them in user://.

Next: Node Communication and Groups