@driftengine/entities 3.61.0

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * The entity model's public surface.
+ *
+ * **This package imports no other engine package**, which is a stronger rule than the one every
+ * package obeys and is the reason it can be depended on by anything. An entity model that knew what
+ * a `Transform` was would be an entity model that knew it had a scene — and the whole argument for
+ * declared reads and writes is that a declaration is about a component *id* rather than about what
+ * the component means.
+ *
+ * It declares no component types at all, for the same reason. A consumer writes the ones its world
+ * needs, or takes them from whichever package owns the subsystem.
+ *
+ * The one dependency is `driftscript`, for `Schema` and `migrate` — 406 bytes gzipped, measured.
+ * That is the design's spine rather than a convenience: storage layout, serialization, migration
+ * and a future inspector all read **one** description of a component, so there is no second one to
+ * keep in sync.
+ */
+export type { ComponentStoreOptions, ComponentType, StoreSnapshot } from './store.ts';
+export { ComponentStore, createStoreSnapshot, defineComponent } from './store.ts';
+export type { ComponentView, ViewColumn } from './view.ts';
+export type { CursorHost } from './query.ts';
+export { QueryCursor } from './query.ts';
+export type { WorldSnapshot } from './world.ts';
+export { World, createWorldSnapshot } from './world.ts';
+export type { SystemDefinition, SystemView } from './system.ts';
+export { BoundSystem } from './system.ts';
+export type { Schedule } from './schedule.ts';
+export { buildSchedule, runSchedule } from './schedule.ts';
+export type { Prefab } from './prefab.ts';
+export { definePrefab, instantiate } from './prefab.ts';
+export type { LoadResult, SerializedScene } from './scene.ts';
+export { deserializeWorld, serializeWorld } from './scene.ts';
+export type { AllocatorSnapshot, Entity, EntityAllocatorOptions } from './entity.ts';
+export { ENTITY_GENERATION_CEILING, ENTITY_INDEX_CEILING, EntityAllocator, createAllocatorSnapshot, entityGeneration, entityIndex, packEntity, } from './entity.ts';

package/dist/index.js

@@ -0,0 +1,9 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+export { ComponentStore, createStoreSnapshot, defineComponent } from './store.js';
+export { QueryCursor } from './query.js';
+export { World, createWorldSnapshot } from './world.js';
+export { BoundSystem } from './system.js';
+export { buildSchedule, runSchedule } from './schedule.js';
+export { definePrefab, instantiate } from './prefab.js';
+export { deserializeWorld, serializeWorld } from './scene.js';
+export { ENTITY_GENERATION_CEILING, ENTITY_INDEX_CEILING, EntityAllocator, createAllocatorSnapshot, entityGeneration, entityIndex, packEntity, } from './entity.js';

package/dist/prefab.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A prefab is a **value**, and instantiating it writes that value into a fresh entity.
+ *
+ * **There is no link back**, and that is a decision rather than a limitation. A live link is what an
+ * *editor* wants — change the prefab and every instance changes — and it costs every instance a
+ * record of which fields it has overridden, checked on every write. Track K is what needs that, and
+ * it can add the record without changing what a prefab is.
+ *
+ * Overrides are applied at instantiation and are not remembered for the same reason: an override
+ * that was remembered would be half of that record, doing none of its job.
+ */
+import type { Entity } from './entity.ts';
+import type { ComponentType } from './store.ts';
+import type { World } from './world.ts';
+export interface Prefab {
+    readonly name: string;
+    readonly components: readonly (readonly [ComponentType, Readonly<Record<string, unknown>>])[];
+}
+export declare function definePrefab(name: string, components: readonly (readonly [ComponentType, Readonly<Record<string, unknown>>])[]): Prefab;
+/**
+ * Make one.
+ *
+ * Overrides are keyed by component **name**, because that is what a caller has in front of them —
+ * a `ComponentType` key would mean holding the type to override a field of it, which is exactly the
+ * import a scene file or an editor panel does not have.
+ *
+ * An override naming a component the prefab does not carry is **refused**. Adding it instead would
+ * make a typo a silent extra component, and adding nothing would make a typo a silent no-op; the
+ * only answer that cannot be mistaken for working is to say so.
+ */
+export declare function instantiate(world: World, prefab: Prefab, overrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>): Entity;

package/dist/prefab.js

