Teek API Documentation

Teek::SDL2::Gamepad Class

An SDL2 GameController for polling buttons, analog sticks, and triggers.

Gamepad wraps SDL2’s GameController API, which automatically maps physical controls to an Xbox-style layout. This is higher-level than the raw Joystick API and works with most modern controllers out of the box (Xbox, PlayStation, Switch Pro, etc.).

Inherits: Object

Class Methods ↑

Class methods (C-defined)

all

Open and return all connected gamepads.

Returns Array<Gamepad>

View source ▼ 
static VALUE
gamepad_s_all(VALUE klass)
{
    int n;
    VALUE ary;

    ensure_gc_init();
    ary = rb_ary_new();
    n = SDL_NumJoysticks();
    for (int i = 0; i < n; i++) {
        if (SDL_IsGameController(i)) {
            rb_ary_push(ary, gamepad_s_open(klass, INT2NUM(i)));
        }
    }
    return ary;
}
GitHub

attach_virtual

Create a virtual gamepad device for testing without hardware.

Returns Integer — device index (pass to .open)

@raise RuntimeError if a virtual device is already attached

View source ▼ 
static VALUE
gamepad_s_attach_virtual(VALUE klass)
{
    SDL_VirtualJoystickDesc desc;
    int idx;

    ensure_gc_init();

    if (virtual_device_index >= 0) {
        rb_raise(rb_eRuntimeError, "virtual gamepad already attached");
    }

    SDL_zero(desc);
    desc.version    = SDL_VIRTUAL_JOYSTICK_DESC_VERSION;
    desc.type       = SDL_JOYSTICK_TYPE_GAMECONTROLLER;
    desc.naxes      = SDL_CONTROLLER_AXIS_MAX;
    desc.nbuttons   = SDL_CONTROLLER_BUTTON_MAX;
    desc.nhats      = 0;
    desc.vendor_id  = 0;
    desc.product_id = 0;
    desc.name       = "Teek Virtual Gamepad";

    idx = SDL_JoystickAttachVirtualEx(&desc);
    if (idx < 0) {
        rb_raise(rb_eRuntimeError,
                 "failed to attach virtual gamepad: %s", SDL_GetError());
    }
    virtual_device_index = idx;
    return INT2NUM(idx);
}
GitHub

axes

List of valid axis symbols.

Returns Array<Symbol>

View source ▼ 
static VALUE
gamepad_s_axes(VALUE klass)
{
    VALUE ary = rb_ary_new_capa(6);
    rb_ary_push(ary, sym_left_x);
    rb_ary_push(ary, sym_left_y);
    rb_ary_push(ary, sym_right_x);
    rb_ary_push(ary, sym_right_y);
    rb_ary_push(ary, sym_trigger_left);
    rb_ary_push(ary, sym_trigger_right);
    return ary;
}
GitHub

buttons

List of valid button symbols.

Returns Array<Symbol>

View source ▼ 
static VALUE
gamepad_s_buttons(VALUE klass)
{
    VALUE ary = rb_ary_new_capa(15);
    rb_ary_push(ary, sym_a);
    rb_ary_push(ary, sym_b);
    rb_ary_push(ary, sym_x);
    rb_ary_push(ary, sym_y);
    rb_ary_push(ary, sym_back);
    rb_ary_push(ary, sym_guide);
    rb_ary_push(ary, sym_start);
    rb_ary_push(ary, sym_left_stick);
    rb_ary_push(ary, sym_right_stick);
    rb_ary_push(ary, sym_left_shoulder);
    rb_ary_push(ary, sym_right_shoulder);
    rb_ary_push(ary, sym_dpad_up);
    rb_ary_push(ary, sym_dpad_down);
    rb_ary_push(ary, sym_dpad_left);
    rb_ary_push(ary, sym_dpad_right);
    return ary;
}
GitHub

count

Returns the number of connected gamepads recognized by SDL2.

Returns Integer

