This page documents the input system in Godot Engine: the Input singleton, the InputEvent class hierarchy, and InputMap for action handling. It explains how input data from hardware and OS events is collected, processed, mapped to actions, and dispatched through the engine via the scene tree.
For input event propagation and handling in scenes (e.g., _input, _unhandled_input, accept_event), see the Scene System (4) and Viewport System (4.3) pages. For the layer that collects OS-level input events, see Display Server (7.6).
The input system consists principally of:
| Component | Class | Primary File |
|---|---|---|
| Global input state and event manager | Input singleton | core/input/input.h97-98 |
| Named action-to-event mapping | InputMap singleton | core/input/input_map.h31 |
| Event base and subclasses representing input events | InputEvent hierarchy | core/input/input_event.h31 |
The Input singleton handles key presses, mouse buttons and movement, gamepads, and input actions doc/classes/Input.xml7 It tracks the real-time state of devices, buffered input events, and action states. InputMap binds string action names (e.g., "jump") to sets of input event filters doc/classes/InputMap.xml7 InputEvent subclasses represent discrete input occurrences such as keypresses, mouse motion, or joystick movements core/input/input_event.h31
All input events inherit from InputEvent (a Resource subclass) and extend it with additional data as appropriate for the device and event type. These classes describe hardware input at a low level and support matching against configured actions.
InputEvent::device identifies the source device using reserved constants:
| Constant | Value | Description |
|---|---|---|
DEVICE_ID_EMULATION | -1 | Device used for synthesized events (e.g., touch from mouse) core/input/input_event.h141 |
DEVICE_ID_KEYBOARD | 16 | Physical keyboard core/input/input_event.h142 |
DEVICE_ID_MOUSE | 32 | Physical mouse core/input/input_event.h143 |
Sources: core/input/input_event.h141-143 core/input/input_event.cpp42-50
InputEventKey distinguishes three keycode representations to handle international layouts and hardware-specific mappings:
| Field | Use Case |
|---|---|
keycode | Reports the key according to the user's current keyboard layout doc/classes/InputEventKey.xml61 |
physical_keycode | Reports the key based on its physical position on a US QWERTY keyboard doc/classes/InputEventKey.xml72 |
key_label | Reports the label printed on the physical key doc/classes/InputEventKey.xml83 |
The echo flag indicates repeated events sent by OS key-repeat when holding a key down core/input/input_event.cpp95-97
Sources: core/input/input_event.h31 core/input/input_event.cpp87-97 doc/classes/InputEventKey.xml61-115
The Input singleton is the central runtime component managing device states, event buffering, and action states. It handles multiple devices and dispatches events to the SceneTree.
Input maintains several collections to track the current state of all input devices:
keys_pressed, physical_keys_pressed, and key_label_pressed sets for keyboard state core/input/input.cpp130-133joy_buttons_pressed and _joy_axis for gamepad state core/input/input.cpp135-148mouse_button_mask and mouse_pos for mouse state core/input/input.cpp134Mouse modes and cursor shapes are controlled through static function pointers set by the DisplayServer implementation core/input/input.cpp87-95:
set_mouse_mode_func, get_mouse_mode_funcwarp_mouse_funcget_current_cursor_shape_funcMouse mode enum values doc/classes/Input.xml1020-1045:
| Enum Name | Description |
|---|---|
MOUSE_MODE_VISIBLE | Cursor visible and behaves normally |
MOUSE_MODE_HIDDEN | Cursor hidden but movement still reported |
MOUSE_MODE_CAPTURED | Cursor hidden and locked to window, reports relative movement |
MOUSE_MODE_CONFINED | Cursor visible but confined inside window |
Sources: core/input/input.h78-230 core/input/input.cpp87-125 doc/classes/Input.xml1020-1045
Input events enter Godot from several sources — OS, platform sensor drivers, and the SDL joypad driver — and are funneled through the Input singleton.
parse_input_event(). Processing happens during flush_buffered_events(), which is called at key execution points in the main loop doc/classes/Input.xml51-56InputEventMouseMotion events are merged if use_accumulated_input is enabled to reduce processing overhead doc/classes/Input.xml54Sources: core/input/input.cpp793-1050 doc/classes/Input.xml51-56
Input supports synthesizing touch events from mouse input and vice versa core/input/input.cpp128-153:
emulate_touch_from_mouse: Generates InputEventScreenTouch and InputEventScreenDrag from mouse clicks and movement.emulate_mouse_from_touch: Generates InputEventMouseButton and InputEventMouseMotion from touch interactions.Sources: core/input/input.cpp128-153 doc/classes/Input.xml983-998
InputMap is a singleton managing named input actions — strings mapped to lists of input events that trigger the action.
InputMap stores a map from StringName action names to Action objects, each with a deadzone and list of associated InputEvent triggers core/input/input_map.h49-53
When an event occurs, InputMap::event_get_action_status is used to determine if the event matches an action and what its strength is core/input/input_map.cpp147-165 This allows checking:
is_action_pressed: Boolean state.get_action_strength: Value between 0.0 and 1.0 (useful for analog triggers/sticks).get_action_raw_strength: Intensity ignoring the action's deadzone.Sources: core/input/input_map.cpp147-165 core/input/input_map.h40-117 doc/classes/InputMap.xml7
Godot uses a custom SDL-based joypad driver (JoypadSDL) to handle gamepads across desktop platforms drivers/sdl/joypad_sdl.cpp63-82 It handles:
SDL_EVENT_JOYSTICK_ADDED, SDL_EVENT_JOYSTICK_REMOVED).JoyButton and JoyAxis enums using the SDL mapping database drivers/sdl/joypad_sdl.cpp145-287SDL_RumbleJoystick drivers/sdl/joypad_sdl.cpp87-123On supported platforms (Windows, Linux, macOS, iOS), Godot supports joypad motion sensors (accelerometer/gyroscope) doc/classes/Input.xml42-49 These can be calibrated using start_joy_motion_sensors_calibration() doc/classes/Input.xml42-49
Sources: drivers/sdl/joypad_sdl.cpp63-287 doc/classes/Input.xml42-49
Different platforms implement the hardware interface via DisplayServer subclasses:
DisplayServerWindows handles Win32 messages for keyboard/mouse and WinTab for tablet pressure platform/windows/display_server_windows.cpp163-194DisplayServerX11 uses Xlib/XInput2 for events platform/linuxbsd/x11/display_server_x11.cpp181-202DisplayServerWayland dispatches events through a dedicated WaylandThread platform/linuxbsd/wayland/display_server_wayland.cpp126-168DisplayServerAndroid bridges Java-side touch/key events to the engine platform/android/display_server_android.cpp68-105Sources: platform/windows/display_server_windows.cpp163-194 platform/linuxbsd/x11/display_server_x11.cpp181-202 platform/linuxbsd/wayland/display_server_wayland.cpp126-168 platform/android/display_server_android.cpp68-105
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.