Appearance
Labels
Labels is a plugin that pins HTML elements to entities on screen: names, values, buttons, tooltips. The elements are ordinary DOM, so they take CSS, text selection and clicks; the plugin only moves them. An engine installs it when an entity first gets a Label.
ts
import { Label, Position, Visual } from "@pawnjs/core";
const tag = document.createElement("div");
tag.textContent = "Wind park · 19 MW";
engine.world.spawn(
Position({ x: -7, z: 5 }),
Visual(turbines),
Label({ element: tag, offset: { y: 3 } }),
);Late in the render phase, after transforms reach the scene, each label is placed over its entity's world position plus offset. A label is hidden (visibility: hidden) while its entity is off screen, behind the camera, outside its view or has no position.
Label options
| Option | Meaning |
|---|---|
element | Element to move. |
offset | World-space offset from the entity, e.g. { y: 2 } above it. |
align | Point of the element placed on the entity, as fractions of its size. Defaults to { x: 0.5, y: 1 }: centered, above the point. |
view | View to project through. Defaults to the first enabled view. |
The plugin sets position: absolute, left, top, transform and visibility on the element; style everything else yourself.
Many labels
For scenes with hundreds of labelled entities, Labels can show only the ones that matter, configured by installing it yourself before the first label:
ts
import { Labels } from "@pawnjs/core";
engine.use(new Labels({ maxDistance: 40, maxVisible: 50 }));maxDistancehides labels farther than this from their view's camera, in world units.maxVisibleshows at most this many labels, the nearest to the camera.- Both default to
Infinity. A label only rewrites its element'stransformwhen its place on screen changes.
Container
Labels are positioned in a container, by default the canvas's parent element (give it position: relative). Pass another one with new Labels({ container }). An element without a parent is appended to the container and removed again with its label; an element already in the page stays where it is and is only moved.
engine.plugin(Labels) returns the installed plugin, or installs a default one.
World position
An entity is labelled at its world position, so labels on ChildOf children follow their parents, with a Visual or without one. An Instance is drawn in world space, so its Position is its world position.
Projecting points yourself
engine.views.project(point, view?) returns the client coordinates of a world point and whether it is visible, or null without a canvas. Without a view it projects through engine.views.first, the first view drawn:
ts
const at = engine.views.project(new Vector3(0, 2, 0));
if (at?.visible) showTooltip(at.x, at.y);In React, use <EntityLabel>.