@adobe/ecs 0.2.3 → 0.3.0

package/src/perftest/benchmarks.ts

@@ -35,6 +35,8 @@ 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";
+import { chainedBenchmarks } from "./chained.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 });
@@ -648,6 +650,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 +723,6 @@ export const benchmarks: readonly Benchmark[] = [
     ...sharedBenchmarks,
     ...invariantBenchmarks,
     ...journalBenchmarks,
+    ...tableBenchmarks,
+    ...chainedBenchmarks,
 ];

package/src/perftest/chained.ts

@@ -0,0 +1,108 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+import { fastest } from "./suite.js";
+
+// Eight systems over rows no entity has, each with a command its body never issues, run alone or ordered one after
+// another: what orderings and the sync points they need cost a frame whose commands don't fire.
+
+const event = Symbol("chained/event");
+const note = Symbol("chained/note");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [event]: { type: true };
+        [note]: { type: true };
+    }
+}
+
+/** Never true, so no body issues its command. */
+let firing = false;
+/** Systems in each composite. */
+const length = 8;
+/** Runs in each timed sample. */
+const runs = 100;
+
+/** A system spawning, when firing, what each of the composite's systems matches. */
+const commanding = (after: readonly System[]): System => System.create({ components: { with: [event] }, after }, (_row, { commands }) => {
+    if (firing) commands.spawn([event])();
+});
+/** A system spawning, when firing, what none of them matches. */
+const noting = (after: readonly System[]): System => System.create({ components: { with: [event] }, after }, (_row, { commands }) => {
+    if (firing) commands.spawn([note])();
+});
+const quiet = (after: readonly System[]): System => System.create({ components: { with: [event] }, after }, () => {});
+
+/** `length` systems made by `make`, each after the one before when `ordered`. */
+const composite = (make: (after: readonly System[]) => System, ordered: boolean): System => {
+    const systems: System[] = [];
+    for (let k = 0; k < length; k++) {
+        const previous = systems[k - 1];
+        systems.push(make(ordered && previous !== undefined ? [previous] : []));
+    }
+    return System.create(systems);
+};
+
+const unordered = composite(commanding, false);
+const chainedQuiet = composite(quiet, true);
+const chainedNoting = composite(noting, true);
+const chainedCommanding = composite(commanding, true);
+
+const check = (condition: boolean, message: string): void => {
+    if (!condition) throw new Error(message);
+};
+
+const timed = (system: System, tiers: number, syncs: number) => async (): Promise<number> => {
+    const { tiers: scheduled } = System.describe(system);
+    check(scheduled.length === tiers && scheduled.filter(tier => tier.sync !== null).length === syncs, `chained: ${scheduled.length} tiers and ${scheduled.filter(tier => tier.sync !== null).length} sync points`);
+    firing = false;
+    const world = createWorld({ [workers]: 0 });
+    try {
+        return await fastest(async () => { for (let k = 0; k < runs; k++) await world.run(system); });
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+const runBest = { bytes: 64, basis: "A run reads at least one cache line of its system's state." };
+
+export const chainedBenchmarks: readonly Benchmark[] = [
+    {
+        name: "chained unordered",
+        operation: "Running eight systems no entity matches, each with a command it never issues, unordered: one tier, and a sync point at the run's end that applies nothing.",
+        per: "runs",
+        n: runs,
+        typical: [1, 1],
+        best: runBest,
+        run: timed(unordered, 1, 0),
+    },
+    {
+        name: "chained quiet",
+        operation: "Running eight systems no entity matches, without commands, each after the one before: eight tiers and no sync point between them, as orderings that only settle conflicts make.",
+        per: "runs",
+        n: runs,
+        typical: [1, 1],
+        best: runBest,
+        run: timed(chainedQuiet, length, 0),
+    },
+    {
+        name: "chained noting",
+        operation: "Running eight systems no entity matches, each after the one before, each with a command it never issues of what none of them matches: eight tiers, no sync point between them.",
+        per: "runs",
+        n: runs,
+        typical: [1, 1],
+        best: runBest,
+        run: timed(chainedNoting, length, 0),
+    },
+    {
+        name: "chained commanding",
+        operation: "Running eight systems no entity matches, each after the one before, each with a command it never issues of what the next matches: eight tiers and seven sync points that apply nothing.",
+        per: "runs",
+        n: runs,
+        typical: [1, 1],
+        best: runBest,
+        run: timed(chainedCommanding, length, length - 1),
+    },
+];

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/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,
+    },
+];