@adobe/ecs 0.1.0 → 0.2.1

package/src/guide/12-lookups.ts

@@ -0,0 +1,59 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World } from "../index.js";
+
+const health = Symbol();
+const target = Symbol();
+const frozen = Symbol();
+const aim = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [health]: { type: number };
+        [target]: { type: Entity; reference: "weak" };
+        [frozen]: { type: true };
+        [aim]: { type: number };
+    }
+}
+
+const track = System.create({
+    components: { with: [target, aim] },
+    lookup: { enemy: { with: [health], not: [frozen] } },
+}, (row, { lookup }) => {
+    const enemy = lookup.enemy(row[target]);
+    row[aim] = enemy === null ? 0 : enemy[health];
+});
+
+const refreshed: boolean[] = [];
+const watch = System.create({
+    observer: true,
+    components: { with: [target] },
+    lookup: { enemy: { with: [health], changed: [health] } },
+}, (row, { lookup }) => {
+    const enemy = lookup.enemy(row[target]);
+    if (enemy !== null) refreshed.push(enemy.changed);
+});
+
+const aims: number[] = [];
+const readAims = System.create({ observer: true, components: { with: [aim] } }, row => {
+    aims.push(row[aim]);
+});
+
+const spawn = System.create(({ commands }) => {
+    const ogre = commands.spawn([health])({ [health]: 40 });
+    const statue = commands.spawn([health, frozen])({ [health]: 90 });
+    commands.spawn([target, aim])({ [target]: ogre, [aim]: -1 });
+    commands.spawn([target, aim])({ [target]: statue, [aim]: -1 });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(track);
+    await world.run(readAims);
+    console.log("aims", aims.sort((a, b) => a - b));
+    await world.run(watch);
+    console.log("changed", refreshed);
+    refreshed.length = 0;
+    await world.run(watch);
+    console.log("changed", refreshed);
+};

package/src/guide/13-indexes.md

@@ -0,0 +1,21 @@
+# Indexes
+
+An *index* maps component values to the entities holding them, and every world keeps it current. `Index.create`
+declares it with a `key` and the components an entity needs to be in it; a lookup through it,
+`lookup: { at: { index: grid } }`, finds entities by value.
+
+- **Hash**, the default: [`lookup.at(key)`](13-indexes.ts#L20-L25) gives the rows with that key, in entity order.
+- **`sorted: true`**: also takes ranges, such as [`{ ">=": 90 }`](13-indexes.ts#L27-L34), and `order: byScore` runs a
+  system's rows [in the key's order](13-indexes.ts#L36-L38).
+- **`unique: true`**: [one row, or `null`](13-indexes.ts#L40-L42).
+- **`key: []`**: every entity with its components, in entity order.
+
+A lookup gives a list: its `length`, `at(i)`, and `changed`, whether an entity entered, left or moved in it since the
+system last ran. The list is reused, valid until its call site runs again, and costs only what the body reads. Its rows
+hold the index's key and `with`.
+
+With `changed: true` on the lookup, a system runs only when an entity entered or left the index anywhere. Added,
+[`countPlayers`](13-indexes.ts#L44-L47) logs once as the players arrive.
+
+A system can't look up through an index keyed by what it writes, nor order its rows by an index that isn't sorted or
+is keyed by what it writes.

package/src/guide/13-indexes.out

@@ -0,0 +1,8 @@
+players 3
+crowds [ 1, 2, 2 ]
+90 and up [ 'cy', 'ada' ]
+bo 80
+cy 91
+ada 95
+server 8 bo
+server 1 null

package/src/guide/13-indexes.ts

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type I32, Index, System, type Vec2, World } from "../index.js";
+
+const cell = Symbol();
+const crowded = Symbol();
+const score = Symbol();
+const player = Symbol();
+const serverId = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [cell]: { type: Vec2.I32 };
+        [crowded]: { type: number };
+        [score]: { type: number };
+        [player]: { type: string };
+        [serverId]: { type: I32 };
+    }
+}
+
+const grid = Index.create({ key: [cell], components: { with: [crowded] } });
+
+const count = System.create({ components: { with: [cell, crowded] }, lookup: { at: { index: grid } } }, (row, { lookup }) => {
+    const [x, y] = row[cell];
+    row[crowded] = lookup.at([x, y]).length;
+});
+
+const byScore = Index.create({ key: [score], sorted: true, components: { with: [player] } });
+
+const leaders = System.create({ observer: true, lookup: { scores: { index: byScore } } }, ({ lookup }) => {
+    const winners: string[] = [];
+    const high = lookup.scores({ ">=": 90 });
+    for (let i = 0; i < high.length; i++) winners.push(high.at(i)[player]);
+    return winners;
+});
+
+const list = System.create({ observer: true, components: { with: [player, score] }, order: byScore }, row => {
+    console.log(row[player], row[score]);
+});
+
+const byServerId = Index.create({ key: [serverId], unique: true, components: { with: [player] } });
+const find = System.create({ lookup: { byId: { index: byServerId } } }, ({ lookup }, input: { readonly id: number }) =>
+    lookup.byId(input.id)?.[player] ?? null);
+
+const players = Index.create({ key: [], components: { with: [player] } });
+const countPlayers = System.create({ observer: true, lookup: { players: { index: players, changed: true } } }, ({ lookup }) => {
+    console.log("players", lookup.players().length);
+});
+
+const crowds: number[] = [];
+const readCrowds = System.create({ observer: true, components: { with: [crowded] } }, row => {
+    crowds.push(row[crowded]);
+});
+
+const places: readonly (readonly [number, number])[] = [[0, 0], [0, 0], [1, 0]];
+const spawn = System.create(({ commands }) => {
+    for (const place of places) commands.spawn([cell, crowded])({ [cell]: place, [crowded]: 0 });
+    commands.spawn([player, score, serverId])({ [player]: "ada", [score]: 95, [serverId]: 7 });
+    commands.spawn([player, score, serverId])({ [player]: "bo", [score]: 80, [serverId]: 8 });
+    commands.spawn([player, score, serverId])({ [player]: "cy", [score]: 91, [serverId]: 9 });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    world.add(countPlayers);
+    await world.run(spawn);
+    await world.run(count);
+    await world.run(readCrowds);
+    console.log("crowds", crowds.sort((a, b) => a - b));
+    console.log("90 and up", await world.run(leaders));
+    await world.run(list);
+    console.log("server 8", await world.run(find, { id: 8 }));
+    console.log("server 1", await world.run(find, { id: 1 }));
+};

package/src/guide/14-kernels.md

@@ -0,0 +1,15 @@
+# Kernels
+
+A *kernel* is a body the build compiles to run once per row, each row on its own, so the world can split the rows
+across workers and run them as WASM, with results the same as the body as written.
+
+The build makes a kernel of any row system whose body reads and writes only data, calls math, and touches no module
+state, without being asked: [`move`](14-kernels.ts#L18-L21) is one. Two flags change that:
+
+- `kernel: true` asserts it. The build fails, saying why, if [the body](14-kernels.ts#L23-L25) can't be one. It also
+  computes `F32` values at 32 bits, which is faster on dense rows.
+- `kernel: false` runs [the body as written](14-kernels.ts#L27-L29), on its thread: to step through it in a
+  debugger, say.
+
+In the guide, the lens above each system says what it compiles to: JS, WASM and WGSL, or as written. Its Compiled tab
+shows the code.

package/src/guide/14-kernels.out

@@ -0,0 +1 @@
+at 3, moving at 1; at 4, moving at 1; at 5, moving at 1

package/src/guide/14-kernels.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, System, Vec3, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const delta = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+    }
+    interface Resources {
+        [delta]: { type: F32; default: 0.5 };
+    }
+}
+
+// A kernel without asking: the build compiles it.
+const move = System.create({ components: { with: [velocity, position] } }, (row, { resources }) => {
+    row[position] = Vec3.add(row[position], Vec3.scale(row[velocity], resources[delta]));
+});
+
+const drift = System.create({ kernel: true, components: { with: [velocity, position] } }, row => {
+    row[position] = Vec3.add(row[position], row[velocity]);
+});
+
+const slow = System.create({ kernel: false, components: { with: [velocity] } }, row => {
+    row[velocity] = Vec3.scale(row[velocity], 0.5);
+});
+
+const moved: string[] = [];
+const read = System.create({ observer: true, components: { with: [position, velocity] } }, row => {
+    moved.push(`at ${row[position][0]}, moving at ${row[velocity][0]}`);
+});
+
+const spawn = System.create(({ commands }) => {
+    for (let i = 0; i < 3; i++) commands.spawn([position, velocity])({ [position]: [i, 0, 0], [velocity]: [2, 0, 0] });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(move);
+    await world.run(drift);
+    await world.run(slow);
+    await world.run(read);
+    console.log(moved.sort().join("; "));
+};

package/src/guide/15-reductions.md

@@ -0,0 +1,12 @@
+# Reductions
+
+A *reduction* folds what many rows contribute into one resource, however the rows are split across workers. Its
+[declaration](15-reductions.ts#L13-L17) names the operator: `reduce: "+"`, `"*"`, `"min"`, `"max"`, or bitwise `"&"`,
+`"|"`, `"^"`.
+
+- A body contributes with [`reduce[total](value)`](15-reductions.ts#L20-L24), as often as it likes.
+- Each run that reduces into a resource starts it at its operator's identity and leaves it holding the fold of every
+  contribution.
+- Systems can't write a reduced resource; only the fold sets it. Read it after the run, as any resource.
+
+The clock's `wake`, from [Ticks and cadence](04-ticks.md), is a reduction: the earliest time asked for wins.

package/src/guide/15-reductions.out

@@ -0,0 +1 @@
+3 weigh 10, at most 5

package/src/guide/15-reductions.ts

@@ -0,0 +1,38 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, System, World } from "../index.js";
+
+const mass = Symbol();
+const total = Symbol();
+const heaviest = Symbol();
+const count = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [mass]: { type: F32 };
+    }
+    interface Resources {
+        [total]: { type: number; reduce: "+" };
+        [heaviest]: { type: F32; reduce: "max" };
+        [count]: { type: number; reduce: "+" };
+    }
+}
+
+const weigh = System.create({ components: { with: [mass] } }, (row, { reduce }) => {
+    reduce[total](row[mass]);
+    reduce[heaviest](row[mass]);
+    reduce[count](1);
+});
+
+const report = System.create({ observer: true }, ({ resources }) =>
+    `${resources[count]} weigh ${resources[total]}, at most ${resources[heaviest]}`);
+
+const spawn = System.create(({ commands }) => {
+    for (const value of [2, 5, 3]) commands.spawn([mass])({ [mass]: value });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(weigh);
+    console.log(await world.run(report));
+};

package/src/guide/16-gpu.md

@@ -0,0 +1,18 @@
+# GPU kernels and render systems
+
+A world given a WebGPU device, `World.create({ [gpuDevice]: device })`, keeps a GPU copy of the components its GPU
+systems use.
+
+**GPU kernels.** `kernel: "gpu"` runs [the body](16-gpu.ts#L16-L18) as a compute shader over that copy, and as a kernel
+on the CPU in a world without a device, as here. Its rows hold 32-bit numbers and vectors of them, and it has no
+lookups, change filters or commands.
+
+**Render systems.** `System.render` records draws over the GPU copy of the components its `accessors` name, in a world
+with a device; without one it's skipped. [Its body](16-gpu.ts#L23-L32) gets an encoder and `tables`, each a group of
+matching rows to draw: `table.bind(pass)` binds its rows, and `table.count` says how many there are.
+
+- `Gpu.wgsl(draw)` gives the WGSL functions its shaders call, one per accessor, such as
+  `fn dotPosition(row: u32) -> vec2<f32>`.
+- `Gpu.layout(device)` gives the bind group layout its pipeline takes.
+
+The guide says whether this browser has WebGPU.

package/src/guide/16-gpu.out

@@ -0,0 +1,3 @@
+at [ 1, 2 ]
+fn dotPosition(row: u32) -> vec2<f32>
+fn dotSize(row: u32) -> f32

package/src/guide/16-gpu.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, Gpu, System, Vec2, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const size = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec2 };
+        [velocity]: { type: Vec2 };
+        [size]: { type: F32 };
+    }
+}
+
+const move = System.create({ kernel: "gpu", components: { with: [velocity, position] } }, row => {
+    row[position] = Vec2.add(row[position], row[velocity]);
+});
+
+// Made with the app's shaders, using shaderCode, and its canvas.
+let pipeline: GPURenderPipeline | null = null;
+let target: GPUTextureView | null = null;
+const draw = System.render({ shader: { accessors: { dotPosition: position, dotSize: size } } }, ({ encoder, tables }) => {
+    if (pipeline === null || target === null) return;
+    const pass = encoder.beginRenderPass({ colorAttachments: [{ view: target, loadOp: "clear", storeOp: "store" }] });
+    pass.setPipeline(pipeline);
+    for (const table of tables) {
+        table.bind(pass);
+        pass.draw(6, table.count);
+    }
+    pass.end();
+});
+const shaderCode = Gpu.wgsl(draw);
+
+const read = System.create({ observer: true, components: { with: [position] } }, row => {
+    console.log("at", row[position]);
+});
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity, size])({ [position]: [0, 0], [velocity]: [1, 2], [size]: 4 });
+});
+
+export const main = async (): Promise<void> => {
+    // Without a device, move runs on the CPU and draw is skipped.
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(move);
+    await world.run(draw);
+    await world.run(read);
+    for (const accessor of shaderCode.match(/fn dot\w+\(.*?\) -> [\w<>]+/g) ?? []) console.log(accessor);
+};

