@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,63 @@
+import type { World } from '../world/world.js';
+import { System } from './system.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+const move = System.create({
+    name: "compositeInputTest/move",
+    input: { type: "object", properties: { distance: { type: "number" } } },
+}, ({ input }) => { void input.distance; });
+const step = System.create({
+    name: "compositeInputTest/step",
+    input: { type: "object", properties: { distance: { type: "number" }, dt: { type: "number" } } },
+}, ({ input }) => { void input.dt; });
+const pause = System.create({
+    name: "compositeInputTest/pause",
+    input: { type: "object", properties: { dt: { type: "number" } }, required: [] },
+}, ({ input }) => { void input.dt; });
+const label = System.create({
+    name: "compositeInputTest/label",
+    input: { type: "object", properties: { distance: { type: "string" } } },
+}, ({ input }) => { void input.distance; });
+const idle = System.create({ name: "compositeInputTest/idle" }, () => {});
+
+// A composite takes every field its members' inputs have; a field in several is one value for all of them.
+const frame = System.create({ name: "compositeInputTest/frame", systems: [move, step, idle] });
+check<Equal<typeof frame, System<{ readonly distance: number; readonly dt: number }>>>();
+
+// A field optional in one member and required in another is required.
+const paused = System.create({ name: "compositeInputTest/paused", systems: [pause, step] });
+check<Equal<typeof paused, System<{ readonly dt: number; readonly distance: number }>>>();
+
+// Nested composites take their members' fields too.
+const outer = System.create({ name: "compositeInputTest/outer", systems: [System.create({ name: "compositeInputTest/inner", systems: [move] }), pause] });
+check<Equal<typeof outer, System<{ readonly distance: number; readonly dt?: number }>>>();
+
+// A composite without a name or constraints is its list of members.
+const listed = System.create([move, step, idle]);
+check<Equal<typeof listed, System<{ readonly distance: number; readonly dt: number }>>>();
+const constrained = System.create({ systems: [pause], after: [listed] });
+check<Equal<typeof constrained, System<{ readonly dt?: number }>>>();
+
+// Without inputs, a composite takes none.
+const quiet = System.create({ name: "compositeInputTest/quiet", systems: [idle] });
+check<Equal<typeof quiet, System>>();
+
+// @ts-expect-error a field with different types in two members is an error at the member
+System.create({ name: "compositeInputTest/conflict", systems: [move, label] });
+// @ts-expect-error in a list of members too
+System.create([move, label]);
+// @ts-expect-error a composite declaration lists its systems
+System.create({ name: "compositeInputTest/empty", after: [move] });
+
+declare const world: World;
+void world.run(frame, { distance: 1, dt: 0.5 });
+// @ts-expect-error run takes every field
+void world.run(frame, { distance: 1 });
+
+System.create({
+    name: "compositeInputTest/scalar",
+    // @ts-expect-error input is an object of named fields
+    input: { type: "number" },
+}, () => {});

package/src/interface/system/composite.ts

@@ -0,0 +1,5 @@
+import type { CompositeDeclaration } from './composite-declaration.js';
+import type { Name } from './name.js';
+
+/** A system made of subsystems; members are flattened and ordered by their constraints. */
+export type Composite = { readonly kind: "composite"; readonly name: Name; readonly declaration: CompositeDeclaration };

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

