@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/system/index.ts

@@ -0,0 +1,3 @@
+export type { Commands } from './commands.js';
+export * from './create.js';
+export { render, type RenderContext, type RenderTable } from './render.js';

package/src/interface/system/input.ts

@@ -0,0 +1,28 @@
+import type { Schema } from '../schema/schema.js';
+import type { System } from './system.js';
+
+/**
+ * The input a system declares: a value of its `input` schema, or `undefined` without one; `unknown` for `any`, as an
+ * overload's declaration erases to, since every schema's value type is too deep to compute.
+ */
+export type InputOf<D> = 0 extends 1 & D ? unknown : D extends { readonly input: infer A extends Schema } ? Schema.ToType<A> : undefined;
+
+/** What `run` takes after a system: nothing, or one value. */
+export type Input<I> = [I] extends [undefined] ? [] : [input: I];
+
+/** A member's input fields, or `unknown` without input. */
+type Fields<S> = S extends System<infer I> ? [Exclude<I, undefined>] extends [never] ? unknown : Exclude<I, undefined> : unknown;
+
+type Merged<T, A = unknown> = T extends readonly [infer S, ...infer R] ? Merged<R, A & Fields<S>> : A;
+
+/** The input a composite of `T` takes: every field of its members' inputs, or `undefined` when none has input. */
+export type CompositeInputOf<T> = unknown extends Merged<T> ? undefined : { [K in keyof Merged<T>]: Merged<T>[K] };
+
+/** The fields of `M` whose type differs from the one the composite's input `I` gives them. */
+type Conflicts<M, I> = { [K in keyof M]-?: [Exclude<M[K], undefined>] extends [Exclude<I[K & keyof I], undefined>] ? never : K }[keyof M];
+
+type Checked<S, I> = [Conflicts<Fields<S>, I>] extends [never] ? S
+    : `Input field "${Extract<Conflicts<Fields<S>, I>, string>}" has a different type in another member of this composite.`;
+
+/** Members whose input has a field of a different type than another member's. */
+export type CheckMembers<T> = { readonly [P in keyof T]: Checked<T[P], Merged<T>> };

package/src/interface/system/leaf.ts

@@ -0,0 +1,13 @@
+import type { Declaration } from './declaration.js';
+import type { Name } from './name.js';
+
+/**
+ * A system that runs a body: `"render"` for one made by `render`, `"system"` otherwise. Its body's parameters are
+ * checked where it's created, so a leaf holds any body.
+ */
+export type Leaf = {
+    readonly kind: "system" | "render";
+    readonly name: Name;
+    readonly declaration: Declaration;
+    readonly body: (...parameters: never[]) => void;
+};

package/src/interface/system/name.ts

@@ -0,0 +1,6 @@
+/**
+ * The label reports and errors give it, which needn't be unique: the value its constructor returns is its identity, so
+ * separately written code can't collide by name. Namespacing it (`"physics/integrate"`) keeps labels short. Without
+ * one, it's labeled by its binding and the id the plugin gave it, or else by its kind numbered.
+ */
+export type Name = string;

package/src/interface/system/property.ts

@@ -0,0 +1,4 @@
+
+export type Property<T, K extends PropertyKey> = T extends { readonly [P in K]?: infer V } ? V : undefined;
+
+export type Listed<T, K extends PropertyKey> = Property<T, K> extends readonly (infer E)[] ? E : never;

package/src/interface/system/render.ts

