- Pygame module to work with controllers.
— initialize the controller module — Uninitialize the controller module. — Returns True if the controller module is initialized. — Sets the current state of events related to controllers — Gets the current state of events related to controllers — Get the number of joysticks connected — Check if the given joystick is supported by the game controller interface — Get the name of the controller — Create a new Controller object.
This module offers control over common controller types like the dualshock 4 or the xbox 360 controllers: They have two analog sticks, two triggers, two shoulder buttons, a dpad, 4 buttons on the side, 2 (or 3) buttons in the middle.
Pygame uses xbox controllers naming conventions (like a, b, x, y for buttons) but they always refer to the same buttons. For example
CONTROLLER_BUTTON_Xis always the leftmost button of the 4 buttons on the right.
Controllers can generate the following events:
CONTROLLERAXISMOTION, CONTROLLERBUTTONDOWN, CONTROLLERBUTTONUP, CONTROLLERDEVICEREMAPPED, CONTROLLERDEVICEADDED, CONTROLLERDEVICEREMOVED
Additionally if pygame is built with SDL 2.0.14 or higher the following events can also be generated (to get the version of sdl pygame is built with use
pygame.version.SDL()tupled integers of the SDL library version):
CONTROLLERTOUCHPADDOWN, CONTROLLERTOUCHPADMOTION, CONTROLLERTOUCHPADUP
These events can be enabled/disabled by
pygame._sdl2.controller.set_eventstate()Sets the current state of events related to controllers Note that controllers can generate joystick events as well. This function only toggles events related to controllers.
pygame.joystickPygame module for interacting with joysticks, gamepads, and trackballs. for a more versatile but more advanced api.
New in pygame 2: This module requires SDL2.
- initialize the controller moduleinit() -> None
Initialize the controller module.
- Uninitialize the controller module.quit() -> None
Uninitialize the controller module.
- Returns True if the controller module is initialized.get_init() -> bool
- Sets the current state of events related to controllersset_eventstate(state) -> None
Enable or disable events connected to controllers.
Controllers can still generate joystick events, which will not be toggled by this function.
Changed in pygame 2.0.2:: Changed return type from int to None
- Gets the current state of events related to controllersget_eventstate() -> bool
Returns the current state of events related to controllers, True meaning events will be posted.
New in pygame 2.0.2.
- Get the number of joysticks connectedget_count() -> int
Get the number of joysticks connected.
- Check if the given joystick is supported by the game controller interfaceis_controller(index) -> bool
Returns True if the index given can be used to create a controller object.
- Get the name of the controllername_forindex(index) -> name or None
Returns the name of controller, or None if there's no name or the index is invalid.
- Create a new Controller object.Controller(index) -> Controller
Create a new Controller object. Index should be integer between 0 and
pygame._sdl2.controller.get_count(). Controllers also can be created from a
pygame._sdl2.controller.from_joystick. Controllers are initialized on creation.
— uninitialize the Controller — check if the Controller is initialized — Create a Controller from a pygame.joystick.Joystick object — Check if the Controller has been opened and is currently connected. — Returns a pygame.joystick.Joystick() object — Get the current state of a joystick axis — Get the current state of a button — Get the mapping assigned to the controller — Assign a mapping to the controller — Start a rumbling effect — Stop any rumble effect playing
- uninitialize the Controllerquit() -> None
Close a Controller object. After this the pygame event queue will no longer receive events from the device.
It is safe to call this more than once.
- check if the Controller is initializedget_init() -> bool
Returns True if the Controller object is currently initialised.
- static from_joystick()¶
- Create a Controller from a pygame.joystick.Joystick objectfrom_joystick(joystick) -> Controller
Create a Controller object from a
- Check if the Controller has been opened and is currently connected.attached() -> bool
Returns True if the Controller object is opened and connected.
- Returns a pygame.joystick.Joystick() objectas_joystick() -> Joystick object
Returns a pygame.joystick.Joystick() object created from this controller's index
- Get the current state of a joystick axisget_axis(axis) -> int
Get the current state of a trigger or joystick axis. The axis argument must be one of the following constants:
CONTROLLER_AXIS_LEFTX, CONTROLLER_AXIS_LEFTY, CONTROLLER_AXIS_RIGHTX, CONTROLLER_AXIS_RIGHTY, CONTROLLER_AXIS_TRIGGERLEFT, CONTROLLER_AXIS_TRIGGERRIGHT
Joysticks can return a value between -32768 and 32767. Triggers however can only return a value between 0 and 32768.
- Get the current state of a buttonget_button(button) -> bool
Get the current state of a button, True meaning it is pressed down. The button argument must be one of the following constants:
CONTROLLER_BUTTON_A, CONTROLLER_BUTTON_B, CONTROLLER_BUTTON_X, CONTROLLER_BUTTON_Y CONTROLLER_BUTTON_DPAD_UP, CONTROLLER_BUTTON_DPAD_DOWN, CONTROLLER_BUTTON_DPAD_LEFT, CONTROLLER_BUTTON_DPAD_RIGHT, CONTROLLER_BUTTON_LEFTSHOULDER, CONTROLLER_BUTTON_RIGHTSHOULDER, CONTROLLER_BUTTON_LEFTSTICK, CONTROLLER_BUTTON_RIGHTSTICK, CONTROLLER_BUTTON_BACK, CONTROLLER_BUTTON_GUIDE, CONTROLLER_BUTTON_START
- Get the mapping assigned to the controllerget_mapping() -> mapping
Returns a dict containing the mapping of the Controller. For more information see
Changed in pygame 2.0.2:: Return type changed from
- Assign a mapping to the controllerset_mapping(mapping) -> int
Rebind buttons, axes, triggers and dpads. The mapping should be a dict containing all buttons, hats and axes. The easiest way to get this is to use the dict returned by
Controller.get_mapping(). To edit this mapping assign a value to the original button. The value of the dictionary must be a button, hat or axis represented in the following way:
For a button use: bX where X is the index of the button.
For a hat use: hX.Y where X is the index and the Y is the direction (up: 1, right: 2, down: 3, left: 4).
For an axis use: aX where x is the index of the axis.
An example of mapping:
mapping = controller.get_mapping() # Get current mapping mapping["a"] = "b3" # Remap button a to y mapping["y"] = "b0" # Remap button y to a controller.set_mapping(mapping) # Set the mapping
The function will return 1 if a new mapping is added or 0 if an existing one is updated.
Changed in pygame 2.0.2:: Renamed from
Changed in pygame 2.0.2:: Argument type changed from
- Start a rumbling effectrumble(low_frequency, high_frequency, duration) -> bool
Start a rumble effect on the controller, with the specified strength ranging from 0 to 1. Duration is length of the effect, in ms. Setting the duration to 0 will play the effect until another one overwrites it or
Controller.stop_rumble()is called. If an effect is already playing, then it will be overwritten.
Returns True if the rumble was played successfully or False if the controller does not support it or
pygame.version.SDL()tupled integers of the SDL library version is below 2.0.9.
New in pygame 2.0.2.
Edit on GitHub