@adobe/ecs 0.2.3 → 0.2.4

package/src/implementation/world/sync-points.test.ts

@@ -0,0 +1,135 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Index } from "../../interface/indexes/index-type.js";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { count as countOf, readEach, select } from "./reads.test-helper.js";
+
+const position = Symbol("syncPointsTest/position");
+const cell = Symbol("syncPointsTest/cell");
+const found = Symbol("syncPointsTest/found");
+const team = Symbol("syncPointsTest/team");
+const member = Symbol("syncPointsTest/member");
+const local = Symbol("syncPointsTest/local");
+const total = Symbol("syncPointsTest/total");
+const parent = Symbol("syncPointsTest/parent");
+const seed = Symbol("syncPointsTest/seed");
+const grown = Symbol("syncPointsTest/grown");
+const children = Symbol("syncPointsTest/children");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [cell]: { type: number };
+        [team]: { type: true };
+        [member]: { type: Entity; reference: "owner" };
+        [local]: { type: number };
+        [total]: { type: number };
+        [parent]: { type: Entity; reference: "weak" };
+        [seed]: { type: number };
+        [grown]: { type: number };
+    }
+    export interface Resources {
+        [found]: { type: number };
+        [children]: { type: number; default: 0 };
+    }
+}
+
+const byCell = Index.create({ key: [cell] });
+
+const spawn = System.create(({ commands }) => { for (let k = 0; k < 3; k++) commands.spawn([position])({ [position]: k }); });
+const counted: number[] = [];
+const count = System.create({ components: { with: [position] }, after: [spawn] }, row => { counted.push(row[position]); });
+const changes: number[] = [];
+const watchChanges = System.create({ components: { with: [position], changed: [position] }, after: [count] }, row => { changes.push(row[position]); });
+const deriveCells = System.create({ components: { with: [position], not: [cell] }, after: [watchChanges] }, (row, { commands }) => { commands.add(row.entity, cell, row[position] % 2); });
+const pick = System.create({ lookup: { cells: { index: byCell } }, after: [deriveCells] }, ({ lookup, resources }) => { resources[found] = lookup.cells(0).length; });
+const readFound = System.create({ readonly: true }, ({ resources }) => resources[found]);
+const frame = System.create([spawn, count, watchChanges, deriveCells, pick]);
+
+const spawnTeams = System.create(({ commands }) => {
+    for (let k = 0; k < 3; k++) {
+        const owner = commands.spawn([team])();
+        for (let m = 0; m < 2; m++) commands.spawn([member])({ [member]: owner });
+    }
+});
+const disband = System.create({ components: { with: [team] }, after: [spawnTeams] }, (row, { commands }) => { commands.despawn(row.entity); });
+const round = System.create([spawnTeams, disband]);
+
+/** Spawns a root, `count` children of it and a child of each. */
+const spawnTree = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    const root = commands.spawn([local, total])({ [local]: 1, [total]: 0 });
+    for (let k = 0; k < input.count; k++) {
+        const child = commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: root });
+        commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: child });
+    }
+});
+const propagate = System.create({ components: { with: [local, total], changed: [local] }, up: { through: parent }, after: [spawnTree] }, (row, { up }) => {
+    row[total] = (up === null ? 0 : up[total]) + row[local];
+});
+const grow = System.create([spawnTree, propagate]);
+
+const plant = System.create(({ commands }) => { for (let k = 0; k < 64; k++) commands.spawn([seed])({ [seed]: k }); });
+const sprout = System.create({ kernel: true, components: { with: [seed] }, after: [plant] }, (row, { commands }) => {
+    commands.spawn([grown])({ [grown]: row[seed] * 2 });
+});
+const tally = System.create({ components: { with: [grown] }, after: [sprout] }, (row, { resources }) => { resources[children] += row[grown]; });
+const garden = System.create([plant, sprout, tally]);
+const readChildren = System.create({ readonly: true }, ({ resources }) => resources[children]);
+
+describe("sync points within a run", () => {
+    it("apply commands before a later system that depends on what they change, which then sees them in the same run", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(frame);
+        expect(counted).toEqual([0, 1, 2]);
+        expect(await world.run(readFound)).toBe(2);
+        await world.dispose();
+    });
+    it("keep each change seen once by change filters across runs", async () => {
+        const world = createWorld({ [workers]: 0 });
+        changes.length = 0;
+        await world.run(frame);
+        expect(changes).toEqual([0, 1, 2]);
+        changes.length = 0;
+        counted.length = 0;
+        await world.run(frame);
+        // The second run's spawns are new; the first run's three are seen again by count alone.
+        expect([counted.length, changes]).toEqual([6, [0, 1, 2]]);
+        expect(await world.run(readFound)).toBe(4);
+        await world.dispose();
+    });
+
+    it("despawn what rows spawned at an earlier sync point of the run own, once a later tier despawns their owners", async () => {
+        expect(System.describe(round).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(round);
+        expect([await countOf(world, { required: [team] }), await countOf(world, { required: [member] })]).toEqual([0, 0]);
+    });
+
+    it("bring an `up` tree up to date at each, built again or patched, for a tier after it in the same run", async () => {
+        expect(System.describe(grow).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        let spawned = 0;
+        // Past the journal's worth a tree patches, then within it.
+        for (const count of [5_000, 3_000, 10]) {
+            await world.run(grow, { count });
+            spawned += count;
+            const totals = await readEach(world, await select(world, { required: [total] }), total);
+            const byDepth = [1, 2, 3].map(depth => totals.filter(value => value === depth).length);
+            expect([byDepth, totals.length]).toEqual([[totals.length - 2 * spawned, spawned, spawned], totals.length]);
+        }
+    });
+
+    it("commit a kernel's staged spawns at a sync point within the run, for a later tier", async () => {
+        expect(System.describe(garden).tiers.map(tier => tier.sync === null)).toEqual([false, false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        const sum = 63 * 64;
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum);
+        // The second run's seeds are both runs' plantings, and its tally reads the first run's grown rows too.
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum + sum + 2 * sum);
+    });
+});

package/src/implementation/world/synchronize.ts

@@ -2,10 +2,10 @@
 import type { Views } from '../../interface/registry/layout.js';
 import { copyValue, ensureCapacity, swapRemove, writeF32, writeF32Lanes, writeF64, writeI32, writeU32, type Archetype, type Storage } from './archetype.js';
 import { blockShift, chunkShift } from './kernel.js';
-import { addCommand, clearBuffer, despawnCommand, endOf, referenceAt, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, clearBuffer, despawnCommand, despawnWhereCommand, despawnWhereHolds, endOf, referenceAt, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
 import { readCell, writeCell } from './cells.js';
 import { commitBatches, commitStaged } from './batches.js';
-import { applyIndexChanges, cascadeReferences, indexChangesOf, type IndexChanges, type Written } from './cascade.js';
+import { applyIndexChanges, cascadeReferences, indexChangesOf, linkBorn, type IndexChanges, type Written } from './cascade.js';
 import { refreshDirectories } from './directories.js';
 import { createArrivals, logArrival } from './arrivals.js';
 import { noteEdge, noteEmptied, reclaimEmptied } from './reclaim.js';
@@ -21,6 +21,8 @@ import type { Plan } from './plan.js';
 import type { MoveLog } from './move-log.js';
 import { archetypeOf, movesOf, sharedNumberOf, withComponent, withoutComponent, withShared, type State } from './state.js';
 import { releaseValue } from './transfers.js';
+import { resourcesWritten } from './resource-changes.js';
+import { recordPlan } from './run-changes.js';
 
 /** Buffers queued for the next sync point, in merge order. Commands in guarded buffers can't touch the resource entity. */
 export type Queued = { readonly buffer: CommandBuffer; readonly guarded: boolean };
@@ -127,6 +129,56 @@ const releaseDropped = (state: State, buffer: CommandBuffer, command: number): v
     }
 };
 
