@adobe/ecs 0.2.1 → 0.2.4

package/src/perftest/benchmarks.ts

@@ -35,6 +35,7 @@ import { Observe } from "../observe/index.js";
 import { entitiesWith } from "./observer.js";
 import { invariantBenchmarks } from "./invariants.js";
 import { journalBenchmarks } from "./journal.js";
+import { tableBenchmarks } from "./tables.js";
 
 /** A world whose kernels run on this thread, which the benchmarks without a placement measure; `workers` ones use the pool. */
 const inline = (): World => createWorld({ [workers]: 0 });
@@ -505,7 +506,7 @@ export const benchmarks: readonly Benchmark[] = [
         run: async () => {
             const { world, roots } = await filteredForest();
             const found: { child: Entity | null } = { child: null };
-            await world.run(System.create({ observer: true, components: { with: [hierarchyParent] } }, row => {
+            await world.run(System.create({ readonly: true, components: { with: [hierarchyParent] } }, row => {
                 if (found.child === null && row[hierarchyParent] === roots[0]) found.child = row.entity;
             }));
             const { child } = found;
@@ -648,6 +649,22 @@ export const benchmarks: readonly Benchmark[] = [
             return best;
         },
     },
+    ...[10, 1_000, 100_000].flatMap(n => ([
+        ["rows", "a command per row", structural.despawnDoomedRows, 24],
+        ["where", "one `despawnWhere`", structural.despawnDoomedWhere, 16],
+    ] as const).map(([how, by, system, bytes]): Benchmark => {
+        const name = `despawn tagged ${n >= 1_000 ? `${n / 1_000}K` : n} ${how}`;
+        return {
+            name,
+            operation: `A run despawning the ${n >= 1_000 ? `${n / 1_000}K` : n} entities of a tag beside 100K others, by ${by}: clearing one kind, such as expired effects.`,
+            per: "despawns",
+            n,
+            typical: [10, 100_000],
+            best: { bytes, basis: bytes === 16 ? "Each despawn frees its 8-byte location and entity; the archetype empties, so no row moves." : "Each row reads its entity; each despawn frees its location and entity." },
+            run: () => structuralBest(1, world => world.run(structural.spawnDoomed, { count: n }), world => world.run(system),
+                async world => await countOf(world, [structural.doomed]) === 0, name),
+        };
+    })),
     ...([
         ["add tag", "Adding a tag to 100K entities of one archetype: a state flag set on many at once.", 1, structural.removeFlag, structural.addFlag, [structural.flag], 16],
         ["add tag kernel", "The same adds from a kernel.", 1, structural.removeFlagKernel, structural.addFlagKernel, [structural.flag], 20],
@@ -705,4 +722,5 @@ export const benchmarks: readonly Benchmark[] = [
     ...sharedBenchmarks,
     ...invariantBenchmarks,
     ...journalBenchmarks,
+    ...tableBenchmarks,
 ];

package/src/perftest/indexes.ts

@@ -307,13 +307,13 @@ const seedFlags = System.create({}, ({ commands }) => {
     for (let i = 0; i < flagged; i++) commands.spawn([flag])({ [flag]: i % 2 === 0 });
 });
 /** A run of observer systems alone, which passes every one added. */
-const pass = System.create({ observer: true }, () => {});
+const pass = System.create({ readonly: true }, () => {});
 /** A count of each bucket, written only when the index's entries changed: by `changed: true`, or by its lists' `changed`. */
 const countsWhenChanged = (filtered: boolean): System => filtered
-    ? System.create({ observer: true, lookup: { byFlag: { index: byFlag, changed: true } } }, ({ lookup }) => {
+    ? System.create({ readonly: true, lookup: { byFlag: { index: byFlag, changed: true } } }, ({ lookup }) => {
         found += lookup.byFlag(false).length + lookup.byFlag(true).length;
     })
-    : System.create({ observer: true, lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
+    : System.create({ readonly: true, lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
         const off = lookup.byFlag(false);
         const on = lookup.byFlag(true);
         if (!off.changed && !on.changed) return;

package/src/perftest/loop.ts

@@ -12,7 +12,7 @@ export const loopTicks = 10_000;
 export const observerIdles = 100;
 
 /** Observer systems no entity matches, each run after every tick. */
-const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ observer: true, components: { with: [unused] } }, () => {}));
+const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ readonly: true, components: { with: [unused] } }, () => {}));
 
 /**
  * The fastest of `stretches` stretches of `loopTicks` ticks with nothing changed, after one to warm up: a world with

package/src/perftest/observer.ts

@@ -14,14 +14,14 @@ import type { World } from "../interface/world/world.js";
  * first call only starts the stretch that warms up.
  */
 export const eachTick = (world: World, notify: () => void): (() => void) => {
-    const counter = System.create({ observer: true, resources: { changed: [clock] } }, () => { notify(); });
+    const counter = System.create({ readonly: true, resources: { changed: [clock] } }, () => { notify(); });
     world.add(counter);
     return () => world.remove(counter);
 };
 
 /** The clock as an observer run last read it. */
 const read = { tick: 0, now: 0 };
-const readClock = System.create({ observer: true }, ({ resources }) => {
+const readClock = System.create({ readonly: true }, ({ resources }) => {
     read.tick = resources[clock].tick;
     read.now = resources[clock].now;
 });
@@ -36,7 +36,7 @@ export const ticksAfter = async (world: World, count: number): Promise<void> =>
     let { tick, now } = read;
     let seen = 0;
     await new Promise<void>(resolve => {
-        const counter = System.create({ observer: true }, ({ resources }) => {
+        const counter = System.create({ readonly: true }, ({ resources }) => {
             const current = resources[clock];
             if (current.tick === tick && current.now === now) return;
             tick = current.tick;
@@ -52,7 +52,7 @@ export const ticksAfter = async (world: World, count: number): Promise<void> =>
 /** The entities with every component of `has` and none of `not`, in storage order, read by an observer run. */
 export const entitiesWith = async (world: World, has: readonly Component.Key[], not: readonly Component.Key[] = []): Promise<Entity[]> => {
     const found: Entity[] = [];
-    await world.run(System.create({ observer: true, components: { with: [...has], not } }, row => { found.push(row.entity); }));
+    await world.run(System.create({ readonly: true, components: { with: [...has], not } }, row => { found.push(row.entity); }));
     return found;
 };
 

package/src/perftest/reads.ts

@@ -78,7 +78,7 @@ const lookups = async (system: System): Promise<{ readonly best: number; readonl
 /** Every entity a seeded world holds. */
 const entitiesOf = async (world: World): Promise<readonly Entity[]> => {
     const found: Entity[] = [];
-    await world.run(System.create({ observer: true, components: { with: [value] } }, row => { found.push(row.entity); }));
+    await world.run(System.create({ readonly: true, components: { with: [value] } }, row => { found.push(row.entity); }));
     return found;
 };
 
@@ -124,7 +124,7 @@ export const readBenchmarks: readonly Benchmark[] = [
         run: async () => {
             const world = await seeded(10_000);
             copied = 0;
-            const best = await fastest(() => world.run(System.create({ observer: true }, ({ resources }) => { copied = resources[level]; })), 300);
+            const best = await fastest(() => world.run(System.create({ readonly: true }, ({ resources }) => { copied = resources[level]; })), 300);
             check(copied === 3, "read run observer: wrong value");
             await world.dispose();
             return best;

package/src/perftest/remote.ts

@@ -49,7 +49,7 @@ export const reorder = System.create([flip, reverse]);
 export const observerSeen = { last: 0, notified: 0 };
 
 /** On a joined thread, after each sync point that changed it: the observed resource. */
-export const observerCounter = System.create({ observer: true, resources: { changed: [counter] } }, ({ resources }) => {
+export const observerCounter = System.create({ readonly: true, resources: { changed: [counter] } }, ({ resources }) => {
     observerSeen.last = resources[counter];
     observerSeen.notified++;
 });
@@ -61,7 +61,7 @@ const sortedKeys = { keys: new Float64Array(0), entities: new Float64Array(0), p
  * On a joined thread, after each sync point: the entities in `order`, sorted from a scan of the index of every ranked
  * entity into reused arrays.
  */
-export const observerSelect = System.create({ observer: true, lookup: { all: { index: ranked } } }, ({ lookup }) => {
+export const observerSelect = System.create({ readonly: true, lookup: { all: { index: ranked } } }, ({ lookup }) => {
     const list = lookup.all();
     const count = list.length;
     if (sortedKeys.keys.length < count) {
@@ -99,12 +99,12 @@ export const retext = System.create([count, recaption]);
 export const reamounted = System.create([count, reamount]);
 
 /** On a joined thread, after each sync point: every row's caption, out of its record. */
-export const observerCaptions = System.create({ observer: true, components: { with: [caption] } }, row => {
+export const observerCaptions = System.create({ readonly: true, components: { with: [caption] } }, row => {
     observerSeen.last += row[caption].length;
     observerSeen.notified++;
 });
 /** On a joined thread, after each sync point: every row's amount. */
-export const observerAmounts = System.create({ observer: true, components: { with: [amount] } }, row => {
+export const observerAmounts = System.create({ readonly: true, components: { with: [amount] } }, row => {
     observerSeen.last += row[amount];
     observerSeen.notified++;
 });
@@ -129,7 +129,7 @@ const joinedFile = "./joined.js";
 /** The observed resource, read by an observer run. */
 const counterOf = async (world: World): Promise<number> => {
     let value = 0;
-    await world.run(System.create({ observer: true }, ({ resources }) => { value = resources[counter]; }));
+    await world.run(System.create({ readonly: true }, ({ resources }) => { value = resources[counter]; }));
     return value;
 };
 

package/src/perftest/strings.ts

@@ -80,7 +80,7 @@ const read = (system: System, name: string) => measure(system, async world => {
 /** Each row's text, as the last write left it. */
 const written = (name: string) => async (world: World): Promise<void> => {
     let wrong = 0;
-    await world.run(System.create({ observer: true, components: { with: [text, boxed] } }, row => {
+    await world.run(System.create({ readonly: true, components: { with: [text, boxed] } }, row => {
         if (row[text] !== row[boxed].text && row[text] !== labelOf(row.entity, round) && row[boxed].text !== labelOf(row.entity, round)) wrong++;
     }));
     check(wrong === 0, `${name}: wrong text`);

package/src/perftest/structural.ts

@@ -12,6 +12,7 @@ export const flag = Symbol("structural/flag");
 export const amount = Symbol("structural/amount");
 export const extra = Symbol("structural/extra");
 export const spawned = Symbol("structural/spawned");
+export const doomed = Symbol("structural/doomed");
 const source1 = Symbol("structural/source1");
 const source2 = Symbol("structural/source2");
 const t0 = Symbol("structural/t0");
@@ -27,6 +28,7 @@ declare module "@adobe/ecs" {
         [amount]: { type: F32 };
         [extra]: { type: F32 };
         [spawned]: { type: true };
+        [doomed]: { type: true };
         [source1]: { type: true };
         [source2]: { type: true };
         [t0]: { type: true };
@@ -128,6 +130,24 @@ export const removeFlagKernel = System.create({ kernel: true, components: { with
     commands.remove(row.entity, flag);
 });
 
+const doomedList = [index, value, doomed] as const;
+const doomedQuery = { with: [doomed] } as const;
+
+/** `count` spawns of entities tagged `doomed`, beside the seeded ones. */
+export const spawnDoomed = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn(doomedList)({ [index]: i, [value]: i });
+});
+
+/** Despawns every `doomed` entity, a command per row. */
+export const despawnDoomedRows = System.create({ kernel: false, components: { with: [doomed] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+/** Despawns every `doomed` entity, by one command. */
+export const despawnDoomedWhere = System.create({}, ({ commands }) => {
+    commands.despawnWhere(doomedQuery);
+});
+
 export const addAmount = System.create({ kernel: false, components: { with: [index], not: [amount, spawned] } }, (row, { commands }) => {
     commands.add(row.entity, amount, row[index]);
 });

package/src/perftest/suite.ts

@@ -196,7 +196,7 @@ export const idle = System.create({ components: { with: [unused] } }, () => {});
 /** A system that throws, so each run of it rejects. */
 export const failing = System.create({}, () => { throw new Error("suite: failing"); });
 /** An observer system no entity matches: a run of it alone has no tiers. */
-export const idleObserver = System.create({ observer: true, components: { with: [unused] } }, () => {});
+export const idleObserver = System.create({ readonly: true, components: { with: [unused] } }, () => {});
 
 /** Fifty systems no entity matches, in one tier. */
 export const idles = System.create({

package/src/perftest/tables.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from "../interface/entity/entity.js";
+import type { Vec3 } from "../interface/math/index.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import type { Tables } from "../interface/system/tables.js";
+import type { Table } from "../interface/world/table/table.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// Spawning 1M entities into a fresh world in one sync point, each owned by an earlier one or by none: from tables, as
+// loading a snapshot does, and from commands; and the same tables without the owner reference.
+
+const position = Symbol("tables/position");
+const owner = Symbol("tables/owner");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Vec3 };
+        [owner]: { type: Entity; reference: "owner" };
+    }
+}
+
+const count = 1_000_000;
+
+/** A root and `count - 1` entities, each owned by the one at half its position. */
+const build = System.create(({ commands }) => {
+    const made: Entity[] = [commands.spawn([position])({ [position]: [0, 0, 0] })];
+    const owned = commands.spawn([position, owner]);
+    for (let i = 1; i < count; i++) made.push(owned({ [position]: [i, i, i], [owner]: made[i >> 1] }));
+});
+
+const tablesOf = (components: readonly (typeof position | typeof owner)[]) =>
+    System.create({ readonly: true, tables: { components } }, ({ tables }): Tables => tables);
+
+const given: { tables: readonly Table[] } = { tables: [] };
+const spawnGiven = System.create(({ commands }) => {
+    commands.spawnTables(given.tables);
+});
+
+/** The fastest of a few runs spawning `tables` into a fresh world. */
+const spawnFastest = async (tables: readonly Table[]): Promise<number> => {
+    let best = Infinity;
+    for (let k = 0; k < 7; k++) {
+        const world = createWorld({ [workers]: 0 });
+        given.tables = tables;
+        const start = performance.now();
+        await world.run(spawnGiven);
+        const time = performance.now() - start;
+        // The first runs warm up.
+        if (k >= 2) best = Math.min(best, time);
+        await world.dispose();
+    }
+    given.tables = [];
+    return best;
+};
+
+const tables = async (components: readonly (typeof position | typeof owner)[]): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    await world.run(build);
+    const { archetypes } = await world.run(tablesOf(components));
+    await world.dispose();
+    return spawnFastest(archetypes);
+};
+
+/** The fastest of a few runs of `build` in a fresh world. */
+const commanded = async (): Promise<number> => {
+    let best = Infinity;
+    for (let k = 0; k < 7; k++) {
+        const world = createWorld({ [workers]: 0 });
+        const start = performance.now();
+        await world.run(build);
+        const time = performance.now() - start;
+        if (k >= 2) best = Math.min(best, time);
+        await world.dispose();
+    }
+    return best;
+};
+
+export const tableBenchmarks: readonly Benchmark[] = [
+    {
+        name: "spawn tables 1M owner",
+        operation: "commands.spawnTables of 1M entities into a fresh world, each but one owned by another of them, and its sync point: loading a snapshot of a hierarchy.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 36, basis: "Each entity copies its 12-byte position and 8-byte owner, and writes its 8-byte entity and location." },
+        run: () => tables([position, owner]),
+    },
+    {
+        name: "spawn tables 1M",
+        operation: "As `spawn tables 1M owner`, without the owner reference: its cost is the difference.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 28, basis: "Each entity copies its 12-byte position, and writes its 8-byte entity and location." },
+        run: () => tables([position]),
+    },
+    {
+        name: "spawn owned 1M",
+        operation: "A main-thread system spawning 1M entities through one spawner, each but one owned by an earlier one, and its sync point.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 36, basis: "Each entity writes its 12-byte position and 8-byte owner, its 8-byte entity and location." },
+        run: commanded,
+    },
+];

package/src/world.test.ts

@@ -23,7 +23,7 @@ describe("World.create", () => {
         await world.run(spawn);
         await world.run(add);
         let seen = 0;
-        await world.run(System.create({ observer: true, components: { with: [count] } }, row => { seen = row[count]; }));
+        await world.run(System.create({ readonly: true, components: { with: [count] } }, row => { seen = row[count]; }));
         expect(seen).toBe(2);
     });
     it("rejects a key that isn't a resource, as worlds the implementation creates do", () => {
@@ -40,7 +40,7 @@ describe("World.join", () => {
         await shared;
         await joined.run(raise);
         let seen = 0;
-        await world.run(System.create({ observer: true }, ({ resources }) => { seen = resources[total]; }));
+        await world.run(System.create({ readonly: true }, ({ resources }) => { seen = resources[total]; }));
         expect(seen).toBe(7);
     });
 });

package/src/world.ts

@@ -0,0 +1,32 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { create as createWorld, join as joinWorld } from './implementation/index.js';
+import type { Create } from './interface/world/create.js';
+import type { Join } from './interface/world/join.js';
+
+export type { Table } from './interface/world/table/table.js';
+
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
+ * @function
+ */
+export const create: Create = createWorld;
+
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * readonly systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
+ * @function
+ */
+export const join: Join = joinWorld;