Gamepad

class genesis_forge.gamepads.Gamepad(debug: bool = False)

Bases: object

Wrapper around SDL2 ControllerEventLoop that provides a polling-based interface.

This maintains axis and button state that can be queried at any time, similar to the old HID-based Gamepad API.

Example:

>>> gamepad = Gamepad()
>>> gamepad.axis(0)  # Get left stick X axis
0.0
>>> gamepad.buttons()  # Get list of pressed buttons
['a', 'b']

Initialize the SDL2 gamepad wrapper.

Parameters:

debug – If True, print debug information

axis(index: int) → float

Get the value of an axis.

Parameters:

index – The axis index (0-5)

Returns:

The axis value in range [-1.0, 1.0] for sticks, [0.0, 1.0] for triggers

buttons() → list[str]

Get the list of currently pressed buttons.

Returns:

List of button names (lowercase, e.g., ‘a’, ‘b’, ‘x’, ‘y’)

stop() → None

Stop reading gamepad input.

property dpad: str | None

Get the current D-pad direction (e.g., ‘up’, ‘down’, ‘left’, ‘right’).

Low-level SDL2 API

For advanced users who want direct access to the SDL2 event loop:

class genesis_forge.gamepads.ControllerEventLoop(handle_key: Callable[[Key], None], alive: threading.Event | None = None, timeout: int = 2000)

Bases: object

Minimal SDL2 controller event loop for genesis-forge.

This class runs in a background thread and processes SDL2 controller events, converting them to Key objects and passing them to a callback function.

Parameters:

• handle_key – Callback function that receives Key objects for each controller event

• alive – Optional threading.Event to control the event loop. When cleared, the loop exits.

• timeout – Milliseconds to wait for events before checking the alive flag (default: 2000ms)

Example:

def on_key(key: Key):
    print(f"Key event: {key}")

loop = ControllerEventLoop(handle_key=on_key)
thread = threading.Thread(target=loop.run, daemon=True)
thread.start()

# Later, to stop:
loop.stop()

run() → None

stop() → None

class genesis_forge.gamepads.Key(keytype: str, index: int, name: str | None = None, value: float | None = None)

Bases: object

Gamepad input abstraction shared across backends.

AXIS = 'Axis'

BUTTON = 'Button'

HAT = 'Hat'

index: int

keytype: str

name: str | None = None

value: float | None = None

genesis_forge.gamepads.controller_key_from_event(event: sdl2.SDL_Event, deadzone: float = 0.05) → Key | None