gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/input-systems
input-systems
VerifiedEngine-neutral input architecture with Godot InputMap code: named actions, stick deadzones, buffered presses and rebinding with conflict checks. Use for controller support or a rebind menu, or a drifting stick, WASD on AZERTY, or a dropped press. Not for coyote time (`platformer`) or Unity and Unreal input assets (`unity-input-system`, `unreal-enhanced-input`).
Input systems
Gameplay reads named actions (jump, attack, move); bindings from keys, buttons and
touch to those actions are data. Rebinding, multi-device support and most input accessibility
fall out of that one indirection. This skill is the engine-neutral architecture with Godot 4.7
code. For the engine's own input assets use unity-input-system or unreal-enhanced-input;
Godot's InputMap is covered here.
When to use
- Designing an input layer: actions, per-device bindings, device detection and prompts.
- Stick handling: deadzones, response curves, sensitivity.
- Buffering discrete presses (attack during recovery, dodge, combo links, menu confirm).
- A rebinding screen with conflict handling, saved bindings and reset to defaults.
- Accessible controls: full remap, toggle vs hold, no required chords, adjustable windows.
Not this skill: coyote time, jump buffering and variable jump height belong to
platformer, which owns the jump controller. Hit-stop and other juice that interact with
buffers are game-feel. Writing the bindings file is save-systems. Menu focus and
navigation rules are game-ui-ux.
Core workflow
- Inventory before editing. List the existing actions (Godot: the
[input]section ofproject.godot; Unity: the.inputactionsfile; Unreal:IA_/IMC_assets) and grep gameplay code for raw key reads (is_key_pressed,KEY_,Input.GetKey). Raw reads are the first thing to replace. - Name actions by intent, not by key, and give each one a keyboard and a gamepad binding. Touch routes through the same actions.
- Match the read to the action. Edge (pressed this frame or tick) for discrete actions, held or axis for continuous ones.
- Filter analog input with a radial deadzone and a separate response curve.
- Buffer discrete presses that arrive a little before they are legal, measured in game time and consumed when they fire.
- Rebinding: capture the next input, bind the physical key, reject or swap conflicts, save, and offer reset to defaults. Keep a way back to the pause menu that cannot be unbound.
- Check it yourself, then ask for the device test (see "Check it" below).
Patterns
1. Actions over raw keys; edge vs held
if Input.is_action_just_pressed("jump"): # edge: true on the press frame or tick only
try_jump()
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
# get_vector applies a radial deadzone, rescales past it and caps length at 1,
# so diagonals are not faster. Use get_axis for a single axis.
# WRONG: Input.is_key_pressed(KEY_SPACE): unrebindable, keyboard-only, and a held
# check, so jump re-fires every frame.
Engine equivalents: Unity Input System InputAction and action maps; Unreal Enhanced Input
Actions plus Mapping Contexts.
2. Analog deadzone and sensitivity
# Raw sticks never rest at exactly zero. Apply a RADIAL deadzone (on the vector
# length), not per-axis, so diagonals aren't clipped into the axes.
func apply_deadzone(stick: Vector2, dead := 0.2, curve := 1.0) -> Vector2:
# dead == 1 cannot be rescaled; report invalid settings before stopping movement.
if not (dead >= 0.0 and dead < 1.0 and curve > 0.0):
push_error("apply_deadzone requires 0 <= dead < 1 and curve > 0.")
return Vector2.ZERO
var mag := stick.length()
if mag <= dead:
return Vector2.ZERO # inside deadzone -> no movement
# Rescale so motion ramps from 0 at the edge of the deadzone, not from `dead`.
var scaled := minf((mag - dead) / (1.0 - dead), 1.0) # some pads report > 1 on diagonals
return stick / mag * pow(scaled, curve) # curve > 1 = finer aim near center
# WRONG: clamping each axis separately — it carves a square hole and snaps to axes.
Keep the response curve (exponent) separate from sensitivity (a gain on the result, usually a
camera turn rate) and expose both in settings. Invalid settings report an error and return zero
movement. Godot's get_vector already does this deadzone and rescale, using the average of the
four actions' deadzones (0.2 per action by default) unless you pass one.
3. Action buffer for discrete presses
# action_buffer.gd: remember discrete presses briefly so an early press still fires.
extends RefCounted
var window := 0.15 # seconds; 0.1-0.2 suits attacks and dodges
var _pressed_at := {} # action -> game time of its latest press
func press(action: StringName, now: float) -> void:
_pressed_at[action] = now
func consume(action: StringName, now: float) -> bool:
if not _pressed_at.has(action) or now - _pressed_at[action] > window:
return false
_pressed_at.erase(action) # one press fires one action
return true
func clear() -> void: # on death, pause, cutscene, scene change
_pressed_at.clear()
Feed it from the input read (if Input.is_action_just_pressed("attack"): buffer.press(&"attack", clock)) and call consume where the action becomes legal, such as the first frame after attack
recovery. clock is game time you advance in _physics_process, so the window freezes during
pause and hit-stop. When two buffered actions become legal on the same tick, choose by a fixed
priority, not by dictionary order. Jump buffering and coyote time use the same idea but belong to
platformer.
4. Rebinding with conflict detection
# Godot 4.7. Capture the next physical input, reject conflicts, then persist.
var _waiting_for: StringName = &"" # set by the "press a key for Jump" button
func _unhandled_input(event: InputEvent) -> void:
if _waiting_for != &"" and _is_bindable(event):
get_viewport().set_input_as_handled()
if not rebind(_waiting_for, event):
show_conflict_warning(event) # offer swap or cancel
_waiting_for = &""
func _is_bindable(e: InputEvent) -> bool:
if e is InputEventKey or e is InputEventJoypadButton or e is InputEventMouseButton:
return e.pressed and not e.is_echo() # ignore releases and key repeat
return e is InputEventJoypadMotion and absf(e.axis_value) > 0.5 # ignore stick noise
func rebind(action: StringName, captured: InputEvent) -> bool:
var event := _to_binding(captured)
for other in InputMap.get_actions():
if other != action and not String(other).begins_with("ui_") \
and InputMap.action_has_event(other, event):
return false # already used -> let UI warn/swap
for old in InputMap.action_get_events(action):
if old.get_class() == event.get_class(): # replace only this device kind's binding
InputMap.action_erase_event(action, old)
InputMap.action_add_event(action, event)
save_bindings() # persist (see save-systems)
return true
func _to_binding(e: InputEvent) -> InputEvent:
if e is InputEventKey: # bind the physical key, not the layout's letter
var k := InputEventKey.new()
k.physical_keycode = e.physical_keycode
return k
var b := e.duplicate() as InputEvent
b.device = -1 # all devices: a pad binding must not stick to pad 0
if b is InputEventJoypadMotion:
b.axis_value = signf(b.axis_value) # keep the direction only
return b
Keyboard bindings use physical_keycode with keycode left at 0, which makes Godot match by key
position, so WASD stays in place on AZERTY or Dvorak. Show the player's own label with
DisplayServer.keyboard_get_label_from_physical. Reset to defaults with
InputMap.load_from_project_settings(). Unity: PerformInteractiveRebinding() and
SaveBindingOverridesAsJson()/LoadBindingOverridesFromJson(). Unreal: Enhanced Input User
Settings with player-mappable keys.
5. Binding audit (headless, exits 1 on problems)
# tools/audit_bindings.gd: godot --headless --path . --script res://tools/audit_bindings.gd
extends SceneTree
const KEYBOARD_ONLY := [&"toggle_console"] # actions allowed to have no gamepad binding
func _initialize() -> void:
var problems := PackedStringArray()
var actions := InputMap.get_actions().filter(func(a): return not String(a).begins_with("ui_"))
for i in actions.size():
var action: StringName = actions[i]
var events := InputMap.action_get_events(action)
if not events.any(func(e): return e is InputEventKey or e is InputEventMouseButton):
problems.append("%s: no keyboard or mouse binding" % action)
if action not in KEYBOARD_ONLY and not events.any(
func(e): return e is InputEventJoypadButton or e is InputEventJoypadMotion):
problems.append("%s: no gamepad binding" % action)
for other in actions.slice(i + 1):
for e in events:
for o in InputMap.action_get_events(other):
if e.is_match(o, true): # exact: axis direction and modifiers count
problems.append("%s and %s share %s" % [action, other, e.as_text()])
for p in problems:
printerr("BINDING: ", p)
print("Checked %d actions, %d problems" % [actions.size(), problems.size()])
quit(1 if problems.size() > 0 else 0)
It reads the project's [input] section. Exact matching matters: with the default loose match,
move_left and move_right on the two directions of one stick axis would count as a conflict.
Two actions that are never active at the same time (a menu action and a gameplay action) may
share a key; list such pairs instead of deleting the check.
Check it
- Run the binding audit and fix every line it prints. In Unity or Unreal, do the same review on
the
.inputactionsJSON or by listing mapping-context keys. - Unit-test the pure parts headless with fixed inputs: deadzone outputs at 0, at the deadzone
edge and on a diagonal; a buffered press fires once and expires after the window. Follow
godot-gdscript-headless-testingfor the runner and exit codes. - Grep gameplay code for raw key reads again; the count should be zero outside debug tools.
- Ask the user to plug in a gamepad, rebind one action to a face button, restart the game and report whether the new binding still works, whether prompts switch between keyboard and pad glyphs, and whether a second pad can use the rebound button. You cannot press buttons yourself, so do not report device behaviour you have not had confirmed.
Gotchas
- Edge vs held confusion. A held check for jump re-fires every frame; an edge check for movement drops held input.
- Per-axis deadzones clip diagonals and snap movement to the axes. Use a radial deadzone.
- A buffered press fires twice because
consumenever clears it, or it fires after a respawn because nothing callsclear(). - A buffer that expires during hit-stop or pause is counting wall-clock time
(
Time.get_ticks_msec). Use game time from the physics step. - Rebinding without conflict handling lets two actions share a key, or strands the player by unbinding the menu. Detect conflicts and keep an unbindable way back.
- WASD in the wrong place on AZERTY or QWERTZ: bindings stored by key letter follow the layout. Store physical positions and show the layout's label.
- A rebound gamepad button works only for player 1: the captured event kept pad 0's device
ID. Store bindings for all devices (Godot
device = -1) unless pads are assigned on purpose. - Comparing InputEvents with
==is always false for two separate objects. Useaction_has_eventoris_match. - "Press Space" shown to a gamepad player. Track the last device that sent input and swap glyphs on every change, without a restart.
- Steam Input reports every pad as Xbox when it is on for that controller, so name and ID checks pick the wrong glyphs. Ask Steam for the real type (details in the reference).
- Hold-only actions, required chords and fixed sensitivity block some players. Offer toggle vs hold, single-input alternatives and sensitivity settings.
References
references/buffering-and-accessibility.md: read when tuning buffer windows, choosing button glyphs per controller family (SDL3 positions, Steam Input), building touch controls, or reviewing an accessibility checklist for controls.
Related skills
platformer: coyote time, jump buffering, variable jump height and jump feel.unity-input-system,unreal-enhanced-input: engine input assets and APIs.save-systems: persisting bindings and input settings.game-ui-ux: menu focus and navigation;camera-systems: look sensitivity and invert.
Version notes
Last verified: 2026-11-11.
- Godot 4.7:
Input.is_action_just_pressedis true on the frame or physics tick of the press;InputEvent.is_match(event, exact_match = true);get_joy_info()fillsraw_name,vendor_idandproduct_idon Windows, Linux, macOS and iOS, andsteam_input_indexon desktop only (https://github.com/godotengine/godot/blob/4.7-stable/doc/classes/Input.xml). - The binding audit and action buffer above were run on Godot 4.7.2 headless.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |