.. include:: common.txt

:mod:`pygame.joystick`
======================

.. module:: pygame.joystick
   :synopsis: Pygame module for interacting with joysticks, gamepads, and trackballs.

| :sl:`Pygame module for interacting with joysticks, gamepads, and trackballs.`

The joystick module manages the joystick devices on a computer.
Joystick devices include trackballs and video-game-style
gamepads, and the module allows the use of multiple buttons and "hats".
Computers may manage multiple joysticks at a time.

Each instance of the Joystick class represents one gaming device plugged
into the computer. If a gaming pad has multiple joysticks on it, then the
joystick object can actually represent multiple joysticks on that single
game device.

For a quick way to initialise the joystick module and get a list of Joystick instances
use the following code::

    pygame.joystick.init()
    joysticks = [pygame.joystick.Joystick(x) for x in range(pygame.joystick.get_count())]

The following event types will be generated by the joysticks ::

    JOYAXISMOTION JOYBALLMOTION JOYBUTTONDOWN JOYBUTTONUP JOYHATMOTION

And in pygame 2, which supports hotplugging::

   JOYDEVICEADDED JOYDEVICEREMOVED

Note that in pygame 2, joysticks events use a unique "instance ID". The device index
passed in the constructor to a Joystick object is not unique after devices have
been added and removed. You must call :meth:`Joystick.get_instance_id()` to find
the instance ID that was assigned to a Joystick on opening.

The event queue needs to be pumped frequently for some of the methods to work.
So call one of pygame.event.get, pygame.event.wait, or pygame.event.pump regularly.


.. function:: init

   | :sl:`Initialize the joystick module.`
   | :sg:`init() -> None`

   This function is called automatically by ``pygame.init()``.

   It initializes the joystick module. The module must be initialized before any
   other functions will work.

   It is safe to call this function more than once.

   .. ## pygame.joystick.init ##

.. function:: quit

   | :sl:`Uninitialize the joystick module.`
   | :sg:`quit() -> None`

   Uninitialize the joystick module. After you call this any existing joystick
   objects will no longer work.

   It is safe to call this function more than once.

   .. ## pygame.joystick.quit ##

.. function:: get_init

   | :sl:`Returns True if the joystick module is initialized.`
   | :sg:`get_init() -> bool`

   Test if the ``pygame.joystick.init()`` function has been called.

   .. ## pygame.joystick.get_init ##

.. function:: get_count

   | :sl:`Returns the number of joysticks.`
   | :sg:`get_count() -> count`

   Return the number of joystick devices on the system. The count will be ``0`` 
   if there are no joysticks on the system.

   When you create Joystick objects using ``Joystick(id)``, you pass an integer
   that must be lower than this count.

   .. ## pygame.joystick.get_count ##

