@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/changes-finalizers.test.ts

@@ -0,0 +1,40 @@
+import { expect, it } from "vitest";
+import { Component, Finalizer, Resource, System, World } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "../index.js";
+
+const name = Symbol("changesFinalizers/name");
+const score = Symbol("changesFinalizers/score");
+const journal = Symbol("changesFinalizers/journal");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [name]: { type: string };
+        [score]: { type: number };
+    }
+    interface Resources {
+        [journal]: { type: readonly string[] };
+    }
+}
+
+Component.register(name, { type: { type: "string" } });
+Component.register(score, { type: { type: "number" } });
+Resource.register(journal, { type: { type: "array", items: { type: "string" }, default: [] } });
+
+// A changes finalizer sees each sync point's structural changes to the components it watches, grouped by how
+// they changed, with values before and after: for persistence, replication and undo.
+Finalizer.changes({ name: "changesFinalizers/save", watch: [name, score], resources: { write: [journal] } }, (changes, { resources }) => {
+    const lines = changes.groups.flatMap(group => group.entities.map(entity =>
+        `${changes.previous(entity, name) ?? changes.next(entity, name)}: +${group.added.length} -${group.removed.length} score ${changes.previous(entity, score)} → ${changes.next(entity, score)}`));
+    resources[journal] = [...resources[journal], ...lines];
+});
+
+const spawn = System.create({ name: "changesFinalizers/spawn" }, ({ commands }) => { commands.spawn([name, score])({ [name]: "ada", [score]: 3 }); });
+const retire = System.create({ name: "changesFinalizers/retire", components: { has: [score] } }, (row, { commands }) => { commands.remove(row.entity, score); });
+
+it("records each sync point's structural changes", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    await world.run(retire);
+    expect(await Observe.toPromise(Observe.resource(world, journal))).toEqual(["ada: +2 -0 score null → 3", "ada: +0 -1 score 3 → null"]);
+});

package/src/implementation/world/check-kernel.ts

