murow 0.0.60 → 0.0.71

package/src/core/fixed-ticker/fixed-ticker.ts

@@ -1,169 +0,0 @@
-/**
- * @description
- * A utility class for managing fixed-rate update ticks, useful for deterministic behaviour
- * in both client and server.
- *
- * The `FixedTicker` accumulates elapsed time and determines how many fixed-interval "ticks"
- * should be processed based on a specified tick rate. It also limits the maximum number of
- * ticks per frame to prevent runaway update loops when frame times are long.
- *
- *
- * @remarks
- * - The `tick` method should be called once per frame, passing the elapsed time in seconds.
- * - The class ensures that no more than a safe number of ticks are processed per frame.
- */
-export class FixedTicker {
-  /**
-   * @description Accumulator for the time passed since the last tick
-   */
-  private accumulator = 0;
-
-  /**
-   * @description Rate of ticks per second
-   */
-  rate: number;
-
-  /**
-   * @description
-   * Interval in milliseconds per tick
-   */
-  intervalMs: number;
-
-  /**
-   * @description
-   * Maximum amount of ticks to run per frame, to avoid
-   * running too many ticks in a single frame.
-   */
-  private maxTicksPerFrame: number;
-
-  /**
-   * @description
-   * Callback to execute on each tick
-   */
-  private onTick: (deltaTime: number, tick?: number) => void;
-
-  /**
-   * @description
-   * Optional callback to execute when ticks are skipped due to high delta time.
-   * This can be useful for debugging or logging purposes.
-   */
-  private onTickSkipped?: (skippedTicks: number) => void;
-
-  /**
-   * @description
-   * Internal counter for the number of ticks processed.
-   */
-  private _tickCount = 0;
-
-  constructor({ rate, onTick }: FixedTickerProps) {
-    this.rate = rate;
-    this.intervalMs = 1000 / this.rate;
-    this.onTick = onTick;
-
-    // Allow up to rate/2 ticks per frame, but at least 1.
-    // Prevents runaway loops if delta is too large.
-    this.maxTicksPerFrame = Math.max(1, Math.floor(rate / 2));
-  }
-
-  /**
-   * @description
-   * Returns how many ticks to run.
-   *
-   * @param deltaTime Delta time in seconds
-   * @returns {number} Amount of ticks to run
-   */
-  private getTicks(deltaTime: number): number {
-    this.accumulator += deltaTime * 1000;
-
-    let ticks = 0;
-
-    while (
-      this.accumulator >= this.intervalMs &&
-      ticks < this.maxTicksPerFrame
-    ) {
-      this.accumulator -= this.intervalMs;
-      ticks++;
-    }
-
-    const skippedTicks = Math.floor(this.accumulator / this.intervalMs);
-    if (skippedTicks > 0 && this.onTickSkipped) {
-      this.onTickSkipped(skippedTicks);
-    }
-
-    return ticks;
-  }
-
-  /**
-   * @description
-   * Processes the ticks based on the elapsed time.
-   *
-   * @param deltaTime Delta time in seconds
-   */
-  tick(deltaTime: number): void {
-    const ticks = this.getTicks(deltaTime);
-
-    for (let i = 0; i < ticks; i++) {
-      this.onTick(1 / this.rate, this._tickCount++);
-    }
-  }
-
-  /**
-   * @description
-   * Returns the number of ticks processed since the last reset.
-   *
-   * @returns {number} Number of ticks processed
-   */
-  get tickCount(): number {
-    return this._tickCount;
-  }
-
-  /**
-   * @description
-   * Resets the tick count to zero.
-   */
-  resetTickCount(): void {
-    this._tickCount = 0;
-  }
-
-  /**
-   * @description
-   * Returns the accumulated time in seconds, useful for interpolation.
-   *
-   * @returns {number} Accumulated time in seconds
-   */
-  get accumulatedTime(): number {
-    return this.accumulator / 1000; // Convert to seconds
-  }
-
-  /**
-   * @description
-   * Returns the interpolation factor between 0 and 1 for smooth rendering between ticks.
-   * Clamped to prevent extrapolation when ticks are skipped.
-   *
-   * @returns {number} Alpha value between 0 and 1
-   */
-  get alpha(): number {
-    return Math.min(this.accumulatedTime / (1 / this.rate), 1.0);
-  }
-}
-
-interface FixedTickerProps {
-  /**
-   * @description
-   * Rate of ticks per second
-   */
-  rate: number;
-
-  /**
-   * @description
-   * Callback to execute on each tick
-   */
-  onTick: (deltaTime: number, tick?: number) => void;
-
-  /**
-   * @description
-   * Optional callback to execute when ticks are skipped due to high delta time.
-   * This can be useful for debugging or logging purposes.
-   */
-  onTickSkipped?: (skippedTicks: number) => void
-}

