murow 0.0.60 → 0.0.71

package/src/core/loop/drivers/index.ts

@@ -1,3 +0,0 @@
-export * from "./immediate";
-export * from "./raf";
-export * from "./timeout";

package/src/core/loop/drivers/raf.ts

@@ -1,67 +0,0 @@
-import { LoopDriver } from "../loop";
-
-/**
- * Client-side game loop driver using requestAnimationFrame.
- *
- * This driver synchronizes updates with the browser's display refresh rate (typically 60 FPS),
- * providing smooth rendering and automatic throttling when the tab is not visible.
- *
- * Delta time is automatically calculated between frames and passed to the update callback in seconds.
- *
- * @example
- * ```typescript
- * const driver = new RafDriver((dt) => {
- *   player.update(dt);
- *   renderer.render();
- * });
- * driver.start();
- * ```
- */
-export class RafDriver implements LoopDriver {
-    /**
-     * @param update - Callback invoked each frame with delta time in seconds
-     */
-    constructor(public update: (dt: number) => void) { }
-
-    private last = performance.now();
-    private running = false;
-    private rafId: number | null = null;
-
-    /**
-     * Starts the game loop using requestAnimationFrame.
-     * 
-     * Resets timing to prevent large initial delta.
-     */
-    start() {
-        this.running = true;
-        this.last = performance.now();
-        this.rafId = requestAnimationFrame(this.loop);
-    }
-
-    /**
-     * Stops the game loop and cancels any pending animation frame.
-     */
-    stop() {
-        this.running = false;
-        if (this.rafId !== null) {
-            cancelAnimationFrame(this.rafId);
-            this.rafId = null;
-        }
-    }
-
-    /**
-     * Internal loop method that calculates delta time and schedules the next frame.
-     * 
-     * Delta time is provided in seconds.
-     */
-    loop = () => {
-        if (!this.running) return;
-
-        const now = performance.now();
-        const dt = (now - this.last) / 1000;
-        this.last = now;
-
-        this.update(dt);
-        requestAnimationFrame(this.loop);
-    };
-}

package/src/core/loop/drivers/timeout.ts

@@ -1,77 +0,0 @@
-import { LoopDriver } from "../loop";
-
-/**
- * Minimal delay for setTimeout-based loop scheduling.
- * Using 1ms allows the event loop to process I/O while still maintaining high tick rates.
- */
-const TIMEOUT_DELAY = 1;
-
-/**
- * Server-side game loop driver using setTimeout.
- *
- * This driver provides a more controlled alternative to setImmediate, running the game loop
- * with a minimal delay (1ms) between iterations. This ensures the event loop can process
- * I/O operations while maintaining high tick rates.
- *
- * Unlike setImmediate which runs as fast as possible, setTimeout provides better I/O responsiveness
- * by yielding to the event loop between ticks with a minimal delay.
- *
- * Delta time is automatically calculated between iterations and passed to the update callback in seconds.
- *
- * **Note:** This driver is designed for Node.js/Bun server environments. For maximum performance
- * without I/O concerns, use ImmediateDriver instead.
- *
- * @example
- * ```typescript
- * const driver = new TimeoutDriver((dt) => {
- *   world.tick(dt);
- *   broadcastState();
- * });
- * driver.start();
- * ```
- */
-export class TimeoutDriver implements LoopDriver {
-    /**
-     * @param update - Callback invoked each tick with delta time in seconds
-     */
-    constructor(public update: (dt: number) => void) { }
-
-    private last = performance.now();
-    private running = false;
-
-    /**
-     * Starts the game loop using setTimeout with minimal delay.
-     * 
-     * Resets timing to prevent large initial delta.
-     */
-    start() {
-        this.running = true;
-        this.last = performance.now();
-        this.loop();
-    }
-
-    /**
-     * Stops the game loop.
-     * 
-     * Note: Does not cancel already queued setTimeout callbacks.
-     */
-    stop() {
-        this.running = false;
-    }
-
-    /**
-     * Internal loop method that calculates delta time and schedules the next iteration.
-     * 
-     * Delta time is provided in seconds. Uses 1ms delay to allow I/O processing.
-     */
-    loop = () => {
-        if (!this.running) return;
-
-        const now = performance.now();
-        const dt = (now - this.last) / 1000;
-        this.last = now;
-
-        this.update(dt);
-        setTimeout(this.loop, TIMEOUT_DELAY);
-    };
-}

package/src/core/loop/index.ts

@@ -1,2 +0,0 @@
-export * from './loop';
-export * from './drivers';

