@adobe/ecs 0.2.1 → 0.2.3

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

@@ -0,0 +1,267 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { clock, Component, Entity, Resource, System, workers } from "../../index.js";
+import type { Vec3 } from "../../interface/math/index.js";
+import type { Tables } from "../../interface/system/tables.js";
+import type { Table } from "../../interface/world/table/table.js";
+import { createWorld } from "./create.js";
+
+const position = Symbol("tablesTest/position");
+const label = Symbol("tablesTest/label");
+const tags = Symbol("tablesTest/tags");
+const team = Symbol("tablesTest/team");
+const pinned = Symbol("tablesTest/pinned");
+const parent = Symbol("tablesTest/parent");
+const target = Symbol("tablesTest/target");
+const link = Symbol("tablesTest/link");
+const friends = Symbol("tablesTest/friends");
+const hidden = Symbol("tablesTest/hidden");
+const buddy = Symbol("tablesTest/buddy");
+const score = Symbol("tablesTest/score");
+const title = Symbol("tablesTest/title");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [label]: { type: string };
+        [tags]: { type: readonly string[] };
+        [team]: { type: "red" | "blue"; shared: true };
+        [pinned]: { type: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [target]: { type: Entity; reference: "weak" };
+        [link]: { type: { readonly to: Entity; readonly weight: number } };
+        [friends]: { type: readonly Entity[] };
+        [hidden]: { type: true };
+        [buddy]: { type: Entity };
+    }
+    interface Resources {
+        [score]: { type: number; default: 0 };
+        [title]: { type: string; default: "" };
+    }
+}
+
+const inline = () => createWorld({ [workers]: 0 });
+
+/** A readonly system's tables of these components. */
+const tablesOf = (components: readonly Component.Key[], resources: readonly Resource.Key[] = [], not: readonly Component.Key[] = []) =>
+    System.create({ readonly: true, tables: { components, resources, not } }, ({ tables }): Tables => tables);
+
+const spawnedBy: { spawned: Table.Spawned } = { spawned: { entities: [], dropped: 0 } };
+const given: { tables: readonly Table[]; resources?: { readonly [key: symbol]: unknown } } = { tables: [] };
+const spawnGiven = System.create(({ commands }) => {
+    spawnedBy.spawned = given.resources === undefined ? commands.spawnTables(given.tables) : commands.spawnTables(given.tables, given.resources);
+});
+const spawnTables = async (world: ReturnType<typeof inline>, tables: readonly Table[]): Promise<Table.Spawned> => {
+    given.tables = tables;
+    await world.run(spawnGiven);
+    return spawnedBy.spawned;
+};
+
+const values = System.create({ readonly: true, components: { with: [label], optional: [position, parent, target, link, friends, tags, buddy] } }, row => {
+    found.push({ entity: row.entity, label: row[label], position: row[position], parent: row[parent], target: row[target], link: row[link], friends: row[friends], tags: row[tags], buddy: row[buddy] });
+});
+type Found = { entity: Entity; label: string; position?: Vec3; parent?: Entity; target?: Entity; link?: { readonly to: Entity; readonly weight: number }; friends?: readonly Entity[]; tags?: readonly string[]; buddy?: Entity };
+const found: Found[] = [];
+const readAll = async (world: ReturnType<typeof inline>): Promise<Found[]> => {
+    found.length = 0;
+    await world.run(values);
+    return [...found].sort((a, b) => a.label.localeCompare(b.label));
+};
+
+describe("tables", () => {
+    it("give each archetype holding a component asked for, its entities, and a copy of each column in the world's layout", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([position, label])({ [position]: [1, 2, 3], [label]: "a" });
+            commands.spawn([position, label, tags])({ [position]: [4, 5, 6], [label]: "b", [tags]: ["x", "y"] });
+            commands.spawn([team, label], { [team]: "red" })({ [label]: "c" });
+            commands.spawn([pinned])();
+        }));
+        const { archetypes } = await world.run(tablesOf([position, label, tags, team, pinned]));
+        expect(archetypes.map(table => table.count)).toEqual([1, 1, 1, 1]);
+        const plain = archetypes.find(table => table.columns[tags] === undefined && table.columns[position] !== undefined);
+        const bytes = plain?.columns[position];
+        expect(bytes?.kind === "bytes" && [...new Float32Array(bytes.bytes.buffer, bytes.bytes.byteOffset, 3)]).toEqual([1, 2, 3]);
+        expect(bytes?.kind === "bytes" && bytes.stride).toBe(12);
+        const withTags = archetypes.find(table => table.columns[tags] !== undefined);
+        expect(withTags?.columns[tags]).toEqual({ kind: "values", values: [["x", "y"]] });
+        expect(withTags?.columns[label]).toEqual({ kind: "values", values: ["b"] });
+        const shared = archetypes.find(table => table.columns[team] !== undefined);
+        expect(shared?.columns[team]).toEqual({ kind: "value", value: "red" });
+        expect(archetypes.find(table => table.columns[pinned] !== undefined)?.columns[pinned]).toEqual({ kind: "value", value: true });
+    });
+
+    it("leave out archetypes not matching with and not, and give the values of resources asked for", async () => {
+        await using world = createWorld({ [workers]: 0, [score]: 7, [title]: "won" });
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([label])({ [label]: "shown" });
+            commands.spawn([label, hidden])({ [label]: "hidden" });
+        }));
+        const { archetypes, resources } = await world.run(tablesOf([label], [score, title], [hidden]));
+        expect(archetypes.map(table => table.columns[label])).toEqual([{ kind: "values", values: ["shown"] }]);
+        expect(resources[score]).toBe(7);
+        expect(resources[title]).toBe("won");
+    });
+
+    it("spawn back as they were read, shared values and strings included", async () => {
+        await using from = inline();
+        await from.run(System.create(({ commands }) => {
+            commands.spawn([position, label, tags])({ [position]: [1, 2, 3], [label]: "a", [tags]: ["t"] });
+            commands.spawn([team, label], { [team]: "blue" })({ [label]: "b" });
+        }));
+        const { archetypes } = await from.run(tablesOf([position, label, tags, team]));
+        await using into = inline();
+        const { entities, dropped } = await spawnTables(into, archetypes);
+        expect([entities.map(list => list.length), dropped]).toEqual([[1, 1], 0]);
+        const again = await into.run(tablesOf([position, label, tags, team]));
+        expect(again.archetypes.map(table => ({ ...table, entities: [] }))).toEqual(archetypes.map(table => ({ ...table, entities: [] })));
+        expect(await readAll(into)).toMatchObject([{ label: "a", position: [1, 2, 3], tags: ["t"] }, { label: "b" }]);
+    });
+
+    it("rewrite entities in references, struct fields and arrays to those spawned for them, self references and cycles included", async () => {
+        await using from = inline();
+        await from.run(System.create(({ commands }) => {
+            const root = commands.spawn([label])({ [label]: "root" });
+            const child = commands.spawn([label, parent])({ [label]: "child", [parent]: root });
+            commands.spawn([label, target, link, friends])({ [label]: "other", [target]: child, [link]: { to: root, weight: 2 }, [friends]: [root, child] });
+            const a = commands.spawn([label, link])({ [label]: "self", [link]: { to: Entity.none, weight: 1 } });
+            commands.add(a, link, { to: a, weight: 1 });
+        }));
+        const before = await readAll(from);
+        const { archetypes } = await from.run(tablesOf([label, parent, target, link, friends]));
+        await using into = inline();
+        // Entities already in the world, so the new ones differ from the old.
+        await into.run(System.create(({ commands }) => { for (let i = 0; i < 5; i++) commands.spawn([pinned])(); }));
+        await spawnTables(into, archetypes);
+        const after = await readAll(into);
+        const old = new Map(before.map(entry => [entry.entity, entry.label]));
+        const now = new Map(after.map(entry => [entry.label, entry.entity]));
+        const translated = (entity: Entity | undefined): Entity | undefined => entity === undefined ? undefined : now.get(old.get(entity) ?? "");
+        expect(after.map(entry => entry.label)).toEqual(before.map(entry => entry.label));
+        for (const entry of before) {
+            const moved = after.find(other => other.label === entry.label);
+            expect(moved?.entity).not.toBe(entry.entity);
+            expect(moved?.parent).toBe(translated(entry.parent));
+            expect(moved?.target).toBe(translated(entry.target));
+            expect(moved?.link?.to).toBe(translated(entry.link?.to));
+            expect(moved?.friends).toEqual(entry.friends?.map(translated));
+        }
+        expect(after.find(entry => entry.label === "self")?.link?.to).toBe(now.get("self"));
+    });
+
+    it("leave out a weak reference to an entity outside the tables, its holder spawned without it", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            const outside = commands.spawn([pinned])();
+            const inside = commands.spawn([label])({ [label]: "inside" });
+            commands.spawn([label, target])({ [label]: "away", [target]: outside });
+            commands.spawn([label, target])({ [label]: "near", [target]: inside });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, target]));
+        await using other = inline();
+        expect((await spawnTables(other, archetypes)).dropped).toBe(0);
+        const read = await readAll(other);
+        expect(read.map(entry => [entry.label, entry.target === undefined ? "none" : read.find(found => found.entity === entry.target)?.label])).toEqual([["away", "none"], ["inside", "none"], ["near", "inside"]]);
+    });
+
+    it("spawn no row owned, directly or through others, by an entity outside the tables, saying how many", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            const outside = commands.spawn([pinned])();
+            const top = commands.spawn([label, parent])({ [label]: "top", [parent]: outside });
+            const middle = commands.spawn([label, parent])({ [label]: "middle", [parent]: top });
+            commands.spawn([label, parent])({ [label]: "bottom", [parent]: middle });
+            const kept = commands.spawn([label])({ [label]: "kept" });
+            commands.spawn([label, parent, target])({ [label]: "kept child", [parent]: kept, [target]: middle });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, parent, target]));
+        await using other = inline();
+        const { entities, dropped } = await spawnTables(other, archetypes);
+        expect(dropped).toBe(3);
+        expect(entities.flatMap(list => [...list]).filter(entity => entity === Entity.none).length).toBe(3);
+        const read = await readAll(other);
+        // The kept child's weak target was dropped, so it's spawned without it.
+        expect(read.map(entry => [entry.label, entry.parent === undefined ? null : read.find(found => found.entity === entry.parent)?.label, entry.target ?? null])).toEqual([["kept", null, null], ["kept child", "kept", null]]);
+    });
+
+    it("make any other entity value naming an entity outside the tables none: a whole component, a struct's field and an array's item", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            const outside = commands.spawn([pinned])();
+            const inside = commands.spawn([label])({ [label]: "inside" });
+            commands.spawn([label, buddy, link, friends])({ [label]: "pointing", [buddy]: outside, [link]: { to: outside, weight: 1 }, [friends]: [outside, inside] });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, buddy, link, friends]));
+        await using other = inline();
+        await spawnTables(other, archetypes);
+        const read = await readAll(other);
+        const inside = read.find(entry => entry.label === "inside")?.entity;
+        expect(read.find(entry => entry.label === "pointing")).toMatchObject({ buddy: Entity.none, link: { to: Entity.none, weight: 1 }, friends: [Entity.none, inside] });
+    });
+
+    it("set the resources they're given at the sync point, beside the entities", async () => {
+        await using world = createWorld({ [workers]: 0, [score]: 7 });
+        given.tables = [];
+        given.resources = { [score]: 12, [title]: "loaded" };
+        try {
+            await world.run(spawnGiven);
+        }
+        finally {
+            given.resources = undefined;
+        }
+        const { resources } = await world.run(tablesOf([label], [score, title]));
+        expect(resources[score]).toBe(12);
+        expect(resources[title]).toBe("loaded");
+    });
+
+    it("refuse a resource only the world writes or a value its type doesn't take, spawning nothing", async () => {
+        await using world = inline();
+        const table: Table = { count: 1, entities: new Float64Array([1]), columns: { [label]: { kind: "values", values: ["kept out"] } } };
+        given.tables = [table];
+        try {
+            given.resources = { [clock]: { now: 0, delta: 0, tick: 0 } };
+            await expect(world.run(spawnGiven)).rejects.toThrow(/clock" is written only by the world/);
+            given.resources = { [score]: "twelve" };
+            await expect(world.run(spawnGiven)).rejects.toThrow(/score" is given a value its type doesn't take/);
+            given.resources = { [position]: [0, 0, 0] };
+            await expect(world.run(spawnGiven)).rejects.toThrow(/position" isn't a registered resource/);
+        }
+        finally {
+            given.resources = undefined;
+        }
+        expect(await readAll(world)).toEqual([]);
+        expect((await world.run(tablesOf([label], [score]))).resources[score]).toBe(0);
+    });
+
+    it("fail a column that doesn't fit its component's layout or its table's count", async () => {
+        await using world = inline();
+        const table = (columns: Table["columns"], count = 1): Table => ({ count, entities: new Float64Array(count).fill(1), columns });
+        given.tables = [table({ [position]: { kind: "bytes", bytes: new Uint8Array(8), stride: 8 } })];
+        await expect(world.run(spawnGiven)).rejects.toThrow(/stride of 12 bytes in this world, not 8/);
+        given.tables = [table({ [position]: { kind: "bytes", bytes: new Uint8Array(24), stride: 12 } })];
+        await expect(world.run(spawnGiven)).rejects.toThrow(/gives 24 bytes for 1 rows of 12/);
+        given.tables = [table({ [label]: { kind: "values", values: ["a", "b"] } })];
+        await expect(world.run(spawnGiven)).rejects.toThrow(/gives 2 values for 1 rows/);
+        given.tables = [table({ [team]: { kind: "values", values: ["red"] } })];
+        await expect(world.run(spawnGiven)).rejects.toThrow(/shared component, so its column is one value/);
+        // Two rows of one entity can't both be what a reference to it names.
+        given.tables = [table({ [friends]: { kind: "values", values: [[]] } }, 1), table({ [friends]: { kind: "values", values: [[]] } }, 1)];
+        await expect(world.run(spawnGiven)).rejects.toThrow(/entity 1 is in two rows/);
+        expect(await readAll(world)).toEqual([]);
+    });
+
+    it("are read only by a readonly system without components", () => {
+        // @ts-expect-error: tables are read only by a readonly system, which the declaration's type says too.
+        expect(() => System.create({ tables: { components: [label] } }, () => {})).toThrow(/reads tables, which only a readonly system reads/);
+    });
+});
+
+describe("declarations", () => {
+    it("give every component and resource registered, with its schema and traits", () => {
+        const declared = Component.declarations().get(parent);
+        expect(declared?.type).toEqual({ type: "integer", format: "entity" });
+        expect(declared?.reference).toBe("owner");
+        expect(Resource.declarations().get(score)?.default).toBe(0);
+        const components: readonly symbol[] = [...Component.declarations().keys()];
+        expect(components.includes(score)).toBe(false);
+    });
+});

package/src/implementation/world/tables.ts

@@ -0,0 +1,330 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Layout, Path } from '../../interface/registry/layout.js';
+import { declarationOf, labelOf } from '../../interface/registry/names.js';
+import { isEntity } from '../../interface/registry/schemas.js';
+import type { Schema } from '../../interface/schema/schema.js';
+import type { Table } from '../../interface/world/table/table.js';
+import { batchOf } from './batches.js';
+import { indexOf, reserveRun } from './entities.js';
+import { internShared } from './shared.js';
+import { claimRows, openRows, writerOf, type Column as BatchColumn } from './staging.js';
+import { commandIdOf, type Key, type State } from './state.js';
+
+/** Whether a value of `schema` may hold an entity anywhere in it. */
+const holdsEntity = (schema: Schema): boolean => {
+    if (isEntity(schema)) return true;
+    if ("anyOf" in schema) return schema.anyOf.some(holdsEntity);
+    if ("allOf" in schema) return schema.allOf.some(holdsEntity);
+    if (!("type" in schema)) return false;
+    switch (schema.type) {
+        case "array": case "set": return holdsEntity(schema.items);
+        case "map": return holdsEntity(schema.keys) || holdsEntity(schema.values);
+        case "object": return Object.values(schema.properties).some(holdsEntity);
+        default: return false;
+    }
+};
+
+/** The schema at `path` inside `schema`, through struct fields and tuple items. */
+const schemaAt = (schema: Schema, path: Path): Schema | undefined => {
+    let at: Schema | undefined = schema;
+    for (const step of path) {
+        if (at === undefined || !("type" in at)) return undefined;
+        if (at.type === "object" && typeof step === "string") at = at.properties[step];
+        else if (at.type === "array" && typeof step === "number") at = at.items;
+        else return undefined;
+    }
+    return at;
+};
+
+/** The f64 leaves of a linear layout holding entities: where, in f64 elements, each row's is. */
+const entityLeavesOf = (layout: Layout, schema: Schema | undefined): readonly { readonly unitStride: number; readonly unitOffset: number }[] => {
+    if (layout.kind !== "linear" || schema === undefined) return [];
+    return layout.leaves.filter(leaf => {
+        const leafSchema = schemaAt(schema, leaf.path);
+        return leaf.view === "f64" && leafSchema !== undefined && isEntity(leafSchema);
+    });
+};
+
+/** The entity each entity of the tables given is spawned as, and what a value naming none of them becomes. */
+type Remap = (entity: number) => number;
+
+/** `value` of `schema` with each entity in it replaced by `remap`'s. */
+const remapValue = (schema: Schema, value: unknown, remap: Remap): unknown => {
+    if (isEntity(schema)) return typeof value === "number" ? remap(value) : value;
+    if (!holdsEntity(schema)) return value;
+    if ("anyOf" in schema) {
+        for (const member of schema.anyOf) {
+            if (isEntity(member) && typeof value === "number") return remap(value);
+            if (!("type" in member) || !holdsEntity(member)) continue;
+            if ((member.type === "array" && Array.isArray(value)) || (member.type === "set" && value instanceof Set) || (member.type === "map" && value instanceof Map)
+                || (member.type === "object" && typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map))) return remapValue(member, value, remap);
+        }
+        return value;
+    }
+    if ("allOf" in schema) return schema.allOf.reduce<unknown>((next, member) => remapValue(member, next, remap), value);
+    if (!("type" in schema)) return value;
+    switch (schema.type) {
+        case "array": return Array.isArray(value) ? value.map(item => remapValue(schema.items, item, remap)) : value;
+        case "set": return value instanceof Set ? new Set(Array.from(value, item => remapValue(schema.items, item, remap))) : value;
+        case "map": return value instanceof Map ? new Map(Array.from(value, ([key, item]) => [remapValue(schema.keys, key, remap), remapValue(schema.values, item, remap)])) : value;
+        case "object": {
+            if (typeof value !== "object" || value === null) return value;
+            const copy: { [name: string]: unknown } = {};
+            for (const name of Object.keys(value)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(value, name);
+                copy[name] = field === undefined ? item : remapValue(field, item, remap);
+            }
+            return copy;
+        }
+        default: return value;
+    }
+};
+
+/** A table's components with their ids, the columns given for them, and their layouts. */
+type Planned = {
+    readonly table: Table;
+    readonly keys: readonly Key[];
+    readonly ids: readonly number[];
+    readonly shared: (number | undefined)[];
+};
+
+/** Throws, naming the component, for a column that doesn't fit its component's layout or its table's count. */
+const checkColumn = (state: State, key: Key, id: number, column: Table.Column, count: number): void => {
+    const layout = state.layouts[id];
+    const fail = (message: string): never => { throw new Error(`commands.spawnTables: "${labelOf(key)}" ${message}.`); };
+    if (state.shared[id] !== undefined) {
+        if (column.kind !== "value") fail("is a shared component, so its column is one value");
+        return;
+    }
+    if (layout.kind === "constant" || column.kind === "value") return;
+    if (layout.kind === "linear") {
+        if (column.kind !== "bytes") fail("is stored as bytes, so its column gives bytes");
+        else if (column.stride !== layout.stride) fail(`has a stride of ${layout.stride} bytes in this world, not ${column.stride}`);
+        else if (column.bytes.length !== count * layout.stride) fail(`gives ${column.bytes.length} bytes for ${count} rows of ${layout.stride}`);
+        return;
+    }
+    if (column.kind !== "values") fail("is stored as values, so its column gives values");
+    else if (column.values.length !== count) fail(`gives ${column.values.length} values for ${count} rows`);
+};
+
+/** The plan of each table: its keys, their command ids, and the numbers of its shared values. Throws for one that won't spawn. */
+const planOf = (state: State, table: Table): Planned => {
+    const { count, entities, columns } = table;
+    if (!Number.isInteger(count) || count < 0 || entities.length !== count) throw new Error(`commands.spawnTables: a table of ${count} rows gives ${entities.length} entities.`);
+    const keys = Object.getOwnPropertySymbols(columns).filter(key => Reflect.get(columns, key) !== undefined);
+    const ids = keys.map(key => commandIdOf(state, key));
+    const shared: (number | undefined)[] = [];
+    keys.forEach((key, k) => {
+        const column: Table.Column = Reflect.get(columns, key);
+        checkColumn(state, key, ids[k], column, count);
+        const values = state.shared[ids[k]];
+        if (values !== undefined && column.kind === "value") {
+            const number = internShared(values, column.value);
+            if (number < 0) throw new Error(`commands.spawnTables: "${labelOf(key)}", a shared component, isn't given one of its type's values: ${labelOf(column.value)}.`);
+            shared[ids[k]] = number;
+        }
+    });
+    return { table, keys, ids, shared };
+};
+
+/**
+ * Where each entity of the tables is, by its index: the entity itself, to tell it from another of that index, and its
+ * position among all the tables' rows. Throws for an entity two rows name.
+ */
+const placesOf = (plans: readonly Planned[]): { readonly entities: Float64Array; readonly positions: Int32Array } => {
+    let largest = 0;
+    for (const { table } of plans) for (let row = 0; row < table.count; row++) largest = Math.max(largest, indexOf(table.entities[row]));
+    const entities = new Float64Array(largest + 1).fill(-1);
+    const positions = new Int32Array(largest + 1);
+    let position = 0;
+    for (const { table } of plans) {
+        for (let row = 0; row < table.count; row++) {
+            const entity = table.entities[row];
+            const index = indexOf(entity);
+            if (entities[index] === entity) throw new Error(`commands.spawnTables: entity ${entity} is in two rows.`);
+            entities[index] = entity;
+            positions[index] = position++;
+        }
+    }
+    return { entities, positions };
+};
+
+/** A reference column's entity value in each row: the f64 at the row's start, a reference's whole value. */
+const referencesOf = (column: Table.Column): ((row: number) => number) => {
+    if (column.kind !== "bytes") return () => 0;
+    const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+    const { stride } = column;
+    return row => view.getFloat64(row * stride, true);
+};
+
+/** Copies a table's `rows`, or all of them, of one column into rows `start` on of a batch's column, remapping entities. */
+const copyColumn = (target: BatchColumn, column: Table.Column, schema: Schema | undefined, rows: readonly number[] | null, count: number, start: number, remap: Remap | null): void => {
+    const rowAt = (i: number): number => rows === null ? i : rows[i];
+    const remapped = remap !== null && schema !== undefined && holdsEntity(schema);
+    if (column.kind === "value") {
+        const write = writerOf(target, column.value);
+        const value = remapped ? remapValue(schema, column.value, remap) : column.value;
+        for (let i = 0; i < count; i++) write(start + i, value);
+        return;
+    }
+    if (column.kind === "bytes") {
+        const { stride } = target;
+        if (rows === null) target.views.u8.set(column.bytes, start * stride);
+        else for (let i = 0; i < count; i++) target.views.u8.set(column.bytes.subarray(rows[i] * stride, (rows[i] + 1) * stride), (start + i) * stride);
+        if (!remapped) return;
+        const { f64 } = target.views;
+        for (const leaf of entityLeavesOf(target.layout, schema)) {
+            for (let row = start, end = start + count; row < end; row++) {
+                const index = row * leaf.unitStride + leaf.unitOffset;
+                f64[index] = remap(f64[index]);
+            }
+        }
+        return;
+    }
+    if (target.remote !== null && column.values.some(value => value !== undefined && value !== null)) throw new Error(target.remote);
+    for (let i = 0; i < count; i++) {
+        const value = column.values[rowAt(i)];
+        target.values[start + i] = remapped ? remapValue(schema, value, remap) : value;
+    }
+};
+
+/** Spawns `rows` of a plan's table, or all of them, with the components it holds but `removed`, as `entities`. */
+const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: readonly number[] | null, removed: ReadonlySet<Key>, entities: Float64Array, remap: Remap | null): void => {
+    const kept = keys.flatMap((key, k) => removed.has(key) ? [] : [k]);
+    const batch = batchOf(state, kept.map(k => ids[k]), shared.length === 0 ? undefined : shared);
+    const start = openRows(batch, entities.length);
+    for (const k of kept) {
+        const target = batch.columns.find(column => column.id === ids[k]);
+        if (target === undefined || target.layout.kind === "constant") continue;
+        const column: Table.Column = Reflect.get(table.columns, keys[k]);
+        copyColumn(target, column, declarationOf(keys[k])?.type, rows, entities.length, start, remap);
+    }
+    claimRows(batch, entities);
+};
+
+/**
+ * Spawns an entity for each row of `tables` into the batches of their components, as references would leave them had
+ * the entities outside the tables despawned: a row owned, directly or through others, by an entity outside them isn't
+ * spawned; a weak reference to one is removed; and any other entity value naming one is `Entity.none`. Every entity
+ * value naming an entity spawned names the one spawned for it.
+ */
+export const spawnTables = (state: State, tables: readonly Table[]): Table.Spawned => {
+    const plans = tables.map(table => planOf(state, table));
+    // Entities are mapped only where a value of the tables may hold one.
+    const remapping = plans.some(({ keys }) => keys.some(key => {
+        const schema = declarationOf(key)?.type;
+        return schema !== undefined && holdsEntity(schema);
+    }));
+    const none: ReadonlySet<Key> = new Set();
+    if (!remapping) {
+        const entities = plans.map(({ table }) => {
+            const spawned = new Float64Array(table.count);
+            reserveRun(state.entities, spawned);
+            return spawned;
+        });
+        plans.forEach((plan, t) => spawnRows(state, plan, null, none, entities[t], null));
+        return { entities, dropped: 0 };
+    }
+    const places = placesOf(plans);
+    const positionOf = (entity: number): number => {
+        const index = indexOf(entity);
+        return entity !== 0 && index < places.entities.length && places.entities[index] === entity ? places.positions[index] : -1;
+    };
+    const firsts: number[] = [];
+    let total = 0;
+    for (const { table } of plans) {
+        firsts.push(total);
+        total += table.count;
+    }
+    // A row owned by an entity outside the tables isn't spawned, nor anything it owns, as despawning its owner would.
+    const dropped = new Uint8Array(total);
+    /** Each owner reference between rows of the tables: the owned row's position, and its owner's. */
+    const ownedRows: number[] = [];
+    const ownerRows: number[] = [];
+    const waiting: number[] = [];
+    plans.forEach(({ table, keys }, t) => {
+        for (const key of keys) {
+            if (declarationOf(key)?.reference !== "owner") continue;
+            const ownerAt = referencesOf(Reflect.get(table.columns, key));
+            for (let row = 0; row < table.count; row++) {
+                const owner = ownerAt(row);
+                if (owner === 0) continue;
+                const at = positionOf(owner);
+                const position = firsts[t] + row;
+                if (at >= 0) {
+                    ownedRows.push(position);
+                    ownerRows.push(at);
+                }
+                else if (dropped[position] === 0) {
+                    dropped[position] = 1;
+                    waiting.push(position);
+                }
+            }
+        }
+    });
+    if (waiting.length > 0) {
+        const owned = new Map<number, number[]>();
+        for (let i = 0; i < ownedRows.length; i++) {
+            const list = owned.get(ownerRows[i]);
+            if (list === undefined) owned.set(ownerRows[i], [ownedRows[i]]);
+            else list.push(ownedRows[i]);
+        }
+        for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
+            for (const child of owned.get(next) ?? []) {
+                if (dropped[child] !== 0) continue;
+                dropped[child] = 1;
+                waiting.push(child);
+            }
+        }
+    }
+    const spawnedAt = new Float64Array(total);
+    const entities = plans.map(({ table }, t) => {
+        const alive = [];
+        for (let row = 0; row < table.count; row++) if (dropped[firsts[t] + row] === 0) alive.push(row);
+        const reserved = new Float64Array(alive.length);
+        reserveRun(state.entities, reserved);
+        const spawned = new Float64Array(table.count);
+        alive.forEach((row, i) => {
+            spawned[row] = reserved[i];
+            spawnedAt[firsts[t] + row] = reserved[i];
+        });
+        return spawned;
+    });
+    const isSpawned = (entity: number): boolean => {
+        const at = positionOf(entity);
+        return at >= 0 && dropped[at] === 0;
+    };
+    const remap: Remap = entity => isSpawned(entity) ? spawnedAt[positionOf(entity)] : 0;
+    let droppedCount = 0;
+    plans.forEach((plan, t) => {
+        const { table, keys } = plan;
+        const first = firsts[t];
+        const weak = keys.filter(key => declarationOf(key)?.reference === "weak").map(key => ({ key, targetAt: referencesOf(Reflect.get(table.columns, key)) }));
+        const loses = (row: number): boolean => weak.some(({ targetAt }) => {
+            const target = targetAt(row);
+            return target !== 0 && !isSpawned(target);
+        });
+        let whole = true;
+        for (let row = 0; row < table.count && whole; row++) if (dropped[first + row] !== 0 || loses(row)) whole = false;
+        if (whole) return spawnRows(state, plan, null, none, entities[t], remap);
+        // Rows by the weak references they lose, whose targets aren't spawned: each set of components a batch of its own.
+        const groups = new Map<string, { readonly removed: Set<Key>; readonly rows: number[] }>();
+        for (let row = 0; row < table.count; row++) {
+            if (dropped[first + row] !== 0) {
+                droppedCount++;
+                continue;
+            }
+            const removed = weak.filter(({ targetAt }) => {
+                const target = targetAt(row);
+                return target !== 0 && !isSpawned(target);
+            }).map(({ key }) => key);
+            const signature = removed.map(key => weak.findIndex(entry => entry.key === key)).join(",");
+            let group = groups.get(signature);
+            if (group === undefined) groups.set(signature, group = { removed: new Set(removed), rows: [] });
+            group.rows.push(row);
+        }
+        for (const { removed, rows } of groups.values()) spawnRows(state, plan, rows, removed, Float64Array.from(rows, row => entities[t][row]), remap);
+    });
+    return { entities, dropped: droppedCount };
+};

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

