Input¶
Responsibility¶
input_manager loads and stores physical bindings and normalizes keyboard, mouse, gamepad,
touch/backend events. input_context registers semantic actions for one UI and resolves an
event into an action, including help, conflicts, timeout, directions, and text input.
Entry points¶
Read src/input.h, src/input.cpp, src/input_context.h, and src/input_context.cpp. Initialize
the manager once, construct a named context, register every accepted action, then call
handle_input and branch on the returned action ID.
Data ownership¶
The global manager owns loaded binding maps and backend key-name mappings. A local context owns its registered action set and transient input mode; UI code owns the meaning and resulting state transition.
Dependencies¶
Input depends on platform event backends, keybinding JSON, translation of action names, UI mode, options, SDL/curses codes, Android mode, and optional Lua UI routing.
Lifecycle¶
Defaults and user overrides load at startup; a UI creates and configures a context; backend events normalize and resolve; the context is destroyed; changed global mappings can be saved.
Invariants¶
Action IDs are stable strings; every handled action is registered; context overrides fall back according to manager policy; portable key names round trip; and timeout/edit modes reset when their context exits.
Extension points¶
Add a semantic action to the narrowest context and update default bindings/data. Platform
backends should emit normalized input_events, not hard-code gameplay commands.
Serialization¶
Bindings are user configuration written by input_manager::save, not world-save state. Local
contexts, queued events, timeouts, and focus are ephemeral.
Tests¶
Exercise the affected UI plus binding load/save, conflict, fallback, portable-name, mouse/touch, and backend mode behavior. Manual checks must name the platform and input device.
Performance¶
Input handling is latency-sensitive. Avoid rescanning all actions per event, blocking work in a redraw callback, and unnecessary polling outside the manager's timeout model.
CCB divergence¶
CCB routes input across native, Lua UI, Android new UI, and legacy modes. An upstream binding or context port must preserve action IDs and all enabled routing branches.
Technical debt¶
Global mappings and multiple platform code systems make implicit assumptions easy. New code should use portable names and semantic actions rather than raw key integers.