Skip to content

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 ​

OptionMeaning
elementElement to move.
offsetWorld-space offset from the entity, e.g. { y: 2 } above it.
alignPoint of the element placed on the entity, as fractions of its size. Defaults to { x: 0.5, y: 1 }: centered, above the point.
viewView 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 }));
  • maxDistance hides labels farther than this from their view's camera, in world units.
  • maxVisible shows at most this many labels, the nearest to the camera.
  • Both default to Infinity. A label only rewrites its element's transform when 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>.