feat(bgfx): desktop GLFW gamepad reading (buttons + axes)

[apotema]

Implement bgfx desktop GLFW gamepad reading (buttons + axes). The bgfx desktop input path only had isGamepadAvailable (joystick presence); isGamepadButtonDown/Pressed/getGamepadAxisValue were return false/0 TODO stubs — so a bgfx game on desktop knew a pad was plugged in but received no input from it.

What

Read via glfw.getGamepadState, translating the engine's canonical raylib-compatible numbering — buttons [0,17], axes LX/LY/RX/RY/LT/RT = [0,5] (matching android_gamepad + the raylib/sdl backends) — to GLFW's standard layout:

• canonToGlfwButton maps face/dpad/bumper/thumb/middle buttons; the digital LEFT/RIGHT_TRIGGER_2 (10/12) are derived from the analog trigger axes (> 0).
• Axes are 1:1 (canonical 0..5 == GLFW 0..5).
• isGamepadButtonPressed rising edges are snapshotted once per gamepad per frame in newFrame (snapshotGamepads), mirroring the keyboard/mouse *_pressed pattern — one getGamepadState per slot, not per query.

The Android path (#310) is untouched; the agp-vs-GLFW split is comptime-gated.

Verification

• bgfx desktop zig build test + Android compile-check + example build → green.
• On-host probe (macOS): a connected controller in slot 0 reads as present but NOT a GLFW-mapped gamepad — confirming the documented limit: GLFW can't decode a Switch-mode Nintendo Pro Controller (only SDL's HIDAPI can). An X-input/Xbox pad is the reliable GLFW target, or use the SDL backend.

Honest caveat

Live button/axis input wasn't end-to-end confirmed — the only controller paired to this machine is the Pro Controller, which GLFW doesn't map (above), and on macOS reading input also needs Input Monitoring permission for the host binary (run from a real Terminal, not a sandboxed shell). The mapping + edge logic is build-verified and matches the canonical numbering used by the other backends; confirming with an Xbox pad on a permitted Terminal is the remaining runtime check.

[cursor]

PR Summary

Medium Risk
Changes per-frame input semantics on desktop bgfx only; behavior depends on GLFW/SDL mappings and can differ from joystickPresent for unsupported controllers.

Overview
Desktop bgfx games can read gamepad input again. The GLFW path no longer returns stub false/0 for button and axis queries; it pulls mapped gamepad state via glfw.getGamepadState and maps the engine’s canonical raylib-style buttons [0,17] and axes [0,5] onto GLFW’s standard layout.

Each frame, newFrame calls snapshotGamepads after pollEvents so isGamepadButtonPressed uses rising-edge state (same pattern as keyboard/mouse). Face, dpad, bumpers, and thumbs go through canonToGlfwButton; digital LEFT/RIGHT_TRIGGER_2 (10/12) come from analog trigger axes above a 0.0 threshold. isGamepadAvailable is unchanged (still joystickPresent); unmapped pads stay “present” but read as idle. Android agp behavior is untouched.

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

[gemini-code-assist]

Code Review

This pull request implements desktop gamepad support using GLFW in the bgfx backend. The review feedback identifies two critical compilation issues: first, snapshotGamepads() will fail to compile on Android targets because glfw is an empty struct, which requires a comptime guard; second, referencing glfw.Gamepad.Axis.count will cause a compilation error on desktop platforms because standard zglfw enums do not expose a count field, and the length of state.axes should be used instead.

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]

On Android targets, glfw is defined as an empty struct (struct {}), which does not contain getGamepadState. Since snapshotGamepads() is referenced in newFrame(), the compiler will perform semantic analysis on its body and fail to compile on Android.

Adding a comptime check at the beginning of snapshotGamepads() ensures that the compiler discards the rest of the function body during semantic analysis on Android, preventing compilation errors.

fn snapshotGamepads() void {
    if (comptime is_android) return;
    var g: u32 = 0;

[gemini-code-assist]

Using glfw.Gamepad.Axis.count will cause a compilation error on desktop platforms because standard zglfw enums do not expose a count field. Instead, you should fetch the gamepad state first and guard the axis index using the actual length of the state.axes array (state.axes.len). This is more robust and idiomatic Zig.

    if (gamepad >= MAX_GAMEPADS) return 0;
    const state = glfw.getGamepadState(@enumFromInt(gamepad)) catch return 0;
    if (axis >= state.axes.len) return 0;
    return state.axes[axis];

[apotema]

Bot triage — both declined as false positives (each contradicted by a passing build):

• snapshotGamepads() breaks the Android build (Gemini, high) — declined. snapshotGamepads() is referenced only in newFrame's desktop path, after the comptime if (is_android) { ...; return; }. With is_android comptime-true, Zig does not analyze the post-return tail (this is the exact pattern the pre-existing glfw.pollEvents() on the line above already relies on). Proven: zig build test -Dtarget=aarch64-linux-android compiles clean with this code.
• glfw.Gamepad.Axis.count is not exposed (Gemini, high) — declined. This zglfw fork does define it: pub const Axis = enum(u8) { ...; pub const count = std.meta.fields(@This()).len; }. The desktop CI build (bgfx-build macOS + build-and-test) is green, which compiles this expression.

Both are the generic-knowledge-vs-this-fork mismatch; CI + the local Android compile-check are authoritative.