input-action-routing-workflow

name	input-action-routing-workflow
description	Operational workflow for routing InputMap actions through a single authority with deterministic debounce and repeat behavior.
tier	operational
godot_version	4.6+
doc_anchors	["godot-docs/getting_started/step_by_step/scripting_player_input.rst","godot-docs/tutorials/inputs/inputevent.rst","godot-docs/tutorials/inputs/input_examples.rst","godot-docs/classes/class_inputmap.rst","godot-docs/classes/class_input.rst"]
tags	["input","workflow","routing"]
depends_on	["godot-skills/godot-tertiary/input-debounce-repeat-contract/SKILL.md","godot-skills/godot-secondary/domain-ui-input-accessibility/SKILL.md"]

Input Action Routing Workflow

Use When

• Input handling is spread across many nodes and causes duplicate triggers.
• UI and gameplay both consume the same actions inconsistently.
• Hold/repeat behavior must be unified across keyboard and controller.

Outcomes

• One input authority node defines routing order and ownership boundaries.
• Discrete, hold, and repeat actions are handled with explicit policies.
• InputMap actions stay remap-safe across devices.

Required Rules

• Route gameplay actions through _unhandled_input(event) before polling fallbacks.
• Use InputMap action names; avoid direct key-code logic in gameplay systems.
• Keep one authoritative consumer path per action in a given context.
• Implement repeat cadence in gameplay code, not OS key echo behavior.

Workflow

1. Inventory actions and classify each as discrete, hold, or repeat.
2. Assign one authority node to consume actions for current gameplay context.
3. Wire UI-first consumption boundaries and hand off only unhandled gameplay events.
4. Add deterministic repeat controller for grid/selection style actions.
5. Verify parity across keyboard/controller mappings and context transitions.

Validation

• Action collision test: same action bound to UI and gameplay only fires one path.
• Repeat cadence test: held action follows configured initial delay and interval.
• Device parity test: keyboard and controller trigger equivalent action semantics.

Failure Modes

• _input and _unhandled_input both mutate gameplay state for same action.
• Multiple subtree listeners consume identical action, creating double-apply bugs.
• OS repeat/echo drives gameplay cadence and differs by platform.

Local Doc Anchors

• godot-docs/getting_started/step_by_step/scripting_player_input.rst
• godot-docs/tutorials/inputs/inputevent.rst
• godot-docs/tutorials/inputs/input_examples.rst
• godot-docs/classes/class_inputmap.rst
• godot-docs/classes/class_input.rst