@adobe/ecs 0.2.4 → 0.3.0

package/src/interface/system/render.ts

@@ -11,7 +11,7 @@ import type { Body } from './body.js';
 import type { ReturnsNoPromise } from './input.js';
 import { accessorsOf } from '../gpu/accessors.js';
 import { checkLeaf } from './check.js';
-import { accessOf, compact, resourceUses } from './resolve.js';
+import { accessOf, compact, noCommands, resourceUses } from './resolve.js';
 import type { Leaf } from './leaf.js';
 import type { StructComponent } from './struct.js';
 import type { Shared } from '../component/value.js';
@@ -96,7 +96,7 @@ export const render = <const D extends RenderDeclaration, B extends Body<D>>(
         },
         input: undefined,
         body,
-        commands: undefined,
+        commands: noCommands,
     };
     if (uses.write.length > 0 || uses.reduce.length > 0) throw new Error(`${what} writes or reduces into resources; a render system only reads.`);
     checkLeaf(system);

package/src/interface/system/resolve.test.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import "../registry/declarations.js";
-import { componentLists, lookupsLists, resourceUses, type Access } from "./resolve.js";
+import { commandListsOf, componentLists, lookupsLists, resourceUses, type Access } from "./resolve.js";
 
 const mass = Symbol("resolveTest/mass");
 const pool = Symbol("resolveTest/pool");
@@ -47,3 +47,19 @@ describe("resourceUses", () => {
         expect(() => resourceUses("System \"s\"", changing(pool), undefined)).not.toThrow();
     });
 });
+
+describe("commandListsOf", () => {
+    const commanding = (commands: () => unknown): Access => ({ components: null, resources: null, lookup: null, up: null, commands, at: "a test" });
+    it("reads what the commands name at the first call, once", () => {
+        let reads = 0;
+        const lists = commandListsOf("System \"s\"", commanding(() => { reads++; return { spawn: [[mass, position]], add: [mass], remove: [], despawn: false }; }));
+        expect(reads).toBe(0);
+        expect([lists(), lists(), reads]).toEqual([{ spawn: [mass, position], add: [mass] }, { spawn: [mass, position], add: [mass] }, 1]);
+    });
+    it("names the system and the declaration its commands name before it's initialized", () => {
+        for (const message of ["Cannot access 'standard' before initialization", "can't access lexical declaration 'standard' before initialization"]) {
+            const lists = commandListsOf("System \"s\"", commanding(() => { throw new ReferenceError(message); }));
+            expect(lists).toThrow(`System "s" names "standard" in its commands before it's initialized: declare it above the system.`);
+        }
+    });
+});

package/src/interface/system/resolve.ts

@@ -23,7 +23,10 @@ export type Access = {
     readonly up: readonly Key[] | null;
     /** The resources the predicates of its declaration's `where` read; absent without predicates. */
     readonly where?: readonly Key[] | null;
-    /** What its commands name, keys or lists of them, by kind, and whether it despawns; absent where no build said. */
+    /**
+     * What its commands name, keys or lists of them, by kind, and whether it despawns, or a function giving that; absent
+     * where no build said.
+     */
     readonly commands?: unknown;
     readonly at: string;
 };
@@ -35,7 +38,7 @@ const isKeys = (value: unknown): value is readonly Key[] => Array.isArray(value)
 
 const isNamed = (value: unknown): value is Named => Array.isArray(value) && value.every(item => typeof item === "symbol" || isKeys(item));
 
-/** A binding a command named that holds neither a key nor a list of them, as one declared below its system, isn't followed. */
+/** A binding a command named that holds neither a key nor a list of them isn't followed. */
 const isCommanded = (value: unknown): value is Commanded => typeof value === "object" && value !== null
     && isNamed(Reflect.get(value, "spawn")) && isNamed(Reflect.get(value, "add")) && isNamed(Reflect.get(value, "remove"))
     && typeof Reflect.get(value, "despawn") === "boolean";
@@ -173,9 +176,28 @@ export const whereReadsOf = (what: string, components: ComponentAccess | undefin
     return reads;
 };
 
-/** What a body's commands name, as the world takes it: null where the build couldn't follow them, nothing for none. */
-export const commandLists = (access: Access): CommandLists | null | undefined => {
-    const { commands } = access;
+/**
+ * What a body's commands name, as the world takes it, read at the first call and kept: null where the build couldn't
+ * follow them, nothing for none. The build gives them as a function, so a list declared below the system is read once
+ * its module has loaded; one still uninitialized then, as an import cycle leaves it, throws naming it.
+ */
+export const commandListsOf = (what: string, access: Access): (() => CommandLists | null | undefined) => {
+    let read = false;
+    let lists: CommandLists | null | undefined;
+    return () => {
+        if (!read) {
+            lists = listsOf(what, access.commands);
+            read = true;
+        }
+        return lists;
+    };
+};
+
+/** The command lists of a system whose body issues none. */
+export const noCommands = (): undefined => undefined;
+
+const listsOf = (what: string, given: unknown): CommandLists | null | undefined => {
+    const commands = typeof given === "function" ? evaluated(what, () => Reflect.apply(given, undefined, [])) : given;
     if (commands === undefined) return undefined;
     if (!isCommanded(commands)) return null;
     if (!commands.despawn && commands.spawn.length + commands.add.length + commands.remove.length === 0) return undefined;
@@ -184,5 +206,18 @@ export const commandLists = (access: Access): CommandLists | null | undefined =>
     return Object.keys(lists).length === 0 ? undefined : lists;
 };
 
+/** What the build's function of a body's commands gives. */
+const evaluated = (what: string, commands: () => unknown): unknown => {
+    try {
+        return commands();
+    } catch (error) {
+        if (!(error instanceof ReferenceError)) throw error;
+        // Engines quote the binding in the message: "Cannot access 'standard' before initialization", or "can't access
+        // lexical declaration 'standard' before initialization".
+        const binding = /'([A-Za-z_$][\w$]*)'/.exec(error.message)?.[1];
+        throw new Error(`${what} names ${binding === undefined ? "a declaration" : `"${binding}"`} in its commands before it's initialized: declare it above the system.`, { cause: error });
+    }
+};
+
 /** What a body reads of its parent's values. */
 export const upReads = (what: string, access: Access): readonly Key[] => followed(what, access.up, "its parent's values", access);

package/src/interface/system/system.type-test.ts

@@ -154,6 +154,12 @@ System.create({
     // @ts-expect-error ordering takes systems
     after: ["test/unregistered"],
 }, () => {});
+// Ordering by a resource: before or after every other system of the composite that uses it.
+System.create({ before: [time], after: [integrate, score] }, ({ resources }) => { resources[time] = resources[score]; });
+System.create({
+    // @ts-expect-error ordering takes systems and resources, not components
+    after: [position],
+}, () => {});
 
 // @ts-expect-error a system with input can't use change filters
 System.create({ components: { changed: [position] } }, (_row, _context, input: { readonly distance: number }) => { void input; });

package/src/perftest/benchmarks.ts

@@ -36,6 +36,7 @@ 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 });
@@ -723,4 +724,5 @@ export const benchmarks: readonly Benchmark[] = [
     ...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),
+    },
+];