package/src/core/fixed-ticker/index.ts

@@ -1 +0,0 @@
-export * from './fixed-ticker';

package/src/core/generate-id/README.md

@@ -1,18 +0,0 @@
-# generateId
-
-A simple utility function to generate unique 64-bit identifiers using the Web Crypto API.
-The IDs are returned as hexadecimal strings and work in both modern browsers and Node.js (v15+).
-
-## Features
-
-- Generates cryptographically strong 64-bit IDs.
-- Returns hexadecimal strings (always padded to 16 characters).
-- Works in browsers and Node ≥15 without any imports.
-- Fast and clean using BigInt arithmetic.
-
-## Usage
-
-```typescript
-import { generateId } from './generate-id';
-const id = generateId(); // akwats 16-character hex string
-```

package/src/core/generate-id/generate-id.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { generateId } from "./generate-id";
-
-describe("generateId", () => {
-  test("should generate an ID with default length of 16", () => {
-    const id = generateId();
-    expect(id.length).toBe(16);
-  });
-
-  test("should generate a hexadecimal string", () => {
-    const id = generateId();
-    expect(id).toMatch(/^[0-9a-f]+$/);
-  });
-
-  test("should generate unique IDs", () => {
-    const ids = new Set();
-    for (let i = 0; i < 1000; i++) {
-      ids.add(generateId());
-    }
-    expect(ids.size).toBe(1000);
-  });
-
-  test("should include prefix when provided", () => {
-    const prefix = "user_";
-    const id = generateId({ prefix });
-    expect(id.startsWith(prefix)).toBe(true);
-  });
-
-  test("should maintain total size including prefix", () => {
-    const prefix = "user_";
-    const size = 20;
-    const id = generateId({ prefix, size });
-    expect(id.length).toBe(size);
-    expect(id.startsWith(prefix)).toBe(true);
-  });
-
-  test("should generate custom size without prefix", () => {
-    const size = 32;
-    const id = generateId({ size });
-    expect(id.length).toBe(size);
-  });
-
-  test("should enforce minimum of 8 hex characters", () => {
-    const prefix = "verylongprefix_";
-    const size = 10; // shorter than prefix + 8
-    const id = generateId({ prefix, size });
-    // Should be prefix + at least 8 hex chars
-    expect(id.length).toBeGreaterThanOrEqual(prefix.length + 8);
-  });
-
-  test("should pad ID to desired length", () => {
-    const size = 24;
-    const id = generateId({ size });
-    expect(id.length).toBe(size);
-  });
-
-  test("should generate different IDs on consecutive calls", () => {
-    const id1 = generateId();
-    const id2 = generateId();
-    expect(id1).not.toBe(id2);
-  });
-
-  test("should work with various prefix lengths", () => {
-    const prefixes = ["a", "ab", "abc", "player_", "super_long_prefix_"];
-    prefixes.forEach((prefix) => {
-      const id = generateId({ prefix });
-      expect(id.startsWith(prefix)).toBe(true);
-    });
-  });
-
-  test("should generate valid hex with leading zeros preserved", () => {
-    // Generate many IDs to ensure padding works correctly
-    for (let i = 0; i < 100; i++) {
-      const id = generateId({ size: 16 });
-      expect(id.length).toBe(16);
-      expect(id).toMatch(/^[0-9a-f]{16}$/);
-    }
-  });
-});

package/src/core/generate-id/generate-id.ts

