gamepad

Vibedgames Gamepad

Add on-screen touch controls — a floating analog joystick plus action buttons — and physical controller input 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 (custom event routing / custom renderers only) and PhysicalGamepad

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.
• update() once per frame is mandatory (either adapter). It reconciles touches whose up was lost (finger slid off-canvas) and publishes justPressed/justReleased edges. Skip it and the joystick sticks on.
• Held vs edge: movement and continuous fire read isButtonDown(id) / getStick() each frame; one-shot actions (bomb, jump) use onButtonDown(id) or justPressed(id) after update().