gamepad

Vibedgames Gamepad

Add on-screen touch controls — a floating analog joystick plus action buttons — to any browser game with @vibedgames/gamepad. Framework-agnostic core, with drop-in adapters that wire the input and render the overlay for you: one for Phaser, one for the DOM (Three.js, canvas, anything else).

Install

npm install @vibedgames/gamepad

phaser is an optional peer dependency — only needed if you use the /phaser adapter. The core and /dom adapter have no engine dependency.

Three entry points

• @vibedgames/gamepad/phaser — attachVirtualGamepad(scene, options) for Phaser games
• @vibedgames/gamepad/dom — attachDomGamepad(options) for everything else (Three.js, canvas, vanilla). Prefer this over the raw core.
• @vibedgames/gamepad — framework-agnostic VirtualGamepad class, for custom event routing / custom renderers only

Core concepts

• Floating stick — the first free touch anchors a virtual analog stick wherever the finger lands; dragging from the anchor steers. Reads back as angle + magnitude (0–1 thrust after a dead zone).
• Action buttons — either fixed (a circle pinned on-screen, e.g. a bottom-right bomb/jump button) or "rest" (no position — catches any touch that isn't the stick or a fixed button; this is the "any second finger fires" model).
• Touch is the overlay. The adapter ignores the mouse, so a desktop game keeps whatever controls it already had. isTouch flips true the first time a finger lands — use it to switch control schemes or swap an on-screen hint.

Touch routing

Each touch-down is routed in order: fixed buttons → the stick → a "rest" button. This one model covers both common layouts — a stick + rest "fire" button (twin-stick: move one thumb, any other finger fires), and a stick + fixed action button (grid/platformer: move with the stick, tap to bomb/jump). Both are shown below.

Phaser quickstart (twin-stick shooter)

import { attachVirtualGamepad } from "@vibedgames/gamepad/phaser";

class GameScene extends Phaser.Scene {
  private gamepad!: ReturnType<typeof attachVirtualGamepad>;

  create() {
    this.gamepad = attachVirtualGamepad(this, {
      buttons: [{ id: "fire" }], // rest button: any non-stick finger fires
      onFirstTouch: () => this.hint?.destroy(),
    });
    this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => this.gamepad.destroy());
  }

  update() {
    this.gamepad.update(); // ALWAYS call once per frame: reconciles + redraws

    const stick = this.gamepad.getStick();
    if (stick.active && !stick.inDeadZone) {
      this.steer(stick.angle, stick.magnitude); // radians, 0–1
    }
    if (this.gamepad.isButtonDown("fire")) this.shoot();
  }
}