Billboard

For a health bar over an entity, put <ResourceBar resource={healthResource}> in an anchored Panel, as the Health page shows. That bar reads the entity’s health itself, shows each hit as it lands, and takes the theme’s colours. A nameplate, a label or a button goes in an anchored Panel too.

<Billboard> turns what it holds to face the camera, however the entity it sits in turns. Put it inside an entity’s view, and put meshes inside it, such as a marker over a quest giver. A marker seen from the side of its entity still shows square on, not as a line.

Its props are in BillboardProps, and its units in BillboardUnits.

The following marker is a yellow diamond over the entity’s head. The engine’s tests mount it and check that it faces the camera:

packages/engine/test/outside/QuestMarker.tsx

import { Billboard } from "@spawnite/engine";

export function QuestMarker() {
    return (
        <Billboard offset={[0, 2.4, 0]} maxDistance={40} fade={10}>
            <mesh name="marker" rotation={[0, 0, Math.PI / 4]} scale={0.4}>
                <planeGeometry />
                <meshBasicMaterial color="#ffd166" />
            </mesh>
        </Billboard>
    );
}

Where it stands

offset is the metres from the entity’s origin to the billboard’s middle, in the entity’s own axes: [0, 2.2, 0] stands it 2.2 metres over the entity’s feet. It is [0, 0, 0] unless set.

How big it draws

units says what its children measure in:

• BillboardUnits.Metres, the default: a unit is a metre, so the billboard shrinks on the screen as the camera draws away, as a sign in the world does.
• BillboardUnits.Pixels: a unit is one CSS pixel on the screen at any distance, so a bar 80 units wide is 80 pixels wide up close and far off.

A billboard in pixels expects the entity it sits in to be scaled alike on every axis, as an entity is. Under a turned parent stretched on one axis, what it holds draws skewed.

Hiding it far off

maxDistance hides the billboard farther than that many metres from the camera. It has no limit unless set. fade fades it out over that many metres before maxDistance, rather than all at once. The fade writes the opacity of each material under the billboard, so give a faded billboard materials of its own: a material it shares with other meshes fades them too.

Text and controls

A billboard holds meshes, drawn in the scene. For text, a button, a Bar or a health bar drawn as HTML, an anchored Panel follows the entity and always faces the screen.

What the other engines do

drei’s <Billboard> turns a group to the camera’s world rotation less its parent’s each frame, as this one does, with no size mode and no distance limit. Roblox’s BillboardGui stands at an offset from its part, sizes in studs or in pixels, and hides past MaxDistance; this component takes those three props from it, and adds a fade. Godot’s Sprite3D and Label3D take a billboard mode and fixed_size. A Unity game writes a LookAt script. Unreal draws a widget component in screen or world space.

Where it runs

Client. It turns its children each frame on the page that draws them. Headless, it mounts its children, and nothing draws them.