joypad-ts

This repo is a fork from joypad.js, add module exports and type declaration.

JavaScript library that lets you connect and use various gaming controllers with browsers that support the Gamepad API.

Zero dependencies and support for button press, axis movement events and vibration play effect.

Examples

Working examples can be found in the examples folder in the repo -

Connection - Gamepad connection example.

Jumping Ball - Button press example (with custom button mapping).

Moving Ball - Axis (analog stick) movement example.

Vibration - Vibration play effect example.

Installation

via npm

npm install @flyskypie/joypad-ts --save

via yarn

yarn add @flyskypie/joypad-ts

Or, download the latest version and include joypad.min.js to your project.

Usage

Once joypad.js is installed and included in your project it becomes available on the global scope - window.joypad.

If you're working with ES6 or Common JS modules you can include the library as follows -

import joypad from '@flyskypie/joypad-ts'; // ES6

const joypad = require('@flyskypie/joypad-ts'); // Common JS

Once set up you can start listening to joypad.js events like so -

joypad.on('connect', (e) => {
  const { id } = e.gamepad;

  console.log(`${id} connected!`);
});

API

joypad.instances {object}

Lists all the connected Gamepad instances. Each instance defines an individual gamepad or controller with access to information such as button presses, axis movements, id, index etc.

console.log(joypad.instances); // {0: Gamepad {id: "Wireless Contr..", index: 0 ..}, 1: Gamepad {id: "Wireless Contr..", index: 1 ..}}

joypad.on(event, callback) {method}

Used to attach event listeners to joypad.js events. It takes 2 parameters, an event name (which is a string) and a callback function which is fired whenever the specified event is triggered.

joypad.on('button_press', (e) => {
  const { buttonName } = e.detail;

  console.log(`${buttonName} was pressed!`);
});

This returns a reference to the unsubscribe method which can be used to unsubscribe from the specified event.

const buttonPressEvent = joypad.on('button_press', e => { ... });

const gameOver = () => {
    buttonPressEvent.unsubscribe();
};

View all of the supported events here.

joypad.set({settings}) {method}

Used to set the global settings for joypad.js such as the threshold for axis movement and options for vibration play effect. It expects a single parameter, which is an object with the required setting values to be applied.

joypad.set({
  axisMovementThreshold: 0.3,
});

Note: To make sure that your applied settings have the desired effect, please use this method before initialising your event listeners.

View all of the available settings here.

joypad.settings {object}

Lists all the global settings applied to joypad.js.

console.log(joypad.settings); // {axisMovementThreshold: 0.3, vibration: {..}}

joypad.vibrate(gamepad, options) {method}

Triggers the vibration play effect for a particular gamepad (which is an instance of Gamepad). The options parameter is an object with the required vibration setting values to be applied.

joypad.on('connect', (e) => {
  const { gamepad } = e;
  const options = {
    startDelay: 500,
    duration: 2000,
    weakMagnitude: 1,
    strongMagnitude: 1,
  };

  joypad.vibrate(gamepad, options);
});

Note: Options passed to the vibrate method will override the global vibration settings.

To know about all the options supported by the vibrate method click here.

Note: Since the Gamepad API is in very early stages, the vibrate method might not work on most browsers.

joypad.trigger(event, data) {method}

Emulates an event with the provided data.

joypad.trigger('button_press', {
  detail: {
    buttonName: 'button_0',
  },
});

Events

connect

Fired whenever a controller is connected.

disconnect

Fired whenever a controller is disconnected.

button_press

Fired whenever a controller's button is pressed.

button_release

Fired whenever a controller's button is released.

joypad.js supports the standard gamepad button layout which is supported by most controllers in which button locations are laid out in a left cluster of four buttons, a right cluster of four buttons , a center cluster of three buttons (some controllers have four) and a pair of front facing buttons (shoulder buttons) on the left and right side of the gamepad.

Note: Since the Gamepad API is in very early stages, the standard gamepad button layout may differ from browser to browser.

The following image and table describes the default button mappings as on Chrome -

| Button | Location | | --------- | ------------------------------ | | button_0 | Bottom button in right cluster | | button_1 | Right button in right cluster | | button_2 | Left button in right cluster | | button_3 | Top button in right cluster | | button_4 | Shoulder left front button | | button_5 | Shoulder right front button | | button_6 | Shoulder left back button | | button_7 | Shoulder right back button | | button_8 | Left button in center cluster | | button_9 | Right button in center cluster | | button_10 | Left stick pressed button | | button_11 | Right stick pressed button | | button_12 | Top button in left cluster | | button_13 | Bottom button in left cluster | | button_14 | Left button in left cluster | | button_15 | Right button in left cluster | | button_16 | Vendor button 1 | | button_17 | Vendor button 2 |

If you would like to set custom button mappings for better cross browser support, you can use the customButtonMapping setting.

axis_move

Fired whenever a controller's axis (analog stick) is moved.

The standard button layout has four axes associated with a pair of analog sticks, one on the left and one on the right.

| Axis | Location | | ---- | -------------------------------------------------------------- | | 0 | Horizontal axis for left stick (negative left/positive right) | | 1 | Vertical axis for left stick (negative up/positive down) | | 2 | Horizontal axis for right stick (negative left/positive right) | | 3 | Vertical axis for right stick (negative up/positive down) |

Settings

vibration {object}

The vibration option sets the parameters for the vibration play effect globally. Currently there is support for a dual-rumble effect. A dual-rumble effect is a fixed-length, constant-intensity vibration effect intended for an actuator of type dual-rumble. Dual-rumble effects are defined by four parameters -

startDelay {number}

Sets the duration of the delay in milliseconds after which the vibration effect is started.

duration {number}

Sets the duration of the vibration effect in milliseconds.

weakMagnitude {number}

Sets the rumble intensity of the high-frequency (weak) rumble motors, normalized to the range [0.0, 1.0].

strongMagnitude {number}

Sets the rumble intensity of the low-frequency (strong) rumble motors, normalized to the range [0.0, 1.0].

joypad.set({
  vibration: {
    startDelay: 500,
    duration: 3000,
    weakMagnitude: 1,
    strongMagnitude: 1,
  },
});

Note: To override the global vibration settings you can pass these parameters to the joypad.vibrate method.

Note: Since the Gamepad API is in very early stages, the vibrate method might not work on most browsers.

axisMovementThreshold {number}

Sets the threshold for axis (analog stick) movement normalized to the range [0.0, 1.0]. Higher the value, more rigid will be the movement.

To test the calibration of the analong sticks you can check out html5gamepad.com and decide a suitable value for the axis movement threshold.

joypad.set({
  axisMovementThreshold: 0.3,
});

customButtonMapping {object}

Used to set custom button mapping for better cross browser button mappings support.

function setCustomButtonMapping() {
  if (browserIs('Firefox')) {
    return {
      button_0: 1,
      button_7: 11,
      button_8: 12,
    };
  } else {
    return null;
  }
}

joypad.set({
  customButtonMapping: setCustomButtonMapping(),
});

Testing

joypad.js uses the Jest test runner. Run the following command to initiate it -

npm test

Building

joypad.js uses SWC for its compilation and bundling. Run the following command to build the library -

npm run build

License

MIT Licensed

All icons and images have been taken from freepik.com.