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
- Pick a mapping — it translates gamepad buttons/sticks to game actions like
move,jump,accelerate. Use a built-in preset or write your own. - Create a
MappedInputProviderwith your mapping and any input sources (keyboard, hardware gamepad, touch overlay). - 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.
addSource(source)/removeSource(source)— hot-swap input devicessetMapping(mapping)— switch mappings at runtime (e.g. entering a vehicle)pollRaw()— get the mergedVirtualGamepadbefore mapping (for visualizers)
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
})