@aethervtt/shard-core 0.0.1

package/dist/ecs/world.js

@@ -0,0 +1,513 @@
+import { ShardError } from "../error.js";
+import { Registry } from "../schema/registry.js";
+import { formatEntity, MAX_ENTITIES, makeEntity } from "./entity.js";
+import { EventQueue, EventReader } from "./events.js";
+import { ChildOf, Children } from "./hierarchy.js";
+import {
+  ObserverTable,
+  onAdd,
+  onRemove,
+  onSet
+} from "./observers.js";
+import { Query, queryKey } from "./query.js";
+import { Table } from "./table.js";
+const FREE = 4294967295;
+const PENDING = 4294967294;
+const MAX_GENERATION = 2147483647;
+const byId = (a, b) => a.id - b.id;
+class World {
+  /** Change-detection clock. The scheduler advances it once per system run. */
+  tick = 1;
+  registry = new Registry();
+  generations = new Uint32Array(1024);
+  tableOf = new Uint32Array(1024).fill(FREE);
+  rowOf = new Uint32Array(1024);
+  nextIndex = 0;
+  freeIndices = [];
+  aliveCount = 0;
+  tables = [];
+  tableByKey = /* @__PURE__ */ new Map();
+  emptyTable;
+  queries = /* @__PURE__ */ new Map();
+  resources = /* @__PURE__ */ new Map();
+  eventQueues = /* @__PURE__ */ new Map();
+  observers = new ObserverTable();
+  registered = [];
+  constructor() {
+    this.emptyTable = this.getOrCreateTable([]);
+    this.installHierarchy();
+  }
+  incrementTick() {
+    return ++this.tick;
+  }
+  // --- entities --------------------------------------------------------------
+  spawn(...inits) {
+    const entity = this.allocate();
+    this.insert(entity, inits);
+    return entity;
+  }
+  /** Allocates an id that comes alive later via `spawnReserved`. Used by `Commands.spawn`. */
+  reserveEntity() {
+    return this.allocate();
+  }
+  spawnReserved(entity, inits) {
+    const index = entity % MAX_ENTITIES;
+    if (index >= this.nextIndex || this.tableOf[index] !== PENDING || this.generations[index] !== Math.floor(entity / MAX_ENTITIES)) {
+      throw new ShardError("ecs/dead-entity", `Entity ${formatEntity(entity)} is not reserved`);
+    }
+    this.insert(entity, inits);
+  }
+  isAlive(entity) {
+    if (!Number.isInteger(entity) || entity < 0) return false;
+    const index = entity % MAX_ENTITIES;
+    if (index >= this.nextIndex || this.tableOf[index] >= PENDING) return false;
+    return this.generations[index] === Math.floor(entity / MAX_ENTITIES);
+  }
+  get entityCount() {
+    return this.aliveCount;
+  }
+  /** Despawns the entity and, if it has children, all of its descendants. */
+  despawn(entity) {
+    this.locate(entity);
+    const children = this.tryGet(entity, Children);
+    if (children) {
+      for (const child of children.entities) {
+        if (child !== null && this.isAlive(child)) this.despawn(child);
+      }
+    }
+    this.despawnSingle(entity);
+  }
+  /** Despawns only this entity. Its children lose their `ChildOf` and become roots. */
+  despawnSingle(entity) {
+    this.locate(entity);
+    const children = this.tryGet(entity, Children);
+    if (children) {
+      for (const child of children.entities) {
+        if (child !== null && this.isAlive(child)) this.remove(child, ChildOf);
+      }
+    }
+    let index = this.locate(entity);
+    const components = this.tables[this.tableOf[index]].components;
+    for (const def of components) {
+      this.fire("remove", entity, def, void 0);
+      if (!this.isAlive(entity)) return;
+    }
+    index = this.locate(entity);
+    const table = this.tables[this.tableOf[index]];
+    const moved = table.removeRow(this.rowOf[index]);
+    if (moved !== -1) this.rowOf[moved % MAX_ENTITIES] = this.rowOf[index];
+    this.generations[index] = this.generations[index] + 1 & MAX_GENERATION;
+    this.tableOf[index] = FREE;
+    this.freeIndices.push(index);
+    this.aliveCount--;
+  }
+  // --- components ------------------------------------------------------------
+  /** Adds a component (defaults for missing fields). If present, replaces it and fires `onSet`. */
+  add(entity, component, value) {
+    const def = component;
+    const index = this.locate(entity);
+    this.ensureRegistered(def);
+    const table = this.tables[this.tableOf[index]];
+    const row = this.rowOf[index];
+    const init = value;
+    if (table.has(def)) {
+      const previous = this.hasObservers("set", def) ? table.readComponent(def, row) : void 0;
+      const added2 = table.addedTicks(def)[row];
+      table.initComponent(def, row, init);
+      table.addedTicks(def)[row] = added2;
+      this.fire("set", entity, def, previous);
+      return;
+    }
+    const target = this.tableWith(table, def);
+    const newRow = this.moveEntity(index, table, row, target);
+    target.initComponent(def, newRow, init);
+    const added = target.components;
+    for (let i = 0; i < added.length; i++) {
+      const c = added[i];
+      if (c !== def && !table.has(c)) target.initComponent(c, newRow, void 0);
+    }
+    this.fire("add", entity, def, void 0);
+    for (let i = 0; i < added.length; i++) {
+      const c = added[i];
+      if (c !== def && !table.has(c)) this.fire("add", entity, c, void 0);
+    }
+  }
+  /** Removes a component. Returns false if the entity didn't have it. */
+  remove(entity, component) {
+    let index = this.locate(entity);
+    if (!this.tables[this.tableOf[index]].has(component)) return false;
+    this.fire("remove", entity, component, void 0);
+    index = this.locate(entity);
+    const table = this.tables[this.tableOf[index]];
+    if (!table.has(component)) return true;
+    this.moveEntity(index, table, this.rowOf[index], this.tableWithout(table, component));
+    return true;
+  }
+  has(entity, component) {
+    if (!this.isAlive(entity)) return false;
+    return this.tables[this.tableOf[entity % MAX_ENTITIES]].has(component);
+  }
+  /** A copy of the component's value. Cold path: allocates. */
+  get(entity, component) {
+    const index = this.locate(entity);
+    const table = this.tables[this.tableOf[index]];
+    if (!table.has(component)) throw missingComponent(entity, component.name);
+    return table.readComponent(component, this.rowOf[index]);
+  }
+  tryGet(entity, component) {
+    if (!this.has(entity, component)) return void 0;
+    const index = entity % MAX_ENTITIES;
+    return this.tables[this.tableOf[index]].readComponent(component, this.rowOf[index]);
+  }
+  /** Writes the given fields and marks the component changed. */
+  set(entity, component, values) {
+    const def = component;
+    const index = this.locate(entity);
+    const table = this.tables[this.tableOf[index]];
+    if (!table.has(def)) throw missingComponent(entity, def.name);
+    const row = this.rowOf[index];
+    const previous = this.hasObservers("set", def) ? table.readComponent(def, row) : void 0;
+    table.writeComponent(def, row, values);
+    this.fire("set", entity, def, previous);
+  }
+  /** The table holding the entity's components. For system code that walks relationships. */
+  entityTable(entity) {
+    return this.tables[this.tableOf[this.locate(entity)]];
+  }
+  /** The entity's row in its table. Valid until the next structural change. */
+  entityRow(entity) {
+    return this.rowOf[this.locate(entity)];
+  }
+  /**
+   * Like `entityTable` / `entityRow` but without the liveness check, for hot relationship walks
+   * where the caller already knows the entity is alive (e.g. entries of a `Children` list).
+   */
+  entityTableUnchecked(entity) {
+    return this.tables[this.tableOf[entity % MAX_ENTITIES]];
+  }
+  entityRowUnchecked(entity) {
+    return this.rowOf[entity % MAX_ENTITIES];
+  }
+  componentsOf(entity) {
+    return this.tables[this.tableOf[this.locate(entity)]].components;
+  }
+  // --- queries ---------------------------------------------------------------
+  /** Returns a cached query; the same descriptor always gives the same `Query`. */
+  query(desc) {
+    const key = queryKey(desc);
+    let query = this.queries.get(key);
+    if (!query) {
+      query = new Query(desc);
+      for (const def of query.with) this.ensureRegistered(def);
+      for (const table of this.tables) query.consider(table);
+      this.queries.set(key, query);
+    }
+    return query;
+  }
+  // --- resources -------------------------------------------------------------
+  insertResource(def, value) {
+    this.registry.register(def);
+    this.resources.set(def.id, value);
+  }
+  /** Inserts the resource from its `init` if it isn't present yet, and returns it. */
+  initResource(def) {
+    if (!this.resources.has(def.id)) {
+      if (!def.init) {
+        throw new ShardError(
+          "ecs/no-resource-init",
+          `Resource "${def.name}" has no init function`,
+          {
+            hint: "Use insertResource with a value instead."
+          }
+        );
+      }
+      this.insertResource(def, def.init());
+    }
+    return this.resources.get(def.id);
+  }
+  resource(def) {
+    if (!this.resources.has(def.id)) {
+      throw new ShardError("ecs/missing-resource", `Resource "${def.name}" is not in the world`, {
+        hint: "Insert it with insertResource, or add the plugin that provides it."
+      });
+    }
+    return this.resources.get(def.id);
+  }
+  tryResource(def) {
+    return this.resources.get(def.id);
+  }
+  hasResource(def) {
+    return this.resources.has(def.id);
+  }
+  removeResource(def) {
+    return this.resources.delete(def.id);
+  }
+  // --- events ----------------------------------------------------------------
+  send(def, ...data) {
+    this.eventQueue(def).send(data[0]);
+  }
+  reader(def) {
+    return new EventReader(this.eventQueue(def));
+  }
+  /** Advances every event queue by one frame. Called by the app at the start of each frame. */
+  updateEvents() {
+    for (const queue of this.eventQueues.values()) queue.update();
+  }
+  eventQueue(def) {
+    let queue = this.eventQueues.get(def.id);
+    if (!queue) {
+      this.registry.register(def);
+      queue = new EventQueue(def);
+      this.eventQueues.set(def.id, queue);
+    }
+    return queue;
+  }
+  observe(target, fn) {
+    let lists;
+    let id;
+    if (target.kind === "event") {
+      this.registry.register(target);
+      lists = this.observers.custom;
+      id = target.id;
+    } else {
+      this.ensureRegistered(target.component);
+      lists = this.observers.listFor(target.kind);
+      id = target.component.id;
+    }
+    let list = lists[id];
+    if (!list) {
+      list = [];
+      lists[id] = list;
+    }
+    list.push(fn);
+    return () => {
+      const i = list.indexOf(fn);
+      if (i !== -1) list.splice(i, 1);
+    };
+  }
+  /** Runs observers registered for `event`, synchronously. */
+  trigger(event, data, entity) {
+    const list = this.observers.custom[event.id];
+    if (!list || list.length === 0) return;
+    const payload = { event, data, entity, world: this };
+    for (const fn of list.slice()) fn(payload);
+  }
+  // --- introspection ---------------------------------------------------------
+  stats() {
+    return {
+      entities: this.aliveCount,
+      archetypes: this.tables.length,
+      tables: this.tables.map((t) => ({
+        components: t.components.map((c) => c.name),
+        count: t.count,
+        capacity: t.capacity,
+        bytes: t.bytes()
+      }))
+    };
+  }
+  /** All archetype tables, including empty ones. */
+  allTables() {
+    return this.tables;
+  }
+  // --- internals -------------------------------------------------------------
+  allocate() {
+    let index = this.freeIndices.pop();
+    if (index === void 0) {
+      if (this.nextIndex >= MAX_ENTITIES) {
+        throw new ShardError("ecs/entity-limit", `Cannot exceed ${MAX_ENTITIES} live entities`, {
+          hint: "High-count data (particles, foliage, tiles) belongs in buffers, not entities."
+        });
+      }
+      index = this.nextIndex++;
+      if (index >= this.generations.length) this.growIndex();
+    }
+    this.tableOf[index] = PENDING;
+    return makeEntity(index, this.generations[index]);
+  }
+  growIndex() {
+    const size = Math.min(this.generations.length * 2, MAX_ENTITIES);
+    const generations = new Uint32Array(size);
+    generations.set(this.generations);
+    const tableOf = new Uint32Array(size).fill(FREE);
+    tableOf.set(this.tableOf);
+    const rowOf = new Uint32Array(size);
+    rowOf.set(this.rowOf);
+    this.generations = generations;
+    this.tableOf = tableOf;
+    this.rowOf = rowOf;
+  }
+  /** Returns the entity's index, or throws if it isn't alive. */
+  locate(entity) {
+    if (!this.isAlive(entity)) {
+      throw new ShardError("ecs/dead-entity", `Entity ${formatEntity(entity)} is not alive`, {
+        hint: "It was despawned, or the id is stale. Check world.isAlive(entity) first."
+      });
+    }
+    return entity % MAX_ENTITIES;
+  }
+  insert(entity, inits) {
+    let table = this.emptyTable;
+    for (let i = 0; i < inits.length; i++) {
+      const init = inits[i];
+      const def = Array.isArray(init) ? init[0] : init;
+      this.ensureRegistered(def);
+      table = this.tableWith(table, def);
+    }
+    const row = table.pushRow(entity);
+    const index = entity % MAX_ENTITIES;
+    this.tableOf[index] = table.id;
+    this.rowOf[index] = row;
+    this.aliveCount++;
+    const components = table.components;
+    for (let c = 0; c < components.length; c++) {
+      if (!initsInclude(inits, components[c])) table.initComponent(components[c], row, void 0);
+    }
+    for (let i = 0; i < inits.length; i++) {
+      const init = inits[i];
+      if (Array.isArray(init)) table.initComponent(init[0], row, init[1]);
+      else table.initComponent(init, row, void 0);
+    }
+    for (let c = 0; c < components.length; c++) this.fire("add", entity, components[c], void 0);
+  }
+  moveEntity(index, from, row, to) {
+    const entity = from.entities[row];
+    const newRow = to.pushRow(entity);
+    from.copySharedTo(row, to, newRow);
+    const moved = from.removeRow(row);
+    if (moved !== -1) this.rowOf[moved % MAX_ENTITIES] = row;
+    this.tableOf[index] = to.id;
+    this.rowOf[index] = newRow;
+    return newRow;
+  }
+  /** The archetype with `def` and everything `def` requires (transitively) added. Cached. */
+  tableWith(table, def) {
+    let next = table.addEdges.get(def.id);
+    if (next) return next;
+    const components = [...table.components];
+    const stack = [def];
+    while (stack.length > 0) {
+      const c = stack.pop();
+      if (components.some((x) => x.id === c.id)) continue;
+      this.ensureRegistered(c);
+      components.push(c);
+      stack.push(...c.requires);
+    }
+    next = components.length === table.components.length ? table : this.getOrCreateTable(components.sort(byId));
+    table.addEdges.set(def.id, next);
+    return next;
+  }
+  tableWithout(table, def) {
+    let next = table.removeEdges.get(def.id);
+    if (next) return next;
+    next = table.has(def) ? this.getOrCreateTable(table.components.filter((c) => c.id !== def.id)) : table;
+    table.removeEdges.set(def.id, next);
+    return next;
+  }
+  /**
+   * Hot reload: replaces a definition with one that reuses its id. Components keep their storage
+   * when `migrate` is omitted (same layout); otherwise every row is rebuilt through `migrate`.
+   * Resources and events keep their values and queues.
+   */
+  redefine(def, migrate) {
+    if (this.registry.get(def.name) || this.registered[def.id]) this.registry.replace(def);
+    if (def.kind !== "component") return;
+    for (const table of this.tables) {
+      table.addEdges.clear();
+      if (!table.hasId(def.id)) continue;
+      table.redefine(
+        def,
+        migrate && ((value, row) => migrate(value, table.entities[row]))
+      );
+    }
+  }
+  getOrCreateTable(components) {
+    const key = components.map((c) => c.id).join(",");
+    let table = this.tableByKey.get(key);
+    if (!table) {
+      table = new Table(this.tables.length, components, this);
+      this.tables.push(table);
+      this.tableByKey.set(key, table);
+      for (const query of this.queries.values()) query.consider(table);
+    }
+    return table;
+  }
+  ensureRegistered(def) {
+    if (this.registered[def.id]) return;
+    this.registry.register(def);
+    this.registered[def.id] = true;
+  }
+  hasObservers(kind, def) {
+    const list = this.observers.listFor(kind)[def.id];
+    return list !== void 0 && list.length > 0;
+  }
+  fire(kind, entity, def, previous) {
+    const list = this.observers.listFor(kind)[def.id];
+    if (!list || list.length === 0) return;
+    const event = { kind, entity, component: def, world: this, previous };
+    for (const fn of list.slice()) fn(event);
+  }
+  /** Keeps `Children` in sync with `ChildOf`. */
+  installHierarchy() {
+    this.observe(onAdd(ChildOf), ({ entity }) => {
+      const { parent } = this.get(entity, ChildOf);
+      if (parent !== null) this.addChild(parent, entity);
+    });
+    this.observe(onSet(ChildOf), ({ entity, previous }) => {
+      const before = previous?.parent ?? null;
+      const { parent } = this.get(entity, ChildOf);
+      if (before === parent) return;
+      if (before !== null && this.isAlive(before)) this.removeChild(before, entity);
+      if (parent !== null) this.addChild(parent, entity);
+    });
+    this.observe(onRemove(ChildOf), ({ entity }) => {
+      const { parent } = this.get(entity, ChildOf);
+      if (parent !== null && this.isAlive(parent)) this.removeChild(parent, entity);
+    });
+  }
+  childList(parent) {
+    const index = this.locate(parent);
+    const table = this.tables[this.tableOf[index]];
+    if (!table.has(Children)) return void 0;
+    return table.column(Children, "entities")[this.rowOf[index]];
+  }
+  addChild(parent, child) {
+    const list = this.childList(parent);
+    if (!list) {
+      this.add(parent, Children, { entities: [child] });
+      return;
+    }
+    if (!list.includes(child)) list.push(child);
+    const index = parent % MAX_ENTITIES;
+    this.tables[this.tableOf[index]].markChanged(Children, this.rowOf[index]);
+  }
+  removeChild(parent, child) {
+    const list = this.childList(parent);
+    if (!list) return;
+    const i = list.indexOf(child);
+    if (i === -1) return;
+    list.splice(i, 1);
+    if (list.length === 0) {
+      this.remove(parent, Children);
+      return;
+    }
+    const index = parent % MAX_ENTITIES;
+    this.tables[this.tableOf[index]].markChanged(Children, this.rowOf[index]);
+  }
+}
+function initsInclude(inits, def) {
+  for (let i = 0; i < inits.length; i++) {
+    const init = inits[i];
+    if ((Array.isArray(init) ? init[0] : init) === def) return true;
+  }
+  return false;
+}
+function missingComponent(entity, name) {
+  return new ShardError(
+    "ecs/missing-component",
+    `Entity ${formatEntity(entity)} has no "${name}" component`,
+    { hint: "Check world.has(entity, component) first, or use tryGet." }
+  );
+}
+export {
+  World
+};