@@ -1,37 +0,0 @@
-interface GenerateIdOptions {
-  /** Optional prefix to prepend to the ID */
-  prefix?: string;
-  /** Total length of the returned ID including prefix (default 16) */
-  size?: number;
-}
-
-/**
- * @description
- * Generates a unique identifier as a hexadecimal string.
- * Can include a prefix and a custom total length.
- *
- * @param options Optional configuration: prefix and total size
- * @returns A unique identifier string
- *
- * @example
- * generateId(); // "f3a2b1c4d5e67890"
- * generateId({ prefix: 'user_' }); // "user_f3a2b1c4d5e67890"
- * generateId({ prefix: 'user_', size: 24 }); // "user_00f3a2b1c4d5e67890"
- */
-export function generateId(options: GenerateIdOptions = {}): string {
-  const { prefix = "", size = 16 } = options;
-
-  // compute number of hex characters to generate (subtract prefix length)
-  const hexLength = Math.max(size - prefix.length, 8); // min 8 hex chars
-
-  // number of 32-bit integers needed to cover the hexLength
-  const numInts = Math.ceil(hexLength / 8);
-
-  const arr = crypto.getRandomValues(new Uint32Array(numInts));
-  let id = arr.reduce((acc, val) => acc + val.toString(16).padStart(8, "0"), "");
-
-  // truncate/pad to desired length
-  id = id.slice(0, hexLength).padStart(hexLength, "0");
-
-  return `${prefix}${id}`;
-}

package/src/core/generate-id/index.ts

@@ -1 +0,0 @@
-export * from './generate-id';

package/src/core/index.ts

@@ -1,9 +0,0 @@
-export * from './binary-codec';
-export * from './events';
-export * from './fixed-ticker';
-export * from './generate-id';
-export * from './lerp';
-export * from './loop';
-export * from './navmesh';
-export * from './pooled-codec';
-export * from './prediction';

package/src/core/lerp/README.md

@@ -1,79 +0,0 @@
-# lerp
-
-A simple utility function for linear interpolation between two numeric values. Perfect for smooth animations, transitions, and value easing in game development.
-
-## Features
-
-- Clean linear interpolation implementation.
-- Unclamped by design - allows extrapolation when t is outside [0, 1].
-- Zero dependencies.
-- Works in browsers and Node.js.
-- TypeScript support with proper type definitions.
-
-## Usage
-
-```typescript
-import { lerp } from './lerp';
-
-// Basic interpolation
-const value = lerp(0, 100, 0.5); // Returns 50
-
-// Animation example
-const startPos = 0;
-const endPos = 100;
-const progress = 0.75;
-const currentPos = lerp(startPos, endPos, progress); // Returns 75
-
-// Smooth camera movement
-function updateCamera(deltaTime: number) {
-  const t = deltaTime * smoothingFactor;
-  camera.x = lerp(camera.x, target.x, t);
-  camera.y = lerp(camera.y, target.y, t);
-}
-
-// Color transitions
-const r = lerp(startColor.r, endColor.r, progress);
-const g = lerp(startColor.g, endColor.g, progress);
-const b = lerp(startColor.b, endColor.b, progress);
-```
-
-## Parameters
-
-- `start` (number): The starting value (returned when t = 0)
-- `end` (number): The ending value (returned when t = 1)
-- `t` (number): The interpolation factor, typically in range [0, 1]
-
-## Returns
-
-`number` - The interpolated value between start and end.
-
-## Extrapolation
-
-The function does not clamp the `t` parameter, allowing extrapolation:
-
-```typescript
-lerp(0, 100, 1.5);  // Returns 150 (extrapolated beyond end)
-lerp(0, 100, -0.5); // Returns -50 (extrapolated before start)
-```
-
-If you need clamped interpolation, combine with a clamp function:
-
-```typescript
-function clampedLerp(start: number, end: number, t: number): number {
-  const clampedT = Math.max(0, Math.min(1, t));
-  return lerp(start, end, clampedT);
-}
-```
-
-## Common Use Cases
-
-- **Smooth animations**: Interpolate position, rotation, scale over time
-- **Camera movement**: Create smooth camera following behavior
-- **UI transitions**: Fade effects, sliding panels, progress bars
-- **Color blending**: Transition between colors smoothly
-- **Value easing**: Gradually approach target values
-- **Physics simulations**: Interpolate between physics states for rendering
-
----
-
-`lerp` provides a foundational building block for smooth, continuous value transitions in game development and interactive applications.

package/src/core/lerp/index.ts

@@ -1 +0,0 @@
-export * from './lerp';

package/src/core/lerp/lerp.test.ts