@@ -0,0 +1,86 @@
+import { declarationOf, labelOf, labelOfItem } from '../../interface/registry/index.js';
+import { layoutOf, samePath, type Layout, type Path } from '../../interface/registry/layout.js';
+import type { Leaf } from '../../interface/system/leaf.js';
+import type { KernelDescription } from './kernel.js';
+import type { Key } from './state.js';
+
+/**
+ * A key's layout, or null for one this copy of the package didn't register, as a library bundling its own copy
+ * registers its keys: a world binding the kernel checks those.
+ */
+const layoutOfKey = (key: Key): Layout | null => {
+    const declaration = declarationOf(key);
+    return declaration === undefined ? null : layoutOf(declaration.type);
+};
+
+/** Whether `path` names a scalar leaf of `layout`; true for an unknown layout. */
+const hasLeaf = (layout: Layout | null, path: Path): boolean => layout === null || (layout.kind === "linear" && layout.leaves.some(leaf => samePath(leaf.path, path)));
+
+/** Whether `leaves` are every scalar leaf of `layout`, each once; true for an unknown layout. */
+const exactly = (layout: Layout | null, leaves: readonly Path[]): boolean => {
+    if (layout === null) return true;
+    const own = layout.kind === "linear" ? layout.leaves : [];
+    return own.length === leaves.length && own.every(leaf => leaves.some(path => samePath(path, leaf.path)));
+};
+
+/**
+ * Checks a compiled kernel against its declaration and the registered schemas, which don't depend on a world, so
+ * registering the kernel rejects it where it's declared: every column, whole-value write, lookup, `up` read and
+ * reduction it uses is declared, and names scalar leaves of its component's schema, each spawn site names each of its
+ * components once, from its keys, and a tuple or struct a command or spawn gives goes to a component stored in linear
+ * memory. Throws with the first mismatch.
+ */
+export const checkKernel = (leaf: Leaf, description: KernelDescription): void => {
+    const { lookup, components: query, resources, up, reduce } = leaf.declaration;
+    const fail = (message: string): never => { throw new Error(`Kernel "${labelOfItem(leaf)}": ${message}`); };
+    const queried = new Set<Key>([...query?.read ?? [], ...query?.write ?? []]);
+    const written = new Set<Key>(query?.write);
+    // A condition in `is` is readable too, and the compiler lists it with the reads.
+    const readable = new Set<Key>([...resources?.read ?? [], ...resources?.is ?? []]);
+    for (const key of description.resources) if (!readable.has(key)) fail(`reads resource "${labelOf(key)}", which isn't in resources.read.`);
+    for (const column of description.columns) {
+        if (column.kind === "entity") continue;
+        if (!queried.has(column.component)) fail(`"${labelOf(column.component)}" isn't in its components' read or write.`);
+        if (column.kind === "changed" || column.kind === "chunks") {
+            if (!written.has(column.component)) fail(`writes "${labelOf(column.component)}", which isn't in its components' write.`);
+            continue;
+        }
+        const layout = layoutOfKey(column.component);
+        if (layout !== null && layout.kind !== "linear") fail(`"${labelOf(column.component)}" isn't stored in linear memory.`);
+        if (!hasLeaf(layout, column.path)) fail(`"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`);
+    }
+    for (const shape of description.shapes) {
+        if (!written.has(shape.component)) fail(`writes "${labelOf(shape.component)}", which isn't in its components' write.`);
+        if (!exactly(layoutOfKey(shape.component), shape.leaves)) fail(`a whole-value write of "${labelOf(shape.component)}" doesn't match its schema.`);
+    }
+    for (const lookupName of description.lookups) if (lookup?.[lookupName] === undefined) fail(`unknown lookup "${lookupName}".`);
+    if ((description.up === true) !== (up !== undefined)) fail(description.up === true ? "reads up, which its declaration doesn't declare." : "its declaration declares up, which it doesn't read.");
+    const upReadable = new Set<Key>(up?.read);
+    for (const column of description.upColumns ?? []) {
+        if (column.kind !== "field" || !upReadable.has(column.component)) fail(`reads "${labelOf(column.kind === "field" ? column.component : column.kind)}" through up, which isn't in up.read.`);
+        if (column.kind !== "field") continue;
+        const layout = layoutOfKey(column.component);
+        if (layout !== null && layout.kind !== "linear") fail(`up reads "${labelOf(column.component)}", which isn't stored in linear memory.`);
+        if (!hasLeaf(layout, column.path)) fail(`"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`);
+    }
+    for (const reduced of description.reductions) {
+        if (Reflect.get(reduce ?? {}, reduced.resource) !== reduced.operator) fail(`reduces "${labelOf(reduced.resource)}" with "${reduced.operator}", which its reduce doesn't declare.`);
+        if (!hasLeaf(layoutOfKey(reduced.resource), reduced.path)) fail(`contributes to "${labelOf(reduced.resource)}" at [${reduced.path.join(", ")}], which isn't a scalar of its value; destructure tuples and structs or build them.`);
+    }
+    for (const list of description.spawns) {
+        list.forEach((k, position) => {
+            if (!Number.isInteger(k) || k < 0 || k >= description.keys.length) fail(`spawns a list naming component ${k} of its ${description.keys.length} keys.`);
+            if (list.findIndex(other => description.keys[other] === description.keys[k]) < position) fail(`spawns a list naming "${labelOf(description.keys[k])}" twice.`);
+        });
+    }
+    for (const k of description.structuredValues) {
+        const key = description.keys[k];
+        const layout = key === undefined ? null : layoutOfKey(key);
+        if (layout !== null && layout.kind !== "linear") fail(`gives "${labelOf(key)}" a tuple or struct, which only a component stored in linear memory takes.`);
+    }
+    for (const shape of description.reducedShapes) {
+        if (Reflect.get(reduce ?? {}, shape.component) === undefined || !exactly(layoutOfKey(shape.component), shape.leaves)) {
+            fail(`contributes a value to "${labelOf(shape.component)}" that doesn't match its schema.`);
+        }
+    }
+};