@@ -0,0 +1,81 @@
+import type { Component } from '../component/component.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { claimSystem } from '../registry/program.js';
+import type { Condition } from '../resource/condition.js';
+import type { Resource } from '../resource/resource.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import type { Body } from './body.js';
+import { accessorsOf } from '../gpu/accessors.js';
+import { checkLeaf } from './check.js';
+import type { Leaf } from './leaf.js';
+import type { Name } from './name.js';
+import type { StructComponent } from './struct.js';
+import type { System } from './system.js';
+import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
+
+/**
+ * How a render system's shaders reach its components: `accessors` names a WGSL function for each component it reads,
+ * generated by `Gpu.wgsl` at bind group `group` (0 by default).
+ */
+export type Shader = { readonly group?: number; readonly accessors: { readonly [name: string]: StructComponent } };
+
+/** One group of matching rows, `0` to `count`. `bind` sets the world's bind group for it on a pass. */
+export type RenderTable = {
+    readonly count: number;
+    readonly bind: (pass: GPURenderPassEncoder | GPUComputePassEncoder) => void;
+};
+
+/**
+ * What a render body records with. `encoder` is the run's: the world submits it, after the run's GPU kernels and
+ * uploads, when the run ends. Acquire canvas textures inside the body.
+ */
+export type RenderContext = {
+    readonly device: GPUDevice;
+    readonly encoder: GPUCommandEncoder;
+    readonly tables: readonly RenderTable[];
+};
+
+type RenderDeclaration = {
+    readonly name?: Name;
+    /** It reads the components its accessors name. */
+    readonly components?: { readonly has?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    /** It runs only while `gpuDevice` is set, as if `is` listed it. */
+    readonly resources?: { readonly read?: readonly Resource.Key[]; readonly is?: readonly Condition[]; readonly not?: readonly Condition[] };
+    readonly shader: Shader;
+    readonly before?: readonly System<unknown>[];
+    readonly after?: readonly System<unknown>[];
+    readonly during?: readonly System<unknown>[];
+};
+
+/** A render declaration with the components its accessors name as `components.read`. */
+type Rendered<D extends RenderDeclaration> = D & { readonly components: { readonly read: readonly StructComponent[] } };
+
+/**
+ * Declares a render system: it runs once per run on `gpuDevice`'s thread, in schedule order, and records GPU work over
+ * the GPU copy of the components its accessors name, which the world uploads first as needed. It runs only while the
+ * world has a `gpuDevice`. Throws as `create` does, and for an accessor its shader can't read on the GPU.
+ */
+export const render = <const D extends RenderDeclaration>(
+    declaration: D & OneThread<ThreadsOf<D> | ThreadOfResource<typeof gpuDevice>, ThreadedBy<D>>,
+    body: Body<Rendered<D>>,
+): System => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "system");
+    const system: Leaf & System = {
+        kind: "render",
+        name,
+        declaration: {
+            ...declaration,
+            components: { ...declaration.components, read: [...new Set(Object.values(declaration.shader.accessors))] },
+            resources: { ...declaration.resources, is: [...new Set<Condition>([...declaration.resources?.is ?? [], gpuDevice])] },
+        },
+        body,
+    };
+    checkLeaf(system);
+    const accessors = accessorsOf(declaration.shader);
+    if (typeof accessors === "string") throw new Error(`System "${name}" can't render: ${accessors}.`);
+    claimSystem(system, id);
+    return system;
+};

package/src/interface/system/struct.ts

@@ -0,0 +1,9 @@
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { IsStruct } from '../schema/is-struct.js';
+
+/** Components whose values are structs, which kernels read and write. */
+export type StructComponent = { [K in Component.Key]: IsStruct<Component.Value<K>> extends true ? K : never }[Component.Key];
+
+/** Resources whose values are structs, which kernels read. */
+export type StructResource = { [K in Resource.Key]: IsStruct<Resource.Value<K>> extends true ? K : never }[Resource.Key];

package/src/interface/system/system.ts

@@ -0,0 +1,9 @@
+declare const input: unique symbol;
+
+/**
+ * A system, the value a System constructor returned: identified by that value and labeled by its name. `run` takes it
+ * with a value of type `I`, or with nothing when `I` is `undefined`.
+ */
+export type System<I = undefined> = { readonly name: string; readonly [input]?: I };
+
+export * as System from './index.js';

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