View source ▼ 
static VALUE
gamepad_s_count(VALUE klass)
{
    int n, count = 0;

    ensure_gc_init();
    n = SDL_NumJoysticks();
    for (int i = 0; i < n; i++) {
        if (SDL_IsGameController(i))
            count++;
    }
    return INT2NUM(count);
}
GitHub

detach_virtual

Remove the virtual gamepad created by .attach_virtual.

Returns nil

View source ▼ 
static VALUE
gamepad_s_detach_virtual(VALUE klass)
{
    if (virtual_device_index >= 0) {
        SDL_JoystickDetachVirtual(virtual_device_index);
        virtual_device_index = -1;
    }
    return Qnil;
}
GitHub

first

Open the first available gamepad.

Returns Gamepad, nil — nil if no gamepads are connected

View source ▼ 
static VALUE
gamepad_s_first(VALUE klass)
{
    int n;

    ensure_gc_init();
    n = SDL_NumJoysticks();
    for (int i = 0; i < n; i++) {
        if (SDL_IsGameController(i)) {
            return gamepad_s_open(klass, INT2NUM(i));
        }
    }
    return Qnil;
}
GitHub

init_subsystem

Initialize the SDL2 gamepad subsystem. Called automatically by other methods, but can be called early for hot-plug detection.

Returns nil

View source ▼ 
static VALUE
gamepad_s_init_subsystem(VALUE klass)
{
    ensure_gc_init();
    return Qnil;
}
GitHub

on_added({|device_index| ... })

Register a callback for when a new gamepad is connected.

Returns nil

@yieldparam device_index Integer device index (pass to .open)

View source ▼ 
static VALUE
gamepad_s_on_added(VALUE klass)
{
    rb_need_block();
    cb_on_added = rb_block_proc();
    return Qnil;
}
GitHub

on_axis({|instance_id, axis, value| ... })

Register a callback for axis motion events.

Returns nil

@yieldparam instance_id Integer SDL joystick instance ID

@yieldparam axis Symbol axis name (e.g. :left_x, :trigger_left)

@yieldparam value Integer axis value (-32768..32767 for sticks, 0..32767 for triggers)

View source ▼ 
static VALUE
gamepad_s_on_axis(VALUE klass)
{
    rb_need_block();
    cb_on_axis = rb_block_proc();
    return Qnil;
}
GitHub

on_button({|instance_id, button, pressed| ... })

Register a callback for button press/release events.

Returns nil

@yieldparam instance_id Integer SDL joystick instance ID

@yieldparam button Symbol button name (e.g. :a, :dpad_up)

@yieldparam pressed Boolean true if pressed, false if released

View source ▼ 
static VALUE
gamepad_s_on_button(VALUE klass)
{
    rb_need_block();
    cb_on_button = rb_block_proc();
    return Qnil;
}
GitHub

on_removed({|instance_id| ... })

Register a callback for when a gamepad is disconnected.

Returns nil

@yieldparam instance_id Integer SDL joystick instance ID

View source ▼ 
static VALUE
gamepad_s_on_removed(VALUE klass)
{
    rb_need_block();
    cb_on_removed = rb_block_proc();
    return Qnil;
}
GitHub

open(index)

Open the gamepad at the given device index.

Parameters
  • index Integer — device index (0-based)

Returns Gamepad

@raise ArgumentError if index is negative

@raise RuntimeError if index is out of range or device cannot be opened

