# GamePads

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Input Devices

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/platform/input/game-pads.js#L784

Input handler for accessing GamePad input.

For frame-accumulated input deltas rather than raw pad state, see [GamepadSource](https://api.playcanvas.com/engine/classes/GamepadSource.md),
[KeyboardMouseSource](https://api.playcanvas.com/engine/classes/KeyboardMouseSource.md) and [MultiTouchSource](https://api.playcanvas.com/engine/classes/MultiTouchSource.md), which feed [InputController](https://api.playcanvas.com/engine/classes/InputController.md)s
such as [OrbitController](https://api.playcanvas.com/engine/classes/OrbitController.md), [FlyController](https://api.playcanvas.com/engine/classes/FlyController.md) and [FocusController](https://api.playcanvas.com/engine/classes/FocusController.md).

## Constructors

### constructor

```ts
new GamePads()
```

Create a new GamePads instance.

## Properties

### current

```ts
current: GamePad[] = []
```

The list of current gamepads.

### gamepadsSupported

```ts
gamepadsSupported: boolean
```

Whether gamepads are supported by this device.

## Methods

### findById

```ts
findById(id: string): GamePad | null
```

Find a connected [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) from its identifier.

**Parameters**

- `id` (`string`): The identifier to search for.

**Returns** [`GamePad`](https://api.playcanvas.com/engine/classes/GamePad.md) `| null`: The [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) with the matching identifier or null if no gamepad is found or the gamepad is not connected.

### findByIndex

```ts
findByIndex(index: number): GamePad | null
```

Find a connected [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) from its device index.

**Parameters**

- `index` (`number`): The device index to search for.

**Returns** [`GamePad`](https://api.playcanvas.com/engine/classes/GamePad.md) `| null`: The [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) with the matching device index or null if no gamepad is found or the gamepad is not connected.

### getAxis

```ts
getAxis(orderIndex: number, axis: number): number
```

Get the value of one of the analog axes of the pad.

**Parameters**

- `orderIndex` (`number`): The index of the pad to check, use constants [PAD_1](https://api.playcanvas.com/engine/variables/PAD_1.md), [PAD_2](https://api.playcanvas.com/engine/variables/PAD_2.md), etc. For gamepad index call the function from the pad.
- `axis` (`number`): The axis to get the value of, use constants [PAD_L_STICK_X](https://api.playcanvas.com/engine/variables/PAD_L_STICK_X.md), etc.

**Returns** `number`: The value of the axis between -1 and 1.

### getMap

```ts
getMap(pad: Gamepad): any
```

Retrieve the order for buttons and axes for given HTML5 Gamepad.

**Parameters**

- `pad` (`Gamepad`): The HTML5 Gamepad object.

**Returns** `any`: Object defining the order of buttons and axes for given HTML5 Gamepad.

### isPressed

```ts
isPressed(orderIndex: number, button: number): boolean
```

Returns true if the button on the pad requested is pressed.

**Parameters**

- `orderIndex` (`number`): The order index of the pad to check, use constants [PAD_1](https://api.playcanvas.com/engine/variables/PAD_1.md), [PAD_2](https://api.playcanvas.com/engine/variables/PAD_2.md), etc. For gamepad index call the function from the pad.
- `button` (`number`): The button to test, use constants [PAD_FACE_1](https://api.playcanvas.com/engine/variables/PAD_FACE_1.md), etc.

**Returns** `boolean`: True if the button is pressed.

### poll

```ts
poll(pads?: GamePad[]): GamePad[]
```

Poll for the latest data from the gamepad API.

**Parameters**

- `pads` ([`GamePad`](https://api.playcanvas.com/engine/classes/GamePad.md)`[]`, optional, default `[]`): An optional array used to receive the gamepads mapping. This
  array will be returned by this function.

**Returns** [`GamePad`](https://api.playcanvas.com/engine/classes/GamePad.md)`[]`: An array of gamepads and mappings for the model of gamepad that is
attached.

**Example**

```ts
const gamepads = new GamePads();
const pads = gamepads.poll();
```

### pulse

```ts
pulse(orderIndex: number, intensity: number, duration: number, options?: object): Promise<boolean>
```

Make the gamepad vibrate.

**Parameters**

- `orderIndex` (`number`): The index of the pad to check, use constants [PAD_1](https://api.playcanvas.com/engine/variables/PAD_1.md), [PAD_2](https://api.playcanvas.com/engine/variables/PAD_2.md), etc. For gamepad index call the function from the pad.
- `intensity` (`number`): Intensity for the vibration in the range 0 to 1.
- `duration` (`number`): Duration for the vibration in milliseconds.
- `options` (`object`, optional): Options for special vibration pattern.
    - `options.startDelay` (`number`, optional): Delay before the pattern starts, in milliseconds. Defaults to 0.
    - `options.strongMagnitude` (`number`, optional): Intensity for strong actuators in the range 0 to 1. Defaults to intensity.
    - `options.weakMagnitude` (`number`, optional): Intensity for weak actuators in the range 0 to 1. Defaults to intensity.

**Returns** `Promise<boolean>`: Return a Promise resulting in true if the pulse was successfully completed.

### pulseAll

```ts
pulseAll(intensity: number, duration: number, options?: object): Promise<boolean[]>
```

Make all gamepads vibrate.

**Parameters**

- `intensity` (`number`): Intensity for the vibration in the range 0 to 1.
- `duration` (`number`): Duration for the vibration in milliseconds.
- `options` (`object`, optional): Options for special vibration pattern.
    - `options.startDelay` (`number`, optional): Delay before the pattern starts, in milliseconds. Defaults to 0.
    - `options.strongMagnitude` (`number`, optional): Intensity for strong actuators in the range 0 to 1. Defaults to intensity.
    - `options.weakMagnitude` (`number`, optional): Intensity for weak actuators in the range 0 to 1. Defaults to intensity.

**Returns** `Promise<boolean[]>`: Return a Promise resulting in an array of booleans defining if the pulse was successfully completed for every gamepads.

### wasPressed

```ts
wasPressed(orderIndex: number, button: number): boolean
```

Returns true if the button was pressed since the last frame.

**Parameters**

- `orderIndex` (`number`): The index of the pad to check, use constants [PAD_1](https://api.playcanvas.com/engine/variables/PAD_1.md), [PAD_2](https://api.playcanvas.com/engine/variables/PAD_2.md), etc. For gamepad index call the function from the pad.
- `button` (`number`): The button to test, use constants [PAD_FACE_1](https://api.playcanvas.com/engine/variables/PAD_FACE_1.md), etc.

**Returns** `boolean`: True if the button was pressed since the last frame.

### wasReleased

```ts
wasReleased(orderIndex: number, button: number): boolean
```

Returns true if the button was released since the last frame.

**Parameters**

- `orderIndex` (`number`): The index of the pad to check, use constants [PAD_1](https://api.playcanvas.com/engine/variables/PAD_1.md), [PAD_2](https://api.playcanvas.com/engine/variables/PAD_2.md), etc. For gamepad index call the function from the pad.
- `button` (`number`): The button to test, use constants [PAD_FACE_1](https://api.playcanvas.com/engine/variables/PAD_FACE_1.md), etc.

**Returns** `boolean`: True if the button was released since the last frame.

## Events

### EVENT_GAMEPADCONNECTED

```ts
static EVENT_GAMEPADCONNECTED: string = 'gamepadconnected'
```

Fired when a gamepad is connected. The handler is passed the [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) object that was
connected.

**Example**

```ts
const onPadConnected = (pad) => {
    if (!pad.mapping) {
        // Map the gamepad as the system could not find the proper map.
    } else {
        // Make the gamepad pulse.
    }
};

app.keyboard.on("gamepadconnected", onPadConnected, this);
```

### EVENT_GAMEPADDISCONNECTED

```ts
static EVENT_GAMEPADDISCONNECTED: string = 'gamepaddisconnected'
```

Fired when a gamepad is disconnected. The handler is passed the [GamePad](https://api.playcanvas.com/engine/classes/GamePad.md) object that
was disconnected.

**Example**

```ts
const onPadDisconnected = (pad) => {
    // Pause the game.
};

app.keyboard.on("gamepaddisconnected", onPadDisconnected, this);
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`