murow 0.0.1

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

@@ -0,0 +1,158 @@
+/**
+ * @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
+   */
+  private 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
+  }
+}
+
+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

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

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

@@ -0,0 +1,18 @@
+# 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

@@ -0,0 +1,79 @@
+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

@@ -0,0 +1,37 @@
+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

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

package/src/core/index.ts

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

package/src/core/lerp/README.md

@@ -0,0 +1,79 @@
+# 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

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

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

@@ -0,0 +1,90 @@
+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

@@ -0,0 +1,42 @@
+/**
+ * @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/navmesh/README.md

@@ -0,0 +1,124 @@
+# NavMesh / Pathfinding Utility
+
+A lightweight navigation system for grid-based and hybrid games.
+
+Supports:
+
+* **Grid A*** pathfinding
+* **Line-of-sight graph navigation**
+* **Dynamic obstacles**
+* **Spatial hashing for fast queries**
+* **Circle / Rect / Polygon obstacles**
+* **Zero rebuilds unless data changes**
+
+Designed for **games**, not CAD-grade geometry.
+
+---
+
+## Features
+
+* ⚡ **Fast obstacle queries** via spatial hash
+* 🧠 **Smart rebuilds** (version-based, no unnecessary work)
+* 🧩 **Multiple obstacle types**
+* 🧭 **A*** with binary heap
+* 🧱 **Grid or graph navigation**
+* 🔁 Dynamic obstacle add / move / remove
+* 🧪 Deterministic & allocation-safe
+
+---
+
+## Usage
+
+### Create navmesh
+
+```ts
+const nav = new NavMesh('grid'); // or 'graph'
+```
+
+### Add obstacles
+
+```ts
+nav.addObstacle({
+  type: 'circle',
+  pos: { x: 5, y: 5 },
+  radius: 2
+});
+```
+
+```ts
+nav.addObstacle({
+  type: 'rect',
+  pos: { x: 2, y: 3 },
+  size: { x: 4, y: 2 },
+});
+```
+
+```ts
+nav.addObstacle({
+  type: 'polygon',
+  pos: { x: 10, y: 5 },
+  points: [
+    { x: 0, y: 0 },
+    { x: 2, y: 0 },
+    { x: 1, y: 2 },
+  ],
+});
+```
+
+### Move / remove
+
+```ts
+nav.moveObstacle(id, { x: 8, y: 4 });
+nav.removeObstacle(id);
+```
+
+### Find path
+
+```ts
+const path = nav.findPath({
+  from: { x: 1, y: 1 },
+  to: { x: 10, y: 8 }
+});
+```
+
+---
+
+## Navigation Modes
+
+### `grid`
+
+* A* over grid cells
+* Accurate
+* Best for RTS / tactics / tile games
+
+### `graph`
+
+* Line-of-sight check
+* Falls back to grid if blocked
+* Faster for open maps
+
+---
+
+## Performance
+
+| Feature        | Cost                              |
+| -------------- | --------------------------------- |
+| Obstacle query | **O(1)** avg                      |
+| Grid rebuild   | O(n × area)                       |
+| Pathfinding    | O(bᵈ log n)                       |
+| Memory         | Minimal, no allocations per frame |
+
+Handles:
+
+* 1k+ obstacles
+* 10k+ A* nodes
+* Real-time updates
+
+---
+
+## Notes
+
+* Polygon points **must be local (0,0-based)**
+* Rotation is supported for rects & polygons
+* All math is deterministic
+* No dependencies

package/src/core/navmesh/index.ts

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