View source ▼ 
static VALUE
gamepad_s_open(VALUE klass, VALUE idx_val)
{
    int idx;
    SDL_GameController *ctrl;
    SDL_Joystick *joy;
    struct sdl2_gamepad *gp;
    VALUE obj;

    ensure_gc_init();
    idx = NUM2INT(idx_val);

    if (idx < 0) {
        rb_raise(rb_eArgError, "gamepad index must be non-negative, got %d", idx);
    }

    if (idx >= SDL_NumJoysticks()) {
        rb_raise(rb_eRuntimeError,
                 "gamepad index %d out of range (only %d joystick(s) connected)",
                 idx, SDL_NumJoysticks());
    }

    if (!SDL_IsGameController(idx)) {
        rb_raise(rb_eRuntimeError,
                 "device at index %d is not a game controller", idx);
    }

    ctrl = SDL_GameControllerOpen(idx);
    if (!ctrl) {
        rb_raise(rb_eRuntimeError,
                 "failed to open gamepad at index %d: %s",
                 idx, SDL_GetError());
    }

    obj = gamepad_alloc(klass);
    TypedData_Get_Struct(obj, struct sdl2_gamepad, &gamepad_type, gp);
    gp->controller = ctrl;

    joy = SDL_GameControllerGetJoystick(ctrl);
    gp->instance_id = SDL_JoystickInstanceID(joy);

    return obj;
}
GitHub

poll_events

Pump SDL events and dispatch gamepad events to registered callbacks. Call this periodically (e.g. every 16–50ms) for responsive input.

Note: on macOS, SDL_PollEvent pumps the Cocoa run loop, which can steal events from other UI toolkits (e.g. Tk). Use .update_state instead when you only need fresh controller state.

Returns Integer — number of events processed

View source ▼ 
static VALUE
gamepad_s_poll_events(VALUE klass)
{
    SDL_Event ev;
    int count = 0;

    if (!gc_subsystem_initialized) return INT2NUM(0);

    while (SDL_PollEvent(&ev)) {
        switch (ev.type) {
        case SDL_CONTROLLERBUTTONDOWN:
        case SDL_CONTROLLERBUTTONUP:
            if (cb_on_button != Qnil) {
                VALUE btn = button_to_sym((SDL_GameControllerButton)ev.cbutton.button);
                if (btn != Qnil) {
                    VALUE pressed = (ev.type == SDL_CONTROLLERBUTTONDOWN) ? Qtrue : Qfalse;
                    VALUE args[3];
                    args[0] = INT2NUM(ev.cbutton.which);
                    args[1] = btn;
                    args[2] = pressed;
                    rb_proc_call_with_block(cb_on_button, 3, args, Qnil);
                }
            }
            count++;
            break;

        case SDL_CONTROLLERAXISMOTION:
            if (cb_on_axis != Qnil) {
                VALUE ax = axis_to_sym((SDL_GameControllerAxis)ev.caxis.axis);
                if (ax != Qnil) {
                    VALUE args[3];
                    args[0] = INT2NUM(ev.caxis.which);
                    args[1] = ax;
                    args[2] = INT2NUM(ev.caxis.value);
                    rb_proc_call_with_block(cb_on_axis, 3, args, Qnil);
                }
            }
            count++;
            break;

        case SDL_CONTROLLERDEVICEADDED:
            if (cb_on_added != Qnil) {
                VALUE args[1];
                args[0] = INT2NUM(ev.cdevice.which);
                rb_proc_call_with_block(cb_on_added, 1, args, Qnil);
            }
            count++;
            break;

        case SDL_CONTROLLERDEVICEREMOVED:
            if (cb_on_removed != Qnil) {
                VALUE args[1];
                args[0] = INT2NUM(ev.cdevice.which);
                rb_proc_call_with_block(cb_on_removed, 1, args, Qnil);
            }
            count++;
            break;

        default:
            break;
        }
    }
    return INT2NUM(count);
}
GitHub

shutdown_subsystem

Shut down the gamepad subsystem. Existing Gamepad objects become invalid.

Returns nil

View source ▼ 
static VALUE
gamepad_s_shutdown_subsystem(VALUE klass)
{
    if (gc_subsystem_initialized) {
        SDL_QuitSubSystem(SDL_INIT_GAMECONTROLLER);
        gc_subsystem_initialized = 0;
    }
    return Qnil;
}
GitHub

update_state

