@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { collector, heapAfterCollecting, tablesAfterCollecting } from "./lifetime.test-helper.js";
+import { fillReports } from "./reports.test-helper.js";
+
+const count = Symbol("lifetimeTest/count");
+const parent = Symbol("lifetimeTest/parent");
+const score = Symbol("lifetimeTest/score");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [count]: { type: number };
+        [parent]: { type: Entity; reference: "owner" };
+    }
+    interface Resources {
+        [score]: { type: number };
+    }
+}
+
+Component.register(count, { type: { type: "number" } });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Resource.register(score, { type: { type: "number", default: 7 } });
+
+const seed = System.create({ name: "lifetimeTest/seed" }, ({ commands }) => {
+    const root = commands.spawn([count])({ [count]: 1 });
+    for (let i = 0; i < 4; i++) commands.spawn([count, parent])({ [count]: i, [parent]: root });
+});
+
+/** A module-level system, run between and after the fresh ones, as an app's own systems are. */
+const steady = System.create({ name: "lifetimeTest/steady", components: { read: [count], changed: [count] } }, row => { void row[count]; });
+
+let copied = 0;
+
+/** Fresh systems of each shape that holds something: a body alone, a resource read, a change filter, and `up`. */
+const freshSystems = (k: number): readonly System[] => [
+    System.create(() => {}),
+    System.create({ resources: { read: [score] } }, ({ resources }) => { copied = resources[score] + k; }),
+    System.create({ components: { write: [count], changed: [count] } }, row => { row[count] += 1; }),
+    System.create({ components: { read: [count] }, up: { through: parent, read: [count] } }, (row, { up }) => { copied = row[count] + (up?.[count] ?? 0); }),
+];
+
+const fresh = 10_000;
+
+/**
+ * Runs `count` fresh systems, each once, then a module-level one. Its own function, since an async function's
+ * suspended frame keeps its last locals.
+ */
+const runFresh = async (world: World, count: number): Promise<void> => {
+    for (let k = 0; k < count; k += 4) for (const system of freshSystems(k)) await world.run(system);
+    await world.run(steady);
+};
+
+describe("what a system holds", () => {
+    it("lives as long as the system: fresh systems run once leave every table as it was", async () => {
+        expect(collector()).not.toBeNull();
+        const world = createWorld({ [workers]: 0 });
+        await world.run(seed);
+        // Past the runs that spawn reports, which grow the entity table.
+        await fillReports(world);
+        await runFresh(world, 4);
+        const before = await tablesAfterCollecting(world);
+        await runFresh(world, fresh);
+        const after = await tablesAfterCollecting(world);
+        expect(copied).toBeGreaterThan(0);
+        expect(after).toEqual(before);
+        await world.dispose();
+    }, 120_000);
+
+    it("leaves the JS heap where it was once fresh systems run once are collected", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(seed);
+        // The first runs compile the paths they take and grow tables to hold what's uncollected between collections.
+        await runFresh(world, 2 * fresh);
+        const before = await heapAfterCollecting();
+        await runFresh(world, 2 * fresh);
+        const after = await heapAfterCollecting();
+        // About 12 bytes a system, which a kept runner, label or unregister token exceeds, and the heap's noise doesn't.
+        expect(after - before).toBeLessThan(250_000);
+        await world.dispose();
+    }, 120_000);
+});

package/src/implementation/world/lists.ts

