Hud

<Hud> marks UI for the screen. Put one at any level: inside Game, a Scene, a World or an Entity. The engine draws what it holds into the screen layer that Game owns, over the canvas.

A Hud inside the world renders under three’s reconciler, where HTML cannot draw. The Hud carries its children out to the screen layer, and they keep every context around it. So useEntity() inside a Hud reads the Entity the Hud sits in, and the Hud’s UI lives as long as that entity.

A Hud holds Panels. Each Panel names the slot it stands in.

import { Hud, Panel, Slot, Text, useEntity } from "@daniel-zarinski/engine";

export function Scoreboard() {
    const entity = useEntity();

    return (
        <Hud>
            <Panel slot={Slot.TopLeft}>
                <Text>Entity {entity.id()}</Text>
            </Panel>
        </Hud>
    );
}

The screen layer

Game draws the screen layer after its canvas and isolates the canvas, so the screen layer always draws over the world, including over a nameplate. The layer takes no pointer events itself: only a control such as a Button takes one, so a drag that starts between two buttons still turns the camera.

The layer keeps clear of the screen’s edges by four CSS variables, --game-inset-top, --game-inset-right, --game-inset-bottom and --game-inset-left. Each defaults to the device’s safe area. The app sets them to keep the slots clear of its own controls; see the trust boundary.