package/src/core/loop/loop.test.ts

@@ -1,414 +0,0 @@
-import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { RafDriver, ImmediateDriver, TimeoutDriver } from "./drivers";
-import { createDriver } from "./loop";
-
-// Mock requestAnimationFrame for testing (Node.js doesn't have it)
-(() => {
-  let rafId = 0;
-  const callbacks = new Map<number, FrameRequestCallback>();
-  let running = false;
-  let intervalId: Timer | null = null;
-
-  (globalThis as any).requestAnimationFrame = (callback: FrameRequestCallback): number => {
-    const id = ++rafId;
-    callbacks.set(id, callback);
-
-    if (!running) {
-      running = true;
-      intervalId = setInterval(() => {
-        const now = performance.now();
-        const cbs = Array.from(callbacks.entries());
-        callbacks.clear();
-        for (const [_, cb] of cbs) {
-          cb(now);
-        }
-        if (callbacks.size === 0) {
-          running = false;
-          if (intervalId) clearInterval(intervalId);
-        }
-      }, 16); // ~60fps
-    }
-
-    return id;
-  };
-
-  (globalThis as any).cancelAnimationFrame = (id: number): void => {
-    callbacks.delete(id);
-    if (callbacks.size === 0) {
-      running = false;
-      if (intervalId) clearInterval(intervalId);
-    }
-  };
-})();
-
-describe("Loop", () => {
-  describe("createDriver", () => {
-    test("should create RafDriver for client type", () => {
-      const driver = createDriver('client', () => {});
-      expect(driver).toBeInstanceOf(RafDriver);
-    });
-
-    test("should create ImmediateDriver for server-immediate type", () => {
-      const driver = createDriver('server-immediate', () => {});
-      expect(driver).toBeInstanceOf(ImmediateDriver);
-    });
-
-    test("should create TimeoutDriver for server-timeout type", () => {
-      const driver = createDriver('server-timeout', () => {});
-      expect(driver).toBeInstanceOf(TimeoutDriver);
-    });
-
-    test("should pass update callback to driver", () => {
-      let called = false;
-      const update = () => { called = true; };
-      const driver = createDriver('server-immediate', update);
-
-      // Access the update function directly
-      (driver as ImmediateDriver).update(0.016);
-      expect(called).toBe(true);
-    });
-  });
-
-  describe("ImmediateDriver", () => {
-    let driver: ImmediateDriver;
-    let updateCalls: number[] = [];
-
-    beforeEach(() => {
-      updateCalls = [];
-      driver = new ImmediateDriver((dt) => {
-        updateCalls.push(dt);
-      });
-    });
-
-    afterEach(() => {
-      driver.stop();
-    });
-
-    test("should initialize without starting", () => {
-      expect(updateCalls.length).toBe(0);
-    });
-
-    test("should call update with delta time", async () => {
-      driver.start();
-
-      // Wait for a few ticks
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-
-      // Delta times should be positive and in seconds
-      for (const dt of updateCalls) {
-        expect(dt).toBeGreaterThan(0);
-        expect(dt).toBeLessThan(1); // Should be less than 1 second
-      }
-    });
-
-    test("should stop calling update after stop", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      const callsAfterStop = updateCalls.length;
-
-      // Wait a bit more
-      await new Promise(resolve => setTimeout(resolve, 20));
-
-      // Should not have significantly more calls (allow 1-2 in-flight)
-      expect(updateCalls.length - callsAfterStop).toBeLessThanOrEqual(2);
-    });
-
-    test("should calculate delta time correctly", async () => {
-      driver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      // Sum of all deltas should approximately equal wall time
-      const totalTime = updateCalls.reduce((sum, dt) => sum + dt, 0);
-      expect(totalTime).toBeGreaterThan(0.04); // At least 40ms
-      expect(totalTime).toBeLessThan(0.1); // Less than 100ms
-    });
-
-    test("should handle restart", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      const firstBatch = updateCalls.length;
-      updateCalls = [];
-
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe("RafDriver", () => {
-    let driver: RafDriver;
-    let updateCalls: number[] = [];
-
-    beforeEach(() => {
-      updateCalls = [];
-      driver = new RafDriver((dt) => {
-        updateCalls.push(dt);
-      });
-    });
-
-    afterEach(() => {
-      driver.stop();
-    });
-
-    test("should initialize without starting", () => {
-      expect(updateCalls.length).toBe(0);
-    });
-
-    test("should call update with delta time", async () => {
-      driver.start();
-
-      // Wait for a few frames (at 60fps, 100ms = ~6 frames)
-      await new Promise(resolve => setTimeout(resolve, 100));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-
-      // Delta times should be positive and reasonable for 60fps
-      for (const dt of updateCalls) {
-        expect(dt).toBeGreaterThan(0);
-        expect(dt).toBeLessThan(0.1); // Less than 100ms per frame
-      }
-    });
-
-    test("should stop calling update after stop", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      const callsAfterStop = updateCalls.length;
-
-      // Wait for potential in-flight RAF
-      await new Promise(resolve => setTimeout(resolve, 50));
-
-      // Should not have any more calls (RAF properly cancelled)
-      expect(updateCalls.length).toBe(callsAfterStop);
-    });
-
-    test("should calculate delta time correctly", async () => {
-      driver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 100));
-      driver.stop();
-
-      // Sum of all deltas should approximately equal wall time
-      const totalTime = updateCalls.reduce((sum, dt) => sum + dt, 0);
-      expect(totalTime).toBeGreaterThan(0.08); // At least 80ms
-      expect(totalTime).toBeLessThan(0.15); // Less than 150ms
-    });
-
-    test("should handle restart", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      const firstBatch = updateCalls.length;
-      updateCalls = [];
-
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-    });
-
-    test("should cancel RAF on stop", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 50));
-
-      // Stop should cancel the RAF
-      driver.stop();
-
-      // rafId should be cleared
-      expect((driver as any).rafId).toBe(null);
-    });
-  });
-
-  describe("TimeoutDriver", () => {
-    let driver: TimeoutDriver;
-    let updateCalls: number[] = [];
-
-    beforeEach(() => {
-      updateCalls = [];
-      driver = new TimeoutDriver((dt) => {
-        updateCalls.push(dt);
-      });
-    });
-
-    afterEach(() => {
-      driver.stop();
-    });
-
-    test("should initialize without starting", () => {
-      expect(updateCalls.length).toBe(0);
-    });
-
-    test("should call update with delta time", async () => {
-      driver.start();
-
-      // Wait for a few ticks
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-
-      // Delta times should be positive and in seconds
-      for (const dt of updateCalls) {
-        expect(dt).toBeGreaterThan(0);
-        expect(dt).toBeLessThan(1); // Should be less than 1 second
-      }
-    });
-
-    test("should stop calling update after stop", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      const callsAfterStop = updateCalls.length;
-
-      // Wait a bit more
-      await new Promise(resolve => setTimeout(resolve, 20));
-
-      // Should not have significantly more calls (allow 1-2 in-flight)
-      expect(updateCalls.length - callsAfterStop).toBeLessThanOrEqual(2);
-    });
-
-    test("should calculate delta time correctly", async () => {
-      driver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 50));
-      driver.stop();
-
-      // Sum of all deltas should approximately equal wall time
-      const totalTime = updateCalls.reduce((sum, dt) => sum + dt, 0);
-      expect(totalTime).toBeGreaterThan(0.04); // At least 40ms
-      expect(totalTime).toBeLessThan(0.1); // Less than 100ms
-    });
-
-    test("should handle restart", async () => {
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      const firstBatch = updateCalls.length;
-      updateCalls = [];
-
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 20));
-      driver.stop();
-
-      expect(updateCalls.length).toBeGreaterThan(0);
-    });
-
-    test("should run slower than ImmediateDriver due to 1ms delay", async () => {
-      let timeoutTicks = 0;
-      let immediateTicks = 0;
-
-      const timeoutDriver = new TimeoutDriver(() => { timeoutTicks++; });
-      const immediateDriver = new ImmediateDriver(() => { immediateTicks++; });
-
-      timeoutDriver.start();
-      immediateDriver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      timeoutDriver.stop();
-      immediateDriver.stop();
-
-      // ImmediateDriver should tick significantly more than TimeoutDriver
-      expect(immediateTicks).toBeGreaterThan(timeoutTicks);
-    });
-  });
-
-  describe("Driver comparison", () => {
-    test("ImmediateDriver should run faster than RAF", async () => {
-      let immediateTicks = 0;
-      let rafTicks = 0;
-
-      const immediateDriver = new ImmediateDriver(() => { immediateTicks++; });
-      const rafDriver = new RafDriver(() => { rafTicks++; });
-
-      immediateDriver.start();
-      rafDriver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      immediateDriver.stop();
-      rafDriver.stop();
-
-      // setImmediate should tick way more than RAF (~60fps)
-      expect(immediateTicks).toBeGreaterThan(rafTicks * 2);
-    });
-
-    test("TimeoutDriver should run faster than RAF but slower than Immediate", async () => {
-      let timeoutTicks = 0;
-      let rafTicks = 0;
-      let immediateTicks = 0;
-
-      const timeoutDriver = new TimeoutDriver(() => { timeoutTicks++; });
-      const rafDriver = new RafDriver(() => { rafTicks++; });
-      const immediateDriver = new ImmediateDriver(() => { immediateTicks++; });
-
-      timeoutDriver.start();
-      rafDriver.start();
-      immediateDriver.start();
-
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      timeoutDriver.stop();
-      rafDriver.stop();
-      immediateDriver.stop();
-
-      // TimeoutDriver should be between RAF and Immediate
-      expect(timeoutTicks).toBeGreaterThan(rafTicks);
-      expect(immediateTicks).toBeGreaterThan(timeoutTicks);
-    });
-  });
-
-  describe("Edge cases", () => {
-    test("should handle multiple stops gracefully", () => {
-      const driver = new ImmediateDriver(() => {});
-      driver.start();
-      driver.stop();
-      driver.stop(); // Should not throw
-      driver.stop(); // Should not throw
-    });
-
-    test("should handle stop before start", () => {
-      const driver = new RafDriver(() => {});
-      driver.stop(); // Should not throw
-    });
-
-    test("should reset timing on restart to prevent large delta", async () => {
-      let firstDelta = 0;
-      const driver = new ImmediateDriver((dt) => {
-        if (firstDelta === 0) firstDelta = dt;
-      });
-
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 10));
-      driver.stop();
-
-      // Wait a bit
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      firstDelta = 0;
-      driver.start();
-      await new Promise(resolve => setTimeout(resolve, 10));
-      driver.stop();
-
-      // First delta after restart should be small, not 100ms+
-      expect(firstDelta).toBeLessThan(0.05);
-    });
-  });
-});