@@ -0,0 +1,152 @@
+import type { Entity } from '../../interface/entity/entity.js';
+import { archetypeIndexOf, labelOf } from '../../interface/registry/index.js';
+import { batchOf } from './batches.js';
+import { reserve } from './entities.js';
+import { claim, generated, openRow, writerOf, type Column, type Positional, type SpawnBatch, type Writer } from './staging.js';
+import { commandIdOf, type State } from './state.js';
+
+/** Values by key, as spawns and adds read them. */
+export type Values = { readonly [key: symbol]: unknown };
+
+/** Spawns one entity of a list's components, writing its values into the list's batch. */
+export type Spawner = (values: Values) => Entity;
+
+/** Where a shape's spawns go: its batch, and the components holding values, each with its key, column and writer. */
+export type Written = {
+    readonly batch: SpawnBatch;
+    readonly keys: readonly symbol[];
+    readonly columns: readonly Column[];
+    readonly writers: readonly Writer[];
+};
+
+/**
+ * A set of components commands named, by their keys: keys and ids in the order of the list that first named them, what
+ * each starts at when a spawn or add leaves it out, and, made on the first spawn, where spawns go and its spawner.
+ */
+export type ListShape = {
+    /** Its index among the world's lists, by which commands name it. */
+    readonly index: number;
+    /** By source archetype id: the archetype an add or a remove of these components leaves, once a sync point resolved it. */
+    readonly adding: number[];
+    readonly removing: number[];
+    readonly keys: readonly symbol[];
+    readonly ids: readonly number[];
+    readonly starts: readonly unknown[];
+    written: Written | null;
+    spawner: Spawner | null;
+};
+
+/** A plain list named recently, found by its keys, copied, since it may change. */
+export type Recent = { readonly keys: readonly unknown[]; readonly shape: ListShape };
+
+const recentCount = 8;
+
+/** Resolves a list, checking each key is a component commands may name, listed once. Throws otherwise. */
+const resolve = (state: State, list: readonly unknown[]): ListShape => {
+    const ids = list.map(key => commandIdOf(state, key));
+    for (let k = 1; k < ids.length; k++) {
+        if (ids.indexOf(ids[k]) < k) throw new Error(`A list of components lists "${labelOf(list[k])}" twice.`);
+    }
+    const keys = list.filter(key => typeof key === "symbol");
+    const name = [...ids].sort((a, b) => a - b).join(",");
+    // Symbols a module evaluated again makes are the same components, but values are keyed by the caller's own.
+    const shapes = state.lists.get(name) ?? [];
+    const found = shapes.find(shape => keys.every(key => shape.keys.includes(key)));
+    if (found !== undefined) return found;
+    const shape: ListShape = { index: state.shapes.length, adding: [], removing: [], keys, ids, starts: ids.map(id => state.starts[id]), written: null, spawner: null };
+    state.lists.set(name, [...shapes, shape]);
+    state.shapes.push(shape);
+    return shape;
+};
+
+/**
+ * The shape of a list of components: an archetype `Archetype.create` indexed, which never changes, by its index; any
+ * other list by its keys among the recent plain lists, else resolved and made recent. Lists of the same components in
+ * any order share a shape.
+ */
+export const listShapeOf = (state: State, list: readonly unknown[]): ListShape => {
+    const index = archetypeIndexOf(list);
+    // Kept small, so it inlines into the systems spawning and adding: the rest is outlined.
+    return (index >= 0 ? state.byIndex[index] : undefined) ?? shapeOfList(state, list, index);
+};
+
+/** A list's shape, other than an archetype's already resolved. */
+const shapeOfList = (state: State, list: readonly unknown[], index: number): ListShape => {
+    if (index >= 0) {
+        const shape = resolve(state, list);
+        state.byIndex[index] = shape;
+        return shape;
+    }
+    const { recent } = state;
+    const length = list.length;
+    for (let r = 0; r < recent.length; r++) {
+        const { keys } = recent[r];
+        if (keys.length !== length) continue;
+        let same = true;
+        for (let k = 0; k < length && same; k++) same = keys[k] === list[k];
+        if (same) return recent[r].shape;
+    }
+    const shape = resolve(state, list);
+    const entry: Recent = { keys: [...list], shape };
+    if (recent.length < recentCount) recent.push(entry);
+    else recent[state.nextRecent = (state.nextRecent + 1) % recentCount] = entry;
+    return shape;
+};
+
+/** Where a shape's spawns go, resolved once. A constant's column holds nothing, so nothing is written or read for it. */
+export const writtenOf = (state: State, shape: ListShape): Written => {
+    if (shape.written !== null) return shape.written;
+    const batch = batchOf(state, shape.ids);
+    const held = shape.ids.flatMap((id, k) => state.layouts[id].kind === "constant" ? [] : [k]);
+    const columns = held.map(k => batch.columns[batch.ids.indexOf(shape.ids[k])]);
+    shape.written = { batch, keys: held.map(k => shape.keys[k]), columns, writers: held.map((k, c) => writerOf(columns[c], shape.starts[k])) };
+    return shape.written;
+};
+
+/** Spawns by reading each value by key in a loop: where code can't be generated. */
+const loopSpawner = (state: State, { batch, keys, writers }: Written): Spawner => {
+    const { entities } = state;
+    const count = keys.length;
+    return values => {
+        const row = openRow(batch);
+        for (let k = 0; k < count; k++) writers[k](row, values[keys[k]]);
+        const entity = reserve(entities);
+        claim(batch, entity);
+        return entity;
+    };
+};
+
+export type { Positional };
+
+/**
+ * Spawns of a shape taking values positionally in `order`, a site's key order: generated, else a loop over the
+ * writers. A key the shape doesn't name is ignored.
+ */
+export const positionalOf = (state: State, shape: ListShape, order: readonly unknown[]): Positional => {
+    const { batch, keys, columns, writers } = writtenOf(state, shape);
+    const at = keys.map(key => order.indexOf(key));
+    const made = generated<Positional>(state.entities, reserve, batch, order.map((_, k) => `v${k}`), keys, columns, writers, k => at[k] < 0 ? "undefined" : `v${at[k]}`);
+    if (made !== null) return made;
+    const { entities } = state;
+    return (...values) => {
+        const row = openRow(batch);
+        for (let k = 0; k < writers.length; k++) writers[k](row, at[k] < 0 ? undefined : values[at[k]]);
+        const entity = reserve(entities);
+        claim(batch, entity);
+        return entity;
+    };
+};
+
+/**
+ * The spawner of a shape, made once: it writes each value it reads by key into the shape's batch, a tag or `undefined`
+ * as the component's start, then reserves the entity, so a value that throws leaves nothing behind.
+ */
+export const spawnerOf = (state: State, shape: ListShape): Spawner => shape.spawner ?? makeSpawner(state, shape);
+
+/** Makes a shape's spawner, the first time it spawns. */
+const makeSpawner = (state: State, shape: ListShape): Spawner => {
+    const written = writtenOf(state, shape);
+    const { batch, keys, columns, writers } = written;
+    shape.spawner = generated<Spawner>(state.entities, reserve, batch, ["values"], keys, columns, writers, k => `values[k${k}]`) ?? loopSpawner(state, written);
+    return shape.spawner;
+};

