Chapter 8: Controllers and haptics

Web games are no longer limited to only mouse and keyboard inputs! Using controllers in web games has been possible since 2012, but even over a decade later I seldom see games take advantage of these capabilities, which is a real shame since controller support--especially in local multiplayer games--can completely transform gameplay.

This chapter will teach you how to add controller support to your web games from scratch. But if you're more interested in a higher-level wrapper for handling controllers so that you don't need to do the math yourself for things like analog stick normalization, we've also got you covered.

The Gamepad API

Browsers refer to controllers as "gamepads" so that's what we'll call them from here on out, too. The Gamepad API [MDN] supports up to four simultaneously connected gamepads.

const [p1, p2, p3, p4] = navigator.getGamepads();

This array generally fills in from left to right, but it can also be sparse. Browsers try to keep the same controller in the same index, so if three controllers are initially connected and then players 1 and 2 disconnect, the array will look like this:

navigator.getGamepads(); // => [undefined, undefined, Gamepad, undefined]

Let's say P2 rejoins. They'll enter back into slot 2:

navigator.getGamepads(); // => [undefined, Gamepad, Gamepad, undefined]

Just note that this is a best-effort algorithm, so it isn't guaranteed that a specific controller will rejoin into any particular slot. The practical takeaway here is that your gameplay should not depend on specific slots being filled. If you have a two-player game, it may be the case that the two connected controllers are in slots 3 and 4, not 1 and 2.

So, once you have a reference to a Gamepad object, what can you do with it?

Buttons

Each Gamepad contains an array of buttons. The index of each button in the array tells you which button it is. The Start button, for example, is at index 9, so to check if it's pressed for Player 1, you would run:

const [p1] = navigator.getGamepads();

if (p1) {
  const startButton = p1.buttons[9];
  if (startButton.pressed) {
    // do start action
  }
}

Having to remember which button is at each index is a pain. So feel free to copy this constant to refer to gamepad buttons in your codebase by name rather than by index!

/**
 * Standard gamepad button mappings using the HTML5 Gamepad API button indices.
 * These values correspond to the physical buttons on most modern controllers.
 * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
 */
export const Button = {
  /** Xbox A / PlayStation ✕ / Nintendo B */
  South: 0,
  /** Xbox B / PlayStation ○ / Nintendo A */
  East: 1,
  /** Xbox X / PlayStation □ / Nintendo Y */
  West: 2,
  /** Xbox Y / PlayStation △ / Nintendo X */
  North: 3,

  /**
   * Xbox LB / PlayStation L1 / Nintendo L
   * Check the boolean `pressed` property.
   */
  LeftShoulder: 4,
  /**
   * Xbox RB / PlayStation R1 / Nintendo R
   * Check the boolean `pressed` property.
   */
  RightShoulder: 5,
  /**
   * Xbox LT / PlayStation L2 / Nintendo ZL
   * When used as a button, check the boolean `pressed` property.
   * When used as an analog value, check the floating point `value` (0-1 range) property.
   */
  LeftTrigger: 6,
  /**
   * Xbox RT / PlayStation R2 / Nintendo ZR
   * When used as a button, check the boolean `pressed` property.
   * When used as an analog value, check the floating point `value` (0-1 range) property.
   */
  RightTrigger: 7,

  /** Select/View/Back button */
  Select: 8,
  /** Start/Menu button */
  Start: 9,

  /** Left analog stick clickable button */
  LeftStick: 10,
  /** Right analog stick clickable button */
  RightStick: 11,

  /** Directional pad up button */
  DpadUp: 12,
  /** Directional pad down button */
  DpadDown: 13,
  /** Directional pad left button */
  DpadLeft: 14,
  /** Directional pad right button */
  DpadRight: 15,

  /**
   * Microsoft "Xbox" button / Sony "PlayStation" button / Nintendo Switch "Home" button
   */
  Home: 16,
  /**
   * Nintendo Switch controller "Capture" button
   * Alias: `Button.TouchPad` (for Sony DualSense/DualShock)
   */
  Capture: 17,
  /**
   * Sony TouchPad button
   * Alias: `Button.Capture` (for Nintendo Switch controllers)
   */
  TouchPad: 17,
} as const;

export type Button = (typeof Button)[keyof typeof Button];

Triggers

Triggers are a special type of button that have a floating point value property between 0 and 1.

The left trigger happens to be the button at index 6, so if you wanted to use it to increase your player's speed anywhere between 1-2x, you could do this:

const [p1] = navigator.getGamepads();

if (p1) {
  const leftTrigger = p1.buttons[6];
  const speedBoostMultiplier = 1 + leftTrigger.value;
  // ...
}

Axes

In addition to buttons and triggers, gamepads have two analog sticks (aka joysticks aka left/right thumbsticks). Each stick has two axes--x and y. An axis is a floating point number between -1 and 1, where 0 is the neutral resting position. The Gamepad API provides an array of four axes we can read.