@@ -1,90 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { lerp } from "./lerp";
-
-describe("lerp", () => {
-  test("should return start value when t is 0", () => {
-    expect(lerp(0, 100, 0)).toBe(0);
-    expect(lerp(50, 200, 0)).toBe(50);
-    expect(lerp(-10, 10, 0)).toBe(-10);
-  });
-
-  test("should return end value when t is 1", () => {
-    expect(lerp(0, 100, 1)).toBe(100);
-    expect(lerp(50, 200, 1)).toBe(200);
-    expect(lerp(-10, 10, 1)).toBe(10);
-  });
-
-  test("should return midpoint when t is 0.5", () => {
-    expect(lerp(0, 100, 0.5)).toBe(50);
-    expect(lerp(50, 150, 0.5)).toBe(100);
-    expect(lerp(-10, 10, 0.5)).toBe(0);
-  });
-
-  test("should interpolate between positive values", () => {
-    expect(lerp(0, 100, 0.25)).toBe(25);
-    expect(lerp(0, 100, 0.75)).toBe(75);
-    expect(lerp(10, 20, 0.3)).toBeCloseTo(13, 5);
-  });
-
-  test("should interpolate between negative values", () => {
-    expect(lerp(-100, -50, 0.5)).toBe(-75);
-    expect(lerp(-10, -5, 0.2)).toBe(-9);
-  });
-
-  test("should interpolate from negative to positive", () => {
-    expect(lerp(-50, 50, 0.5)).toBe(0);
-    expect(lerp(-10, 10, 0.25)).toBe(-5);
-    expect(lerp(-10, 10, 0.75)).toBe(5);
-  });
-
-  test("should handle extrapolation when t > 1", () => {
-    expect(lerp(0, 100, 1.5)).toBe(150);
-    expect(lerp(0, 100, 2)).toBe(200);
-    expect(lerp(10, 20, 1.1)).toBeCloseTo(21, 5);
-  });
-
-  test("should handle extrapolation when t < 0", () => {
-    expect(lerp(0, 100, -0.5)).toBe(-50);
-    expect(lerp(0, 100, -1)).toBe(-100);
-    expect(lerp(10, 20, -0.1)).toBeCloseTo(9, 5);
-  });
-
-  test("should handle same start and end values", () => {
-    expect(lerp(50, 50, 0)).toBe(50);
-    expect(lerp(50, 50, 0.5)).toBe(50);
-    expect(lerp(50, 50, 1)).toBe(50);
-    expect(lerp(50, 50, 2)).toBe(50);
-  });
-
-  test("should handle floating point values", () => {
-    expect(lerp(0.1, 0.9, 0.5)).toBeCloseTo(0.5, 10);
-    expect(lerp(1.5, 2.5, 0.3)).toBeCloseTo(1.8, 10);
-  });
-
-  test("should be commutative with inverted t", () => {
-    const start = 10;
-    const end = 20;
-    expect(lerp(start, end, 0.3)).toBeCloseTo(lerp(end, start, 0.7), 10);
-  });
-
-  test("should handle very small differences", () => {
-    expect(lerp(1.0, 1.0001, 0.5)).toBeCloseTo(1.00005, 10);
-  });
-
-  test("should handle very large values", () => {
-    expect(lerp(1e10, 2e10, 0.5)).toBe(1.5e10);
-  });
-
-  test("should be linear (no easing)", () => {
-    const start = 0;
-    const end = 100;
-    const step = 0.1;
-    const expectedDiff = 10;
-
-    for (let t = 0; t < 1; t += step) {
-      const val1 = lerp(start, end, t);
-      const val2 = lerp(start, end, t + step);
-      expect(val2 - val1).toBeCloseTo(expectedDiff, 5);
-    }
-  });
-});

package/src/core/lerp/lerp.ts

@@ -1,42 +0,0 @@
-/**
- * @description
- * Performs linear interpolation between two values.
- *
- * Linear interpolation (lerp) calculates a value between a start and end point
- * based on a normalized interpolation factor (t). When t = 0, the result equals
- * the start value; when t = 1, the result equals the end value. Values of t
- * between 0 and 1 produce intermediate results.
- *
- * @remarks
- * - This function does not clamp the interpolation factor. Values of t outside
- *   the range [0, 1] will extrapolate beyond the start and end values.
- * - For clamped interpolation, combine with a clamp function on the t parameter.
- * - Commonly used for smooth animations, camera movements, and value transitions.
- *
- * @param start - The starting value (when t = 0)
- * @param end - The ending value (when t = 1)
- * @param t - The interpolation factor, typically in the range [0, 1]
- *
- * @returns {number} The interpolated value between start and end
- *
- * @example
- * ```typescript
- * // Basic interpolation
- * lerp(0, 100, 0.5);   // Returns 50
- * lerp(0, 100, 0);     // Returns 0
- * lerp(0, 100, 1);     // Returns 100
- *
- * // Animation example
- * const startPos = 0;
- * const endPos = 100;
- * const progress = 0.75;
- * const currentPos = lerp(startPos, endPos, progress); // Returns 75
- *
- * // Extrapolation (t outside [0, 1])
- * lerp(0, 100, 1.5);   // Returns 150
- * lerp(0, 100, -0.5);  // Returns -50
- * ```
- */
-export function lerp(start: number, end: number, t: number): number {
-  return start + (end - start) * t;
-}

