AI agent skill · by @MRCalderon3D

Godot Input Patterns

Implement Godot input through InputMap actions with correct event propagation, device support, and rebinding.

Archived 2026-10-23 · Source updated 2026-08-20 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# Godot Input Patterns

## Purpose
Implement Godot input through InputMap actions with correct event propagation, device support, and rebinding.

## Use When
- adding or unifying input handling for a Godot game
- gameplay scripts read raw keycodes, scancodes, or joypad button indices directly
- input behaves differently between gameplay, UI, and pause states and the propagation order is unclear

## Inputs
- list of gameplay actions (move, jump, fire, pause, confirm)
- supported devices (keyboard/mouse, joypad, touch) per platform target
- UI flow and pause/overlay states that consume input
- rebinding and accessibility requirements

## Process
1. define every action in the InputMap (project settings or at startup) and bind devices to actions; gameplay code calls `Input.is_action_*` or handles `InputEvent` actions, never raw keycodes
2. choose polling versus events deliberately: poll continuous state (movement axes via `Input.get_vector`) in `_physics_process`, and handle discrete edges (just pressed/released) through events or `is_action_just_pressed`
3. respect the propagation order — `_input`, then Control `_gui_input`, then `_unhandled_input` — and put gameplay input in `_unhandled_input` so UI consumes events first; call `set_input_as_handled()` explicitly when a layer swallows an event
4. handle joypads through actions with deadzone configured per action, listen to `joy_connection_changed` for hot-plug, and verify mappings on each exported platform
5. for touch targets, decide between `InputEventScreenTouch` handling and `emulate_mouse_from_touch`, and keep on-screen controls as a separate Control layer bound to the same actions
6. implement rebinding by editing InputMap at runtime (`action_erase_events` / `action_add_event`), persist bindings to user settings, and expose them through the accessibility options
7. define how paused state affects input: which nodes keep processing via `process_mode`, and which actions (pause/menu) must work while the tree is paused

## Outputs
- InputMap action inventory with device bindings and deadzones
- propagation rules: which layer handles what, in which callback
- rebinding and persistence design
- device and platform test scenarios (hot-plug, focus loss, touch emulation)

## Quality Bar
- no gameplay script references keycodes, scancodes, or joypad indices outside the InputMap setup
- UI reliably consumes events before gameplay, and nothing double-handles an event after `set_input_as_handled()`
- movement uses `Input.get_vector` (or equivalent) with per-action deadzones, not per-frame keycode checks
- pause/menu actions keep working while the tree is paused, and nothing else does
- rebinds survive a restart and are reflected in any input prompts shown to the player

## Common Failure Modes
- mixing `_input` and `_process` polling for the same action, double-counting presses across frames
- gameplay input in `_input` so UI clicks also fire gameplay actions underneath
- hardcoded joypad button indices that differ between controller types and platforms
- pause menus that cannot be closed because their own input stopped processing with the tree
- touch handled through mouse emulation only, breaking multi-touch (move plus fire) on mobile

## Related Agents
- godot-reviewer
- gameplay-programmer
- ui-programmer

## Related Commands
- input-review
- godot-review
- verify

## Related Skills
- godot-signals-patterns
- godot-scene-architecture

## Notes
- Keep this skill aligned with the relevant rules layer and current project documentation.
- The engine-neutral action-abstraction policy lives in `engineering-common/input-abstraction`; this skill is the Godot-specific implementation of it.