17 Gamepads

9.0.0.11

Racket

17 Gamepads🔗ℹ

This section covers gamepad (game controller) support with standardized button and axis names. For lower-level joystick access, see Joysticks.

17.1 Detection🔗ℹ

procedure
(has-gamepad?) → boolean?

Returns #t if any gamepads are connected.

procedure
(get-gamepads) → (listof exact-nonnegative-integer?)

Returns a list of connected gamepad instance IDs.

(for ([id (get-gamepads)])
(printf "Gamepad: ~a~n" (get-gamepad-name-for-id id)))

procedure
(get-gamepad-count) → exact-nonnegative-integer?

Returns the number of connected gamepads.

procedure
(is-gamepad? instance-id) → boolean?
instance-id : exact-nonnegative-integer?

Returns #t if the given joystick instance ID is a gamepad.

17.2 Opening and Closing🔗ℹ

procedure
(open-gamepad instance-id) → gamepad?
instance-id : exact-nonnegative-integer?

Opens a gamepad by its instance ID.

The gamepad is registered with the current custodian for automatic cleanup.

(define ids (get-gamepads))
(when (pair? ids)
(define gp (open-gamepad (car ids)))
(printf "Opened: ~a~n" (gamepad-name gp)))

procedure
(gamepad? v) → boolean?
v : any/c

Returns #t if v is a gamepad.

procedure
(gamepad-connected? gp) → boolean?
gp : gamepad?

Returns #t if the gamepad is still connected.

procedure
(gamepad-destroy! gp) → void?
gp : gamepad?

Closes a gamepad.

Note: Gamepads are automatically closed when their custodian shuts down.

17.3 Gamepad Information🔗ℹ

