godot-input-handling

Input Handling

Handle keyboard, mouse, gamepad, and touch input with proper buffering and accessibility support.

MANDATORY script triggers (by scenario)

Scenario	Load before coding
Jump/dash/coyote feel	input_buffer.gd (physics-tied decay) + advanced_input_buffer.gd for multi-action priority
Settings remapping UI	safe_runtime_rebind.gd (ConfigFile persist to user://)
Analog stick movement	analog_deadzone_manager.gd — never raw axis without radial deadzone
"Press X / Press E" prompts	glyph_prompt_manager.gd
UI nav vs gameplay confirm	input_echo_filter.gd — echoes move menus, not Confirm/Back
Gameplay vs menu clicks	unhandled_input_priority.gd

Do-NOT-Load (by scenario)

Scenario	Load	Do NOT load
Settings remapping UI	safe_runtime_rebind.gd	multi_touch_gestures.gd, mouse_capture_manager.gd, combo/replay injectors
Mobile / touch gestures	multi_touch_gestures.gd	mouse_capture_manager.gd, desktop remapper persistence
Jump/dash buffer only	input_buffer.gd / advanced_input_buffer.gd	Remapper, multi-touch, replay, combo validator
FPS mouse look	mouse_capture_manager.gd + deadzone/glyph as needed	multi_touch_gestures.gd, combo/replay
Combo / fighting sequences	combo_validator.gd + buffers	Touch gestures, mouse capture
Replay / virtual injection tests	input_replay_buffer.gd / virtual_input_injector.gd	Remapper UI, multi-touch

Available Scripts

advanced_input_buffer.gd

Frame-perfect input buffering system for responsive jumps, dashes, and combo chains.

input_buffer.gd

Timed action buffer with _physics_process decay so windows match CharacterBody consumption, not render FPS.

safe_runtime_rebind.gd

Dynamic input rebinding with conflict detection and user://input_rebinds.cfg persistence.

analog_deadzone_manager.gd

Radial deadzone management for analog sticks to eliminate drift while maintaining natural follow-through.

multi_touch_gestures.gd

Handling touch, drags, and pinch-to-zoom gestures for mobile and touchscreen compatibility.

input_echo_filter.gd

Filtering echo events to distinguish between hold-to-navigate (UI) and one-time gameplay actions.

mouse_capture_manager.gd

Robust mouse capture and sensitivity scaling logic for FPS and mouse-intensive systems.

hold_toggle_accessibility.gd

Software-side support for user-defined 'Hold' vs 'Toggle' accessibility preferences.

glyph_prompt_manager.gd

Real-time switching between Keyboard and Gamepad UI prompts based on the last active device.

action_state_machine.gd

Tracking the lifecycle of an action ('Just Pressed', 'Held', 'Released') for complex state logic.

unhandled_input_priority.gd

Demonstrating the correct use of _unhandled_input to prevent gameplay logic from leaking into UI.

virtual_input_injector.gd

Input.parse_input_event injection for CI tutorials / AI assistance — not physical hardware.

combo_validator.gd

Rolling timed sequence buffer for special-move validation (fighting / action RPG).

input_replay_buffer.gd

Frame-tagged capture + deterministic replay via parse_input_event.

NEVER Do in Input Handling

• NEVER poll input in _process() for gameplay actions — Use _physics_process() or _unhandled_input(). _process() is frame-rate dependent, causing dropped inputs at low FPS [22].
• NEVER use hardcoded key checks (e.g., KEY_W) — Always use InputMap actions. Hardcoded keys prevent rebinding and break compatibility with non-QWERTY layouts [23].
• NEVER ignore analog stick deadzones — Drifting sticks at 0.05 magnitude will cause unintended movement. Implement a radial deadzone (not axial) in code or settings [24].
• NEVER assume a single input device — Players may switch between Keyboard and Controller mid-session. Use Input.joy_connection_changed to update UI prompts dynamically [25].
• NEVER use _input() for gameplay actions — _input() fires for ALL events (including UI). Use _unhandled_input() so gameplay logic doesn't trigger while clicking menus [26].
• NEVER omit input buffering in fast-paced games — If a player presses jump 50ms before landing, the input is lost without a buffer. Implement a 100-150ms buffer for a "tight" feel [27].
• NEVER use Input.is_action_pressed() for one-time triggers — It returns true every frame the key is held. Use _just_pressed for jumps, attacks, and toggles to avoid logic spam.
• NEVER implement manual 'Hold vs Toggle' logic in multiple places — Centralize it in a setting or input wrapper to ensure accessibility consistency across the whole game.
• NEVER forget to handle InputEvent.is_echo() in UI navigation — Echo events (keyboard repeat) should move menus but rarely should they trigger "Confirm" or "Back" actions.
• NEVER capture the mouse without a 'Release' shortcut — If your game crashes or blocks ui_cancel, the user is trapped. Always provide a fallback escape for mouse capture.

---

Input Propagation & Isolation

Godot propagates input events in a specific order. Understanding this is key to isolating UI from gameplay.

1. _input(event): High-priority global intercept. Use for dev consoles or debug overlays.
2. _gui_input(event): Handled by Control nodes (UI). If a UI element consumes the event (e.g., clicking a button), it calls accept_event(), stopping further propagation.
3. _unhandled_input(event): Reached ONLY if no UI element consumed the event. Expert Pattern: Put all gameplay logic (jump, shoot) here to prevent accidental triggers while interacting with menus.

InputMap Best Practices

Avoid physical key checks. Define semantic actions (e.g., move_left, interact) in Project Settings > Input Map.

1. Analog Deadzones

Analog sticks suffer from drift. MANDATORY: analog_deadzone_manager.gd. Prefer Input.get_vector() for circular deadzones — never subtract axes into a square deadzone.

2. Expert polling delta (no hardcoded keys)

Gameplay samples actions in _physics_process / _unhandled_input — never KEY_* / MOUSE_BUTTON_* branches. Pause/cancel must be InputMap actions (e.g. ui_cancel) so rebinds and non-QWERTY layouts work. See unhandled_input_priority.gd.

Multi-Modal Input & UI Glyphs

Modern games must handle simultaneous Controller and Keyboard/Mouse input smoothly.

1. Handling Input Modes

• Mouse Aiming: Process InputEventMouseMotion in _unhandled_input() for relative movement (mouse_capture_manager.gd).
• Stick Movement: Poll vectors in _physics_process() after analog_deadzone_manager.gd.

2. Dynamic Glyph Swapping

MANDATORY: glyph_prompt_manager.gd for last-device prompt swaps. Do not hand-roll event is InputEventJoypadButton detectors in every HUD widget.

Expert Input Extensions (script sole-source)

• Input buffering — MANDATORY: input_buffer.gd + advanced_input_buffer.gd. Do not paste jump-timer tutorials inline.
• Coyote time — Owned by movement skills: godot-characterbody-2d (frame_perfect_coyote_time.gd) and godot-genre-platformer. Pair with buffers from this skill; do not re-implement coyote here.
• Multiplayer input sync — Do not RPC sync_input here. Route to godot-multiplayer-networking for authoritative action snapshots / get_remote_sender_id validation.
• Virtual injection — MANDATORY: virtual_input_injector.gd (Input.parse_input_event).
• Combo sequences — MANDATORY: combo_validator.gd; fighting fiction stays in godot-genre-fighting.
• Deterministic replay — MANDATORY: input_replay_buffer.gd.

Deep recipes (on demand)

Topic	Reference / script
Buffering / coyote / MP sync	input-event-processing.md
Virtual injection / combos / replay	expert-input-extensions.md
InputMap & device IDs	inputmap-best-practices.md

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Using InputEvent — Event propagation order (_input → GUI → _unhandled_input) and why gameplay belongs after UI consumes events.
• Input examples — Practical InputMap action polling, mouse buttons, and keyboard patterns this skill builds on.
• Controllers, gamepads, and joysticks — Joypad connection, button/axis events, and multi-device mapping for remappers and glyph swaps.
• Controller vibration and features — Extended pad capabilities beyond basic buttons when shipping console-style feedback.
• Mouse and input coordinates — Viewport vs screen coordinates for clicks, aim, and capture-relative motion.
• Customizing the mouse cursor — Cursor shapes alongside Input.mouse_mode capture/release flows.
• Handling quit requests — Safe ESC / back / quit paths so mouse capture never traps the player.
• Input — Singleton API: is_action_*, get_vector, mouse_mode, parse_input_event, and joy connection signals.
• InputMap — Runtime action_add_event / erase / conflict checks for safe rebinding.
• InputEvent — Base event API including is_echo(), is_action_pressed(), and device IDs.
• Idle and Physics Processing — Why hold/poll gameplay input in _physics_process, not frame-tied _process.
• Control — _gui_input / accept_event so menus stop events before _unhandled_input gameplay.

Related Skills

Prerequisites

• godot-project-foundations — Project Settings Input Map, scene boot, and Autoload registration that host remappers and glyph managers.
• godot-gdscript-mastery — Typed InputEvent branches, StringName actions, and safe signal/await patterns used in buffers and device routers.

Complements

• godot-ui-containers — Control focus and _gui_input ownership so menus consume clicks before gameplay _unhandled_input.
• godot-signal-architecture — device_changed and rebind events should signal up to HUD/prompt listeners without hard UI refs.
• godot-autoload-architecture — Singleton ownership for InputBuffer / GlyphPrompt / Remapper services that survive scene changes.
• godot-characterbody-2d — Consumes buffered jump/dash and get_vector movement inside physics steps.
• godot-camera-systems — Mouse-look sensitivity and capture modes pair with FPS camera rigs.
• godot-state-machine-advanced — Action just-pressed / held / released phases drive FSM transitions without polling spam.
• godot-save-load-systems — Persist InputMap rebinds and hold/toggle accessibility prefs to user:// config.
• godot-adapt-desktop-to-mobile — Virtual joysticks and touch cameras extend this skill’s multi-touch gesture patterns.

Downstream / consumers

• godot-genre-platformer — Coyote time and jump buffers are the primary consumer of input buffering.
• godot-genre-shooter-fps — Captured mouse aim, fire just-pressed, and gamepad look rely on this skill’s capture/deadzone stack.
• godot-genre-fighting — Combo sequence validators and frame-perfect buffers feed special-move detection.
• godot-multiplayer-networking — Authoritative peers need sanitized action snapshots / RPC’d input, not raw local keycodes.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting input concern.