+/**
+ * Whether `archetype` has each component of `ids` from `start` to `middle` and none from there to `end`, and holds the
+ * values `holds` tells it holds, when it isn't null.
+ */
+const matches = (archetype: Archetype, ids: Int32Array, start: number, middle: number, end: number, holds: Function | null): boolean => {
+    const { storageById } = archetype;
+    for (let k = start; k < middle; k++) if (storageById[ids[k]] === undefined) return false;
+    for (let k = middle; k < end; k++) if (storageById[ids[k]] !== undefined) return false;
+    return holds === null || Reflect.apply(holds, undefined, [archetype]) === true;
+};
+
+/** The archetype an entity planned into `archetype` ends up in once derived. */
+const closedOf = (state: State, archetype: Archetype): Archetype => {
+    const cached = state.structure.closures[archetype.id] ?? -1;
+    return cached >= 0 ? state.archetypes[cached] : closureOf(state.structure, state.derived, archetype, (components, shared) => archetypeOf(state, components, shared), state.archetypes);
+};
+
+/**
+ * Despawns each entity a `despawnWhere` command selects given the plan so far: those planned, by where they're going,
+ * then the rest, by the archetype they're in. Never the resource entity.
+ */
+const despawnWhere = (state: State, buffer: CommandBuffer, command: number, within: boolean): void => {
+    const { plan, archetypes } = state;
+    const { ids } = buffer;
+    const start = buffer.starts[command];
+    const middle = start + buffer.entities[command];
+    const last = endOf(buffer, command);
+    const where = ids[last - 1] === despawnWhereHolds ? buffer.values[last - 1] : null;
+    const holds = typeof where === "function" ? where : null;
+    const end = holds === null ? last : last - 1;
+    for (let entry = 0; entry < plan.count; entry++) {
+        if (plan.despawned[entry] === 1 || plan.entity[entry] === state.resourceEntity) continue;
+        const to = archetypes[plan.to[entry]];
+        if (matches(within && plan.to[entry] !== plan.from[entry] ? closedOf(state, to) : to, ids, start, middle, end, holds)) plan.despawned[entry] = 1;
+    }
+    const { slots } = plan;
+    const count = archetypes.length;
+    for (let id = 0; id < count; id++) {
+        const archetype = archetypes[id];
+        if (archetype.resource || archetype.count === 0 || !matches(archetype, ids, start, middle, end, holds)) continue;
+        ensurePlanCapacity(state, plan.count + archetype.count);
+        const { entities } = archetype;
+        for (let row = 0; row < archetype.count; row++) {
+            const entity = entities[row];
+            const index = indexOf(entity);
+            if (slots[index] < 0) plan.despawned[addPlanned(state, entity, index, id, id)] = 1;
+        }
+    }
+};
+
 /**
  * Plan: the net change for each entity, in issue order. Commands against dead entities do nothing. Reference values
  * written by commands go to `written`, to check once despawns are known.
@@ -146,6 +198,11 @@ const planOf = (state: State, queued: readonly Queued[], written: Written): void
         ensurePlanCapacity(state, plan.count + buffer.count);
         for (let command = 0; command < buffer.count; command++) {
             const kind = kinds[command];
+            if (kind === despawnWhereCommand) {
+                despawnWhere(state, buffer, command, within);
+                ensurePlanCapacity(state, plan.count + buffer.count - command);
+                continue;
+            }
             const entity = entities[command];
             if (guarded && entity === state.resourceEntity) continue;
             const index = indexOf(entity);
@@ -631,7 +688,9 @@ const noneQueued: readonly Queued[] = [];
 export const syncPending = (state: State, queued: readonly Queued[] = state.queued): boolean =>
     anyCommands(queued) || reserved(state.entities) || state.carried !== null || state.structure.rederive
     // Failures for its run, as a gone thread's stops it never finalized are.
-    || state.unplaced.length > 0;
+    || state.unplaced.length > 0
+    // A watched resource written, which its changes finalizers see at a sync point.
+    || (state.resourcesSeen.size > 0 && resourcesWritten(state));
 
 /**
  * The first half of a sync point: commits batch spawns, plans every command, cascades references and closes the plan
@@ -688,22 +747,9 @@ const preparePending = (state: State, queued: readonly Queued[], isolated: boole
         if (deriving) for (let entry = 0; entry < plan.count; entry++) if (plan.despawned[entry] === 0) plan.to[entry] = close(state.archetypes[plan.to[entry]]).id;
         let index: IndexChanges | null = null;
         if (structure.referenceIds.length > 0) {
-            for (const [id, first] of born) {
-                const archetype = state.archetypes[id];
-                for (const component of structure.referenceIds) {
-                    const storage = archetype.storageById[component];
-                    if (storage === undefined) continue;
-                    for (let row = first; row < archetype.count; row++) written.push(archetype.entities[row], component, Number(readCell(storage, row)));
-                }
-            }
+            linkBorn(state, born, written, tick);
             cascadeReferences(state, queued, written, entity => entryOf(state, entity));
-            const fromOf = (entry: number): Archetype | null => {
-                const from = plan.from[entry];
-                if (from < 0) return null;
-                const first = born.get(from);
-                return first !== undefined && state.entities.row[indexOf(plan.entity[entry])] >= first ? null : state.archetypes[from];
-            };
-            index = indexChangesOf(state, queued, fromOf, [...born].map(([id, first]) => [state.archetypes[id], first] as const));
+            index = indexChangesOf(state, queued, entry => plan.from[entry] < 0 ? null : state.archetypes[plan.from[entry]]);
         }
         // References change only here: each component written to is stamped, and each holder journaled, as are spawns.
         for (let k = 1; k < written.length; k += 3) state.referencesWritten[written[k]] = tick;
@@ -741,6 +787,7 @@ export const applySync = (state: State): readonly Thrown[] => {
     let errors = nothingThrown;
     try {
         if (state.unplaced.length > 0 && !isolated) errors = state.unplaced.splice(0);
+        if (state.recording !== null && !isolated) recordPlan(state, state.recording, queued, born);
         if (state.finalizers.length > 0 && !isolated) {
             const thrown = runFinalizers(state, queued, born, tick);
             errors = errors.length === 0 ? thrown : [...errors, ...thrown];

package/src/implementation/world/tables-read.ts

@@ -2,10 +2,11 @@
 import { labelOf } from '../../interface/registry/names.js';
 import type { Tables, TablesDeclaration } from '../../interface/system/tables.js';
 import type { Table } from '../../interface/world/table/table.js';
-import type { Storage } from './archetype.js';
+import type { Archetype, Storage } from './archetype.js';
 import { readCell } from './cells.js';
 import { resourceCell } from './resources.js';
 import { idOf, type Key, type State } from './state.js';
+import { holdsValuesOf } from './where.js';
 
 // Reading tables, apart from spawning them: rows' contexts import it, and what spawning imports would make a cycle.
 
@@ -27,12 +28,21 @@ const columnOf = (key: Key, storage: Storage, count: number): Table.Column => {
 };
 
 /**
- * A readonly system's `tables`: of each archetype matching `with` and `not` and holding any of `components`, its
- * entities and a copy of the column of each of them it holds; and the value of each resource of `resources`.
+ * A readonly system's `tables`, read by the function this returns, once per read: of each archetype matching `with`,
+ * `not` and `where` and holding any of `components`, its entities and a copy of the column of each of them it holds;
+ * and the value of each resource of `resources`. `where` holds its values as a system's does, and an archetype
+ * matches it as one matches a system's `where`, required as `with` requires them.
  */
