Class GamepadManagerSingleton

A Gamepad API manager for games and interactive applications.

Polling ownership

The manager starts an internal requestAnimationFrame polling loop when it is constructed. This is the easiest option for menus, tools, and small applications: connect/disconnect events are handled automatically and controller state changes are delivered without any setup beyond registering listeners.

Games that already own a single authoritative frame loop should use the host-controlled option instead:

GamepadManager.stopPolling();
gameLoop.onFrame(() => GamepadManager.pollGamepadStateOnce());

Do not use both polling modes. Running the library loop and calling pollGamepadStateOnce() from another loop reads and processes the same controller state twice per frame. That creates redundant work, can duplicate event callbacks, and can make input race the host's simulation order.

The tradeoff is simple:

  • Automatic polling is simpler and is usually correct for UI or small apps.
  • Host-controlled polling gives a game deterministic update ordering and avoids a second animation-frame loop, at the cost of one more integration step and responsibility for polling once per frame.

The library normalizes device state and emits controller events. It does not decide whether mouse, touch, or another controller owns a game's input; that arbitration belongs in the host game's input manager.

GamepadManagerSingleton

License

GamepadManager does not have a license at this time. For licensing contact the author

Author

https://github.com/doubleactii

Todo

Currently bluetooth gamepads when disconnecting (PS4 only) do no fire a disconnected event. Manually calling this.gamepad.vibrationActuator.reset() can force it to call a disconnect event, but this is a messy way of checking each tick to see if the gamepad is still connected. It also will cancel ongoing vibrations. Find a fix. (This is a GamepadAPI issue/OS issue/not code wise issue)

Constructors

Properties

connectHandler: {
    [key: string]: ((controller) => void);
} = {}

Object containing the callback for when a controller is connected

Type declaration

  • [key: string]: ((controller) => void)
      • (controller): void
      • Parameters

        Returns void

connectedControllers: null | Set<Controller> = null

Controllers connected before an event listener caught them.

unassignedControllers: null | Set<Controller> = null

Controllers connected before an event listener caught them.

disconnectHandler: {
    [key: string]: ((controller) => void);
} = {}

Object containing the callback for when a controller is disconnected

Type declaration

  • [key: string]: ((controller) => void)
      • (controller): void
      • Parameters

        Returns void

version: string = "VERSION_REPLACE_ME"

The version of the module.

logger: any

The logger module this module uses to log errors / logs.

Methods

  • Gets the angle between two points

    Parameters

    • pStartPoint: Point2D

      The starting point

    • pEndPoint: Point2D

      The ending point

    Returns number

    The angle between the starting point and the ending point

    Deprecated

    Use Controller.getAngle() instead

  • Sets the main controller by index

    Parameters

    • pIndex: number

      The index of the controller to set as main

    Returns boolean

    True if successfully set, false if controller not found

  • Gets a specific controller by index

    Parameters

    • pIndex: number

      The index of the controller

    Returns null | Controller

    The controller or null if not found

  • Gets all controllers with metadata

    Returns {
        controller: Controller;
        index: number;
        isMain: boolean;
        connectionOrder: number;
    }[]

    Array of controller objects with metadata

  • Attaches a callback to the specified event.

    Parameters

    • pEvent: string

      The event to attach the callback to

    • pCallback: ((controller) => void)

      The function to be called when the event is triggered

        • (controller): void
        • Parameters

          Returns void

    Returns GamepadManagerSingleton

    The GamepadManagerSingleton instance

  • Listener function for when a gamepad is connected

    Parameters

    • pGamepadEvent: GamepadEvent

      A gamepad event

    Returns void

  • Listener function for when the gamepad is disconnected

    Parameters

    • pGamepadEvent: GamepadEvent

      A gamepad event

    Returns void

  • Starts the library-owned requestAnimationFrame polling loop.

    Use this for the library-managed polling mode. It is idempotent, so calling it while polling is already active does not create another loop. Do not call this if the host is polling with pollGamepadStateOnce().

    Returns void

  • Stops the library-owned requestAnimationFrame polling loop.

    This does not disconnect controllers or clear their cached state. It only transfers polling responsibility to the host. Pair it with one pollGamepadStateOnce() call per host frame when the game owns its loop.

    Returns void

  • Returns whether the library-owned polling loop is active.

    Returns boolean

  • Polls controller state exactly once.

    Hosts with an existing game loop should call stopPolling() once and then call this method once per frame. It reads navigator.getGamepads(), updates every connected controller, and may emit button/analog events. Avoid doing expensive work or allocating heavily inside those callbacks because this method normally runs at frame rate.

    Returns void

  • Poll callback for the library-owned loop.

    Prefer startPolling()/stopPolling()/pollGamepadStateOnce() in host code. Calling this method directly is unnecessary and can be confusing because it also schedules the next automatic poll while polling is active.

    Returns void