Engine API Reference - v2.6.1
    Preparing search index...

    Class GamePads

    Input handler for accessing GamePad input.

    Hierarchy (View Summary)

    Index

    Constructors

    Properties

    current: GamePad[]

    The list of current gamepads.

    gamepadsSupported: boolean

    Whether gamepads are supported by this device.

    Methods

    • Find a connected GamePad from its identifier.

      Parameters

      • id: string

        The identifier to search for.

      Returns null | GamePad

      The GamePad with the matching identifier or null if no gamepad is found or the gamepad is not connected.

    • Find a connected GamePad from its device index.

      Parameters

      • index: number

        The device index to search for.

      Returns null | GamePad

      The GamePad with the matching device index or null if no gamepad is found or the gamepad is not connected.

    • 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.

      obj.fire('test', 'This is the message');
      
    • 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.

    • 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.

    • 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.

      obj.on('test', () => {}); // bind an event to 'test'
      obj.hasEvent('test'); // returns true
      obj.hasEvent('hello'); // returns false
    • 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.

    • 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: any

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

      Returns EventHandler

      Self for chaining.

      const handler = () => {};
      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
    • 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: any = ...

        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.

      obj.on('test', (a, b) => {
      console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console
      const evt = obj.on('test', (a, b) => {
      console.log(a + b);
      });
      // some time later
      evt.off();
    • 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: any = ...

        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.
      obj.once('test', (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 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.

      const gamepads = new pc.GamePads();
      const pads = gamepads.poll();
    • 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.

    • 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.

    • 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.

    • 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

    EVENT_GAMEPADCONNECTED: string = 'gamepadconnected'

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

    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: string = 'gamepaddisconnected'

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

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

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