gamepad-io

Node.js library for gamepad support using node-hid. Provides event-driven API for button presses, stick movements, and key combinations.

Installation

npm install gamepad-io

Important: This library requires native HID access. On Linux, you may need to configure udev rules. On macOS and Windows, additional setup might be required for non-standard gamepads.

Quick Start

import { Gamepad, GamepadEvent, GamepadButton } from 'gamepad-io';
import { config } from 'gamepad-io/src/gamepads/8bitdopro2.json';

// Create gamepad instance
const gamepad = new Gamepad(config);

// Listen for button events
gamepad.on(GamepadEvent.DOWN, (buttonName) => {
    console.log(`Button ${buttonName} pressed`);
});

gamepad.on(GamepadEvent.UP, (buttonName) => {
    console.log(`Button ${buttonName} released`);
});

// Start listening
gamepad.start();

Built-in Configurations

The library provides predefined gamepad configurations for supported controllers. These configurations are available via the gamepadConfigs export.

import { Gamepad, GamepadEvent } from 'gamepad-io';
import { gamepadConfigs } from 'gamepad-io';

// Use the 8BitDo Pro 2 configuration
const gamepad = new Gamepad(gamepadConfigs.eightBitDoPro2);

// Listen for button events
gamepad.on(GamepadEvent.DOWN, (buttonName) => {
    console.log(`Button ${buttonName} pressed`);
});

gamepad.start();

Currently Supported Gamepads

• 8BitDo Pro 2 (gamepadConfigs.eightBitDoPro2) - Vendor ID: 0x2dc8, Product ID: 0x6006
• Logitech F310 (gamepadConfigs.logitechF310) - Vendor ID: 0x046d, Product ID: 0xc216
• Logitech F710 (gamepadConfigs.logitechF710) - Vendor ID: 0x046d, Product ID: 0xc219

To add support for other gamepads, create a custom JSON configuration file following the existing structure and use it with the Gamepad constructor.

Gamepad Configuration Helper

For easier gamepad configuration creation, use the standalone gamepad‑io‑helper tool. It provides a GUI for mapping buttons, axes, and combinations, and generates JSON configurations compatible with gamepad‑io.

Usage Examples

Tracking Button States

import { Gamepad, GamepadEvent, GamepadButton } from 'gamepad-io';
import config from './path-to-your-config.json';

const gamepad = new Gamepad(config);

// Check if a button is currently pressed
if (gamepad.isPressed(GamepadButton.A)) {
    console.log('A button is pressed');
}

// Handle specific button events
gamepad.on(GamepadEvent.DOWN, (buttonName) => {
    switch (buttonName) {
        case GamepadButton.A:
            console.log('Jump!');
            break;
        case GamepadButton.B:
            console.log('Attack!');
            break;
    }
});

gamepad.start();

Working with Sticks (Joysticks)

import { Gamepad, GamepadEvent } from 'gamepad-io';
import config from './path-to-your-config.json';

const gamepad = new Gamepad(config);

// Listen for stick movements
gamepad.on(GamepadEvent.MOVE, (stickName, position) => {
    console.log(`Stick ${stickName} moved: x=${position.x}, y=${position.y}`);

    // Example: dead zone handling
    const deadZone = 0.1;
    if (Math.abs(position.x) > deadZone || Math.abs(position.y) > deadZone) {
        console.log(`Active movement detected`);
    }
});

gamepad.start();

Key Combinations

import { Gamepad, GamepadEvent, GamepadButton } from 'gamepad-io';
import config from './path-to-your-config.json';

const gamepad = new Gamepad(config);

// Register combination
gamepad.registerCombination('SPECIAL_ATTACK', [GamepadButton.A, GamepadButton.B, GamepadButton.X]);

// Listen for combination events
gamepad.on(GamepadEvent.COMBO_DOWN, (comboName) => {
    console.log(`${comboName} activated!`);
});

gamepad.on(GamepadEvent.COMBO_UP, (comboName) => {
    console.log(`${comboName} deactivated`);
});

// Check combination state
if (gamepad.isCombinationPressed('SPECIAL_ATTACK')) {
    console.log('Special attack is ready!');
}

gamepad.start();

Debug Mode

The library includes a debug utility that logs all gamepad events:

import { debug } from 'gamepad-io/debug';
import config from './path-to-your-config.json';

// Start debug mode
debug(config);

Or via npm script:

npm run debug

Development

Building

npm run build

Testing

npm test

Linting

npm run lint
npm run lint:fix  # Auto-fix lint issues

Watch Mode (Development)

npm run dev

License

MIT © 2026 ys.kalyakin