package/src/guide/17-hierarchies.md

@@ -0,0 +1,11 @@
+# Hierarchies
+
+A hierarchy is entities pointing at their parent through a reference, here `reference: "owner"`, so a child is
+despawned with its parent.
+
+`up: { through: parent }` runs a system's rows parent first, so each row reads its parent's values as the same run
+left them. The body's `up` holds what it reads of the parent, or `null` for a row without one.
+[`place`](17-hierarchies.ts#L19-L21) adds each offset to its parent's place, so the cup, on the tray, on the table, is
+at 13 after one run.
+
+A system with `up` can't also have `order`: both decide the order of its rows.

package/src/guide/17-hierarchies.out

@@ -0,0 +1 @@
+cup at 13, table at 10, tray at 12

package/src/guide/17-hierarchies.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World } from "../index.js";
+
+const parent = Symbol();
+const offset = Symbol();
+const placed = Symbol();
+const label = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        // Despawned with its parent.
+        [parent]: { type: Entity; reference: "owner" };
+        [offset]: { type: number };
+        [placed]: { type: number };
+        [label]: { type: string };
+    }
+}
+
+const place = System.create({ components: { with: [offset, placed] }, up: { through: parent } }, (row, { up }) => {
+    row[placed] = (up === null ? 0 : up[placed]) + row[offset];
+});
+
+const where: string[] = [];
+const read = System.create({ observer: true, components: { with: [label, placed] } }, row => {
+    where.push(`${row[label]} at ${row[placed]}`);
+});
+
+const spawn = System.create(({ commands }) => {
+    const table = commands.spawn([label, offset, placed])({ [label]: "table", [offset]: 10, [placed]: 0 });
+    const tray = commands.spawn([label, offset, placed, parent])({ [label]: "tray", [offset]: 2, [placed]: 0, [parent]: table });
+    commands.spawn([label, offset, placed, parent])({ [label]: "cup", [offset]: 1, [placed]: 0, [parent]: tray });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(place);
+    await world.run(read);
+    console.log(where.sort().join(", "));
+};

package/src/guide/18-identity.md

@@ -0,0 +1,10 @@
+# Identity and ids
+
+A key, system, index, rule or finalizer is the value its constructor returns. Two written alike are two, and code
+written apart can't collide.
+
+The build gives each one bound at a module's top level an *id*: its package's name and version, its module's path,
+and its binding. Other threads, and a module evaluated again by hot reload, name the same one by it.
+
+What fails is named by its binding, with its id beside it to tell two of one name apart, as
+[`explode`](18-identity.ts#L4-L6)'s error shows.

package/src/guide/18-identity.out

@@ -0,0 +1 @@
+Error: System "explode" (@adobe/ecs@0.2.1/src/guide/18-identity.ts#explode) failed: boom

package/src/guide/18-identity.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World } from "../index.js";
+
+const explode = System.create(() => {
+    throw new Error("boom");
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(explode).catch((error: unknown) => console.log(String(error)));
+};

package/src/guide/19-threads.md

@@ -0,0 +1,16 @@
+# Threads
+
+A *logical thread* is where objects live and the code touching them runs: the page's `"main"`, or one you declare in
+[`interface Threads`](19-threads.ts#L7-L17). `thread: "audio"` places a component or resource on it.
+
+- A system runs on the thread its objects live on: [`mix`](19-threads.ts#L19-L22) writes `levels`, so it runs on
+  `audio`.
+- A run reading objects on another thread runs there, and resolves to a copy of what it returns.
+
+**Joining.** A world shares itself over a message port, `world.share(port)`, and another thread joins it with
+`World.join(port, { threads: ["audio"] })`, claiming the threads it fills. Usually the other end of the channel goes
+to a worker; [here both ends](19-threads.ts#L44-L54) are on one thread.
+
+- `share` resolves once the thread joined, with the observer systems it added as `join` resolved, before awaiting
+  anything else. Those observers run there after the world's sync points: `listen` hears what `mix` wrote.
+- A joined world runs systems as the world does: [`audio.run`](19-threads.ts#L60-L61) spawns and mixes too.

package/src/guide/19-threads.out

@@ -0,0 +1,2 @@
+mixed 2 voices; listening hears 2
+mixed 4 voices; listening hears 4

package/src/guide/19-threads.ts

@@ -0,0 +1,65 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World } from "../index.js";
+
+const volume = Symbol();
+const levels = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Threads {
+        audio: true;
+    }
+    interface Components {
+        [volume]: { type: number };
+    }
+    interface Resources {
+        [levels]: { type: ReadonlyMap<string, number>; thread: "audio" };
+    }
+}
+
+// Runs on audio, where levels lives.
+const mix = System.create({ components: { with: [volume] } }, (row, { resources }) => {
+    resources[levels] = new Map([...resources[levels], [`voice ${row.entity}`, row[volume]]]);
+});
+
+let heard = 0;
+const listen = System.create({ observer: true }, ({ resources }) => {
+    heard = resources[levels].size;
+});
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([volume])({ [volume]: 0.8 });
+    commands.spawn([volume])({ [volume]: 0.3 });
+});
+
+const countVoices = System.create({ observer: true }, ({ resources }) => resources[levels].size);
+
+/** Waits a turn of the event loop at a time until `done`, for two seconds at most. */
+const until = async (done: () => boolean): Promise<void> => {
+    const end = performance.now() + 2000;
+    while (!done() && performance.now() < end) await new Promise(resolve => setTimeout(resolve, 1));
+};
+
+export const main = async (): Promise<void> => {
+    // Usually one end of the channel goes to a worker, `new Worker(...)`, which joins with the other.
+    const channel = new MessageChannel();
+    await using world = World.create();
+    // Each side awaits its own end, here both on one thread.
+    const [joined] = await Promise.all([
+        World.join(channel.port2, { threads: ["audio"] }).then(audio => {
+            audio.add(listen);
+            return audio;
+        }),
+        world.share(channel.port1),
+    ]);
+    await using audio = joined;
+    await world.run(spawn);
+    await world.run(mix);
+    const mixed = await world.run(countVoices);
+    await until(() => heard === mixed);
+    console.log("mixed", mixed, "voices; listening hears", heard);
+    await audio.run(spawn);
+    await audio.run(mix);
+    const more = await world.run(countVoices);
+    await until(() => heard === more);
+    console.log("mixed", more, "voices; listening hears", heard);
+};

package/src/guide/20-shared.md

@@ -0,0 +1,29 @@
+# Shared components and where
+
+A *shared* component's value belongs to its archetype: entities with equal values share one archetype, which holds the
+value once. [`cell`](20-shared.ts#L16), declared `shared: true`, is the chunk of the world a unit is in, so each
+chunk's units share an archetype.
+
+- A spawner's first call takes *constants*, values every entity it spawns starts with:
+  [`commands.spawn(Unit, { [cell]: [x, y], ... })`](20-shared.ts#L31-L39). The shared ones choose the archetype; the
+  others, here every unit's velocity, start each entity's own value. The spawner's call takes the rest.
+- A row reads `row[cell]` as its archetype's value, read-only: [`place`](20-shared.ts#L41-L43) reads it, and as a
+  kernel takes it as a parameter of each call over an archetype, not as a column.
+- Assigning a shared component is a type error. `commands.add` with another value
+  [moves the entity](20-shared.ts#L49-L53) to that value's archetype, creating it if needed.
+
+**`where`** keeps a system to the archetypes whose shared values pass:
+
+- A value passes the archetypes holding an equal one: [`where: { [cell]: [4, 0] }`](20-shared.ts#L77-L79) counts only
+  the chunk the step's crossing units move into.
+- A predicate of the value and the resources passes those it returns `true` for: [`draw`](20-shared.ts#L58-L65) visits
+  only the chunks the camera sees.
+
+A predicate runs once per archetype as the archetype appears, and again for every archetype only after a resource it
+reads changed, never per row or per run. The camera counts what it's asked: every chunk for each of the two systems at
+first, only the new chunks after the step, nothing while nothing changed, and every chunk again once
+[`look`](20-shared.ts#L92-L94) writes a new camera. Since the world caches the results, the build rejects a predicate
+that reads anything but its value, the resources and module constants.
+
+With a change filter, a chunk out of view keeps its rows unseen: [`refresh`](20-shared.ts#L67-L73) counts, when the
+camera moves, the rows that changed while their chunk was out of view, through `changed: [position]`.

package/src/guide/20-shared.out

@@ -0,0 +1,4 @@
+start: drew 18 from x -8 to 17 refreshed 18 east 0 asked 98
+after a step: drew 18 from x -9 to 16 refreshed 18 east 1 asked 14
+unchanged: drew 18 from x -9 to 16 refreshed 0 east 1 asked 0
+camera moved: drew 18 from x 11 to 36 refreshed 16 east 1 asked 112