@driftengine/entities 3.61.0

package/src/system.ts

@@ -0,0 +1,208 @@
+/**
+ * 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 class BoundSystem implements SystemView {
+  readonly definition: SystemDefinition;
+  private readonly world: World;
+  private readonly readable = new Set<number>();
+  private readonly writable = new Set<number>();
+  /** Entities to destroy after this system returns. Reused, drained with a count. */
+  private readonly pendingDestroy: Entity[] = [];
+  private destroyCount = 0;
+  private readonly pendingRemoveEntity: Entity[] = [];
+  private readonly pendingRemoveType: ComponentType[] = [];
+  private removeCount = 0;
+
+  constructor(world: World, definition: SystemDefinition) {
+    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(): void {
+    this.definition.run(this);
+    this.drain();
+  }
+
+  query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor {
+    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: ComponentType, forWriting: boolean): ComponentView {
+    if (forWriting) this.requireWritable(type);
+    else this.requireReadable(type);
+    return this.world.view(type);
+  }
+
+  read(entity: Entity, type: ComponentType, field: string): unknown {
+    this.requireReadable(type);
+    return this.world.read(entity, type, field);
+  }
+
+  write(entity: Entity, type: ComponentType, field: string, value: unknown): void {
+    this.requireWritable(type);
+    this.world.write(entity, type, field, value);
+  }
+
+  has(entity: Entity, type: ComponentType): boolean {
+    this.requireReadable(type);
+    return this.world.has(entity, type);
+  }
+
+  create(): Entity {
+    return this.world.create();
+  }
+
+  add(entity: Entity, type: ComponentType, values: Readonly<Record<string, unknown>> = {}): void {
+    this.requireWritable(type);
+    this.world.add(entity, type, values);
+  }
+
+  destroy(entity: Entity): void {
+    if (this.destroyCount < this.pendingDestroy.length)
+      this.pendingDestroy[this.destroyCount] = entity;
+    else this.pendingDestroy.push(entity);
+    this.destroyCount += 1;
+  }
+
+  remove(entity: Entity, type: ComponentType): void {
+    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`. */
+  private drain(): void {
+    for (let i = 0; i < this.removeCount; i += 1) {
+      this.world.remove(
+        this.pendingRemoveEntity[i] as Entity,
+        this.pendingRemoveType[i] as ComponentType,
+      );
+    }
+    this.removeCount = 0;
+    for (let i = 0; i < this.destroyCount; i += 1)
+      this.world.destroy(this.pendingDestroy[i] as Entity);
+    this.destroyCount = 0;
+  }
+
+  private requireReadable(type: ComponentType): void {
+    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.',
+    );
+  }
+
+  private requireWritable(type: ComponentType): void {
+    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.',
+    );
+  }
+}

package/src/view.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 function refreshView(
+  view: ComponentView,
+  sparse: Int32Array,
+  columns: ReadonlyMap<string, ViewColumn>,
+): void {
+  view.sparse = sparse;
+  for (const [field, column] of columns) view[field] = column;
+}

package/src/world.ts

@@ -0,0 +1,223 @@
+/**
+ * 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,
+  EntityAllocator,
+  type EntityAllocatorOptions,
+  createAllocatorSnapshot,
+} from './entity.ts';
+import { type CursorHost, QueryCursor } from './query.ts';
+import {
+  ComponentStore,
+  type ComponentType,
+  type StoreSnapshot,
+  createStoreSnapshot,
+} 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 function createWorldSnapshot(): WorldSnapshot {
+  return { allocator: createAllocatorSnapshot(), stores: new Map() };
+}
+
+export class World implements CursorHost {
+  private readonly entities: EntityAllocator;
+  private readonly stores = new Map<number, ComponentStore>();
+  /**
+   * 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: QueryCursor[] = [];
+  private inUse = 0;
+
+  constructor(options: EntityAllocatorOptions = {}) {
+    this.entities = new EntityAllocator(options);
+  }
+
+  get liveCount(): number {
+    return this.entities.liveCount;
+  }
+
+  /** How many cursors are inside a loop. For a consumer looking at a leak rather than inferring one. */
+  get cursorsInUse(): number {
+    return this.inUse;
+  }
+
+  create(): Entity {
+    return this.entities.create();
+  }
+
+  alive(entity: Entity): boolean {
+    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: Entity): boolean {
+    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: ComponentType): ComponentStore {
+    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: ComponentType): ComponentView {
+    return this.store(type).view();
+  }
+
+  add(entity: Entity, type: ComponentType, values: Readonly<Record<string, unknown>> = {}): void {
+    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: Entity, type: ComponentType): boolean {
+    return this.store(type).remove(entity);
+  }
+
+  has(entity: Entity, type: ComponentType): boolean {
+    return this.store(type).has(entity);
+  }
+
+  read(entity: Entity, type: ComponentType, field: string): unknown {
+    return this.store(type).read(entity, field);
+  }
+
+  write(entity: Entity, type: ComponentType, field: string, value: unknown): void {
+    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: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor {
+    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: QueryCursor): void {
+    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: WorldSnapshot): void {
+    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: WorldSnapshot): void {
+    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: StoreSnapshot = createStoreSnapshot();