Negligent Pachinko Machine

    gamepad-wrapper
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    Gamepad Wrapper 🎮

    npm version language npm download license

    A Game-Loop-Based, Non-Event-Driven, Lightweight Gamepad and WebXR Gamepad Wrapper

    Table of contents

    Key features | Installation | Usage | API | License

    Key features

    • Supports both Gamepad API and the derived WebXR Gamepad API
    • Auto detects and applies gamepad mapping type
    • Built-in support for standard and xr-standard button mapping, no more remembering button index
    • Supports threshold tuning for analog input (specify deadzone by defining min/max input value)
    • Has Typescript types!

    Installation

    To install and set up the library, run:

    $ npm install gamepad-wrapper

    Or if you prefer using Yarn:

    $ yarn add gamepad-wrapper

    Usage

    To properly import GameWrapper:

    // import just the GamepadWrapper class
    import { GamepadWrapper } from 'gamepad-wrapper';
    // or import button/axes Enums with it
    import { GamepadWrapper, BUTTONS, AXES } from 'gamepad-wrapper';

    To register and update gamepads with GameWrapper:

    let gamepadWrapper;
    
    // get standard gamepad object from gamepadconnected event
    window.addEventListener('gamepadconnected', (event) => {
    	gamepadWrapper = new GamepadWrapper(event.gamepad);
    });
    
    // get xr-standard gamepad object from XRInputSource
    // 3D engines like Three.js or Babylon.js usually have
    // their higher-level API to get gamepad
    for (const source of frame.session.inputSources) {
    	gamepadWrapper = new GamepadWrapper(source.gamepad);
    }
    
    // make sure to update the gamepadWrapper before other
    // interactive game logic to get the latest results
    function gameLoop() {
    	gamepadWrapper.update();
    	// do other stuff
    }

    To check button states (including linear inputs like triggers):

    // the trigger of a WebXR gamdpad is pressed down in current frame
    const triggerIsCurrentlyDown = gamepadWrapper.getButton(
    	BUTTONS.XR_STANDARD.TRIGGER,
    );
    
    // the trigger is down in current frame but not in previous frame
    const triggerWasJustPressedDown = gamepadWrapper.getButtonDown(
    	BUTTONS.XR_STANDARD.TRIGGER,
    );
    
    // the trigger was down in previous frame but not in current frame
    const triggerWasJustReleased = gamepadWrapper.getButtonUp(
    	BUTTONS.XR_STANDARD.TRIGGER,
    );

    To check thumbstick states:

    // the left thumbstick x-axis value (between 0 to 1.0)
    const thumbstickValueX = gamepadWrapper.getAxis(
    	AXES.STANDARD.THUMBSTICK_LEFT_X,
    );
    
    // 2D vector length from x-axis and y-axis value of the left thumbstick
    const thumbstickValue = gamepadWrapper.get2DInputValue(
    	BUTTONS.STANDARD.THUMBSTICK_LEFT,
    );

    API

    Constructor

    GamepadWrapper( gamepad : Gamepad, options : ConfigOptions | any )

    ConfigOptions can be used to tune the deadzone for certain input on the gamepad. For example when an old and dusty gamepad cannot reliably register trigger input as 1.0 when fully pressed down, specifying buttonPressValueMax as 0.98 can help resolve the issue. User can also specify buttonClickThreshold as the threshold to register a click event.

    interface ConfigOptions {
    	buttonPressValueMin: number | null;
    	buttonPressValueMax: number | null;
    	buttonClickThreshold: number | null;
    }

    Properties

    .gamepad : Gamepad

    The raw gamepad object, data source of the GamepadWrapper instance.

    Methods

    .getButtonValue

    getButtonValue( buttonId : string ) : number

    Returns the value of the button identified by buttonId. Value should range from 0.0 to 1.0.

    .getButtonValueByIndex

    getButtonValueByIndex( buttonIdx : number ) : number

    Bypasses the button id mapping and directly query by gamepad button index. Returns the value of the button identified by buttonId. Value should range from 0.0 to 1.0.

    .getButton

    getButton( buttonId : string ) : boolean

    Returns true while the button identified by buttonId is held down.

    .getButtonByIndex

    getButtonByIndex( buttonIdx : number ) : boolean

    Bypasses the button id mapping and directly query by gamepad button index. Returns true while the button identified by buttonId is held down.

    .getButtonDown

    getButtonDown( buttonId : string ) : boolean

    Returns true during the frame the user pressed down the button identified by buttonId.

    .getButtonDownByIndex

    getButtonDownByIndex( buttonIdx : number ) : boolean

    Bypasses the button id mapping and directly query by gamepad button index. Returns true during the frame the user pressed down the button identified by buttonId.

    .getButtonUp

    getButtonUp( buttonId : string ) : boolean

    Returns true the first frame the user releases the button identified by buttonId.

    .getButtonUpByIndex

    getButtonUpByIndex( buttonIdx : number ) : boolean

    Bypasses the button id mapping and directly query by gamepad button index. Returns true the first frame the user releases the button identified by buttonId.

    .getButtonClick

    getButtonClick( buttonId : string ) : boolean

    Returns true the first frame the user pressed the button identified by buttonId down to a point exceeding the buttonClickThreshold.

    .getButtonClickByIndex

    getButtonClickByIndex( buttonIdx : number ) : boolean

    Bypasses the button id mapping and directly query by gamepad button index. Returns true the first frame the user pressed the button identified by buttonId down to a point exceeding the buttonClickThreshold.

    .getAxis

    getAxis( axisId : string ) : number

    Returns the value of the axis identified by axisId. Value should range from -1.0 to 1.0.

    .getAxisByIndex

    getAxisByIndex( axisIdx : number ) : number

    Bypasses the button id mapping and directly query by gamepad button index. Returns the value of the axis identified by axisId. Value should range from -1.0 to 1.0.

    .get2DInputAngle

    get2DInputAngle( buttonId : string ) : number

    Returns the angle between the input 2D vector and 2D vector (0, 1).

    .get2DInputValue

    get2DInputValue( buttonId : string ) : number

    Returns the Euclidean length of the input 2D vector.

    .getHapticActuator

    getHapticActuator( actuatorIdx : number ) : GamepadHapticActuator | never

    Returns the GamepadHapticActuator of actuatorIdx, returns null if actuator is not available.

    Input Mapping Enums

    Standard Gamepad Mapping

    Button ID Description XBox
    BUTTONS.STANDARD.RC_BOTTOM Bottom button in right cluster A
    BUTTONS.STANDARD.RC_RIGHT Right button in right cluster B
    BUTTONS.STANDARD.RC_LEFT Left button in right cluster X
    BUTTONS.STANDARD.RC_TOP Top button in right cluster Y
    BUTTONS.STANDARD.BUMPER_LEFT Top left front button Left Bumper
    BUTTONS.STANDARD.BUMPER_RIGHT Top right front button Right Bumper
    BUTTONS.STANDARD.TRIGGER_LEFT Bottom left front button Left Trigger
    BUTTONS.STANDARD.TRIGGER_RIGHT Bottom right front button Right Trigger
    BUTTONS.STANDARD.CC_LEFT Left button in center cluster View Button
    BUTTONS.STANDARD.CC_RIGHT Right button in center cluster Menu Button
    BUTTONS.STANDARD.THUMBSTICK_LEFT Left stick pressed button Left Stick
    BUTTONS.STANDARD.THUMBSTICK_RIGHT Right stick pressed button Right Stick
    BUTTONS.STANDARD.LC_BOTTOM Bottom button in left cluster D-pad Down
    BUTTONS.STANDARD.LC_RIGHT Right button in left cluster D-pad Right
    BUTTONS.STANDARD.LC_LEFT Left button in left cluster D-pad Left
    BUTTONS.STANDARD.LC_TOP Top button in left cluster D-pad Up
    BUTTONS.STANDARD.CC_CENTER Center button in center cluster Xbox Button

    License

    MIT License © Felix Zhang

    Install

    npm i gamepad-wrapper

    DownloadsWeekly Downloads

    1,719

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    48.1 kB

    Total Files

    23

    Last publish

    Collaborators

    • felixtrz