-export const readTables = (state: State, declaration: TablesDeclaration): Tables => {
+export const tablesReader = (state: State, declaration: TablesDeclaration): (() => Tables) => {
+    const holds = declaration.where === undefined ? null : holdsValuesOf(state, declaration.where, true);
+    if (typeof holds === "symbol") throw new Error(`Tables' where names "${labelOf(holds)}", which isn't a shared component.`);
+    const where = declaration.where === undefined ? [] : Object.getOwnPropertySymbols(declaration.where);
+    return () => readTables(state, declaration, [...where, ...declaration.with ?? []], holds);
+};
+
+const readTables = (state: State, declaration: TablesDeclaration, requiring: readonly Key[], holds: ((archetype: Archetype) => boolean) | null): Tables => {
     const asked = declaration.components.map(key => ({ key, id: idOf(state, key) }));
-    const required = (declaration.with ?? []).map(key => idOf(state, key));
+    const required = requiring.map(key => idOf(state, key));
     const excluded = (declaration.not ?? []).map(key => idOf(state, key));
     const archetypes: Table[] = [];
     for (const archetype of state.archetypes) {
@@ -40,6 +50,7 @@ export const readTables = (state: State, declaration: TablesDeclaration): Tables
         if (count === 0 || archetype.reclaimed) continue;
         const { storageById } = archetype;
         if (required.some(id => storageById[id] === undefined) || excluded.some(id => storageById[id] !== undefined)) continue;
+        if (holds !== null && !holds(archetype)) continue;
         const columns: { [key: symbol]: Table.Column } = {};
         let held = false;
         for (const { key, id } of asked) {

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

@@ -46,16 +46,31 @@ const tablesOf = (components: readonly Component.Key[], resources: readonly Reso
     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 given: { tables: readonly Table[]; resources?: { readonly [key: symbol]: unknown }; existing?: ReadonlyMap<Entity, Entity> } = { tables: [] };
 const spawnGiven = System.create(({ commands }) => {
-    spawnedBy.spawned = given.resources === undefined ? commands.spawnTables(given.tables) : commands.spawnTables(given.tables, given.resources);
+    spawnedBy.spawned = commands.spawnTables(given.tables, { resources: given.resources, existing: given.existing });
 });
-const spawnTables = async (world: ReturnType<typeof inline>, tables: readonly Table[]): Promise<Table.Spawned> => {
+const spawnTables = async (world: ReturnType<typeof inline>, tables: readonly Table[], existing?: ReadonlyMap<Entity, Entity>): Promise<Table.Spawned> => {
     given.tables = tables;
-    await world.run(spawnGiven);
+    given.existing = existing;
+    try {
+        await world.run(spawnGiven);
+    }
+    finally {
+        given.existing = undefined;
+    }
     return spawnedBy.spawned;
 };
 
+/** Spawns `labels` in `world`, giving each label's entity. */
+const spawnLabels = async (world: ReturnType<typeof inline>, labels: readonly string[]): Promise<ReadonlyMap<string, Entity>> => {
+    const made = new Map<string, Entity>();
+    await world.run(System.create(({ commands }) => {
+        for (const text of labels) made.set(text, commands.spawn([label])({ [label]: text }));
+    }));
+    return made;
+};
+
 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] });
 });
@@ -198,6 +213,53 @@ describe("tables", () => {
         expect(read.find(entry => entry.label === "pointing")).toMatchObject({ buddy: Entity.none, link: { to: Entity.none, weight: 1 }, friends: [Entity.none, inside] });
     });
 
+    it("spawn no row existing maps, giving the entity it maps to, which every entity value naming it names", async () => {
+        await using world = inline();
+        let steel = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            steel = commands.spawn([label])({ [label]: "steel" });
+            commands.spawn([label, parent, target, buddy, link, friends])({ [label]: "body", [parent]: steel, [target]: steel, [buddy]: steel, [link]: { to: steel, weight: 2 }, [friends]: [steel] });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, parent, target, buddy, link, friends]));
+        await using other = inline();
+        const existingSteel = (await spawnLabels(other, ["steel in other"])).get("steel in other") ?? Entity.none;
+        const { entities, dropped } = await spawnTables(other, archetypes, new Map([[steel, existingSteel]]));
+        expect(dropped).toBe(0);
+        expect(entities.flatMap(list => [...list])).toContain(existingSteel);
+        const read = await readAll(other);
+        // Steel isn't spawned again: the body's every entity value names the one already there.
+        expect(read.map(entry => entry.label)).toEqual(["body", "steel in other"]);
+        expect(read.find(entry => entry.label === "body")).toMatchObject({ parent: existingSteel, target: existingSteel, buddy: existingSteel, link: { to: existingSteel, weight: 2 }, friends: [existingSteel] });
+    });
+
+    it("let an entity existing maps stand for one outside the tables, so what it owns or points at is kept", async () => {
+        await using world = inline();
+        let steel = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            steel = commands.spawn([pinned])();
+            commands.spawn([label, parent, target])({ [label]: "owned", [parent]: steel, [target]: steel });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, parent, target]));
+        await using other = inline();
+        const existingSteel = (await spawnLabels(other, ["steel"])).get("steel") ?? Entity.none;
+        const { dropped } = await spawnTables(other, archetypes, new Map([[steel, existingSteel]]));
+        expect(dropped).toBe(0);
+        expect((await readAll(other)).find(entry => entry.label === "owned")).toMatchObject({ parent: existingSteel, target: existingSteel });
+    });
+
+    it("refuse existing mapping to an entity that isn't alive, spawning nothing", async () => {
+        await using world = inline();
+        const gone = (await spawnLabels(world, ["gone"])).get("gone") ?? Entity.none;
+        await world.run(System.create(({ commands }) => { commands.despawn(gone); }));
+        const { archetypes } = await world.run(tablesOf([label]));
+        await using source = inline();
+        const steel = (await spawnLabels(source, ["steel"])).get("steel") ?? Entity.none;
+        const { archetypes: tables } = await source.run(tablesOf([label]));
+        expect(archetypes).toEqual([]);
+        await expect(spawnTables(world, tables, new Map([[steel, gone]]))).rejects.toThrow(new RegExp(`as entity ${gone}, which isn't alive`));
+        expect(await readAll(world)).toEqual([]);
+    });
+
     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 = [];
