@aethervtt/shard-core 0.0.1

package/dist/ecs/table.js

@@ -0,0 +1,286 @@
+const TYPED = {
+  f32: Float32Array,
+  f64: Float64Array,
+  i8: Int8Array,
+  i16: Int16Array,
+  i32: Int32Array,
+  u8: Uint8Array,
+  u16: Uint16Array,
+  u32: Uint32Array
+};
+function createColumn(storage, length) {
+  return storage === "object" ? new Array(length) : new TYPED[storage](length);
+}
+function growColumn(column, storage, length) {
+  if (storage === "object") return column;
+  const next = new TYPED[storage](length);
+  next.set(column);
+  return next;
+}
+function growTicks(ticks, length) {
+  const next = new Uint32Array(length);
+  next.set(ticks);
+  return next;
+}
+class ComponentStorage {
+  columns;
+  /** Columns by field name. Same arrays as `columns`. */
+  byName = /* @__PURE__ */ Object.create(null);
+  added;
+  changed;
+  /** The newest tick in `changed`, so a system can skip a table where nothing changed. */
+  lastChanged = 0;
+  def;
+  constructor(def, capacity) {
+    this.def = def;
+    this.columns = def.layout.map((c) => createColumn(c.storage, capacity * c.stride));
+    this.reindex();
+    this.added = new Uint32Array(capacity);
+    this.changed = new Uint32Array(capacity);
+  }
+  grow(capacity) {
+    const layout = this.def.layout;
+    for (let i = 0; i < layout.length; i++) {
+      const c = layout[i];
+      this.columns[i] = growColumn(this.columns[i], c.storage, capacity * c.stride);
+    }
+    this.reindex();
+    this.added = growTicks(this.added, capacity);
+    this.changed = growTicks(this.changed, capacity);
+  }
+  reindex() {
+    const layout = this.def.layout;
+    for (let i = 0; i < layout.length; i++) this.byName[layout[i].name] = this.columns[i];
+  }
+}
+class Table {
+  count = 0;
+  capacity;
+  entities;
+  /** Component ids in this archetype, sorted. */
+  ids;
+  storages;
+  /** Cached archetype transitions: component id → table with it added / removed. */
+  addEdges = /* @__PURE__ */ new Map();
+  removeEdges = /* @__PURE__ */ new Map();
+  idSet;
+  byId = /* @__PURE__ */ new Map();
+  id;
+  /**
+   * The tick a row last moved in or out. Rows that move in keep their change ticks, so "nothing
+   * changed" needs this too.
+   */
+  lastStructural = 0;
+  components;
+  clock;
+  constructor(id, components, clock, capacity = 16) {
+    this.id = id;
+    this.components = components;
+    this.clock = clock;
+    this.capacity = capacity;
+    this.entities = new Float64Array(capacity);
+    this.ids = components.map((c) => c.id);
+    this.idSet = new Set(this.ids);
+    this.storages = components.map((def) => {
+      const storage = new ComponentStorage(def, capacity);
+      this.byId.set(def.id, storage);
+      return storage;
+    });
+  }
+  has(def) {
+    return this.idSet.has(def.id);
+  }
+  hasId(id) {
+    return this.idSet.has(id);
+  }
+  storage(def) {
+    return this.byId.get(def.id);
+  }
+  /**
+   * The raw column for one field. Numeric fields are TypedArrays with `stride` values per row
+   * (a vec3 at row `i` is at `[i * 3]`, `[i * 3 + 1]`, `[i * 3 + 2]`).
+   */
+  column(def, field) {
+    return this.byId.get(def.id).byName[field];
+  }
+  addedTicks(def) {
+    return this.byId.get(def.id).added;
+  }
+  changedTicks(def) {
+    return this.byId.get(def.id).changed;
+  }
+  /** Marks one row, or every row, as changed at the current tick. */
+  markChanged(def, row) {
+    const storage = this.byId.get(def.id);
+    const tick = this.clock.tick;
+    if (row === void 0) storage.changed.fill(tick, 0, this.count);
+    else storage.changed[row] = tick;
+    storage.lastChanged = tick;
+  }
+  /**
+   * The newest change tick of any row of `def`: when it's not after `since`, no row changed. Code
+   * that writes `changedTicks()` directly must call `touch` too.
+   */
+  lastChanged(def) {
+    return this.byId.get(def.id).lastChanged;
+  }
+  /** Records that rows of `def` changed this tick, after writing `changedTicks()` directly. */
+  touch(def) {
+    this.byId.get(def.id).lastChanged = this.clock.tick;
+  }
+  isAdded(def, row, since) {
+    return this.byId.get(def.id).added[row] > since;
+  }
+  isChanged(def, row, since) {
+    return this.byId.get(def.id).changed[row] > since;
+  }
+  // --- structural operations (used by the world) ----------------------------
+  pushRow(entity) {
+    if (this.count === this.capacity) this.grow(this.capacity * 2);
+    this.lastStructural = this.clock.tick;
+    const row = this.count++;
+    this.entities[row] = entity;
+    return row;
+  }
+  /** Swap-removes a row. Returns the entity moved into `row`, or -1 if it was the last row. */
+  removeRow(row) {
+    this.lastStructural = this.clock.tick;
+    const last = --this.count;
+    const storages = this.storages;
+    if (row === last) {
+      for (let s = 0; s < storages.length; s++) {
+        const storage = storages[s];
+        const layout = storage.def.layout;
+        for (let c = 0; c < layout.length; c++) {
+          if (layout[c].storage === "object") storage.columns[c][last] = void 0;
+        }
+      }
+      return -1;
+    }
+    const moved = this.entities[last];
+    this.entities[row] = moved;
+    for (let s = 0; s < storages.length; s++) {
+      const storage = storages[s];
+      copyRow(storage, last, storage, row);
+      const layout = storage.def.layout;
+      for (let c = 0; c < layout.length; c++) {
+        if (layout[c].storage === "object") storage.columns[c][last] = void 0;
+      }
+    }
+    return moved;
+  }
+  /** Copies the components both tables share from `row` here into `targetRow` there. */
+  copySharedTo(row, target, targetRow) {
+    const storages = this.storages;
+    for (let s = 0; s < storages.length; s++) {
+      const from = storages[s];
+      const to = target.byId.get(from.def.id);
+      if (to) copyRow(from, row, to, targetRow);
+    }
+  }
+  /** Writes a full component value; fields missing from `init` take their defaults. */
+  initComponent(def, row, init) {
+    const storage = this.byId.get(def.id);
+    const layout = def.layout;
+    for (let c = 0; c < layout.length; c++) {
+      const { name, field } = layout[c];
+      const value = init?.[name];
+      field.write(storage.columns[c], row, value === void 0 ? field.defaultValue() : value);
+    }
+    const tick = this.clock.tick;
+    storage.added[row] = tick;
+    storage.changed[row] = tick;
+    storage.lastChanged = tick;
+  }
+  /** Writes only the fields present in `values`. */
+  writeComponent(def, row, values) {
+    const storage = this.byId.get(def.id);
+    const layout = def.layout;
+    for (let c = 0; c < layout.length; c++) {
+      const { name, field } = layout[c];
+      const value = values[name];
+      if (value !== void 0) field.write(storage.columns[c], row, value);
+    }
+    storage.changed[row] = this.clock.tick;
+    storage.lastChanged = this.clock.tick;
+  }
+  readComponent(def, row) {
+    const storage = this.byId.get(def.id);
+    const out = {};
+    const layout = def.layout;
+    for (let c = 0; c < layout.length; c++) {
+      const { name, field } = layout[c];
+      out[name] = field.read(storage.columns[c], row);
+    }
+    return out;
+  }
+  /**
+   * Replaces a component's definition with one sharing its id (hot reload). Without `migrate`
+   * the layout must be the same and only the definition changes; with it, every row's value is
+   * rebuilt into new columns. Added ticks carry over; changed ticks become the current tick.
+   */
+  redefine(def, migrate) {
+    const i = this.ids.indexOf(def.id);
+    if (i === -1) return;
+    const old = this.storages[i];
+    this.components[i] = def;
+    if (!migrate) {
+      old.def = def;
+      return;
+    }
+    const values = [];
+    for (let row = 0; row < this.count; row++) {
+      values.push(migrate(this.readComponent(old.def, row), row));
+    }
+    const next = new ComponentStorage(def, this.capacity);
+    next.added.set(old.added);
+    this.storages[i] = next;
+    this.byId.set(def.id, next);
+    const tick = this.clock.tick;
+    for (let row = 0; row < this.count; row++) {
+      this.writeComponent(def, row, values[row]);
+      next.changed[row] = tick;
+    }
+  }
+  /** Approximate bytes used by TypedArray columns (object columns count as 8 bytes a slot). */
+  bytes() {
+    let total = this.entities.byteLength;
+    for (const storage of this.storages) {
+      total += storage.added.byteLength + storage.changed.byteLength;
+      for (const column of storage.columns) {
+        total += Array.isArray(column) ? this.capacity * 8 : column.byteLength;
+      }
+    }
+    return total;
+  }
+  grow(capacity) {
+    const entities = new Float64Array(capacity);
+    entities.set(this.entities);
+    this.entities = entities;
+    for (const storage of this.storages) storage.grow(capacity);
+    this.capacity = capacity;
+  }
+}
+function copyRow(from, fromRow, to, toRow) {
+  const layout = from.def.layout;
+  for (let c = 0; c < layout.length; c++) {
+    const stride = layout[c].stride;
+    const src = from.columns[c];
+    const dst = to.columns[c];
+    if (stride === 1) {
+      dst[toRow] = src[fromRow];
+    } else {
+      const a = fromRow * stride;
+      const b = toRow * stride;
+      for (let i = 0; i < stride; i++) dst[b + i] = src[a + i];
+    }
+  }
+  to.added[toRow] = from.added[fromRow];
+  const changed = from.changed[fromRow];
+  to.changed[toRow] = changed;
+  if (changed > to.lastChanged) to.lastChanged = changed;
+}
+export {
+  ComponentStorage,
+  Table
+};