@@ -0,0 +1,47 @@
+export function definePrefab(name, components) {
+    return { name, components };
+}
+/**
+ * Make one.
+ *
+ * Overrides are keyed by component **name**, because that is what a caller has in front of them —
+ * a `ComponentType` key would mean holding the type to override a field of it, which is exactly the
+ * import a scene file or an editor panel does not have.
+ *
+ * An override naming a component the prefab does not carry is **refused**. Adding it instead would
+ * make a typo a silent extra component, and adding nothing would make a typo a silent no-op; the
+ * only answer that cannot be mistaken for working is to say so.
+ */
+export function instantiate(world, prefab, overrides = {}) {
+    const named = new Set(prefab.components.map(([type]) => type.name));
+    for (const name of Object.keys(overrides)) {
+        if (named.has(name))
+            continue;
+        throw new Error(`\`${prefab.name}\` has no \`${name}\` to override. It has ${[...named].join(', ')}. An ` +
+            'override for something absent is a typo either way — added silently, or ignored silently.');
+    }
+    const entity = world.create();
+    for (const [type, values] of prefab.components) {
+        const override = overrides[type.name];
+        /*
+         * **Spread would apply a key whose value is `undefined`, which is not an override.** A caller
+         * building one from optional data — `{ hp: config.hp }` where `config.hp` may be absent — means
+         * "leave it alone", and a spread means "set it to nothing": the component is then written with
+         * `undefined` where a number belongs. Measured elsewhere in this repository as the same shape
+         * taking a camera's arm to `NaN` on its first step. Nothing here can see it, because this
+         * repository does not run `exactOptionalPropertyTypes`.
+         */
+        world.add(entity, type, override === undefined ? values : applyOverride(values, override));
+    }
+    return entity;
+}
+/** `values` with every *defined* key of `override` applied over it. */
+function applyOverride(values, override) {
+    const merged = { ...values };
+    for (const key of Object.keys(override)) {
+        const value = override[key];
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}

package/dist/query.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Iterating the entities that have a set of components, without allocating.
+ *
+ * **An iterator allocated per frame is the per-frame allocation `AGENTS.md` forbids**, arriving
+ * through the most-used call in the package. So a cursor is its own iterator, returns a **reused**
+ * result record, and comes from a pool the world owns — the same shape the render graph's arena
+ * uses, and for the same reason.
+ *
+ * The cost is that **a query result may not outlive the loop it was made in**. A caller that stores
+ * one gets whatever the next query writes into it. That is stated here rather than discovered, and
+ * it is the bargain the arena makes too.
+ *
+ * ---
+ *
+ * ## The walk is over the smallest set
+ *
+ * A query over three components walks one dense array and tests membership in the other two, so the
+ * work is bounded by the *smallest* of them. Walking the first named instead would make
+ * `query(Position, Dying)` cost the whole world when two entities are dying.
+ *
+ * **The order is not sorted and is not promised.** It follows the chosen dense array, whose order is
+ * insertion modified by swap-removal — deterministic given the same history, which is what a replay
+ * needs, and not a stable property of the set. A consumer needing a stable order sorts by entity,
+ * and the fact that it is a choice is why this says so.
+ */
+import type { Entity } from './entity.ts';
+import type { ComponentStore, ComponentType } from './store.ts';
+/**
+ * What a cursor needs from the world it belongs to.
+ *
+ * An interface rather than the `World` class, because a cursor importing the world and the world
+ * importing the cursor is a cycle — and because what a cursor actually needs is two functions.
+ */
+export interface CursorHost {
+    store(type: ComponentType): ComponentStore;
+    releaseCursor(cursor: QueryCursor): void;
+}
+export declare class QueryCursor implements Iterator<Entity>, Iterable<Entity> {
+    /**
+     * Stores every yielded entity must be in, including the one being walked.
+     *
+     * **Reused with a count rather than emptied**, and that is not a micro-optimisation. Setting
+     * `length = 0` and pushing again makes V8 re-grow the backing store, which allocates — measured:
+     * half a million `length = 0` and two pushes collected as often as a control allocating two
+     * objects per iteration, while writing in place collected nothing. The whole point of a pooled
+     * cursor is undone by emptying its arrays.
+     */
+    private readonly required;
+    private requiredCount;
+    /** Stores no yielded entity may be in. Same arrangement, same reason. */
+    private readonly excluded;
+    private excludedCount;
+    private walking;
+    private at;
+    private readonly step;
+    private host;
+    private open_;
+    constructor(host: CursorHost);
+    private readonly owner;
+    /**
+     * Configure and take ownership.
+     *
+     * **Four component types rather than a rest parameter**, because `...types` allocates an array on
+     * every call — once per system per frame, which is exactly the hot path this file exists for.
+     * Four covers every query in the corpus; a fifth is `.with()`, which is one more call and no
+     * array either.
+     */
+    open(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): this;
+    /** Require a component without yielding anything about it. */
+    with(type: ComponentType): this;
+    /** Exclude everything that has this component. */
+    without(type: ComponentType): this;
+    private require;
+    [Symbol.iterator](): Iterator<Entity>;
+    next(): IteratorResult<Entity>;
+    /** Called by `for…of` when a loop breaks, which is what stops an abandoned cursor leaking. */
+    return(): IteratorResult<Entity>;
+    private matches;
+    private chooseSmallest;
+    private finish;
+}

package/dist/query.js

@@ -0,0 +1,140 @@
+export class QueryCursor {
+    /**
+     * Stores every yielded entity must be in, including the one being walked.
+     *
+     * **Reused with a count rather than emptied**, and that is not a micro-optimisation. Setting
+     * `length = 0` and pushing again makes V8 re-grow the backing store, which allocates — measured:
+     * half a million `length = 0` and two pushes collected as often as a control allocating two
+     * objects per iteration, while writing in place collected nothing. The whole point of a pooled
+     * cursor is undone by emptying its arrays.
+     */
+    required = [];
+    requiredCount = 0;
+    /** Stores no yielded entity may be in. Same arrangement, same reason. */
+    excluded = [];
+    excludedCount = 0;
+    walking = null;
+    at = 0;
+    step = { value: 0, done: false };
+    host = null;
+    open_ = false;
+    constructor(host) {
+        this.host = host;
+        this.owner = host;
+    }
+    owner;
+    /**
+     * Configure and take ownership.
+     *
+     * **Four component types rather than a rest parameter**, because `...types` allocates an array on
+     * every call — once per system per frame, which is exactly the hot path this file exists for.
+     * Four covers every query in the corpus; a fifth is `.with()`, which is one more call and no
+     * array either.
+     */
+    open(a, b, c, d) {
+        this.requiredCount = 0;
+        this.excludedCount = 0;
+        this.require(a);
+        if (b !== undefined)
+            this.require(b);
+        if (c !== undefined)
+            this.require(c);
+        if (d !== undefined)
+            this.require(d);
+        this.walking = null;
+        this.at = 0;
+        this.host = this.owner;
+        this.open_ = true;
+        return this;
+    }
+    /** Require a component without yielding anything about it. */
+    with(type) {
+        this.require(type);
+        return this;
+    }
+    /** Exclude everything that has this component. */
+    without(type) {
+        const store = this.owner.store(type);
+        if (this.excludedCount < this.excluded.length)
+            this.excluded[this.excludedCount] = store;
+        else
+            this.excluded.push(store);
+        this.excludedCount += 1;
+        return this;
+    }
+    require(type) {
+        const store = this.owner.store(type);
+        /* Written in place where the slot exists; pushed only the first time the cursor is asked for a
+           query this wide, so a pool of cursors settles at the widest query a consumer makes. */
+        if (this.requiredCount < this.required.length)
+            this.required[this.requiredCount] = store;
+        else
+            this.required.push(store);
+        this.requiredCount += 1;
+    }
+    [Symbol.iterator]() {
+        /*
+         * The cursor is its own iterator. Returning a fresh object here would allocate one per loop,
+         * which is the whole thing this file exists to avoid — and it is what makes `for…of` over a
+         * cursor twice at once wrong, which the pool is what stops.
+         */
+        return this;
+    }
+    next() {
+        if (!this.open_)
+            return this.step.done ? this.step : this.finish();
+        if (this.walking === null)
+            this.chooseSmallest();
+        const walking = this.walking;
+        if (walking === null)
+            return this.finish();
+        const dense = walking.dense;
+        for (; this.at < walking.size; this.at += 1) {
+            const entity = dense[this.at];
+            if (!this.matches(entity, walking))
+                continue;
+            this.at += 1;
+            this.step.value = entity;
+            this.step.done = false;
+            return this.step;
+        }
+        return this.finish();
+    }
+    /** Called by `for…of` when a loop breaks, which is what stops an abandoned cursor leaking. */
+    return() {
+        return this.finish();
+    }
+    matches(entity, walking) {
+        for (let i = 0; i < this.requiredCount; i += 1) {
+            const store = this.required[i];
+            if (store !== walking && !store.has(entity))
+                return false;
+        }
+        for (let i = 0; i < this.excludedCount; i += 1) {
+            if (this.excluded[i].has(entity))
+                return false;
+        }
+        return true;
+    }
+    chooseSmallest() {
+        let smallest = null;
+        for (let i = 0; i < this.requiredCount; i += 1) {
+            const store = this.required[i];
+            if (smallest === null || store.size < smallest.size)
+                smallest = store;
+        }
+        this.walking = smallest;
+    }
+    finish() {
+        this.walking = null;
+        if (this.open_) {
+            this.open_ = false;
+            /* Through the host rather than a closure handed in at `open`: a closure per query is an
+               allocation per system per frame, which is the thing this file refuses. */
+            this.owner.releaseCursor(this);
+        }
+        this.step.value = 0;
+        this.step.done = true;
+        return this.step;
+    }
+}

package/dist/scene.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A world as data: entities, their components, and every value under a **stable field id**.
+ *
+ * Ids rather than names, so a field renamed with an explicit id still loads; never positions,
+ * because a field inserted in the middle would renumber every field after it and a save would load
+ * the right names with the wrong values — worse than failing, because it looks like it worked.
+ *
+ * ---
+ *
+ * ## Loading across a change goes through `migrate`, unchanged
+ *
+ * The file carries the **schema each component had when it was written**, so a load has both sides
+ * and can hand them to the migration Track N's Phase 5 built. A field added since arrives with its
+ * default, one removed is dropped, and one whose *type* changed is refused naming it rather than
+ * coerced. Nothing here re-implements any of that; if the migration needs changing, the change
+ * belongs in `driftscript` and serves both callers.
+ *
+ * ## Entity references are remapped, which is why the type has to be declared
+ *
+ * A saved entity's slot may be live in the world being loaded into, so a scene that kept its
+ * handles would overwrite whatever held them. Every entity is created fresh and every stored
+ * reference is rewritten through the map — which only works for fields **declared** `Entity`. A
+ * number that happens to hold one is a number, and is left alone. That is the cost of not guessing.
+ *
+ * ## It writes nothing until it can write everything
+ *
+ * A refusal on the fifth entity must not leave four in the world. Every migration runs first, into
+ * plain objects; the world is touched only once all of them have succeeded.
+ */
+import { type Schema } from 'driftscript';
+import type { Entity } from './entity.ts';
+import type { ComponentType } from './store.ts';
+import type { World } from './world.ts';
+export interface SerializedScene {
+    readonly version: 1;
+    /** What each component type looked like when this was written. The `from` half of a migration. */
+    readonly schemas: Readonly<Record<string, Schema>>;
+    readonly entities: readonly {
+        /** Component name → field id → value. Entity-typed values hold a scene index, not a handle. */
+        readonly components: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    }[];
+}
+export type LoadResult = {
+    readonly loaded: true;
+    readonly entities: readonly Entity[];
+} | {
+    readonly loaded: false;
+    readonly reason: string;
+};
+/**
+ * Write a world out.
+ *
+ * The component types are passed rather than discovered, because a world holds a store for every
+ * type anything has ever asked it about — including empty ones a query created — and a scene is a
+ * decision about what to save rather than everything that happens to exist.
+ */
+export declare function serializeWorld(world: World, types: readonly ComponentType[]): SerializedScene;
+/** Read a world in, or refuse in words having written nothing. */
+export declare function deserializeWorld(world: World, scene: SerializedScene, types: readonly ComponentType[]): LoadResult;

package/dist/scene.js

@@ -0,0 +1,136 @@
+/**
+ * A world as data: entities, their components, and every value under a **stable field id**.
+ *
+ * Ids rather than names, so a field renamed with an explicit id still loads; never positions,
+ * because a field inserted in the middle would renumber every field after it and a save would load
+ * the right names with the wrong values — worse than failing, because it looks like it worked.
+ *
+ * ---
+ *
+ * ## Loading across a change goes through `migrate`, unchanged
+ *
+ * The file carries the **schema each component had when it was written**, so a load has both sides
+ * and can hand them to the migration Track N's Phase 5 built. A field added since arrives with its
+ * default, one removed is dropped, and one whose *type* changed is refused naming it rather than
+ * coerced. Nothing here re-implements any of that; if the migration needs changing, the change
+ * belongs in `driftscript` and serves both callers.
+ *
+ * ## Entity references are remapped, which is why the type has to be declared
+ *
+ * A saved entity's slot may be live in the world being loaded into, so a scene that kept its
+ * handles would overwrite whatever held them. Every entity is created fresh and every stored
+ * reference is rewritten through the map — which only works for fields **declared** `Entity`. A
+ * number that happens to hold one is a number, and is left alone. That is the cost of not guessing.
+ *
+ * ## It writes nothing until it can write everything
+ *
+ * A refusal on the fifth entity must not leave four in the world. Every migration runs first, into
+ * plain objects; the world is touched only once all of them have succeeded.
+ */
+import { migrate } from 'driftscript';
+/**
+ * Write a world out.
+ *
+ * The component types are passed rather than discovered, because a world holds a store for every
+ * type anything has ever asked it about — including empty ones a query created — and a scene is a
+ * decision about what to save rather than everything that happens to exist.
+ */
+export function serializeWorld(world, types) {
+    /* Scene index per entity, so a stored reference is a position in this file rather than a handle
+       that means nothing in another world. */
+    /*
+     * Membership through a `Set`, not `Array.includes`.
+     *
+     * It was `includes`, which is a linear scan per entity and made this quadratic: **8.8 seconds**
+     * for a hundred thousand entities across three components, measured. With a set it is a fraction
+     * of that. The shape is worth naming because it reads as obviously correct — the list is the
+     * thing being built, so testing it is the natural move — and the cost is invisible until the
+     * world is large.
+     */
+    const indexOf = new Map();
+    const living = [];
+    for (const type of types) {
+        const store = world.store(type);
+        for (let i = 0; i < store.size; i += 1) {
+            const entity = store.dense[i];
+            if (indexOf.has(entity))
+                continue;
+            indexOf.set(entity, living.length);
+            living.push(entity);
+        }
+    }
+    const schemas = {};
+    for (const type of types)
+        schemas[type.name] = type.schema;
+    const entities = living.map((entity) => {
+        const components = {};
+        for (const type of types) {
+            if (!world.has(entity, type))
+                continue;
+            const fields = {};
+            for (const field of type.schema.fields) {
+                const value = world.read(entity, type, field.name);
+                fields[field.id] = field.type === 'Entity' ? (indexOf.get(value) ?? -1) : value;
+            }
+            components[type.name] = fields;
+        }
+        return { components };
+    });
+    return { version: 1, schemas, entities };
+}
+/** Read a world in, or refuse in words having written nothing. */
+export function deserializeWorld(world, scene, types) {
+    const byName = new Map(types.map((type) => [type.name, type]));
+    /* Everything checked and migrated before the world is touched at all. */
+    const planned = [];
+    for (const record of scene.entities) {
+        const components = [];
+        for (const [name, saved] of Object.entries(record.components)) {
+            const type = byName.get(name);
+            if (type === undefined) {
+                return {
+                    loaded: false,
+                    reason: `this scene holds a \`${name}\`, and no component type by that name was supplied. ` +
+                        'Loading it as nothing would drop data the file still holds.',
+                };
+            }
+            const from = scene.schemas[name];
+            if (from === undefined) {
+                return {
+                    loaded: false,
+                    reason: `this scene holds a \`${name}\` and no schema for it, so there is nothing to match ` +
+                        'its fields by. A scene written without one cannot be loaded across any change at all.',
+                };
+            }
+            /* `migrate` takes an instance keyed by the *saved* names, so the ids in the file are read
+               through the saved schema. That is what keeps the file addressed by id and the migration
+               unchanged from the one the language uses. */
+            const instance = {};
+            for (const field of from.fields)
+                instance[field.name] = saved[field.id];
+            const defaults = {};
+            for (const field of type.schema.fields)
+                defaults[field.name] = field.type === 'String' ? null : 0;
+            const result = migrate(instance, from, type.schema, defaults);
+            if (!result.migrated)
+                return { loaded: false, reason: result.reason };
+            components.push({ type, values: result.value });
+        }
+        planned.push({ components });
+    }
+    const made = planned.map(() => world.create());
+    planned.forEach((record, index) => {
+        const entity = made[index];
+        for (const { type, values } of record.components) {
+            /* Scene indices become handles here, and only for fields the schema declares `Entity`. */
+            for (const field of type.schema.fields) {
+                if (field.type !== 'Entity')
+                    continue;
+                const at = values[field.name];
+                values[field.name] = typeof at === 'number' && at >= 0 && at < made.length ? made[at] : 0;
+            }
+            world.add(entity, type, values);
+        }
+    });
+    return { loaded: true, entities: made };
+}

package/dist/schedule.d.ts

@@ -0,0 +1,44 @@
+import { type SystemDefinition } from './system.ts';
+import type { World } from './world.ts';
+export interface Schedule {
+    /** The systems, in the order they run. */
+    readonly order: readonly SystemDefinition[];
+    /**
+     * Runs of adjacent systems that touch nothing in common.
+     *
+     * Reported rather than used. A group of one is a system that conflicts with its neighbour.
+     */
+    readonly groups: readonly (readonly SystemDefinition[])[];
+}
+/**
+ * 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 declare function buildSchedule(systems: readonly SystemDefinition[]): Schedule;
+/**
+ * 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 declare function runSchedule(world: World, schedule: Schedule, tick: number): void;