.. module:: pygame._sdl2.controller :synopsis: pygame module to work with controllers
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_X is
always the leftmost button of the 4 buttons on the right.
Controllers can generate the following events:
CONTROLLERAXISMOTION, CONTROLLERBUTTONDOWN, CONTROLLERBUTTONUP, CONTROLLERDEVICEREMAPPED, CONTROLLERDEVICEADDED, CONTROLLERDEVICEREMOVED, CONTROLLERTOUCHPADDOWN, CONTROLLERTOUCHPADMOTION, CONTROLLERTOUCHPADUP
These events can be enabled/disabled by :meth:`pygame._sdl2.controller.set_eventstate` Note that controllers can generate joystick events as well. This function only toggles events related to controllers.
Note
See the :mod:`pygame.joystick` for a more versatile but more advanced api.
.. versionaddedold:: 2 This module requires SDL2.
.. function:: init | :sl:`initialize the controller module` | :sg:`init() -> None` Initialize the controller module. .. ## pygame._sdl2.controller.init ##
.. function:: quit | :sl:`Uninitialize the controller module.` | :sg:`quit() -> None` Uninitialize the controller module. .. ## pygame._sdl2.controller.quit ##
.. function:: get_init
| :sl:`Returns True if the controller module is initialized.`
| :sg:`get_init() -> bool`
Test if ``pygame._sdl2.controller.init()`` was called.
.. ## pygame._sdl2.controller.get_init ##
.. function:: set_eventstate
| :sl:`Sets the current state of events related to controllers`
| :sg:`set_eventstate(state) -> None`
Enable or disable events connected to controllers.
.. note::
Controllers can still generate joystick events, which will not be toggled by this function.
.. versionchangedold:: 2.0.2: Changed return type from int to None
.. ## pygame._sdl2.controller.set_eventstate ##
.. function:: get_eventstate
| :sl:`Gets the current state of events related to controllers`
| :sg:`get_eventstate() -> bool`
Returns the current state of events related to controllers, True meaning
events will be posted.
.. versionaddedold:: 2.0.2
.. ## pygame._sdl2.controller.get_eventstate ##
.. function:: get_count
| :sl:`Get the number of joysticks connected`
| :sg:`get_count() -> int`
Get the number of joysticks connected.
.. ## pygame._sdl2.controller.get_count ##
.. function:: is_controller
| :sl:`Check if the given joystick is supported by the game controller interface`
| :sg:`is_controller(index) -> bool`
Returns True if the index given can be used to create a controller object.
.. ## pygame._sdl2.controller.is_controller ##
.. function:: name_forindex
| :sl:`Get the name of the controller`
| :sg:`name_forindex(index) -> name or None`
Returns the name of controller, or None if there's no name or the
index is invalid.
.. ## pygame._sdl2.controller.name_forindex ##
Create a new Controller object. Index should be integer between 0 and
pygame._sdl2.controller.get_count(). Controllers also can be created from apygame.joystick.Joystickusingpygame._sdl2.controller.from_joystick. Controllers are initialized on creation.
.. method:: init | :sl:`Initialize the Controller` | :sg:`init() -> None` Initialize a controller object. This should not be used much, since Controllers are initialised on creation.
.. method:: quit | :sl:`uninitialize the Controller` | :sg:`quit() -> 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. .. ## Controller.quit ##
.. method:: get_init | :sl:`check if the Controller is initialized` | :sg:`get_init() -> bool` Returns True if the Controller object is currently initialised. .. ## Controller.get_init ##
.. staticmethod:: from_joystick
| :sl:`Create a Controller from a pygame.joystick.Joystick object`
| :sg:`from_joystick(joystick) -> Controller`
Create a Controller object from a ``pygame.joystick.Joystick`` object
.. ## Controller.from_joystick ##
.. method:: attached | :sl:`Check if the Controller has been opened and is currently connected.` | :sg:`attached() -> bool` Returns True if the Controller object is opened and connected. .. ## Controller.attached ##
.. method:: as_joystick | :sl:`Returns a pygame.joystick.Joystick() object` | :sg:`as_joystick() -> Joystick object` Returns a pygame.joystick.Joystick() object created from this controller's index .. ## Controller.as_joystick ##
.. method:: get_axis
| :sl:`Get the current state of a joystick axis`
| :sg:`get_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.
.. ## Controller.get_axis ##
.. method:: get_button
| :sl:`Get the current state of a button`
| :sg:`get_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
.. ## Controller.get_button ##
.. method:: get_mapping | :sl:`Get the mapping assigned to the controller` | :sg:`get_mapping() -> mapping` Returns a dict containing the mapping of the Controller. For more information see :meth:`Controller.set_mapping()` .. versionchangedold:: 2.0.2: Return type changed from ``str`` to ``dict`` .. ## Controller.get_mapping ##
.. method:: set_mapping
| :sl:`Assign a mapping to the controller`
| :sg:`set_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 :meth:`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.
.. versionchangedold:: 2.0.2: Renamed from ``add_mapping`` to ``set_mapping``
.. versionchangedold:: 2.0.2: Argument type changed from ``str`` to ``dict``
.. ## Controller.set_mapping ##
.. method:: rumble | :sl:`Start a rumbling effect` | :sg:`rumble(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 :meth:`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. .. versionaddedold:: 2.0.2 .. ## Controller.rumble ##
.. method:: stop_rumble | :sl:`Stop any rumble effect playing` | :sg:`stop_rumble() -> None` Stops any rumble effect playing on the controller. See :meth:`Controller.rumble` for more information. .. versionaddedold:: 2.0.2 .. ## Controller.stop_rumble ##