0
# Joystick and Game Controller Input
1

2
Complete joystick and game controller support with both raw joystick access and standardized game controller mapping. PySDL2 provides comprehensive input handling for gaming devices through SDL2's robust input subsystem.
3

4
## Capabilities
5

6
### Joystick Management
7

8
Core joystick functions for device enumeration and management.
9

10
```python { .api }
11
def SDL_NumJoysticks() -> int:
12
    """
13
    Get the number of joysticks attached to the system.
14
    
15
    Returns:
16
    Number of joysticks available
17
    """
18

19
def SDL_JoystickNameForIndex(device_index: int) -> bytes:
20
    """Get the implementation-dependent name of a joystick."""
21

22
def SDL_JoystickOpen(device_index: int) -> SDL_Joystick:
23
    """
24
    Open a joystick for use.
25
    
26
    Parameters:
27
    - device_index: index of the joystick to open
28
    
29
    Returns:
30
    SDL_Joystick object or None on failure
31
    """
32

33
def SDL_JoystickClose(joystick: SDL_Joystick) -> None:
34
    """Close a joystick previously opened with SDL_JoystickOpen."""
35

36
def SDL_JoystickGetDeviceGUID(device_index: int) -> SDL_JoystickGUID:
37
    """Get the implementation-dependent GUID for the joystick at a given device index."""
38

39
def SDL_JoystickInstanceID(joystick: SDL_Joystick) -> int:
40
    """Get the instance ID of an opened joystick."""
41
```
42

43
### Joystick Input Reading
44

45
Functions for reading joystick axes, buttons, and hat switches.
46

47
```python { .api }
48
def SDL_JoystickNumAxes(joystick: SDL_Joystick) -> int:
49
    """Get the number of general axis controls on a joystick."""
50

51
def SDL_JoystickNumButtons(joystick: SDL_Joystick) -> int:
52
    """Get the number of buttons on a joystick."""
53

54
def SDL_JoystickNumHats(joystick: SDL_Joystick) -> int:
55
    """Get the number of POV hats on a joystick."""
56

57
def SDL_JoystickGetAxis(joystick: SDL_Joystick, axis: int) -> int:
58
    """
59
    Get the current state of an axis on a joystick.
60
    
61
    Parameters:
62
    - joystick: joystick to query
63
    - axis: axis index (0-based)
64
    
65
    Returns:
66
    Axis value ranging from -32768 to 32767
67
    """
68

69
def SDL_JoystickGetButton(joystick: SDL_Joystick, button: int) -> int:
70
    """
71
    Get the current state of a button on a joystick.
72
    
73
    Parameters:
74
    - joystick: joystick to query  
75
    - button: button index (0-based)
76
    
77
    Returns:
78
    1 if button is pressed, 0 if not pressed
79
    """
80

81
def SDL_JoystickGetHat(joystick: SDL_Joystick, hat: int) -> int:
82
    """Get the current state of a POV hat on a joystick."""
83
```
84

85
### Game Controller Management
86

87
High-level game controller API with standardized button and axis mapping.
88

89
```python { .api }
90
def SDL_IsGameController(joystick_index: int) -> bool:
91
    """Check if the given joystick is supported by the game controller interface."""
92

93
def SDL_GameControllerOpen(joystick_index: int) -> SDL_GameController:
94
    """
95
    Open a game controller for use.
96
    
97
    Parameters:
98
    - joystick_index: index of the device to open
99
    
100
    Returns:
101
    SDL_GameController object or None on failure
102
    """
103

104
def SDL_GameControllerClose(gamecontroller: SDL_GameController) -> None:
105
    """Close a game controller previously opened with SDL_GameControllerOpen."""
106

107
def SDL_GameControllerName(gamecontroller: SDL_GameController) -> bytes:
108
    """Get the implementation-dependent name for an opened game controller."""
109

110
def SDL_GameControllerGetJoystick(gamecontroller: SDL_GameController) -> SDL_Joystick:
111
    """Get the underlying joystick object used by a game controller."""
112
```
113

114
### Game Controller Input Reading
115

116
Standardized input reading for game controllers with consistent button and axis naming.
117

118
```python { .api }
119
def SDL_GameControllerGetAxis(gamecontroller: SDL_GameController, axis: int) -> int:
120
    """
121
    Get the current state of an axis on a game controller.
122
    
123
    Parameters:
124
    - gamecontroller: controller to query
125
    - axis: axis constant (SDL_CONTROLLER_AXIS_*)
126
    
127
    Returns:
128
    Axis value ranging from -32768 to 32767
129
    """
130

131
def SDL_GameControllerGetButton(gamecontroller: SDL_GameController, button: int) -> int:
132
    """
133
    Get the current state of a button on a game controller.
134
    
135
    Parameters:
136
    - gamecontroller: controller to query
137
    - button: button constant (SDL_CONTROLLER_BUTTON_*)
138
    
139
    Returns:
140
    1 if button is pressed, 0 if not pressed
141
    """
142
```
143

