---
url: /pawn/docs/guide/hierarchy.md
description: Parenting entities with ChildOf and reading world positions.
---

# 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](https://jakubprill.github.io/pawn/solar.html) 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.
