@aura3d/core 1.0.6

package/src/EngineLoop.ts

@@ -0,0 +1,83 @@
+import { FixedStepAccumulator } from "./FixedStepAccumulator.js";
+import { Time, type TimeSnapshot } from "./Time.js";
+
+export type LoopMode = "manual" | "raf";
+
+export interface FrameContext {
+  readonly time: TimeSnapshot;
+  readonly fixedSteps: number;
+  readonly interpolationAlpha: number;
+}
+
+export type FrameCallback = (context: FrameContext) => void | Promise<void>;
+
+export interface EngineLoopOptions {
+  readonly mode: LoopMode;
+  readonly fixedDelta: number;
+  readonly maxDelta: number;
+  readonly maxFixedSteps: number;
+  readonly timeScale?: number;
+}
+
+export class EngineLoop {
+  private readonly time: Time;
+  private readonly accumulator: FixedStepAccumulator;
+  private running = false;
+  private rafHandle: number | undefined;
+  private lastTimestamp: number | undefined;
+
+  constructor(
+    private readonly options: EngineLoopOptions,
+    private readonly onFrame: FrameCallback
+  ) {
+    this.time = new Time(options.maxDelta, options.timeScale ?? 1);
+    this.accumulator = new FixedStepAccumulator(options.fixedDelta, options.maxFixedSteps);
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    if (this.options.mode === "raf") {
+      if (typeof requestAnimationFrame !== "function") throw new Error("requestAnimationFrame is unavailable.");
+      this.lastTimestamp = undefined;
+      this.rafHandle = requestAnimationFrame((timestamp) => void this.tickRaf(timestamp));
+    }
+  }
+
+  stop(): void {
+    if (!this.running) return;
+    this.running = false;
+    if (this.rafHandle !== undefined && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(this.rafHandle);
+    }
+    this.rafHandle = undefined;
+  }
+
+  pause(): void {
+    this.stop();
+  }
+
+  resume(): void {
+    this.start();
+  }
+
+  async step(delta: number): Promise<FrameContext> {
+    const time = this.time.update(delta);
+    const fixed = this.accumulator.add(time.delta);
+    const context = Object.freeze({ time, fixedSteps: fixed.steps, interpolationAlpha: fixed.alpha });
+    await this.onFrame(context);
+    return context;
+  }
+
+  snapshot(): TimeSnapshot {
+    return this.time.snapshot();
+  }
+
+  private async tickRaf(timestamp: number): Promise<void> {
+    if (!this.running) return;
+    const delta = this.lastTimestamp === undefined ? 0 : (timestamp - this.lastTimestamp) / 1000;
+    this.lastTimestamp = timestamp;
+    await this.step(delta);
+    if (this.running) this.rafHandle = requestAnimationFrame((nextTimestamp) => void this.tickRaf(nextTimestamp));
+  }
+}

package/src/Errors.ts

@@ -0,0 +1,28 @@
+export class EngineError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+}
+
+export class LifecycleError extends EngineError {
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(`LIFECYCLE_${code}`, message, options);
+  }
+}
+
+export class ValidationError extends EngineError {
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(`VALIDATION_${code}`, message, options);
+  }
+}
+
+export class ResourceError extends EngineError {
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(`RESOURCE_${code}`, message, options);
+  }
+}

package/src/EventBus.ts