package/src/core/loop/loop.ts

@@ -1,71 +0,0 @@
-import { ImmediateDriver, RafDriver, TimeoutDriver } from "./drivers";
-
-// Re-export driver classes for testing and direct usage
-export { ImmediateDriver, RafDriver, TimeoutDriver };
-
-/**
- * Interface for game loop drivers that handle frame updates.
- * Drivers are responsible for scheduling and executing the game loop
- * at the appropriate rate for their environment (client or server).
- */
-export interface LoopDriver {
-    /** Starts the game loop */
-    start(): void;
-    /** Stops the game loop */
-    stop(): void;
-    /** Internal loop iteration method */
-    loop(): void;
-    /** Update callback invoked each frame with delta time in seconds */
-    update(dt: number): void;
-}
-
-/**
- * Type of driver to use for the game loop.
- * - `'client'`: Uses requestAnimationFrame for browser environments (syncs with display refresh rate)
- * - `'server-immediate'`: Uses setImmediate for Node.js environments (runs as fast as possible, maximum performance)
- * - `'server-timeout'`: Uses setTimeout with 1ms delay for Node.js environments (balanced performance with better I/O responsiveness)
- */
-export type DriverType = 'server-immediate' | 'client' | 'server-timeout';
-
-/**
- * Factory function to create a loop driver for the specified environment.
- *
- * @param type - The environment type
- *   - `'client'`: Browser RAF driver (60 FPS, syncs with display)
- *   - `'server'`: Node.js setImmediate driver (maximum performance)
- *   - `'server-timeout'`: Node.js setTimeout driver (balanced with I/O)
- * @param update - Callback function invoked each frame with delta time in seconds
- * @returns A configured LoopDriver instance ready to start
- *
- * @example
- * ```typescript
- * // Client
- * const clientDriver = createDriver('client', (dt) => {
- *   game.update(dt);
- *   renderer.render();
- * });
- * clientDriver.start();
- *
- * // Server (maximum performance)
- * const serverDriver = createDriver('server', (dt) => {
- *   simulation.tick(dt);
- * });
- * serverDriver.start();
- *
- * // Server (balanced with I/O)
- * const balancedDriver = createDriver('server-timeout', (dt) => {
- *   simulation.tick(dt);
- *   handleNetworkIO();
- * });
- * balancedDriver.start();
- * ```
- */
-export function createDriver(type: DriverType, update: (dt: number) => void) {
-    if (type === 'server-immediate') {
-        return new ImmediateDriver(update);
-    } else if (type === 'server-timeout') {
-        return new TimeoutDriver(update);
-    } else {
-        return new RafDriver(update);
-    }
-}