@@ -249,6 +311,46 @@ describe("tables", () => {
         expect(await readAll(world)).toEqual([]);
     });
 
+    it("keep to the archetypes holding where's shared values, each required as with requires it", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([team, label], { [team]: "red" })({ [label]: "red" });
+            commands.spawn([team, label, position], { [team]: "red" })({ [label]: "red placed", [position]: [1, 1, 1] });
+            commands.spawn([team, label], { [team]: "blue" })({ [label]: "blue" });
+            commands.spawn([label])({ [label]: "none" });
+        }));
+        const red = await world.run(System.create({ readonly: true, tables: { components: [label], where: { [team]: "red" } } }, ({ tables }): Tables => tables));
+        expect(red.archetypes.map(table => table.columns[label]).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))))
+            .toEqual([{ kind: "values", values: ["red placed"] }, { kind: "values", values: ["red"] }]);
+        const placed = await world.run(System.create({ readonly: true, tables: { components: [label], with: [position], where: { [team]: "red" } } }, ({ tables }): Tables => tables));
+        expect(placed.archetypes.map(table => table.columns[label])).toEqual([{ kind: "values", values: ["red placed"] }]);
+        // One system's tables follow its archetypes as they come and go.
+        const blue = System.create({ readonly: true, tables: { components: [label], where: { [team]: "blue" } } }, ({ tables }): Tables => tables);
+        expect((await world.run(blue)).archetypes.map(table => table.count)).toEqual([1]);
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([team, label, position], { [team]: "blue" })({ [label]: "blue placed", [position]: [2, 2, 2] });
+        }));
+        expect((await world.run(blue)).archetypes.map(table => table.count)).toEqual([1, 1]);
+    });
+
+    it("give no table for a shared value no archetype holds", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => { commands.spawn([team, label], { [team]: "red" })({ [label]: "red" }); }));
+        const blue = System.create({ readonly: true, tables: { components: [label], where: { [team]: "blue" } } }, ({ tables }): Tables => tables);
+        expect((await world.run(blue)).archetypes).toEqual([]);
+        await world.run(System.create(({ commands }) => { commands.spawn([team, label], { [team]: "blue" })({ [label]: "blue" }); }));
+        expect((await world.run(blue)).archetypes.map(table => table.columns[label])).toEqual([{ kind: "values", values: ["blue"] }]);
+    });
+
+    it("take only values of shared components in where", () => {
+        // @ts-expect-error: where names only shared components.
+        expect(() => System.create({ readonly: true, tables: { components: [label], where: { [label]: "a" } } }, () => {})).toThrow(/tables' where names "tablesTest\/label", which isn't a shared component/);
+        // @ts-expect-error: tables' where takes values, not predicates.
+        expect(() => System.create({ readonly: true, tables: { components: [label], where: { [team]: (value: string) => value === "red" } } }, () => {})).toThrow(/tables' where gives "tablesTest\/team" a predicate/);
+        // @ts-expect-error: a value of the component's type.
+        expect(() => System.create({ readonly: true, tables: { components: [label], where: { [team]: "green" } } }, () => {})).toThrow(/isn't one of its type's values/);
+    });
+
     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/);