package/src/implementation/world/lookup-keys.ts

@@ -0,0 +1,48 @@
+import type { SystemLookup } from '../../interface/system/access.js';
+import { indexDefinitionOf, indexOfLookup, watchedBy } from '../../interface/registry/index.js';
+import type { Component } from '../../interface/component/component.js';
+
+/** Every component a lookup names: what it reads, matches on and watches, and for an index lookup the index's own. */
+export const lookupComponentsOf = (lookup: SystemLookup): readonly Component.Key[] => {
+    const index = indexOfLookup(lookup);
+    if (index === undefined) return [...lookup.read ?? [], ..."has" in lookup ? lookup.has ?? [] : [], ..."not" in lookup ? lookup.not ?? [] : []];
+    const { key, components } = index.declaration;
+    return [...lookup.read ?? [], ...watchedBy(lookup), ...key, ...components?.has ?? [], ...components?.not ?? []];
+};
+
+const none: readonly Component.Key[] = [];
+
+/**
+ * The components whose changes the indexes of a declaration's lookups follow, which keep ticks and kernels' stamps
+ * while it lives: each index's key parts, and what its lookups watch.
+ */
+export const indexWatchesOf = (lookup: { readonly [name: string]: SystemLookup } | undefined): readonly Component.Key[] => {
+    if (lookup === undefined) return none;
+    const keys: Component.Key[] = [];
+    for (const name in lookup) {
+        const declared = lookup[name];
+        const index = indexOfLookup(declared);
+        if (index === undefined) continue;
+        keys.push(...index.declaration.key, ...watchedBy(declared));
+    }
+    return keys;
+};
+
+/** The components a declaration's lookups by entity watch: their `changed`, which keep ticks and kernels' stamps while it lives. */
+export const entityWatchesOf = (lookup: { readonly [name: string]: SystemLookup } | undefined): readonly Component.Key[] => {
+    if (lookup === undefined) return none;
+    const keys: Component.Key[] = [];
+    for (const name in lookup) {
+        const declared = lookup[name];
+        if (indexOfLookup(declared) === undefined) keys.push(...watchedBy(declared));
+    }
+    return keys;
+};
+
+/** Every component the index a declaration orders its rows by names: its key parts, `has` and `not`. */
+export const orderComponentsOf = (declaration: { readonly order?: unknown }): readonly Component.Key[] => {
+    const index = indexDefinitionOf(declaration.order);
+    if (index === undefined) return none;
+    const { key, components } = index.declaration;
+    return [...key, ...components?.has ?? [], ...components?.not ?? []];
+};

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

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import { Component, System } from "../../index.js";
+import { requireDefinition, type Composite } from "../../interface/registry/index.js";
+import type { Cadence } from "../../interface/resources/cadence.js";
+import { backToBack, createLoop, type Clock, type LoopSettings } from "./loop.js";
+import { createWorld } from "./create.js";
+import { always } from "../../interface/resources/always.js";
+import { clock } from "../../interface/resources/clock.js";
+import { Observe } from "../../observe/index.js";
+
+const count = Symbol("loopTest/count");
+declare module "@adobe/ecs" {
+    interface Components {
+        [count]: { type: number };
+    }
+}
+Component.register(count, { type: { type: "number" } });
+
+const increment = requireDefinition(System.create({ name: "loopTest/increment", components: { write: [count] } }, row => { row[count] += 1; }));
+const reader = requireDefinition(System.create({ name: "loopTest/reader", components: { read: [count] } }, row => { void row[count]; }));
+const ordered = requireDefinition(System.create({ name: "loopTest/ordered", components: { read: [count] }, after: [System.create({ name: "loopTest/phase" }, () => {})] }, row => { void row[count]; }));
+const takesInput = requireDefinition(System.create({ name: "loopTest/input", input: { type: "object", properties: { by: { type: "number" } } } }, () => {}));
+
+/** A host whose frames and timers run only when the test says, at the times it gives. */
+const createHost = (settings: { cadence: Cadence; always: boolean; wake: number }) => {
+    let time = 0;
+    let frames: ((time: number) => void)[] = [];
+    const timers: { at: number; callback: () => void; live: boolean }[] = [];
+    const ticks: Clock[] = [];
+    const host = {
+        settings: (): LoopSettings => settings,
+        tick: async (_: Composite, clock: Clock): Promise<void> => { ticks.push({ ...clock }); },
+        now: () => time,
+        frame: (callback: (time: number) => void) => {
+            frames.push(callback);
+            return () => { frames = frames.filter(other => other !== callback); };
+        },
+        timer: (callback: () => void, milliseconds: number) => {
+            const timer = { at: time + milliseconds, callback, live: true };
+            timers.push(timer);
+            return () => { timer.live = false; };
+        },
+    };
+    /** Advances time, firing due timers, then gives a frame at the new time to whatever asked for one. */
+    const advance = async (milliseconds: number, frame = true): Promise<void> => {
+        time += milliseconds;
+        for (const timer of timers) {
+            if (timer.live && timer.at <= time) {
+                timer.live = false;
+                timer.callback();
+            }
+        }
+        if (frame) {
+            const due = frames;
+            frames = [];
+            for (const callback of due) callback(time);
+        }
+        // Ticks resolve through promises.
+        for (let i = 0; i < 10; i++) await Promise.resolve();
+    };
+    return { host, ticks, advance, pending: () => frames.length + timers.filter(timer => timer.live).length };
+};
+
+describe("the loop", () => {
+    it("runs no tick while quiet, and one on the beat after a run arrives", async () => {
+        const { host, ticks, advance, pending } = createHost({ cadence: { kind: "frame" }, always: false, wake: Infinity });
+        const loop = createLoop(host);
+        loop.add(increment);
+        await advance(16);
+        expect(ticks).toEqual([]);
+        expect(pending()).toBe(0);
+        loop.arrived();
+        loop.arrived();
+        await advance(16);
+        expect(ticks).toEqual([{ now: 32, delta: 0, tick: 0 }]);
+        await advance(16);
+        expect(ticks).toHaveLength(1);
+        loop.arrived();
+        await advance(16);
+        expect(ticks[1]).toEqual({ now: 64, delta: 32, tick: 1 });
+    });
+
+    it("runs nothing while no system is added, even when runs arrive", async () => {
+        const { host, ticks, advance, pending } = createHost({ cadence: { kind: "frame" }, always: true, wake: Infinity });
+        const loop = createLoop(host);
+        loop.arrived();
+        await advance(16);
+        expect([ticks.length, pending()]).toEqual([0, 0]);
+    });
+
+    it("ticks every frame while always is set", async () => {
+        const settings = { cadence: { kind: "frame" } as Cadence, always: true, wake: Infinity };
+        const { host, ticks, advance } = createHost(settings);
+        createLoop(host).add(increment);
+        for (let i = 0; i < 3; i++) await advance(10);
+        expect(ticks.map(clock => clock.delta)).toEqual([0, 10, 10]);
+        settings.always = false;
+        await advance(10);
+        await advance(10);
+        expect(ticks).toHaveLength(3);
+    });
+
+    it("ticks once when a wake time comes, and not again for the same wake", async () => {
+        const settings = { cadence: { kind: "frame" } as Cadence, always: false, wake: 50 };
+        const { host, ticks, advance } = createHost(settings);
+        createLoop(host).add(increment);
+        await advance(40);
+        expect(ticks).toEqual([]);
+        await advance(20);
+        expect(ticks.map(clock => clock.now)).toEqual([60]);
+        await advance(100);
+        expect(ticks).toHaveLength(1);
+    });
+
+    it("under a fixed cadence ticks by step, at most maxSteps per beat, and builds no debt while quiet", async () => {
+        const settings = { cadence: { kind: "fixed", step: 10, maxSteps: 2 } as Cadence, always: true, wake: Infinity };
+        const { host, ticks, advance } = createHost(settings);
+        createLoop(host).add(increment);
+        await advance(0, false);
+        expect(ticks).toEqual([{ now: 0, delta: 10, tick: 0 }]);
+        await advance(10, false);
+        expect(ticks.map(clock => clock.now)).toEqual([0, 10]);
+        // Behind by 5 steps: 2 run and the rest of the debt is dropped.
+        await advance(50, false);
+        expect(ticks.map(clock => clock.now)).toEqual([0, 10, 20, 30]);
+        await advance(10, false);
+        expect(ticks.map(clock => clock.now)).toEqual([0, 10, 20, 30, 70]);
+        expect(ticks.every(clock => clock.delta === 10)).toBe(true);
+        settings.always = false;
+        await advance(1000, false);
+        expect(ticks).toHaveLength(5);
+    });
+
+    it("runs a fixed cadence's default of 4 steps per beat when behind", async () => {
+        const { host, ticks, advance } = createHost({ cadence: { kind: "fixed", step: 1 }, always: true, wake: Infinity });
+        createLoop(host).add(increment);
+        await advance(0, false);
+        await advance(100, false);
+        expect(ticks).toHaveLength(5);
+    });
+
+    it("rejects a system that conflicts with one added and has no order to it, or takes input", () => {
+        const { host } = createHost({ cadence: { kind: "frame" }, always: false, wake: Infinity });
+        const loop = createLoop(host);
+        loop.add(increment);
+        expect(() => loop.add(reader)).toThrow('Systems "loopTest/increment" and "loopTest/reader" both access "loopTest/count" and one writes it');
+        expect(() => loop.add(takesInput)).toThrow("takes input, which ticks don't pass");
+        loop.add(increment);
+        expect(() => loop.add(ordered)).toThrow("both access");
+    });
+
+    it("schedules nothing more once stopped", async () => {
+        const { host, ticks, advance, pending } = createHost({ cadence: { kind: "frame" }, always: true, wake: Infinity });
+        const loop = createLoop(host);
+        loop.add(increment);
+        loop.stop();
+        await advance(16);
+        expect([ticks.length, pending()]).toEqual([0, 0]);
+        expect(() => loop.add(reader)).toThrow("disposed");
+    });
+});
+
+describe("a world's loop platform", () => {
+    it("can be given, so a back-to-back driver ticks as fast as tasks run", async () => {
+        const driver = backToBack();
+        const world = createWorld({ [always]: true }, { loop: driver });
+        world.add(System.create({ name: "loopTest/idle", components: { has: [count] } }, () => {}));
+        const start = performance.now();
+        // At 60 frames a second, a timer's frames would take 1.6 s.
+        await new Promise<void>(resolve => {
+            let ticks = 0;
+            const unobserve = Observe.resource(world, clock)(() => {
+                if (++ticks < 100) return;
+                unobserve();
+                resolve();
+            });
+        });
+        expect(performance.now() - start).toBeLessThan(800);
+        await world.dispose();
+        driver.close();
+    });
+});