glass-gamepad (b3dGamepad)
A split on-screen ("glass") gamepad for touch contexts, as a Component (so
it's both the overlay element and a virtual-gamepad GamepadSource, like
gameController/keyboardGamepad). It is laid out like a pair of VR
controllers held flat, in three clusters pinned along the bottom of the view:
| Cluster | Anchor | Controls |
|---|---|---|
left |
bottom-left | left trigger and bumper, left stick and its click, X, Y |
right |
bottom-right | right trigger and bumper, right stick and its click, A, B |
center |
bottom-center | view, menu, and the d-pad when you ask for it |
The face buttons wear Xbox colours (A green, B red, X blue, Y yellow) in a Quest controller's places. Under each stick is its click (L3, R3): on glass a press on the stick itself cannot be told from the start of a drag, so the click is its own button.
The d-pad is hidden unless you name it (controls="…,dpad"). View and
menu are shown by default for now; they will become opt-in in a future
release, so name them if your scene uses them. Named, they also appear on
the system bar in a headset, where the controllers have no view or menu button
(a thumbstick click is a stick press).
The art is one sheet (static/glass-gamepad.svg, built into the library), and the pad
cuts it into the clusters, each cropped to what it shows plus each stick's full
reach. Its paths are labelled by id (copied to data-part on load). When the
three do not fit side by side (a d-pad on a phone in portrait), the centre
cluster sits above the others.
Usually you don't place this yourself: set the gamepad attribute on
tosi-b3d and it mounts one and wires it into the active input system. Placed
directly, it's a GamepadSource whose poll() merges all clusters.
import { b3d, b3dGamepad, b3dSkybox } from 'tosijs-3d'
import { demoSun, patternGround } from 'tosijs-3d/demo-utils'
import { elements } from 'tosijs'
const { div, pre } = elements
// fade OFF in the demo: this page is where you LOOK at the pad, and any
// keypress (a doc search, a scroll with the arrow keys) would fade it out
// mid-inspection. Pointer movement never fades it.
const pad = b3dGamepad({ fade: 'off' })
const readout = pre({ class: 'readout' })
let rover, mat
const scene = b3d(
{
sceneCreated(el, BABYLON) {
// FIXED view (no attachControl) so the pad owns every pointer — you drag a stick, not the
// camera. This is the rare demo where a hand-rolled camera is right: the pad is the subject.
const cam = new BABYLON.ArcRotateCamera('cam', -Math.PI / 2, Math.PI / 3.4, 13, new BABYLON.Vector3(0, 0.6, 0), el.scene)
el.setActiveCamera(cam)
rover = BABYLON.MeshBuilder.CreateBox('rover', { width: 1.4, height: 0.8, depth: 1.4 }, el.scene)
rover.position.y = 0.5
mat = new BABYLON.StandardMaterial('rover-mat', el.scene)
mat.diffuseColor = new BABYLON.Color3(0.35, 0.6, 0.95)
rover.material = mat
el.register?.({ meshes: [rover] }) // cast a shadow
el.scene.registerBeforeRender(() => {
const s = pad.poll()
// left stick drives it around; right stick spins it; A hops; B/X/Y recolour it.
rover.position.x = Math.max(-9, Math.min(9, rover.position.x + s.leftStickX * 0.12))
rover.position.z = Math.max(-9, Math.min(9, rover.position.z + s.leftStickY * 0.12))
rover.rotation.y += s.rightStickX * 0.06
const lift = s.buttonA > 0.5 ? 1.7 : 0.5
rover.position.y += (lift - rover.position.y) * 0.2
if (s.buttonB > 0.5) mat.diffuseColor.set(0.95, 0.4, 0.35)
else if (s.buttonX > 0.5) mat.diffuseColor.set(0.4, 0.9, 0.55)
else if (s.buttonY > 0.5) mat.diffuseColor.set(0.95, 0.85, 0.35)
const held = ['A', 'B', 'X', 'Y'].filter((b) => s['button' + b] > 0.5)
readout.textContent =
`L ${s.leftStickX.toFixed(2)},${s.leftStickY.toFixed(2)} R ${s.rightStickX.toFixed(2)},${s.rightStickY.toFixed(2)}` +
(held.length ? ' ' + held.join(' ') : '')
})
},
},
demoSun(),
b3dSkybox({ timeOfDay: 11 }),
patternGround({ size: 22 }),
// INSIDE the scene, as `gamepad: true` mounts it, so it goes full screen
// with it (a pad beside the scene is left behind).
pad,
)
// The pad's clusters sit OVER the scene: touch/drag them to drive the cube.
preview.append(div({ class: 'glass-stage' }, scene), readout)
.preview { display: flex; flex-direction: column; height: 100%; }
.glass-stage {
position: relative;
flex: 1;
min-height: 0;
background: #0b0f14;
border-radius: 8px;
overflow: hidden;
}
.glass-stage tosi-b3d,
.glass-stage tosi-b3d-gamepad {
position: absolute;
inset: 0;
}
.readout {
margin: 0;
padding: 4px 8px;
background: #222;
border-radius: 5px;
font-family: ui-monospace, monospace;
font-size: 12px;
color: #fff;
white-space: pre;
pointer-events: none;
}
Attributes
| Attribute | Default | Purpose |
|---|---|---|
controls |
'' (all but the d-pad) |
Comma-separated piece list, e.g. 'a,b,right_stick(40,0),menu'. Empty (the default) shows everything except the d-pad. a/b/x/y map to A/B/X/Y; dpad expands to the four directions; the clicks are left_stick_click and right_stick_click; name(dx,dy) nudges one piece. Naming view or menu also puts them on the headset's system bar |
scale |
1 |
Size multiplier for every cluster |
deadzone |
0.15 |
Stick travel (fraction of the radius) ignored at the centre |
maxZone |
0.85 |
Stick travel that counts as full deflection, so you need not reach the rim |
fade |
'on' |
Hide the pad once a real input device is in use. 'off' pins it visible — what you want on a page where the pad itself is the subject |
idleSeconds |
10 |
Seconds of silence before a faded pad comes back |
fadedOpacity |
0 |
How faded is faded. 0 is invisible; a low value like 0.15 leaves a hint that the fallback exists |
What fading listens to, and what it ignores
Only a keypress or a physical gamepad fades the pad. The pointer never does — not touch, not mouse, not trackpad.
That is a deliberate asymmetry rather than an oversight. The pad is operable by
pointer: pointerdown drives the sticks. Fading on pointer movement would make it
vanish exactly as you reached for it. A keypress is the honest signal, because it is the one
that actually implies an on-screen fallback isn't needed.
If the pad is disappearing on you during development, fade="off" (or
setFade(false)) pins it; faded reports the current state.
Getting out of the way of a menu
The pad sits over the canvas, so a menu drawn in the scene would be under it
and a button beneath a stick could not be pressed. The pad therefore steps
aside by itself while the scene is paused, while a death panel is up and
while a modal popup (openPopup({ modal: true })) is open. That reaches a pad
inside the scene element (where gamepad: true puts it) or directly beside
it. For any other menu of your own, say so on the pad you mounted:
// `pad` is your b3dGamepad(), or scene.querySelector('tosi-b3d-gamepad')
// when `gamepad: true` mounted it for you.
pad.suppress('shop') // gone, and it reports no input
pad.release('shop') // back, unless something else still holds it
Each caller names its own reason, so two menus cannot release each other's
hold. This is separate from the fade: setFade is about a real keyboard or
controller being in use. There is no switch to keep the pad up over a paused
scene; if you need one, call release('pause') from a pause listener.