virtual-gamepad

Standardized virtual gamepad abstraction. All input sources (keyboard, hardware gamepad, XR controllers, touch) produce a VirtualGamepad, and each entity type defines an InputMapping that converts it to ControlInput. inputFocus and b3dController wire all of this for you; this page is for when you assemble it yourself.

Demo

import {
  gamepadSvg, TouchGamepadSource, KeyboardGamepadSource,
  HardwareGamepadSource, MappedInputProvider,
  bipedMapping, bipedMappingDescriptor,
  carMapping, carMappingDescriptor,
  aircraftMapping, aircraftMappingDescriptor,
} from 'tosijs-3d'
import { elements } from 'tosijs'
const { div, pre, select, option } = elements

const mappings = {
  biped: bipedMappingDescriptor,
  car: carMappingDescriptor,
  aircraft: aircraftMappingDescriptor(),
}

const pad = gamepadSvg()
const touchSource = new TouchGamepadSource(pad)
const keyboardSource = new KeyboardGamepadSource()
const hardwareSource = new HardwareGamepadSource()

const provider = new MappedInputProvider(
  mappings.biped.map, keyboardSource, hardwareSource, touchSource
)

touchSource.showLabels(mappings.biped.labels)

const readout = pre({ class: 'readout' })

const mappingSelect = select(
  { class: 'mapping-select' },
  option({ value: 'biped' }, 'Biped'),
  option({ value: 'car' }, 'Car'),
  option({ value: 'aircraft' }, 'Aircraft'),
)
mappingSelect.addEventListener('change', () => {
  const desc = mappings[mappingSelect.value]
  provider.setMapping(desc.map)
  touchSource.showLabels(desc.labels)
})

let lastTime = performance.now()
function update() {
  const now = performance.now()
  const dt = Math.min((now - lastTime) * 0.001, 0.1)
  lastTime = now

  const raw = provider.pollRaw()
  const input = provider.poll(dt)
  touchSource.reflectState(raw)

  const lines = []

  // Gamepad state
  const stickParts = []
  if (raw.leftStickX || raw.leftStickY)
    stickParts.push(`L: ${raw.leftStickX.toFixed(2)}, ${raw.leftStickY.toFixed(2)}`)
  if (raw.rightStickX || raw.rightStickY)
    stickParts.push(`R: ${raw.rightStickX.toFixed(2)}, ${raw.rightStickY.toFixed(2)}`)
  if (stickParts.length) lines.push(stickParts.join('  '))

  const btns = Object.keys(raw).filter(k =>
    !k.includes('Stick') && raw[k] > 0
  )
  if (btns.length) lines.push(btns.join(', '))

  // Mapped controls
  const controls = Object.entries(input)
    .filter(([, v]) => v !== 0)
    .map(([k, v]) => `${k}: ${typeof v === 'number' ? v.toFixed(2) : v}`)
  if (controls.length) lines.push(controls.join('  '))

  // Source status
  const hw = navigator.getGamepads?.()
  const hasGamepad = hw && Array.from(hw).some(g => g != null)
  lines.push(`keyboard: on  gamepad: ${hasGamepad ? 'on' : 'off'}`)

  readout.textContent = lines.join('\n') || 'Press WASD, plug in a gamepad, or touch the SVG'
  requestAnimationFrame(update)
}
update()

preview.append(div(
  { class: 'vgp-demo' },
  keyboardSource,
  pad,
  div({ class: 'vgp-controls' }, mappingSelect, readout),
))
.vgp-demo {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
}
.vgp-demo svg {
  width: 50%;
  max-height: 50%;
  cursor: pointer;
}
.vgp-controls {
  display: flex;
  flex-direction: column;
  gap: 4px;
  width: 100%;
  max-width: 400px;
}
.vgp-demo .mapping-select {
  padding: 4px;
  font-size: 13px;
  border-radius: 4px;
}
.vgp-demo .readout {
  font-family: ui-monospace, monospace;
  font-size: 11px;
  color: #222;
  min-height: 4em;
  margin: 0;
  white-space: pre-wrap;
}
.vgp-demo [data-part].active {
  stroke-width: 24;
  filter: brightness(1.3);
}
.vgp-demo .mapping-label {
  font-size: 18px;
  fill: #000;
  opacity: 0.7;
  pointer-events: none;
}

Try the controls above — press WASD, plug in a gamepad, or touch the SVG. All sources merge and drive the same readout.

How to wire up controls

  1. Pick a mapping — it translates gamepad buttons/sticks to game actions like move, jump, accelerate. Use a built-in preset or write your own.
  2. Create a MappedInputProvider with your mapping and any input sources (keyboard, hardware gamepad, touch overlay).
  3. Assign it to your entity — done.

Every input source produces a standardized VirtualGamepad. The provider merges them all (max-abs for sticks, max for buttons) and runs your mapping. Plug in a gamepad mid-game, touch the SVG overlay, or enter XR — it all composes automatically.