@@ -0,0 +1,52 @@
+export type EventMapBase = object;
+export type EventListener<T> = (event: T) => void;
+export type EventErrorHandler = (error: unknown, eventName: string) => void;
+
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+export class EventBus<TEvents extends EventMapBase> {
+  private readonly listeners = new Map<keyof TEvents, Set<EventListener<TEvents[keyof TEvents]>>>();
+  private readonly onceListeners = new WeakSet<EventListener<TEvents[keyof TEvents]>>();
+
+  constructor(private readonly onListenerError?: EventErrorHandler) {}
+
+  on<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription {
+    const set = this.listeners.get(eventName) ?? new Set<EventListener<TEvents[keyof TEvents]>>();
+    set.add(listener as EventListener<TEvents[keyof TEvents]>);
+    this.listeners.set(eventName, set);
+    return { unsubscribe: () => this.off(eventName, listener) };
+  }
+
+  once<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription {
+    const subscription = this.on(eventName, listener);
+    this.onceListeners.add(listener as EventListener<TEvents[keyof TEvents]>);
+    return subscription;
+  }
+
+  off<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): void {
+    const set = this.listeners.get(eventName);
+    set?.delete(listener as EventListener<TEvents[keyof TEvents]>);
+    if (set?.size === 0) this.listeners.delete(eventName);
+  }
+
+  emit<K extends keyof TEvents>(eventName: K, event: TEvents[K]): void {
+    const snapshot = [...(this.listeners.get(eventName) ?? [])];
+    for (const listener of snapshot) {
+      if (!this.listeners.get(eventName)?.has(listener)) continue;
+      try {
+        (listener as EventListener<TEvents[K]>)(event);
+      } catch (error) {
+        this.onListenerError?.(error, String(eventName));
+      }
+      if (this.onceListeners.has(listener)) {
+        this.listeners.get(eventName)?.delete(listener);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/FixedStepAccumulator.ts

@@ -0,0 +1,39 @@
+export interface FixedStepResult {
+  readonly steps: number;
+  readonly alpha: number;
+  readonly droppedTime: number;
+}
+
+export class FixedStepAccumulator {
+  private accumulator = 0;
+
+  constructor(
+    readonly fixedDelta: number,
+    readonly maxSteps: number
+  ) {
+    if (!Number.isFinite(fixedDelta) || fixedDelta <= 0) throw new RangeError("fixedDelta must be finite and positive.");
+    if (!Number.isInteger(maxSteps) || maxSteps <= 0) throw new RangeError("maxSteps must be a positive integer.");
+  }
+
+  add(delta: number): FixedStepResult {
+    if (!Number.isFinite(delta) || delta < 0) throw new RangeError("delta must be finite and non-negative.");
+    this.accumulator += delta;
+    const possibleSteps = Math.floor(this.accumulator / this.fixedDelta);
+    const steps = Math.min(possibleSteps, this.maxSteps);
+    this.accumulator -= steps * this.fixedDelta;
+    let droppedTime = 0;
+    if (possibleSteps > this.maxSteps) {
+      droppedTime = this.accumulator;
+      this.accumulator = 0;
+    }
+    return Object.freeze({ steps, alpha: this.alpha, droppedTime });
+  }
+
+  get alpha(): number {
+    return this.accumulator / this.fixedDelta;
+  }
+
+  reset(): void {
+    this.accumulator = 0;
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,67 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+export interface LogEntry {
+  readonly level: Exclude<LogLevel, "silent">;
+  readonly category: string;
+  readonly message: string;
+  readonly timestamp: number;
+  readonly data?: unknown;
+}
+
+export type LogSink = (entry: LogEntry) => void;
+
+const levelRank: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 50
+};
+
+export class Logger {
+  private readonly sinks = new Set<LogSink>();
+  private readonly lastEmitted = new Map<string, number>();
+
+  constructor(private level: LogLevel = "info") {}
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  addSink(sink: LogSink): () => void {
+    this.sinks.add(sink);
+    return () => this.sinks.delete(sink);
+  }
+
+  debug(category: string, message: string, data?: unknown): void {
+    this.log("debug", category, message, data);
+  }
+
+  info(category: string, message: string, data?: unknown): void {
+    this.log("info", category, message, data);
+  }
+
+  warn(category: string, message: string, data?: unknown): void {
+    this.log("warn", category, message, data);
+  }
+
+  error(category: string, message: string, data?: unknown): void {
+    this.log("error", category, message, data);
+  }
+
+  log(level: Exclude<LogLevel, "silent">, category: string, message: string, data?: unknown, rateLimitMs = 0): void {
+    if (levelRank[level] < levelRank[this.level]) return;
+    const key = `${level}:${category}:${message}`;
+    const now = Date.now();
+    if (rateLimitMs > 0 && now - (this.lastEmitted.get(key) ?? -Infinity) < rateLimitMs) return;
+    this.lastEmitted.set(key, now);
+    const entry: LogEntry = Object.freeze({ level, category, message, timestamp: now, data });
+    for (const sink of [...this.sinks]) {
+      try {
+        sink(entry);
+      } catch {
+        this.sinks.delete(sink);
+      }
+    }
+  }
+}

package/src/ResourceScope.ts

@@ -0,0 +1,55 @@
+import { DisposableStack, type Disposable } from "./Disposable.js";
+
+export interface ResourceLeak {
+  name: string;
+  resourceCount: number;
+  childScopes: ResourceLeak[];
+}
+
+export class ResourceScope implements Disposable {
+  private readonly stack = new DisposableStack();
+  private readonly children = new Set<ResourceScope>();
+  private disposed = false;
+
+  constructor(readonly name: string) {}
+
+  use<T extends Disposable>(resource: T): T {
+    if (this.disposed) throw new Error(`Resource scope ${this.name} is disposed.`);
+    return this.stack.use(resource);
+  }
+
+  createChild(name: string): ResourceScope {
+    if (this.disposed) throw new Error(`Resource scope ${this.name} is disposed.`);
+    const child = new ResourceScope(name);
+    this.children.add(child);
+    return child;
+  }
+
+  leakSnapshot(): ResourceLeak {
+    return {
+      name: this.name,
+      resourceCount: this.stack.size,
+      childScopes: [...this.children].map((child) => child.leakSnapshot())
+    };
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    const errors: unknown[] = [];
+    for (const child of [...this.children].reverse()) {
+      try {
+        await child.dispose();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.children.clear();
+    try {
+      await this.stack.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length > 0) throw new AggregateError(errors, `Resource scope ${this.name} failed to dispose.`);
+  }
+}

package/src/Scheduler.ts

@@ -0,0 +1,94 @@
+import { ValidationError } from "./Errors.js";
+
+export const SystemPhase = Object.freeze({
+  Platform: "platform",
+  Tasks: "tasks",
+  Fixed: "fixed",
+  Update: "update",
+  Scene: "scene",
+  Render: "render",
+  Present: "present",
+  Cleanup: "cleanup"
+});
+
+export type SystemPhase = (typeof SystemPhase)[keyof typeof SystemPhase];
+
+export interface SchedulerContext {
+  readonly phase: SystemPhase;
+  readonly fixedStepIndex?: number;
+}
+
+export interface ScheduledTask {
+  readonly id: string;
+  readonly phase: SystemPhase;
+  readonly dependsOn?: readonly string[];
+  readonly enabled?: boolean;
+  run(context: SchedulerContext): void | Promise<void>;
+}
+
+const phaseOrder = Object.values(SystemPhase);
+
+export class Scheduler {
+  private readonly tasks = new Map<string, ScheduledTask>();
+
+  add(task: ScheduledTask): void {
+    if (this.tasks.has(task.id)) throw new ValidationError("DUPLICATE_TASK", `Task ${task.id} already exists.`);
+    this.tasks.set(task.id, task);
+  }
+
+  remove(id: string): void {
+    this.tasks.delete(id);
+  }
+
+  getExecutionPlan(): readonly ScheduledTask[] {
+    const ordered: ScheduledTask[] = [];
+    const byPhase = new Map<SystemPhase, ScheduledTask[]>();
+    for (const task of this.tasks.values()) {
+      if (task.enabled === false) continue;
+      const list = byPhase.get(task.phase) ?? [];
+      list.push(task);
+      byPhase.set(task.phase, list);
+    }
+
+    for (const phase of phaseOrder) {
+      ordered.push(...this.sortPhase(byPhase.get(phase) ?? []));
+    }
+    return Object.freeze(ordered);
+  }
+
+  async runPhase(phase: SystemPhase, fixedStepIndex?: number): Promise<void> {
+    for (const task of this.getExecutionPlan()) {
+      if (task.phase === phase) {
+        const context: SchedulerContext = fixedStepIndex === undefined ? { phase } : { phase, fixedStepIndex };
+        await task.run(context);
+      }
+    }
+  }
+
+  private sortPhase(tasks: readonly ScheduledTask[]): ScheduledTask[] {
+    const taskIds = new Set(tasks.map((task) => task.id));
+    const visiting = new Set<string>();
+    const visited = new Set<string>();
+    const output: ScheduledTask[] = [];
+    const taskById = new Map(tasks.map((task) => [task.id, task]));
+
+    const visit = (task: ScheduledTask): void => {
+      if (visited.has(task.id)) return;
+      if (visiting.has(task.id)) throw new ValidationError("TASK_CYCLE", `Scheduler cycle includes ${task.id}.`);
+      visiting.add(task.id);
+      for (const dependency of task.dependsOn ?? []) {
+        const dep = this.tasks.get(dependency);
+        if (!dep || dep.enabled === false) throw new ValidationError("MISSING_DEPENDENCY", `Task ${task.id} depends on missing task ${dependency}.`);
+        if (dep.phase !== task.phase) throw new ValidationError("CROSS_PHASE_DEPENDENCY", `Task ${task.id} depends on ${dependency} in a different phase.`);
+        if (!taskIds.has(dependency)) throw new ValidationError("MISSING_DEPENDENCY", `Task ${task.id} depends on missing phase peer ${dependency}.`);
+        visit(taskById.get(dependency)!);
+      }
+      visiting.delete(task.id);
+      visited.add(task.id);
+      output.push(task);
+    };
+
+    for (const task of tasks) visit(task);
+    return output;
+  }
+}

package/src/TaskQueue.ts

@@ -0,0 +1,50 @@
+export interface TaskHandle {
+  readonly id: number;
+  cancel(): void;
+  readonly cancelled: boolean;
+}
+
+interface QueuedTask {
+  handle: MutableTaskHandle;
+  task: () => void | Promise<void>;
+}
+
+class MutableTaskHandle implements TaskHandle {
+  cancelled = false;
+  constructor(readonly id: number) {}
+  cancel(): void {
+    this.cancelled = true;
+  }
+}
+
+export class TaskQueue {
+  private queue: QueuedTask[] = [];
+  private nextId = 1;
+
+  enqueue(task: () => void | Promise<void>): TaskHandle {
+    const handle = new MutableTaskHandle(this.nextId++);
+    this.queue.push({ handle, task });
+    return handle;
+  }
+
+  get size(): number {
+    return this.queue.length;
+  }
+
+  async flush(): Promise<void> {
+    const errors: unknown[] = [];
+    while (this.queue.length > 0) {
+      const batch = this.queue;
+      this.queue = [];
+      for (const item of batch) {
+        if (item.handle.cancelled) continue;
+        try {
+          await item.task();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, "One or more queued tasks failed.");
+  }
+}

package/src/Time.ts

@@ -0,0 +1,54 @@
+export interface TimeSnapshot {
+  readonly frame: number;
+  readonly elapsed: number;
+  readonly unscaledElapsed: number;
+  readonly delta: number;
+  readonly unscaledDelta: number;
+  readonly smoothedDelta: number;
+  readonly timeScale: number;
+}
+
+export class Time {
+  private frameValue = 0;
+  private elapsedValue = 0;
+  private unscaledElapsedValue = 0;
+  private deltaValue = 0;
+  private unscaledDeltaValue = 0;
+  private smoothedDeltaValue = 0;
+
+  constructor(
+    private readonly maxDelta: number,
+    private timeScaleValue = 1
+  ) {
+    if (!Number.isFinite(maxDelta) || maxDelta <= 0) throw new RangeError("maxDelta must be finite and positive.");
+    this.setTimeScale(timeScaleValue);
+  }
+
+  setTimeScale(timeScale: number): void {
+    if (!Number.isFinite(timeScale) || timeScale < 0) throw new RangeError("timeScale must be finite and non-negative.");
+    this.timeScaleValue = timeScale;
+  }
+
+  update(unscaledDelta: number): TimeSnapshot {
+    if (!Number.isFinite(unscaledDelta) || unscaledDelta < 0) throw new RangeError("delta must be finite and non-negative.");
+    this.unscaledDeltaValue = Math.min(unscaledDelta, this.maxDelta);
+    this.deltaValue = this.unscaledDeltaValue * this.timeScaleValue;
+    this.unscaledElapsedValue += this.unscaledDeltaValue;
+    this.elapsedValue += this.deltaValue;
+    this.frameValue++;
+    this.smoothedDeltaValue = this.frameValue === 1 ? this.deltaValue : this.smoothedDeltaValue * 0.9 + this.deltaValue * 0.1;
+    return this.snapshot();
+  }
+
+  snapshot(): TimeSnapshot {
+    return Object.freeze({
+      frame: this.frameValue,
+      elapsed: this.elapsedValue,
+      unscaledElapsed: this.unscaledElapsedValue,
+      delta: this.deltaValue,
+      unscaledDelta: this.unscaledDeltaValue,
+      smoothedDelta: this.smoothedDeltaValue,
+      timeScale: this.timeScaleValue
+    });
+  }
+}