@driftengine/entities 3.61.0

package/dist/view.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A live handle on a component's columns, for a caller that indexes them directly.
+ *
+ * **A holder of this object holds the object and never an array.** A column grows by
+ * reallocation, so a hoisted `Float64Array` goes stale the first time anything adds a component —
+ * and `system.ts` makes `add` immediate on purpose, so that happens *during* a walk. The failure
+ * would be a write into an array nothing reads any more: no error, no wrong type, just a value
+ * that never arrives.
+ *
+ * So the store refreshes this object's properties after a reallocation rather than handing back a
+ * new object. A caller that hoisted it at the top of a loop is still correct at the bottom.
+ *
+ * **What this costs** is one live object per store, and a property load on every field access
+ * rather than a captured local. **What would make it wrong** is a caller holding one past its
+ * world's disposal — which is why a generated script reaches one through a call per loop rather
+ * than caching it across frames.
+ *
+ * ---
+ *
+ * ## Absence is a column, not a value
+ *
+ * An optional field has two entries here: the value column under its own name, and a `Uint8Array`
+ * under `presenceColumn(field)`. A reader that consults only the value column reads whatever the
+ * slot last held, which for a cleared field is the value it was cleared from.
+ */
+/** Every array shape a column can be. `unknown[]` is the boxed case — today, `String`. */
+export type ViewColumn = Int8Array | Int16Array | Int32Array | Uint8Array | Uint16Array | Uint32Array | Float32Array | Float64Array | unknown[];
+/**
+ * A component's storage, addressable by field name.
+ *
+ * `sparse` maps an entity's *index* — not its handle — to a position in every column here. Taking
+ * the index from a handle is `entity % 2 ** 26`, which is what a caller that cannot import
+ * `entityIndex` writes inline.
+ */
+export interface ComponentView {
+    sparse: Int32Array;
+    [field: string]: ViewColumn;
+}
+/**
+ * Point a view at the arrays a store holds now.
+ *
+ * Called when a view is first asked for and again after every reallocation. It rewrites the
+ * existing object rather than returning a new one, because the object identity is the contract: a
+ * caller hoisted it, and handing back a second object would leave the first one pointing at
+ * storage nothing reads.
+ *
+ * It lives here rather than on the store so that the two halves of this mechanism — what a view
+ * *is* and what keeps one current — are one file. **What that costs** is passing the store's two
+ * internals in. **What would make it wrong** is a store whose columns are not a map, at which point
+ * this signature is the thing to change rather than the call sites.
+ */
+export declare function refreshView(view: ComponentView, sparse: Int32Array, columns: ReadonlyMap<string, ViewColumn>): void;

package/dist/view.js

@@ -0,0 +1,43 @@
+/**
+ * A live handle on a component's columns, for a caller that indexes them directly.
+ *
+ * **A holder of this object holds the object and never an array.** A column grows by
+ * reallocation, so a hoisted `Float64Array` goes stale the first time anything adds a component —
+ * and `system.ts` makes `add` immediate on purpose, so that happens *during* a walk. The failure
+ * would be a write into an array nothing reads any more: no error, no wrong type, just a value
+ * that never arrives.
+ *
+ * So the store refreshes this object's properties after a reallocation rather than handing back a
+ * new object. A caller that hoisted it at the top of a loop is still correct at the bottom.
+ *
+ * **What this costs** is one live object per store, and a property load on every field access
+ * rather than a captured local. **What would make it wrong** is a caller holding one past its
+ * world's disposal — which is why a generated script reaches one through a call per loop rather
+ * than caching it across frames.
+ *
+ * ---
+ *
+ * ## Absence is a column, not a value
+ *
+ * An optional field has two entries here: the value column under its own name, and a `Uint8Array`
+ * under `presenceColumn(field)`. A reader that consults only the value column reads whatever the
+ * slot last held, which for a cleared field is the value it was cleared from.
+ */
+/**
+ * Point a view at the arrays a store holds now.
+ *
+ * Called when a view is first asked for and again after every reallocation. It rewrites the
+ * existing object rather than returning a new one, because the object identity is the contract: a
+ * caller hoisted it, and handing back a second object would leave the first one pointing at
+ * storage nothing reads.
+ *
+ * It lives here rather than on the store so that the two halves of this mechanism — what a view
+ * *is* and what keeps one current — are one file. **What that costs** is passing the store's two
+ * internals in. **What would make it wrong** is a store whose columns are not a map, at which point
+ * this signature is the thing to change rather than the call sites.
+ */
+export function refreshView(view, sparse, columns) {
+    view.sparse = sparse;
+    for (const [field, column] of columns)
+        view[field] = column;
+}

