Skip to content

Tutorial 5 — ECS + Three.js (render-sync + safe spawn/despawn)

Outcome: you’ll see moving cubes in Three.js. You’ll also spawn new cubes on click and despawn them safely using cmd() + phase flush boundaries (via Schedule).


1) Create a new project

1
2
3
4
5
6
mkdir ecs-threejs-tutorial
cd ecs-threejs-tutorial
npm init -y

npm i archetype-ecs-lib three
npm i -D vite typescript

The ECS package is installed as archetype-ecs-lib.


2) Add index.html

Create index.html:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ECS + Three.js Tutorial</title>
    <style>
      html, body { margin: 0; height: 100%; overflow: hidden; }
      #hud {
        position: fixed; left: 12px; top: 12px;
        padding: 8px 10px; border-radius: 8px;
        background: rgba(0,0,0,0.55); color: #fff;
        font-family: system-ui, sans-serif; font-size: 13px;
        user-select: none;
      }
    </style>
  </head>
  <body>
    <div id="hud">Click to spawn cubes</div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

3) Add src/main.ts

Create src/main.ts:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
import * as THREE from "three";
import { World, WorldApi, Schedule, SystemFn } from "archetype-ecs-lib";

// --------------------
// Components (data only)
// --------------------
class Position { constructor(public x = 0, public y = 0, public z = 0) {} }
class Velocity { constructor(public x = 0, public y = 0, public z = 0) {} }
class Lifetime { constructor(public seconds = 2.0) {} }
class Renderable { constructor(public kind: "cube" = "cube") {} }

// --------------------
// Three.js setup
// --------------------
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x101018);

const camera = new THREE.PerspectiveCamera(
  60,
  window.innerWidth / window.innerHeight,
  0.1,
  1000
);
camera.position.set(0, 6, 14);
camera.lookAt(0, 0, 0);

const grid = new THREE.GridHelper(40, 40);
scene.add(grid);

window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

// --------------------
// ECS setup
// --------------------
const world = new World();
const sched = new Schedule();

// Map ECS entities -> Three.js objects
// Use id+gen so reuse of ids never points to the wrong mesh.
const entityKey = (e: { id: number; gen: number }) => `${e.id}:${e.gen}`;
const objects = new Map<string, THREE.Object3D>();

function makeObject(r: Renderable): THREE.Object3D {
  // MeshNormalMaterial doesn't need lights
  const geo = new THREE.BoxGeometry(1, 1, 1);
  const mat = new THREE.MeshNormalMaterial();
  const mesh = new THREE.Mesh(geo, mat);
  mesh.castShadow = false;
  mesh.receiveShadow = false;
  return mesh;
}

// --------------------
// Input: click to spawn
// --------------------
let pendingClicks = 0;
window.addEventListener("pointerdown", () => pendingClicks++);

const inputPhase: SystemFn = (w: WorldApi) => {
  if (pendingClicks <= 0) return;

  const cmd = w.cmd();
  for (let i = 0; i < pendingClicks; i++) {
    cmd.spawn((e: any) => {
      // Spawn near origin with random velocity and short lifetime
      const x = (Math.random() - 0.5) * 8;
      const z = (Math.random() - 0.5) * 8;

      const vx = (Math.random() - 0.5) * 6;
      const vz = (Math.random() - 0.5) * 6;

      cmd.addBundle(
        e,
        [new Position(x, 0.5, z), new Velocity(vx, 0, vz), new Lifetime(2.0 + Math.random() * 2.0), new Renderable("cube")]
      );
    });
  }

  pendingClicks = 0;
}

// --------------------
// Simulation: movement
// --------------------
const movementSystem: SystemFn = (w: WorldApi, dt: number) => {
  for (const { c1: pos, c2: vel } of w.query(Position, Velocity)) {
    pos.x += vel.x * dt;
    pos.y += vel.y * dt;
    pos.z += vel.z * dt;

    // simple bounds bounce
    const limit = 12;
    if (pos.x < -limit || pos.x > limit) vel.x *= -1;
    if (pos.z < -limit || pos.z > limit) vel.z *= -1;
  }
}

// --------------------
// Simulation: lifetime -> despawn (deferred)
// --------------------
const lifetimeSystem: SystemFn = (w: WorldApi, dt: number) => {
  for (const { e, c1: life } of w.query(Lifetime)) {
    life.seconds -= dt;
    if (life.seconds <= 0) {
      w.cmd().despawn(e); // structural change deferred
    }
  }
}

// --------------------
// Render phase: ECS -> Three.js sync + remove despawned
// --------------------
const renderSync: SystemFn = (w: WorldApi) => {
  const alive = new Set<string>();

  // Create/update objects for all renderables
  for (const { e, c1: pos, c2: rend } of w.query(Position, Renderable)) {
    const key = entityKey(e);
    alive.add(key);

    let obj = objects.get(key);
    if (!obj) {
      obj = makeObject(rend);
      scene.add(obj);
      objects.set(key, obj);
    }

    obj.position.set(pos.x, pos.y, pos.z);
  }

  // Remove objects whose entities are gone
  for (const [key, obj] of objects) {
    if (!alive.has(key)) {
      scene.remove(obj);
      objects.delete(key);
    }
  }
}

// --------------------
// Schedule: phase ordering + flush boundaries
// --------------------
// Schedule runs phases in order and calls world.flush() after each phase. :contentReference[oaicite:2]{index=2}
sched.add("input", inputPhase);
sched.add("sim", movementSystem);
sched.add("sim", lifetimeSystem);
sched.add("render", renderSync);

const phases = ["input", "sim", "render"];

// --------------------
// Animation loop
// --------------------
let last = performance.now();

function frame(now: number) {
  const dt = Math.min(0.05, (now - last) / 1000);
  last = now;

  // Run ECS phases (flush after each phase)
  sched.run(world, dt, phases);

  // Render Three.js
  renderer.render(scene, camera);

  requestAnimationFrame(frame);
}

requestAnimationFrame(frame);

// Spawn a few cubes at start (via commands so it behaves like gameplay)
pendingClicks = 6;

This uses:

  • Schedule.add(phase, fn) and Schedule.run(world, dt, phases) with flush between phases
  • world.query(A, B) yielding { e, c1, c2 }
  • deferred structural ops via cmd().spawn/add/despawn

4) Run it

1
npx vite

Open the local URL Vite prints.


5) What to try (hands-on)

  1. Click to spawn cubes
  2. Watch them move (ECS Position + Velocity)
  3. Watch them disappear after a few seconds (Lifetimecmd().despawn(e)), and see the Three.js mesh removed automatically in renderSync().

That’s the “safe loop”:

  • structural requests happen inside systems using cmd()
  • structural changes become real at flush boundaries (Schedule phases)
  • render-sync runs on a stable world snapshot