@driftengine/entities 3.61.0

package/dist/schedule.js

@@ -0,0 +1,161 @@
+import { BoundSystem } from './system.js';
+/**
+ * Order the systems, refusing what cannot be ordered.
+ *
+ * Deterministic: the same definitions in the same order produce the same schedule on every machine
+ * and every run, which is what a replay of a recorded session depends on.
+ */
+export function buildSchedule(systems) {
+    const byName = new Map();
+    systems.forEach((system, index) => {
+        if (byName.has(system.name)) {
+            throw new Error(`\`${system.name}\` is declared more than once. \`after\` addresses a system by name, so ` +
+                'two of a name is an ordering constraint nobody can write.');
+        }
+        byName.set(system.name, index);
+    });
+    for (const system of systems) {
+        for (const name of system.after ?? []) {
+            if (!byName.has(name)) {
+                throw new Error(`\`${system.name}\` says it runs after \`${name}\`, which no system declares. A ` +
+                    'constraint naming nothing is a constraint that silently does nothing.');
+            }
+        }
+    }
+    /*
+     * Kahn's algorithm over the `after` edges, taking the **lowest-numbered** ready system each time.
+     * That is the tie-break: among systems whose constraints are all satisfied, declaration order
+     * decides, so the result is a total order rather than whichever the set happened to yield.
+     */
+    const order = [];
+    const done = new Set();
+    for (let placed = 0; placed < systems.length; placed += 1) {
+        let chosen = -1;
+        for (let i = 0; i < systems.length; i += 1) {
+            const system = systems[i];
+            if (done.has(system.name))
+                continue;
+            const waiting = (system.after ?? []).some((name) => !done.has(name));
+            if (waiting)
+                continue;
+            chosen = i;
+            break;
+        }
+        if (chosen < 0) {
+            const stuck = systems.filter((system) => !done.has(system.name)).map((s) => s.name);
+            throw new Error(`these systems each say they run after another of them, so none can go first: ` +
+                `${stuck.join(', ')}. One of the \`after\` clauses has to give.`);
+        }
+        const system = systems[chosen];
+        done.add(system.name);
+        order.push(system);
+    }
+    return { order, groups: group(order) };
+}
+/** Which of a component type's ids a system touches at all. */
+function touched(system) {
+    const ids = new Set();
+    for (const type of system.reads ?? [])
+        ids.add(type.id);
+    for (const type of system.writes ?? [])
+        ids.add(type.id);
+    return ids;
+}
+/** Whether two systems must not run at the same time: one writes what the other touches. */
+function conflicts(a, b) {
+    const bTouched = touched(b);
+    for (const type of a.writes ?? [])
+        if (bTouched.has(type.id))
+            return true;
+    const aTouched = touched(a);
+    for (const type of b.writes ?? [])
+        if (aTouched.has(type.id))
+            return true;
+    return false;
+}
+function group(order) {
+    const groups = [];
+    let current = [];
+    for (const system of order) {
+        if (current.length > 0 && current.some((other) => conflicts(other, system))) {
+            groups.push(current);
+            current = [];
+        }
+        current.push(system);
+    }
+    if (current.length > 0)
+        groups.push(current);
+    return groups;
+}
+/** Systems bound to a world, made once and reused for the life of it. */
+const bound = new WeakMap();
+/**
+ * Systems whose failure has already been reported, per world.
+ *
+ * A declaration error repeats every step by construction, so the message is said once. Keyed by
+ * definition rather than counted, because what a reader needs is the name of each broken system
+ * and not how many times it has failed.
+ */
+const reported = new WeakMap();
+/**
+ * Run one fixed step of a schedule.
+ *
+ * `tick` is the simulation's step count and is what `everyTicks` strides over — so a system at
+ * stride 60 runs on tick 0, 60, 120, in every replay of the same input.
+ *
+ * **A system that throws does not take the rest of the tick with it, since 2026-08-28.** It used
+ * to: the throw left this function, so every system scheduled after the failing one never ran —
+ * once per tick, for as long as the game was up. Reported from outside, and the way it was found is
+ * the argument for containing it. A system queried a component it had not declared, which throws by
+ * design; the system that stopped was three places later and was the one stepping a vehicle; the
+ * symptom was *a car moving in jerks*, and the only evidence was a console line no headless check
+ * reads. A broken system must not be able to silently starve its neighbours.
+ *
+ * So each system's failure is caught, reported **once** naming the system and the reason, and the
+ * schedule carries on. Nothing is disabled: a declaration error will throw again next tick and be
+ * caught again, which costs a throw per tick and keeps a transient failure recoverable — and this
+ * function no longer throws, which is what `AGENTS.md` requires of anything the frame loop calls.
+ *
+ * **What it gives up** is the stack reaching a debugger's uncaught-exception break, which is how
+ * somebody working on a system would rather meet it. **What would change it** is a consumer wanting
+ * failures fatal in development; the answer then is a reporter this takes as a parameter rather than
+ * a rule chosen here for everybody.
+ */
+export function runSchedule(world, schedule, tick) {
+    let forWorld = bound.get(world);
+    if (forWorld === undefined) {
+        forWorld = new Map();
+        bound.set(world, forWorld);
+    }
+    for (const definition of schedule.order) {
+        const stride = definition.everyTicks ?? 1;
+        if (stride > 1 && tick % stride !== 0)
+            continue;
+        let system = forWorld.get(definition);
+        if (system === undefined) {
+            system = new BoundSystem(world, definition);
+            forWorld.set(definition, system);
+        }
+        try {
+            system.run();
+        }
+        catch (error) {
+            announce(world, definition, error);
+        }
+    }
+}
+/** Say what failed, once per system per world. */
+function announce(world, definition, error) {
+    let seen = reported.get(world);
+    if (seen === undefined) {
+        seen = new Set();
+        reported.set(world, seen);
+    }
+    if (seen.has(definition))
+        return;
+    seen.add(definition);
+    const reason = error instanceof Error ? error.message : String(error);
+    console.error(`[driftengine] the system \`${definition.name}\` threw and was skipped; every other system ` +
+        `in the schedule still ran. This is said once, and it will keep happening every tick until ` +
+        `it is fixed: ${reason}`);
+}