package/dist/world.d.ts

@@ -0,0 +1,121 @@
+/**
+ * A world: the entities, the stores keyed by component type, and the cursor pool.
+ *
+ * **What a world adds over a bag of stores is that an entity which is gone is gone from all of
+ * them.** Without that, destroying something leaves its components behind, a query goes on yielding
+ * it, and a scene serialises a handle nothing can reach — three symptoms of one missing sweep.
+ */
+import { type AllocatorSnapshot, type Entity, type EntityAllocatorOptions } from './entity.ts';
+import { type CursorHost, QueryCursor } from './query.ts';
+import { ComponentStore, type ComponentType, type StoreSnapshot } from './store.ts';
+import type { ComponentView } from './view.ts';
+/**
+ * A world's whole state at one instant, for a rewind. **Not a save file**, and the two are not
+ * interchangeable.
+ *
+ * `serializeWorld` in `scene.ts` writes a scene: it carries every component's schema so a load can
+ * migrate across a change, keys values by stable field id so a renamed field still loads, and
+ * *creates* entities so a scene can be loaded into a world that already holds things. Every one of
+ * those properties is wrong here. A rewind needs the handles it had — an input recorded for entity
+ * 4,194,307 means nothing if the restore hands that slot a new generation — and it needs to cost
+ * nothing per tick, which rules out an object per component per entity.
+ *
+ * | | `SerializedScene` | `WorldSnapshot` |
+ * |---|---|---|
+ * | Keyed by | stable field id | column position |
+ * | Handles | remapped, all of them change | preserved, generations included |
+ * | On load | creates, appending | overwrites in place |
+ * | Migration | yes | no |
+ * | Allocates | per entity, per component | nothing after the first save |
+ * | Goes on a wire | yes | never |
+ *
+ * **A rewind covers every store the world holds, and takes no list of types.** That is the other
+ * half of the difference: `serializeWorld` is handed the types because a scene is a decision about
+ * what to save, and a rewind is not a decision at all. A component type left out of a restore is
+ * state that survived the rewind, which is the definition of a desync.
+ */
+export interface WorldSnapshot {
+    readonly allocator: AllocatorSnapshot;
+    /** By `ComponentType.id`. Holds a slot for every store the world had when this was written. */
+    readonly stores: Map<number, StoreSnapshot>;
+}
+/**
+ * An empty slot, to be filled by `World.saveInto` and reused for the life of a rewind ring.
+ *
+ * Its arrays are zero-length and grow to the world's shape on the first save, so a ring of eight
+ * costs eight small objects up front and allocates nothing on the ticks that matter.
+ */
+export declare function createWorldSnapshot(): WorldSnapshot;
+export declare class World implements CursorHost {
+    private readonly entities;
+    private readonly stores;
+    /**
+     * Cursors not currently in a loop.
+     *
+     * A pool rather than a fresh cursor, because a query runs per frame per system and an object per
+     * query is the allocation this whole design refuses. It grows to the deepest nesting a consumer
+     * reaches and never shrinks, which for any real workload is a handful.
+     */
+    private readonly idle;
+    private inUse;
+    constructor(options?: EntityAllocatorOptions);
+    get liveCount(): number;
+    /** How many cursors are inside a loop. For a consumer looking at a leak rather than inferring one. */
+    get cursorsInUse(): number;
+    create(): Entity;
+    alive(entity: Entity): boolean;
+    /**
+     * Destroy an entity and sweep it out of every store.
+     *
+     * Every store, not the ones it is known to be in: a world keeps no per-entity list of its
+     * components, because that list is a second description of what the stores already know and it
+     * would be the thing that goes stale. The sweep is one `remove` per registered type, which is a
+     * number of component *types* rather than of entities.
+     */
+    destroy(entity: Entity): boolean;
+    /** The store for a component type, made on first ask. */
+    store(type: ComponentType): ComponentStore;
+    /**
+     * The live columns of a component, for a caller indexing them directly.
+     *
+     * **Unenforced, and that is not an oversight**: a world outside a system has no declarations to
+     * enforce against. Inside one, go through `SystemView.view`, which checks first — see the note
+     * there for what happens if anything routes around it.
+     */
+    view(type: ComponentType): ComponentView;
+    add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void;
+    remove(entity: Entity, type: ComponentType): boolean;
+    has(entity: Entity, type: ComponentType): boolean;
+    read(entity: Entity, type: ComponentType, field: string): unknown;
+    write(entity: Entity, type: ComponentType, field: string, value: unknown): void;
+    /**
+     * Everything that has all of these components.
+     *
+     * The cursor is borrowed and is given back when the loop ends — including when it `break`s, which
+     * `for…of` reports through the iterator's `return`. A caller that keeps the result past its loop
+     * gets whatever the next query writes into it; see `query.ts`.
+     */
+    query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor;
+    /** Called by a cursor when its loop ends, including when the loop breaks. Not for a consumer. */
+    releaseCursor(cursor: QueryCursor): void;
+    /**
+     * Write this world's whole state into a slot. See `WorldSnapshot` for why this is not a save.
+     *
+     * **Every store, and the slot keeps one for each.** A store is never removed from a world, so a
+     * later restore always finds the stores this save described still present — which is why nothing
+     * here has to record a component *type*, only its id.
+     */
+    saveInto(slot: WorldSnapshot): void;
+    /**
+     * Put this world back to a saved slot.
+     *
+     * **A store the slot does not mention is emptied rather than skipped.** Such a store was created
+     * after the save — by a query, or by something adding a component the world had never seen — and
+     * leaving its contents alone would leave components attached to entities the restored allocator
+     * says do not exist. Emptying it is what the snapshot actually claims.
+     *
+     * The cursor pool is untouched: a borrowed cursor belongs to a loop that is running, and a
+     * rewind happens between ticks.
+     */
+    loadFrom(slot: WorldSnapshot): void;
+}

