Skip to content

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, Rotation and Scale become relative to the parent.
  • The child's Visual is nested under the parent's Visual, so three.js composes world transforms.
  • An entity has at most one parent. Adding another ChildOf reparents it, keeping its local transform (so its world pose changes).
  • Removing ChildOf moves 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 ignore ChildOf.
  • Physics bodies work in world space and belong on root entities.
  • Entities without a Visual have no stored world transform: worldPositionOf composes it on each call, walking up the parents.