Class GamePads

Input handler for accessing GamePad input.

Hierarchy (View Summary)

Constructors

constructor

Properties

current gamepadsSupported

Methods

findById findByIndex fire getAxis getMap hasEvent isPressed off on once poll pulse pulseAll wasPressed wasReleased

Events

EVENT_GAMEPADCONNECTED EVENT_GAMEPADDISCONNECTED

Constructors

constructor

Properties

current

current: GamePad[]

The list of current gamepads.

gamepadsSupported

gamepadsSupported: boolean

Whether gamepads are supported by this device.

Methods

findById

findByIndex

fire

  • fire(
        name: string,
        arg1?: any,
        arg2?: any,
        arg3?: any,
        arg4?: any,
        arg5?: any,
        arg6?: any,
        arg7?: any,
        arg8?: any,
    ): EventHandler

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    Example

    obj.fire('test', 'This is the message');

getAxis

  • 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, PAD_2, 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, etc.

    Returns number

    The value of the axis between -1 and 1.

getMap

hasEvent

  • hasEvent(name: string): boolean

  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    Example

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

isPressed

  • 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, PAD_2, etc. For gamepad index call the function from the pad.

    • button: number

      The button to test, use constants PAD_FACE_1, etc.

    Returns boolean

    True if the button is pressed.

off

  • off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler

  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    Example

    const handler = function () {
    };
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

on

  • on(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    Example

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', function (a, b) {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.

    Example

    obj.once('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

poll

  • poll(pads?: GamePad[]): GamePad[]

  • Poll for the latest data from the gamepad API.

    Parameters

    • Optionalpads: GamePad[] = []

      An optional array used to receive the gamepads mapping. This array will be returned by this function.

    Returns GamePad[]

    An array of gamepads and mappings for the model of gamepad that is attached.

    Example

    const gamepads = new pc.GamePads();
    const pads = gamepads.poll();

pulse

  • pulse(
        orderIndex: number,
        intensity: number,
        duration: number,
        options?: {
            startDelay?: number;
            strongMagnitude?: number;
            weakMagnitude?: number;
        },
    ): Promise<boolean>

  • Make the gamepad vibrate.

    Parameters

    • orderIndex: number

      The index of the pad to check, use constants PAD_1, PAD_2, 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.

    • Optionaloptions: { startDelay?: number; strongMagnitude?: number; weakMagnitude?: number }

      Options for special vibration pattern.

      • OptionalstartDelay?: number

        Delay before the pattern starts, in milliseconds. Defaults to 0.

      • OptionalstrongMagnitude?: number

        Intensity for strong actuators in the range 0 to 1. Defaults to intensity.

      • OptionalweakMagnitude?: number

        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

  • pulseAll(
        intensity: number,
        duration: number,
        options?: {
            startDelay?: number;
            strongMagnitude?: number;
            weakMagnitude?: number;
        },
    ): 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.

    • Optionaloptions: { startDelay?: number; strongMagnitude?: number; weakMagnitude?: number }

      Options for special vibration pattern.

      • OptionalstartDelay?: number

        Delay before the pattern starts, in milliseconds. Defaults to 0.

      • OptionalstrongMagnitude?: number

        Intensity for strong actuators in the range 0 to 1. Defaults to intensity.

      • OptionalweakMagnitude?: number

        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

  • 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, PAD_2, etc. For gamepad index call the function from the pad.

    • button: number

      The button to test, use constants PAD_FACE_1, etc.

    Returns boolean

    True if the button was pressed since the last frame.

wasReleased

  • 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, PAD_2, etc. For gamepad index call the function from the pad.

    • button: number

      The button to test, use constants PAD_FACE_1, etc.

    Returns boolean

    True if the button was released since the last frame.

Events

StaticEVENT_GAMEPADCONNECTED

EVENT_GAMEPADCONNECTED: string = 'gamepadconnected'

Fired when a gamepad is connected. The handler is passed the GamePad object that was connected.

Example

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);

StaticEVENT_GAMEPADDISCONNECTED

EVENT_GAMEPADDISCONNECTED: string = 'gamepaddisconnected'

Fired when a gamepad is disconnected. The handler is passed the GamePad object that was disconnected.

Example

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

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

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
Events