package/src/implementation/world/tables.ts

@@ -5,7 +5,7 @@ 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 { indexOf, locate, 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';
@@ -153,6 +153,12 @@ const placesOf = (plans: readonly Planned[]): { readonly entities: Float64Array;
 /** 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 { bytes } = column;
+    if (bytes.byteOffset % 8 === 0 && column.stride % 8 === 0) {
+        const view = new Float64Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 3);
+        const words = column.stride >> 3;
+        return row => view[row * words];
+    }
     const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
     const { stride } = column;
     return row => view.getFloat64(row * stride, true);
@@ -203,16 +209,25 @@ const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: re
     claimRows(batch, entities);
 };
 
+/** Throws for an entity `existing` maps to that isn't alive in this world. */
+const checkExisting = (state: State, existing: ReadonlyMap<number, number>): void => {
+    for (const [source, target] of existing) {
+        if (locate(state.entities, target) < 0) throw new Error(`commands.spawnTables: entity ${source} is given as existing as entity ${target}, which isn't alive.`);
+    }
+};
+
 /**
  * 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.
+ * value naming an entity spawned names the one spawned for it. A row whose entity `existing` maps isn't spawned: the
+ * entity it maps to stands for it, as it does for an entity outside the tables that `existing` maps.
  */
-export const spawnTables = (state: State, tables: readonly Table[]): Table.Spawned => {
+export const spawnTables = (state: State, tables: readonly Table[], existing: ReadonlyMap<number, number> = new Map()): 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 => {
+    checkExisting(state, existing);
+    // Entities are mapped only where a value of the tables may hold one, or a row is one that exists.
+    const remapping = existing.size > 0 || plans.some(({ keys }) => keys.some(key => {
         const schema = declarationOf(key)?.type;
         return schema !== undefined && holdsEntity(schema);
     }));
@@ -237,65 +252,87 @@ export const spawnTables = (state: State, tables: readonly Table[]): Table.Spawn
         firsts.push(total);
         total += table.count;
     }
+    // The entity standing for each row `existing` maps, 0 for a row spawned.
+    const existingAt = new Float64Array(total);
+    if (existing.size > 0) plans.forEach(({ table }, t) => {
+        for (let row = 0; row < table.count; row++) existingAt[firsts[t] + row] = existing.get(table.entities[row]) ?? 0;
+    });
     // 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) => {
+    /**
+     * Calls `each` with each owner reference of a row that doesn't exist: the owned row's position, its owner's among
+     * the tables' rows or -1 for an owner outside them, and the owner.
+     */
+    const forEachOwner = (each: (position: number, at: number, owner: number) => void): void => 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);
-                }
+                // A row that exists stands, whatever owns it.
+                if (owner !== 0 && existingAt[position] === 0) each(position, positionOf(owner), owner);
             }
         }
     });
