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.