144
### Constants and Enums
145

146
```python { .api }
147
# Joystick hat positions
148
SDL_HAT_CENTERED = 0x00
149
SDL_HAT_UP = 0x01
150
SDL_HAT_RIGHT = 0x02
151
SDL_HAT_DOWN = 0x04
152
SDL_HAT_LEFT = 0x08
153
SDL_HAT_RIGHTUP = 0x03
154
SDL_HAT_RIGHTDOWN = 0x06
155
SDL_HAT_LEFTUP = 0x09
156
SDL_HAT_LEFTDOWN = 0x0c
157

158
# Game controller axes
159
SDL_CONTROLLER_AXIS_LEFTX = 0
160
SDL_CONTROLLER_AXIS_LEFTY = 1
161
SDL_CONTROLLER_AXIS_RIGHTX = 2
162
SDL_CONTROLLER_AXIS_RIGHTY = 3
163
SDL_CONTROLLER_AXIS_TRIGGERLEFT = 4
164
SDL_CONTROLLER_AXIS_TRIGGERRIGHT = 5
165

166
# Game controller buttons  
167
SDL_CONTROLLER_BUTTON_A = 0
168
SDL_CONTROLLER_BUTTON_B = 1
169
SDL_CONTROLLER_BUTTON_X = 2
170
SDL_CONTROLLER_BUTTON_Y = 3
171
SDL_CONTROLLER_BUTTON_BACK = 4
172
SDL_CONTROLLER_BUTTON_GUIDE = 5
173
SDL_CONTROLLER_BUTTON_START = 6
174
SDL_CONTROLLER_BUTTON_LEFTSTICK = 7
175
SDL_CONTROLLER_BUTTON_RIGHTSTICK = 8
176
SDL_CONTROLLER_BUTTON_LEFTSHOULDER = 9
177
SDL_CONTROLLER_BUTTON_RIGHTSHOULDER = 10
178
SDL_CONTROLLER_BUTTON_DPAD_UP = 11
179
SDL_CONTROLLER_BUTTON_DPAD_DOWN = 12
180
SDL_CONTROLLER_BUTTON_DPAD_LEFT = 13
181
SDL_CONTROLLER_BUTTON_DPAD_RIGHT = 14
182
```
183

184
## Usage Examples
185

186
### Basic Joystick Usage
187

188
```python
189
import sdl2
190

191
# Initialize SDL
192
sdl2.SDL_Init(sdl2.SDL_INIT_JOYSTICK)
193

194
# Check for joysticks
195
num_joysticks = sdl2.SDL_NumJoysticks()
196
if num_joysticks > 0:
197
    # Open first joystick
198
    joystick = sdl2.SDL_JoystickOpen(0)
199
    
200
    # Get joystick info
201
    name = sdl2.SDL_JoystickName(joystick)
202
    num_axes = sdl2.SDL_JoystickNumAxes(joystick)
203
    num_buttons = sdl2.SDL_JoystickNumButtons(joystick)
204
    
205
    print(f"Opened joystick: {name}")
206
    print(f"Axes: {num_axes}, Buttons: {num_buttons}")
207
    
208
    # Read input in game loop
209
    while True:
210
        # Update joystick state
211
        sdl2.SDL_JoystickUpdate()
212
        
213
        # Read first axis and button
214
        axis_value = sdl2.SDL_JoystickGetAxis(joystick, 0)
215
        button_pressed = sdl2.SDL_JoystickGetButton(joystick, 0)
216
        
217
        # Close joystick when done
218
        sdl2.SDL_JoystickClose(joystick)
219
```
220

221
### Game Controller Usage
222

223
```python
224
import sdl2
225

226
# Initialize SDL with game controller support
227
sdl2.SDL_Init(sdl2.SDL_INIT_GAMECONTROLLER)
228

229
# Check for game controllers
230
for i in range(sdl2.SDL_NumJoysticks()):
231
    if sdl2.SDL_IsGameController(i):
232
        # Open game controller
233
        controller = sdl2.SDL_GameControllerOpen(i)
234
        
235
        # Read standardized input
236
        left_stick_x = sdl2.SDL_GameControllerGetAxis(
237
            controller, sdl2.SDL_CONTROLLER_AXIS_LEFTX
238
        )
239
        a_button = sdl2.SDL_GameControllerGetButton(
240
            controller, sdl2.SDL_CONTROLLER_BUTTON_A
241
        )
242
        
243
        # Close controller when done
244
        sdl2.SDL_GameControllerClose(controller)
245
        break
246
```
247

248
## Types
249

250
```python { .api }
251
class SDL_Joystick:
252
    """Opaque joystick structure for raw joystick access."""
253

254
class SDL_GameController:
255
    """Opaque game controller structure for standardized controller input."""
256

257
class SDL_JoystickGUID:
258
    """Structure representing a joystick GUID."""
259
    data: bytes
260
```