@galfus/engine 0.0.0-stage → 0.31.0-alpha

package/src/platform/window.ts

@@ -0,0 +1,181 @@
+/**
+ * WindowManager coordinates native OS and browser canvas display surfaces.
+ */
+
+import type { GalfusEngine, WindowConfig, WindowState } from '@galfus/transport-types';
+import { IdAllocator, type WindowId } from '../types';
+
+export type CursorGrabMode = 'none' | 'confined' | 'locked';
+
+export type CursorIconName =
+  'default' | 'pointer' | 'grab' | 'grabbing' | 'crosshair' | 'text' | 'move' | 'wait';
+
+const CURSOR_GRAB_MAP: Record<CursorGrabMode, number> = {
+  none: 0,
+  confined: 1,
+  locked: 2
+};
+
+const CURSOR_ICON_MAP: Record<CursorIconName, number> = {
+  default: 0,
+  pointer: 1,
+  grab: 2,
+  grabbing: 3,
+  crosshair: 4,
+  text: 5,
+  move: 6,
+  wait: 7
+};
+
+export interface WindowCreateOptions {
+  title?: string;
+  size?: [number, number];
+  position?: [number, number];
+  resizable?: boolean;
+  decorations?: boolean;
+  transparent?: boolean;
+  initialState?: WindowState;
+  canvasId?: string;
+}
+
+export class WindowManager {
+  private _engine: GalfusEngine | null = null;
+  private readonly _idAllocator = new IdAllocator<WindowId>(1);
+  private readonly _openWindows = new Set<WindowId>();
+  private readonly _lifecycleListeners = new Set<(windowId: WindowId, opened: boolean) => void>();
+
+  /** Observes actual window creation and closure, independent of close requests. */
+  onLifecycle(listener: (windowId: WindowId, opened: boolean) => void): () => void {
+    this._lifecycleListeners.add(listener);
+    return () => {
+      this._lifecycleListeners.delete(listener);
+    };
+  }
+
+  bindEngine(engine: GalfusEngine): void {
+    this._engine = engine;
+  }
+
+  /**
+   * Creates an OS window or binds a browser canvas, returning a strongly-typed WindowId.
+   */
+  create(options: WindowCreateOptions = {}): WindowId {
+    const windowId = this._idAllocator.allocate('WindowId');
+    if (this._engine) {
+      const config: WindowConfig = {
+        id: windowId,
+        title: options.title ?? 'Galfus Engine',
+        size: options.size,
+        position: options.position,
+        resizable: options.resizable ?? true,
+        decorations: options.decorations ?? true,
+        transparent: options.transparent ?? false,
+        initialState: options.initialState ?? 'windowed',
+        canvasId: options.canvasId
+      };
+      this._engine.windowCreate(config);
+    }
+    this._openWindows.add(windowId);
+    for (const listener of this._lifecycleListeners) listener(windowId, true);
+    return windowId;
+  }
+
+  /**
+   * Closes and destroys an open window surface.
+   */
+  close(windowId: WindowId): void {
+    if (!this._openWindows.has(windowId)) return;
+    if (this._engine) {
+      this._engine.windowClose(windowId);
+    }
+    this._openWindows.delete(windowId);
+    for (const listener of this._lifecycleListeners) listener(windowId, false);
+  }
+
+  /**
+   * Updates the window title bar.
+   */
+  setTitle(windowId: WindowId, title: string): void {
+    if (this._engine) {
+      this._engine.windowSetTitle(windowId, title);
+    }
+  }
+
+  /** Enables or disables input method composition for a window. */
+  setImeAllowed(windowId: WindowId, allowed: boolean): void {
+    if (this._openWindows.has(windowId))
+      this._engine?.windowSetImeAllowed(windowId, allowed ? 1 : 0);
+  }
+
+  /** @internal Controls whether the platform captures Tab navigation for this window. */
+  setTabCapture(windowId: WindowId, enabled: boolean): void {
+    this._engine?.windowSetTabCapture?.(windowId, enabled ? 1 : 0);
+  }
+
+  /** @internal Requests keyboard focus for the platform input surface. */
+  requestInputFocus(windowId: WindowId): void {
+    this._engine?.windowRequestInputFocus?.(windowId);
+  }
+
+  /** Sets the input method candidate area in physical window pixels. */
+  setImeCursorArea(windowId: WindowId, x: number, y: number, width: number, height: number): void {
+    this._engine?.windowSetImeCursorArea(windowId, x, y, width, height);
+  }
+
+  /**
+   * Retrieves the physical inner surface dimensions [width, height].
+   */
+  getSize(windowId: WindowId): [number, number] {
+    if (this._engine && this._engine.platformGetWindowSize) {
+      return this._engine.platformGetWindowSize(windowId);
+    }
+    return [0, 0];
+  }
+
+  /**
+   * Explicitly updates the window / swapchain surface size in the Multiverse.
+   */
+  updateSize(windowId: WindowId, width: number, height: number): void {
+    if (this._engine) {
+      this._engine.multiverseUpdateWindowSize(windowId, width, height);
+    }
+  }
+
+  /**
+   * Updates cursor grab mode ('none' | 'confined' | 'locked').
+   * 'locked' enables Pointer Lock for FPS and orbit cameras.
+   */
+  setCursorGrab(windowId: WindowId, mode: CursorGrabMode | number): void {
+    const numericMode = typeof mode === 'string' ? (CURSOR_GRAB_MAP[mode] ?? 0) : mode;
+    if (this._engine) {
+      this._engine.windowSetCursorGrab(windowId, numericMode);
+    }
+  }
+
+  /**
+   * Updates cursor visual appearance icon ('default' | 'pointer' | 'grab' | 'grabbing' | 'crosshair' | 'text' | 'move' | 'wait').
+   */
+  setCursorIcon(windowId: WindowId, icon: CursorIconName | number): void {
+    const numericIcon = typeof icon === 'string' ? (CURSOR_ICON_MAP[icon] ?? 0) : icon;
+    if (this._engine) {
+      this._engine.windowSetCursorIcon(windowId, numericIcon);
+    }
+  }
+
+  /**
+   * Sets the visual application icon of this window using raw image bytes (ICO, PNG, WebP, JPEG).
+   * Follows payload-first convention: (windowId, data).
+   */
+  setIcon(windowId: WindowId, data: Uint8Array): void {
+    if (this._engine && this._engine.windowSetIcon) {
+      this._engine.windowSetIcon(windowId, data, data.byteLength);
+    }
+  }
+
+  /**
+   * Disposes and closes all active windows.
+   */
+  dispose(): void {
+    for (const windowId of [...this._openWindows]) this.close(windowId);
+  }
+}

