Docs

.claude/input.md

@@ -0,0 +1,93 @@
+# Input System
+
+Source: `src/dusk/input/`
+
+The input system decouples physical hardware buttons from logical game actions via a binding layer. Actions are defined in `src/dusk/input/input.csv` and code-generated into `inputaction_t` enum values — see [architecture.md](architecture.md#code-generation-from-csv).
+
+---
+
+## Concepts
+
+**Button** (`inputbutton_t`) — a physical input source: a keyboard scancode, gamepad button, gamepad axis, or pointer axis. The available button types depend on which `DUSK_INPUT_*` defines are active for the target platform.
+
+**Action** (`inputaction_t`) — a logical game input (e.g. `INPUT_ACTION_UP`, `INPUT_ACTION_CONFIRM`, `INPUT_ACTION_RAGEQUIT`). Each action accumulates a float value `[0.0, 1.0]` from all buttons bound to it.
+
+**Binding** — a many-to-one mapping from buttons to actions. Bindings are registered at runtime with `inputBind(button, action)`.
+
+---
+
+## Querying actions
+
+```c
+// Boolean helpers (current frame):
+inputIsDown(action)        // value > 0 this frame
+inputPressed(action)       // down this frame but not last
+inputReleased(action)      // down last frame but not this
+
+// Last frame state:
+inputWasDown(action)
+
+// Raw float value:
+inputGetCurrentValue(action)   // [0.0, 1.0]
+inputGetLastValue(action)
+
+// Axis helpers — combine two opposing actions into a signed float:
+float_t h = inputAxis(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT);  // -1.0 to 1.0
+inputAxis2D(negX, posX, negY, posY, result);   // fills vec2
+inputAngle2D(negX, posX, negY, posY, result);  // atan2-based normalized direction
+
+// Deadzone:
+float_t clean = inputDeadzone(rawValue, 0.1f);
+```
+
+---
+
+## Dynamic values (`DUSK_TIME_DYNAMIC`)
+
+On platforms with variable frame rates, each action also tracks `dynamicDelta`-scaled values:
+
+```c
+inputGetCurrentValueDynamic(action)
+inputGetLastValueDynamic(action)
+```
+
+These account for the actual time elapsed since the last frame, so movement calculated from them is frame-rate independent.
+
+---
+
+## Events on actions
+
+Each `inputactiondata_t` exposes `onPressed` and `onReleased` events:
+
+```c
+eventSubscribe(&INPUT.actions[INPUT_ACTION_CONFIRM].onPressed, myCallback, myUser);
+```
+
+The callback signature is `void cb(void *params, void *user)`. `params` is always `NULL` for input events.
+
+---
+
+## Buttons and bindings
+
+Physical buttons are typed via `inputbuttontype_t`:
+
+| Constant | When available | Payload |
+|---|---|---|
+| `INPUT_BUTTON_TYPE_KEYBOARD` | `DUSK_INPUT_KEYBOARD` | `inputscancode_t` |
+| `INPUT_BUTTON_TYPE_GAMEPAD` | `DUSK_INPUT_GAMEPAD` | `inputgamepadbutton_t` |
+| `INPUT_BUTTON_TYPE_GAMEPAD_AXIS` | `DUSK_INPUT_GAMEPAD` | axis + positive direction flag |
+| `INPUT_BUTTON_TYPE_POINTER` | `DUSK_INPUT_POINTER` | `inputpointeraxis_t` |
+
+Button names and default bindings are defined in `input.csv`. Look up a button by name:
+```c
+inputbutton_t btn = inputButtonGetByName("keyboard_w");
+inputBind(btn, INPUT_ACTION_UP);
+```
+
+`INPUT_BUTTON_DATA[]` holds runtime state (current/last raw values) for every physical button.
+
+---
+
+## Platform platform-specific reads
+
+`inputButtonGetValuePlatform(button)` is the one required platform function — it returns the current raw `[0.0, 1.0]` value for a button. The platform implementations live in `src/dusk{platform}/input/`.