rgame 0.1.0

data/ext/rgame_core/input/device_slots.c

@@ -0,0 +1,103 @@
+#include "input/device_slots.h"
+
+#include <string.h>
+
+/* memcmp returns 0 when the two byte ranges are identical, so this reads as
+ * "same GUID" rather than as an inverted comparison at each call site. */
+static int guid_equal(const rgame_device_guid *a, const rgame_device_guid *b) {
+    return memcmp(a->bytes, b->bytes, RGAME_DEVICE_GUID_BYTES) == 0;
+}
+
+static int slot_in_range(int slot) {
+    return slot >= 0 && slot < RGAME_MAX_DEVICE_SLOTS;
+}
+
+void rgame_device_slots_init(rgame_device_slots *table) {
+    for (int i = 0; i < RGAME_MAX_DEVICE_SLOTS; i++) {
+        rgame_device_slot *slot = &table->slots[i];
+        slot->connected = 0;
+        slot->remembered = 0;
+        slot->instance_id = RGAME_DEVICE_SLOT_NONE;
+        memset(slot->guid.bytes, 0, RGAME_DEVICE_GUID_BYTES);
+    }
+}
+
+int rgame_device_slots_find(const rgame_device_slots *table, int instance_id) {
+    for (int i = 0; i < RGAME_MAX_DEVICE_SLOTS; i++) {
+        const rgame_device_slot *slot = &table->slots[i];
+        if (slot->connected && slot->instance_id == instance_id) {
+            return i;
+        }
+    }
+    return RGAME_DEVICE_SLOT_NONE;
+}
+
+int rgame_device_slots_connect(rgame_device_slots *table,
+                               const rgame_device_guid *guid,
+                               int instance_id) {
+    /* Already connected: a duplicate event must not consume a second slot. */
+    int existing = rgame_device_slots_find(table, instance_id);
+    if (existing != RGAME_DEVICE_SLOT_NONE) {
+        return existing;
+    }
+
+    /* Preferred: a free slot that remembers this GUID — the reconnect case.
+     * Only free slots are considered, which is what keeps two identical pads
+     * (same GUID, see the header) from fighting over one slot. */
+    for (int i = 0; i < RGAME_MAX_DEVICE_SLOTS; i++) {
+        rgame_device_slot *slot = &table->slots[i];
+        if (!slot->connected && slot->remembered && guid_equal(&slot->guid, guid)) {
+            slot->connected = 1;
+            slot->instance_id = instance_id;
+            return i;
+        }
+    }
+
+    /* Otherwise the lowest free slot, remembering this GUID for next time. */
+    for (int i = 0; i < RGAME_MAX_DEVICE_SLOTS; i++) {
+        rgame_device_slot *slot = &table->slots[i];
+        if (!slot->connected) {
+            slot->connected = 1;
+            slot->remembered = 1;
+            slot->instance_id = instance_id;
+            slot->guid = *guid;
+            return i;
+        }
+    }
+
+    /* All four players already have a controller. */
+    return RGAME_DEVICE_SLOT_NONE;
+}
+
+int rgame_device_slots_disconnect(rgame_device_slots *table, int instance_id) {
+    int index = rgame_device_slots_find(table, instance_id);
+    if (index == RGAME_DEVICE_SLOT_NONE) {
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+
+    rgame_device_slot *slot = &table->slots[index];
+    slot->connected = 0;
+    slot->instance_id = RGAME_DEVICE_SLOT_NONE;
+    /* `remembered` and `guid` deliberately survive: they are what a later
+     * reconnect matches against to reclaim this same slot. */
+    return index;
+}
+
+int rgame_device_slots_connected(const rgame_device_slots *table, int slot) {
+    return slot_in_range(slot) ? table->slots[slot].connected : 0;
+}
+
+int rgame_device_slots_instance_id(const rgame_device_slots *table, int slot) {
+    if (!slot_in_range(slot) || !table->slots[slot].connected) {
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+    return table->slots[slot].instance_id;
+}
+
+int rgame_device_slots_count(const rgame_device_slots *table) {
+    int count = 0;
+    for (int i = 0; i < RGAME_MAX_DEVICE_SLOTS; i++) {
+        count += table->slots[i].connected ? 1 : 0;
+    }
+    return count;
+}

data/ext/rgame_core/input/device_slots.h

@@ -0,0 +1,93 @@
+#ifndef RGAME_DEVICE_SLOTS_H
+#define RGAME_DEVICE_SLOTS_H
+
+/*
+ * Player slots for game controllers — pure logic, no SDL, no I/O.
+ *
+ * This is "layer 1" per CLAUDE.md's abstraction strategy: all the decisions
+ * about *which player a controller belongs to* live here as plain arithmetic
+ * over plain structs, so they can be exercised by the Check suite without ever
+ * plugging in real hardware.
+ *
+ * The problem it solves: the engine wants a stable "player 1 / player 2 / ..."
+ * index, and SDL does not provide one. SDL's joystick *device index* renumbers
+ * whenever anything is plugged or unplugged, and its *instance id* is unique
+ * per connection — unplug a pad and plug the same one back in and you get a
+ * fresh instance id. Either would shuffle players around mid-game, which is
+ * exactly what docs/c_engine_feature_specs.md rules out when it asks for
+ * indices "stable across a momentary disconnect/reconnect".
+ *
+ * So this table owns the mapping instead. Each slot remembers the GUID of the
+ * last device that filled it, even after that device disconnects. A pad that
+ * comes back reclaims the slot it had; a genuinely new pad takes the lowest
+ * free one.
+ *
+ * IMPORTANT — a GUID identifies a device *model*, not an individual unit. Two
+ * identical controllers report the same GUID, so "the slot remembering this
+ * GUID" can be ambiguous. The rule below resolves it by only ever reclaiming a
+ * slot that is currently free, which gives the behaviour a player expects:
+ * two matching pads take slots 0 and 1, and whichever one is unplugged gets
+ * its own slot back when it returns.
+ */
+
+/* Four players, matching the feature spec's "up to 4 simultaneous controllers". */
+#define RGAME_MAX_DEVICE_SLOTS 4
+
+/* Matches the size of an SDL_JoystickGUID, without naming SDL here. */
+#define RGAME_DEVICE_GUID_BYTES 16
+
+/* Returned by the lookup functions when there is no such slot/device. */
+#define RGAME_DEVICE_SLOT_NONE (-1)
+
+typedef struct {
+    unsigned char bytes[RGAME_DEVICE_GUID_BYTES];
+} rgame_device_guid;
+
+typedef struct {
+    int connected;   /* is a device plugged into this slot right now */
+    int remembered;  /* has this slot ever been filled (i.e. is `guid` meaningful) */
+    int instance_id; /* caller's handle for the live device; NONE while empty */
+    rgame_device_guid guid;
+} rgame_device_slot;
+
+typedef struct {
+    rgame_device_slot slots[RGAME_MAX_DEVICE_SLOTS];
+} rgame_device_slots;
+
+/* Empties every slot and forgets every remembered GUID. */
+void rgame_device_slots_init(rgame_device_slots *table);
+
+/*
+ * Assigns a newly connected device to a slot and returns that slot's index,
+ * or RGAME_DEVICE_SLOT_NONE if all slots are already occupied.
+ *
+ * Order of preference:
+ *   1. the device is already connected (same instance_id) — returns its slot
+ *      unchanged, so a duplicate connect event is harmless;
+ *   2. the lowest *free* slot that remembers this GUID — the reconnect case;
+ *   3. the lowest free slot.
+ */
+int rgame_device_slots_connect(rgame_device_slots *table,
+                               const rgame_device_guid *guid,
+                               int instance_id);
+
+/*
+ * Marks the slot holding `instance_id` as free and returns its index, or
+ * RGAME_DEVICE_SLOT_NONE if no slot held it. The slot keeps its remembered
+ * GUID — that is the whole point, and what lets a reconnect reclaim it.
+ */
+int rgame_device_slots_disconnect(rgame_device_slots *table, int instance_id);
+
+/* The slot currently holding `instance_id`, or RGAME_DEVICE_SLOT_NONE. */
+int rgame_device_slots_find(const rgame_device_slots *table, int instance_id);
+
+/* Whether a device is plugged into `slot`. Out-of-range slots are simply 0. */
+int rgame_device_slots_connected(const rgame_device_slots *table, int slot);
+
+/* The live device in `slot`, or RGAME_DEVICE_SLOT_NONE if it is empty. */
+int rgame_device_slots_instance_id(const rgame_device_slots *table, int slot);
+
+/* How many slots currently have a device plugged in. */
+int rgame_device_slots_count(const rgame_device_slots *table);
+
+#endif /* RGAME_DEVICE_SLOTS_H */

data/ext/rgame_core/input/gamepad.c

@@ -0,0 +1,145 @@
+#include "input/gamepad.h"
+
+#include <SDL2/SDL.h>
+
+/* The pure modules size their arrays from these; if SDL ever grows a button or
+ * an axis, the snapshot copies below would silently truncate without this. */
+_Static_assert(RGAME_GAMEPAD_BUTTON_COUNT == SDL_CONTROLLER_BUTTON_MAX,
+               "RGAME_GAMEPAD_BUTTON_COUNT must match SDL_CONTROLLER_BUTTON_MAX");
+_Static_assert(RGAME_GAMEPAD_AXIS_COUNT == SDL_CONTROLLER_AXIS_MAX,
+               "RGAME_GAMEPAD_AXIS_COUNT must match SDL_CONTROLLER_AXIS_MAX");
+
+/* Gamepad button ids are the gamepad range plus SDL's own button number, so
+ * each named id must line up with the SDL constant it mirrors. */
+_Static_assert(RGAME_PAD_A == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_A,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_START == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_START,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_DPAD_UP == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_UP,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_DPAD_RIGHT ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_AXIS_LEFT_X == SDL_CONTROLLER_AXIS_LEFTX, "axis id must match SDL axis");
+_Static_assert(RGAME_AXIS_TRIGGER_RIGHT == SDL_CONTROLLER_AXIS_TRIGGERRIGHT,
+               "axis id must match SDL axis");
+
+/* Every named pad id must land inside the gamepad range, or a query would be
+ * rejected as belonging to a different device class. */
+_Static_assert(RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_MAX - 1 <=
+                   RGAME_BUTTON_GAMEPAD_LAST,
+               "SDL controller buttons must fit the gamepad button-id range");
+
+static SDL_GameController *controller_at(const rgame_gamepads *pads, int slot) {
+    if (slot < 0 || slot >= RGAME_INPUT_MAX_GAMEPADS) {
+        return NULL;
+    }
+    return (SDL_GameController *)pads->controllers[slot];
+}
+
+void rgame_gamepads_init(rgame_gamepads *pads) {
+    rgame_device_slots_init(&pads->slots);
+    for (int i = 0; i < RGAME_INPUT_MAX_GAMEPADS; i++) {
+        pads->controllers[i] = NULL;
+    }
+}
+
+void rgame_gamepads_shutdown(rgame_gamepads *pads) {
+    for (int i = 0; i < RGAME_INPUT_MAX_GAMEPADS; i++) {
+        SDL_GameController *pad = controller_at(pads, i);
+        if (pad) {
+            SDL_GameControllerClose(pad);
+            pads->controllers[i] = NULL;
+        }
+    }
+    rgame_device_slots_init(&pads->slots);
+}
+
+int rgame_gamepads_add(rgame_gamepads *pads, int device_index) {
+    /* A joystick is only a *game controller* if SDL has a button mapping for
+     * it. Anything else (a flight stick, a dance mat) is ignored rather than
+     * seated in a player slot with meaningless buttons. */
+    if (!SDL_IsGameController(device_index)) {
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+
+    SDL_GameController *pad = SDL_GameControllerOpen(device_index);
+    if (!pad) {
+        SDL_Log("SDL_GameControllerOpen(%d) failed: %s", device_index, SDL_GetError());
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+
+    SDL_Joystick *joystick = SDL_GameControllerGetJoystick(pad);
+    SDL_JoystickID instance_id = SDL_JoystickInstanceID(joystick);
+    SDL_JoystickGUID sdl_guid = SDL_JoystickGetGUID(joystick);
+
+    /* SDL_JoystickGUID is a 16-byte blob; the slot table keeps its own copy in
+     * an SDL-free struct of the same size (asserted here rather than hoped). */
+    _Static_assert(sizeof(sdl_guid.data) == RGAME_DEVICE_GUID_BYTES,
+                   "SDL joystick GUID must be RGAME_DEVICE_GUID_BYTES long");
+    rgame_device_guid guid;
+    SDL_memcpy(guid.bytes, sdl_guid.data, RGAME_DEVICE_GUID_BYTES);
+
+    int slot = rgame_device_slots_connect(&pads->slots, &guid, (int)instance_id);
+    if (slot == RGAME_DEVICE_SLOT_NONE) {
+        /* All four players already have a pad: don't hold a handle we can't
+         * reach, or it would leak until shutdown. */
+        SDL_GameControllerClose(pad);
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+
+    pads->controllers[slot] = pad;
+    return slot;
+}
+
+int rgame_gamepads_remove(rgame_gamepads *pads, int instance_id) {
+    int slot = rgame_device_slots_disconnect(&pads->slots, instance_id);
+    if (slot == RGAME_DEVICE_SLOT_NONE) {
+        return RGAME_DEVICE_SLOT_NONE;
+    }
+
+    SDL_GameController *pad = controller_at(pads, slot);
+    if (pad) {
+        SDL_GameControllerClose(pad);
+        pads->controllers[slot] = NULL;
+    }
+    return slot;
+}
+
+void rgame_gamepads_snapshot(const rgame_gamepads *pads, rgame_input_state *state) {
+    for (int slot = 0; slot < RGAME_INPUT_MAX_GAMEPADS; slot++) {
+        SDL_GameController *pad = controller_at(pads, slot);
+        if (!pad) {
+            /* No pad: clear rather than leave the last reading, so a button
+             * held at the moment of unplugging doesn't stay stuck down. */
+            rgame_input_state_clear_pad(state, slot);
+            continue;
+        }
+
+        unsigned char buttons[RGAME_GAMEPAD_BUTTON_COUNT];
+        for (int i = 0; i < RGAME_GAMEPAD_BUTTON_COUNT; i++) {
+            buttons[i] = SDL_GameControllerGetButton(pad, (SDL_GameControllerButton)i);
+        }
+
+        float axes[RGAME_GAMEPAD_AXIS_COUNT];
+        for (int i = 0; i < RGAME_GAMEPAD_AXIS_COUNT; i++) {
+            int raw = SDL_GameControllerGetAxis(pad, (SDL_GameControllerAxis)i);
+            axes[i] = rgame_input_axis_normalize(raw);
+        }
+
+        rgame_input_state_set_pad(state, slot, buttons, axes);
+    }
+}
+
+int rgame_gamepads_connected(const rgame_gamepads *pads, int slot) {
+    return controller_at(pads, slot) != NULL;
+}
+
+int rgame_gamepads_count(const rgame_gamepads *pads) {
+    return rgame_device_slots_count(&pads->slots);
+}
+
+const char *rgame_gamepads_name(const rgame_gamepads *pads, int slot) {
+    SDL_GameController *pad = controller_at(pads, slot);
+    return pad ? SDL_GameControllerName(pad) : NULL;
+}

data/ext/rgame_core/input/gamepad.h

@@ -0,0 +1,63 @@
+#ifndef RGAME_GAMEPAD_H
+#define RGAME_GAMEPAD_H
+
+#include "input/device_slots.h"
+#include "input/input.h"
+
+/*
+ * The game-controller shim — "layer 3", the thin real SDL part.
+ *
+ * Deliberately dumb. Every decision about *which player a pad belongs to*
+ * lives in device_slots.{c,h}, and every decision about *what a button id
+ * means* lives in input.{c,h}; both are pure and unit-tested. What is left
+ * here is opening and closing SDL handles and copying values, which is little
+ * enough to get wrong that it justifies not unit-testing it directly (see
+ * CLAUDE.md's verification tiers).
+ *
+ * The SDL_GameController pointers are held as void* so this header stays free
+ * of SDL types and can be included from app.c without ordering constraints —
+ * the same reason include/rgame/core.h names none either.
+ */
+
+typedef struct {
+    rgame_device_slots slots;
+    /* SDL_GameController* per player slot; NULL when the slot is empty. */
+    void *controllers[RGAME_INPUT_MAX_GAMEPADS];
+} rgame_gamepads;
+
+void rgame_gamepads_init(rgame_gamepads *pads);
+
+/* Closes every open controller. Safe to call twice. */
+void rgame_gamepads_shutdown(rgame_gamepads *pads);
+
+/*
+ * Opens the controller at SDL device index `device_index` and seats it in a
+ * player slot. Returns the slot, or RGAME_DEVICE_SLOT_NONE if the device isn't
+ * a game controller, can't be opened, or every slot is taken.
+ *
+ * Note `device_index` is SDL's *device index*, which is what
+ * SDL_CONTROLLERDEVICEADDED reports — not the instance id.
+ */
+int rgame_gamepads_add(rgame_gamepads *pads, int device_index);
+
+/*
+ * Releases the controller with SDL instance id `instance_id` and frees its
+ * slot, returning that slot or RGAME_DEVICE_SLOT_NONE if it wasn't seated.
+ *
+ * Note SDL_CONTROLLERDEVICEREMOVED reports an *instance id*, not a device
+ * index — the two are different numbers in the same `which` field, which is
+ * an easy and silent mistake to make.
+ */
+int rgame_gamepads_remove(rgame_gamepads *pads, int instance_id);
+
+/* Copies every connected pad's buttons and axes into the frame snapshot, and
+ * zeroes the slots that have no controller. */
+void rgame_gamepads_snapshot(const rgame_gamepads *pads, rgame_input_state *state);
+
+int rgame_gamepads_connected(const rgame_gamepads *pads, int slot);
+int rgame_gamepads_count(const rgame_gamepads *pads);
+
+/* Display name of the pad in `slot`, or NULL when empty. Owned by SDL. */
+const char *rgame_gamepads_name(const rgame_gamepads *pads, int slot);
+
+#endif /* RGAME_GAMEPAD_H */

data/ext/rgame_core/input/input.c

@@ -0,0 +1,109 @@
+#include "input/input.h"
+
+#include <string.h>
+
+int rgame_button_is_keyboard(int button_id) {
+    return button_id >= RGAME_BUTTON_KEYBOARD_FIRST &&
+           button_id <= RGAME_BUTTON_KEYBOARD_LAST;
+}
+
+int rgame_button_is_gamepad(int button_id) {
+    return button_id >= RGAME_BUTTON_GAMEPAD_FIRST &&
+           button_id <= RGAME_BUTTON_GAMEPAD_LAST;
+}
+
+int rgame_input_device_valid(int device) {
+    return device >= 0 && device < RGAME_INPUT_DEVICE_COUNT;
+}
+
+int rgame_input_device_slot(int device) {
+    if (device < RGAME_INPUT_GAMEPAD_FIRST || device >= RGAME_INPUT_DEVICE_COUNT) {
+        return -1;
+    }
+    return device - RGAME_INPUT_GAMEPAD_FIRST;
+}
+
+float rgame_input_axis_normalize(int raw) {
+    float value = (float)raw / 32767.0f;
+    if (value < -1.0f) {
+        return -1.0f; /* raw == -32768 is one step past the positive limit */
+    }
+    if (value > 1.0f) {
+        return 1.0f;
+    }
+    return value;
+}
+
+void rgame_input_state_clear(rgame_input_state *state) {
+    memset(state->keys, 0, sizeof(state->keys));
+    memset(state->pad_buttons, 0, sizeof(state->pad_buttons));
+    memset(state->pad_axes, 0, sizeof(state->pad_axes));
+}
+
+void rgame_input_state_set_pad(rgame_input_state *state, int slot,
+                               const unsigned char *buttons, const float *axes) {
+    if (slot < 0 || slot >= RGAME_INPUT_MAX_GAMEPADS) {
+        return;
+    }
+    memcpy(state->pad_buttons[slot], buttons, sizeof(state->pad_buttons[slot]));
+    memcpy(state->pad_axes[slot], axes, sizeof(state->pad_axes[slot]));
+}
+
+void rgame_input_state_clear_pad(rgame_input_state *state, int slot) {
+    if (slot < 0 || slot >= RGAME_INPUT_MAX_GAMEPADS) {
+        return;
+    }
+    memset(state->pad_buttons[slot], 0, sizeof(state->pad_buttons[slot]));
+    memset(state->pad_axes[slot], 0, sizeof(state->pad_axes[slot]));
+}
+
+float rgame_input_state_axis(const rgame_input_state *state, int device, int axis_id) {
+    int slot = rgame_input_device_slot(device);
+    if (slot < 0 || axis_id < 0 || axis_id >= RGAME_GAMEPAD_AXIS_COUNT) {
+        return 0.0f;
+    }
+    return state->pad_axes[slot][axis_id];
+}
+
+void rgame_input_state_set_keys(rgame_input_state *state, const unsigned char *keys) {
+    memcpy(state->keys, keys, sizeof(state->keys));
+}
+
+int rgame_input_state_down(const rgame_input_state *state, int device, int button_id) {
+    if (device == RGAME_INPUT_KEYBOARD) {
+        /* A gamepad button asked of the keyboard is simply not held. */
+        if (!rgame_button_is_keyboard(button_id)) {
+            return 0;
+        }
+        /* The keyboard range (0x0FFF) is wider than the scancodes SDL actually
+         * defines, so the array bound is checked separately from the range. */
+        if (button_id >= RGAME_KEYBOARD_KEY_COUNT) {
+            return 0;
+        }
+        return state->keys[button_id] ? 1 : 0;
+    }
+
+    /*
+     * A gamepad answers only for gamepad buttons — and this check has to come
+     * *before* the subtraction below, not merely alongside the bound check.
+     * For a hugely negative id, `button_id - RGAME_BUTTON_GAMEPAD_FIRST` is
+     * signed overflow, i.e. undefined behaviour, before any bound check gets a
+     * chance to reject it. (Confirmed by removing this guard: UBSan reports
+     * "signed integer overflow: -2147483648 - 4096".)
+     */
+    if (!rgame_button_is_gamepad(button_id)) {
+        return 0;
+    }
+
+    /* rgame_input_device_slot rejects the keyboard and any out-of-range device
+     * by returning -1, so no separate device-validity check is needed here. */
+    int slot = rgame_input_device_slot(device);
+    int index = button_id - RGAME_BUTTON_GAMEPAD_FIRST;
+    /* The gamepad range (256 ids) is wider than the buttons SDL defines, so
+     * the array bound is checked separately from the range — same split as the
+     * keyboard above. A slot with no pad simply holds zeroes. */
+    if (slot < 0 || index < 0 || index >= RGAME_GAMEPAD_BUTTON_COUNT) {
+        return 0;
+    }
+    return state->pad_buttons[slot][index] ? 1 : 0;
+}

data/ext/rgame_core/input/input.h

@@ -0,0 +1,99 @@
+#ifndef RGAME_INPUT_H
+#define RGAME_INPUT_H
+
+#include "rgame/core.h"
+
+/*
+ * The input snapshot — pure logic, no SDL, no I/O.
+ *
+ * "Layer 1" per CLAUDE.md: this holds the *state* and all the rules for
+ * reading it, as plain arrays and integer comparisons, so the Check suite can
+ * fill a snapshot by hand and assert on every query without a keyboard, a
+ * window, or an event loop existing at all.
+ *
+ * Only filling the snapshot from real hardware needs SDL, and that is a
+ * separate handful of lines in app.c — the thin "layer 3" shim.
+ *
+ * Why a snapshot rather than reading hardware on demand: the engine runs a
+ * fixed timestep, so one rendered frame may run zero or several simulation
+ * ticks. If a tick asked the hardware directly, the same held key could read
+ * differently between two ticks of the same frame, and how many ticks ran
+ * depends on how long the last frame took. Sampling once per frame makes the
+ * answer constant across the whole frame.
+ *
+ * Note what this does *not* fix: an edge — "pressed this tick" — is a
+ * comparison against the previous poll, so whatever polls decides what a press
+ * is. Polling per rendered frame while simulating per tick loses presses on a
+ * fast machine. See RGame::Game, which polls in `update`.
+ *
+ * The button-id space and device numbering both live in rgame/core.h, because
+ * callers outside this directory need to name them.
+ */
+
+/* All three == the matching SDL maxima; asserted against SDL in app.c. */
+#define RGAME_KEYBOARD_KEY_COUNT 512
+#define RGAME_GAMEPAD_BUTTON_COUNT 21
+#define RGAME_GAMEPAD_AXIS_COUNT 6
+
+typedef struct {
+    /* One byte per scancode: non-zero means held. A byte array rather than a
+     * bitset because it is what SDL_GetKeyboardState already hands us, so the
+     * snapshot is a straight copy with no packing step on the frame path. */
+    unsigned char keys[RGAME_KEYBOARD_KEY_COUNT];
+
+    /* Per player slot, not per SDL device index — the slot table owns that
+     * mapping, so a pad that is unplugged and replugged keeps writing here. */
+    unsigned char pad_buttons[RGAME_INPUT_MAX_GAMEPADS][RGAME_GAMEPAD_BUTTON_COUNT];
+    float pad_axes[RGAME_INPUT_MAX_GAMEPADS][RGAME_GAMEPAD_AXIS_COUNT];
+} rgame_input_state;
+
+/* Clears every button to "not held". */
+void rgame_input_state_clear(rgame_input_state *state);
+
+/* Replaces the keyboard half of the snapshot. `keys` must have
+ * RGAME_KEYBOARD_KEY_COUNT entries, non-zero meaning held — the exact shape
+ * SDL_GetKeyboardState returns. */
+void rgame_input_state_set_keys(rgame_input_state *state, const unsigned char *keys);
+
+/* Replaces one slot's gamepad state. `buttons` and `axes` must have
+ * RGAME_GAMEPAD_BUTTON_COUNT / RGAME_GAMEPAD_AXIS_COUNT entries. */
+void rgame_input_state_set_pad(rgame_input_state *state, int slot,
+                               const unsigned char *buttons, const float *axes);
+
+/* Zeroes one slot — what a disconnect must do, so a pad unplugged mid-press
+ * does not leave that button stuck held forever. */
+void rgame_input_state_clear_pad(rgame_input_state *state, int slot);
+
+/*
+ * Whether `button_id` is held on `device`. Returns 0 rather than raising for
+ * every out-of-range case: an unknown device, a button outside any range, or a
+ * button belonging to a different device class than the one asked about.
+ */
+int rgame_input_state_down(const rgame_input_state *state, int device, int button_id);
+
+/* Current value of `axis_id` on `device`; 0.0 for anything out of range. */
+float rgame_input_state_axis(const rgame_input_state *state, int device, int axis_id);
+
+/*
+ * Converts a raw SDL axis reading (-32768..32767) to -1.0..1.0.
+ *
+ * The range is asymmetric — there is one more negative value than positive —
+ * so dividing by 32767 would make full-left read slightly past -1.0. The
+ * result is clamped instead, which costs nothing and keeps callers from having
+ * to special-case a single value.
+ */
+float rgame_input_axis_normalize(int raw);
+
+/* The player slot a gamepad device id refers to, or -1 for the keyboard or an
+ * invalid device. */
+int rgame_input_device_slot(int device);
+
+/* Range predicates for the flat button-id space. Exposed because they are the
+ * part worth testing directly, and because app.c uses them too. */
+int rgame_button_is_keyboard(int button_id);
+int rgame_button_is_gamepad(int button_id);
+
+/* Whether `device` names the keyboard or a real gamepad slot. */
+int rgame_input_device_valid(int device);
+
+#endif /* RGAME_INPUT_H */