const state = { x: 100, y: 100 };

const [p1] = navigator.getGamepads();

if (p1) {
  const [
    leftStickX, // -1 is left, 1 is right
    leftStickY, // -1 is up, 1 is down
    rightStickX,
    rightStickY,
  ] = p1.axes;
  state.x += leftStickX * dt;
  state.y += leftStickY * dt;
}

Here's another constant you can copy so you can refer to each axis by name rather than by index:

/**
 * Standard gamepad axis mappings using the HTML5 Gamepad API axis indices.
 * Axis values range from -1 to 1.
 */
export const Axis = {
  /** Left analog stick horizontal movement */
  LeftStickX: 0,
  /** Left analog stick vertical movement */
  LeftStickY: 1,
  /** Right analog stick horizontal movement */
  RightStickX: 2,
  /** Right analog stick vertical movement */
  RightStickY: 3,
} as const;

export type Axis = (typeof Axis)[keyof typeof Axis];

Thinking in terms of vectors

Despite reading the x and y axes separately, you'll typically want to think of them as forming a single vector together. To get the direction of the vector (in radians), use atan2(y, x). To get its magnitude use sqrt(x² + y²), which JavaScript conveniently has a built-in function for: Math.hypot(x, y).

const [p1] = navigator.getGamepads();

if (p1) {
  const [x, y] = p1.axes;
  const direction = Math.atan2(y, x);
  const magnitude = Math.hypot(x, y);
}

Deadzones

If you've ever experienced ghost movement from loose analog sticks, you know how frustrating it can be when deadzones are not properly accounted for. Most controllers have a tiny bit of drift in each axis when you release your thumbs from them. It's rare that they fully zero out.

To account for that, it's a good practice to ignore the first ~20% of movement. But what does it really mean to ignore those initial input values?

Axial normalization: The naïve approach ("axial normalization") simply lops off the first 20% of values on each axis. This can work if your game's movement is grid-based, but if you want to be able to freely rotate to any angle, you won't be able to. Axial normalization prevents you from hitting angles that are close to the horizontal and vertical axes, snapping you to straight lines when you approach them.

Radial normalization: Another option is to read both axes and normalize the combined vector ("radial normalization"). This preserves small angular changes and lets you rotate smoothly, but there is still a problem. It's still impossible to move very slowly or precisely since your speed jolts from 0 all the way up to 20% before being able to change smoothly.

Scaled radial normalization: To prevent the jolting behavior, treat 20% as the new zero, and scale the rest of the values from there.

For an excellent overview on deadzone normalization, I recommend Josh Sutphin's Doing Thumbstick Dead Zones Right. Carlos Pérez Ramil's interactive demo and deep dive article on deadzones are also well worth a visit!

Here's some drop-in code you can use in order to eliminate deadzones on two axes using scaled radial normalization:

export function normalizeRadialAxisValue(x: number, y: number, deadzone = 0.2) {
  const magnitude = Math.hypot(x, y);

  // ignore inputs below deadzone magnitude
  if (magnitude <= deadzone) {
    return { x: 0, y: 0 };
  }

  // scale the remaining magnitude
  const clampedMagnitude = Math.min(magnitude, 1);
  const normalized = (clampedMagnitude - deadzone) / (1 - deadzone);
  const scale = normalized / magnitude;
  return {
    x: x * scale,
    y: y * scale,
  };
}

function snapToRadian(x: number, y: number, numberOfSnaps: number, deadzone = 0.2) {
  const magnitude = Math.min(Math.hypot(x, y), 1);
  if (magnitude <= deadzone) return { x: 0, y: 0 };
  const angle = Math.atan2(y, x);
  const snapRadians = (Math.PI * 2) / numberOfSnaps;
  const snappedAngle = snapRadians * Math.round(angle / snapRadians);
  const normalizedMagnitude = (magnitude - deadzone) / (1 - deadzone);
  return {
    x: Math.cos(snappedAngle) * normalizedMagnitude,
    y: Math.sin(snappedAngle) * normalizedMagnitude,
  };
}

/**
 * snaps analog stick to 8 directions
 */
export function snap8(x: number, y: number, deadzone = 0.2) {
  return snapToRadian(x, y, 8, deadzone);
}

/**
 * snaps analog stick to 4 directions
 */
export function snap4(x: number, y: number, deadzone = 0.2) {
  return snapToRadian(x, y, 4, deadzone);
}

Using analog sticks to fire events

Sometimes you want an analog stick to behave more like the D-pad, like when you're using it to navigate menus. In other words, sometimes you want stick movement to produce one-shot events.

A simple implementation to address this might be to start with 4-way snapping and an activation threshold. You could have logic like: "if the stick is pointing to the right with a magnitude above 80%, move to the next menu item".

Polled state instead of events