@@ -0,0 +1,460 @@
+import { Resource } from '../resource/resource.js';
+import { Component } from '../component/component.js';
+import { Entity } from '../entity/entity.js';
+import { System } from './system.js';
+import type { Index } from '../indexes/index-type.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>() => { };
+
+export const position = Symbol("systemTest/position");
+const velocity = Symbol("systemTest/velocity");
+const target = Symbol("systemTest/target");
+const player = Symbol('systemTest/player');
+export const time = Symbol("systemTest/time");
+const score = Symbol("systemTest/score");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+        [target]: { type: Entity };
+        [player]: { type: true };
+    }
+}
+Component.register(position, { type: { type: "number" } });
+Component.register(velocity, { type: { type: "number" } });
+Component.register(target, { type: Entity.schema });
+Component.register(player, { type: { const: true } });
+const flagged = Symbol("systemTest/flagged");
+const bounds = Symbol("systemTest/bounds");
+export const total = Symbol("systemTest/total");
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [time]: { type: number };
+        [score]: { type: number };
+        [flagged]: { type: boolean; reduce: "|" };
+        [bounds]: { type: readonly [number, number, number]; reduce: "min" };
+        [total]: { type: number; reduce: "+" };
+    }
+}
+Resource.register(bounds, { type: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3, default: [Infinity, Infinity, Infinity] }, reduce: "min" });
+Resource.register(time, { type: { type: "number", default: 0 } });
+Resource.register(score, { type: { type: "number", default: 0 } });
+Resource.register(flagged, { type: { type: "boolean", default: false }, reduce: "|" });
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
+
+// Row: read values are read-only, write values writable, others absent.
+export const integrate = System.create({
+    name: "test/integrate",
+    components: { read: [velocity], write: [position], has: [player] },
+    resources: { read: [time] },
+}, (row, { resources: { [time]: delta } }) => {
+    row[position] += row[velocity] * delta;
+    const entity: Entity = row.entity;
+    // @ts-expect-error read values are read-only
+    row[velocity] = 0;
+    // @ts-expect-error entity is read-only
+    row.entity = entity;
+    // @ts-expect-error components outside read and write are not in the row
+    void row[player];
+});
+
+// Write grants read: a component in write is readable, and listing it in read as well is rejected.
+System.create({
+    name: "test/integrate",
+    // @ts-expect-error write already makes it readable
+    components: { read: [position], write: [position] },
+}, () => {});
+
+// Lookups: read-only values by entity, or null.
+export const follow = System.create({
+    name: "test/follow",
+    components: { read: [target, position], write: [velocity] },
+    lookup: { targets: { read: [position] } },
+    after: [integrate],
+}, (row, { lookup: { targets } }) => {
+    const other = targets(row[target]);
+    if (other !== null) {
+        row[velocity] = other[position] - row[position];
+        // @ts-expect-error lookup values are read-only
+        other[position] = 0;
+    }
+    // @ts-expect-error a lookup returns null for a missing entity
+    void targets(row[target])[position];
+    // @ts-expect-error a lookup without changed has no changed
+    void targets(row[target])?.changed;
+});
+
+// A lookup by entity with `changed`: its row also says whether what `changed` names may have changed since the system
+// last ran.
+System.create({
+    name: "test/followChanged",
+    components: { read: [target], write: [velocity] },
+    lookup: { targets: { read: [position], changed: [position] }, players: { has: [player], changed: [player] } },
+}, (row, { lookup: { targets, players } }) => {
+    const other = targets(row[target]);
+    if (other !== null) {
+        check<Equal<typeof other.changed, boolean>>();
+        check<Equal<typeof other[typeof position], number>>();
+        // @ts-expect-error changed is read-only
+        other.changed = false;
+    }
+    const found = players(row[target]);
+    if (found !== null) check<Equal<typeof found, { readonly changed: boolean }>>();
+});
+
+System.create({
+    name: "test/followChanged",
+    components: { read: [target], write: [velocity] },
+    // @ts-expect-error a lookup by entity's changed names what it reads or has
+    lookup: { targets: { read: [position], changed: [velocity] } },
+}, () => {});
+
+// Input: typed from its schema.
+export const move = System.create({
+    name: "test/move",
+    input: { type: "object", properties: { distance: { type: "number" } } },
+    components: { has: [player], write: [position] },
+}, (row, { input }) => {
+    row[position] += input.distance;
+    // @ts-expect-error input has its schema's type
+    void input.missing;
+});
+
+// A system without components takes only its context; resource writes are writable, and written ones readable.
+export const tally = System.create({
+    name: "test/tally",
+    resources: { read: [time], write: [score] },
+}, ({ resources, commands }) => {
+    resources[score] += resources[time];
+    // @ts-expect-error read resources are read-only
+    resources[time] = 0;
+    const spawned: Entity = commands.spawn([position, player])({ [position]: 0, [player]: true });
+    // @ts-expect-error spawn values must match the component type
+    commands.spawn([position])({ [position]: "zero" });
+    commands.remove(spawned, velocity);
+});
+
+// The context holds only what the declaration declares.
+System.create({ name: "test/tally" }, context => {
+    // @ts-expect-error no resources declared
+    void context.resources;
+    // @ts-expect-error no lookups declared
+    void context.lookup;
+    // @ts-expect-error no reductions declared
+    void context.reduce;
+    // @ts-expect-error no input declared
+    void context.input;
+    void context.commands;
+});
+
+// @ts-expect-error a system without components has no row
+System.create({ name: "test/tally" }, (row: object, context: object) => { void [row, context]; });
+
+System.create({
+    name: "test/tally",
+    // @ts-expect-error write already makes a resource readable
+    resources: { read: [score], write: [score] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    // @ts-expect-error ordering takes systems
+    after: ["test/unregistered"],
+}, () => {});
+
+System.create({
+    name: "test/move",
+    input: { type: "object", properties: { distance: { type: "number" } } },
+    // @ts-expect-error a system with input can't use change filters
+    components: { changed: [position] },
+}, () => {});
+
+export const main = System.create({ name: "test/main", systems: [integrate, follow, tally] });
+const moving = System.create({ name: "test/moving", systems: [move] });
+
+// A composite takes its members' input.
+check<Equal<typeof moving, System<{ readonly distance: number }>>>();
+
+// A system is its name and the input `run` takes with it.
+check<Equal<typeof integrate, System>>();
+check<Equal<typeof move, System<{ readonly distance: number }>>>();
+check<Equal<typeof main, System>>();
+
+const label = Symbol("systemTest/label");
+const path = Symbol("systemTest/path");
+const vector = Symbol("systemTest/vector");
+const marks = Symbol("systemTest/marks");
+declare module '@adobe/ecs' {
+    export interface Components {
+        [label]: { type: string };
+        [path]: { type: readonly number[] };
+        [vector]: { type: readonly [number, number, number] };
+        [marks]: { type: ReadonlySet<number> };
+    }
+}
+Component.register(label, { type: { type: "string" } });
+Component.register(marks, { type: { type: "set", items: { type: "number" } } });
+Component.register(path, { type: { type: "array", items: { type: "number" } } });
+Component.register(vector, { type: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 } });
+
+// Kernels: linear values (numbers, booleans, entities, fixed tuples), read-only resources.
+System.create({
+    name: "test/integrate",
+    kernel: "cpu",
+    components: { read: [velocity, vector, player, target], write: [position], has: [label] },
+    resources: { read: [time] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "cpu",
+    // @ts-expect-error kernel values must be linear
+    components: { read: [label] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "cpu",
+    // @ts-expect-error kernel values can't be variable-length arrays
+    components: { write: [path] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "cpu",
+    // @ts-expect-error kernel values can't be sets or maps
+    components: { read: [marks] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "cpu",
+    // @ts-expect-error kernel lookups must read linear values
+    lookup: { labels: { read: [label] } },
+}, () => {});
+
+declare const byTarget: Index<{ readonly key: readonly [typeof target] }>;
+
+// A kernel's lookup by entity matches has and not, as any system's does.
+System.create({
+    name: "test/followPlayers",
+    kernel: "cpu",
+    components: { read: [target], write: [position] },
+    lookup: { players: { read: [position], has: [player], not: [velocity] } },
+}, (row, { lookup }) => {
+    const found = lookup.players(row[target]);
+    if (found !== null) row[position] = found[position];
+});
+
+System.create({
+    name: "test/followPlayers",
+    kernel: "cpu",
+    // @ts-expect-error an index lookup matches what its index holds, so it takes no has
+    lookup: { byTarget: { index: byTarget, read: [position], has: [player] } },
+}, () => {});
+
+System.create({
+    name: "test/tally",
+    kernel: "cpu",
+    // @ts-expect-error kernels can't write resources
+    resources: { write: [score] },
+}, () => {});
+
+// GPU kernels: everything kernels can't do, and no lookups, change filters or commands.
+System.create({
+    name: "test/integrate",
+    kernel: "gpu",
+    components: { read: [velocity], write: [position] },
+    resources: { read: [time] },
+}, row => {
+    row[position] = row[velocity];
+});
+
+System.create({
+    name: "test/integrate",
+    kernel: "gpu",
+    // @ts-expect-error GPU kernel values must be linear too
+    components: { read: [label] },
+}, () => {});
+
+System.create({
+    name: "test/follow",
+    kernel: "gpu",
+    components: { read: [target], write: [position] },
+    // @ts-expect-error GPU kernels can't use lookups
+    lookup: { targets: { read: [position] } },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "gpu",
+    // @ts-expect-error GPU kernels can't use change filters
+    components: { write: [position], changed: [velocity] },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "gpu",
+    components: { read: [velocity], write: [position] },
+}, (row, context) => {
+    // @ts-expect-error GPU kernels can't issue commands
+    context.commands.despawn(row.entity);
+});
+
+System.create({
+    name: "test/integrate",
+    // @ts-expect-error a kernel is "cpu" or "gpu"
+    kernel: true,
+}, () => {});
+
+// Reductions: each reduced resource is a function contributing a value of its type, with its trait's operator repeated.
+System.create({
+    name: "test/tally",
+    components: { read: [velocity, vector], changed: [velocity] },
+    reduce: { [total]: "+", [bounds]: "min", [flagged]: "|" },
+}, (row, { reduce }) => {
+    reduce[total](row[velocity]);
+    reduce[bounds](row[vector]);
+    reduce[flagged](row[velocity] > 1);
+    // @ts-expect-error a contribution has the resource's type
+    reduce[bounds](1);
+    // @ts-expect-error a reduced resource can't be read
+    void (reduce[total] + 1);
+});
+
+System.create({
+    name: "test/tally",
+    // @ts-expect-error the operator must equal the resource's reduce trait
+    reduce: { [total]: "max" },
+}, () => {});
+
+System.create({
+    name: "test/tally",
+    // @ts-expect-error only resources with a reduce trait can be reduced
+    reduce: { [score]: "+" },
+}, () => {});
+
+System.create({
+    name: "test/tally",
+    // @ts-expect-error a reduced resource is never written
+    resources: { write: [total] },
+}, () => {});
+
+System.create({
+    name: "test/tally",
+    // @ts-expect-error a contributor doesn't read what it reduces into
+    resources: { read: [total] },
+    reduce: { [total]: "+" },
+}, () => {});
+
+System.create({
+    name: "test/integrate",
+    kernel: "gpu",
+    components: { read: [velocity] },
+    // @ts-expect-error GPU kernels can't reduce yet
+    reduce: { [total]: "+" },
+}, () => {});
+
+
+// Render systems: the accessors name the components they read.
+System.render({ name: "test/draw", components: { has: [player] }, resources: { read: [time] }, shader: { accessors: { place: position, speed: velocity } } }, (gpu, { resources }) => {
+    void [gpu.encoder, resources[time]];
+});
+System.render({ name: "test/draw", shader: { accessors: { place: position } } }, (_, context) => {
+    // @ts-expect-error a render body issues no commands
+    void context.commands;
+});
+System.render({
+    name: "test/draw",
+    // @ts-expect-error a render system reads the components its accessors name
+    components: { read: [position] },
+    shader: { accessors: { place: position } },
+}, () => {});
+// A pass helper several render systems share declares its context and tables by name.
+const drawAll = (gpu: System.RenderContext, pass: GPURenderPassEncoder): void => {
+    for (const table of gpu.tables) drawTable(table, pass);
+};
+const drawTable = (table: System.RenderTable, pass: GPURenderPassEncoder): void => {
+    table.bind(pass);
+    pass.draw(6, table.count);
+};
+System.render({ name: "test/drawShared", shader: { accessors: { place: position } } }, gpu => {
+    const pass = gpu.encoder.beginRenderPass({ colorAttachments: [] });
+    drawAll(gpu, pass);
+    pass.end();
+});
+
+// Names are optional: a declaration may leave it out, and a system that declares nothing is just its body.
+export const unnamed = System.create({ components: { write: [position] }, resources: { read: [time] } }, (row, { resources }) => {
+    row[position] += resources[time];
+});
+check<Equal<typeof unnamed, System>>();
+export const unnamedInput = System.create({ input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input }) => {
+    const count: number = input.count;
+    void count;
+});
+check<Equal<typeof unnamedInput, System<{ readonly count: number }>>>();
+export const bodyOnly = System.create(({ commands }) => {
+    commands.spawn([position])({ [position]: 0 });
+});
+check<Equal<typeof bodyOnly, System>>();
+// @ts-expect-error a body alone declares no resources
+System.create(({ resources }) => { void resources; });
+// @ts-expect-error a body alone runs once per run, so it has no row
+System.create((row: { readonly entity: Entity }) => { void row; });
+export const unnamedAll = System.create([unnamed, bodyOnly]);
+check<Equal<typeof unnamedAll, System>>();
+System.render({ shader: { accessors: { place: position } } }, gpu => { void gpu.encoder; });
+
+// Observer systems read what a sync point left, after it: rows, resources, lookups and change filters, and no commands.
+export const watchPositions = System.create({
+    name: "test/watchPositions",
+    observer: true,
+    components: { read: [position], changed: [position] },
+    resources: { read: [time] },
+    lookup: { targets: { read: [velocity] } },
+}, (row, context) => {
+    const read: number = row[position] + context.resources[time];
+    void [read, context.lookup.targets(row.entity)];
+    // @ts-expect-error an observer system reads only
+    row[position] = 0;
+    // @ts-expect-error an observer system issues no commands
+    void context.commands;
+});
+check<Equal<typeof watchPositions, System>>();
+export const watchTime = System.create({ observer: true, resources: { read: [time], changed: [time] } }, ({ resources }) => { void resources[time]; });
+// A composite may hold observer members, which run after its sync point.
+export const withWatch = System.create([integrate, watchTime]);
+check<Equal<typeof withWatch, System>>();
+// @ts-expect-error observer is true or left out
+System.create({ observer: false, resources: { read: [time] } }, () => {});
+// @ts-expect-error an observer system writes no components
+System.create({ observer: true, components: { write: [position] } }, () => {});
+// @ts-expect-error an observer system writes no resources
+System.create({ observer: true, resources: { write: [score] } }, () => {});
+// @ts-expect-error an observer system reduces into nothing
+System.create({ observer: true, components: { read: [velocity] }, reduce: { [total]: "+" } }, () => {});
+// @ts-expect-error an observer system takes no input
+System.create({ observer: true, input: { type: "object", properties: { count: { type: "integer" } } } }, () => {});
+// @ts-expect-error an observer system isn't a kernel
+System.create({ observer: true, kernel: "cpu", components: { read: [position] } }, () => {});
+// @ts-expect-error an observer system is ordered with nothing
+System.create({ observer: true, resources: { read: [time] }, after: [integrate] }, () => {});
+// @ts-expect-error an observer system is ordered with nothing
+System.create({ observer: true, resources: { read: [time] }, before: [integrate] }, () => {});
+// @ts-expect-error an observer system is ordered with nothing
+System.create({ observer: true, resources: { read: [time] }, during: [integrate] }, () => {});
+
+// A system on one entity: its input names the entity, and its body runs on that entity's row.
+const onOne = { type: "object", properties: { entity: Entity.schema, by: { type: "number" } } } as const;
+export const nudge = System.create({ input: onOne, target: "entity", components: { write: [position] } }, (row, { input }) => {
+    row[position] += input.by;
+});
+// @ts-expect-error its target is an entity field of its input
+System.create({ input: onOne, target: "by", components: { write: [position] } }, () => {});
+// @ts-expect-error it runs on a row, so it needs components
+System.create({ input: onOne, target: "entity" }, () => {});
+// @ts-expect-error not a kernel
+System.create({ input: onOne, target: "entity", kernel: "cpu", components: { write: [position] } }, () => {});

package/src/interface/system/threads.ts

@@ -0,0 +1,46 @@
+import type { Component } from '../component/component.js';
+import type { ThreadOfComponent } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import type { Index } from '../indexes/index-type.js';
+import type { Listed, Property } from './property.js';
+import type { KeyOf } from './values.js';
+
+type Lookups<D> = Property<D, "lookup">;
+type LookupReads<D> = { [L in keyof Lookups<D>]: Listed<Lookups<D>[L], "read"> }[keyof Lookups<D>];
+type LookupKeys<D> = { [L in keyof Lookups<D>]: Lookups<D>[L] extends { readonly index: Index<infer I> } ? KeyOf<I>[number] : never }[keyof Lookups<D>];
+type OrderKeys<D> = Property<D, "order"> extends Index<infer I> ? KeyOf<I>[number] : never;
+type Components<D> = Property<D, "components">;
+type Resources<D> = Property<D, "resources">;
+
+/** The components that place a declaration: those it reads, writes or filters on by change, and the keys it looks up and orders by. */
+type Placing<D> =
+    | Listed<Components<D>, "read"> | Listed<Components<D>, "write"> | Listed<Components<D>, "added"> | Listed<Components<D>, "changed">
+    | LookupReads<D> | LookupKeys<D> | Listed<Property<D, "up">, "read"> | OrderKeys<D>;
+
+/** The resources that place a declaration: those it reads, writes, filters on by change, or reads as a condition. */
+type PlacingResources<D> =
+    Listed<Resources<D>, "read"> | Listed<Resources<D>, "write"> | Listed<Resources<D>, "changed"> | Listed<Resources<D>, "is">;
+
+/** The threads of the object components and resources a declaration uses. */
+export type ThreadsOf<D> = ThreadOfComponent<Placing<D> & Component.Key> | ThreadOfResource<PlacingResources<D> & Resource.Key>;
+
+/** Each object component and resource a declaration uses, by key, with the thread it lives on. */
+export type ThreadedBy<D> = {
+    readonly [K in (Placing<D> & Component.Key) | (PlacingResources<D> & Resource.Key) as [Thread<K>] extends [never] ? never : K]: Thread<K>;
+};
+type Thread<K> = K extends Component.Key ? ThreadOfComponent<K> : K extends Resource.Key ? ThreadOfResource<K> : never;
+
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+
+/**
+ * Requires a property no declaration has when `T` holds more than one thread, so the declaration fails to compile; its
+ * value names each key with its thread, `ThreadedBy` of the declaration.
+ */
+export type OneThread<T, Keys = T> = true extends IsUnion<T> ? { readonly "error: its object components and resources live on different threads": { readonly [K in keyof Keys]: Keys[K] } } : {};
+
+/**
+ * Whether `T`, the thread a declaration's objects live on, is another than the world's, which a joined thread may fill;
+ * false for the threads of every declaration, which hold the world's.
+ */
+export type Elsewhere<T> = [T] extends [never] ? false : "world" extends T ? false : true;