gamepad-helper

Helper library for Gamepad API.

Overview

Helper library for Gamepad API. Helps with detecting type of gamepad and mapping to buttons and icons.

Installation

Install via NPM registry

1. Add the dependency to your package.json file:

   npm install @lizardbyte/gamepad-helper --ignore-scripts

Install via GitHub Package Registry

1. Add a .npmrc file to the root of your project with the following contents.

   //npm.pkg.github.com/:_authToken=TOKEN
   @lizardbyte:registry=https://npm.pkg.github.com
   

   Replace TOKEN with a valid GitHub token with read access to the package registry.

   See Authenticating with a personal access token for more information or alternative methods of authentication.

2. Add the dependency to your package.json file:

   npm install @lizardbyte/gamepad-helper --ignore-scripts

Controller visuals

GamepadHelper can render the packaged Xbox, PlayStation, and Nintendo Switch controller artwork and keep its buttons, triggers, and sticks synchronized with a browser Gamepad object. The consumer controls the asset location, color scheme, layout, and theme styling.

const gamepadHelper = new GamepadHelper();
const visualizer = gamepadHelper.createVisualizer(
  document.getElementById('controller-visual'),
  {
    assetBasePath: '/assets/img/gamepads/',
    colorScheme: 'White',
  },
);

visualizer.mount(gamepad);
visualizer.update(navigator.getGamepads()[gamepad.index]);

// Remount the current controller with light-theme artwork.
visualizer.setColorScheme('Black');

// Remove the generated DOM when the visual is no longer needed.
visualizer.destroy();

The renderer emits stable gamepad-visual-*, gamepad-trigger-*, and gamepad-stick-indicator classes for consumer styles. Custom renderers can use getControllerVisualConfig() and getControllerImagePath() without duplicating the asset-relative metadata.

Compatibility issues

Use getCompatibilityIssues() to keep browser/controller compatibility knowledge in the library while presenting the warning in the consumer's own UI.

const issues = gamepadHelper.getCompatibilityIssues(gamepad);

issues.forEach(issue => {
  console.warn(issue.message, issue.issueUrl);
});

Attribution

• Button Icons and Controls were created by Zacksly (Licensed under CC BY 3.0 - https://zacksly.itch.io)