@adobe/ecs 0.2.1 → 0.2.4

package/src/implementation/world/cascade.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Archetype } from './archetype.js';
 import { readCell } from './cells.js';
-import { indexOf, locate } from './entities.js';
+import { generationOf, indexOf, locate } from './entities.js';
 import { commandValue, isMissing } from './finalizers.js';
 import { createHolders, fitHolders, forEachHolder, linkHolder, unlinkHolder } from './holders.js';
 import { closureOf, owner } from './structure.js';
@@ -9,8 +9,8 @@ import { archetypeOf, withoutComponent, type State } from './state.js';
 import type { Queued } from './synchronize.js';
 
 /**
- * A reference value written in this sync point: by spawn or add commands, or a batch spawn. `holder`, `component`
- * and `target` triples, checked once the plan's despawns are known.
+ * A reference value written in this sync point to check: by spawn or add commands, or of a row spawned that `linkBorn`
+ * leaves to the cascade. `holder`, `component` and `target` triples, checked once the plan's despawns are known.
  */
 export type Written = number[];
 
@@ -41,6 +41,48 @@ const aliveAfter = (state: State, target: number): boolean => {
     return locate(entities, target) >= 0;
 };
 
+/**
+ * Links each reference the rows spawned in this sync point hold to its target, before the cascade, so a target it
+ * despawns finds them as it finds any holder. One naming an entity that won't be alive isn't linked, and goes to
+ * `written` to cascade, as does every reference of a row a command touched, which the command may point elsewhere.
+ * The rows spawned into an archetype are those from `first`, by archetype id; an entity is one f64.
+ */
+export const linkBorn = (state: State, born: ReadonlyMap<number, number>, written: Written, tick: number): void => {
+    const { plan, structure, archetypes, entities, referencesWritten } = state;
+    const { slots } = plan;
+    for (const [id, first] of born) {
+        const archetype = archetypes[id];
+        const { count } = archetype;
+        if (first >= count) continue;
+        const rows = archetype.entities;
+        for (const component of structure.referenceIds) {
+            const storage = archetype.storageById[component];
+            if (storage === undefined) continue;
+            referencesWritten[component] = tick;
+            const lists = structure.holders[component] ??= createHolders();
+            fitHolders(lists, entities.length);
+            const { unitStride, unitOffset } = storage;
+            const values = storage.views.f64;
+            // `aliveAfter`, through locals, since it runs for each row spawned.
+            const { archetype: archetypeOfIndex, generation, length } = entities;
+            const { entity: planned, despawned } = plan;
+            for (let row = first; row < count; row++) {
+                const target = values[row * unitStride + unitOffset];
+                if (target === 0) continue;
+                const holder = rows[row];
+                const index = indexOf(holder);
+                const commanded = index < slots.length && slots[index] >= 0;
+                const into = indexOf(target);
+                const entry = into < slots.length ? slots[into] : -1;
+                const alive = entry >= 0 && planned[entry] === target ? despawned[entry] === 0
+                    : into < length && archetypeOfIndex[into] >= 0 && generation[into] === generationOf(target);
+                if (alive) linkHolder(lists, target, holder);
+                if (commanded || !alive) written.push(holder, component, target);
+            }
+        }
+    }
+};
+
 /**
  * Despawns the holders that own a reference to an entity that is despawned or never lives, and removes `weak`
  * references to one, transitively, before rules close the plan. A holder acts only if its value once the plan applies
@@ -91,7 +133,7 @@ export const cascadeReferences = (state: State, queued: readonly Queued[], writt
  */
 export type IndexChanges = { readonly remove: number[]; readonly add: number[] };
 
-export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null, bornRows: readonly (readonly [Archetype, number])[]): IndexChanges => {
+export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null): IndexChanges => {
     const { plan, structure, entities } = state;
     const changes: IndexChanges = { remove: [], add: [] };
     for (let entry = 0; entry < plan.count; entry++) {
@@ -106,24 +148,6 @@ export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf:
             if (typeof after === "number" && after !== 0) changes.add.push(after, holder, component);
         }
     }