package/src/implementation/world/claims.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { claimPiece, startRanges } from "./claims.js";
+import { lineWords } from "./protocol.js";
+
+const drain = (words: Int32Array, self: number, participants: number): number[] => {
+    const claimed: number[] = [];
+    for (let piece = claimPiece(words, self, participants); piece >= 0; piece = claimPiece(words, self, participants)) claimed.push(piece);
+    return claimed;
+};
+
+describe("claims", () => {
+    it("take the home range in order, then steal from the back of the fullest", () => {
+        const words = new Int32Array(new SharedArrayBuffer(3 * lineWords * 4));
+        startRanges(words, 3, 10);
+        // Ranges: 0..3, 3..6, 6..10.
+        expect(claimPiece(words, 1, 3)).toBe(3);
+        expect(claimPiece(words, 1, 3)).toBe(4);
+        expect(claimPiece(words, 1, 3)).toBe(5);
+        // Participant 2 has 4 left, more than participant 0's 3.
+        expect(claimPiece(words, 1, 3)).toBe(9);
+        expect(claimPiece(words, 1, 3)).toBe(2);
+        expect(drain(words, 0, 3)).toEqual([0, 1, 8, 7, 6]);
+        expect(claimPiece(words, 2, 3)).toBe(-1);
+    });
+
+    it("claim every piece exactly once however participants interleave", () => {
+        for (const [participants, pieces] of [[1, 1], [4, 3], [9, 72], [7, 100]]) {
+            const words = new Int32Array(new SharedArrayBuffer(participants * lineWords * 4));
+            startRanges(words, participants, pieces);
+            const claimed: number[] = [];
+            let active = participants;
+            for (let turn = 0; active > 0; turn = (turn * 5 + 3) % participants) {
+                const piece = claimPiece(words, turn, participants);
+                if (piece < 0) active--;
+                else claimed.push(piece);
+                if (claimed.length > pieces) break;
+            }
+            expect(claimed.sort((a, b) => a - b)).toEqual(Array.from({ length: pieces }, (_, i) => i));
+        }
+    });
+});

package/src/implementation/world/claims.ts

@@ -0,0 +1,50 @@
+import { lineWords } from './protocol.js';
+
+/**
+ * Pieces of a claimed split, as a home range per participant: one Int32 per participant, each on its own cache line,
+ * holding its next piece (`front`, low 16 bits) and the end of its range (`back`, high 16 bits). An owner takes pieces
+ * from its front, in order, so it streams forward through rows it ran last tier; a participant whose range is empty
+ * steals from the back of the fullest other range, so owner and thief meet only at the end. Every change is one
+ * compare-and-swap of the whole word, so a piece is claimed exactly once.
+ */
+
+/** Split pieces into at most 32767, so a range's bounds fit its word. */
+export const maximumPieces = 0x7fff;
+
+const rangeWord = (front: number, back: number): number => (back << 16) | front;
+
+/** Gives each of `participants` an equal home range of `pieces`, in order. */
+export const startRanges = (words: Int32Array, participants: number, pieces: number): void => {
+    for (let i = 0; i < participants; i++) {
+        Atomics.store(words, i * lineWords, rangeWord(Math.floor(i * pieces / participants), Math.floor((i + 1) * pieces / participants)));
+    }
+};
+
+/** Claims the next piece for participant `self`: its own front, else the back of the fullest other range; -1 once none are left. */
+export const claimPiece = (words: Int32Array, self: number, participants: number): number => {
+    for (;;) {
+        const own = Atomics.load(words, self * lineWords);
+        const front = own & 0xffff;
+        const back = own >>> 16;
+        if (front < back) {
+            if (Atomics.compareExchange(words, self * lineWords, own, rangeWord(front + 1, back)) === own) return front;
+            continue;
+        }
+        let victim = -1;
+        let most = 0;
+        let word = 0;
+        for (let i = 0; i < participants; i++) {
+            if (i === self) continue;
+            const other = Atomics.load(words, i * lineWords);
+            const left = (other >>> 16) - (other & 0xffff);
+            if (left > most) {
+                most = left;
+                victim = i;
+                word = other;
+            }
+        }
+        if (victim < 0) return -1;
+        const last = (word >>> 16) - 1;
+        if (Atomics.compareExchange(words, victim * lineWords, word, rangeWord(word & 0xffff, last)) === word) return last;
+    }
+};