procedure
(gamepad-name gp) → (or/c string? #f)
gp : gamepad?

Returns the gamepad name.

procedure
(gamepad-path gp) → (or/c string? #f)
gp : gamepad?

Returns the device path.

procedure
(gamepad-id gp) → exact-nonnegative-integer?
gp : gamepad?

Returns the instance ID.

procedure
(gamepad-type gp) → symbol?
gp : gamepad?

Returns the gamepad type as a symbol.

Values: 'unknown, 'standard, 'xbox360, 'xboxone, 'ps3, 'ps4, 'ps5, 'switch-pro, 'switch-joycon-left, 'switch-joycon-right, 'switch-joycon-pair.

procedure
(gamepad-real-type gp) → symbol?
gp : gamepad?

Returns the actual hardware type (may differ from mapped type).

procedure
(gamepad-vendor gp) → exact-nonnegative-integer?
gp : gamepad?

Returns the USB vendor ID.

procedure
(gamepad-product gp) → exact-nonnegative-integer?
gp : gamepad?

Returns the USB product ID.

procedure
(gamepad-serial gp) → (or/c string? #f)
gp : gamepad?

Returns the serial number.

17.3.1 Info by ID (before opening)🔗ℹ

procedure
(get-gamepad-name-for-id instance-id) → (or/c string? #f)
instance-id : exact-nonnegative-integer?

Returns the name of a gamepad before opening it.

procedure
(get-gamepad-type-for-id instance-id) → symbol?
instance-id : exact-nonnegative-integer?

Returns the type of a gamepad before opening it.

17.4 Buttons🔗ℹ

procedure
(gamepad-button gp button) → boolean?
gp : gamepad?
button : (or/c symbol? exact-nonnegative-integer?)

Returns #t if the button is pressed.

Button symbols include:

'south (A on Xbox, Cross on PlayStation)
'east (B on Xbox, Circle on PlayStation)
'west (X on Xbox, Square on PlayStation)
'north (Y on Xbox, Triangle on PlayStation)
'back, 'start, 'guide
'left-stick, 'right-stick (L3/R3)
'left-shoulder, 'right-shoulder (LB/RB or L1/R1)
'dpad-up, 'dpad-down, 'dpad-left, 'dpad-right

Platform-specific aliases are also supported:

Xbox: 'a, 'b, 'x, 'y
PlayStation: 'cross, 'circle, 'square, 'triangle
Shoulder: 'lb, 'rb, 'l1, 'r1

(when (gamepad-button gp 'south)
(player-jump!))

procedure
(gamepad-has-button? gp button) → boolean?
gp : gamepad?
button : (or/c symbol? exact-nonnegative-integer?)

Returns #t if the gamepad has the specified button.

17.5 Axes🔗ℹ

procedure
(gamepad-axis gp axis) → exact-integer?
gp : gamepad?
axis : (or/c symbol? exact-nonnegative-integer?)

Returns the current axis value.

For sticks: -32768 to 32767 (centered at 0). For triggers: 0 to 32767.

Axis symbols:

'left-x, 'left-y — Left stick
'right-x, 'right-y — Right stick
'left-trigger, 'right-trigger — Triggers (LT/RT or L2/R2)

(define lx (gamepad-axis gp 'left-x))
(define ly (gamepad-axis gp 'left-y))
(move-player! (/ lx 32768.0) (/ ly 32768.0))

procedure
(gamepad-has-axis? gp axis) → boolean?
gp : gamepad?
axis : (or/c symbol? exact-nonnegative-integer?)

Returns #t if the gamepad has the specified axis.

17.6 Button Labels🔗ℹ

For displaying button prompts that match the controller type.

procedure
(gamepad-button-label gp button) → symbol?
gp : gamepad?
button : (or/c symbol? exact-nonnegative-integer?)

Returns the label for a button on the connected gamepad.

Returns symbols like 'a, 'b, 'x, 'y for Xbox, or 'cross, 'circle, 'square, 'triangle for PlayStation.

procedure
(gamepad-button-label-for-type type button) → symbol?
type : symbol?
button : (or/c symbol? exact-nonnegative-integer?)

Returns the label for a button on a specific controller type.

17.7 Player Index🔗ℹ

procedure
(gamepad-player-index gp) → exact-integer?
gp : gamepad?

Returns the player index (-1 if not set).

procedure
(set-gamepad-player-index! gp index) → void?
gp : gamepad?
index : exact-integer?

Sets the player index.

17.8 Rumble🔗ℹ

procedure
(gamepad-rumble! gp low high [duration-ms]) → boolean?
  gp : gamepad?
  low : exact-nonnegative-integer?
  high : exact-nonnegative-integer?
  duration-ms : exact-nonnegative-integer? = 0

Starts a rumble effect.

low and high are motor intensities (0-65535). duration-ms is the duration in milliseconds (0 = infinite).

;; Strong rumble for 200ms
(gamepad-rumble! gp 65535 65535 200)

procedure
(gamepad-rumble-triggers! gp
left
right
[ duration-ms]) → boolean?
  gp : gamepad?
  left : exact-nonnegative-integer?
  right : exact-nonnegative-integer?
  duration-ms : exact-nonnegative-integer? = 0

Starts a trigger rumble effect (Xbox-style controllers).

17.9 LED🔗ℹ

procedure
(gamepad-set-led! gp r g b) → boolean?
  gp : gamepad?
  r : byte?
  g : byte?
  b : byte?

Sets the LED color (if supported).

17.10 Power🔗ℹ

procedure
(gamepad-power-info gp) →
symbol? exact-integer?
gp : gamepad?

Returns the power state and battery percentage.

Power states: 'unknown, 'on-battery, 'no-battery, 'charging, 'charged, 'error.

Percentage is 0-100, or -1 if unknown.

procedure
(gamepad-connection-state gp) → symbol?
gp : gamepad?

Returns the connection type.

Values: 'unknown, 'wired, 'wireless, 'invalid.

17.11 Type Conversions🔗ℹ

procedure
(symbol->button sym) → exact-nonnegative-integer?
sym : symbol?

Converts a button symbol to its SDL constant.

procedure
(button->symbol btn) → symbol?
btn : exact-nonnegative-integer?

Converts an SDL button constant to a symbol.

procedure
(symbol->axis sym) → exact-nonnegative-integer?
sym : symbol?

Converts an axis symbol to its SDL constant.

procedure
(axis->symbol axis) → symbol?
axis : exact-nonnegative-integer?

Converts an SDL axis constant to a symbol.

procedure
(gamepad-type->symbol type) → symbol?
type : exact-nonnegative-integer?

Converts an SDL gamepad type to a symbol.

1	Overview
2	Quick Start
3	Resource Management
4	Initialization
5	Windows and Renderers
6	Timer Functions
7	Configuration Hints
8	Properties
9	Drawing
10	Textures
11	Images and Surfaces
12	True Type Fonts
13	Rectangle Collision Detection
14	Events
15	Keyboard Functions
16	Mouse Functions
17	Gamepads
18	Joysticks
19	Audio
20	Camera
21	Display Information
22	Clipboard
23	Dialogs
24	System Tray
25	Open GL
26	Vulkan
27	GPU API

17.1	Detection
17.2	Opening and Closing
17.3	Gamepad Information
17.4	Buttons
17.5	Axes
17.6	Button Labels
17.7	Player Index
17.8	Rumble
17.9	LED
17.10	Power
17.11	Type Conversions