const provider = new MappedInputProvider(
  bipedMapping,          // how gamepad maps to player actions
  keyboardSource,        // WASD/Space/etc.
  hardwareSource,        // any connected gamepad
  touchSource,           // SVG touch overlay
)
entity.inputProvider = provider

VirtualGamepad

Two sticks + buttons, matching a standard controller layout:

Field Range Maps to
leftStickX/Y -1..1 Primary movement (WASD on keyboard)
rightStickX/Y -1..1 Secondary control (arrow keys on keyboard)
buttonA/B/X/Y 0..1 Face buttons (Space, F, E, etc.)
leftBumper/rightBumper 0..1 Bumpers (Shift, etc.)
leftTrigger/rightTrigger 0..1 Triggers (Q/R on keyboard)
dpadUp/Down/Left/Right 0..1 D-pad
menu, view 0..1 Menu (start) and view (select) buttons
leftStickPress/rightStickPress 0..1 Pressing a stick in (L3, R3)

InputMapping

A function (pad, dt) => ControlInput that maps gamepad state to entity-specific controls. Can be a closure with persistent state (e.g. throttle accumulator for aircraft).

Built-in presets: bipedMapping, carMapping, aircraftMapping().

Each preset has a matching descriptor (e.g. bipedMappingDescriptor) that pairs the mapping function with human-readable labels for UI visualizers:

bipedMappingDescriptor.labels
// { leftStickY: 'move', buttonA: 'attack', buttonB: 'use / duck', rightStickPress: 'jump', ... }

MappedInputProvider

Bridges gamepad sources to the InputProvider interface. Merges multiple sources, runs through the active mapping, produces ControlInput.

Sources

Keyboard and mouse

KeyboardGamepadSource (element creator keyboardGamepad()) turns keys and the mouse into a VirtualGamepad, with attack/decay smoothing so digital keys feel analog. It is an element: append it to the page (as the demo does) so it listens.

VirtualGamepad Keys
leftStick Y W (+) / S (-)
leftStick X D (+) / A (-)
rightStick Y ArrowUp (+) / ArrowDown (-) — LOOK, not zoom
rightStick X ArrowRight (+) / ArrowLeft (-)
buttonA Space
buttonB F
buttonX E
leftBumper ShiftLeft
leftTrigger Q
rightTrigger R
buttonY Y
rightBumper ShiftRight
dpadUp/Down/Left/Right I / M / J / K

The mouse wheel adjusts the ZOOM axis (d-pad up/down), not the look stick.

Hardware gamepad

new HardwareGamepadSource({ deadzone, gamepadIndex }) reads navigator.getGamepads() with the Standard Gamepad layout (axes 0-3, buttons 0-16). deadzone (default 0.15) filters stick drift; gamepadIndex -1 (default) takes the first connected pad.

XR controllers

new XrGamepadSource(xrControllers(xrHelper)) adapts the live XR controllers, so whatever a mapping does flat it does in VR, with no per-entity XR code. Standard xr-standard-* mappings (Quest / oculus-touch layout):

VirtualGamepad XR component
leftStickX/Y, rightStickX/Y xr-standard-thumbstick (Y inverted: up = +)
leftTrigger, rightTrigger xr-standard-trigger
leftBumper, rightBumper xr-standard-squeeze (grip)
buttonA, buttonB right a-button, b-button
buttonX, buttonY left x-button, y-button
leftStickPress, rightStickPress pressing xr-standard-thumbstick

Touch

TouchGamepadSource reads an on-screen SVG pad; see touch-gamepad and the glass gamepad.

Drawing a pad

gamepadSvg(colors?) draws the controller used in the demo. Its parts carry data-part attributes (not ids), so several can be on one page.

import { gamepadSvg } from 'tosijs-3d'

const pad = gamepadSvg() // default colours
const dark = gamepadSvg({ controllerColor: '#333', widgetColor: '#888' })
Colour Default Used by
strokeColor #000000 All stroked elements
strokeWidth 16 All stroked elements
widgetColor #ffffff Bumpers, triggers, dpad, sticks, menu, view
controllerColor #aaaaaa Controller body
stickTravelColor #505050 Stick travel circles
fillA #ff1d25 A button (red)
fillB #fcee22 B button (yellow)
fillX #8cc63f X button (green)
fillY #3ea9f5 Y button (blue)

Keys and text fields

The keyboard source listens on window, so you steer without clicking the canvas first. A page also has search boxes and forms, so every global key listener here first asks isTextEntry(event): is the person typing into something? If so the key is left alone. It is a question asked of the event rather than a mode, so it cannot go stale and covers elements nobody planned for.

What counts: <input> (except button-like ones such as checkboxes), <textarea>, <select>, anything contenteditable, and anything with a textbox/searchbox/combobox role. It checks composedPath first, so an input inside a shadow root is recognised.

import { isTextEntry } from 'tosijs-3d'

window.addEventListener('keydown', (event) => {
  if (isTextEntry(event)) return // the person is typing
  // ...your shortcut
})