@@ -0,0 +1,68 @@
+import { Resource } from '../resource/resource.js';
+import { Component } from '../component/component.js';
+import { System } from './system.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+const paused = Symbol("conditionsTypeTest/paused");
+const level = Symbol("conditionsTypeTest/level");
+const cache = Symbol("conditionsTypeTest/cache");
+const count = Symbol("conditionsTypeTest/count");
+const handle = Symbol("conditionsTypeTest/handle");
+const position = Symbol("conditionsTypeTest/position");
+
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [paused]: { type: boolean };
+        [level]: { type: { readonly size: number } | null };
+        [cache]: { type: Map<string, number> | null };
+        [count]: { type: number };
+        [handle]: { type: Map<string, number> };
+    }
+    export interface Components {
+        [position]: { type: number };
+    }
+}
+Resource.register(handle, { default: new Map() });
+Resource.register(level, { type: { anyOf: [{ type: "object", properties: { size: { type: "number" } } }, { type: "null" }], default: null } });
+Resource.register(paused, { type: { type: "boolean", default: false } });
+Resource.register(cache, {});
+Resource.register(count, { type: { type: "number", default: 0 } });
+Component.register(position, { type: { type: "number" } });
+
+// `is`: runs while each is neither null nor false, and reads it narrowed so.
+System.create({ name: "conditionsTypeTest/loaded", resources: { is: [level, cache] } }, ({ resources }) => {
+    check<Equal<typeof resources[typeof level], { readonly size: number }>>();
+    check<Equal<typeof resources[typeof cache], Map<string, number>>>();
+    // @ts-expect-error a condition is read-only
+    resources[level] = null;
+});
+System.create({ name: "conditionsTypeTest/playing", resources: { is: [paused] } }, ({ resources }) => {
+    check<Equal<typeof resources[typeof paused], true>>();
+});
+
+// `not`: runs while each is null or false; its value is known, so it isn't readable.
+System.create({ name: "conditionsTypeTest/running", components: { write: [position] }, resources: { not: [paused] } }, (row, context) => {
+    row[position] += 1;
+    // @ts-expect-error a `not` condition isn't readable
+    void context.resources;
+});
+
+// Only a resource whose type allows null or false is a condition.
+// @ts-expect-error a number is never null or false
+System.create({ name: "conditionsTypeTest/counted", resources: { is: [count] } }, () => {});
+// @ts-expect-error a value that isn't data and doesn't allow null is never null
+System.create({ name: "conditionsTypeTest/handled", resources: { not: [handle] } }, () => {});
+
+// A condition is listed once: `is` already makes it readable, and a written value would have two types.
+// @ts-expect-error both is and not
+System.create({ name: "conditionsTypeTest/both", resources: { is: [paused], not: [paused] } }, () => {});
+// @ts-expect-error is already makes it readable
+System.create({ name: "conditionsTypeTest/read", resources: { is: [level], read: [level] } }, () => {});
+// @ts-expect-error a condition isn't written
+System.create({ name: "conditionsTypeTest/write", resources: { is: [level], write: [level] } }, () => {});
+
+// Kernels and render systems take conditions too.
+System.create({ name: "conditionsTypeTest/kernel", kernel: "cpu", components: { write: [position] }, resources: { not: [paused] } }, row => { row[position] += 1; });
+System.render({ name: "conditionsTypeTest/draw", resources: { is: [level] }, shader: { accessors: { place: position } } }, () => {});

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

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../component/component.js";
+import { Entity } from "../entity/entity.js";
+import { definitionOf, firstItemOf, labelOfItem, requireDefinition, sameItem, scheduleOf, threadOf } from "../registry/index.js";
+import { identify } from "../registry/ids.test-helper.js";
+import { Resource } from "../resource/resource.js";
+import { clock, gpuDevice } from "../resources/index.js";
+import { System } from "./system.js";
+
+const position = Symbol("typesSystemTest/position");
+const label = Symbol("typesSystemTest/label");
+const node = Symbol("typesSystemTest/node");
+const document = Symbol("typesSystemTest/document");
+const time = Symbol("typesSystemTest/time");
+const unregistered = Symbol("typesSystemTest/unregistered");
+const parent = Symbol("typesSystemTest/parent");
+const total = Symbol("typesSystemTest/total");
+const paused = Symbol("typesSystemTest/paused");
+const height = Symbol("typesSystemTest/height");
+const tags = Symbol("typesSystemTest/tags");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [label]: { type: string };
+        [node]: { type: HTMLElement; thread: "main" };
+        [unregistered]: { type: number };
+        [parent]: { type: Entity; reference: "weak" };
+        [height]: { type: number };
+        [tags]: { type: readonly string[] };
+    }
+    export interface Resources {
+        [document]: { type: Document | null; thread: "main" };
+        [time]: { type: number };
+        [total]: { type: number; reduce: "+" };
+        [paused]: { type: boolean };
+    }
+}
+
+Component.register(position, { type: { type: "number" } });
+Component.register(label, { type: { type: "string" } });
+Component.register(node, { thread: "main" });
+Component.register(tags, { type: { type: "array", items: { type: "string" } } });
+Resource.register(document, { thread: "main" });
+Resource.register(time, { type: { type: "number", default: 0 } });
+Component.register(parent, { type: Entity.schema, reference: "weak" });
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
+Resource.register(paused, { type: { type: "boolean", default: false } });
+Component.register(height, { type: { type: "number", precision: 1 } });
+
+/** Creates as an untyped caller would, bypassing the types' checks. */
+const create = (declaration: object): unknown => Reflect.apply(System.create, undefined, [declaration, () => {}]);
+
+describe("System.create", () => {
+    it("records the system, its value holding its declaration and body", () => {
+        const body = (): void => {};
+        const move = System.create({ name: "typesSystemTest/move", components: { write: [position] }, resources: { read: [time] } }, body);
+        expect(definitionOf(move)).toEqual({ kind: "system", name: "typesSystemTest/move", declaration: { name: "typesSystemTest/move", components: { write: [position] }, resources: { read: [time] } }, body });
+        expect(labelOfItem(move)).toBe("typesSystemTest/move");
+        expect(definitionOf({ name: "typesSystemTest/move" })).toBe(undefined);
+    });
+    it("keeps systems of one name apart, labeling each by its name numbered", () => {
+        const first = System.create({ name: "typesSystemTest/twice", components: { read: [position] } }, row => { void row[position]; });
+        expect(labelOfItem(first)).toBe("typesSystemTest/twice");
+        const again = System.create({ name: "typesSystemTest/twice", components: { read: [position] } }, row => { void row[position]; });
+        const other = System.create({ name: "typesSystemTest/twice", components: { write: [position] } }, row => { row[position] = 0; });
+        expect(sameItem(first, again)).toBe(false);
+        expect([first, again, other].map(labelOfItem)).toEqual(["typesSystemTest/twice", "typesSystemTest/twice#2", "typesSystemTest/twice#3"]);
+        expect(scheduleOf(requireDefinition(System.create({ name: "typesSystemTest/twice", systems: [first, again] }))).tiers.flat()).toEqual([first, again]);
+    });
+    it("labels systems of one name by name and id, and takes a declaration of a registered id, the same, as the same system", () => {
+        const declare = (id: string, write: boolean) => System.create(identify({ name: "typesSystemTest/linked", components: write ? { write: [position] } : { read: [position] } }, id), () => {});
+        const first = declare("a.ts#linked", false);
+        const elsewhere = declare("b.ts#linked", false);
+        expect([labelOfItem(first), labelOfItem(elsewhere)]).toEqual(["typesSystemTest/linked (a.ts#linked)", "typesSystemTest/linked (b.ts#linked)"]);
+        const again = declare("a.ts#linked", false);
+        expect(again).not.toBe(first);
+        expect([sameItem(first, again), sameItem(first, elsewhere), firstItemOf(again)]).toEqual([true, false, first]);
+        expect(labelOfItem(again)).toBe("typesSystemTest/linked (a.ts#linked)");
+        const write = System.create({ name: "typesSystemTest/afterLinked", components: { write: [position] }, after: [again] }, row => { row[position] = 0; });
+        const tiers = scheduleOf(requireDefinition(System.create({ name: "typesSystemTest/linkedFrame", systems: [write, first, again] }))).tiers;
+        expect(tiers).toEqual([[first], [write]]);
+        expect(() => declare("a.ts#linked", true)).toThrow('Cannot declare "typesSystemTest/linked" (a.ts#linked): its id is another item\'s, with another declaration; if a module was evaluated again with a changed declaration, reload the page.');
+        expect(() => System.create(identify({ name: "typesSystemTest/linked", systems: [first] }, "a.ts#linked"))).toThrow("its id is a system's");
+        expect(labelOfItem(declare("c.ts#linked", false))).toBe("typesSystemTest/linked (c.ts#linked)");
+    });
+    it("names a system declared without a name by its binding and id, or else by its kind numbered", () => {
+        const body = ({ commands }: { readonly commands: System.Commands }): void => { commands.spawn([position])({ [position]: 0 }); };
+        const alone = System.create(identify(body, "setup.ts#spawnOnce"));
+        expect(definitionOf(alone)).toEqual({ kind: "system", name: "spawnOnce (setup.ts#spawnOnce)", declaration: {}, body });
+        expect(labelOfItem(alone)).toBe("spawnOnce (setup.ts#spawnOnce)");
+        expect(sameItem(System.create(identify(body, "setup.ts#spawnOnce")), alone)).toBe(true);
+        const show = System.create(identify({ components: { read: [position] } }, "show.ts#show"), row => { void row[position]; });
+        expect(labelOfItem(show)).toBe("show (show.ts#show)");
+        const [first, second] = [System.create(() => {}), System.create({ systems: [show] })].map(labelOfItem);
+        const number = Number(first?.slice("system #".length));
+        expect([first, second]).toEqual([`system #${number}`, `system #${number + 1}`]);
+        expect(labelOfItem(System.render({ shader: { accessors: {} } }, () => {}))).toBe(`system #${number + 2}`);
+        expect(() => create({ components: { read: [position], write: [position] } })).toThrow(`System "system #${number + 3}" lists "typesSystemTest/position" in both components read and write`);
+    });
+    it("rejects writing what only the world writes, for untyped callers", () => {
+        expect(() => create({ name: "typesSystemTest/clock", resources: { write: [clock] } })).toThrow(`writes "clock", which only the world writes`);
+    });
+    it("rejects what types reject, for untyped callers", () => {
+        expect(() => create({ name: "typesSystemTest/both", components: { read: [position], write: [position] } })).toThrow("in both components read and write");
+        expect(() => create({ name: "typesSystemTest/bothResources", resources: { read: [time], write: [time] } })).toThrow("in both resources read and write");
+        expect(() => create({ name: "typesSystemTest/lookup", components: { write: [position] }, lookup: { others: { read: [position] } } })).toThrow('lookup "others" reads "typesSystemTest/position", which the system writes');
+        expect(() => create({ name: "typesSystemTest/input", input: { type: "number" } })).toThrow("input is an object schema of named fields");
+        expect(labelOfItem(System.create({ name: "typesSystemTest/both" }, () => {}))).toBe("typesSystemTest/both");
+    });
+    it("rejects at creation what the registry rules out, for untyped callers", () => {
+        const rejected: readonly (readonly [object, string])[] = [
+            [{ components: { read: [position], has: [unregistered] } }, `uses component "typesSystemTest/unregistered", which isn't a registered component`],
+            [{ components: { read: [position] }, lookup: { others: { read: [position], not: [unregistered] } } }, `uses component "typesSystemTest/unregistered", which isn't a registered component`],
+            [{ components: { read: [position] }, lookup: { others: { read: [position], changed: [height] } } }, `lookup "others" watches "typesSystemTest/height", which it neither reads nor has`],
+            [{ components: { write: [parent] } }, `writes "typesSystemTest/parent", a reference, which changes only through commands`],
+            [{ components: { has: [position] }, reduce: { [total]: "max" } }, `reduces "typesSystemTest/total" with "max", but it's declared reduce: "+"`],
+            [{ components: { has: [position] }, reduce: { [time]: "+" } }, `reduces "typesSystemTest/time", which has no reduce trait`],
+            [{ resources: { write: [total] } }, `writes "typesSystemTest/total", which is reduced`],
+            [{ components: { has: [position] }, resources: { read: [total] }, reduce: { [total]: "+" } }, `reduces "typesSystemTest/total", so it can't also read, write or filter on it`],
+            [{ resources: { is: [time] } }, `runs on the condition of "typesSystemTest/time", which is never null or false`],
+            [{ resources: { not: [position] } }, `runs on the condition of "typesSystemTest/position", which isn't a registered resource`],
+            [{ resources: { is: [paused], not: [paused] } }, `lists "typesSystemTest/paused" in both resources is and not`],
+            [{ resources: { is: [paused], read: [paused] } }, `lists "typesSystemTest/paused" in resources is and in read or write; is already makes it readable`],
+            [{ components: { write: [position] }, up: { through: position, read: [position] } }, `up.through "typesSystemTest/position" isn't a reference component`],
+            [{ up: { through: parent } }, "uses up, which orders rows, without components"],
+            [{ kernel: "gpu", components: { write: [position], changed: [position] } }, "can't run on the GPU: GPU kernels don't support change filters yet"],
+            [{ kernel: "gpu", components: { read: [position] }, lookup: { others: { read: [position] } } }, "can't run on the GPU: GPU kernels don't support lookups yet"],
+            [{ kernel: "gpu", components: { has: [position] }, reduce: { [total]: "+" } }, "can't run on the GPU: GPU kernels don't support reductions yet"],
+            [{ observer: false, resources: { read: [time] } }, "observer is true or left out"],
+            [{ observer: true, components: { write: [position] } }, "is an observer, so it writes nothing"],
+            [{ observer: true, resources: { write: [time] } }, "is an observer, so it writes nothing"],
+            [{ observer: true, components: { has: [position] }, reduce: { [total]: "+" } }, "is an observer, so it reduces into nothing"],
+            [{ observer: true, input: { type: "object", properties: {} } }, "is an observer, so it takes no input"],
+            [{ observer: true, kernel: "cpu", components: { read: [position] } }, "is an observer, so it isn't a kernel"],
+            [{ observer: true, components: { read: [position] }, up: { through: parent } }, "is an observer, so it has no up"],
+            [{ observer: true, resources: { read: [time] }, after: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
+            [{ observer: true, resources: { read: [time] }, before: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
+            [{ observer: true, resources: { read: [time] }, during: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
+        ];
+        rejected.forEach(([declaration, message], index) => {
+            expect(() => create({ name: `typesSystemTest/rejected/${index}`, ...declaration })).toThrow(message);
+            // A rejected system records nothing, so its name labels only the next.
+            expect(labelOfItem(System.create({ name: `typesSystemTest/rejected/${index}` }, () => {}))).toBe(`typesSystemTest/rejected/${index}`);
+        });
+    });
+    it("derives its thread from its object components and resources, and rejects two", () => {
+        const show = System.create({ name: "typesSystemTest/show", components: { read: [position, node] }, resources: { read: [time, document] } }, (row, { resources }) => { row[node].textContent = `${row[position]} ${resources[time]} ${resources[document]?.title}`; });
+        const count = System.create({ name: "typesSystemTest/count", components: { read: [tags], has: [node] } }, row => { void row[tags]; });
+        const tick = System.create({ name: "typesSystemTest/tick", components: { write: [position] } }, row => { row[position] += 1; });
+        const leaves = [show, count, tick].map(system => definitionOf(system));
+        expect(leaves.map(leaf => leaf === undefined || leaf.kind === "composite" ? undefined : threadOf(leaf.declaration, "System", leaf.name))).toEqual(["main", "world", null]);
+        expect(() => create({ name: "typesSystemTest/span", components: { read: [tags], write: [node] } })).toThrow('System "typesSystemTest/span" uses "typesSystemTest/tags" on "world" and "typesSystemTest/node" on "main"');
+        expect(() => create({ name: "typesSystemTest/spanResource", components: { read: [tags] }, resources: { is: [document] } })).toThrow('uses "typesSystemTest/tags" on "world" and "typesSystemTest/document" on "main"');
+        // A string lives in shared memory, so it goes with any thread's objects.
+        const caption = System.create({ name: "typesSystemTest/caption", components: { read: [label, node] } }, row => { row[node].textContent = row[label]; });
+        const captionLeaf = definitionOf(caption);
+        expect(captionLeaf === undefined || captionLeaf.kind === "composite" ? undefined : threadOf(captionLeaf.declaration, "System", captionLeaf.name)).toBe("main");
+        expect(() => create({ name: "typesSystemTest/unregistered", components: { read: [unregistered] } })).toThrow(`uses component "typesSystemTest/unregistered", which isn't a registered component`);
+        expect(() => create({ name: "typesSystemTest/wrongKind", components: { read: [time] } })).toThrow(`uses component "typesSystemTest/time", which isn't a registered component`);
+    });
+});
+
+describe("System.create of a composite", () => {
+    it("records a composite whose members may live on different threads, from its list or its declaration", () => {
+        const show = System.create({ name: "typesSystemTest/showMember", components: { read: [node] } }, row => { row[node].hidden = true; });
+        const name = System.create({ name: "typesSystemTest/nameMember", components: { write: [label] } }, row => { row[label] = ""; });
+        const frame = System.create({ name: "typesSystemTest/frame", systems: [show, name] });
+        expect(definitionOf(frame)?.kind).toBe("composite");
+        expect(definitionOf(System.create({ name: "typesSystemTest/frame", systems: [show] }))).not.toBe(definitionOf(frame));
+        const listed = System.create([show, name]);
+        const listedDefinition = definitionOf(listed);
+        expect(listedDefinition?.kind === "composite" ? listedDefinition.declaration.systems : undefined).toEqual([show, name]);
+        expect(listed.name).toMatch(/^system #\d+$/);
+    });
+    it("tells a composite's declaration from a system's by its body", () => {
+        const untyped: (...parameters: never[]) => unknown = System.create;
+        expect(() => Reflect.apply(untyped, undefined, [{ name: "typesSystemTest/bodiless" }])).toThrow("A system needs a body, and a composite its systems.");
+        const leaf = Reflect.apply(untyped, undefined, [{ name: "typesSystemTest/leafWithSystems", systems: [] }, () => {}]);
+        expect(definitionOf(leaf)?.kind).toBe("system");
+    });
+    it("rejects members ordered in a cycle, and conflicting members with no order between them", () => {
+        const first = System.create({ name: "typesSystemTest/first", components: { write: [position] } }, row => { row[position] += 1; });
+        const second = System.create({ name: "typesSystemTest/second", components: { read: [position] }, after: [first] }, row => { void row[position]; });
+        const third = System.create({ name: "typesSystemTest/third", components: { read: [position] } }, row => { void row[position]; });
+        expect(scheduleOf(requireDefinition(System.create({ name: "typesSystemTest/ordered", systems: [second, first] }))).tiers.map(tier => tier.map(leaf => leaf.name))).toEqual([["typesSystemTest/first"], ["typesSystemTest/second"]]);
+        expect(() => System.create({ name: "typesSystemTest/unordered", systems: [first, third] })).toThrow('Systems "typesSystemTest/first" and "typesSystemTest/third" both access "typesSystemTest/position" and one writes it');
+        const looped = System.create({ name: "typesSystemTest/looped", before: [first], after: [second] }, () => {});
+        expect(() => System.create({ name: "typesSystemTest/cycle", systems: [first, second, looped] })).toThrow("Ordering cycle");
+        expect(labelOfItem(System.create({ name: "typesSystemTest/unordered", systems: [first] }))).toBe("typesSystemTest/unordered");
+    });
+    it("runs observer members after its sync point, in no tier, never conflicting and ignoring constraints naming them", () => {
+        const write = System.create({ name: "typesSystemTest/observerWriter", components: { write: [position] } }, row => { row[position] += 1; });
+        const watch = System.create({ name: "typesSystemTest/observer", observer: true, components: { read: [position] } }, row => { void row[position]; });
+        const later = System.create({ name: "typesSystemTest/afterObserver", components: { read: [position] }, after: [watch, write] }, row => { void row[position]; });
+        const free = System.create({ name: "typesSystemTest/afterObserverOnly", resources: { read: [time] }, after: [watch] }, ({ resources }) => { void resources[time]; });
+        const schedule = scheduleOf(requireDefinition(System.create([write, watch, later, free])));
+        expect(schedule.tiers.map(tier => tier.map(leaf => leaf.name))).toEqual([["typesSystemTest/observerWriter", "typesSystemTest/afterObserverOnly"], ["typesSystemTest/afterObserver"]]);
+        expect(schedule.observer.map(leaf => leaf.name)).toEqual(["typesSystemTest/observer"]);
+        const alone = scheduleOf(requireDefinition(watch));
+        expect([alone.tiers.length, alone.observer.map(leaf => leaf.name)]).toEqual([0, ["typesSystemTest/observer"]]);
+    });
+    it("rejects a member no constructor returned, and an input field two members declare differently", () => {
+        expect(() => System.create({ name: "typesSystemTest/forged", systems: [{ name: "typesSystemTest/showMember" }] })).toThrow('member "typesSystemTest/showMember" isn\'t a system a System constructor returned');
+        const move = System.create({ name: "typesSystemTest/moveBy", input: { type: "object", properties: { distance: { type: "number" } } } }, () => {});
+        const tag = System.create({ name: "typesSystemTest/tagBy", input: { type: "object", properties: { distance: { type: "string" } } } }, () => {});
+        const nested = System.create({ name: "typesSystemTest/nested", systems: [tag] });
+        const untyped: (...parameters: never[]) => unknown = System.create;
+        const composite = (declaration: object): unknown => Reflect.apply(untyped, undefined, [declaration]);
+        expect(() => composite({ name: "typesSystemTest/conflict", systems: [move, nested] })).toThrow('Systems "typesSystemTest/moveBy" and "typesSystemTest/tagBy" declare input field "distance" with different schemas.');
+        expect(labelOfItem(System.create({ name: "typesSystemTest/conflict", systems: [move] }))).toBe("typesSystemTest/conflict");
+    });
+});
+
+describe("System.render", () => {
+    it("reads the components its accessors name, once each, and runs only while gpuDevice is set", () => {
+        const draw = System.render({ name: "typesSystemTest/draw", shader: { accessors: { place: height, again: height } } }, () => {});
+        const definition = definitionOf(draw);
+        expect(definition?.kind === "render" ? [definition.declaration.components, definition.declaration.resources] : null).toEqual([{ read: [height] }, { is: [gpuDevice] }]);
+        const render: (declaration: object) => unknown = declaration => Reflect.apply(System.render, undefined, [declaration, () => {}]);
+        expect(() => render({ name: "typesSystemTest/drawDocument", resources: { read: [document] }, shader: { accessors: {} } })).toThrow('uses "typesSystemTest/document" on "main" and "gpuDevice" on "world"');
+    });
+    it("rejects at creation accessors its shader can't read, and reductions", () => {
+        const render: (declaration: object) => unknown = declaration => Reflect.apply(System.render, undefined, [declaration, () => {}]);
+        expect(() => System.render({ name: "typesSystemTest/drawReserved", shader: { accessors: { loop: height } } }, () => {})).toThrow(`System "typesSystemTest/drawReserved" can't render: "loop" isn't usable as a WGSL function name.`);
+        expect(() => render({ name: "typesSystemTest/drawReduced", shader: { accessors: {} }, reduce: { [total]: "+" } })).toThrow("can't reduce: a render system records GPU work rather than running rows");
+        expect(() => render({ name: "typesSystemTest/drawObserver", shader: { accessors: {} }, observer: true })).toThrow("is an observer, so it records no GPU work");
+        expect(labelOfItem(System.render({ name: "typesSystemTest/drawReserved", shader: { accessors: {} } }, () => {}))).toBe("typesSystemTest/drawReserved");
+    });
+});

package/src/interface/system/create.ts

@@ -0,0 +1,181 @@
+import type { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import type { Index } from '../indexes/index-type.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { claimSystem } from '../registry/program.js';
+import type { Resource } from '../resource/resource.js';
+import type { Schema } from '../schema/schema.js';
+import type { Body } from './body.js';
+import type { Commands } from './commands.js';
+import { checkComposite, checkLeaf } from './check.js';
+import type { Composite } from './composite.js';
+import type { CompositeDeclaration } from './composite-declaration.js';
+import type { Declaration } from './declaration.js';
+import type { CheckMembers, CompositeInputOf, InputOf } from './input.js';
+import type { Leaf } from './leaf.js';
+import type { Listed, Property } from './property.js';
+import type { StructComponent, StructResource } from './struct.js';
+import type { System } from './system.js';
+import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
+import type { HeldBy } from './values.js';
+
+type Reduced<D extends Declaration> = keyof Property<D, "reduce"> & Resource.Key;
+type Written<D, K extends "components" | "resources"> = Listed<Property<D, K>, "write">;
+type Is<D> = Listed<Property<D, "resources">, "is">;
+type Lookups<D> = Property<D, "lookup">;
+
+/**
+ * An index lookup reads and watches only what every entity its index holds has, and its system doesn't write what it
+ * finds rows by or reads through it. A lookup by entity watches only what it reads or has.
+ */
+type IndexLookups<D> = {
+    readonly lookup?: {
+        readonly [N in keyof Lookups<D>]?: Lookups<D>[N] extends { readonly index: Index<infer I> }
+            ? {
+                readonly index?: Index<{ readonly key: readonly Exclude<Component.Key, Written<D, "components">>[] }>;
+                readonly read?: readonly Exclude<HeldBy<I>, Written<D, "components">>[];
+                readonly changed?: readonly HeldBy<I>[] | true;
+            }
+            : { readonly changed?: readonly (Listed<Lookups<D>[N], "read"> | Listed<Lookups<D>[N], "has">)[] }
+    };
+};
+
+/** A system's rows are ordered by an index whose key parts it doesn't write. */
+type Order<D> = { readonly order?: Index<{ readonly key: readonly Exclude<Component.Key, Written<D, "components">>[] }> };
+
+/**
+ * A key in `write` is readable too, so it isn't also in `read`. A system doesn't read or filter on what it reduces
+ * into, since the fold is only finished after every contributor runs. A condition in `is` is readable too, and isn't
+ * written or also in `not`.
+ */
+type Lists<D extends Declaration> = {
+    readonly components?: { readonly read?: readonly Exclude<Component.Key, Written<D, "components">>[] };
+    readonly resources?: {
+        readonly read?: readonly Exclude<Resource.Key, Written<D, "resources"> | Reduced<D> | Is<D>>[];
+        readonly write?: readonly Exclude<Resource.Key, Is<D>>[];
+        readonly changed?: readonly Exclude<Resource.Key, Reduced<D>>[];
+        readonly not?: readonly Exclude<Resource.Key, Is<D>>[];
+    };
+};
+
+type Kernel = {
+    readonly components?: { readonly read?: readonly StructComponent[]; readonly write?: readonly StructComponent[] };
+    readonly lookup?: {
+        readonly [name: string]:
+            | { readonly read?: readonly StructComponent[]; readonly has?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly changed?: readonly Component.Key[]; readonly index?: never }
+            | { readonly read?: readonly StructComponent[]; readonly changed?: readonly Component.Key[] | true; readonly index: Index<{ readonly key: readonly StructComponent[] }> };
+    };
+    readonly up?: { readonly read?: readonly StructComponent[] };
+    readonly order?: Index<{ readonly key: readonly StructComponent[] }>;
+    readonly resources?: { readonly read?: readonly StructResource[]; readonly write?: never };
+};
+
+/** What a GPU kernel can't use yet, beyond any kernel's limits. */
+type GpuKernel = {
+    readonly lookup?: { readonly [name: string]: never };
+    readonly components?: { readonly added?: never; readonly changed?: never };
+    readonly resources?: { readonly changed?: never };
+    readonly reduce?: { readonly [K in Resource.Key]?: never };
+    readonly order?: { readonly "error: GPU kernels have no order yet": true };
+};
+
+/**
+ * An observer system only reads, after a sync point: it writes and reduces into nothing, takes no input, isn't a
+ * kernel, has no `up`, and is ordered with nothing.
+ */
+type Observer = {
+    readonly kernel?: never;
+    readonly components?: { readonly write?: never };
+    readonly resources?: { readonly write?: never };
+    readonly reduce?: never;
+    readonly input?: never;
+    readonly up?: never;
+    readonly before?: never;
+    readonly after?: never;
+    readonly during?: never;
+};
+
+/** The fields of input `I` that hold an entity. */
+type EntityFields<I> = { [K in keyof I]-?: [Exclude<I[K], undefined>] extends [Entity] ? K : never }[keyof I] & string;
+
+/** A system on one entity takes it from an entity field of its input, and runs on its row, in no order. */
+type Targeted<D extends Declaration> = {
+    readonly target?: EntityFields<InputOf<D>>;
+    readonly kernel?: never;
+    readonly up?: never;
+    readonly order?: never;
+    readonly reduce?: never;
+};
+
+type Validate<D extends Declaration> =
+    Lists<D>
+    & IndexLookups<D>
+    & Order<D>
+    & (D extends { readonly input: Schema } ? { readonly components?: { readonly added?: never; readonly changed?: never } } : {})
+    & (D extends { readonly kernel: "cpu" | "gpu" } ? Kernel : {})
+    & (D extends { readonly kernel: "gpu" } ? GpuKernel : {})
+    // `up` and `order` order rows, so a system without them has neither, and one has at most one of them.
+    & (Property<D, "components"> extends undefined ? { readonly up?: { readonly [key: string]: never }; readonly order?: { readonly "error: a system without components runs once, in no order": true } } : {})
+    & (D extends { readonly up: object } ? { readonly order?: { readonly "error: up and order both decide the order of its rows": true } } : {})
+    & (D extends { readonly observer: true } ? Observer : {})
+    & (D extends { readonly target: string } ? Targeted<D> : {})
+    & (D extends { readonly target: string } ? Property<D, "components"> extends undefined ? { readonly target?: { readonly "error: a system on one entity runs on its row, so it needs components": true } } : {} : {})
+    & { readonly shader?: never };
+
+/** The body of a system that declares nothing, which runs once per run with its commands. */
+type Alone = (context: { readonly commands: Commands }) => void;
+
+/** A composite: its list of members, or its declaration. */
+type Composition = readonly System<unknown>[] | CompositeDeclaration;
+
+/** A composite's members. */
+type MembersOf<C> = C extends CompositeDeclaration ? C["systems"] : C;
+
+/** A member whose input has a field of a different type than another member's becomes the error saying so. */
+type Checked<C> = C extends Alone ? unknown : C extends CompositeDeclaration ? { readonly systems: CheckMembers<C["systems"]> } : CheckMembers<C>;
+
+/**
+ * Declares a system and returns it; nothing runs. The arguments tell the forms apart:
+ * - `create(body)`: a system that declares nothing, whose body runs once per run with its commands.
+ * - `create(declaration, body)`: a system.
+ * - `create([move, collide])`: a composite of the systems listed, which may live on different threads.
+ * - `create({ systems: [move, collide], after: [input] })`: a composite with a name or constraints.
+ *
+ * Each run passes a composite's members one input, with every field of theirs. Throws if a system names a key that
+ * isn't registered as its kind, lists a key in both `read` and `write`, writes a reference, a lookup reads a component
+ * it writes or goes through an index keyed by one, or reads through an index what not every entity it holds has, its
+ * rows are ordered by an index it isn't sorted or keyed by what it writes, its object components and resources live on
+ * different threads, or its reductions, conditions, `up`, `order` or placement can't hold, or it's an observer and
+ * writes, reduces, takes input, is a kernel, has `up` or is ordered; or if a composite's member isn't a system a
+ * constructor returned, or two members declare an input field with different schemas. A composite's observer members
+ * run after its sync point, ordered with nothing.
+ *
+ * One argument, a body or a composite, is one overload, so a mistake in it is reported where it is rather than as no
+ * overload matching.
+ */
+export function create<const D extends Declaration>(declaration: D & Validate<D> & OneThread<ThreadsOf<D>, ThreadedBy<D>>, body: Body<D>): System<InputOf<D>>;
+export function create<const C extends Alone | Composition>(only: C & Checked<C>): C extends Alone ? System : System<CompositeInputOf<MembersOf<C>>>;
+export function create(first: Declaration | Leaf["body"] | readonly System<unknown>[] | CompositeDeclaration, second?: Leaf["body"]): System<unknown> {
+    // The plugin gives its id to the call's first argument: the declaration, the members, or the body made into a
+    // system alone.
+    const id = takeIdOfDeclaration(first);
+    if (isList(first)) return compose({ systems: first }, id);
+    if (typeof first !== "function" && second === undefined && "systems" in first) return compose(first, id);
+    const declaration: Declaration = typeof first === "function" ? {} : first;
+    const body = typeof first === "function" ? first : second;
+    if (body === undefined) throw new Error("A system needs a body, and a composite its systems.");
+    const system: Leaf & System<unknown> = { kind: "system", name: nameOf(declaration.name, id, "system"), declaration, body };
+    checkLeaf(system);
+    claimSystem(system, id);
+    return system;
+}
+
+const isList = (value: unknown): value is readonly System<unknown>[] => Array.isArray(value);
+
+const compose = (declaration: CompositeDeclaration, id: string | undefined): System<unknown> => {
+    const system: Composite & System<unknown> = { kind: "composite", name: nameOf(declaration.name, id, "system"), declaration };
+    checkComposite(system);
+    claimSystem(system, id);
+    return system;
+};

package/src/interface/system/declaration.ts

@@ -0,0 +1,65 @@
+import type { Index } from '../indexes/index-type.js';
+import type { Resource } from '../resource/resource.js';
+import type { Schema } from '../schema/schema.js';
+import type { ComponentAccess, ResourceAccess, SystemLookup, Up } from './access.js';
+import type { Name } from './name.js';
+import type { Shader } from './render.js';
+import type { System } from './system.js';
+import type { OperatorOf, Reduced } from '../resource/reduction.js';
+
+/**
+ * A system never declares its thread: it runs on the one its object components and resources live on, those it
+ * reads, writes or filters on by change, through `components`, `lookup`, `up` and `resources` but `has` and `not`.
+ * Without them, a kernel runs on the kernel pool and any other system on `"world"`.
+ */
+export type Declaration = {
+    readonly name?: Name;
+    /**
+     * Compiled to a kernel, which the build rejects if the body leaves the kernel subset. Values in `components` and
+     * `lookup` must be structs and resources read-only. Without it, the system runs as written, on its thread.
+     * - `"cpu"`: runs on the kernel pool. - `"gpu"`: also has no lookups, change filters, commands or loops, and only
+     *   4-byte scalar values, its `up` included. It runs as a   compute shader in a world with a GPU, and as a `"cpu"`
+     *   kernel in one without. Every matched row counts as   changed in what it writes.
+     */
+    readonly kernel?: "cpu" | "gpu";
+    /** The entities it runs over, and what it reads and writes of theirs. Omitted for a system that runs once per run. */
+    readonly components?: ComponentAccess;
+    readonly lookup?: { readonly [name: string]: SystemLookup };
+    /**
+     * Runs rows in depth order through `through`, so each reads its parent's `read` values after the parent ran, as
+     * the context's `up`, or null for a row without a parent. With change filters, a row also passes when its parent,
+     * or what it reads of its parent, changed since the system last ran, or it moved to another archetype, as removing
+     * its parent moves it. Rows on or under a parent cycle don't run.
+     */
+    readonly up?: Up;
+    /**
+     * Runs the rows it matches that this sorted index holds, in key order and then entity order; with change filters,
+     * the rows that pass, in that order. Commands, reductions and side effects follow it. Like a lookup through the
+     * index, it reads the index's key parts and doesn't write them. Not with `up`.
+     */
+    readonly order?: Index<{ readonly sorted: true }>;
+    readonly resources?: ResourceAccess;
+    /** The resources its body contributes to, each with the operator its `reduce` trait declares. */
+    readonly reduce?: { readonly [K in Reduced]?: OperatorOf<K> };
+    /** The object of named fields passed to each run. A system with input can't use `added` or `changed`. */
+    readonly input?: Extract<Schema, { readonly type: "object" }>;
+    /**
+     * The input field naming the one entity it runs on: its body runs once, on that entity's row, when the entity is
+     * alive and matches `components`, and not at all otherwise. Needs `components`; not with `kernel`, `up`, `order`
+     * or `reduce`.
+     */
+    readonly target?: string;
+    /** Makes this a render system (see `render`): its body records GPU work over the GPU copy of the components it names. */
+    readonly shader?: Shader;
+    /** Hard constraint. */
+    readonly before?: readonly System<unknown>[];
+    /** Hard constraint. */
+    readonly after?: readonly System<unknown>[];
+    /** Runs inside the span of the systems listed: after what they follow and before what follows them. */
+    readonly during?: readonly System<unknown>[];
+    /**
+     * Runs after the last sync point of each run and tick (a tick is a run of the added composite), reading the settled
+     * state; changes nothing; never ordered; doesn't keep the loop ticking.
+     */
+    readonly observer?: true;
+};

package/src/interface/system/definition.ts

@@ -0,0 +1,5 @@
+import type { Composite } from './composite.js';
+import type { Leaf } from './leaf.js';
+
+/** What the implementation knows of a system: the value a constructor returned, with its kind, declaration and body. */
+export type Definition = Leaf | Composite;