.. class:: Joystick

   | :sl:`Create a new Joystick object.`
   | :sg:`Joystick(id) -> Joystick`

   Create a new joystick to access a physical device. The id argument must be a
   value from ``0`` to ``pygame.joystick.get_count() - 1``.

   Joysticks are initialised on creation and are shut down when deallocated.
   Once the device is initialized the pygame event queue will start receiving
   events about its input.

   .. versionchanged:: 2.0.0 Joystick objects are now opened immediately on creation.

   .. method:: init

      | :sl:`initialize the Joystick`
      | :sg:`init() -> None`

      Initialize the joystick, if it has been closed. It is safe to call this
      even if the joystick is already initialized.

      .. deprecated:: 2.0.0

         In future it will not be possible to reinitialise a closed Joystick
         object. Will be removed in Pygame 2.1.

      .. ## Joystick.init ##

   .. method:: quit

      | :sl:`uninitialize the Joystick`
      | :sg:`quit() -> None`

      Close a Joystick object. After this the pygame event queue will no longer
      receive events from the device.

      It is safe to call this more than once.

      .. ## Joystick.quit ##

   .. method:: get_init

      | :sl:`check if the Joystick is initialized`
      | :sg:`get_init() -> bool`

      Return True if the Joystick object is currently initialised.

      .. ## Joystick.get_init ##

   .. method:: get_id

      | :sl:`get the device index (deprecated)`
      | :sg:`get_id() -> int`

      Returns the original device index for this device. This is the same
      value that was passed to the ``Joystick()`` constructor. This method can
      safely be called while the Joystick is not initialized.

      .. deprecated:: 2.0.0

         The original device index is not useful in pygame 2. Use
         :meth:`.get_instance_id` instead. Will be removed in Pygame 2.1.

   .. method:: get_instance_id() -> int

      | :sl:`get the joystick instance id`
      | :sg:`get_instance_id() -> int`

      Get the joystick instance ID. This matches the ``instance_id`` field
      that is given in joystick events.

      .. versionadded:: 2.0.0dev11

   .. method:: get_guid() -> str

      | :sl:`get the joystick GUID`
      | :sg:`get_guid() -> str`

      Get the GUID string. This identifies the exact hardware of the joystick
      device.

      .. versionadded:: 2.0.0dev11

   .. method:: get_power_level() -> str

      | :sl:`get the approximate power status of the device`
      | :sg:`get_power_level() -> str`

      Get a string giving the power status of the device.

      One of: ``empty``, ``low``, ``medium``, ``full``, ``wired``, ``max``, or
      ``unknown``.

      .. versionadded:: 2.0.0dev11

      .. ## Joystick.get_id ##

   .. method:: get_name

      | :sl:`get the Joystick system name`
      | :sg:`get_name() -> string`

      Returns the system name for this joystick device. It is unknown what name
      the system will give to the Joystick, but it should be a unique name that
      identifies the device. This method can safely be called while the
      Joystick is not initialized.

      .. ## Joystick.get_name ##

   .. method:: get_numaxes

      | :sl:`get the number of axes on a Joystick`
      | :sg:`get_numaxes() -> int`

      Returns the number of input axes are on a Joystick. There will usually be
      two for the position. Controls like rudders and throttles are treated as
      additional axes.

      The ``pygame.JOYAXISMOTION`` events will be in the range from ``-1.0`` 
      to ``1.0``. A value of ``0.0`` means the axis is centered. Gamepad devices 
      will usually be ``-1``, ``0``, or ``1`` with no values in between. Older 
      analog joystick axes will not always use the full ``-1`` to ``1`` range, 
      and the centered value will be some area around ``0``. 
      
      Analog joysticks usually have a bit of noise in their axis, which will 
      generate a lot of rapid small motion events.

      .. ## Joystick.get_numaxes ##

   .. method:: get_axis

      | :sl:`get the current position of an axis`
      | :sg:`get_axis(axis_number) -> float`

      Returns the current position of a joystick axis. The value will range
      from ``-1`` to ``1`` with a value of ``0`` being centered. You may want 
      to take into account some tolerance to handle jitter, and joystick drift 
      may keep the joystick from centering at ``0`` or using the full range of 
      position values.

      The axis number must be an integer from ``0`` to ``get_numaxes() - 1``.

      When using gamepads both the control sticks and the analog triggers are
      usually reported as axes.

      .. ## Joystick.get_axis ##

   .. method:: get_numballs

      | :sl:`get the number of trackballs on a Joystick`
      | :sg:`get_numballs() -> int`

      Returns the number of trackball devices on a Joystick. These devices work
      similar to a mouse but they have no absolute position; they only have
      relative amounts of movement.

      The ``pygame.JOYBALLMOTION`` event will be sent when the trackball is
      rolled. It will report the amount of movement on the trackball.

      .. ## Joystick.get_numballs ##

   .. method:: get_ball

      | :sl:`get the relative position of a trackball`
      | :sg:`get_ball(ball_number) -> x, y`

      Returns the relative movement of a joystick button. The value is a ``x, y``
      pair holding the relative movement since the last call to get_ball.

      The ball number must be an integer from ``0`` to ``get_numballs() - 1``.

      .. ## Joystick.get_ball ##

   .. method:: get_numbuttons

      | :sl:`get the number of buttons on a Joystick`
      | :sg:`get_numbuttons() -> int`

      Returns the number of pushable buttons on the joystick. These buttons
      have a boolean (on or off) state.

      Buttons generate a ``pygame.JOYBUTTONDOWN`` and ``pygame.JOYBUTTONUP``
      event when they are pressed and released.

      .. ## Joystick.get_numbuttons ##

   .. method:: get_button

      | :sl:`get the current button state`
      | :sg:`get_button(button) -> bool`

      Returns the current state of a joystick button.

      .. ## Joystick.get_button ##

   .. method:: get_numhats

      | :sl:`get the number of hat controls on a Joystick`
      | :sg:`get_numhats() -> int`

      Returns the number of joystick hats on a Joystick. Hat devices are like
      miniature digital joysticks on a joystick. Each hat has two axes of
      input.

      The ``pygame.JOYHATMOTION`` event is generated when the hat changes
      position. The ``position`` attribute for the event contains a pair of 
      values that are either ``-1``, ``0``, or ``1``. A position of ``(0, 0)`` 
      means the hat is centered.

      .. ## Joystick.get_numhats ##

   .. method:: get_hat

      | :sl:`get the position of a joystick hat`
      | :sg:`get_hat(hat_number) -> x, y`

      Returns the current position of a position hat. The position is given as
      two values representing the ``x`` and ``y`` position for the hat. ``(0, 0)``
      means centered. A value of ``-1`` means left/down and a value of ``1`` means
      right/up: so ``(-1, 0)`` means left; ``(1, 0)`` means right; ``(0, 1)`` means 
      up; ``(1, 1)`` means upper-right; etc.

      This value is digital, ``i.e.``, each coordinate can be ``-1``, ``0`` or ``1`` 
      but never in-between.

      The hat number must be between ``0`` and ``get_numhats() - 1``.

      .. ## Joystick.get_hat ##

   .. method:: rumble

      | :sl:`Start a rumbling effect`
      | :sg:`rumble(low_frequency, high_frequency, duration) -> bool`

      Start a rumble effect on the joystick, 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:`Joystick.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
      joystick does not support it or :meth:`pygame.version.SDL` is below 2.0.9.

      .. versionadded:: 2.0.2

      .. ## Joystick.rumble ##

   .. method:: stop_rumble

      | :sl:`Stop any rumble effect playing`
      | :sg:`stop_rumble() -> None`

      Stops any rumble effect playing on the joystick. See
      :meth:`Joystick.rumble` for more information.

      .. versionadded:: 2.0.2

      .. ## Joystick.stop_rumble ##

   .. ## pygame.joystick.Joystick ##

.. ## pygame.joystick ##

.. figure:: code_examples/joystick_calls.png
   :scale: 100 %
   :alt: joystick module example

   Example code for joystick module.

.. literalinclude:: code_examples/joystick_calls.py

.. _controller-mappings:


**Common Controller Axis Mappings**

Controller mappings are drawn from the underlying SDL library which pygame uses and they differ
between pygame 1 and pygame 2. Below are a couple of mappings for two popular game pads.


**Pygame 2**

Axis and hat mappings are listed from -1 to +1.


**X-Box 360 Controller (name: "Xbox 360 Controller")**

In pygame 2 the X360 controller mapping has 6 Axes, 11 buttons and 1 hat.

* **Left Stick**::

    Left -> Right   - Axis 0
    Up   -> Down    - Axis 1

* **Right Stick**::

    Left -> Right   - Axis 3
    Up   -> Down    - Axis 4

* **Left Trigger**::

    Out -> In       - Axis 2

* **Right Trigger**::

    Out -> In       - Axis 5

* **Buttons**::

    A Button        - Button 0
    B Button        - Button 1
    X Button        - Button 2
    Y Button        - Button 3
    Left Bumper     - Button 4
    Right Bumper    - Button 5
    Back Button     - Button 6
    Start Button    - Button 7
    L. Stick In     - Button 8
    R. Stick In     - Button 9
    Guide Button    - Button 10

* **Hat/D-pad**::

    Down -> Up      - Y Axis
    Left -> Right   - X Axis


**Playstation 4 Controller (name: "PS4 Controller")**

In pygame 2 the PS4 controller mapping has 6 Axes and 16 buttons.

* **Left Stick**::

    Left -> Right   - Axis 0
    Up   -> Down    - Axis 1

* **Right Stick**::

    Left -> Right   - Axis 2
    Up   -> Down    - Axis 3

* **Left Trigger**::

    Out -> In       - Axis 4

* **Right Trigger**::

    Out -> In       - Axis 5

* **Buttons**::

    Cross Button    - Button 0
    Circle Button   - Button 1
    Square Button   - Button 2
    Triangle Button - Button 3
    Share Button    - Button 4
    PS Button       - Button 5
    Options Button  - Button 6
    L. Stick In     - Button 7
    R. Stick In     - Button 8
    Left Bumper     - Button 9
    Right Bumper    - Button 10
    D-pad Up        - Button 11
    D-pad Down      - Button 12
    D-pad Left      - Button 13
    D-pad Right     - Button 14
    Touch Pad Click - Button 15

**Pygame 1**

Axis and hat mappings are listed from -1 to +1.


**X-Box 360 Controller (name: "Controller (XBOX 360 For Windows)")**

In pygame 1 the X360 controller mapping has 5 Axes, 10 buttons and 1 hat.

* **Left Stick**::

    Left -> Right   - Axis 0
    Up   -> Down    - Axis 1

* **Right Stick**::

    Left -> Right   - Axis 4
    Up   -> Down    - Axis 3

* **Left Trigger & Right Trigger**::

    RT -> LT        - Axis 2

* **Buttons**::

    A Button        - Button 0
    B Button        - Button 1
    X Button        - Button 2
    Y Button        - Button 3
    Left Bumper     - Button 4
    Right Bumper    - Button 5
    Back Button     - Button 6
    Start Button    - Button 7
    L. Stick In     - Button 8
    R. Stick In     - Button 9

* **Hat/D-pad**::

    Down -> Up      - Y Axis
    Left -> Right   - X Axis


**Playstation 4 Controller (name: "Wireless Controller")**

In pygame 1 the PS4 controller mapping has 6 Axes and 14 buttons and 1 hat.

* **Left Stick**::

    Left -> Right   - Axis 0
    Up   -> Down    - Axis 1

* **Right Stick**::

    Left -> Right   - Axis 2
    Up   -> Down    - Axis 3

* **Left Trigger**::

    Out -> In       - Axis 5

* **Right Trigger**::

    Out -> In       - Axis 4

* **Buttons**::

    Cross Button    - Button 0
    Circle Button   - Button 1
    Square Button   - Button 2
    Triangle Button - Button 3
    Left Bumper     - Button 4
    Right Bumper    - Button 5
    L. Trigger(Full)- Button 6
    R. Trigger(Full)- Button 7
    Share Button    - Button 8
    Options Button  - Button 9
    L. Stick In     - Button 10
    R. Stick In     - Button 11
    PS Button       - Button 12
    Touch Pad Click - Button 13

* **Hat/D-pad**::

    Down -> Up      - Y Axis
    Left -> Right   - X Axis