Gamepads don't emit events for button presses or joystick movements. Instead, you have to poll a snapshot of their current state. Each time you call navigator.getGamepads() you read the latest state of every gamepad.

Because of that, if you want to know when a button was just pressed, you need to compare the latest snapshot against some game state from the previous frame.

const size = 30;
const groundY = bounds.height - 20;

const state = {
  wasJumpPressed: false,
  box: {
    x: 50,
    y: groundY - size,
    vy: 0, // y velocity in px/s
  },
};

That example only handled one gamepad (player 1) and one button press (Button.South at index 0). Can the approach be generalized to support all four gamepads and all 18 buttons? Yes!

In the next code example, previousButtons keeps one set of buttons for each of the four gamepad slots, and saveGamepadSnapshot() saves the current buttons at the end of each fixedUpdate(). This powers justPressed(gamepad: Gamepad, button: number), which allows you to react to any gamepad's button presses.

const state = {
  gamepad: {
    previousButtons: [
      new Set<number>(), // player 1
      new Set<number>(), // player 2
      new Set<number>(), // player 3
      new Set<number>(), // player 4
    ],
  },
};

function fixedUpdate() {
  for (const gamepad of navigator.getGamepads()) {
    if (!gamepad) continue;
    if (justPressed(gamepad, Button.South)) {
      // do one-shot action for this gamepad
    }
  }

  // save prev state after handling current inputs
  saveGamepadSnapshot();
}

function draw() {
  // draw the latest game state
}

// new helper functions:

function justPressed(gamepad: Gamepad, button: number) {
  const previousButtons = state.gamepad.previousButtons[gamepad.index];
  return gamepad.buttons[button].pressed && !previousButtons.has(button);
}

function saveGamepadSnapshot() {
  for (const previousButtons of state.gamepad.previousButtons) {
    previousButtons.clear();
  }

  for (const gamepad of navigator.getGamepads()) {
    if (!gamepad) continue;

    const previousButtons = state.gamepad.previousButtons[gamepad.index];

    for (const [button, buttonState] of gamepad.buttons.entries()) {
      if (buttonState.pressed) {
        previousButtons.add(button);
      }
    }
  }
}

Haptics

Most haptics-capable controllers expose low- and high-frequency rumble motors, and some also expose trigger vibration motors. The Gamepad API lets you control these with values like strongMagnitude, weakMagnitude, leftTrigger, and rightTrigger.

Dual-rumble

You can target both the low- and high-frequency palm haptic motors at once (or just one at a time) using the "dual-rumble" vibration effect:

const [p1] = navigator.getGamepads();

if (p1) {
  p1.vibrationActuator?.playEffect("dual-rumble", {
    duration: 200, // milliseconds
    weakMagnitude: 0.3, // 0-1
    strongMagnitude: 0.6, // 0-1
  });
}

Trigger-rumble

Haptics within each trigger can be activated using the "trigger-rumble" effect:

const [p1] = navigator.getGamepads();

if (p1) {
  p1.vibrationActuator?.playEffect("trigger-rumble", {
    duration: 200, // milliseconds
    leftTrigger: 0.5, // 0-1
    rightTrigger: 0.2, // 0-1
    // "trigger-rumble" also supports the strong and weak palm haptics
    weakMagnitude: 0, // 0-1
    strongMagnitude: 0, // 0-1
  });
}

Stack multiple haptic effects

For more convincing haptics, layer several effects that play back-to-back with different parameters. Combined with good sound design and visual effects like screen shake, well-implemented haptics can contribute a lot of juice to your game.

async function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function playEngineRev(gamepad: Gamepad) {
  // engine rev ramp up
  const weakRamp = [0.02, 0.05, 0.09, 0.15, 0.23, 0.34, 0.48, 0.65, 0.83, 1];
  for (const weak of weakRamp) {
    await gamepad.vibrationActuator?.playEffect("dual-rumble", {
      duration: 140,
      weakMagnitude: weak,
    });
  }

  // stay at redline peak for 200ms
  await gamepad.vibrationActuator?.playEffect("dual-rumble", {
    duration: 200,
    weakMagnitude: 1,
  });

  // begin stall
  await gamepad.vibrationActuator?.playEffect("dual-rumble", {
    duration: 100,
    strongMagnitude: 1,
    weakMagnitude: 0.8,
  });

  const stall = [
    { strong: 1, duration: 100, gap: 50 },
    { strong: 0.75, duration: 50, gap: 100 },
    { strong: 0.5, duration: 25, gap: 0 },
  ] as const;

  for (const step of stall) {
    await gamepad.vibrationActuator?.playEffect("dual-rumble", {
      duration: step.duration,
      strongMagnitude: step.strong,
    });
    await sleep(step.gap);
  }
}

for (const gamepad of navigator.getGamepads()) {
  if (!gamepad) continue;
  playEngineRev(gamepad);
}

See also