# Joypad

## Overview

The `sol.joypad` type provides an abstraction over the plugged joypads, it uses [SDL's `GameController` API](https://wiki.libsdl.org/SDL2/CategoryGameController) to map any compatible joypad to standard buttons resembling those of the Xbox.

Joypad instances can be fetched using the `sol.input` module.

## Axes and Buttons Names

| Kind    | Names                                                                                                                                                                            |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| buttons | `a`, `b`, `x`, `y`,</br>`back`, `guide`, `start`,</br>`left_stick`, `right_stick`,</br>`left_shoulder`, `right_shoulder`, </br>`dpad_up`, `dpad_down`, `dpad_left`, `dpad_right` |
| axes    | `left_x`, `left_y`, `right_x`, `right_y`,</br>`trigger_left`, `trigger_right`                                                                                                    |

## Methods of the type `joypad`

### `joypad:get_name()`

Returns the name of this joypad.

Return value (string)
: The name if the joypad.

### `joypad:has_rumble()`

Tells whether this joypad has rumble support.

Return value (boolean)
: `true` if the joypad has rumble support.

### `joypad:rumble(low_frequency_intensity, high_frequency_intensity, duration)`

Makes the joypad rumble. Calling this method with intensity of `0` stops the rumbling. Each call to this method cancels any previous rumbling.

`low_frequency_intensity` (number)
: Intensity for the low frequency rumble (left) (0->1).

`high_frequency_intensity` (number)
: Intensity for the high frequency rumble (right) (0->1).

`duration` (number)
: Duration of the rumble in milliseconds.

### `joypad:get_axis(axis)`

Returns the value of a joypad axis (-1 -> 1).

`axis` (string)
: Axis name (see [axes](#axes-and-buttons-names)).

Return value (number)
: The value of a joypad axis (-1 -> 1).

### `joypad:is_button_pressed(button)`

Returns `true` if the button is pressed, `false` otherwise.

`button` (string)
: Button name (see [button](#axes-and-buttons-names)).

Return value (boolean)
: `true` if the button is pressed, `false` otherwise.

### `joypad:is_attached()`

Returns `true` if the joypad is still attached.

Return value (boolean)
: `true` if the joypad is still attached, `false` otherwise.

### `joypad:get_axis_deadzone(axis)`

Returns the deadzone for a specific axis of this joypad.

If no per-axis deadzone has been set, returns the global default (see [`sol.input.get_joypad_deadzone()`](./inputs.md#solinputget_joypad_deadzone)).

`axis` (string)
: Axis name (see [axes](#axes-and-buttons-names)).

Return value (number)
: The deadzone threshold for that axis, normalized between `0.0` and `1.0`.

### `joypad:set_axis_deadzone(axis, deadzone)`

Sets the deadzone for a specific axis of this joypad.

Axis values whose absolute value is below the deadzone are reported as `0`. Values above the deadzone are rescaled so that the output range remains `[-1, 1]`.

This is useful to set a lower deadzone for triggers (which typically need less dead travel) than for sticks. The setting is per-joypad instance and resets when the joypad is disconnected.

`axis` (string)
: Axis name (see [axes](#axes-and-buttons-names)).

`deadzone` (number)
: Deadzone threshold, normalized between `0.0` and `1.0`.

```lua
function sol.input.on_joypad_connected(joypad)
  joypad:set_axis_deadzone("left_x", 0.15)
  joypad:set_axis_deadzone("left_y", 0.15)
  joypad:set_axis_deadzone("right_x", 0.15)
  joypad:set_axis_deadzone("right_y", 0.15)
  joypad:set_axis_deadzone("trigger_left", 0.05)
  joypad:set_axis_deadzone("trigger_right", 0.05)
end
```

## Events of the type `joypad`

### `joypad:on_button_pressed(button)`

Called when a button of this joypad is pressed.

`button` (string)
: Name of the pressed button.

### `joypad:on_button_released(button)`

Called when a button of this joypad is released.

`button` (string)
: Name of the released button.

### `joypad:on_axis_moved(axis, value)`

Called when a axis of this joypad moves.

`axis` (string)
: Name of the axis.

`value` (number)
: New value of the axis.

### `joypad:on_removed()`

Called when the joypad is removed.
