@galfus/engine 0.0.0-stage → 0.31.1-alpha

package/src/multiverse/presentation-graph.ts

@@ -0,0 +1,306 @@
+import type { MultiverseSchedule, TargetDesc } from '@galfus/transport-types';
+import type { PresentationLinksSnapshot } from './presentation-links';
+
+/** A confirmed surface that maps a consumer realm's texture slot to a source target. */
+export interface PresentationSurface {
+  readonly realmId: number;
+  readonly slot: string;
+  readonly entityId: number;
+}
+export interface PresentationBinding {
+  readonly realmId: number;
+  readonly slot: string;
+  readonly sourceTargetId: number;
+}
+export interface PresentationConnection extends PresentationBinding {
+  readonly entityId: number;
+}
+export interface PresentedInvocation {
+  readonly invocationId: number;
+  readonly realmId: number;
+  readonly cameraSlot?: number;
+  readonly resolvedViewport: readonly [number, number, number, number];
+  readonly zIndex: number;
+}
+/** Immutable view of one dispatched schedule, rooted at an open window. */
+export interface WindowPresentation {
+  readonly windowId: number;
+  readonly rootTargetIds: readonly number[];
+  readonly targetIds: readonly number[];
+  readonly invocationIds: readonly number[];
+  readonly realmIds: readonly number[];
+  readonly candidateBindings: readonly PresentationBinding[];
+  readonly connections: readonly PresentationConnection[];
+  /** Render dependency edges sampled from the previous frame to break cycles. */
+  readonly softCutEdges: readonly (readonly [number, number])[];
+  /** IDs are in render order, as resolved by the renderer. */
+  getInvocations(targetId: number): readonly number[];
+  getInvocation(invocationId: number): PresentedInvocation | undefined;
+  getCandidates(realmId: number): readonly PresentationBinding[];
+}
+export interface PresentationGraphView {
+  getWindow(windowId: number): WindowPresentation | undefined;
+  getWindowIds(): readonly number[];
+}
+interface Snapshot {
+  readonly signature: readonly (number | undefined)[];
+  readonly linksRevision: number;
+  readonly windowRevision: number;
+  readonly windows: Map<number, WindowPresentation>;
+}
+const EMPTY: readonly never[] = Object.freeze([]);
+function sorted(values: Iterable<number>): readonly number[] {
+  return Object.freeze([...values].sort((a, b) => a - b));
+}
+function compareSlot(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Publishes only render schedules whose dispatch completed successfully. */
+export class PresentationGraph {
+  private readonly openWindows = new Set<number>();
+  private windowRevision = 0;
+  private published?: Snapshot;
+  private pending?: Snapshot;
+  private windowIds: readonly number[] = EMPTY;
+  readonly view: PresentationGraphView = Object.freeze({
+    getWindow: (id: number) =>
+      this.openWindows.has(id) ? this.published?.windows.get(id) : undefined,
+    getWindowIds: () => this.windowIds
+  });
+
+  windowOpened(windowId: number): void {
+    if (!this.openWindows.has(windowId)) {
+      this.openWindows.add(windowId);
+      this.windowRevision++;
+    }
+  }
+  windowClosed(windowId: number): void {
+    if (!this.openWindows.delete(windowId)) return;
+    this.windowRevision++;
+    this.published?.windows.delete(windowId);
+    this.pending?.windows.delete(windowId);
+    this.refreshWindowIds();
+  }
+  private refreshWindowIds(): void {
+    this.windowIds = sorted(this.published?.windows.keys() ?? []);
+  }
+
+  private matches(
+    snapshot: Snapshot,
+    schedule: MultiverseSchedule,
+    targets: ReadonlyMap<number, TargetDesc>,
+    linksRevision: number
+  ): boolean {
+    if (snapshot.linksRevision !== linksRevision || snapshot.windowRevision !== this.windowRevision)
+      return false;
+    const signature = snapshot.signature;
+    let i = 0;
+    const blocks = schedule.targetBlocks!;
+    if (signature[i++] !== blocks.length) return false;
+    for (const block of blocks) {
+      const target = targets.get(block.targetId);
+      const windowId = target?.kind.type === 'window' ? target.kind.windowId : undefined;
+      if (
+        signature[i++] !== block.targetId ||
+        signature[i++] !== windowId ||
+        signature[i++] !== block.invocations.length
+      )
+        return false;
+      for (const inv of block.invocations) {
+        if (
+          signature[i++] !== inv.invocationId ||
+          signature[i++] !== inv.realmId ||
+          signature[i++] !== inv.cameraSlot ||
+          signature[i++] !== inv.zIndex ||
+          signature[i++] !== inv.resolvedViewport.length
+        )
+          return false;
+        for (const value of inv.resolvedViewport) if (signature[i++] !== value) return false;
+      }
+    }
+    const cuts = schedule.softCutEdges;
+    if (signature[i++] !== (cuts?.length ?? 0)) return false;
+    if (cuts)
+      for (const edge of cuts) {
+        if (signature[i++] !== edge[0] || signature[i++] !== edge[1]) return false;
+      }
+    return i === signature.length;
+  }
+
+  stage(
+    schedule: MultiverseSchedule | undefined,
+    targets: ReadonlyMap<number, TargetDesc>,
+    links: PresentationLinksSnapshot
+  ): void {
+    this.pending = undefined;
+    if (!schedule || !Array.isArray(schedule.targetBlocks)) return;
+    if (this.published && this.matches(this.published, schedule, targets, links.revision)) {
+      this.pending = this.published;
+      return;
+    }
+    const roots: Array<[number, number]> = [];
+    const signature: (number | undefined)[] = [schedule.targetBlocks.length];
+    for (const block of schedule.targetBlocks) {
+      const target = targets.get(block.targetId);
+      signature.push(
+        block.targetId,
+        target?.kind.type === 'window' ? target.kind.windowId : undefined,
+        block.invocations.length
+      );
+      for (const inv of block.invocations)
+        signature.push(
+          inv.invocationId,
+          inv.realmId,
+          inv.cameraSlot,
+          inv.zIndex,
+          inv.resolvedViewport.length,
+          ...inv.resolvedViewport
+        );
+      if (target?.kind.type === 'window' && this.openWindows.has(target.kind.windowId))
+        roots.push([target.kind.windowId, block.targetId]);
+    }
+    const cuts = schedule.softCutEdges ?? [];
+    signature.push(cuts.length);
+    for (const [source, target] of cuts) signature.push(source, target);
+    const blocks = new Map(schedule.targetBlocks.map((block) => [block.targetId, block]));
+    const bindingsByRealm = new Map<number, PresentationBinding[]>();
+    for (const binding of links.bindings) {
+      let entries = bindingsByRealm.get(binding.realmId);
+      if (!entries) {
+        entries = [];
+        bindingsByRealm.set(binding.realmId, entries);
+      }
+      entries.push(binding);
+    }
+    const surfacesByRealm = new Map<number, Map<string, number[]>>();
+    for (const surface of links.surfaces) {
+      let slots = surfacesByRealm.get(surface.realmId);
+      if (!slots) {
+        slots = new Map();
+        surfacesByRealm.set(surface.realmId, slots);
+      }
+      let entities = slots.get(surface.slot);
+      if (!entities) {
+        entities = [];
+        slots.set(surface.slot, entities);
+      }
+      entities.push(surface.entityId);
+    }
+    const rootMap = new Map<number, number[]>();
+    for (const [windowId, targetId] of roots) {
+      let ids = rootMap.get(windowId);
+      if (!ids) {
+        ids = [];
+        rootMap.set(windowId, ids);
+      }
+      ids.push(targetId);
+    }
+    const windows = new Map<number, WindowPresentation>();
+    for (const [windowId, rootTargets] of rootMap) {
+      const visitedTargets = new Set<number>();
+      const realms = new Set<number>();
+      const invocations = new Map<number, PresentedInvocation>();
+      const byTarget = new Map<number, readonly number[]>();
+      const byRealm = new Map<number, readonly PresentationBinding[]>();
+      const candidates = new Set<PresentationBinding>();
+      const connections: PresentationConnection[] = [];
+      const pending = [...rootTargets];
+      while (pending.length) {
+        const targetId = pending.pop()!;
+        if (visitedTargets.has(targetId)) continue;
+        const block = blocks.get(targetId);
+        if (!block) continue;
+        visitedTargets.add(targetId);
+        const ids: number[] = [];
+        for (const inv of block.invocations) {
+          ids.push(inv.invocationId);
+          invocations.set(
+            inv.invocationId,
+            Object.freeze({
+              invocationId: inv.invocationId,
+              realmId: inv.realmId,
+              cameraSlot: inv.cameraSlot,
+              resolvedViewport: Object.freeze([...inv.resolvedViewport]) as readonly [
+                number,
+                number,
+                number,
+                number
+              ],
+              zIndex: inv.zIndex
+            })
+          );
+          if (realms.has(inv.realmId)) continue;
+          realms.add(inv.realmId);
+          const bindings = [...(bindingsByRealm.get(inv.realmId) ?? [])].sort((a, b) =>
+            compareSlot(a.slot, b.slot)
+          );
+          byRealm.set(inv.realmId, Object.freeze(bindings));
+          for (const binding of bindings) {
+            candidates.add(binding);
+            for (const entityId of surfacesByRealm.get(inv.realmId)?.get(binding.slot) ?? []) {
+              if (!blocks.has(binding.sourceTargetId)) continue;
+              connections.push(Object.freeze({ ...binding, entityId }));
+              pending.push(binding.sourceTargetId);
+            }
+          }
+        }
+        byTarget.set(targetId, Object.freeze(ids));
+      }
+      connections.sort(
+        (a, b) => a.realmId - b.realmId || compareSlot(a.slot, b.slot) || a.entityId - b.entityId
+      );
+      const candidateList = [...candidates].sort(
+        (a, b) => a.realmId - b.realmId || compareSlot(a.slot, b.slot)
+      );
+      const softCutEdges = Object.freeze(
+        cuts
+          .filter(([source, target]) => visitedTargets.has(source) && visitedTargets.has(target))
+          .map(([source, target]) => Object.freeze([source, target] as const))
+      );
+      windows.set(
+        windowId,
+        Object.freeze({
+          windowId,
+          rootTargetIds: sorted(rootTargets),
+          targetIds: sorted(visitedTargets),
+          invocationIds: sorted(invocations.keys()),
+          realmIds: sorted(realms),
+          candidateBindings: Object.freeze(candidateList),
+          connections: Object.freeze(connections),
+          softCutEdges,
+          getInvocations: (targetId: number) => byTarget.get(targetId) ?? EMPTY,
+          getInvocation: (id: number) => invocations.get(id),
+          getCandidates: (realmId: number) => byRealm.get(realmId) ?? EMPTY
+        })
+      );
+    }
+    this.pending = {
+      signature,
+      linksRevision: links.revision,
+      windowRevision: this.windowRevision,
+      windows
+    };
+  }
+  commit(): void {
+    if (this.published === this.pending) {
+      this.pending = undefined;
+      return;
+    }
+    this.published = this.pending;
+    this.pending = undefined;
+    this.refreshWindowIds();
+  }
+  discard(): void {
+    this.pending = undefined;
+  }
+  clear(): void {
+    this.published = undefined;
+    this.pending = undefined;
+    this.windowIds = EMPTY;
+  }
+  dispose(): void {
+    this.clear();
+    this.openWindows.clear();
+  }
+}

package/src/multiverse/presentation-links.ts

@@ -0,0 +1,134 @@
+import type { TargetTextureBinding } from '@galfus/transport-types';
+import type { PresentationBinding, PresentationSurface } from './presentation-graph';
+
+export interface PresentationLinksSnapshot {
+  readonly revision: number;
+  readonly bindings: readonly PresentationBinding[];
+  readonly surfaces: readonly PresentationSurface[];
+}
+
+/** Host-owned links that are not represented by the render schedule. */
+export class PresentationLinks {
+  private readonly bindings = new Map<number, Map<string, PresentationBinding>>();
+  private readonly byTarget = new Map<number, Set<PresentationBinding>>();
+  private readonly surfaces = new Map<number, Map<string, Set<number>>>();
+  private revision = 0;
+  private cached?: PresentationLinksSnapshot;
+
+  getBindings(): readonly PresentationBinding[] {
+    return Array.from(this.bindings.values()).flatMap((slots) => [...slots.values()]);
+  }
+  getBindingsForTarget(targetId: number): readonly PresentationBinding[] {
+    return [...(this.byTarget.get(targetId) ?? [])];
+  }
+  getBindingsForRealm(realmId: number): readonly PresentationBinding[] {
+    return [...(this.bindings.get(realmId)?.values() ?? [])];
+  }
+  private changed(): void {
+    this.revision++;
+    this.cached = undefined;
+  }
+  bind(binding: TargetTextureBinding): void {
+    if (
+      this.bindings.get(binding.realmId)?.get(binding.slot)?.sourceTargetId ===
+      binding.sourceTargetId
+    )
+      return;
+    this.unbind(binding.realmId, binding.slot);
+    let slots = this.bindings.get(binding.realmId);
+    if (!slots) {
+      slots = new Map();
+      this.bindings.set(binding.realmId, slots);
+    }
+    const stored = Object.freeze({
+      realmId: binding.realmId,
+      slot: binding.slot,
+      sourceTargetId: binding.sourceTargetId
+    });
+    slots.set(binding.slot, stored);
+    let targetBindings = this.byTarget.get(binding.sourceTargetId);
+    if (!targetBindings) {
+      targetBindings = new Set();
+      this.byTarget.set(binding.sourceTargetId, targetBindings);
+    }
+    targetBindings.add(stored);
+    this.changed();
+  }
+  unbind(realmId: number, slot: string): void {
+    const slots = this.bindings.get(realmId);
+    const previous = slots?.get(slot);
+    if (!slots || !previous) return;
+    slots.delete(slot);
+    const targetBindings = this.byTarget.get(previous.sourceTargetId);
+    targetBindings?.delete(previous);
+    if (!targetBindings?.size) this.byTarget.delete(previous.sourceTargetId);
+    if (!slots.size) this.bindings.delete(realmId);
+    const surfaces = this.surfaces.get(realmId);
+    surfaces?.delete(slot);
+    if (!surfaces?.size) this.surfaces.delete(realmId);
+    this.changed();
+  }
+  /** Records a validated surface; callers remove it when its entity or material changes. */
+  connectSurface(surface: PresentationSurface): void {
+    if (!this.bindings.get(surface.realmId)?.has(surface.slot))
+      throw new Error('Surface requires a registered target texture binding.');
+    let slots = this.surfaces.get(surface.realmId);
+    if (!slots) {
+      slots = new Map();
+      this.surfaces.set(surface.realmId, slots);
+    }
+    let entities = slots.get(surface.slot);
+    if (!entities) {
+      entities = new Set();
+      slots.set(surface.slot, entities);
+    }
+    if (!entities.has(surface.entityId)) {
+      entities.add(surface.entityId);
+      this.changed();
+    }
+  }
+  disconnectSurface(surface: PresentationSurface): void {
+    const slots = this.surfaces.get(surface.realmId);
+    const entities = slots?.get(surface.slot);
+    if (!entities?.delete(surface.entityId)) return;
+    if (!entities.size) slots!.delete(surface.slot);
+    if (!slots!.size) this.surfaces.delete(surface.realmId);
+    this.changed();
+  }
+  /** Removes surface registrations for entities that are no longer alive. */
+  purgeDeadSurfaces(isAlive: (realmId: number, entityId: number) => boolean): void {
+    let purged = false;
+    for (const [realmId, slots] of this.surfaces) {
+      for (const [slot, entities] of slots) {
+        for (const entityId of [...entities]) {
+          if (!isAlive(realmId, entityId)) {
+            entities.delete(entityId);
+            purged = true;
+          }
+        }
+        if (!entities.size) slots.delete(slot);
+      }
+      if (!slots.size) this.surfaces.delete(realmId);
+    }
+    if (purged) this.changed();
+  }
+  snapshot(): PresentationLinksSnapshot {
+    if (this.cached) return this.cached;
+    const surfaces: PresentationSurface[] = [];
+    for (const [realmId, slots] of this.surfaces)
+      for (const [slot, entities] of slots)
+        for (const entityId of entities) surfaces.push(Object.freeze({ realmId, slot, entityId }));
+    this.cached = Object.freeze({
+      revision: this.revision,
+      bindings: Object.freeze(this.getBindings()),
+      surfaces: Object.freeze(surfaces)
+    });
+    return this.cached;
+  }
+  clear(): void {
+    this.bindings.clear();
+    this.byTarget.clear();
+    this.surfaces.clear();
+    this.changed();
+  }
+}

package/src/multiverse/realm.ts

@@ -0,0 +1,49 @@
+/**
+ * Realm connector contract for domain-specific realms (2D, 3D, Custom).
+ */
+
+import type { GalfusEngine } from '@galfus/transport-types';
+import type { SystemContext } from '../ecs/system';
+import type { RealmId } from '../types';
+
+export { type RealmId };
+export type RealmKind = '2d' | '3d' | 'color' | 'custom';
+
+/**
+ * Base contract implemented by all realm modules to synchronize their ECS state
+ * with the underlying Multiverse and GalfusEngine core.
+ */
+export interface RealmConnector {
+  readonly realmId: RealmId | number;
+  readonly realmKind: RealmKind;
+
+  /**
+   * Binds this realm to the active GalfusEngine ABI driver and initializes native realm resources.
+   */
+  bindEngine(engine: GalfusEngine): void;
+
+  /**
+   * Runs pre-render systems: input, update, preRender (anchors, hierarchies).
+   */
+  preRender?(context: SystemContext): void;
+
+  /**
+   * Synchronizes ECS entity data (transforms, components, lights, cameras) to the core.
+   */
+  sync(context: SystemContext): void;
+
+  /**
+   * Runs post-render systems (metrics, cleanup after GPU dispatch).
+   */
+  postRender?(context: SystemContext): void;
+
+  /**
+   * Resets this realm: clears ECS and local resources and reinitializes native core realm state.
+   */
+  reset?(): void;
+
+  /**
+   * Shuts down and cleans up native resources allocated for this realm in the core.
+   */
+  dispose(): void;
+}

package/src/platform/index.ts

@@ -0,0 +1,2 @@
+export * from './platform';
+export * from './window';

package/src/platform/platform.ts

@@ -0,0 +1,149 @@
+import type {
+  GalfusEngine,
+  GamepadEvent,
+  KeyboardEvent,
+  PlatformCapabilities,
+  PlatformEvent,
+  PointerEvent,
+  WindowEvent
+} from '@galfus/transport-types';
+import { WindowManager } from './window';
+
+export interface PlatformEventMap {
+  window: WindowEvent;
+  pointer: PointerEvent;
+  keyboard: KeyboardEvent;
+  gamepad: GamepadEvent;
+  platform: PlatformEvent;
+}
+
+export type PlatformEventType = keyof PlatformEventMap;
+
+export class PlatformCoordinator {
+  readonly window = new WindowManager();
+  private readonly _eventListeners = new Map<string, Set<(ev: any) => void>>();
+  private _engine: GalfusEngine | null = null;
+
+  bindEngine(engine: GalfusEngine): void {
+    this._engine = engine;
+    this.window.bindEngine(engine);
+  }
+
+  /**
+   * Registers an event listener for a specific platform event category.
+   *
+   * @returns Unsubscribe function to remove the registered listener.
+   */
+  on<T extends PlatformEventType>(
+    type: T,
+    listener: (ev: PlatformEventMap[T]) => void
+  ): () => void {
+    let set = this._eventListeners.get(type);
+    if (!set) {
+      set = new Set();
+      this._eventListeners.set(type, set);
+    }
+    set.add(listener as (ev: any) => void);
+    return () => {
+      set?.delete(listener as (ev: any) => void);
+    };
+  }
+
+  /**
+   * Clears all registered event listeners, or listeners for a specific type.
+   */
+  clearListeners(type?: PlatformEventType): void {
+    if (type) {
+      this._eventListeners.get(type)?.clear();
+    } else {
+      for (const set of this._eventListeners.values()) {
+        set.clear();
+      }
+      this._eventListeners.clear();
+    }
+  }
+
+  /**
+   * Internal dispatcher forwarding a platform event to subscribed listeners.
+   */
+  dispatch(event: PlatformEvent): void {
+    const kindListeners = this._eventListeners.get(event.kind);
+    if (kindListeners && kindListeners.size > 0) {
+      for (const listener of kindListeners) {
+        listener(event);
+      }
+    }
+    const allListeners = this._eventListeners.get('platform');
+    if (allListeners && allListeners.size > 0) {
+      for (const listener of allListeners) {
+        listener(event);
+      }
+    }
+  }
+
+  /**
+   * Pumps platform input events (window, keyboard, mouse, pointer).
+   */
+  pumpEvents(): PlatformEvent[] {
+    if (this._engine && this._engine.platformPumpEvents) {
+      return this._engine.platformPumpEvents();
+    }
+    return [];
+  }
+
+  /**
+   * Queries hardware capabilities and platform feature support flags.
+   */
+  getCapabilities(): PlatformCapabilities | null {
+    if (this._engine) {
+      return this._engine.platformGetCapabilities();
+    }
+    return null;
+  }
+
+  /**
+   * Disposes platform resources and closes active windows.
+   */
+  dispose(): void {
+    this.clearListeners();
+    this.window.dispose();
+    this._engine = null;
+  }
+}
+
+/**
+ * Resolves a normalized lowercase key string from a platform KeyboardEvent or input object.
+ *
+ * @param event The keyboard event from `runtime.on('keyboard', ...)`.
+ * @returns Normalized lowercase key identifier (e.g. `'escape'`, `'w'`, `'enter'`, `'1'`).
+ */
+export function getKey(event: { logicalKey?: string; physicalKey?: string }): string {
+  if (
+    typeof event.logicalKey === 'string' &&
+    event.logicalKey.length > 0 &&
+    event.logicalKey.toLowerCase() !== 'unidentified'
+  ) {
+    return event.logicalKey.toLowerCase();
+  }
+  let phys = String(event.physicalKey ?? '').toLowerCase();
+  const codeMatch = /^code\((.+)\)$/.exec(phys);
+  if (codeMatch) phys = codeMatch[1]!;
+  if (phys.startsWith('key') && phys.length === 4) return phys.slice(3);
+  if (phys.startsWith('digit') && phys.length === 6) return phys.slice(5);
+  return phys;
+}
+
+/**
+ * Checks if a keyboard event matches any of the given key names (case-insensitive).
+ *
+ * @param event The keyboard event.
+ * @param keys Key names to compare against (e.g. `'Escape'`, `'q'`).
+ * @returns `true` if the event key matches any of the target keys.
+ */
+export function isKey(
+  event: { logicalKey?: string; physicalKey?: string },
+  ...keys: string[]
+): boolean {
+  const normalized = getKey(event);
+  return keys.some((k) => k.toLowerCase() === normalized);
+}