useGamepad

Category

Browser

Export Size

1.72 kB

Last Changed

5 days ago

Provides reactive bindings for the Gamepad API.

Demo

Usage

Due to how the Gamepad API works, you must interact with the page using the gamepad before it will be detected.

import { useGamepad } from '@reause/core'

const [gamepads, setGamepads, { isSupported }] = useGamepad()
const gamepad = gamepads.find(g => g.mapping === 'standard')

Gamepad Updates

Currently the Gamepad API does not have event support to update the state of the gamepad. To update the gamepad state, requestAnimationFrame is used to poll for gamepad changes. You can control this polling by using the pause and resume functions provided by useGamepad

import { useGamepad } from '@reause/core'

const [gamepads, , { pause, resume }] = useGamepad()

pause()

// gamepads object will not update

resume()

// gamepads object will update on user input

Gamepad Connect & Disconnect Events

The onConnected and onDisconnected events will trigger when a gamepad is connected or disconnected.

import { useGamepad } from '@reause/core'

const [gamepads, , { onConnected, onDisconnected }] = useGamepad()

onConnected((index) => {
  console.log(`${gamepads[index].id} connected`)
})

onDisconnected((index) => {
  console.log(`${index} disconnected`)
})

Vibration

The Gamepad Haptics API is sparse, so check the compatibility table before using.

import { useGamepad } from '@reause/core'

const [gamepads] = useGamepad()
const gamepad = gamepads[0]!

const supportsVibration = gamepad.hapticActuators.length > 0
function vibrate() {
  if (supportsVibration) {
    const actuator = gamepad.hapticActuators[0]
    actuator.playEffect('dual-rumble', {
      startDelay: 0,
      duration: 1000,
      weakMagnitude: 1,
      strongMagnitude: 1,
    })
  }
}

Mappings

To make the Gamepad API easier to use, we provide mappings to map a controller to a controllers button layout.

Xbox360 Controller

import { mapGamepadToXbox360Controller } from '@reause/core'

const [gamepads] = useGamepad()
const gamepad = gamepads[0]
const controller = mapGamepadToXbox360Controller(gamepad)

// controller is null until a gamepad is connected
console.log(controller?.buttons.a.pressed)
console.log(controller?.buttons.b.pressed)
console.log(controller?.buttons.x.pressed)
console.log(controller?.buttons.y.pressed)

Currently there are only mappings for the Xbox 360 controller. If you have controller you want to add mappings for, feel free to open a PR for more controller mappings!

Type Declarations

Toggle

export interface UseGamepadOptions extends ConfigurableWindow {
    navigator?: Navigator;
}

export interface UseGamepadControls {
    isSupported: boolean;
    onConnected: (fn: (index: number) => void) => () => void;
    onDisconnected: (fn: (index: number) => void) => () => void;
    pause: () => void;
    resume: () => void;
    isActive: boolean;
}

export interface Xbox360Controller {
    buttons: {
        a: GamepadButton;
        b: GamepadButton;
        x: GamepadButton;
        y: GamepadButton;
    };
    bumper: {
        left: GamepadButton;
        right: GamepadButton;
    };
    triggers: {
        left: GamepadButton;
        right: GamepadButton;
    };
    stick: {
        left: {
            horizontal: number;
            vertical: number;
            button: GamepadButton;
        };
        right: {
            horizontal: number;
            vertical: number;
            button: GamepadButton;
        };
    };
    dpad: {
        up: GamepadButton;
        down: GamepadButton;
        left: GamepadButton;
        right: GamepadButton;
    };
    back: GamepadButton;
    start: GamepadButton;
}

export type UseGamepadReturn = readonly [
    gamepads: Gamepad[],
    setGamepads: Dispatch<SetStateAction<Gamepad[]>>,
    controls: UseGamepadControls
]

export function mapGamepadToXbox360Controller(gamepad: Gamepad | undefined): Xbox360Controller | null

export function useGamepad(options?: UseGamepadOptions): UseGamepadReturn

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.7 on

534c2 - refactor(shared)!: return the off function from listener registrars

v0.1.0 on

c9cc3 - fix(core): resolve useGamepad audit findings (#579)