@driftengine/entities 3.61.0

package/dist/store.js

@@ -0,0 +1,453 @@
+import { entityIndex } from './entity.js';
+import { refreshView } from './view.js';
+/**
+ * The presence column's name for an optional field.
+ *
+ * A suffix rather than a parallel map, because `grow`, `remove` and the view all already walk
+ * `this.columns` — and a second map would be one more thing each of them has to remember. What it
+ * gives up is a field literally named `of$present`, which the language refuses at declaration and
+ * which `$` makes unwritable in a `.drs` file anyway. **What would make it wrong** is a component
+ * that is mostly optional, where a bitset over all of its optional fields beats a byte each — a
+ * change to how presence is stored, not to what an option is, so it moves nothing a save holds.
+ */
+export const presenceColumn = (field) => `${field}$present`;
+/**
+ * `option:f64` → `f64`, and `undefined` for a type that is not an option.
+ *
+ * A prefix rather than a structured type because a schema's field type is a *key* — one string
+ * compared for equality by a migration — and parsing it here is cheaper than carrying a second
+ * representation that could disagree with it.
+ */
+export function optionInner(type) {
+    return type.startsWith('option:') ? type.slice('option:'.length) : undefined;
+}
+/**
+ * Which typed array carries which field type.
+ *
+ * `i64` and `u64` are `Float64Array` rather than `BigInt64Array` because the language they come
+ * from represents them as JavaScript numbers — exact to 2^53 — and a `BigInt` column would be a
+ * different representation on this side of a boundary that is supposed to be one.
+ *
+ * **That was inferred here before DriftScript said it, and now it is the language's own rule.**
+ * 1.10.0 defines the domain of `i64` and `u64` as `±(2^53 - 1)` and `0 … 2^53 - 1`, refuses a
+ * literal outside it, and refuses wrapping arithmetic on either width because the true result is
+ * rounded before anything can reduce it. So this column is not a compromise the engine chose; it is
+ * the width the language guarantees, and the two agree by contract rather than by coincidence.
+ *
+ * `Entity` is here too, and `Float64Array` is what makes a handle survive: a handle spends the
+ * whole 53-bit budget, so anything narrower silently truncates the generation, which is the failure
+ * the handle's width exists to prevent.
+ */
+const COLUMNS = {
+    f32: Float32Array,
+    f64: Float64Array,
+    i8: Int8Array,
+    i16: Int16Array,
+    i32: Int32Array,
+    i64: Float64Array,
+    u8: Uint8Array,
+    u16: Uint16Array,
+    u32: Uint32Array,
+    u64: Float64Array,
+    bool: Uint8Array,
+    Entity: Float64Array,
+};
+/** Field types held in a plain array because they are not numbers. */
+const BOXED = new Set(['String']);
+/**
+ * Whether a field type is a fieldless enum, which the language writes as `enum:<Name>`.
+ *
+ * **A discriminant is an integer and always was**, so this is a column rather than a boxed value —
+ * which is the whole of why it can be added without deciding anything about layout.
+ *
+ * **The gap it closes is between a language feature and its usable shape.** DriftScript has `enum`,
+ * and `match` over one refuses to compile until every variant is handled; that exhaustiveness is
+ * the language's stated advantage over a Lua version which would silently do nothing for a state
+ * nobody wrote a branch for. But a state machine's state has to survive between ticks, which means
+ * a *component* field, and there was no column for one — so the language's own corpus keeps its
+ * `Alertness` in a `data` record, which is not what a system iterates, and a consumer shipped
+ * `mood: i32` with the three values written out in a comment. The feature and the place it is
+ * needed could not meet.
+ */
+function enumName(type) {
+    return type.startsWith('enum:') ? type.slice('enum:'.length) : undefined;
+}
+/**
+ * The column a discriminant goes in: `Int32Array`, and the width is the decision.
+ *
+ * **A byte would hold every enum anybody is likely to write and is not what this uses**, because
+ * the failure mode of guessing too small is silent. `defineComponent` is handed `enum:Mood` and a
+ * name is all it gets — the variant list belongs to the module that declared it, which this package
+ * does not read — so it cannot know whether 256 is enough. Four bytes a field costs three more than
+ * a byte for a small enum and cannot truncate a large one.
+ *
+ * **What would make it wrong** is a consumer measuring enum columns as a real share of their
+ * component memory, at which point the width belongs to whoever declares the enum and can count its
+ * variants, and this stops choosing.
+ */
+const ENUM_COLUMN = Int32Array;
+let nextComponentId = 0;
+/**
+ * Declare a component type, from a schema or from a name and a field table.
+ *
+ * **The schema overload is what a language-declared component uses**, and it exists because a field
+ * id is `(declaring module, declaring record, field name)`. A `.drs` file that declares `Health` is
+ * the declaring module; building the id here would file every language-declared component under
+ * `entities` and lose the half that makes a save survive a rename. The record overload goes on
+ * building `entities::<Name>::<field>`, because for a component declared in TypeScript this package
+ * genuinely *is* where the shape is declared.
+ *
+ * The ids are still never hand-written in the record overload, for the reason that has always been
+ * here: a hand-written id is a chance to write two the same, which `driftscript` refuses at
+ * `DS0284` for a record and which nothing would catch on this side.
+ *
+ * **What this costs** is two entry points to one concept. **What would make it wrong** is a third
+ * caller wanting a different id scheme, at which point the id belongs entirely to whoever declares
+ * the field and this function stops building one at all.
+ */
+export function defineComponent(first, fields) {
+    const schema = typeof first === 'string'
+        ? {
+            name: first,
+            fields: Object.entries(fields ?? {}).map(([field, type]) => ({
+                id: `entities::${first}::${field}`,
+                name: field,
+                type,
+            })),
+        }
+        : first;
+    for (const field of schema.fields) {
+        const inner = optionInner(field.type) ?? field.type;
+        if (COLUMNS[inner] === undefined && !BOXED.has(inner) && enumName(inner) === undefined) {
+            throw new Error(`\`${schema.name}.${field.name}\` is declared \`${field.type}\`, which has no column. The ` +
+                `types with one are ${[...Object.keys(COLUMNS), ...BOXED].join(', ')}, a fieldless ` +
+                '`enum:<Name>`, and an option of any of them. A type that has to be boxed is a decision ' +
+                'about layout, so it is added here rather than assumed.');
+        }
+    }
+    return {
+        name: schema.name,
+        id: nextComponentId++,
+        schema,
+        /* An optional handle is still a handle, so a scene load has to rewrite it through the id map
+           exactly as it rewrites a required one. Leaving it out would serialise a handle into a world
+           whose indices mean something else. */
+        entityFields: schema.fields
+            .filter((f) => f.type === 'Entity' || f.type === 'option:Entity')
+            .map((f) => f.name),
+    };
+}
+export function createStoreSnapshot() {
+    return { count: 0, dense: new Float64Array(0), columns: new Map() };
+}
+export class ComponentStore {
+    type;
+    /**
+     * The entities that have this component, in insertion order modified by swap-removal.
+     *
+     * **Deterministic given the same history, and not a stable property of the set** — two worlds
+     * holding the same entities in a different removal order iterate differently. That is what replay
+     * needs and is not what a consumer wanting a stable order gets; they sort by entity, and the fact
+     * that it is a choice is why this says so.
+     */
+    denseArray;
+    /** Entity index → position in `dense`, or -1. */
+    sparse;
+    columns = new Map();
+    count = 0;
+    /**
+     * The live view of these columns, made on first ask.
+     *
+     * Lazy rather than built in the constructor, because a store that nobody indexes directly should
+     * not carry an object per field name it will never hand out.
+     */
+    viewObject = null;
+    constructor(type, options = {}) {
+        this.type = type;
+        const capacity = Math.max(1, options.capacity ?? 16);
+        this.denseArray = new Float64Array(capacity);
+        this.sparse = new Int32Array(64).fill(-1);
+        for (const field of type.schema.fields) {
+            const inner = optionInner(field.type);
+            const declared = inner ?? field.type;
+            /* A discriminant is an integer, so it takes an integer column rather than being boxed. */
+            const Column = enumName(declared) === undefined ? COLUMNS[declared] : ENUM_COLUMN;
+            this.columns.set(field.name, Column === undefined
+                ? new Array(capacity)
+                : new Column(capacity));
+            /* An option keeps its inner type's column and gains a byte per entity saying whether the
+               value in it means anything. Without the second column, an optional `Entity` would have to
+               live in a boxed array so `null` could stand for absence — which is the whole bulk-data
+               rule given up for one bit. */
+            if (inner !== undefined)
+                this.columns.set(presenceColumn(field.name), new Uint8Array(capacity));
+        }
+    }
+    get size() {
+        return this.count;
+    }
+    /** The entities this store holds, oldest first. Valid up to `size`; the rest is capacity. */
+    get dense() {
+        return this.denseArray;
+    }
+    /**
+     * The live columns of this store, addressable by field name.
+     *
+     * The same object every call, refreshed after every reallocation — see `view.ts` for why that is
+     * the contract rather than a convenience.
+     */
+    view() {
+        if (this.viewObject === null)
+            this.viewObject = { sparse: this.sparse };
+        refreshView(this.viewObject, this.sparse, this.columns);
+        return this.viewObject;
+    }
+    /** Point the view at the arrays that exist now. Called after either kind of growth. */
+    refresh() {
+        if (this.viewObject === null)
+            return;
+        refreshView(this.viewObject, this.sparse, this.columns);
+    }
+    /** One field's storage, for a caller iterating it directly rather than through `read`. */
+    column(field) {
+        const found = this.columns.get(field);
+        if (found === undefined)
+            throw new Error(this.noField(field));
+        return found;
+    }
+    has(entity) {
+        const at = this.positionOf(entity);
+        return at >= 0;
+    }
+    add(entity, values = {}) {
+        if (this.has(entity)) {
+            for (const [field, value] of Object.entries(values))
+                this.write(entity, field, value);
+            return;
+        }
+        const at = this.count;
+        this.grow(at + 1);
+        this.growSparse(entityIndex(entity) + 1);
+        this.denseArray[at] = entity;
+        this.sparse[entityIndex(entity)] = at;
+        this.count += 1;
+        /*
+         * Every field written, including the ones the caller omitted.
+         *
+         * A column is reused storage — the slot may hold whatever the entity that was there last left
+         * — so an omitted field would silently inherit a stranger's value. Zeroing is what makes
+         * `add(e, { x: 5 })` mean what it reads like.
+         */
+        for (const field of this.type.schema.fields) {
+            const column = this.columns.get(field.name);
+            if (column === undefined)
+                continue;
+            const given = values[field.name];
+            if (Array.isArray(column))
+                column[at] = given ?? null;
+            else
+                column[at] = typeof given === 'number' ? given : Number(given ?? 0);
+            /*
+             * Presence is written here rather than left at whatever the slot held.
+             *
+             * This loop walks the *schema's* fields and the presence columns are not among them, so a
+             * reused slot would otherwise inherit the presence of whichever entity was there last —
+             * an optional field that reads as set, holding a number the caller never wrote.
+             */
+            const present = this.columns.get(presenceColumn(field.name));
+            if (present !== undefined)
+                present[at] = given === undefined ? 0 : 1;
+        }
+    }
+    /**
+     * Drop an entity's component. `false` when it never had one, which is not an error.
+     *
+     * The last entry is swapped into the hole and **its** sparse entry is fixed — the fix-up being
+     * the whole of what makes a constant-time removal correct.
+     *
+     * **The order of the two sparse writes is load-bearing**, and it is the only thing that is. When
+     * the entry being removed *is* the last, the swap is with itself and `moved` is `entity`: writing
+     * the position first and then the -1 leaves it absent, which is right; the other way round leaves
+     * it pointing into the space past `size`.
+     *
+     * There was a `position < size` guard in `positionOf` as well, which made the order not matter —
+     * and made a perturbation of the order pass every test. Two defences for one case is one defence
+     * and one comment that cannot be checked, so the guard is gone and the order is what the test
+     * for removing the last entry actually holds.
+     */
+    remove(entity) {
+        const at = this.positionOf(entity);
+        if (at < 0)
+            return false;
+        const last = this.count - 1;
+        const moved = this.denseArray[last];
+        this.denseArray[at] = moved;
+        for (const column of this.columns.values()) {
+            if (Array.isArray(column))
+                column[at] = column[last];
+            else
+                column[at] = column[last];
+        }
+        this.sparse[entityIndex(moved)] = at;
+        this.sparse[entityIndex(entity)] = -1;
+        this.count -= 1;
+        return true;
+    }
+    read(entity, field) {
+        const column = this.columns.get(field);
+        if (column === undefined)
+            throw new Error(this.noField(field));
+        const at = this.positionOf(entity);
+        if (at < 0)
+            return undefined;
+        const present = this.columns.get(presenceColumn(field));
+        if (present !== undefined && present[at] === 0)
+            return undefined;
+        return column[at];
+    }
+    write(entity, field, value) {
+        const column = this.columns.get(field);
+        if (column === undefined)
+            throw new Error(this.noField(field));
+        const at = this.positionOf(entity);
+        if (at < 0)
+            return;
+        /* `undefined` is how an optional field is cleared. On a non-optional field there is no presence
+           column and the value goes through the same coercion it always did. */
+        const present = this.columns.get(presenceColumn(field));
+        if (present !== undefined)
+            present[at] = value === undefined ? 0 : 1;
+        if (Array.isArray(column))
+            column[at] = value;
+        else
+            column[at] = typeof value === 'number' ? value : Number(value ?? 0);
+    }
+    /**
+     * Where an entity sits, or -1.
+     *
+     * **The dense array holds the whole handle**, so the generation is compared for free: a stale
+     * handle whose slot is live finds a different number and is refused. A sparse array alone could
+     * only compare indices, which is the silent-reuse failure one level down.
+     */
+    positionOf(entity) {
+        const index = entityIndex(entity);
+        if (index >= this.sparse.length)
+            return -1;
+        const at = this.sparse[index];
+        if (at < 0)
+            return -1;
+        return this.denseArray[at] === entity ? at : -1;
+    }
+    /**
+     * Copy this store's contents into a slot, growing the slot to match if it is short.
+     *
+     * **`count` bounds every copy, not capacity.** A store that once held ten thousand entities and
+     * now holds four has ten thousand slots of stale numbers behind the live four, and copying them
+     * would make a snapshot's cost depend on the world's history instead of its size.
+     *
+     * A boxed column copies references. That is correct rather than a shortcut: the one boxed field
+     * type is `String`, and a string cannot be mutated behind the snapshot's back.
+     */
+    saveInto(slot) {
+        const count = this.count;
+        if (slot.dense.length < count)
+            slot.dense = new Float64Array(this.denseArray.length);
+        for (let i = 0; i < count; i++)
+            slot.dense[i] = this.denseArray[i];
+        for (const [field, column] of this.columns) {
+            let into = slot.columns.get(field);
+            if (into === undefined || into.length < count) {
+                into = Array.isArray(column)
+                    ? new Array(column.length)
+                    : new column.constructor(column.length);
+                slot.columns.set(field, into);
+            }
+            if (Array.isArray(column)) {
+                const target = into;
+                for (let i = 0; i < count; i++)
+                    target[i] = column[i];
+            }
+            else {
+                const source = column;
+                const target = into;
+                for (let i = 0; i < count; i++)
+                    target[i] = source[i];
+            }
+        }
+        slot.count = count;
+    }
+    /**
+     * Put this store back to a saved slot, rebuilding `sparse` from the restored `dense`.
+     *
+     * **The order of the two sparse passes is load-bearing.** The entries this store's *current* live
+     * set occupies are cleared first, while `dense` still says which they are; overwriting `dense`
+     * first loses that record and leaves stale positions behind, and a stale position is worse than a
+     * missing one because `positionOf` would find a live slot holding a different handle.
+     */
+    loadFrom(slot) {
+        for (let at = 0; at < this.count; at++) {
+            this.sparse[entityIndex(this.denseArray[at])] = -1;
+        }
+        /* Before the columns are read out of the map: `grow` replaces every array in it. */
+        this.grow(Math.max(1, slot.count));
+        for (let i = 0; i < slot.count; i++)
+            this.denseArray[i] = slot.dense[i];
+        for (const [field, column] of this.columns) {
+            const from = slot.columns.get(field);
+            if (from === undefined)
+                continue;
+            if (Array.isArray(column)) {
+                const source = from;
+                for (let i = 0; i < slot.count; i++)
+                    column[i] = source[i];
+            }
+            else {
+                const source = from;
+                const target = column;
+                for (let i = 0; i < slot.count; i++)
+                    target[i] = source[i];
+            }
+        }
+        this.count = slot.count;
+        for (let at = 0; at < slot.count; at++) {
+            const index = entityIndex(this.denseArray[at]);
+            this.growSparse(index + 1);
+            this.sparse[index] = at;
+        }
+    }
+    noField(field) {
+        return (`\`${this.type.name}\` has no field \`${field}\`. It has ` +
+            `${this.type.schema.fields.map((f) => `\`${f.name}\``).join(', ')}.`);
+    }
+    grow(needed) {
+        if (needed <= this.denseArray.length)
+            return;
+        let size = this.denseArray.length;
+        while (size < needed)
+            size *= 2;
+        const dense = new Float64Array(size);
+        dense.set(this.denseArray);
+        this.denseArray = dense;
+        for (const [field, column] of this.columns) {
+            if (Array.isArray(column)) {
+                column.length = size;
+                continue;
+            }
+            const grown = new column.constructor(size);
+            grown.set(column);
+            this.columns.set(field, grown);
+        }
+        this.refresh();
+    }
+    growSparse(needed) {
+        if (needed <= this.sparse.length)
+            return;
+        let size = this.sparse.length;
+        while (size < needed)
+            size *= 2;
+        const sparse = new Int32Array(size).fill(-1);
+        sparse.set(this.sparse);
+        this.sparse = sparse;
+        this.refresh();
+    }
+}

package/dist/system.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A system, and the view that holds it to what it declared.
+ *
+ * **The declaration earns its place by being enforced, not by being documentation.** A system that
+ * writes a component it did not declare is refused naming both, because the whole value of the
+ * declaration is what can be derived from it — parallel grouping, ordering, profiling — and
+ * anything derived from a lie is worse than nothing derived at all.
+ *
+ * `writes` implies `reads`. A system that can write a component and not read it can only overwrite
+ * it, which nothing wants, and making every author write both would be a rule that is obeyed by
+ * copying.
+ *
+ * ---
+ *
+ * ## Structural change, and the one that is deferred
+ *
+ * `create` and `add` happen immediately. Neither can corrupt a walk in progress: a handle comes
+ * from the allocator and touches no store, and appending to a dense array only grows it. **A newly
+ * added entity may be visited in the same pass** if the query is walking the store it was added to,
+ * which is surprising and is stated rather than prevented — preventing it means snapshotting the
+ * size at the start of the walk, and a system that spawns and expects to see its own spawn is as
+ * likely as one that does not.
+ *
+ * **`destroy` and `remove` are deferred**, and that is not symmetry for its own sake. A removal
+ * swaps the last dense entry into the hole, so removing mid-walk moves an entity the cursor has
+ * already passed into a position it has already visited — and that entity is **never seen**,
+ * silently, and only whichever one happened to be last. Deferring is the smallest fix that is
+ * correct; the alternative is a tombstone per entry and a compaction pass, which costs every read.
+ */
+import type { Entity } from './entity.ts';
+import type { QueryCursor } from './query.ts';
+import type { ComponentType } from './store.ts';
+import type { ComponentView } from './view.ts';
+import type { World } from './world.ts';
+export interface SystemView {
+    query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor;
+    /**
+     * The live columns of a component, checked against this system's declarations first.
+     *
+     * `forWriting` decides which check: a caller that will only read takes a readable view, and one
+     * that will write takes a writable one. A compiler that can see the body supplies it; a caller
+     * writing this by hand says what it is about to do.
+     */
+    view(type: ComponentType, forWriting: boolean): ComponentView;
+    read(entity: Entity, type: ComponentType, field: string): unknown;
+    write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
+    has(entity: Entity, type: ComponentType): boolean;
+    create(): Entity;
+    add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
+    /** Deferred to after this system runs. See the header. */
+    destroy(entity: Entity): void;
+    /** Deferred to after this system runs. See the header. */
+    remove(entity: Entity, type: ComponentType): void;
+}
+export interface SystemDefinition {
+    readonly name: string;
+    readonly reads?: readonly ComponentType[];
+    readonly writes?: readonly ComponentType[];
+    /**
+     * Run once every this many fixed steps. Absent means every step.
+     *
+     * **A stride and never a rate in seconds.** A rate in wall-clock time leaves the determinism
+     * contract on its first dropped frame: two runs of the same recording would run the system a
+     * different number of times. A tick count is the same in every replay of the same input.
+     */
+    readonly everyTicks?: number;
+    /** Systems this one must run after, by name. A cycle here is refused at build. */
+    readonly after?: readonly string[];
+    run(view: SystemView): void;
+}
+/**
+ * The view one system sees, reused across ticks.
+ *
+ * One per system rather than one per run, because a system runs every tick for the life of a world
+ * and an object per tick per system is the allocation this package refuses everywhere else.
+ */
+export declare class BoundSystem implements SystemView {
+    readonly definition: SystemDefinition;
+    private readonly world;
+    private readonly readable;
+    private readonly writable;
+    /** Entities to destroy after this system returns. Reused, drained with a count. */
+    private readonly pendingDestroy;
+    private destroyCount;
+    private readonly pendingRemoveEntity;
+    private readonly pendingRemoveType;
+    private removeCount;
+    constructor(world: World, definition: SystemDefinition);
+    run(): void;
+    query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor;
+    /**
+     * The live columns of a component, checked first.
+     *
+     * **This is the seam where one mistake disables every declaration in this file.** Every other
+     * accessor here checks before it answers, and a view that went straight to the store would hand
+     * out the raw columns of a component this system never declared — after which `reads` and
+     * `writes` are reachable *around* rather than through, and nothing in the schedule derived from
+     * them means anything.
+     *
+     * **What this costs** is that a caller must say in advance whether it will write, before it has
+     * written anything. **What would make it wrong** is a view narrow enough to enforce per field,
+     * which would be a second object per field and the allocation this package refuses.
+     */
+    view(type: ComponentType, forWriting: boolean): ComponentView;
+    read(entity: Entity, type: ComponentType, field: string): unknown;
+    write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
+    has(entity: Entity, type: ComponentType): boolean;
+    create(): Entity;
+    add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
+    destroy(entity: Entity): void;
+    remove(entity: Entity, type: ComponentType): void;
+    /** Apply what was deferred. Drained by count, never by emptying — see `IMPROVEMENTS.md`. */
+    private drain;
+    private requireReadable;
+    private requireWritable;
+}

package/dist/system.js

@@ -0,0 +1,124 @@
+/**
+ * The view one system sees, reused across ticks.
+ *
+ * One per system rather than one per run, because a system runs every tick for the life of a world
+ * and an object per tick per system is the allocation this package refuses everywhere else.
+ */
+export class BoundSystem {
+    definition;
+    world;
+    readable = new Set();
+    writable = new Set();
+    /** Entities to destroy after this system returns. Reused, drained with a count. */
+    pendingDestroy = [];
+    destroyCount = 0;
+    pendingRemoveEntity = [];
+    pendingRemoveType = [];
+    removeCount = 0;
+    constructor(world, definition) {
+        this.world = world;
+        this.definition = definition;
+        for (const type of definition.writes ?? []) {
+            this.writable.add(type.id);
+            /* `writes` implies `reads` — see the header. */
+            this.readable.add(type.id);
+        }
+        for (const type of definition.reads ?? [])
+            this.readable.add(type.id);
+    }
+    run() {
+        this.definition.run(this);
+        this.drain();
+    }
+    query(a, b, c, d) {
+        this.requireReadable(a);
+        if (b !== undefined)
+            this.requireReadable(b);
+        if (c !== undefined)
+            this.requireReadable(c);
+        if (d !== undefined)
+            this.requireReadable(d);
+        return this.world.query(a, b, c, d);
+    }
+    /**
+     * The live columns of a component, checked first.
+     *
+     * **This is the seam where one mistake disables every declaration in this file.** Every other
+     * accessor here checks before it answers, and a view that went straight to the store would hand
+     * out the raw columns of a component this system never declared — after which `reads` and
+     * `writes` are reachable *around* rather than through, and nothing in the schedule derived from
+     * them means anything.
+     *
+     * **What this costs** is that a caller must say in advance whether it will write, before it has
+     * written anything. **What would make it wrong** is a view narrow enough to enforce per field,
+     * which would be a second object per field and the allocation this package refuses.
+     */
+    view(type, forWriting) {
+        if (forWriting)
+            this.requireWritable(type);
+        else
+            this.requireReadable(type);
+        return this.world.view(type);
+    }
+    read(entity, type, field) {
+        this.requireReadable(type);
+        return this.world.read(entity, type, field);
+    }
+    write(entity, type, field, value) {
+        this.requireWritable(type);
+        this.world.write(entity, type, field, value);
+    }
+    has(entity, type) {
+        this.requireReadable(type);
+        return this.world.has(entity, type);
+    }
+    create() {
+        return this.world.create();
+    }
+    add(entity, type, values = {}) {
+        this.requireWritable(type);
+        this.world.add(entity, type, values);
+    }
+    destroy(entity) {
+        if (this.destroyCount < this.pendingDestroy.length)
+            this.pendingDestroy[this.destroyCount] = entity;
+        else
+            this.pendingDestroy.push(entity);
+        this.destroyCount += 1;
+    }
+    remove(entity, type) {
+        this.requireWritable(type);
+        if (this.removeCount < this.pendingRemoveEntity.length) {
+            this.pendingRemoveEntity[this.removeCount] = entity;
+            this.pendingRemoveType[this.removeCount] = type;
+        }
+        else {
+            this.pendingRemoveEntity.push(entity);
+            this.pendingRemoveType.push(type);
+        }
+        this.removeCount += 1;
+    }
+    /** Apply what was deferred. Drained by count, never by emptying — see `IMPROVEMENTS.md`. */
+    drain() {
+        for (let i = 0; i < this.removeCount; i += 1) {
+            this.world.remove(this.pendingRemoveEntity[i], this.pendingRemoveType[i]);
+        }
+        this.removeCount = 0;
+        for (let i = 0; i < this.destroyCount; i += 1)
+            this.world.destroy(this.pendingDestroy[i]);
+        this.destroyCount = 0;
+    }
+    requireReadable(type) {
+        if (this.readable.has(type.id))
+            return;
+        throw new Error(`\`${this.definition.name}\` reads \`${type.name}\` and did not declare it. The schedule is ` +
+            'derived from what systems declare, so one that touches more than it says makes every ' +
+            'derivation wrong — add it to `reads`, or to `writes` if it also writes it.');
+    }
+    requireWritable(type) {
+        if (this.writable.has(type.id))
+            return;
+        throw new Error(`\`${this.definition.name}\` writes \`${type.name}\` and did not declare it. Add it to ` +
+            '`writes`; over-declaring is conservative and only costs schedule width.');
+    }
+}