Refresh controller state without pumping the platform event loop. Calls SDL_GameControllerUpdate → SDL_JoystickUpdate directly, bypassing SDL_PumpEvents and the Cocoa run loop on macOS.

After calling this, #button? and #axis return updated values. Event callbacks (on_button, on_axis, etc.) will NOT fire — use .poll_events when you need callbacks.

Returns nil

View source ▼ 
static VALUE
gamepad_s_update_state(VALUE klass)
{
    if (gc_subsystem_initialized) {
        SDL_GameControllerUpdate();
    }
    return Qnil;
}
GitHub

virtual_device_index

Device index of the virtual gamepad.

Returns Integer, nil — nil if no virtual device is attached

View source ▼ 
static VALUE
gamepad_s_virtual_device_index(VALUE klass)
{
    if (virtual_device_index < 0) return Qnil;
    return INT2NUM(virtual_device_index);
}
GitHub

apply_dead_zone(value, threshold DEAD_ZONE)

Apply a dead zone to a stick axis value. Returns 0 if the value is within the dead zone, otherwise returns the original value.

Parameters
  • value Integer — raw axis value (-32768..32767)
  • threshold Integer — dead zone threshold

Returns Integer

View source ▼ 
def self.apply_dead_zone(value, threshold = DEAD_ZONE)
  value.abs < threshold ? 0 : value
end
GitHub
Instance Methods ↑

Instance methods (C-defined)

attached?

Whether the controller is still physically connected.

Returns Boolean

View source ▼ 
static VALUE
gamepad_attached_p(VALUE self)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    return SDL_GameControllerGetAttached(gp->controller) ? Qtrue : Qfalse;
}
GitHub

axis(axis)

Current value of an analog axis.

Parameters
  • axis Symbol — one of :left_x, :left_y, :right_x, :right_y, :trigger_left, :trigger_right

Returns Integer — -32768..32767 for sticks, 0..32767 for triggers

View source ▼ 
static VALUE
gamepad_axis(VALUE self, VALUE axis_sym)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    SDL_GameControllerAxis ax;
    Sint16 val;

    Check_Type(axis_sym, T_SYMBOL);
    ax = sym_to_axis(axis_sym);
    if (ax == SDL_CONTROLLER_AXIS_INVALID) {
        rb_raise(rb_eArgError, "unknown axis: %"PRIsVALUE, axis_sym);
    }

    val = SDL_GameControllerGetAxis(gp->controller, ax);
    return INT2NUM(val);
}
GitHub

button?(button)

Whether the given button is currently pressed.

Parameters
  • button Symbol — one of :a, :b, :x, :y, :back, :guide, :start, :left_stick, :right_stick, :left_shoulder, :right_shoulder, :dpad_up, :dpad_down, :dpad_left, :dpad_right

Returns Boolean

View source ▼ 
static VALUE
gamepad_button_p(VALUE self, VALUE btn_sym)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    SDL_GameControllerButton btn;

    Check_Type(btn_sym, T_SYMBOL);
    btn = sym_to_button(btn_sym);
    if (btn == SDL_CONTROLLER_BUTTON_INVALID) {
        rb_raise(rb_eArgError, "unknown button: %"PRIsVALUE, btn_sym);
    }

    return SDL_GameControllerGetButton(gp->controller, btn) ? Qtrue : Qfalse;
}
GitHub

close

Close the controller. Further method calls will raise.

Returns nil

View source ▼ 
static VALUE
gamepad_close(VALUE self)
{
    struct sdl2_gamepad *gp;
    TypedData_Get_Struct(self, struct sdl2_gamepad, &gamepad_type, gp);

    if (!gp->destroyed && gp->controller) {
        SDL_GameControllerClose(gp->controller);
        gp->controller = NULL;
        gp->destroyed = 1;
    }
    return Qnil;
}
GitHub

closed?

Whether the controller has been closed.

Returns Boolean