package/src/core/loop/README.md

@@ -1,97 +0,0 @@
-# Loop
-
-Environment-aware game loop drivers for client (browser) and server (Node.js).
-Provides variable delta time that should be consumed by `FixedTicker` for deterministic game logic.
-
----
-
-## Features
-
-- **Environment-Specific**: Uses `requestAnimationFrame` (client) or `setImmediate` (server)
-- **Automatic Delta Time**: Calculates delta in seconds between frames
-- **Simple API**: Start and stop with a single method call
-- **Designed for FixedTicker**: Provides variable dt that FixedTicker converts to fixed timesteps
-
----
-
-## Usage
-
-### Recommended: With FixedTicker
-
-```typescript
-import { createDriver } from '@/core/loop';
-import { FixedTicker } from '@/core/fixed-ticker';
-
-const ticker = new FixedTicker({
-  rate: 30,
-  onTick: (fixedDt, tick) => {
-    world.update(fixedDt);
-    applyInputs(tick);
-  }
-});
-
-// Client: RAF driver with interpolation
-const clientDriver = createDriver('client', (dt) => {
-  ticker.tick(dt);
-  render(ticker.alpha); // Smooth 60 FPS rendering of 30 TPS simulation
-});
-clientDriver.start();
-
-// Server: Immediate driver for high-frequency updates
-const serverDriver = createDriver('server', (dt) => {
-  ticker.tick(dt);
-  broadcastState();
-});
-serverDriver.start();
-```
-
-### Direct Usage (Single-player only)
-
-```typescript
-import { createDriver } from '@/core/loop';
-
-// ⚠️ Variable delta time - not suitable for multiplayer
-const driver = createDriver('client', (dt) => {
-  player.update(dt);
-  renderer.render();
-});
-driver.start();
-```
-
----
-
-## Drivers
-
-### `RafDriver` (Client)
-- Uses `requestAnimationFrame`
-- Syncs with display refresh rate (~60 FPS)
-- Automatic throttling when tab not visible
-
-### `ImmediateDriver` (Server)
-- Uses `setImmediate` (Node.js only)
-- Runs as fast as possible without blocking event loop
-- Suitable for server simulations
-
----
-
-## API
-
-```typescript
-createDriver(type: 'client' | 'server', update: (dt: number) => void): LoopDriver
-```
-
-```typescript
-interface LoopDriver {
-  start(): void;  // Start the loop
-  stop(): void;   // Stop the loop
-}
-```
-
----
-
-## Notes
-
-- Delta time (`dt`) is always in **seconds**, not milliseconds
-- **Always use with FixedTicker** for multiplayer/deterministic games
-- Direct usage without FixedTicker only suitable for single-player scenarios
-- `ImmediateDriver` requires Node.js (uses `setImmediate`)

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

@@ -1,66 +0,0 @@
-import { LoopDriver } from "../loop";
-
-/**
- * Server-side game loop driver using setImmediate.
- *
- * This driver runs the game loop as fast as possible without blocking the event loop,
- * making it suitable for Node.js server environments where high tick rates are desired.
- *
- * Delta time is automatically calculated between iterations and passed to the update callback in seconds.
- *
- * **Note:** This driver requires Node.js as it uses `setImmediate` which is not available in browsers.
- *
- * @example
- * ```typescript
- * const driver = new ImmediateDriver((dt) => {
- *   world.tick(dt);
- *   broadcastState();
- * });
- * driver.start();
- * ```
- */
-export class ImmediateDriver 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 setImmediate.
-     * 
-     * 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 setImmediate callbacks.
-     */
-    stop() {
-        this.running = false;
-    }
-
-    /**
-     * Internal loop method that calculates delta time and schedules the next iteration.
-     * 
-     * 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);
-        setImmediate(this.loop);
-    };
-}