@galfus/engine 0.0.0-stage → 0.31.1-alpha

package/src/ecs/entity.ts

@@ -0,0 +1,75 @@
+/**
+ * Entity management and ID allocation with policy enforcement.
+ */
+
+import { assertValidLogicalId } from '@galfus/transport-types';
+
+export type EntityId = number;
+
+export class EntityManager {
+  private _nextId = 1;
+  private readonly _alive = new Set<EntityId>();
+  private readonly _freeList: EntityId[] = [];
+
+  /**
+   * Allocates a new unique EntityId, reusing recycled IDs before incrementing,
+   * and asserting validity against the core reserved range.
+   */
+  create(): EntityId {
+    let id: EntityId;
+    if (this._freeList.length > 0) {
+      id = this._freeList.pop()!;
+    } else {
+      id = this._nextId++;
+      assertValidLogicalId(id, 'EntityId');
+    }
+
+    this._alive.add(id);
+    return id;
+  }
+
+  /**
+   * Destroys an entity, marking its ID as free for recycling.
+   *
+   * @param id The EntityId to destroy.
+   * @returns True if the entity was alive and destroyed, false otherwise.
+   */
+  destroy(id: EntityId): boolean {
+    if (!this._alive.has(id)) {
+      return false;
+    }
+    this._alive.delete(id);
+    this._freeList.push(id);
+    return true;
+  }
+
+  /**
+   * Checks whether the specified EntityId is currently alive.
+   */
+  isAlive(id: EntityId): boolean {
+    return this._alive.has(id);
+  }
+
+  /**
+   * Returns the count of currently alive entities.
+   */
+  aliveCount(): number {
+    return this._alive.size;
+  }
+
+  /**
+   * Returns an array of all currently active entity IDs.
+   */
+  getActiveEntities(): EntityId[] {
+    return Array.from(this._alive);
+  }
+
+  /**
+   * Clears all entities and resets the allocation sequence.
+   */
+  clear(): void {
+    this._alive.clear();
+    this._freeList.length = 0;
+    this._nextId = 1;
+  }
+}

package/src/ecs/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Generic ECS subsystem.
+ */
+export * from './component';
+export * from './entity';
+export * from './intent';
+export * from './metadata';
+export * from './system';
+export * from './world';

package/src/ecs/intent.ts

