Appearance
Hierarchy
ChildOf(parent) makes an entity the child of another:
ts
import { ChildOf, Position, Rotation, Visual } from "@pawnjs/core";
const ship = engine.world.spawn(Position, Rotation, Visual(hull));
const turret = engine.world.spawn(
Position({ x: 0, y: 1, z: 0 }),
Rotation,
Visual(gun),
ChildOf(ship),
);- The child's
Position,RotationandScalebecome relative to the parent. - The child's
Visualis nested under the parent'sVisual, so three.js composes world transforms. - An entity has at most one parent. Adding another
ChildOfreparents it, keeping its local transform (so its world pose changes). - Removing
ChildOfmoves the child's visual back to the scene root. - Destroying a parent destroys its children.
- A relation that would create a cycle is removed with a warning.
A parent without a Visual gets an empty Group as its visual, so its children have something to hang from. Give it a mesh later with parent.set(Visual, mesh) (add keeps the existing value).
A pivot without a visual is a handy way to orbit things. The Solar example spins a pivot and puts a planet at a distance on it:
ts
const pivot = engine.world.spawn(Rotation, Spin({ speed }), ChildOf(center));
const anchor = engine.world.spawn(Position({ x: distance }), ChildOf(pivot));
engine.world.spawn(Visual(planet), ChildOf(anchor));Here a pivot carries a planet around the sun, and the planet's own spin carries its moon:
ts
import {
ChildOf,
Engine,
Position,
Scale,
Shape,
Spin,
View,
} from "@pawnjs/core";
import { AmbientLight, DirectionalLight, PerspectiveCamera } from "three";
export default function hierarchy(canvas: HTMLCanvasElement): Engine {
canvas.style.cssText = "display:block;width:100%;height:100%";
const engine = new Engine({ canvas });
const { world } = engine;
engine.scene.add(new AmbientLight(0xffffff, 0.8));
const light = new DirectionalLight(0xffffff, 2);
light.position.set(3, 6, 5);
engine.scene.add(light);
const sun = world.spawn(
Shape({ kind: "sphere", color: "#fbbf24" }),
Position,
Scale({ x: 1.2, y: 1.2, z: 1.2 }),
);
// A spinning pivot carries the planet around the sun...
const orbit = world.spawn(Spin({ speed: 0.6 }), ChildOf(sun));
const planet = world.spawn(
Shape({ kind: "sphere", color: "#6366f1" }),
Position({ x: 2.2 }),
Scale({ x: 0.5, y: 0.5, z: 0.5 }),
Spin({ speed: 1 }),
ChildOf(orbit),
);
// ...and the planet's own spin carries its moon. Transforms are relative
// to the parent, so the moon follows both turns and the planet's scale.
world.spawn(
Shape({ kind: "sphere", color: "#e2e8f0" }),
Position({ x: 1.6 }),
Scale({ x: 0.6, y: 0.6, z: 0.6 }),
ChildOf(planet),
);
const camera = new PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 3, 4.5);
camera.lookAt(0, 0, 0);
engine.views.add(new View({ camera, background: 0x09090b }));
engine.fitToElement(canvas);
engine.start();
return engine;
}World position
worldPositionOf(entity, target) writes an entity's world position into a Vector3 and returns whether it has one. It reads the Visual once that is in the scene, so ChildOf parents are composed. An entity without one (a data-only entity, in a headless test or a feed) has its Position, Rotation and Scale composed with its parents' up ChildOf instead, so it lands where a drawn one would. Visuals are synced at the start of the render phase, so call it in render (after Engine.SCENE_SYNC_ORDER) for this frame's position; Labels and CameraRig do.
ts
import { worldPositionOf } from "@pawnjs/core";
import { Vector3 } from "three";
const point = new Vector3();
if (worldPositionOf(turret, point)) aimAt(point);Limits
- Instances (
Instance) are drawn in world space and ignoreChildOf. - Physics bodies work in world space and belong on root entities.
- Entities without a
Visualhave no stored world transform:worldPositionOfcomposes it on each call, walking up the parents.