feat(backends): relocate windowless-SDL desktop gamepad source out of core into assembler (core#28)

[apotema]

What & why

SDL2 is a third-party C library and does not belong in labelle-core's dependency-free per-OS gamepad layer (core's other sources reach the OS HID stack directly: evdev/udev on Linux, JNI on Android, GameController on ios/tvos). This relocates the windowless-SDL desktop gamepad source OUT of labelle-core and INTO the assembler as a shared sub-package, wired into the raylib + sokol DESKTOP backends through the existing InputInterface(Impl) seam.

Precedent followed exactly: Android gamepad STATE already lives in the assembler at backends/sokol/src/android_gamepad_state.zig (NOT core) and is consumed through the Impl seam. This does the same for the desktop SDL source.

Pairs with the core revert labelle-core#30. Refs labelle-core#28.

What moved

• New in-tree sub-package backends/sdl_gamepad/ (own build.zig + build.zig.zon, the toolkit's own-build.zig sub-package convention) holding the relocated desktop.zig logic: SDL externs gated behind comptime is_desktop, per-slot state table, hotplug event ring, button/axis snapshot with canonical raylib-compatible mapping, startup enumeration, spin-lock discipline, and host-testable pure mapping helpers. ONE copy, depended on by BOTH raylib and sokol via .path = "../sdl_gamepad".
• It imports labelle-core under the labelle_core key for GamepadEvent/GamepadDescription/SourceClass/TypeHint; each consuming backend's build.zig unifies its own core onto the module so the event types match across the engine↔backend boundary.

raylib / sokol desktop wiring (Impl seam)

• backends/raylib/src/input.zig: on a desktop target the four gamepad state methods + pollGamepadEvents/describeGamepads route to the shared SDL Source instead of rl.isGamepad*; off-desktop keeps raylib's GLFW path. New newFrame()/initGamepad()/deinitGamepad() drive the source. Gated behind comptime sdl_gp.is_desktop.
• backends/sokol/src/input.zig: on desktop the state methods route to the shared source; on Android they keep android_gamepad_state (existing); ios/tvos keep the GameController bridge. Gated mirroring the existing agp.is_android style.
• The engine synthesizes connect/disconnect by diffing isGamepadAvailable per frame (game.zig), so routing the state surface IS the complete hotplug integration — no new pollGamepadEvents contract needed on sokol.

SDL2 link gating

• backends/raylib/build.zig and backends/sokol/build.zig link SDL2 (linkSystemLibrary("SDL2"), Homebrew /opt/homebrew/lib path on macOS, no @cImport/include) for DESKTOP targets ONLY. Android/iOS/wasm pull NO SDL.
• The SDL render backend is intentionally untouched — it keeps its own SDL_PollEvent loop (two consumers on one queue would steal each other's events).

Pump location

• sokol: backends/sokol/src/input.zig → snapshotGamepadButtons() calls Source.update() once per frame (reached via the sokol desktop template's existing @import("backend_input").newFrame()).
• raylib: backends/raylib/templates/desktop.txt frame-loop top calls @import("backend_input").newFrame(); initGamepad()/deinitGamepad() wrap the loop.

Verification (compile-level; live input not testable headless on macOS — reads zero, expected)

• zig build test green: sdl_gamepad, raylib (+ test-host links raylib & SDL2), sokol, and the top-level assembler. zig fmt --check clean.
• Cross-compile gating: a gating-obj step emits the gamepad surface as an object (no sokol_clib/NDK needed). aarch64-linux-android → 0 undefined SDL_* symbols; wasm32 → none; macOS → 14 SDL_* externs (proves the probe defeats DCE and the comptime gate actually toggles). Android keeps android_gamepad_state.

For reviewers to scrutinize

• Core unification for the GENERATED game build (deferred): each backend's build.zig unifies its own core onto the sdl_gamepad module for standalone backend builds (the CI cd backends/<b> && zig build test path). The full end-to-end generated-game build (which overrideImports core onto backend_input) and the examples/gamepad app are explicitly out of scope here per the task and deferred to a follow-up slice. Verified at the assembler/backend compile level only.
• .path = "../sdl_gamepad" sibling dependency: standard in-tree sub-package convention, but it references a directory outside each backend's own package root — confirm that matches how the toolkit wants narrow shared deps wired (vs. a URL-pinned repo).

[cursor]

PR Summary

Medium Risk
Touches desktop input/linking (new SDL2 dependency on raylib/sokol desktop) and generated-game module unification; non-desktop paths are gated but regressions could affect cross-compile or gamepad hotplug behavior.

Overview
Introduces a new in-tree backends/sdl_gamepad sub-package: windowless SDL2 gamecontroller/joystick (no video window) with raylib-compatible button/axis mapping, hotplug events, and comptime is_desktop gating so Android/iOS/wasm never reference or link SDL.

Raylib and sokol desktop input modules now delegate gamepad state, hotplug pollGamepadEvents/describeGamepads, and per-frame pumping to this shared source instead of GLFW/raylib or “no gamepad” defaults; Android (sokol) and iOS/tvOS paths are unchanged. Raylib adds initGamepad/deinitGamepad/newFrame and wires them in desktop.txt; sokol pumps via existing newFrame → Source.update().

Build wiring: both backends depend on ../sdl_gamepad, link SDL2 (plus Homebrew lib path on native macOS) only for desktop targets, unify labelle-core onto the sub-module, and add gating-obj steps to verify non-desktop builds emit no undefined SDL_* symbols. deps_linker.zig stages sdl_gamepad for generated raylib/sokol projects; build_zig.txt overrideImports app core onto the transitive sdl_gamepad module to avoid duplicate GamepadEvent types. CI examples integration installs libsdl2-dev.

^{Reviewed by Cursor Bugbot for commit 4ed3f1e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces a shared, windowless SDL2-backed desktop gamepad module (backends/sdl_gamepad) integrated into both the Raylib and Sokol backends to handle advanced controller hotplugging and state decoding on desktop platforms while keeping non-desktop builds free of SDL. The review feedback suggests declaring external C functions using extern "c" fn instead of extern fn for proper cross-platform resolution. Additionally, it recommends replacing the heavy std.Io.Threaded directory existence checks in the build files with a simpler, synchronous call to std.fs.accessAbsolute.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When declaring external C functions in Zig (with link_libc = true), use extern "c" fn instead of extern fn without a library name. The "c" is a logical reference to libc, not a literal filename, and is correctly resolved by the compiler across all platforms, including Windows MSVC.

    extern "c" fn SDL_InitSubSystem(flags: u32) c_int;
    extern "c" fn SDL_QuitSubSystem(flags: u32) void;
    extern "c" fn SDL_SetHint(name: [*:0]const u8, value: [*:0]const u8) c_int;
    extern "c" fn SDL_GameControllerUpdate() void;
    extern "c" fn SDL_PollEvent(event: *SDL_Event) c_int;
    // Count of currently-attached joysticks; used to enumerate controllers
    // already plugged in at startup (SDL does not emit CONTROLLERDEVICEADDED
    // for those). Returns a negative value on error.
    extern "c" fn SDL_NumJoysticks() c_int;
    extern "c" fn SDL_IsGameController(joystick_index: c_int) c_int; // SDL_bool (SDL_TRUE == 1)
    extern "c" fn SDL_GameControllerOpen(joystick_index: c_int) ?*SDL_GameController;
    extern "c" fn SDL_GameControllerClose(gamecontroller: *SDL_GameController) void;
    extern "c" fn SDL_GameControllerName(gamecontroller: *SDL_GameController) ?[*:0]const u8;
    extern "c" fn SDL_GameControllerGetButton(gamecontroller: *SDL_GameController, button: c_int) u8;
    extern "c" fn SDL_GameControllerGetAxis(gamecontroller: *SDL_GameController, axis: c_int) i16;
    // Instance id of an opened controller's underlying joystick.
    extern "c" fn SDL_GameControllerGetJoystick(gamecontroller: *SDL_GameController) ?*anyopaque;
    extern "c" fn SDL_JoystickInstanceID(joystick: *anyopaque) i32;

References

1. When declaring external C functions in Zig (with link_libc = true), use extern "c" fn instead of extern fn without a library name.

[gemini-code-assist]

Using std.Io.Threaded to check if a directory exists is unnecessarily heavy and complex, as it spawns threads and allocates memory. In Zig 0.16.0, std.fs.accessAbsolute is a synchronous, standard function that does not require std.fs.cwd() or libc, making it a much simpler and more efficient choice for build-time checks.

    std.fs.accessAbsolute(path, .{}) catch return false;
    return true;

[gemini-code-assist]

Using std.Io.Threaded to check if a directory exists is unnecessarily heavy and complex, as it spawns threads and allocates memory. In Zig 0.16.0, std.fs.accessAbsolute is a synchronous, standard function that does not require std.fs.cwd() or libc, making it a much simpler and more efficient choice for build-time checks.

    std.fs.accessAbsolute(path, .{}) catch return false;
    return true;

[gemini-code-assist]

Using std.Io.Threaded to check if a directory exists is unnecessarily heavy and complex, as it spawns threads and allocates memory. In Zig 0.16.0, std.fs.accessAbsolute is a synchronous, standard function that does not require std.fs.cwd() or libc, making it a much simpler and more efficient choice for build-time checks.

    std.fs.accessAbsolute(path, .{}) catch return false;
    return true;

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

There are 4 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 90a0b71. Configure here.}

[cursor]

Sokol pumps gamepads after tick

High Severity

On sokol desktop, sdl_gamepad.Source.update() runs from newFrame() at the end of frame(), after g.tick(). Gameplay reads isGamepad* during tick, so button state, edges, axes-vs-buttons coherence, and isGamepadAvailable hotplug diffs reflect the previous frame’s pump—not input since the last tick.

 

^{Reviewed by Cursor Bugbot for commit 90a0b71. Configure here.}

[cursor]

Sokol never tears down SDL gamepads

Low Severity

The raylib desktop template pairs initGamepad() and deinitGamepad() around the main loop, but the sokol backend never exposes or calls sdl_gp.Source.deinit(). After the lazy SDL subsystem init from Source.update(), controllers and SDL joystick state may remain open until process exit on sokol desktop builds.

Additional Locations (1)

• backends/raylib/templates/desktop.txt#L18-L20

 

^{Reviewed by Cursor Bugbot for commit 90a0b71. Configure here.}

[apotema]

Review triage (commit aa5f1a8)

Accepted & fixed:

• Cursor — describe() omits empty slots: valid. Source.describe skipped free slots, but the raylib backend documents a fixed MAX_GAMEPADS-slot snapshot (one row per slot with a connected flag). Now emits every slot in order, connected=false + empty name for free slots.

Rejected (with reasons):

• Gemini ×3 — replace std.Io.Threaded dir-check with std.fs.accessAbsolute(path, .{}): rejected — std.fs.accessAbsolute does not exist in Zig 0.16. The real API is std.Io.Dir.accessAbsolute(io, path, .{}), which requires an Io instance — which is exactly why the build uses an ad-hoc std.Io.Threaded. The suggested replacement would not compile.
• Gemini — use extern "c" fn instead of extern fn for the SDL externs: declined as a non-blocking style nit. The build links the SDL2 symbols fine with bare extern fn on the targeted desktop platforms (macOS/Linux), and the "c = libc" rationale is imprecise (SDL isn't libc). Can revisit if/when a Windows-MSVC target is added.

(Build-time dirExists uses std.Io.Threaded deliberately for the 0.16 fs API; not a leak into runtime.)

[Copilot]

Pull request overview

Relocates the windowless SDL2-backed desktop gamepad implementation out of labelle-core and into labelle-assembler as a shared in-tree sub-package, then wires both the raylib and sokol desktop backends to source gamepad state/hotplug through that shared module (while keeping Android/iOS/tvOS paths intact and ensuring non-desktop targets pull no SDL symbols).

Changes:

• Introduces backends/sdl_gamepad/ (module + tests) implementing a shared SDL2 desktop Source with canonical (raylib-compatible) mapping and hotplug event ring.
• Routes desktop gamepad queries in backends/raylib and backends/sokol through the shared SDL source behind comptime gating.
• Updates backend build scripts/zons to add the new sub-package dependency, unify core types onto it, and link SDL2 only for desktop targets; adds a sokol cross-compile gating probe step.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
backends/sokol/src/input.zig	Adds desktop SDL gamepad routing and per-frame pump via snapshotGamepadButtons().
backends/sokol/src/gamepad_gating_probe.zig	Adds an object-only probe to validate SDL symbol gating under cross-compilation.
backends/sokol/build.zig.zon	Adds labelle_sdl_gamepad path dependency and a pinned labelle_core for type unification.
backends/sokol/build.zig	Imports/unifies sdl_gamepad, links SDL2 only on desktop, and adds a gating-obj build step.
backends/sdl_gamepad/src/sdl_gamepad.zig	New shared SDL2-backed desktop gamepad source with mapping helpers and unit tests.
backends/sdl_gamepad/build.zig.zon	Defines the new in-tree sub-package and its pinned labelle_core dependency.
backends/sdl_gamepad/build.zig	Exposes the sdl_gamepad module, host tests, and a gating object step (no SDL link).
backends/raylib/templates/desktop.txt	Pumps backend_input.newFrame() per frame and adds init/deinit calls for SDL gamepad source.
backends/raylib/src/input.zig	Routes desktop gamepad state/hotplug through shared SDL source and adds init/newFrame/deinit.
backends/raylib/build.zig.zon	Adds labelle_sdl_gamepad path dependency.
backends/raylib/build.zig	Imports/unifies sdl_gamepad and links SDL2 only for desktop targets (including host tests).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.