package/dist/error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structured engine error. Agents read `code` and `hint`; humans read `message`.
+ * Codes are namespaced by package, e.g. `gpu/unsupported`, `platform/fs-read-only`.
+ */
+export declare class ShardError extends Error {
+    readonly name = "ShardError";
+    readonly code: string;
+    readonly hint: string | undefined;
+    /** Location of the problem: a file path, an entity path, a JSON pointer. */
+    readonly path: string | undefined;
+    /** Related errors, e.g. every problem found when validating a whole file. */
+    readonly details: readonly ShardError[] | undefined;
+    constructor(code: string, message: string, options?: {
+        hint?: string;
+        path?: string;
+        cause?: unknown;
+        details?: readonly ShardError[];
+    });
+    toJSON(): {
+        code: string;
+        message: string;
+        hint?: string;
+        path?: string;
+        details?: unknown[];
+    };
+}

package/dist/error.js

@@ -0,0 +1,29 @@
+class ShardError extends Error {
+  name = "ShardError";
+  code;
+  hint;
+  /** Location of the problem: a file path, an entity path, a JSON pointer. */
+  path;
+  /** Related errors, e.g. every problem found when validating a whole file. */
+  details;
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.code = code;
+    this.hint = options.hint;
+    this.path = options.path;
+    this.details = options.details;
+  }
+  toJSON() {
+    const out = {
+      code: this.code,
+      message: this.message
+    };
+    if (this.hint !== void 0) out.hint = this.hint;
+    if (this.path !== void 0) out.path = this.path;
+    if (this.details) out.details = this.details.map((d) => d.toJSON());
+    return out;
+  }
+}
+export {
+  ShardError
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './ecs/index.js';
+export { ShardError } from './error.js';
+export * from './json.js';
+export * from './math/index.js';
+export * from './scheduler/index.js';
+export * from './schema/index.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./ecs/index.js";
+import { ShardError } from "./error.js";
+export * from "./json.js";
+export * from "./math/index.js";
+export * from "./scheduler/index.js";
+export * from "./schema/index.js";
+export {
+  ShardError
+};

package/dist/json.d.ts

@@ -0,0 +1,15 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** A JSON Schema document. Kept loose; we only produce these. */
+export type JsonSchema = {
+    [key: string]: unknown;
+};
+/** Appends one segment to a JSON pointer, escaping `~` and `/`. */
+export declare function pointer(base: string, key: string | number): string;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Deep copy of JSON-like data (arrays and plain objects). Other values are returned as-is. */
+export declare function cloneData<T>(value: T): T;

package/dist/json.js

@@ -0,0 +1,22 @@
+function pointer(base, key) {
+  return `${base}/${String(key).replace(/~/g, "~0").replace(/\//g, "~1")}`;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function cloneData(value) {
+  if (Array.isArray(value)) return value.map(cloneData);
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const key in value) out[key] = cloneData(value[key]);
+    return out;
+  }
+  return value;
+}
+export {
+  cloneData,
+  isPlainObject,
+  pointer
+};

package/dist/math/aabb.d.ts

@@ -0,0 +1,13 @@
+import type { Readable, Writable } from './types.js';
+/** Axis-aligned box as 6 floats: `[minX, minY, minZ, maxX, maxY, maxZ]`. */
+export declare const create: () => Float32Array;
+/** An inverted box that any point expands. */
+export declare function empty<T extends Writable>(out: T): T;
+export declare function set<T extends Writable>(out: T, min: Readable, max: Readable): T;
+/** Bounds of packed xyz positions. */
+export declare function fromPoints<T extends Writable>(out: T, positions: Readable, stride?: number): T;
+/** Bounds of `box` after an affine transform (Arvo's method: exact for the transformed box). */
+export declare function transformAffineAt<T extends Writable>(out: T, box: Readable, m: Readable, mo: number): T;
+export declare function center<T extends Writable>(out: T, box: Readable): T;
+export declare function intersects(a: Readable, b: Readable): boolean;
+export declare function containsPoint(box: Readable, p: Readable): boolean;