@driftengine/entities 3.61.0

package/src/entity.ts

@@ -0,0 +1,256 @@
+/**
+ * What an entity *is*, and the allocator that hands them out.
+ *
+ * An entity is a handle and nothing else — no object, no class, no fields. What it *has* lives in
+ * component stores keyed by it, which is the whole arrangement, and it is why an entity can be a
+ * number in a typed array rather than something a frame has to chase a pointer to.
+ *
+ * ---
+ *
+ * ## The generation, and why it may not wrap
+ *
+ * **An index freed and reused makes every old reference to it silently valid** — pointing at a
+ * different thing, of a different kind, with no error anywhere. That is the failure the generation
+ * exists to prevent, so the only question worth deciding is how long before it wraps and brings the
+ * failure back.
+ *
+ * The conventional answer is a packed 32-bit handle, twenty-four bits of index and eight of
+ * generation. It makes a slot's 257th reuse hand back a handle **identical** to its first. Here the
+ * split is 26 and 27, combined arithmetically rather than by shifting, because a shift is 32-bit in
+ * JavaScript and a double is exact to 53: sixty-seven million entities, and 134 million reuses of
+ * each slot before a repeat.
+ *
+ * **26 + 27 is the whole 53-bit budget, with nothing spare**, so the largest handle is
+ * `Number.MAX_SAFE_INTEGER` itself. A third field in a handle, or one more bit of either, stops the
+ * arithmetic being exact — and the failure then is a handle that compares equal to a different one,
+ * which is the same hole the generation was added to close. A test asserts the top handle rather
+ * than leaving that to be discovered.
+ *
+ * **The cost is that a handle is eight bytes rather than four**, because it lives in a
+ * `Float64Array` and not a `Uint32Array`. That is paid on entity *lists* rather than on component
+ * data, which is where the bytes actually are.
+ *
+ * **What would make this wrong** is a consumer with more than 67 million live entities, at which
+ * point the split moves and every stored scene has to be rewritten — which is why the two numbers
+ * are here, once, and every site goes through `packEntity` rather than writing the arithmetic.
+ */
+
+/** One past the highest index a handle can carry: 2^26, or 67,108,864 entities. */
+export const ENTITY_INDEX_CEILING = 67_108_864;
+
+/** One past the highest generation: 2^27, or 134,217,728 reuses of one slot. */
+export const ENTITY_GENERATION_CEILING = 134_217_728;
+
+/**
+ * An entity handle.
+ *
+ * A plain number so it stores in a typed array and compares with `===`. It is opaque: reading the
+ * index or the generation out of one is what `entityIndex` and `entityGeneration` are for, and code
+ * that does the arithmetic itself is code that has to be found when the split moves.
+ */
+export type Entity = number;
+
+export function packEntity(index: number, generation: number): Entity {
+  return index + generation * ENTITY_INDEX_CEILING;
+}
+
+export function entityIndex(entity: Entity): number {
+  return entity % ENTITY_INDEX_CEILING;
+}
+
+export function entityGeneration(entity: Entity): number {
+  return Math.floor(entity / ENTITY_INDEX_CEILING);
+}
+
+/**
+ * An allocator's whole position, for a rewind.
+ *
+ * **Reused between saves rather than made per save.** A rollback loop takes one of these sixty
+ * times a second, so the arrays are grown to the allocator's own capacity once and then written
+ * over; the fields are mutable for that reason and not because a caller should touch them.
+ *
+ * The free queue is held as a count and a typed array instead of the `number[]` the allocator
+ * keeps, so a save is a memcpy. **Its order is part of the state**, not an incidental detail: the
+ * queue is first-in-first-out precisely so slot wear spreads, and restoring the same slots in a
+ * different order hands out different handles on the next create.
+ */
+export interface AllocatorSnapshot {
+  generations: Uint32Array;
+  live: Uint8Array;
+  free: Int32Array;
+  freeCount: number;
+  highWater: number;
+  aliveCount: number;
+}
+
+export function createAllocatorSnapshot(): AllocatorSnapshot {
+  return {
+    generations: new Uint32Array(0),
+    live: new Uint8Array(0),
+    free: new Int32Array(0),
+    freeCount: 0,
+    highWater: 0,
+    aliveCount: 0,
+  };
+}
+
+export interface EntityAllocatorOptions {
+  /**
+   * How many slots this allocator may ever hand out.
+   *
+   * Present so a test can reach the refusal without allocating sixty-seven million slots. A
+   * consumer has no reason to set it, and setting it low does not save memory — the arrays grow on
+   * demand either way.
+   */
+  readonly ceiling?: number;
+}
+
+/**
+ * Slots, their generations, and a queue of the ones that are free.
+ *
+ * **The free list is first-in-first-out**, and that is what makes the generation ceiling a number
+ * about the pool rather than about one slot. A stack hands the same slot straight back, so one
+ * spawn-and-destroy pair in a loop burns that slot's whole range while every other slot sits
+ * unused. A queue spreads the wear.
+ *
+ * The cost is that a freed slot is not reused until every other freed slot has been, so a workload
+ * that churns a handful of entities touches more of the arrays than a stack would. That is a cache
+ * argument against a correctness one, and correctness wins.
+ */
+export class EntityAllocator {
+  /** Generation per slot. Index `i` holds the generation of whatever lives at index `i` now. */
+  private generations: Uint32Array = new Uint32Array(64);
+  /** Whether slot `i` is currently handed out. */
+  private live: Uint8Array = new Uint8Array(64);
+  /** Freed slots, oldest first. A plain array: a queue that grows, drained from the front. */
+  private readonly free: number[] = [];
+  /** How far into the arrays this allocator has ever reached. */
+  private highWater = 0;
+  private alive_ = 0;
+  private readonly ceiling: number;
+
+  constructor(options: EntityAllocatorOptions = {}) {
+    this.ceiling = options.ceiling ?? ENTITY_INDEX_CEILING;
+  }
+
+  get liveCount(): number {
+    return this.alive_;
+  }
+
+  create(): Entity {
+    /* `shift` is O(n) on a large array and this is not a per-frame path — an entity is created when
+       something enters the world. A ring buffer is the fix if a profile ever says so. */
+    const recycled = this.free.shift();
+    if (recycled !== undefined) {
+      this.live[recycled] = 1;
+      this.alive_ += 1;
+      return packEntity(recycled, this.generations[recycled] as number);
+    }
+
+    if (this.highWater >= this.ceiling) {
+      throw new Error(
+        `this world has handed out ${this.ceiling} entities, which is its index ceiling. Nothing ` +
+          'is wrapped or reused: a handle beyond the ceiling would repeat one that is already ' +
+          'live, and answering the wrong entity is worse than refusing.',
+      );
+    }
+
+    const index = this.highWater;
+    this.highWater += 1;
+    this.grow(index + 1);
+    this.live[index] = 1;
+    this.alive_ += 1;
+    return packEntity(index, this.generations[index] as number);
+  }
+
+  /**
+   * Free an entity's slot. `false` when the handle was already stale, which is not an error.
+   *
+   * A caller destroying something twice is a caller that lost track, and the honest answer is that
+   * there was nothing to destroy — the same shape `patchModule` and `Scope.leave` use.
+   */
+  destroy(entity: Entity): boolean {
+    if (!this.alive(entity)) return false;
+    const index = entityIndex(entity);
+    this.live[index] = 0;
+    /*
+     * The generation moves on **destroy**, not on the next create, so a handle stops being live the
+     * moment it is destroyed rather than the moment somebody happens to take its slot. Moving it
+     * later would leave a window in which a destroyed handle still answered `alive`.
+     */
+    const next = ((this.generations[index] as number) + 1) % ENTITY_GENERATION_CEILING;
+    this.generations[index] = next;
+    this.free.push(index);
+    this.alive_ -= 1;
+    return true;
+  }
+
+  alive(entity: Entity): boolean {
+    const index = entityIndex(entity);
+    if (index >= this.highWater) return false;
+    return this.live[index] === 1 && this.generations[index] === entityGeneration(entity);
+  }
+
+  /**
+   * Copy this allocator's position into a slot, growing the slot's arrays if it has not held one
+   * this large before.
+   *
+   * **`highWater` bounds every copy**, because slots beyond it have never been handed out and their
+   * generations are zero on both sides. That is what keeps the cost proportional to the world rather
+   * than to the arrays' capacity.
+   */
+  saveInto(slot: AllocatorSnapshot): void {
+    const reach = this.highWater;
+    if (slot.generations.length < reach) slot.generations = new Uint32Array(reach);
+    if (slot.live.length < reach) slot.live = new Uint8Array(reach);
+    if (slot.free.length < this.free.length) slot.free = new Int32Array(this.free.length);
+
+    for (let i = 0; i < reach; i++) {
+      slot.generations[i] = this.generations[i] as number;
+      slot.live[i] = this.live[i] as number;
+    }
+    for (let i = 0; i < this.free.length; i++) slot.free[i] = this.free[i] as number;
+
+    slot.freeCount = this.free.length;
+    slot.highWater = reach;
+    slot.aliveCount = this.alive_;
+  }
+
+  /**
+   * Put this allocator back to a saved position.
+   *
+   * **Slots between the saved `highWater` and the current one are cleared rather than left**, and
+   * that is the whole difference between a restore and a partial one. An entity created after the
+   * save has a live slot the save knows nothing about; leaving it live would leave an entity in the
+   * world that the snapshot says does not exist, and its handle would keep answering `alive`.
+   */
+  loadFrom(slot: AllocatorSnapshot): void {
+    this.grow(slot.highWater);
+    for (let i = 0; i < slot.highWater; i++) {
+      this.generations[i] = slot.generations[i] as number;
+      this.live[i] = slot.live[i] as number;
+    }
+    for (let i = slot.highWater; i < this.highWater; i++) {
+      this.generations[i] = 0;
+      this.live[i] = 0;
+    }
+
+    this.free.length = 0;
+    for (let i = 0; i < slot.freeCount; i++) this.free.push(slot.free[i] as number);
+
+    this.highWater = slot.highWater;
+    this.alive_ = slot.aliveCount;
+  }
+
+  private grow(needed: number): void {
+    if (needed <= this.generations.length) return;
+    let size = this.generations.length;
+    while (size < needed) size *= 2;
+    const generations = new Uint32Array(size);
+    generations.set(this.generations);
+    this.generations = generations;
+    const live = new Uint8Array(size);
+    live.set(this.live);
+    this.live = live;
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/*! 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/src/prefab.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 function definePrefab(
+  name: string,
+  components: readonly (readonly [ComponentType, Readonly<Record<string, unknown>>])[],
+): Prefab {
+  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: World,
+  prefab: Prefab,
+  overrides: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {},
+): Entity {
+  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: Readonly<Record<string, unknown>>,
+  override: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...values };
+  for (const key of Object.keys(override)) {
+    const value = override[key];
+    if (value !== undefined) merged[key] = value;
+  }
+  return merged;
+}

package/src/query.ts

@@ -0,0 +1,184 @@
+/**
+ * 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;
+}
+
+/** What `next` hands back. One object, rewritten — see the header. */
+interface Step {
+  value: Entity;
+  done: boolean;
+}
+
+export 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: ComponentStore[] = [];
+  private requiredCount = 0;
+  /** Stores no yielded entity may be in. Same arrangement, same reason. */
+  private readonly excluded: ComponentStore[] = [];
+  private excludedCount = 0;
+  private walking: ComponentStore | null = null;
+  private at = 0;
+  private readonly step: Step = { value: 0, done: false };
+  private host: CursorHost | null = null;
+  private open_ = false;
+
+  constructor(host: CursorHost) {
+    this.host = host;
+    this.owner = host;
+  }
+
+  private readonly owner: CursorHost;
+
+  /**
+   * 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 {
+    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: ComponentType): this {
+    this.require(type);
+    return this;
+  }
+
+  /** Exclude everything that has this component. */
+  without(type: ComponentType): this {
+    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;
+  }
+
+  private require(type: ComponentType): void {
+    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](): Iterator<Entity> {
+    /*
+     * 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(): IteratorResult<Entity> {
+    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] as Entity;
+      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(): IteratorResult<Entity> {
+    return this.finish();
+  }
+
+  private matches(entity: Entity, walking: ComponentStore): boolean {
+    for (let i = 0; i < this.requiredCount; i += 1) {
+      const store = this.required[i] as ComponentStore;
+      if (store !== walking && !store.has(entity)) return false;
+    }
+    for (let i = 0; i < this.excludedCount; i += 1) {
+      if ((this.excluded[i] as ComponentStore).has(entity)) return false;
+    }
+    return true;
+  }
+
+  private chooseSmallest(): void {
+    let smallest: ComponentStore | null = null;
+    for (let i = 0; i < this.requiredCount; i += 1) {
+      const store = this.required[i] as ComponentStore;
+      if (smallest === null || store.size < smallest.size) smallest = store;
+    }
+    this.walking = smallest;
+  }
+
+  private finish(): IteratorResult<Entity> {
+    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;
+  }
+}