package/src/realm2d/components.ts

@@ -0,0 +1,254 @@
+/**
+ * Realm 2D component declarations.
+ * Incorporates spatial Model2D with contiguous local/world matrices and SpatialDirtyFlags.
+ */
+
+import type {
+  Camera2DDesc,
+  Light2DDesc,
+  ParticleEmitter2DDesc,
+  Shape2DDesc,
+  Sprite2DDesc,
+  Svg2DDesc
+} from '@galfus/transport-types';
+import type { Component } from '../ecs/component';
+import { mat2d, type Mat2d, vec2, type Vec2 } from '../math/index';
+import { SpatialDirtyFlags } from '../spatial/flags';
+
+const SCRATCH_P2D = vec2.create();
+const SCRATCH_S2D = vec2.create();
+
+/**
+ * 2D Spatial node component holding dual 2D affine matrices (local and resolved world)
+ * and a two-stage dirty flag state machine (LocalDirty -> WorldDirty -> Clean).
+ */
+export class Model2DComponent implements Component {
+  readonly type = 'Model2D' as const;
+  readonly modelId: number;
+  readonly localMatrix: Mat2d;
+  readonly worldMatrix: Mat2d;
+  private _zLayer = 0;
+  private _drawOrder = 0;
+  flags: SpatialDirtyFlags;
+
+  constructor(modelId: number, initialLocal?: Float32Array | number[]) {
+    this.modelId = modelId;
+    this.localMatrix = mat2d.create();
+    this.worldMatrix = mat2d.create();
+    if (initialLocal) {
+      this.localMatrix.set(initialLocal);
+      this.worldMatrix.set(initialLocal);
+    }
+    this.flags = SpatialDirtyFlags.LocalDirty | SpatialDirtyFlags.WorldDirty;
+  }
+
+  get zLayer(): number {
+    return this._zLayer;
+  }
+  set zLayer(value: number) {
+    if (value !== this._zLayer) {
+      this._zLayer = value;
+      this.flags |= SpatialDirtyFlags.WorldDirty;
+    }
+  }
+  get drawOrder(): number {
+    return this._drawOrder;
+  }
+  set drawOrder(value: number) {
+    if (value !== this._drawOrder) {
+      this._drawOrder = value;
+      this.flags |= SpatialDirtyFlags.WorldDirty;
+    }
+  }
+
+  setPosition(x: number, y: number): this;
+  setPosition(position: [number, number] | Vec2): this;
+  setPosition(xOrPos: number | [number, number] | Vec2, y?: number): this {
+    if (typeof xOrPos === 'number') {
+      this.localMatrix[4] = xOrPos;
+      this.localMatrix[5] = y ?? 0;
+    } else {
+      this.localMatrix[4] = xOrPos[0];
+      this.localMatrix[5] = xOrPos[1];
+    }
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+    return this;
+  }
+
+  setRotation(rad: number): this {
+    vec2.set(SCRATCH_P2D, this.localMatrix[4], this.localMatrix[5]);
+    const sx = Math.hypot(this.localMatrix[0], this.localMatrix[1]);
+    const sy =
+      Math.hypot(this.localMatrix[2], this.localMatrix[3]) *
+      (this.localMatrix[0] * this.localMatrix[3] - this.localMatrix[1] * this.localMatrix[2] < 0
+        ? -1
+        : 1);
+    vec2.set(SCRATCH_S2D, sx, sy);
+    mat2d.fromRotationTranslationScale(this.localMatrix, SCRATCH_P2D, rad, SCRATCH_S2D);
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+    return this;
+  }
+
+  setScale(x: number, y: number): this;
+  setScale(scale: [number, number] | Vec2): this;
+  setScale(xOrScale: number | [number, number] | Vec2, y?: number): this {
+    const x = typeof xOrScale === 'number' ? xOrScale : xOrScale[0];
+    const sy = typeof xOrScale === 'number' ? (y ?? 1) : xOrScale[1];
+    const rotation = Math.atan2(this.localMatrix[1], this.localMatrix[0]);
+    vec2.set(SCRATCH_P2D, this.localMatrix[4], this.localMatrix[5]);
+    vec2.set(SCRATCH_S2D, x, sy);
+    mat2d.fromRotationTranslationScale(this.localMatrix, SCRATCH_P2D, rotation, SCRATCH_S2D);
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+    return this;
+  }
+
+  setTRS(
+    position?: [number, number] | Vec2,
+    rotationRad = 0,
+    scale?: [number, number] | Vec2
+  ): this {
+    const p = (position ?? [0, 0]) as unknown as Vec2;
+    const s = (scale ?? [1, 1]) as unknown as Vec2;
+    mat2d.fromRotationTranslationScale(this.localMatrix, p, rotationRad, s);
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+    return this;
+  }
+
+  setLocalMatrix(mat: Float32Array | number[]): this {
+    this.localMatrix.set(mat);
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+    return this;
+  }
+
+  setWorldMatrix(mat: Float32Array | number[]): this {
+    this.worldMatrix.set(mat);
+    this.flags |= SpatialDirtyFlags.WorldDirty;
+    return this;
+  }
+
+  markLocalDirty(): void {
+    this.flags |= SpatialDirtyFlags.LocalDirty;
+  }
+
+  markWorldDirty(): void {
+    this.flags |= SpatialDirtyFlags.WorldDirty;
+  }
+
+  get isDirty(): boolean {
+    return this.flags !== SpatialDirtyFlags.Clean;
+  }
+
+  set isDirty(val: boolean) {
+    if (val) {
+      this.flags |= SpatialDirtyFlags.WorldDirty;
+    } else {
+      this.flags = SpatialDirtyFlags.Clean;
+    }
+  }
+}
+
+export function createModel2D(
+  modelId: number,
+  initialLocal?: Float32Array | number[]
+): Model2DComponent {
+  return new Model2DComponent(modelId, initialLocal);
+}
+
+export interface Sprite2DComponent extends Component {
+  readonly type: 'Sprite2D';
+  readonly spriteId: number;
+  desc: Sprite2DDesc;
+  isDirty: boolean;
+}
+
+export function createSprite2D(spriteId: number, desc: Sprite2DDesc): Sprite2DComponent {
+  return {
+    type: 'Sprite2D',
+    spriteId,
+    desc,
+    isDirty: true
+  };
+}
+
+export interface Shape2DComponent extends Component {
+  readonly type: 'Shape2D';
+  readonly shapeId: number;
+  desc: Shape2DDesc;
+  isDirty: boolean;
+}
+
+export function createShape2D(shapeId: number, desc: Shape2DDesc): Shape2DComponent {
+  return {
+    type: 'Shape2D',
+    shapeId,
+    desc,
+    isDirty: true
+  };
+}
+
+export interface Light2DComponent extends Component {
+  readonly type: 'Light2D';
+  readonly lightId: number;
+  desc: Light2DDesc;
+  isDirty: boolean;
+}
+
+export function createLight2D(lightId: number, desc: Light2DDesc): Light2DComponent {
+  return {
+    type: 'Light2D',
+    lightId,
+    desc,
+    isDirty: true
+  };
+}
+
+export interface Camera2DComponent extends Component {
+  readonly type: 'Camera2D';
+  readonly cameraId: number;
+  desc: Camera2DDesc;
+  isDirty: boolean;
+}
+
+export function createCamera2D(cameraId: number, desc: Camera2DDesc): Camera2DComponent {
+  return {
+    type: 'Camera2D',
+    cameraId,
+    desc,
+    isDirty: true
+  };
+}
+
+export interface Svg2DComponent extends Component {
+  readonly type: 'Svg2D';
+  readonly svgId: number;
+  desc: Svg2DDesc;
+  isDirty: boolean;
+}
+
+export function createSvg2D(svgId: number, desc: Svg2DDesc): Svg2DComponent {
+  return {
+    type: 'Svg2D',
+    svgId,
+    desc,
+    isDirty: true
+  };
+}
+
+export interface ParticleEmitter2DComponent extends Component {
+  readonly type: 'ParticleEmitter2D';
+  readonly emitterId: number;
+  desc: ParticleEmitter2DDesc;
+  isDirty: boolean;
+}
+
+export function createParticleEmitter2D(
+  emitterId: number,
+  desc: ParticleEmitter2DDesc
+): ParticleEmitter2DComponent {
+  return {
+    type: 'ParticleEmitter2D',
+    emitterId,
+    desc,
+    isDirty: true
+  };
+}