package/src/implementation/world/closure.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { strataOf, type RuleFacts } from "../../interface/registry/strata.js";
+import { closedComponents } from "./closure.js";
+
+// Components 0 to 9: 0 mesh, 1 transform, 2 hidden, 3 slot (derived), 4 ready (within slot), 5 visible (derived), 6 resident (derived), 7 sprite.
+const derived = [false, false, false, true, false, true, true, false];
+const hosts = [-1, -1, -1, -1, 3, -1, -1, -1];
+const name = (id: number): string => `c${id}`;
+const rule = (has: number[], not: number[], derives: number[]): RuleFacts => ({ has, not, derives });
+const closure = (rules: readonly RuleFacts[], components: number[]): number[] => closedComponents(components, derived, hosts, strataOf(rules, hosts, name));
+
+describe("closure", () => {
+    const slots = rule([0, 1], [2], [3]);
+    it("derives where a rule matches, and drops what no rule derives", () => {
+        expect(closure([slots], [0, 1])).toEqual([0, 1, 3]);
+        expect(closure([slots], [0, 1, 2, 3])).toEqual([0, 1, 2]);
+        expect(closure([slots], [0, 3])).toEqual([0]);
+    });
+    it("keeps a component within its host only while the host is present", () => {
+        expect(closure([slots], [0, 1, 3, 4])).toEqual([0, 1, 3, 4]);
+        expect(closure([slots], [0, 1, 2, 3, 4])).toEqual([0, 1, 2]);
+    });
+    it("chains rules and unions owners, after the strata their negations read", () => {
+        const visible = rule([3], [], [5]);
+        const fromSprite = rule([7], [], [5]);
+        const resident = rule([5], [4], [6]);
+        expect(closure([slots, visible, fromSprite, resident], [0, 1])).toEqual([0, 1, 3, 5, 6]);
+        expect(closure([slots, visible, fromSprite, resident], [0, 1, 4])).toEqual([0, 1, 3, 4, 5]);
+        expect(closure([slots, visible, fromSprite, resident], [7])).toEqual([5, 6, 7]);
+    });
+    it("is a least fixed point: positive cycles derive nothing on their own", () => {
+        expect(closure([rule([5], [], [6]), rule([6], [], [5])], [0])).toEqual([0]);
+        expect(closure([rule([5], [], [6]), rule([6], [], [5]), rule([0], [], [5])], [0])).toEqual([0, 5, 6]);
+    });
+    it("rejects cycles through a negation or within", () => {
+        expect(() => strataOf([rule([], [6], [5]), rule([5], [], [6])], hosts, name)).toThrow("cycle through a negation, which could oscillate: c5, c6");
+        expect(() => strataOf([rule([4], [], [3])], hosts, name)).toThrow("within each other in a cycle: c3, c4");
+    });
+});

package/src/implementation/world/closure.ts

@@ -0,0 +1,40 @@
+/**
+ * Structural derivation: which components an archetype's entities have once rules and `within` are applied.
+ * Datalog with stratified negation over the components each entity has. A rule adds the components it derives where
+ * its query matches; a component declared within a host stays only while the host is present. Each stratum is a least
+ * fixed point, evaluated after every stratum it depends on, so the result is a pure function of the archetype.
+ */
+
+import type { Strata } from '../../interface/registry/strata.js';
+
+/**
+ * The sorted components an entity with `components` has once derived: derived components only where a rule derives
+ * them, and components within a host only where the host is.
+ */
+export const closedComponents = (components: readonly number[], derived: readonly boolean[], hosts: readonly number[], strata: Strata): number[] => {
+    const present = new Set<number>();
+    const given = new Set<number>();
+    for (const id of components) {
+        if ((hosts[id] ?? -1) >= 0) given.add(id);
+        else if (derived[id] !== true) present.add(id);
+    }
+    for (const { rules, within } of strata) {
+        for (let changed = true; changed;) {
+            changed = false;
+            for (const rule of rules) {
+                if (!rule.has.every(id => present.has(id)) || rule.not.some(id => present.has(id))) continue;
+                for (const id of rule.derives) {
+                    if (present.has(id)) continue;
+                    present.add(id);
+                    changed = true;
+                }
+            }
+            for (const { dependent, host } of within) {
+                if (present.has(dependent) || !given.has(dependent) || !present.has(host)) continue;
+                present.add(dependent);
+                changed = true;
+            }
+        }
+    }
+    return [...present].sort((a, b) => a - b);
+};