@@ -75,7 +75,7 @@ describe("tails", () => {
         const { world, remote } = await joined({ loop: driver }, { [always]: true });
         await world.run(seed, { count: 10 });
         const counters: number[] = [];
-        const values = System.create({ observer: true }, ({ resources }) => { counters.push(resources[counter]); });
+        const values = System.create({ readonly: true }, ({ resources }) => { counters.push(resources[counter]); });
         world.add(ticked);
         world.add(values);
         await until(Observe.resource(world, counter), value => value >= 5);

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

@@ -24,8 +24,8 @@ const remove = System.create({ target: "entity", components: { with: [tagged] }
 });
 let amounts: number[] = [];
 let changed: number[] = [];
-const readAmounts = System.create({ observer: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
-const watchChanged = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
+const readAmounts = System.create({ readonly: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
+const watchChanged = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
 
 const inline = () => createWorld({ [workers]: 0 });
 const amountsOf = async (world: ReturnType<typeof inline>): Promise<number[]> => {

package/src/implementation/world/thread-observer.ts

@@ -69,7 +69,7 @@ const errorOf = (error: unknown): WorkerError =>
 
 const refuse = (): never => { throw new Error("An observer system issues no commands."); };
 /** An observer system's context has no commands, so these are never called. */
-const noCommands: Commands = { spawn: refuse, despawn: refuse, add: refuse, remove: refuse };
+const noCommands: Commands = { spawn: refuse, despawn: refuse, add: refuse, remove: refuse, spawnTables: refuse };
 const noStamps: number[] = [];
 
 export const createThreadObserver = (host: ThreadObserverHost) => {

package/src/implementation/world/thread-systems.test-helper.ts

@@ -172,7 +172,7 @@ const reading: { entities: readonly Entity[]; objects: readonly { readonly [name
 
 /** Each entity's objects of the thread, as data, a note by its text: none for an entity that's dead or has no uid. */
 const readObjects = System.create({
-    observer: true,
+    readonly: true,
     lookup: { ids: { with: [uid] }, captions: { with: [caption] }, notes: { with: [note] } },
 }, ({ lookup }) => {
     reading.objects = reading.entities.map(entity => {
@@ -322,9 +322,9 @@ export const paintReader = System.create(({ resources }) => () => resources[pain
 /** A composite of systems on the thread returning values, which no run resolves to. */
 export const paintsTogether = System.create([paintReader, paintLengthThere]);
 /** An observer system on the thread, as it reads the thread's paint: what a run of it resolves to. */
-export const paintObserved = System.create({ observer: true }, ({ resources }) => resources[paint].text);
+export const paintObserved = System.create({ readonly: true }, ({ resources }) => resources[paint].text);
 /** An observer system on the thread, throwing there. */
-export const paintObservedFails = System.create({ observer: true }, ({ resources }) => {
+export const paintObservedFails = System.create({ readonly: true }, ({ resources }) => {
     if (resources[paint].text !== "never") throw new Error("threadSystemsTest observer failure there");
     return 0;
 });