b3d-panel
A declarative spatial-UI panel you drop into the scene as a child of <tosi-b3d>,
instead of hard-wiring panels in code. It anchors to an
XR reference frame via frame-panel, tuned with
plain attributes. By default it is VR-only; presence: 'both' also puts it
in the flat view, where the frames follow the flat camera — ONE panel, placed
relative to the viewer in both, rather than a flat overlay plus a VR panel to keep
in step. The hand frames have no flat analogue, so a hand panel
names its flat home with flatFrame.
Demo
import { b3d, b3dPanel, b3dSvgPlane, b3dLight, b3dSkybox, b3dGround, b3dBox, label3d, slider3d } from 'tosijs-3d'
import { tosi } from 'tosijs'
const { cfg } = tosi({ cfg: { height: 1 } })
const scene = b3d(
{
// Start with the flat panel open so it's visible without hunting for the owl.
scenePanelOpen: true,
panelTitle: 'Settings',
// DUAL-PRESENCE: one settings panel, flat and in VR, same values.
scenePanel: () => [
slider3d({ label: 'cube height', value: cfg.height, min: 0.5, max: 3, step: 0.1 }),
],
},
b3dLight({ y: 1, intensity: 0.8 }),
b3dSkybox({ timeOfDay: 12 }),
b3dGround({ width: 20, height: 20, texture: 'checker', textureTiles: 10 }),
// `axes` pins a debug XYZ READOUT on any AbstractMesh geometry (glowing R/G/B).
// It shows you an orientation; it is NOT a handle — there is nothing to grab
// and nothing happens if you try. (It reads as Babylon's position gizmo,
// which is a manipulator: for one you can grab, see b3d-manipulator.)
b3dBox({ meshName: 'cube', size: 1, y: cfg.height, color: '#39c5ff', axes: true }),
// BOTH flat + VR: a world-anchored SVG panel — it IS a mesh in the scene, so it
// shows in the regular view and in VR, always in the same spot.
b3dSvgPlane({ url: '/tosi-test-pattern.svg', x: -2.6, y: 1.6, z: 0, width: 1.6, height: 1.6 }),
// VR-ONLY: a <tosi-b3d-panel> anchored to the eye frame. No flat presence.
b3dPanel({ frame: 'eye', azimuth: 45, elevation: 25, title: 'VR only', width: 0.4, reveal: 'always' }),
// BOTH: the same kind of panel, viewer-relative in the flat view too. The
// eye frame is LEVEL (it takes the view's yaw, not its pitch), and this orbit
// camera looks down ~30°, so -38° lands it low in the view.
b3dPanel({ frame: 'eye', azimuth: 16, elevation: -38, distance: 1.4, title: 'Flat + VR', width: 0.22, reveal: 'always', presence: 'both' }),
)
preview.append(scene)
tosi-b3d { width: 100%; height: 100%; }
Four ways to show a panel, side by side. The world panel (a b3d-svg-plane) is
a mesh in the scene — it renders in the regular flat view AND in VR, fixed in the
world. The Settings panel (the scenePanel hook) is dual-presence: the owl on
the system bar (top left) opens it in the scene, flat and in VR alike — its slider
drives the cube in both. The VR only panel (<tosi-b3d-panel>) has no flat presence — enter VR to see
it anchored to your view. The Flat + VR panel is the same element with
presence: 'both': viewer-relative on the monitor AND in the headset, one panel.
The coloured axes are a readout, not a manipulator. They show the cube's orientation. To place something by dragging, use b3d-manipulator.
On the system bar
Give a panel an icon and a title, and put what it shows inside it: it gets a button on the scene's system bar and opens under the bar with a title bar of its own (move, its title, ×), flat and in a headset. Drag it by that bar and it reopens where you left it; hold its button to put it back. Nothing else to wire.
import { b3d, b3dPanel, b3dLight, b3dGround, panel3d, label3d, slider3d, button3d } from 'tosijs-3d'
import { tosi } from 'tosijs'
const { nav } = tosi({ nav: { zoom: 2 } })
// No content: a card with its title. `attention()` blinks its button.
const journal = b3dPanel({ icon: 'book', title: 'Journal' })
preview.append(
b3d(
{},
b3dLight({ intensity: 1 }),
b3dGround({ width: 20, height: 20, texture: 'checker', textureTiles: 10 }),
b3dPanel(
{ icon: 'map', title: 'Map' },
panel3d(
{ width: 300 },
label3d({ text: 'Nowhere in particular' }),
slider3d({ label: 'zoom', value: nav.zoom, min: 1, max: 5, step: 0.5 }),
button3d({ label: 'New journal entry', handleClick: () => journal.attention() })
)
),
journal
)
)
The same in HTML; the <svg> inside is what it shows:
<tosi-b3d>
<tosi-b3d-panel icon="compass" title="Heading">
<svg viewBox="0 0 240 120">
<text x="120" y="70" fill="#cfe0ff" font-size="32" text-anchor="middle">N 12°</text>
</svg>
</tosi-b3d-panel>
</tosi-b3d>
Content that takes the pointer has a handlePointer(kind, x, y) (a
panel3d does). A panel with a preset or a position is pinned instead (see
Pins); chrome="none" leaves off the title bar, for content with its own.
Pins: named places on your body
The rig has named places a panel can be pinned to, around you in a headset:
left-shoulder and right-shoulder (45° up, 60° to each side),
overhead (60° up), waist (45° down, facing up at you) and
wrist (on the left hand). Each is revealed by looking toward it. None
come filled: they are for your game's panels (a map, a journal, a radio).
Here each one holds a card with its name; enter VR and look around.
Not a pin: a panel with an icon (and no preset) goes on the system bar
instead; see above. That is where an inventory goes.
import { b3d, b3dPanel, b3dLight, b3dSkybox, b3dGround } from 'tosijs-3d'
preview.append(
b3d(
{},
b3dLight({ y: 1, intensity: 0.8 }),
b3dSkybox({ timeOfDay: 12 }),
b3dGround({ width: 20, height: 20, texture: 'checker', textureTiles: 10 }),
// One card per pin, named for it (pins are around you: a headset's).
b3dPanel({ frame: 'eye', preset: 'left-shoulder', title: 'left-shoulder' }),
b3dPanel({ frame: 'eye', preset: 'right-shoulder', title: 'right-shoulder' }),
b3dPanel({ frame: 'eye', preset: 'overhead', title: 'overhead' }),
b3dPanel({ frame: 'eye', preset: 'waist', title: 'waist' }),
b3dPanel({ frame: 'left-hand', preset: 'wrist', title: 'wrist', width: 0.09 }),
)
)
tosi-b3d { width: 100%; height: 100%; }
An app's chrome: several open at once
An editor's tools are several panels used together, not one at a time.
exclusive="off" lets a system panel stay open beside the others, open
opens it when the scene starts, and its screenAnchor is where it first
appears (drag one and it reopens where you left it; hold its button to put it
back). In a headset the same panels follow you in, left column left, right
column right. An exclusive panel (the settings panel, an inventory) still
opens and closes over them without closing them.
import { b3d, b3dPanel, b3dLight, b3dSkybox, b3dGround, panel3d, label3d, slider3d, ui } from 'tosijs-3d'
import { tosi } from 'tosijs'
const { editor } = tosi({ editor: { size: 1, name: 'crate' } })
// One app panel: open at start, pinned flat to a side of the screen.
const chrome = (icon, title, screenAnchor, ...widgets) => {
const el = b3dPanel({ icon, title, exclusive: 'off', open: true })
el.screenAnchor = screenAnchor
el.svg = panel3d({ width: 220 }, ...widgets)
return el
}
preview.append(
b3d(
{},
b3dLight({ y: 1, intensity: 0.8 }),
b3dSkybox({ timeOfDay: 12 }),
b3dGround({ width: 20, height: 20, texture: 'checker', textureTiles: 10 }),
chrome('mousePointer', 'Tools', { left: 8, top: 66 }, label3d({ text: 'select · move · rotate' })),
chrome('menu', 'Pieces', { left: 8, top: 190 }, label3d({ text: 'crate' }), label3d({ text: 'barrel' })),
chrome('settings', 'Options', { right: 8, top: 66 }, slider3d({ label: 'size', value: editor.size, min: 0.5, max: 4 })),
chrome('checkSquare', 'Properties', { right: 8, top: 190 }, ui.inputField({ value: editor.name.value, handleChange: (v) => (editor.name.value = v) })),
)
)
tosi-b3d { width: 100%; height: 100%; }
Three ways to place a panel
- World-anchored (
b3d-svg-plane) — a panel that IS a mesh in the scene: visible in flat 3D and VR, fixed in the world. Use for holograms, signage, in-world screens. - Dual-presence (
scenePanelhook) — one panel, opened by the owl on the system bar, drawn in the scene flat and in VR, bound to the same reactive values. Use for settings/controls you want everywhere. - Viewer-frame-anchored (
<tosi-b3d-panel>, VR-only) — anchored to an XR reference frame (eye/body/left-hand/…); follows you. By default it exists only in a session;presence: 'both'shows it flat too, and aniconmakes it a system panel (a button on the system bar, flat and in VR). Use for HUDs, wrist menus, over-the-shoulder inventory.
The <tosi-b3d-panel> children are the set (none ship by default):
<tosi-b3d gamepad>
<tosi-b3d-panel frame="eye" azimuth="-60" elevation="45" title="Inventory"></tosi-b3d-panel>
<tosi-b3d-panel frame="eye" azimuth="0" elevation="-45" title="Quick Access"></tosi-b3d-panel>
<tosi-b3d-panel frame="face" position="0 0 2" reveal="always" blend="add" view="first" url="/reticle.svg" width="0.24"></tosi-b3d-panel>
<tosi-b3d-panel frame="left-hand" preset="wrist" title="Menu" width="0.09"></tosi-b3d-panel>
</tosi-b3d>
Attributes
| Attribute | Default | Description |
|---|---|---|
frame |
eye |
eye / rig / world / body / neck / face / left-hand / right-hand |
preset |
'' |
A named pin (waist, left-shoulder, right-shoulder, overhead, wrist; see Pins), overriding the angular fields. system-bar puts it on the system bar, which an icon with no preset already does |
azimuth / elevation |
0 / 0 |
Degrees off the frame's eye: +az right, +el up |
distance |
1.4 |
Metres from the eye |
position |
'' |
Explicit "x y z" local position (overrides az/el/distance) |
roll |
0 |
Roll about the panel normal (deg) |
reveal |
gaze |
gaze (look toward it) or always |
blend |
composite |
composite or add (additive HUD glyphs) |
view |
both |
first / third / both — restrict to a camera view |
title |
'' |
Placeholder card title (ignored if url set) |
icon |
'' |
Puts it on the scene's system bar: its button's picture, an svgIcons name (e.g. personStanding, book, map); unknown draws a square. Its title is the button's tooltip and the panel's caption |
exclusive |
'on' |
On the system bar: one system panel is open at a time. 'off' lets this one stay open beside the others and leaves them open when it opens (an app's main chrome: a tool palette, a properties panel). The settings panel and exclusive panels still close each other |
bar-button |
'on' |
On the system bar: 'off' gives it no button there, for a panel something else opens (a menu entry calling el.show()). It still opens under the bar like the others |
open |
false |
On the system bar: open when the scene starts (and again in a headset, if it was open flat). To open or close it later, el.show() / el.hide() |
chrome |
'' |
On the system bar: the panel opens with the settings panel's title bar (move, its title, ×; flat, a drag moves it and it reopens where you left it; holding its button on the bar puts it back). 'none' for content with chrome of its own |
url |
'' |
SVG URL (e.g. a reticle) |
width |
0.26 |
Panel width (m); height follows aspect |
reveal-start / reveal-full |
50 / 25 |
Gaze half-angles (deg) where the reveal begins / completes |
max-distance |
0 |
Hide beyond this distance (m); 0 = no limit |
presence |
'xr' |
'xr' — only in an immersive session; 'both' — also in the flat view, on frames derived from the flat camera |
flat-frame |
'' |
The frame to use in the FLAT view, required for a hand panel (a monitor has no hands): e.g. face with a position at the screen edge. 'face' measures elevation from the view instead of the horizon, so a menu stays centred under a pitched camera. Without one a hand panel stays VR-only and warns once |
resolution |
0 |
Texture size in px (square); 0 = 384. Raise it for a menu with text |
layer |
'world' |
'ui': drawn over the whole world and pressed first, never hidden by a nearer wall (what a page overlay is flat); 'modal': over even the ui (pause, a dialog). 'world': in the scene like anything else. The same in a headset: the controller's ray picks modal, then ui, then the world |
Properties, methods and events
Five more are JavaScript properties, not attributes, because they are
objects: svg (live content, in place of an <svg> child: an <svg> whose own handlePointer(kind, x, y)
gets the panel's pointer, such as an inventoryDock's), screenAnchor (flat, pinned to the screen's edges in pixels, % or vmin: { left: '2vmin', top: '2vmin' }; for a system panel, where it first opens, before it is dragged, and in a headset which side it goes), flatAnchor (where
it goes in the flat view instead), focusAnchor and focusScale (where it
comes, and how much bigger, when its content asks for focus with a
panelfocus event). A system-bar panel with no svg opens a card with its title.
Rebuilt content goes back on the same element. A system panel is the
<tosi-b3d-panel>, not its content: set el.svg = next and an open panel
shows next where it is, with the same button, spot and open state, refitted
to the new height (a closed one shows it next time). Dispose the content you
dropped yourself. The setter fires a bubbling panelcontent event.
A host can stack its panels. Until someone drags a system panel by its
title bar, its spot is its screenAnchor, so setting a new one moves an open
panel (a column re-stacked as a panel above it grows). Once dragged it stays
where it was put, until its button is held on the bar.
A game can open, close and flag one. el.show(), el.hide() and
el.toggle() open and close a system panel as its button does, and
el.isOpen says which it is. el.attention() blinks its button on the bar,
flat and in a headset, for a moment (pass milliseconds for longer): an
objective met while the list was closed. A paneltoggle event (detail.open)
fires on the element whenever it opens or closes, by code or by a press, so a
list can put itself away a while after it opened:
let away
objectives.addEventListener('paneltoggle', (e) => {
clearTimeout(away)
if (e.detail.open) away = setTimeout(() => objectives.hide(), 8000)
})
game.on('objective', () => objectives.attention())
Who opened it matters. A panel the person opens with its button is one
they are looking at, so the glass gamepad gets out of the way. A panel opened
by code (show(), open) is up while they play, so the pad stays: give one
that stays open in play a screenAnchor clear of the pad's controls.
Every open and close is reported, and the game decides what it means. The
scene fires systempanels with detail.panel (the one that changed),
detail.shown, detail.byUser (opened by its button) and detail.open (every
open one, { panel, byUser }); paneltoggle on the panel carries open and
byUser. To pause while the person has one up:
scene.addEventListener('systempanels', (e) => {
game.paused = e.detail.open.some((p) => p.byUser)
})
A headset session starting or ending closes and reopens the shared panels;
that is reported once, when it is over, with detail.panel null.
Clicking one from a test. The content is drawn on a texture, so nothing in
it has a box on the page. el.contentToClient(x, y) says where a point of the
content (its viewBox units) is in client pixels, through the drawn plane, so a
drag, a scale and the title bar are all accounted for; el.clientRect() is
the content's box. Both are null unless the panel is open and flat.