package/dist/store.d.ts

@@ -0,0 +1,183 @@
+/**
+ * A component type, and the sparse set that holds one.
+ *
+ * **Sparse sets rather than archetypes, and the reason is churn.** An archetype table iterates a
+ * multi-component query faster because the components are already adjacent — but adding or removing
+ * one component moves the entity between tables, which copies every component it has. A game that
+ * adds and removes a marker component per frame pays that copy per frame, and a marker is exactly
+ * the pattern queries are built for. Here, add and remove are constant time and move nothing else.
+ *
+ * The cost is that a multi-component query walks one dense array and tests membership in the others,
+ * so the data is not adjacent. **That is to be measured rather than assumed**, and the measurement
+ * is a deliverable of this track — in a language where every object field is already an indirection
+ * the gap is not the one a systems language would see.
+ *
+ * ---
+ *
+ * ## The schema is DriftScript's, and there is no second description
+ *
+ * A component's fields, their types and their **stable ids** are a `Schema` — the same structure
+ * Track N's Phase 5 built for state migration. Storage layout reads it, serialization reads its
+ * ids, loading a scene across a field change goes through `migrate` unchanged, and an inspector
+ * will read it when Track K exists. Four readers, one description, nothing to keep in sync.
+ *
+ * A field id is `(declaring module, declaring record, field name)` and never a position, so a field
+ * inserted in the middle moves nothing and a scene saved before it loads afterwards.
+ *
+ * ## Numeric fields get typed arrays; everything else gets a plain one
+ *
+ * `AGENTS.md`'s bulk-data rule where it belongs. **What it gives up** is that a component is not a
+ * value a caller can hold — reading one means reading its fields — which is deliberate, because a
+ * component object handed out is an object allocated per read, sixty times a second.
+ */
+import type { Schema } from 'driftscript';
+import { type Entity } from './entity.ts';
+import { type ComponentView } from './view.ts';
+/**
+ * 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 declare const presenceColumn: (field: string) => string;
+/**
+ * `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 declare function optionInner(type: string): string | undefined;
+export interface ComponentType {
+    readonly name: string;
+    readonly schema: Schema;
+    /**
+     * A small dense integer, for indexing by component type in a query or a schedule.
+     *
+     * Allocated in declaration order at module load, so it is the same on every run of the same
+     * code — and it is deliberately **not** what a scene is written with. A scene uses field ids,
+     * which survive a reorder; this survives nothing and is never stored.
+     */
+    readonly id: number;
+    /** Fields typed `Entity`, which a scene load has to rewrite through its id map. */
+    readonly entityFields: readonly string[];
+}
+export declare function defineComponent(schema: Schema): ComponentType;
+export declare function defineComponent(name: string, fields: Readonly<Record<string, string>>): ComponentType;
+/**
+ * One store's contents, for a rewind. Reused between saves; see `AllocatorSnapshot`.
+ *
+ * **`sparse` is absent and that is a decision.** It is derivable from `dense` — position *i* holds
+ * the entity whose sparse entry is *i* — and its length grows with the highest entity index the
+ * world has ever reached rather than with the live set. A world of forty entities that once held
+ * forty thousand would copy 160 KB per store per tick to save an array it can rebuild in forty
+ * writes. `loadFrom` rebuilds it.
+ */
+export interface StoreSnapshot {
+    count: number;
+    dense: Float64Array;
+    /** Field name to its column's contents, mirroring `columns`. Grown to match, never shrunk. */
+    columns: Map<string, NumericColumn | unknown[]>;
+}
+export declare function createStoreSnapshot(): StoreSnapshot;
+export interface ComponentStoreOptions {
+    /** Initial column length. Present for the growth test; a consumer has no reason to set it. */
+    readonly capacity?: number;
+}
+/** A mutable numeric column, which the readonly `ArrayLike` in `COLUMNS` does not describe. */
+type NumericColumn = Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint8Array | Uint16Array | Uint32Array;
+export declare class ComponentStore {
+    readonly type: ComponentType;
+    /**
+     * 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.
+     */
+    private denseArray;
+    /** Entity index → position in `dense`, or -1. */
+    private sparse;
+    private readonly columns;
+    private count;
+    /**
+     * 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.
+     */
+    private viewObject;
+    constructor(type: ComponentType, options?: ComponentStoreOptions);
+    get size(): number;
+    /** The entities this store holds, oldest first. Valid up to `size`; the rest is capacity. */
+    get dense(): Float64Array;
+    /**
+     * 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(): ComponentView;
+    /** Point the view at the arrays that exist now. Called after either kind of growth. */
+    private refresh;
+    /** One field's storage, for a caller iterating it directly rather than through `read`. */
+    column(field: string): NumericColumn | unknown[];
+    has(entity: Entity): boolean;
+    add(entity: Entity, values?: Readonly<Record<string, unknown>>): void;
+    /**
+     * 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: Entity): boolean;
+    read(entity: Entity, field: string): unknown;
+    write(entity: Entity, field: string, value: unknown): void;
+    /**
+     * 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.
+     */
+    private positionOf;
+    /**
+     * 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: StoreSnapshot): void;
+    /**
+     * 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: StoreSnapshot): void;
+    private noField;
+    private grow;
+    private growSparse;
+}
+export {};