@@ -0,0 +1,162 @@
+/**
+ * Intent store for atomic and deferred ECS state mutations.
+ * Built on a strictly FIFO linked list with isolated error recovery and recursion bounds.
+ */
+
+import type { Component } from './component';
+import type { EntityId } from './entity';
+
+export type Intent =
+  | { kind: 'attach'; entityId: EntityId; component: Component }
+  | { kind: 'detach'; entityId: EntityId; componentType: string }
+  | { kind: 'destroy'; entityId: EntityId }
+  | { kind: 'custom'; action: () => void };
+
+export interface IntentFlusher {
+  attachComponent(entityId: EntityId, component: Component): void;
+  detachComponent(entityId: EntityId, componentType: string): void;
+  destroyEntity(entityId: EntityId): void;
+}
+
+interface IntentNode {
+  intent: Intent;
+  next: IntentNode | null;
+}
+
+export class IntentStore {
+  private _head: IntentNode | null = null;
+  private _tail: IntentNode | null = null;
+  private _size = 0;
+  private _lastErrors: Error[] = [];
+
+  /**
+   * Enqueues an intention to attach a component to an entity on the next flush.
+   */
+  queueAttach(entityId: EntityId, component: Component): void {
+    this._enqueue({ kind: 'attach', entityId, component });
+  }
+
+  /**
+   * Enqueues an intention to detach a component from an entity on the next flush.
+   */
+  queueDetach(entityId: EntityId, componentType: string): void {
+    this._enqueue({ kind: 'detach', entityId, componentType });
+  }
+
+  /**
+   * Enqueues an intention to destroy an entity on the next flush.
+   */
+  queueDestroy(entityId: EntityId): void {
+    this._enqueue({ kind: 'destroy', entityId });
+  }
+
+  /**
+   * Enqueues a custom arbitrary atomic mutation callback.
+   */
+  queueCustom(action: () => void): void {
+    this._enqueue({ kind: 'custom', action });
+  }
+
+  /**
+   * Returns the count of pending queued intents.
+   */
+  get pendingCount(): number {
+    return this._size;
+  }
+
+  /**
+   * Returns errors captured during the last flush execution.
+   */
+  get lastErrors(): readonly Error[] {
+    return this._lastErrors;
+  }
+
+  /**
+   * Clears recorded execution errors.
+   */
+  clearErrors(): void {
+    this._lastErrors = [];
+  }
+
+  /**
+   * Flushes all queued intents strictly in FIFO order.
+   * If intent executions trigger further intents, they are flushed up to `maxFlushDepth`.
+   * Each intent is executed in an isolated try/catch so a failure does not break subsequent intents.
+   *
+   * @param flusher Target receiver executing the atomic state operations.
+   * @param maxFlushDepth Maximum number of recursive flush cycles before aborting (default 100).
+   * @returns Array of errors that occurred during this flush.
+   */
+  flush(flusher: IntentFlusher, maxFlushDepth = 100): readonly Error[] {
+    if (this._head === null && this._lastErrors.length === 0) return this._lastErrors;
+    this._lastErrors = [];
+    let depth = 0;
+
+    while (this._head !== null) {
+      if (++depth > maxFlushDepth) {
+        const overflow = new Error(
+          `[IntentStore] Max flush depth (${maxFlushDepth}) exceeded; dropping pending intents to prevent infinite recursion.`
+        );
+        this._lastErrors.push(overflow);
+        console.error(overflow.message);
+        this.clear();
+        break;
+      }
+
+      // Detach current chain for processing this cycle
+      let current: IntentNode | null = this._head;
+      this._head = null;
+      this._tail = null;
+      this._size = 0;
+
+      while (current !== null) {
+        const node = current;
+        current = current.next;
+
+        try {
+          switch (node.intent.kind) {
+            case 'attach':
+              flusher.attachComponent(node.intent.entityId, node.intent.component);
+              break;
+            case 'detach':
+              flusher.detachComponent(node.intent.entityId, node.intent.componentType);
+              break;
+            case 'destroy':
+              flusher.destroyEntity(node.intent.entityId);
+              break;
+            case 'custom':
+              node.intent.action();
+              break;
+          }
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          this._lastErrors.push(error);
+          console.error('[IntentStore] Error executing intent:', error);
+        }
+      }
+    }
+
+    return this._lastErrors;
+  }
+
+  /**
+   * Discards all pending queued intents without executing them.
+   */
+  clear(): void {
+    this._head = null;
+    this._tail = null;
+    this._size = 0;
+  }
+
+  private _enqueue(intent: Intent): void {
+    const node: IntentNode = { intent, next: null };
+    if (this._tail === null) {
+      this._head = node;
+      this._tail = node;
+    } else {
+      this._tail.next = node;
+      this._tail = node;
+    }
+    this._size++;
+  }
+}

package/src/ecs/metadata.ts

@@ -0,0 +1,44 @@
+/**
+ * Name and Metadata components for ECS entities.
+ */
+
+import type { Component } from './component';
+
+export interface NameComponent extends Component {
+  readonly type: 'Name';
+  name: string;
+}
+
+export function createName(name: string): NameComponent {
+  return {
+    type: 'Name',
+    name
+  };
+}
+
+export interface MetadataComponent extends Component {
+  readonly type: 'Metadata';
+  readonly entries: Map<string, unknown>;
+}
+
+export function createMetadata(
+  initial?: Record<string, unknown> | Map<string, unknown>
+): MetadataComponent {
+  const entries = new Map<string, unknown>();
+  if (initial) {
+    if (initial instanceof Map) {
+      for (const [key, value] of initial.entries()) {
+        entries.set(key, value);
+      }
+    } else {
+      for (const [key, value] of Object.entries(initial)) {
+        entries.set(key, value);
+      }
+    }
+  }
+
+  return {
+    type: 'Metadata',
+    entries
+  };
+}

