npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gamepad-wrapper

v1.3.4

Published

Game-Loop-Based Gamepad API Wrapper

Downloads

7,940

Readme

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