HUD GamePad

A fully customizable on-screen gamepad interface for HTML5 canvas applications

npm i hud-gamepad

Quick Start

import { GamePad } from 'hud-gamepad';

// Basic setup with joystick and default buttons
GamePad.setup({
  joystick: true
});

// Listen for state changes
setInterval(() => {
  const state = GamePad.observe();
  console.log(state);
}, 16);

Try the Live Demo

Configuration Options

The GamePad is highly customizable with various options for buttons, layout, and behavior.

| Property | Type | Values | Description | Example | |----------|------|--------|-------------|---------| | canvas | string | Canvas ID | Target canvas element (creates new if omitted) | canvas: "gamepad" | | joystick | boolean | true/false | Enable joystick (default: false) | joystick: true | | buttons | array | [{name, color, key}] | Button configurations | buttons: [{name: "a", color: "rgba(255,0,0,0.75)"}] | | layout | string | TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT | Controller position (default: BOTTOM_RIGHT) | layout: "BOTTOM_LEFT" | | start | boolean | true/false | Show start button (default: false) | start: true | | select | boolean | true/false | Show select button (default: false) | select: true | | debug | boolean | true/false | Show debug info (default: false) | debug: true | | trace | boolean | true/false | Show state trace (default: false) | trace: true | | hint | boolean | true/false | Show keyboard hints (default: false) | hint: true | | hidden | boolean | true/false | Hide gamepad (default: false) | hidden: true |

Button Configuration

Each button can be customized with:

{
  name: "a",                    // Button label
  color: "rgba(255,0,0,0.75)", // Button color
  key: "x"                     // Keyboard binding
}

Example Configurations

Basic Setup

GamePad.setup();

Custom Button Configuration

GamePad.setup({
  buttons: [
    { name: "jump", color: "rgba(255,0,0,0.75)", key: "space" },
    { name: "shoot", color: "rgba(0,255,0,0.75)", key: "x" }
  ],
  joystick: true,
  hint: true
});

Full Configuration

GamePad.setup({
  canvas: "gamepad",
  joystick: true,
  start: true,
  select: true,
  debug: true,
  trace: true,
  hint: true,
  layout: "BOTTOM_RIGHT",
  buttons: [
    { name: "a", color: "rgba(255,0,0,0.75)", key: "x" },
    { name: "b", color: "rgba(0,255,0,0.75)", key: "z" },
    { name: "x", color: "rgba(0,0,255,0.75)", key: "a" },
    { name: "y", color: "rgba(255,255,0,0.75)", key: "s" }
  ]
});

State Observation

The GamePad provides real-time state information through the observe method:

// Get current state
const state = GamePad.observe();

// State includes:
// - Button states (0 or 1)
// - Joystick axes (-1 to 1)
// - Joystick directions (-1, 0, 1)

// Example state object:
{
  "a": 0,          // Button a state
  "b": 1,          // Button b state
  "x-axis": 0.5,   // Joystick X position
  "y-axis": -0.25, // Joystick Y position
  "x-dir": 1,      // Joystick X direction
  "y-dir": -1      // Joystick Y direction
}

Integration Example

// Game loop integration
function gameLoop() {
  const state = GamePad.observe();

  // Handle joystick
  if (state["x-axis"] !== 0 || state["y-axis"] !== 0) {
    player.move(state["x-axis"], state["y-axis"]);
  }

  // Handle buttons
  if (state.a) {
    player.jump();
  }

  requestAnimationFrame(gameLoop);
}

gameLoop();

Example with Keyboard Support

GamePad.setup({
  canvas: "controller",
  start: true,
  select: true,
  trace: true,
  debug: true,
  hint: true,
  buttons: [
    { name: "a", key: "s" },
    { name: "b", key: "a" },
    { name: "x", key: "w" },
    { name: "y", key: "q" }
  ]
});

Browser Support

• Modern browsers with Canvas support
• Touch events for mobile devices
• Keyboard support for desktop

License

ISC License