@adobe/ecs 0.2.3 → 0.3.0

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,11 +129,67 @@ 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 alive before the sync point that 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, nor an
+ * entity the sync point spawns: `born` holds the first row each archetype gained at it.
+ */
+const despawnWhere = (state: State, buffer: CommandBuffer, command: number, within: boolean, born: ReadonlyMap<number, number>): 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;
+    const { row } = state.entities;
+    for (let entry = 0; entry < plan.count; entry++) {
+        const from = plan.from[entry];
+        if (plan.despawned[entry] === 1 || plan.entity[entry] === state.resourceEntity || from < 0) continue;
+        const first = born.get(from);
+        if (first !== undefined && row[indexOf(plan.entity[entry])] >= first) 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;
+        const alive = born.get(id) ?? archetype.count;
+        for (let at = 0; at < alive; at++) {
+            const entity = entities[at];
+            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.
  */
-const planOf = (state: State, queued: readonly Queued[], written: Written): void => {
+const planOf = (state: State, queued: readonly Queued[], written: Written, born: ReadonlyMap<number, number>): void => {
     const { plan, structure } = state;
     if (plan.slots.length < state.entities.length) plan.slots = new Int32Array(Math.max(state.entities.length, plan.slots.length * 2)).fill(-1);
     const { slots } = plan;
@@ -146,6 +204,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, born);
+                ensurePlanCapacity(state, plan.count + buffer.count - command);
+                continue;
+            }
             const entity = entities[command];
             if (guarded && entity === state.resourceEntity) continue;
             const index = indexOf(entity);
@@ -631,7 +694,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
@@ -683,27 +748,14 @@ const preparePending = (state: State, queued: readonly Queued[], isolated: boole
         if (!isolated) plan.spawned += commitBatches(state, tick, born, deriving ? close : null);
         plan.spawned += commitStaged(state, queued, tick, born, deriving ? close : null);
         const written: Written = [];
-        planOf(state, queued, written);
+        planOf(state, queued, written, born);
         if (structure.rederive && !isolated) rederive(state);
         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 +793,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,33 @@ 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>; update?: boolean } = { 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, update: given.update });
 });
-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>, update?: boolean): Promise<Table.Spawned> => {
     given.tables = tables;
-    await world.run(spawnGiven);
+    given.existing = existing;
+    given.update = update;
+    try {
+        await world.run(spawnGiven);
+    }
+    finally {
+        given.existing = undefined;
+        given.update = 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 +215,84 @@ 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("write a row existing maps onto its entity with update, as an add would, entity values rewritten as a spawned row's", async () => {
+        await using world = inline();
+        let steel = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            const inside = commands.spawn([label])({ [label]: "inside" });
+            const outside = commands.spawn([pinned])();
+            steel = commands.spawn([label, position, buddy, target, link, team], { [team]: "red" })({ [label]: "steel", [position]: [1, 2, 3], [buddy]: inside, [target]: outside, [link]: { to: inside, weight: 4 } });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, position, buddy, target, link, team]));
+        await using other = inline();
+        let mine = Entity.none, kept = Entity.none;
+        await other.run(System.create(({ commands }) => {
+            kept = commands.spawn([label])({ [label]: "kept" });
+            mine = commands.spawn([label, hidden, target, team], { [team]: "blue" })({ [label]: "mine", [target]: kept });
+        }));
+        const changed: string[] = [];
+        const watch = System.create({ components: { with: [label], changed: [label] } }, row => { changed.push(row[label]); });
+        await other.run(watch);
+        changed.length = 0;
+        const { entities, dropped } = await spawnTables(other, archetypes, new Map([[steel, mine]]), true);
+        expect([dropped, entities.flatMap(list => [...list]).includes(mine)]).toEqual([0, true]);
+        const read = await readAll(other);
+        const inside = read.find(entry => entry.label === "inside")?.entity;
+        // The weak reference to an entity outside the tables is left out, so the entity's own stands.
+        expect(read.find(entry => entry.entity === mine)).toMatchObject({ label: "steel", position: [1, 2, 3], buddy: inside, target: kept, link: { to: inside, weight: 4 } });
+        const teams = await other.run(System.create({ readonly: true, tables: { components: [team, hidden] } }, ({ tables }) => tables.archetypes.map(table => [table.columns[team], table.columns[hidden] !== undefined])));
+        expect(teams).toEqual([[{ kind: "value", value: "red" }, true]]);
+        await other.run(watch);
+        expect(changed.sort()).toEqual(["inside", "steel"]);
+    });
+
+    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 +344,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

@@ -1,14 +1,15 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-import type { Layout, Path } from '../../interface/registry/layout.js';
+import { viewsOf, type Layout, type 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 { 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';
+import { commandIdOf, storedShared, type Key, type State } from './state.js';
+import { addCommand, pushCommand, pushComponent, type CommandBuffer } from './buffer.js';
 
 /** Whether a value of `schema` may hold an entity anywhere in it. */
 const holdsEntity = (schema: Schema): boolean => {
@@ -153,6 +154,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 +210,64 @@ const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: re
     claimRows(batch, entities);
 };
 
+/** A linear value read out of a table's bytes, copied to row 0 here first; grown for larger layouts. */
+let scratch = viewsOf(new ArrayBuffer(256), 0, 256);
+
+/** A table's value of a component in a row: its column's one value, its value there, or one read out of its bytes. */
+const valueIn = (layout: Layout, column: Table.Column, row: number): unknown => {
+    if (column.kind === "value") return column.value;
+    if (column.kind === "values") return column.values[row];
+    if (layout.kind !== "linear") return undefined;
+    const { stride } = layout;
+    if (stride > scratch.u8.length) scratch = viewsOf(new ArrayBuffer(stride * 2), 0, stride * 2);
+    scratch.u8.set(column.bytes.subarray(row * stride, (row + 1) * stride));
+    return layout.read(scratch, 0);
+};
+
+/**
+ * Queues an add of each of its table's components onto the entity standing for a row `existing` maps, its entity
+ * values remapped, but a reference whose target isn't there.
+ */
+const updateRows = (state: State, { table, keys, ids }: Planned, rows: readonly number[], standing: Float64Array, buffer: CommandBuffer, remap: Remap): void => {
+    const columns: Table.Column[] = keys.map(key => Reflect.get(table.columns, key));
+    const schemas = keys.map(key => declarationOf(key)?.type);
+    const references = keys.map(key => declarationOf(key)?.reference !== undefined);
+    for (const row of rows) {
+        pushCommand(buffer, addCommand, standing[row]);
+        for (let k = 0; k < keys.length; k++) {
+            const id = ids[k];
+            const schema = schemas[k];
+            let value = valueIn(state.layouts[id], columns[k], row);
+            if (references[k]) {
+                const to = remap(Number(value));
+                if (to === 0 && value !== 0) continue;
+                value = to;
+            }
+            else if (schema !== undefined && holdsEntity(schema)) value = remapValue(schema, value, remap);
+            pushComponent(buffer, id, state.shared[id] === undefined ? value : storedShared(state, id, value));
+        }
+    }
+};
+
+/** 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(), updates: CommandBuffer | null = null): 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 +292,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 +382,18 @@ 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;
+        if (updates !== null && !wholly[t]) {
+            const mapped: number[] = [];
+            for (let row = 0; row < table.count; row++) if (existingAt[first + row] !== 0) mapped.push(row);
+            if (mapped.length > 0) updateRows(state, plan, mapped, entities[t], updates, remap);
+        }
+        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) => {