package/dist/world.js

@@ -0,0 +1,161 @@
+/**
+ * A world: the entities, the stores keyed by component type, and the cursor pool.
+ *
+ * **What a world adds over a bag of stores is that an entity which is gone is gone from all of
+ * them.** Without that, destroying something leaves its components behind, a query goes on yielding
+ * it, and a scene serialises a handle nothing can reach — three symptoms of one missing sweep.
+ */
+import { EntityAllocator, createAllocatorSnapshot, } from './entity.js';
+import { QueryCursor } from './query.js';
+import { ComponentStore, createStoreSnapshot, } from './store.js';
+/**
+ * An empty slot, to be filled by `World.saveInto` and reused for the life of a rewind ring.
+ *
+ * Its arrays are zero-length and grow to the world's shape on the first save, so a ring of eight
+ * costs eight small objects up front and allocates nothing on the ticks that matter.
+ */
+export function createWorldSnapshot() {
+    return { allocator: createAllocatorSnapshot(), stores: new Map() };
+}
+export class World {
+    entities;
+    stores = new Map();
+    /**
+     * Cursors not currently in a loop.
+     *
+     * A pool rather than a fresh cursor, because a query runs per frame per system and an object per
+     * query is the allocation this whole design refuses. It grows to the deepest nesting a consumer
+     * reaches and never shrinks, which for any real workload is a handful.
+     */
+    idle = [];
+    inUse = 0;
+    constructor(options = {}) {
+        this.entities = new EntityAllocator(options);
+    }
+    get liveCount() {
+        return this.entities.liveCount;
+    }
+    /** How many cursors are inside a loop. For a consumer looking at a leak rather than inferring one. */
+    get cursorsInUse() {
+        return this.inUse;
+    }
+    create() {
+        return this.entities.create();
+    }
+    alive(entity) {
+        return this.entities.alive(entity);
+    }
+    /**
+     * Destroy an entity and sweep it out of every store.
+     *
+     * Every store, not the ones it is known to be in: a world keeps no per-entity list of its
+     * components, because that list is a second description of what the stores already know and it
+     * would be the thing that goes stale. The sweep is one `remove` per registered type, which is a
+     * number of component *types* rather than of entities.
+     */
+    destroy(entity) {
+        if (!this.entities.alive(entity))
+            return false;
+        for (const store of this.stores.values())
+            store.remove(entity);
+        return this.entities.destroy(entity);
+    }
+    /** The store for a component type, made on first ask. */
+    store(type) {
+        const existing = this.stores.get(type.id);
+        if (existing !== undefined)
+            return existing;
+        const made = new ComponentStore(type);
+        this.stores.set(type.id, made);
+        return made;
+    }
+    /**
+     * The live columns of a component, for a caller indexing them directly.
+     *
+     * **Unenforced, and that is not an oversight**: a world outside a system has no declarations to
+     * enforce against. Inside one, go through `SystemView.view`, which checks first — see the note
+     * there for what happens if anything routes around it.
+     */
+    view(type) {
+        return this.store(type).view();
+    }
+    add(entity, type, values = {}) {
+        if (!this.entities.alive(entity)) {
+            throw new Error(`entity ${entity} is not alive, so \`${type.name}\` has nowhere to go. Storing it anyway ` +
+                'would leave a component keyed to a handle nothing can reach, which a query would skip ' +
+                'and a scene would serialise.');
+        }
+        this.store(type).add(entity, values);
+    }
+    remove(entity, type) {
+        return this.store(type).remove(entity);
+    }
+    has(entity, type) {
+        return this.store(type).has(entity);
+    }
+    read(entity, type, field) {
+        return this.store(type).read(entity, field);
+    }
+    write(entity, type, field, value) {
+        this.store(type).write(entity, field, value);
+    }
+    /**
+     * Everything that has all of these components.
+     *
+     * The cursor is borrowed and is given back when the loop ends — including when it `break`s, which
+     * `for…of` reports through the iterator's `return`. A caller that keeps the result past its loop
+     * gets whatever the next query writes into it; see `query.ts`.
+     */
+    query(a, b, c, d) {
+        const cursor = this.idle.pop() ?? new QueryCursor(this);
+        this.inUse += 1;
+        return cursor.open(a, b, c, d);
+    }
+    /** Called by a cursor when its loop ends, including when the loop breaks. Not for a consumer. */
+    releaseCursor(cursor) {
+        this.inUse -= 1;
+        this.idle.push(cursor);
+    }
+    /**
+     * Write this world's whole state into a slot. See `WorldSnapshot` for why this is not a save.
+     *
+     * **Every store, and the slot keeps one for each.** A store is never removed from a world, so a
+     * later restore always finds the stores this save described still present — which is why nothing
+     * here has to record a component *type*, only its id.
+     */
+    saveInto(slot) {
+        this.entities.saveInto(slot.allocator);
+        for (const [id, store] of this.stores) {
+            let into = slot.stores.get(id);
+            if (into === undefined) {
+                into = createStoreSnapshot();
+                slot.stores.set(id, into);
+            }
+            store.saveInto(into);
+        }
+    }
+    /**
+     * Put this world back to a saved slot.
+     *
+     * **A store the slot does not mention is emptied rather than skipped.** Such a store was created
+     * after the save — by a query, or by something adding a component the world had never seen — and
+     * leaving its contents alone would leave components attached to entities the restored allocator
+     * says do not exist. Emptying it is what the snapshot actually claims.
+     *
+     * The cursor pool is untouched: a borrowed cursor belongs to a loop that is running, and a
+     * rewind happens between ticks.
+     */
+    loadFrom(slot) {
+        this.entities.loadFrom(slot.allocator);
+        for (const [id, store] of this.stores) {
+            store.loadFrom(slot.stores.get(id) ?? EMPTY_STORE);
+        }
+    }
+}
+/**
+ * The slot a store restores from when the snapshot never knew about it: count zero.
+ *
+ * Shared and never written to — `ComponentStore.loadFrom` only reads its slot — so this costs one
+ * object for the process instead of one per rewind.
+ */
+const EMPTY_STORE = createStoreSnapshot();

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@driftengine/entities",
+  "version": "3.61.0",
+  "description": "Entities with generational identity, component storage, systems and scenes",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "driftscript": "1.13.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/entities"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "ecs",
+    "entity-component-system",
+    "prefab",
+    "scene"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}