View source ▼ 
static VALUE
gamepad_closed_p(VALUE self)
{
    struct sdl2_gamepad *gp;
    TypedData_Get_Struct(self, struct sdl2_gamepad, &gamepad_type, gp);
    return (gp->destroyed || gp->controller == NULL) ? Qtrue : Qfalse;
}
GitHub

instance_id

SDL joystick instance ID. Useful for matching with event callbacks.

Returns Integer

View source ▼ 
static VALUE
gamepad_instance_id(VALUE self)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    return INT2NUM(gp->instance_id);
}
GitHub

name

Human-readable name of the controller (e.g. “Xbox One Controller”).

Returns String

View source ▼ 
static VALUE
gamepad_name(VALUE self)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    const char *name = SDL_GameControllerName(gp->controller);
    if (!name) return rb_str_new_cstr("Unknown");
    return rb_str_new_cstr(name);
}
GitHub

rumble(low_freq, high_freq, duration_ms)

Trigger haptic feedback (rumble).

Parameters
  • low_freq Integer — low-frequency motor intensity (0–65535)
  • high_freq Integer — high-frequency motor intensity (0–65535)
  • duration_ms Integer — duration in milliseconds

Returns Boolean — true on success

View source ▼ 
static VALUE
gamepad_rumble(VALUE self, VALUE low, VALUE high, VALUE duration)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    Uint16 lo = (Uint16)NUM2UINT(low);
    Uint16 hi = (Uint16)NUM2UINT(high);
    Uint32 ms = (Uint32)NUM2UINT(duration);

    int rc = SDL_GameControllerRumble(gp->controller, lo, hi, ms);
    return rc == 0 ? Qtrue : Qfalse;
}
GitHub

set_virtual_axis(axis, value)

Set the value of an axis on a virtual gamepad.

Parameters
  • axis Symbol — axis name
  • value Integer — axis value (-32768..32767 for sticks, 0..32767 for triggers)

Returns nil

View source ▼ 
static VALUE
gamepad_set_virtual_axis(VALUE self, VALUE axis_sym, VALUE val)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    SDL_Joystick *joy;
    SDL_GameControllerAxis ax;
    Sint16 v;

    Check_Type(axis_sym, T_SYMBOL);
    ax = sym_to_axis(axis_sym);
    if (ax == SDL_CONTROLLER_AXIS_INVALID) {
        rb_raise(rb_eArgError, "unknown axis: %"PRIsVALUE, axis_sym);
    }

    joy = SDL_GameControllerGetJoystick(gp->controller);
    v = (Sint16)NUM2INT(val);

    if (SDL_JoystickSetVirtualAxis(joy, ax, v) < 0) {
        rb_raise(rb_eRuntimeError, "failed to set virtual axis: %s",
                 SDL_GetError());
    }
    return Qnil;
}
GitHub

set_virtual_button(button, pressed)

Set the state of a button on a virtual gamepad.

Parameters
  • button Symbol — button name
  • pressed Boolean — true for pressed, false for released

Returns nil

View source ▼ 
static VALUE
gamepad_set_virtual_button(VALUE self, VALUE btn_sym, VALUE pressed)
{
    struct sdl2_gamepad *gp = get_gamepad(self);
    SDL_Joystick *joy;
    SDL_GameControllerButton btn;
    Uint8 state;

    Check_Type(btn_sym, T_SYMBOL);
    btn = sym_to_button(btn_sym);
    if (btn == SDL_CONTROLLER_BUTTON_INVALID) {
        rb_raise(rb_eArgError, "unknown button: %"PRIsVALUE, btn_sym);
    }

    joy = SDL_GameControllerGetJoystick(gp->controller);
    state = RTEST(pressed) ? SDL_PRESSED : SDL_RELEASED;

    if (SDL_JoystickSetVirtualButton(joy, btn, state) < 0) {
        rb_raise(rb_eRuntimeError, "failed to set virtual button: %s",
                 SDL_GetError());
    }
    return Qnil;
}
GitHub