package/src/realm2d/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Realm 2D module.
+ */
+export * from './components';
+export * from './presets/index';
+export * as presets2D from './presets/index';
+export * from './realm';
+export * from './sync';
+export * from './utils/index';
+export * as utils2D from './utils/index';
+
+export { Collider2DComponent, createCollider2D } from '../collision/components';

package/src/realm2d/presets/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Realm 2D presets for quick entity and camera setup.
+ */
+
+import type { Camera2DDesc, Light2DDesc } from '@galfus/transport-types';
+
+export function createOrthoCamera2DPreset(
+  options: {
+    orthoScale?: number;
+    near?: number;
+    far?: number;
+    cameraSlot?: number;
+  } = {}
+): Camera2DDesc {
+  return {
+    orthoScale: options.orthoScale ?? 1.0,
+    near: options.near ?? 0.0,
+    far: options.far ?? 1000.0,
+    cameraSlot: options.cameraSlot ?? 0,
+    active: true
+  };
+}
+
+export function createPointLight2DPreset(
+  options: {
+    color?: [number, number, number];
+    intensity?: number;
+    range?: number;
+  } = {}
+): Light2DDesc {
+  return {
+    color: options.color ?? [1.0, 1.0, 1.0],
+    intensity: options.intensity ?? 1.0,
+    range: options.range ?? 200.0
+  };
+}