package/src/ecs/system.ts

@@ -0,0 +1,224 @@
+/**
+ * Execution pipeline and 4-phase system scheduler.
+ */
+
+import type { GalfusEngine } from '@galfus/transport-types';
+
+/**
+ * Standard execution stages executed in fixed sequence each frame:
+ * 1. `input`: Processes incoming platform events, gamepads, pointers, keyboards.
+ * 2. `update`: Main game logic, physics integration, AI behavior.
+ * 3. `preRender`: Anchor solving, spatial hierarchies, camera sync, scene graph updates.
+ * 4. `postRender`: Frame metrics, debug diagnostics, cleanups (executed after dispatch).
+ */
+export type SystemStep = 'input' | 'update' | 'preRender' | 'postRender';
+
+export const SYSTEM_STEPS: readonly SystemStep[] = [
+  'input',
+  'update',
+  'preRender',
+  'postRender'
+] as const;
+
+/**
+ * Functional classification of a registered system.
+ */
+export type SystemKind = 'ordinary' | 'anchor' | 'sync' | 'cleanup' | 'custom';
+
+/**
+ * Reserved internal system execution priorities.
+ * User-registered ordinary systems are clamped to [MIN_USER_PRIORITY, MAX_USER_PRIORITY]
+ * to ensure that internal stages (anchor solving, skinning, realm sync) execute in strict order.
+ */
+export const RESERVED_PRIORITY_ANCHOR_RESOLVE = -1_000_000;
+export const RESERVED_PRIORITY_INTERNAL_RESOLVERS = -2_000_000;
+export const RESERVED_PRIORITY_REALM_SYNC = -3_000_000;
+export const MIN_USER_PRIORITY = -999_999;
+export const MAX_USER_PRIORITY = 999_999;
+
+/**
+ * Execution context passed to every system during frame execution.
+ */
+export interface SystemContext {
+  /** Total elapsed simulation time in seconds. */
+  time: number;
+  /** Delta time of the current frame in seconds (`deltaMs / 1000`). */
+  dt: number;
+  /** Sequential frame identifier. */
+  frameId: number;
+  /** Direct access to the underlying native or WASM GalfusEngine ABI. */
+  engine?: GalfusEngine;
+}
+
+/**
+ * Pure function signature of an ECS system.
+ */
+export type System<TWorld = unknown> = (world: TWorld, context: SystemContext) => void;
+
+/**
+ * Options or configuration descriptor for registering an ECS system.
+ */
+export interface SystemDescriptor<TWorld = unknown> {
+  step: SystemStep;
+  fn: System<TWorld>;
+  /**
+   * Execution priority within the stage.
+   * Higher priority systems execute earlier. Ties are resolved by stable insertion order.
+   * Defaults to 0.
+   */
+  priority?: number;
+  /** Functional category of the system. Defaults to 'ordinary'. */
+  kind?: SystemKind;
+}
+
+/**
+ * An immutable registration entry in the system scheduler.
+ */
+export interface RegisteredSystem<TWorld = unknown> {
+  step: SystemStep;
+  fn: System<TWorld>;
+  priority: number;
+  insertionOrder: number;
+  kind: SystemKind;
+}
+
+/**
+ * Manages systems registered across the 4 stages with stable priority and insertion ordering.
+ */
+export class SystemPipeline<TWorld = unknown> {
+  private readonly _systems: Record<SystemStep, RegisteredSystem<TWorld>[]> = {
+    input: [],
+    update: [],
+    preRender: [],
+    postRender: []
+  };
+  private _insertionCounter = 0;
+
+  /**
+   * Registers a system into a specified execution stage with stable ordering.
+   *
+   * @param stepOrDesc Stage name or full {@link SystemDescriptor}.
+   * @param systemFn The system function when passing step as string.
+   * @param options Optional priority and kind configuration.
+   */
+  add(
+    stepOrDesc: SystemStep | SystemDescriptor<TWorld>,
+    systemFn?: System<TWorld>,
+    options?: { priority?: number; kind?: SystemKind }
+  ): this {
+    let desc: SystemDescriptor<TWorld>;
+    if (typeof stepOrDesc === 'string') {
+      if (!systemFn) {
+        throw new Error('System function must be provided when step is passed as a string');
+      }
+      desc = {
+        step: stepOrDesc,
+        fn: systemFn,
+        priority: options?.priority,
+        kind: options?.kind ?? 'ordinary'
+      };
+    } else {
+      desc = stepOrDesc;
+    }
+
+    const kind = desc.kind ?? 'ordinary';
+    let priority: number;
+    if (kind === 'ordinary' || kind === 'custom') {
+      priority = Math.max(MIN_USER_PRIORITY, Math.min(MAX_USER_PRIORITY, desc.priority ?? 0));
+    } else if (desc.priority !== undefined) {
+      priority = desc.priority;
+    } else if (kind === 'anchor') {
+      priority = RESERVED_PRIORITY_ANCHOR_RESOLVE;
+    } else if (kind === 'sync') {
+      priority = RESERVED_PRIORITY_REALM_SYNC;
+    } else {
+      priority = RESERVED_PRIORITY_INTERNAL_RESOLVERS;
+    }
+
+    const entry: RegisteredSystem<TWorld> = {
+      step: desc.step,
+      fn: desc.fn,
+      priority,
+      insertionOrder: ++this._insertionCounter,
+      kind
+    };
+
+    const list = [...this._systems[desc.step]];
+    list.push(entry);
+
+    // Stably sort: higher priority first; equal priorities preserve ascending insertionOrder
+    list.sort((a, b) => {
+      if (b.priority !== a.priority) {
+        return b.priority - a.priority;
+      }
+      return a.insertionOrder - b.insertionOrder;
+    });
+
+    this._systems[desc.step] = list;
+    return this;
+  }
+
+  /**
+   * Removes a previously registered system from a stage.
+   */
+  remove(step: SystemStep, system: System<TWorld>): boolean {
+    const list = this._systems[step];
+    const index = list.findIndex((s) => s.fn === system);
+    if (index !== -1) {
+      this._systems[step] = [...list.slice(0, index), ...list.slice(index + 1)];
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Runs all systems registered in a specific stage in sorted order.
+   * Safe against removal during iteration and isolates individual system exceptions.
+   */
+  runStep(step: SystemStep, world: TWorld, context: SystemContext): void {
+    const list = this._systems[step];
+    for (const entry of list) {
+      try {
+        entry.fn(world, context);
+      } catch (err) {
+        console.error(`[SystemPipeline] Error executing system in stage '${step}':`, err);
+      }
+    }
+  }
+
+  /**
+   * Runs all 4 stages in canonical sequence: input -> update -> preRender -> postRender.
+   */
+  runAll(world: TWorld, context: SystemContext): void {
+    this.runStep('input', world, context);
+    this.runStep('update', world, context);
+    this.runStep('preRender', world, context);
+    this.runStep('postRender', world, context);
+  }
+
+  /**
+   * Returns a copy of registered systems in the given stage or all stages.
+   */
+  getRegistered(step?: SystemStep): RegisteredSystem<TWorld>[] {
+    if (step) {
+      return [...this._systems[step]];
+    }
+    return [
+      ...this._systems.input,
+      ...this._systems.update,
+      ...this._systems.preRender,
+      ...this._systems.postRender
+    ];
+  }
+
+  /**
+   * Clears all registered systems.
+   */
+  clear(): void {
+    this._systems.input = [];
+    this._systems.update = [];
+    this._systems.preRender = [];
+    this._systems.postRender = [];
+    this._insertionCounter = 0;
+  }
+}