-    // Batch spawns no command touched still hold the references they were spawned with. An entity is one f64.
-    const { slots } = plan;
-    for (const [archetype, first] of bornRows) {
-        for (const component of structure.referenceIds) {
-            const storage = archetype.storageById[component];
-            if (storage === undefined) continue;
-            const { unitStride, unitOffset } = storage;
-            const values = storage.views.f64;
-            const rows = archetype.entities;
-            for (let row = first; row < archetype.count; row++) {
-                const holder = rows[row];
-                const index = indexOf(holder);
-                if (index < slots.length && slots[index] >= 0) continue;
-                const value = values[row * unitStride + unitOffset];
-                if (value !== 0) changes.add.push(value, holder, component);
-            }
-        }
-    }
     return changes;
 };
 

package/src/implementation/world/change-blocks.test.ts

@@ -89,7 +89,7 @@ const setGroup = System.create({ target: "entity", components: { with: [group] }
 // Readers.
 let found: number[] = [];
 const onMain = System.create({ components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
-const observed = System.create({ observer: true, components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
+const observed = System.create({ readonly: true, components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
 const ofTwo = System.create({ components: { with: [at], changed: [group, value] } }, row => { found.push(row[at]); });
 const inKernel = System.create({ kernel: true, components: { with: [seen], changed: [value] } }, row => { row[seen] += 1; });
 const inUp = System.create({ components: { with: [at], changed: [value] }, up: { through: parent } }, row => { found.push(row[at]); });

package/src/implementation/world/commands.ts

@@ -1,8 +1,15 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Commands } from '../../interface/system/commands.js';
-import { addCommand, despawnCommand, pushCommand, pushComponent, removeCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, createBuffer, despawnCommand, despawnWhereCommand, despawnWhereHolds, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import type { Archetype } from './archetype.js';
+import { reserve } from './entities.js';
 import { listShapeOf, presetSpawnerOf, spawnerOf, type ListShape } from './lists.js';
-import { commandIdOf, idOf, storedShared, type Key, type State } from './state.js';
+import { commandIdOf, idOf, queryIdOf, storedShared, type Key, type State } from './state.js';
+import { spawnTables } from './tables.js';
+import { holdsValuesOf } from './where.js';
+import { checkWhereValues } from '../../interface/system/check.js';
+import { declarationOf, isWorldWritten, kindOf, labelOf, threadOfDeclaration, whyUnregistered } from '../../interface/registry/index.js';
+import { matchesSchema } from '../../interface/registry/schemas.js';
 
 const collect = (state: State, buffer: CommandBuffer, key: Key, value: unknown): void => {
     if (value !== undefined) pushComponent(buffer, idOf(state, key), value);
@@ -44,9 +51,67 @@ const addShared = (state: State, buffer: CommandBuffer, entity: number, shape: L
     for (let k = 0; k < keys.length; k++) pushComponent(buffer, ids[k], values[k]);
 };
 
+/**
+ * Throws for a key of `resources` that isn't a resource, is one only the world writes or one living on another thread,
+ * or is given a value its schema doesn't take.
+ */
+const checkResources = (resources: object): void => {
+    for (const key of Object.getOwnPropertySymbols(resources)) {
+        const fail = (message: string): never => { throw new Error(`commands.spawnTables: "${labelOf(key)}" ${message}.`); };
+        if (kindOf(key) !== "resource") fail(`isn't a registered resource: ${whyUnregistered(key)}`);
+        if (isWorldWritten(key)) fail("is written only by the world");
+        const declaration = declarationOf(key);
+        if (declaration === undefined) continue;
+        const thread = threadOfDeclaration(declaration);
+        if (thread !== null && thread !== "world") fail(`lives on thread "${thread}", not the world's`);
+        if (declaration.type !== undefined && !matchesSchema(declaration.type, Reflect.get(resources, key))) fail("is given a value its type doesn't take");
+    }
+};
+
+/**
+ * Queues `resources`' values for the sync point as the world's own change to its resource entity, which it reserves
+ * when the world has none yet: a buffer of their own, since the sync point skips systems' commands to that entity.
+ */
+const queueResources = (state: State, resources: object): void => {
+    if (Object.getOwnPropertySymbols(resources).length === 0) return;
+    const buffer = createBuffer();
+    if (state.resourceEntity < 0) {
+        state.resourceEntity = reserve(state.entities);
+        pushValues(state, buffer, spawnCommand, state.resourceEntity, resources);
+    }
+    else pushValues(state, buffer, addCommand, state.resourceEntity, resources);
+    state.queued.push({ buffer, guarded: false });
+};
+
 /** Values of a list add given none, which only an untyped caller does. */
 const empty = {};
 
+const noKeys: readonly unknown[] = [];
+
+/**
+ * Queues a `despawnWhere`, its ids resolved and its `where` checked first, so a key that isn't a component, or a `where`
+ * that isn't of shared values, queues nothing.
+ */
+const pushDespawnWhere = (state: State, buffer: CommandBuffer, query: Parameters<Commands["despawnWhere"]>[0]): void => {
+    const including: readonly unknown[] = query.with;
+    const excluding: readonly unknown[] = query.not ?? noKeys;
+    const { where } = query;
+    if (including.length === 0) throw new Error("commands.despawnWhere's `with` names at least one component.");
+    for (let k = 0; k < including.length; k++) queryIdOf(state, including[k]);
+    for (let k = 0; k < excluding.length; k++) queryIdOf(state, excluding[k]);
+    let holds: ((archetype: Archetype) => boolean) | null = null;
+    if (where !== undefined && Object.getOwnPropertySymbols(where).length > 0) {
+        checkWhereValues("commands.despawnWhere", "where", "a despawn", where, false);
+        const found = holdsValuesOf(state, where, false);
+        if (typeof found === "symbol") throw new Error(`commands.despawnWhere: where names "${labelOf(found)}", which isn't a shared component.`);
+        holds = found;
+    }
+    pushCommand(buffer, despawnWhereCommand, including.length);
+    for (let k = 0; k < including.length; k++) pushComponent(buffer, queryIdOf(state, including[k]), undefined);
+    for (let k = 0; k < excluding.length; k++) pushComponent(buffer, queryIdOf(state, excluding[k]), undefined);
+    if (holds !== null) pushComponent(buffer, despawnWhereHolds, holds);
+};
+
 /**
  * Commands that queue for the next sync point. A key that isn't a component commands may name throws here, inside the
  * issuing system, before anything is queued. Values are immutable by convention, so they aren't copied.
@@ -61,6 +126,7 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
     despawn: entity => {
         pushCommand(target.buffer, despawnCommand, entity);
     },
+    despawnWhere: query => pushDespawnWhere(state, target.buffer, query),
     add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
         const { buffer } = target;
         if (typeof components === "symbol") {
@@ -83,6 +149,14 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
             pushComponent(buffer, ids[k], value === undefined ? starts[k] : value);
         }
     },
+    spawnTables: (tables, options) => {
+        const resources = options?.resources;
+        if (resources === undefined) return spawnTables(state, tables, options?.existing);
+        checkResources(resources);
+        const spawned = spawnTables(state, tables, options?.existing);
+        queueResources(state, resources);
+        return spawned;
+    },
     remove: (entity: number, components: symbol | readonly symbol[]) => {
         const { buffer } = target;
         if (typeof components === "symbol") {

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

@@ -71,28 +71,28 @@ const positions = async (world: World): Promise<Vec2[]> =>
     (await readEach(world, await select(world, { required: [position], order: { [position]: true } }), position)).map(value => value ?? [NaN, NaN]);
 
 describe("World.create", () => {
-    it("spawns once from a changed resource, then integrates", async () => {
+    it("spawns once from a changed resource, then integrates, from the run that spawns", async () => {
         const world = createWorld();
         await world.run(main);
-        expect(await positions(world)).toEqual([[0, 0], [1, 0], [2, 0]]);
-        await world.run(main);
         expect(await positions(world)).toEqual([[0, 1], [1, 1], [2, 1]]);
+        await world.run(main);
+        expect(await positions(world)).toEqual([[0, 2], [1, 2], [2, 2]]);
         expect(await readResource(world, spawnCount)).toBe(3);
     });
 
     it("reports each change to a system exactly once", async () => {
         const world = createWorld();
         await world.run(main);
-        // Spawned at the sync point, after watch ran: seen on the next run.
-        expect(await readResource(world, seen)).toBe(0);
-        await world.run(main);
+        // Spawned at the sync point before move, which watch follows: seen in the same run.
         expect(await readResource(world, seen)).toBe(3);
+        await world.run(main);
+        expect(await readResource(world, seen)).toBe(6);
         // Moved before watch in the last run, so already reported.
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(3);
+        expect(await readResource(world, seen)).toBe(6);
         await world.run(move);
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(6);
+        expect(await readResource(world, seen)).toBe(9);
     });
 
     it("applies the net structural change of a sync point", async () => {

package/src/implementation/world/create.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Finalizer } from '../../interface/finalizer/created.js';
 import type { Rule } from '../../interface/rule/created.js';
-import { requireDefinition, type Definition } from '../../interface/registry/index.js';
+import { definitionOf, requireDefinition, type Definition } from '../../interface/registry/index.js';
 import type { World } from '../../interface/world/world.js';
 import type { Input } from '../../interface/system/input.js';
 import type { System } from '../../interface/system/system.js';
@@ -43,6 +43,10 @@ import { stampChanged } from './archetype.js';
 import { createLoop, platformFrame, platformTimer, type Clock, type LoopPlatform } from './loop.js';
 import { presetLevelsOf } from './lists.js';
 import { createState, defaultOf, idOf, reside, startTicking, type Key } from './state.js';
+import { asksForChanges, changesOf, resourcesWrittenBy, startRecording, takesInput } from './run-changes.js';
+import type { ChangeSet } from '../../interface/finalizer/body.js';
+import type { Essential } from '../../interface/component/value.js';
+import type { Resource } from '../../interface/resource/resource.js';
 import { indexOf } from './entities.js';
 import { touchedHeld } from './up.js';
 import { isHeld } from './transfers.js';
@@ -53,6 +57,9 @@ type Queue = <T>(task: () => T | Promise<T>) => Promise<T>;
 
 /** A task's failure as the queue's own chain carries it, which never rejects: made only when a task fails. */
 type Carried = { readonly thrown: unknown };
+/** A schedule of nothing, whose run is its sync point alone. */
+const noTiers: Schedule = { tiers: [], reductions: new Map(), observer: [], syncs: [] };
+
 const thrownValues = new WeakSet<object>();
 const thrownOf = (error: unknown): Carried => {
     const wrapped = { thrown: error };
@@ -956,9 +963,57 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
         },
     });
 
+    /**
+     * Runs a system or composite, recording its own changes, which it resolves to: what earlier finalizers queued
+     * applies first, at a sync point of its own, and the recording covers the run's sync points alone.
+     */
+    const runChanging = (definition: Definition, value: unknown): Promise<unknown> => {
+        const started = enqueue(() => startChanges(definition));
+        const ran = runWith(definition, value);
+        const taken = enqueue(takeChanges);
+        return Promise.all([started, ran, taken]).then(([, , changes]) => changes);
+    };
+    const startChanges = (definition: Definition): unknown => {
+        checkLive();
+        const flushed = execution(definition, undefined, noTiers);
+        if (flushed instanceof Promise) return flushed.then(report => startRecordingOf(definition, report));
+        startRecordingOf(definition, flushed);
+        return undefined;
+    };
+    const startRecordingOf = (definition: Definition, flushed: RunReport): void => {
+        outOfBand.reportAll(flushed.failures);
+        state.recording = startRecording(state, resourcesWrittenBy(definition));
+    };
+    const takeChanges = (): unknown => {
+        const { recording } = state;
+        state.recording = null;
+        if (recording === null) throw new Error("The run's changes weren't recorded.");
+        return changesOf(state, recording);
+    };
+
+    function run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
+    function run<I, R>(system: System<I, R>, ...input: [...Input<NoInfer<I>>, options: { readonly changes: true }]): Promise<ChangeSet<Essential, Resource.Key>>;
+    function run(system: System<unknown, unknown>, ...args: readonly unknown[]): Promise<unknown> {
+        // Options come last, so a run not asking for changes reads one value more.
+        const { length } = args;
+        if (length === 0 || !asksForChanges(args[length - 1])) return runWith(system, args[0]);
+        const definition = definitionOf(system);
+        let input = false;
+        try {
+            input = definition !== undefined && takesInput(definition);
+        }
+        catch {
+            // A composite whose schedule can't be made fails its run, as `runWith` finds.
+            return runWith(system, args[0]);
+        }
+        // A system taking input whose input is all it was given runs with it.
+        if (definition === undefined || (input && args.length < 2)) return runWith(system, args[0]);
+        return runChanging(definition, input ? args[0] : undefined);
+    }
+
     const world: CreatedWorld = {
         // A run gives what its system's body returned, `R` by the system's type.
-        run: <I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>) => runWith(system, input[0]) as Promise<R>,
+        run,
         share: port => {
             if (disposed) return Promise.reject(new Error("The world is disposed."));
             if (!state.memory.shared) return Promise.reject(new Error("Without cross-origin isolation memory can't be shared, so no thread can join."));

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

@@ -56,7 +56,7 @@ describe("a derived component declared without a default", () => {
             commands.spawn([tagged])({});
         });
         const seen: unknown[] = [];
-        const read = System.create({ observer: true, components: { with: [index] } }, row => { seen.push(row[index]); });
+        const read = System.create({ readonly: true, components: { with: [index] } }, row => { seen.push(row[index]); });
         await using first = createWorld();
         await using second = createWorld();
         for (const world of [first, second]) {

package/src/implementation/world/despawn-where.test.ts

@@ -0,0 +1,287 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { Rule } from "../../interface/rule/rule.js";
+import type { Commands } from "../../interface/system/commands.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "./create.js";
+import { runReported } from "./outcomes.test-helper.js";
+import { count, read, readResource } from "./reads.test-helper.js";
+
+const mark = Symbol("despawnWhereTest/mark");
+const kept = Symbol("despawnWhereTest/kept");
+const value = Symbol("despawnWhereTest/value");
+const extra = Symbol("despawnWhereTest/extra");
+const host = Symbol("despawnWhereTest/host");
+const derivedFrom = Symbol("despawnWhereTest/derivedFrom");
+const slot = Symbol("despawnWhereTest/slot");
+const parent = Symbol("despawnWhereTest/parent");
+const finalized = Symbol("despawnWhereTest/finalized");
+const watched = Symbol("despawnWhereTest/watched");
+const trigger = Symbol("despawnWhereTest/trigger");
+const level = Symbol("despawnWhereTest/level");
+const journal = Symbol("despawnWhereTest/journal");
+const chunk = Symbol("despawnWhereTest/chunk");
+// Never declared, so never registered.
+const unregistered = Symbol("despawnWhereTest/unregistered");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [mark]: { type: true };
+        [kept]: { type: true };
+        [value]: { type: number };
+        [extra]: { type: true };
+        [host]: { type: true };
+        [derivedFrom]: { type: true };
+        [slot]: { type: number; derived: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [finalized]: { type: number };
+        [watched]: { type: number };
+        [trigger]: { type: true };
+        [chunk]: { type: number; shared: true };
+    }
+    export interface Resources {
+        [level]: { type: number };
+        [journal]: { type: readonly string[]; default: [] };
+    }
+}
+
+Rule.create({ components: { with: [host, derivedFrom] }, derive: [slot] });
+
+const seen: number[] = [];
+Finalizer.create({ components: { with: [finalized] } }, row => { seen.push(row[finalized]); });
+
+Finalizer.changes({ watch: [watched, mark] }, (changes, { resources }) => {
+    const lines = changes.groups.map(group => `${group.entities.map(entity => changes.previous(entity, watched)).join(",")}: +${group.added.length} -${group.removed.length}`);
+    resources[journal] = [...resources[journal], ...lines];
+});
+
+/** A world, and a function running `body` once in a system with the world's commands, rejecting with what it threw. */
+const withCommands = () => {
+    const world = createWorld({ [workers]: 0 });
+    let body: (commands: Commands) => void = () => {};
+    const issue = System.create({}, ({ commands }) => body(commands));
+    const run = async (next: (commands: Commands) => void): Promise<void> => {
+        body = next;
+        const [failure] = (await runReported(world, issue)).failures;
+        if (failure !== undefined) throw new Error(failure.message);
+    };
+    return { world, run };
+};
+
+const alive = async (world: World, entity: Entity): Promise<boolean> =>
+    (await Observe.toPromise(Observe.entity(world, entity, { optional: [mark] }))) !== null;
+
+const aliveEach = (world: World, entities: readonly Entity[]): Promise<boolean[]> => Promise.all(entities.map(entity => alive(world, entity)));
+
+describe("despawnWhere", () => {
+    it("despawns every entity with each `with` component and no `not` one, across archetypes", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            for (let i = 0; i < 3; i++) {
+                spawned.push(commands.spawn([mark])());
+                spawned.push(commands.spawn([mark, value])({ [value]: i }));
+                spawned.push(commands.spawn([mark, value, extra])({ [value]: i }));
+                spawned.push(commands.spawn([value])({ [value]: i }));
+                spawned.push(commands.spawn([mark, kept])());
+            }
+        });
+        await run(commands => commands.despawnWhere({ with: [mark], not: [kept] }));
+        expect(await aliveEach(world, spawned)).toEqual([0, 1, 2].flatMap(() => [false, false, false, true, true]));
+        await run(commands => commands.despawnWhere({ with: [value, mark] }));
+        expect(await count(world, { required: [value] })).toBe(3);
+        await world.dispose();
+    });
+
+    it("selects by the commands issued before it at the sync point; later ones to a despawned entity do nothing", async () => {
+        const { world, run } = withCommands();
+        let gains = Entity.none, loses = Entity.none, gainsAfter = Entity.none, changedAfter = Entity.none;
+        await run(commands => {
+            gains = commands.spawn([value])({ [value]: 1 });
+            loses = commands.spawn([mark, value])({ [value]: 2 });
+            gainsAfter = commands.spawn([value])({ [value]: 3 });
+            changedAfter = commands.spawn([mark, value])({ [value]: 4 });
+        });
+        await run(commands => {
+            commands.add(gains, mark);
+            commands.remove(loses, mark);
+            commands.despawnWhere({ with: [mark] });
+            commands.add(gainsAfter, mark);
+            commands.add(changedAfter, extra);
+        });
+        expect(await aliveEach(world, [gains, loses, gainsAfter, changedAfter])).toEqual([false, true, true, false]);
+        expect(await read(world, gainsAfter, mark)).toBe(true);
+        await world.dispose();
+    });
+
+    it("despawns matching entities spawned at the same sync point, whenever spawned, since spawns commit first", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, value])({ [value]: 1 }));
+            commands.despawnWhere({ with: [mark] });
+            spawned.push(commands.spawn([mark, value])({ [value]: 2 }));
+            spawned.push(commands.spawn([value])({ [value]: 3 }));
+        });
+        expect(await aliveEach(world, spawned)).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("matches derived components, by where earlier commands leave an entity once derived", async () => {
+        const { world, run } = withCommands();
+        let derived = Entity.none, deriving = Entity.none, underived = Entity.none;
+        await run(commands => {
+            derived = commands.spawn([host, derivedFrom])();
+            deriving = commands.spawn([host])();
+            underived = commands.spawn([host, derivedFrom])();
+        });
+        expect(await read(world, derived, slot)).not.toBeNull();
+        await run(commands => {
+            commands.add(deriving, derivedFrom);
+            commands.remove(underived, derivedFrom);
+            commands.despawnWhere({ with: [slot] });
+        });
+        expect(await aliveEach(world, [derived, deriving, underived])).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("runs finalizers for each entity it despawns, reading its values", async () => {
+        const { world, run } = withCommands();
+        seen.length = 0;
+        await run(commands => {
+            for (let i = 0; i < 4; i++) commands.spawn(i % 2 === 0 ? [finalized, mark] : [finalized])({ [finalized]: i });
+        });
+        await run(commands => commands.despawnWhere({ with: [mark, finalized] }));
+        expect(seen.sort()).toEqual([0, 2]);
+        await world.dispose();
+        seen.length = 0;
+    });
+
+    it("gives a changes finalizer the same changes as a despawn of each", async () => {
+        const journals: (readonly string[])[] = [];
+        for (const despawn of [
+            (commands: Commands, entities: readonly Entity[]) => { for (const entity of entities) commands.despawn(entity); },
+            (commands: Commands) => commands.despawnWhere({ with: [mark] }),
+        ]) {
+            const { world, run } = withCommands();
+            const entities: Entity[] = [];
+            await run(commands => {
+                for (let i = 0; i < 3; i++) entities.push(commands.spawn([watched, mark])({ [watched]: i }));
+                entities.push(commands.spawn([watched, mark, extra])({ [watched]: 9 }));
+                commands.spawn([watched])({ [watched]: 5 });
+            });
+            await run(commands => despawn(commands, entities));
+            journals.push(await readResource(world, journal));
+            await world.dispose();
+        }
+        expect(journals[1]).toEqual(journals[0]);
+        expect(journals[1]).toContain("0,1,2: +0 -2");
+    });
+
+    it("cascades owner references as a despawn does", async () => {
+        const { world, run } = withCommands();
+        let root = Entity.none, child = Entity.none, other = Entity.none;
+        await run(commands => {
+            root = commands.spawn([mark])();
+            child = commands.spawn([parent, value])({ [parent]: root, [value]: 1 });
+            other = commands.spawn([value])({ [value]: 2 });
+        });
+        await run(commands => commands.despawnWhere({ with: [mark] }));
+        expect(await aliveEach(world, [root, child, other])).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("never despawns the resource entity", async () => {
+        const { world, run } = withCommands();
+        const set = System.create({}, ({ resources, commands }) => {
+            resources[level] = 3;
+            commands.spawn([mark])();
+            commands.despawnWhere({ with: [mark] });
+        });
+        await world.run(set);
+        await run(commands => commands.despawnWhere({ with: [mark] }));
+        expect(await readResource(world, level)).toBe(3);
+        expect(await count(world, { required: [mark] })).toBe(0);
+        await world.dispose();
+    });
+
+    it("throws in the issuing system, queuing nothing, for an empty `with` or a key that isn't a component", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([mark])(); });
+        // @ts-expect-error `with` names at least one component
+        await expect(run(commands => commands.despawnWhere({ with: [] }))).rejects.toThrow("names at least one component");
+        // @ts-expect-error never registered
+        await expect(run(commands => commands.despawnWhere({ with: [mark], not: [unregistered] }))).rejects.toThrow("no registered schema");
+        // @ts-expect-error a resource
+        await expect(run(commands => commands.despawnWhere({ with: [level] }))).rejects.toThrow("is a resource");
+        expect(await alive(world, entity)).toBe(true);
+        await world.dispose();
+    });
+
+    it("runs in a system over rows, which isn't a kernel", async () => {
+        const { world, run } = withCommands();
+        const clear = System.create({ components: { with: [trigger] } }, (_row, { commands }) => {
+            commands.despawnWhere({ with: [mark] });
+        });
+        await run(commands => {
+            for (let i = 0; i < 5; i++) commands.spawn([mark, value])({ [value]: i });
+            commands.spawn([trigger])();
+            commands.spawn([trigger])();
+        });
+        const { failures } = await runReported(world, clear);
+        expect(failures).toEqual([]);
+        expect(await count(world, { required: [mark] })).toBe(0);
+        expect(await count(world, { required: [trigger] })).toBe(2);
+        await world.dispose();
+    });
+
+    it("keeps to the archetypes holding where's shared values, each required as with requires it", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
+            spawned.push(commands.spawn([mark, value, chunk], { [chunk]: 1 })({ [value]: 1 }));
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 2 })());
+            spawned.push(commands.spawn([mark])());
+            spawned.push(commands.spawn([value, chunk], { [chunk]: 1 })({ [value]: 2 }));
+        });
+        await run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } }));
+        expect(await aliveEach(world, spawned)).toEqual([false, false, true, true, true]);
+        await world.dispose();
+    });
+
+    it("despawns by where the entities spawned at the same sync point, and none for a value no archetype holds", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
+            commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } });
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 2 })());
+            commands.despawnWhere({ with: [mark], where: { [chunk]: 3 } });
+        });
+        expect(await aliveEach(world, spawned)).toEqual([false, true]);
+        await run(commands => commands.despawnWhere({ with: [mark], where: {} }));
+        expect(await aliveEach(world, spawned)).toEqual([false, false]);
+        await world.dispose();
+    });
+
+    it("throws for a where that isn't values of shared components, queuing nothing", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([mark, chunk], { [chunk]: 1 })(); });
+        // @ts-expect-error where names only shared components
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [value]: 1 } }))).rejects.toThrow(/where names "despawnWhereTest\/value", which isn't a shared component/);
+        // @ts-expect-error where takes values, not predicates
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: (given: number) => given === 1 } }))).rejects.toThrow(/gives "despawnWhereTest\/chunk" a predicate/);
+        // @ts-expect-error a value of the component's type
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: "1" } }))).rejects.toThrow(/isn't one of its type's values/);
+        expect(await alive(world, entity)).toBe(true);
+        await world.dispose();
+    });
+});

package/src/implementation/world/entities.ts

@@ -70,6 +70,12 @@ export const createEntities = (memory: Memory): Entities => {
 /** Reserves an entity. Safe to call from any thread between sync points. */
 export const reserve = ({ cursor, free, generation }: Reservations): Entity => entityAt(cursor, free, generation, Atomics.add(cursor, taken, 1));
 
+/** Reserves an entity for each of `into`'s elements, with one atomic add. Safe to call from any thread between sync points. */
+export const reserveRun = ({ cursor, free, generation }: Reservations, into: Float64Array): void => {
+    const first = Atomics.add(cursor, taken, into.length);
+    for (let i = 0; i < into.length; i++) into[i] = entityAt(cursor, free, generation, first + i);
+};
+
 /**
  * Reservations a thread takes in blocks of positions, so threads spawning together don't contend for the cursor.
  * Positions a block leaves unused are reserved entities that never spawn, which the sync point releases.