+    forEachOwner((position, at, owner) => {
+        if (at >= 0 || dropped[position] !== 0 || existing.has(owner)) return;
+        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]);
-        }
+        forEachOwner((position, at) => {
+            if (at < 0) return;
+            const list = owned.get(at);
+            if (list === undefined) owned.set(at, [position]);
+            else list.push(position);
+        });
         for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
             for (const child of owned.get(next) ?? []) {
-                if (dropped[child] !== 0) continue;
+                if (dropped[child] !== 0 || existingAt[child] !== 0) continue;
                 dropped[child] = 1;
                 waiting.push(child);
             }
         }
     }
+    // Each row's entity in this world: the one spawned for it, the one existing for it, or 0 for one dropped.
     const spawnedAt = new Float64Array(total);
+    /** By table, whether every row of it is spawned: none exists or is dropped. */
+    const wholly: boolean[] = [];
     const entities = plans.map(({ table }, t) => {
+        const first = firsts[t];
+        const spawned = new Float64Array(table.count);
+        let standing = 0;
+        for (let row = 0; row < table.count; row++) if (existingAt[first + row] !== 0 || dropped[first + row] !== 0) standing++;
+        wholly.push(standing === 0);
+        if (standing === 0) {
+            reserveRun(state.entities, spawned);
+            spawnedAt.set(spawned, first);
+            return spawned;
+        }
         const alive = [];
-        for (let row = 0; row < table.count; row++) if (dropped[firsts[t] + row] === 0) alive.push(row);
+        for (let row = 0; row < table.count; row++) {
+            const position = first + row;
+            if (existingAt[position] !== 0) spawnedAt[position] = spawned[row] = existingAt[position];
+            else if (dropped[position] === 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];
+            spawnedAt[first + row] = reserved[i];
         });
         return spawned;
     });