package/dist/ecs/world.d.ts

@@ -0,0 +1,127 @@
+import type { ComponentDef } from '../schema/component.js';
+import type { Fields, InferFields, InitFields } from '../schema/field.js';
+import { Registry } from '../schema/registry.js';
+import type { EventDef, ResourceDef } from '../schema/resource.js';
+import { type Entity } from './entity.js';
+import { EventReader } from './events.js';
+import { type LifecycleObserver, type LifecycleTrigger, type TriggerObserver } from './observers.js';
+import { Query, type QueryDescriptor } from './query.js';
+import { Table, type TickSource } from './table.js';
+/** A component to spawn/add with: the bare definition (defaults), or `[definition, values]`. */
+export type ComponentInit<F extends Fields = Fields> = ComponentDef<F> | readonly [ComponentDef<F>, InitFields<F>];
+export interface WorldStats {
+    entities: number;
+    archetypes: number;
+    tables: {
+        components: string[];
+        count: number;
+        capacity: number;
+        bytes: number;
+    }[];
+}
+/**
+ * Entities, their components (in archetype tables), resources, events, and observers.
+ *
+ * Direct methods (`spawn`, `add`, `remove`, `despawn`) apply immediately and fire observers
+ * synchronously. Don't call them while iterating a query; record them on `Commands` instead.
+ */
+export declare class World implements TickSource {
+    /** Change-detection clock. The scheduler advances it once per system run. */
+    tick: number;
+    readonly registry: Registry;
+    private generations;
+    private tableOf;
+    private rowOf;
+    private nextIndex;
+    private readonly freeIndices;
+    private aliveCount;
+    private readonly tables;
+    private readonly tableByKey;
+    private readonly emptyTable;
+    private readonly queries;
+    private readonly resources;
+    private readonly eventQueues;
+    private readonly observers;
+    private readonly registered;
+    constructor();
+    incrementTick(): number;
+    spawn<const T extends readonly Fields[]>(...inits: {
+        [K in keyof T]: ComponentInit<T[K]>;
+    }): Entity;
+    /** Allocates an id that comes alive later via `spawnReserved`. Used by `Commands.spawn`. */
+    reserveEntity(): Entity;
+    spawnReserved(entity: Entity, inits: readonly ComponentInit[]): void;
+    isAlive(entity: Entity): boolean;
+    get entityCount(): number;
+    /** Despawns the entity and, if it has children, all of its descendants. */
+    despawn(entity: Entity): void;
+    /** Despawns only this entity. Its children lose their `ChildOf` and become roots. */
+    despawnSingle(entity: Entity): void;
+    /** Adds a component (defaults for missing fields). If present, replaces it and fires `onSet`. */
+    add<F extends Fields>(entity: Entity, component: ComponentDef<F>, value?: InitFields<F>): void;
+    /** Removes a component. Returns false if the entity didn't have it. */
+    remove(entity: Entity, component: ComponentDef): boolean;
+    has(entity: Entity, component: ComponentDef): boolean;
+    /** A copy of the component's value. Cold path: allocates. */
+    get<F extends Fields>(entity: Entity, component: ComponentDef<F>): InferFields<F>;
+    tryGet<F extends Fields>(entity: Entity, component: ComponentDef<F>): InferFields<F> | undefined;
+    /** Writes the given fields and marks the component changed. */
+    set<F extends Fields>(entity: Entity, component: ComponentDef<F>, values: InitFields<F>): void;
+    /** The table holding the entity's components. For system code that walks relationships. */
+    entityTable(entity: Entity): Table;
+    /** The entity's row in its table. Valid until the next structural change. */
+    entityRow(entity: Entity): number;
+    /**
+     * 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: Entity): Table;
+    entityRowUnchecked(entity: Entity): number;
+    componentsOf(entity: Entity): readonly ComponentDef[];
+    /** Returns a cached query; the same descriptor always gives the same `Query`. */
+    query(desc: QueryDescriptor): Query;
+    insertResource<T>(def: ResourceDef<T>, value: T): void;
+    /** Inserts the resource from its `init` if it isn't present yet, and returns it. */
+    initResource<T>(def: ResourceDef<T>): T;
+    resource<T>(def: ResourceDef<T>): T;
+    tryResource<T>(def: ResourceDef<T>): T | undefined;
+    hasResource(def: ResourceDef<unknown>): boolean;
+    removeResource(def: ResourceDef<unknown>): boolean;
+    send<T>(def: EventDef<T>, ...data: T extends undefined ? [data?: T] : [data: T]): void;
+    reader<T>(def: EventDef<T>): EventReader<T>;
+    /** Advances every event queue by one frame. Called by the app at the start of each frame. */
+    updateEvents(): void;
+    private eventQueue;
+    /** Registers an observer. Returns a function that unregisters it. */
+    observe<F extends Fields>(trigger: LifecycleTrigger<F>, fn: LifecycleObserver<F>): () => void;
+    observe<T>(event: EventDef<T>, fn: TriggerObserver<T>): () => void;
+    /** Runs observers registered for `event`, synchronously. */
+    trigger<T>(event: EventDef<T>, data: T, entity?: Entity): void;
+    stats(): WorldStats;
+    /** All archetype tables, including empty ones. */
+    allTables(): readonly Table[];
+    private allocate;
+    private growIndex;
+    /** Returns the entity's index, or throws if it isn't alive. */
+    private locate;
+    private insert;
+    private moveEntity;
+    /** The archetype with `def` and everything `def` requires (transitively) added. Cached. */
+    private tableWith;
+    private tableWithout;
+    /**
+     * 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: ComponentDef | ResourceDef<unknown> | EventDef<unknown>, migrate?: (value: Record<string, unknown>, entity: Entity) => Record<string, unknown>): void;
+    private getOrCreateTable;
+    private ensureRegistered;
+    private hasObservers;
+    private fire;
+    /** Keeps `Children` in sync with `ChildOf`. */
+    private installHierarchy;
+    private childList;
+    private addChild;
+    private removeChild;
+}