@galfus/engine 0.0.0-stage → 0.31.1-alpha

package/src/ecs/world.ts

@@ -0,0 +1,291 @@
+/**
+ * Generic ECS World orchestrating entities, components, systems, and intents.
+ */
+
+import { type Component, ComponentStore } from './component';
+import { type EntityId, EntityManager } from './entity';
+import { type IntentFlusher, IntentStore } from './intent';
+import { createMetadata, createName, type MetadataComponent, type NameComponent } from './metadata';
+import {
+  type System,
+  type SystemContext,
+  type SystemDescriptor,
+  type SystemKind,
+  SystemPipeline,
+  type SystemStep
+} from './system';
+
+export class EcsWorld implements IntentFlusher {
+  readonly entities = new EntityManager();
+  readonly components = new ComponentStore();
+  readonly intents = new IntentStore();
+  readonly systems = new SystemPipeline<EcsWorld>();
+
+  /**
+   * Spawns a new entity and returns its ID.
+   */
+  createEntity(): EntityId {
+    return this.entities.create();
+  }
+
+  /**
+   * Destroys an entity and immediately detaches all its attached components.
+   */
+  destroyEntity(entityId: EntityId): boolean {
+    if (this.entities.destroy(entityId)) {
+      this.components.removeAllForEntity(entityId);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Checks whether the entity is alive in this world.
+   */
+  isAlive(entityId: EntityId): boolean {
+    return this.entities.isAlive(entityId);
+  }
+
+  /**
+   * Attaches or updates a component on an entity with strict structural integrity checks.
+   */
+  attachComponent(entityId: EntityId, component: Component): void {
+    if (!this.entities.isAlive(entityId)) {
+      throw new Error(`Cannot attach component: Entity ${entityId} is not alive.`);
+    }
+
+    // Structural integrity enforcement (F04, F06, F08)
+    if (component.type === 'Mesh3D' || component.type === 'Collider3D') {
+      if (!this.components.has(entityId, 'Model3D')) {
+        throw new Error(
+          `Integrity violation: Entity ${entityId} cannot have ${component.type} attached without a Model3D spatial component.`
+        );
+      }
+    } else if (
+      component.type === 'Collider2D' ||
+      component.type === 'Sprite2D' ||
+      component.type === 'Shape2D' ||
+      component.type === 'Svg2D'
+    ) {
+      if (!this.components.has(entityId, 'Model2D')) {
+        throw new Error(
+          `Integrity violation: Entity ${entityId} cannot have ${component.type} attached without a Model2D spatial component.`
+        );
+      }
+    }
+
+    this.components.set(entityId, component);
+  }
+
+  /**
+   * Detaches a component from an entity by component type name.
+   */
+  detachComponent(entityId: EntityId, componentType: string): boolean {
+    if (
+      (componentType === 'Model2D' && this.components.has(entityId, 'Collider2D')) ||
+      (componentType === 'Model3D' && this.components.has(entityId, 'Collider3D'))
+    ) {
+      throw new Error(`Cannot detach ${componentType} while its collider component exists.`);
+    }
+    return this.components.delete(entityId, componentType);
+  }
+
+  /**
+   * Retrieves a component from an entity.
+   */
+  getComponent<T extends Component = Component>(
+    entityId: EntityId,
+    componentType: string
+  ): T | undefined {
+    return this.components.get<T>(entityId, componentType);
+  }
+
+  /**
+   * Checks if an entity possesses a component of the specified type.
+   */
+  hasComponent(entityId: EntityId, componentType: string): boolean {
+    return this.components.has(entityId, componentType);
+  }
+
+  /**
+   * Queries all entities possessing all requested component types.
+   *
+   * @param componentTypes Names of component types that matching entities must possess.
+   * @returns Array of matching entity IDs.
+   */
+  query(...componentTypes: string[]): EntityId[] {
+    if (componentTypes.length === 0) {
+      return this.entities.getActiveEntities();
+    }
+
+    const result: EntityId[] = [];
+    for (const id of this.components.entityIds(componentTypes[0]!)) {
+      let matches = true;
+      for (let i = 1; i < componentTypes.length; i++) {
+        if (!this.components.has(id, componentTypes[i]!)) {
+          matches = false;
+          break;
+        }
+      }
+      if (matches) result.push(id);
+    }
+    return result;
+  }
+
+  /**
+   * Sets or replaces the human-readable name of an entity.
+   */
+  setEntityName(entityId: EntityId, name: string): void {
+    const existing = this.getComponent<NameComponent>(entityId, 'Name');
+    if (existing) {
+      existing.name = name;
+    } else {
+      this.attachComponent(entityId, createName(name));
+    }
+  }
+
+  /**
+   * Retrieves the human-readable name of an entity if assigned.
+   */
+  getEntityName(entityId: EntityId): string | undefined {
+    return this.getComponent<NameComponent>(entityId, 'Name')?.name;
+  }
+
+  /**
+   * Finds the first entity possessing the exact given name.
+   */
+  findEntityByName(name: string): EntityId | undefined {
+    const ids = this.components.getEntitiesWith('Name');
+    for (const id of ids) {
+      const comp = this.components.get<NameComponent>(id, 'Name');
+      if (comp?.name === name) return id;
+    }
+    return undefined;
+  }
+
+  /**
+   * Finds all entities matching a given name or regular expression pattern.
+   */
+  findEntitiesByName(pattern: string | RegExp): EntityId[] {
+    const matches: EntityId[] = [];
+    const ids = this.components.getEntitiesWith('Name');
+    const isRegex = pattern instanceof RegExp;
+
+    for (const id of ids) {
+      const comp = this.components.get<NameComponent>(id, 'Name');
+      if (!comp) continue;
+      if (isRegex) {
+        pattern.lastIndex = 0;
+        if (pattern.test(comp.name)) {
+          matches.push(id);
+        }
+      } else if (comp.name === pattern) {
+        matches.push(id);
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Sets or updates a key-value entry in the entity's MetadataComponent.
+   */
+  setMetadataKV(entityId: EntityId, key: string, value: unknown): void {
+    let metadata = this.getComponent<MetadataComponent>(entityId, 'Metadata');
+    if (!metadata) {
+      metadata = createMetadata();
+      this.attachComponent(entityId, metadata);
+    }
+    metadata.entries.set(key, value);
+  }
+
+  /**
+   * Retrieves a metadata value by key for an entity.
+   */
+  getMetadataKV<T = unknown>(entityId: EntityId, key: string): T | undefined {
+    const metadata = this.getComponent<MetadataComponent>(entityId, 'Metadata');
+    return metadata?.entries.get(key) as T | undefined;
+  }
+
+  /**
+   * Finds all entities possessing a specific metadata key (and optional matching value).
+   */
+  findEntitiesByMetadata(key: string, value?: unknown): EntityId[] {
+    const matches: EntityId[] = [];
+    const ids = this.components.getEntitiesWith('Metadata');
+
+    for (const id of ids) {
+      const comp = this.components.get<MetadataComponent>(id, 'Metadata');
+      if (!comp || !comp.entries.has(key)) continue;
+
+      if (value === undefined || comp.entries.get(key) === value) {
+        matches.push(id);
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Adds a system to a given execution stage with optional priority and kind.
+   */
+  addSystem(
+    stepOrDesc: SystemStep | SystemDescriptor<EcsWorld>,
+    system?: System<EcsWorld>,
+    options?: { priority?: number; kind?: SystemKind }
+  ): this {
+    this.systems.add(stepOrDesc, system, options);
+    return this;
+  }
+
+  /**
+   * Flushes all queued intents in the intent store.
+   */
+  flushIntents(): void {
+    this.intents.flush(this);
+  }
+
+  /**
+   * Executes the pre-render phases:
+   * 1. Runs `input` stage systems & flushes intents.
+   * 2. Runs `update` stage systems & flushes intents.
+   * 3. Runs `preRender` stage systems & flushes intents.
+   */
+  stepPreRender(context: SystemContext): void {
+    this.systems.runStep('input', this, context);
+    this.flushIntents();
+
+    this.systems.runStep('update', this, context);
+    this.flushIntents();
+
+    this.systems.runStep('preRender', this, context);
+    this.flushIntents();
+  }
+
+  /**
+   * Executes the post-render phase (runs after GPU dispatch):
+   * 4. Runs `postRender` stage systems & final flush of intents.
+   */
+  stepPostRender(context: SystemContext): void {
+    this.systems.runStep('postRender', this, context);
+    this.flushIntents();
+  }
+
+  /**
+   * Executes a full frame cycle (used for standalone test stepping):
+   */
+  step(context: SystemContext): void {
+    this.stepPreRender(context);
+    this.stepPostRender(context);
+  }
+
+  /**
+   * Resets the entire world, clearing entities, components, systems, and intents.
+   */
+  reset(): void {
+    this.components.clear();
+    this.entities.clear();
+    this.intents.clear();
+    this.systems.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @galfus/engine: Unified game engine runtime with Multiverse, Realms, Anchors, ECS, Resources, Audio, Animation, and Zero-Alloc Math.
+ */
+export * from './anchors/index';
+export * from './animation/index';
+export * from './audio/index';
+export * from './ecs/index';
+export * from './interaction/index';
+export * from './collision/index';
+export * from './math/index';
+export * from './multiverse/index';
+export * from './platform/index';
+export * from './realm2d/index';
+export * from './realm3d/index';
+export * from './resources/index';
+export * from './runtime';
+export * from './spatial/index';
+export * from './text/index';
+export * from './types';

package/src/interaction/focus.ts

@@ -0,0 +1,327 @@
+import type { InteractiveListener } from './listener';
+import type { InteractiveTarget } from './types';
+import type { InteractiveSystem } from './system';
+import type { KeyboardEvent, PointerEvent } from '@galfus/transport-types';
+
+export type FocusEventType = 'focus' | 'blur';
+export interface FocusEvent {
+  readonly type: FocusEventType;
+  readonly windowId: number;
+  readonly realmId: number;
+  readonly target: InteractiveTarget;
+}
+export type FocusCallback = (event: FocusEvent) => void;
+
+/** A pointer target that can also receive focus in one or more windows. */
+export class Focusable {
+  private readonly callbacks = new Map<FocusEventType, Set<FocusCallback>>();
+  private disposed = false;
+  private disposing = false;
+  private enabled_ = true;
+  private tabIndex_: number;
+
+  constructor(
+    readonly listener: InteractiveListener,
+    private readonly manager: FocusManager,
+    tabIndex: number
+  ) {
+    this.tabIndex_ = Focusable.validateTabIndex(tabIndex);
+    listener.on('down', ({ pointer }) => {
+      if (pointer.type === 'button' && pointer.button === 'primary')
+        this.requestFocus(pointer.windowId);
+    });
+  }
+
+  get realmId(): number {
+    return this.listener.realmId;
+  }
+  get target(): InteractiveTarget {
+    return this.listener.target;
+  }
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+  get enabled(): boolean {
+    return this.enabled_;
+  }
+  get tabIndex(): number {
+    return this.tabIndex_;
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.assertLive();
+    if (this.enabled_ === enabled) return;
+    this.enabled_ = enabled;
+    if (!enabled) this.manager.blurTarget(this);
+    else this.manager.refreshCapture();
+  }
+
+  setTabIndex(index: number): void {
+    this.assertLive();
+    this.tabIndex_ = Focusable.validateTabIndex(index);
+    this.manager.refreshCapture();
+  }
+
+  requestFocus(windowId?: number): boolean {
+    this.assertLive();
+    return this.manager.requestFocus(this, windowId);
+  }
+
+  blur(windowId?: number): void {
+    this.assertLive();
+    this.manager.blurTarget(this, windowId);
+  }
+
+  on(type: FocusEventType, callback: FocusCallback): () => void {
+    this.assertLive();
+    let callbacks = this.callbacks.get(type);
+    if (!callbacks) this.callbacks.set(type, (callbacks = new Set()));
+    callbacks.add(callback);
+    return () => callbacks.delete(callback);
+  }
+
+  off(type: FocusEventType, callback: FocusCallback): void {
+    this.callbacks.get(type)?.delete(callback);
+  }
+
+  /** @internal */
+  emit(type: FocusEventType, windowId: number): void {
+    const event = { type, windowId, realmId: this.realmId, target: this.target };
+    for (const callback of this.callbacks.get(type) ?? []) {
+      callback(event);
+      if (this.disposed) break;
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed || this.disposing) return;
+    this.disposing = true;
+    this.manager.remove(this);
+    this.disposed = true;
+    this.callbacks.clear();
+    this.listener.dispose();
+  }
+
+  private assertLive(): void {
+    if (this.disposed) throw new Error('Focusable is disposed.');
+  }
+
+  private static validateTabIndex(index: number): number {
+    if (!Number.isSafeInteger(index)) throw new RangeError('tabIndex must be a safe integer.');
+    return index;
+  }
+}
+
+/** Keeps focus per window; only successfully presented direct targets are eligible. */
+export class FocusManager {
+  private readonly targets = new Set<Focusable>();
+  private readonly focused = new Map<number, Focusable>();
+  private readonly composing = new Set<number>();
+  private readonly unfocused = new Set<number>();
+  private readonly capturedWindows = new Set<number>();
+
+  constructor(
+    private readonly interaction: InteractiveSystem,
+    private readonly windowIds: () => readonly number[],
+    private readonly captureTab: (windowId: number, enabled: boolean) => void,
+    private readonly requestInputFocus: (windowId: number) => void
+  ) {}
+
+  register(listener: InteractiveListener, tabIndex = 0): Focusable {
+    const target = new Focusable(listener, this, tabIndex);
+    this.targets.add(target);
+    this.refreshCapture();
+    return target;
+  }
+
+  getFocused(windowId: number): Focusable | undefined {
+    return this.focused.get(windowId);
+  }
+
+  requestFocus(target: Focusable, windowId?: number): boolean {
+    if (!this.targets.has(target) || !target.enabled || target.isDisposed) return false;
+    if (windowId === undefined) {
+      let match: number | undefined;
+      for (const id of this.windowIds()) {
+        if (this.unfocused.has(id)) continue;
+        if (this.interaction.presentationOrder(target.listener, id) === undefined) continue;
+        if (match !== undefined) return false;
+        match = id;
+      }
+      if (match === undefined) return false;
+      windowId = match;
+    }
+    if (
+      this.unfocused.has(windowId) ||
+      this.interaction.presentationOrder(target.listener, windowId) === undefined
+    )
+      return false;
+    const previous = this.focused.get(windowId);
+    if (previous === target) return true;
+    this.requestInputFocus(windowId);
+    this.focused.delete(windowId);
+    previous?.emit('blur', windowId);
+    // A blur callback may have changed focus, removed the target, or changed presentation.
+    if (
+      this.focused.has(windowId) ||
+      this.unfocused.has(windowId) ||
+      !this.targets.has(target) ||
+      !target.enabled ||
+      this.interaction.presentationOrder(target.listener, windowId) === undefined
+    )
+      return false;
+    this.focused.set(windowId, target);
+    this.refreshCapture();
+    target.emit('focus', windowId);
+    return this.focused.get(windowId) === target;
+  }
+
+  advance(windowId: number, reverse = false): boolean {
+    const currentFocused = this.focused.get(windowId);
+    let activeRealmId = currentFocused?.realmId;
+    const candidates: Array<{ target: Focusable; order: number; sequence: number }> = [];
+    let sequence = 0;
+    for (const target of this.targets) {
+      const order =
+        target.enabled && target.tabIndex >= 0
+          ? this.interaction.presentationOrder(target.listener, windowId)
+          : undefined;
+      if (order !== undefined) candidates.push({ target, order, sequence });
+      sequence++;
+    }
+    if (!candidates.length) return false;
+    candidates.sort((a, b) => {
+      const ai = a.target.tabIndex || Infinity,
+        bi = b.target.tabIndex || Infinity;
+      return ai - bi || a.order - b.order || a.sequence - b.sequence;
+    });
+    if (activeRealmId === undefined) activeRealmId = candidates[0]!.target.realmId;
+    const realmCandidates = candidates.filter(({ target }) => target.realmId === activeRealmId);
+    if (!realmCandidates.length) return false;
+    const current = realmCandidates.findIndex(({ target }) => target === currentFocused);
+    const index =
+      current < 0
+        ? reverse
+          ? realmCandidates.length - 1
+          : 0
+        : (current + (reverse ? -1 : 1) + realmCandidates.length) % realmCandidates.length;
+    return this.requestFocus(realmCandidates[index]!.target, windowId);
+  }
+
+  handleKeyboard(event: KeyboardEvent): void {
+    if (event.type === 'imePreedit') {
+      if (event.text) this.composing.add(event.windowId);
+      else this.composing.delete(event.windowId);
+    } else if (event.type === 'imeCommit' || event.type === 'imeDisabled') {
+      this.composing.delete(event.windowId);
+    } else if (
+      event.type === 'input' &&
+      event.state === 'pressed' &&
+      event.logicalKey === 'Tab' &&
+      !event.modifiers.ctrl &&
+      !event.modifiers.alt &&
+      !event.modifiers.superKey &&
+      !this.composing.has(event.windowId)
+    ) {
+      this.advance(event.windowId, event.modifiers.shift);
+    }
+  }
+
+  handlePointer(event: PointerEvent): void {
+    if (event.type !== 'button' || event.state !== 'pressed' || event.button !== 'primary') return;
+    const hovered = this.interaction.hovered(event.windowId, event.pointerId);
+    for (const target of this.targets) if (target.enabled && target.listener === hovered) return;
+    this.blurWindow(event.windowId);
+    this.refreshCapture();
+  }
+
+  blurTarget(target: Focusable, windowId?: number): void {
+    const windows: number[] = [];
+    for (const [id, focused] of this.focused)
+      if (focused === target && (windowId === undefined || id === windowId)) windows.push(id);
+    for (const id of windows) {
+      if (this.focused.get(id) !== target) continue;
+      this.focused.delete(id);
+      target.emit('blur', id);
+    }
+    this.refreshCapture();
+  }
+
+  remove(target: Focusable): void {
+    if (!this.targets.delete(target)) return;
+    this.blurTarget(target);
+  }
+
+  windowClosed(windowId: number): void {
+    this.capturedWindows.delete(windowId);
+    this.unfocused.delete(windowId);
+    this.blurWindow(windowId);
+  }
+
+  windowFocusChanged(windowId: number, focused: boolean): void {
+    if (focused) this.unfocused.delete(windowId);
+    else {
+      this.unfocused.add(windowId);
+      this.blurWindow(windowId);
+      this.refreshCapture();
+    }
+  }
+
+  private blurWindow(windowId: number): void {
+    this.composing.delete(windowId);
+    const target = this.focused.get(windowId);
+    if (!target) return;
+    this.focused.delete(windowId);
+    target.emit('blur', windowId);
+  }
+
+  /** Reconciles focus after a successful presentation. */
+  afterDispatch(): void {
+    if (!this.targets.size && !this.focused.size && !this.capturedWindows.size) return;
+    for (const target of this.targets) if (target.listener.isDisposed) target.dispose();
+    for (const [windowId, target] of this.focused)
+      if (
+        !target.enabled ||
+        this.interaction.presentationOrder(target.listener, windowId) === undefined
+      )
+        this.blurWindow(windowId);
+    this.refreshCapture();
+  }
+
+  /** Synchronizes platform Tab capture only when eligibility changes. */
+  refreshCapture(): void {
+    if (!this.targets.size && !this.focused.size && !this.capturedWindows.size) return;
+    const windows = this.windowIds();
+    for (const windowId of this.capturedWindows) {
+      if (windows.includes(windowId)) continue;
+      this.captureTab(windowId, false);
+      this.capturedWindows.delete(windowId);
+    }
+    for (const windowId of windows) {
+      let needed = this.focused.has(windowId);
+      for (const target of this.targets) {
+        if (needed) break;
+        if (
+          target.enabled &&
+          target.tabIndex >= 0 &&
+          this.interaction.presentationOrder(target.listener, windowId) !== undefined
+        ) {
+          needed = true;
+          break;
+        }
+      }
+      if (needed === this.capturedWindows.has(windowId)) continue;
+      this.captureTab(windowId, needed);
+      if (needed) this.capturedWindows.add(windowId);
+      else this.capturedWindows.delete(windowId);
+    }
+  }
+
+  dispose(): void {
+    for (const target of this.targets) target.dispose();
+    this.focused.clear();
+    this.composing.clear();
+    this.unfocused.clear();
+    this.capturedWindows.clear();
+  }
+}

package/src/interaction/index.ts

@@ -0,0 +1,9 @@
+export { InteractiveListener } from './listener';
+export { Focusable } from './focus';
+export type { FocusEvent, FocusEventType, FocusCallback } from './focus';
+export type {
+  InteractiveCallback,
+  InteractiveEvent,
+  InteractiveEventType,
+  InteractiveTarget
+} from './types';

package/src/interaction/listener.ts

@@ -0,0 +1,58 @@
+import type {
+  InteractiveCallback,
+  InteractiveEvent,
+  InteractiveEventType,
+  InteractiveTarget
+} from './types';
+
+/** Event subscriptions for one registered interactive target. */
+export class InteractiveListener {
+  private readonly listeners = new Map<InteractiveEventType, Set<InteractiveCallback>>();
+  private disposed = false;
+
+  constructor(
+    readonly realmId: number,
+    readonly target: InteractiveTarget,
+    private readonly remove: (listener: InteractiveListener) => void
+  ) {}
+
+  /** @internal */
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  on(type: InteractiveEventType, callback: InteractiveCallback): () => void {
+    if (this.disposed) throw new Error('Interactive listener is disposed.');
+    let callbacks = this.listeners.get(type);
+    if (!callbacks) this.listeners.set(type, (callbacks = new Set()));
+    callbacks.add(callback);
+    return () => callbacks.delete(callback);
+  }
+
+  off(type: InteractiveEventType, callback: InteractiveCallback): void {
+    this.listeners.get(type)?.delete(callback);
+  }
+
+  /** @internal */
+  hasListeners(type: InteractiveEventType): boolean {
+    return !this.disposed && (this.listeners.get(type)?.size ?? 0) > 0;
+  }
+
+  /** @internal */
+  emit(event: InteractiveEvent): void {
+    if (this.disposed) return;
+    const callbacks = this.listeners.get(event.type);
+    if (!callbacks) return;
+    for (const callback of callbacks) {
+      callback(event);
+      if (this.disposed) break;
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.listeners.clear();
+    this.remove(this);
+  }
+}