-    const isSpawned = (entity: number): boolean => {
+    /** The entity in this world for one of the tables' or one `existing` maps, or 0 for one that isn't there. */
+    const entityFor = (entity: number): number => {
         const at = positionOf(entity);
-        return at >= 0 && dropped[at] === 0;
+        return at >= 0 ? spawnedAt[at] : existing.get(entity) ?? 0;
     };
-    const remap: Remap = entity => isSpawned(entity) ? spawnedAt[positionOf(entity)] : 0;
+    const isSpawned = (entity: number): boolean => entityFor(entity) !== 0;
+    const remap: Remap = entityFor;
     let droppedCount = 0;
     plans.forEach((plan, t) => {
         const { table, keys } = plan;
@@ -305,12 +342,13 @@ export const spawnTables = (state: State, tables: readonly Table[]): Table.Spawn
             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;
+        let whole = wholly[t];
+        if (weak.length > 0) for (let row = 0; row < table.count && whole; row++) if (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 (existingAt[first + row] !== 0) continue;
             if (dropped[first + row] !== 0) {
                 droppedCount++;
                 continue;

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, spawnTables: refuse };
+const noCommands: Commands = { spawn: refuse, despawn: refuse, despawnWhere: refuse, add: refuse, remove: refuse, spawnTables: refuse };
 const noStamps: number[] = [];
 
 export const createThreadObserver = (host: ThreadObserverHost) => {