murow 0.0.1

package/dist/core/events/event-system.js

@@ -0,0 +1,88 @@
+/**
+ * @description
+ * A callback-based event handling system designed to simplify
+ * event-driven programming.
+ */
+export class EventSystem {
+    constructor({ events }) {
+        this.callbacks = new Map();
+        this.events = events;
+        for (const name of this.events) {
+            this.callbacks.set(name, new Set());
+        }
+    }
+    /**
+     * @description
+     * Registers a callback for an event.
+     *
+     * @param name Event name
+     * @param callback Callback to run when the event is emitted
+     */
+    on(name, callback) {
+        const event = this.callbacks.get(name);
+        if (!event)
+            return console.warn(`Event "${name}" does not exist.`);
+        event.add(callback);
+    }
+    /**
+     * @description
+     * Registers a callback for an event that runs only once.
+     *
+     * @param name Event name
+     * @param callback Callback to run when the event is emitted
+     */
+    once(name, callback) {
+        const wrapper = (props) => {
+            callback(props);
+            this.off(name, wrapper);
+        };
+        this.on(name, wrapper);
+    }
+    /**
+     * @description
+     * Emits an event, running all registered callbacks.
+     *
+     * @param name Event name
+     * @param data Event data
+     */
+    emit(name, data) {
+        const event = this.callbacks.get(name);
+        if (!event)
+            return console.warn(`Event "${name}" does not exist.`);
+        for (const callback of event) {
+            callback(data);
+        }
+    }
+    /**
+     * @description
+     * Removes a callback from an event.
+     *
+     * @param name Event name
+     * @param callback Callback to remove
+     */
+    off(name, callback) {
+        const event = this.callbacks.get(name);
+        if (!event)
+            return console.warn(`Event "${name}" does not exist.`);
+        event.delete(callback);
+    }
+    /**
+     * @description
+     * Removes all callbacks.
+     *
+     * @param name Optional event name
+     */
+    clear(name) {
+        if (!name) {
+            this.callbacks.clear();
+            for (const name of this.events) {
+                this.callbacks.set(name, new Set());
+            }
+            return;
+        }
+        const event = this.callbacks.get(name);
+        if (!event)
+            return console.warn(`Event "${name}" does not exist.`);
+        event.clear();
+    }
+}

package/dist/core/events/index.d.ts

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

package/dist/core/events/index.js

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

package/dist/core/fixed-ticker/fixed-ticker.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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 declare class FixedTicker {
+    /**
+     * @description Accumulator for the time passed since the last tick
+     */
+    private accumulator;
+    /**
+     * @description Rate of ticks per second
+     */
+    rate: number;
+    /**
+     * @description
+     * Interval in milliseconds per tick
+     */
+    private intervalMs;
+    /**
+     * @description
+     * Maximum amount of ticks to run per frame, to avoid
+     * running too many ticks in a single frame.
+     */
+    private maxTicksPerFrame;
+    /**
+     * @description
+     * Callback to execute on each tick
+     */
+    private onTick;
+    /**
+     * @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?;
+    /**
+     * @description
+     * Internal counter for the number of ticks processed.
+     */
+    private _tickCount;
+    constructor({ rate, onTick }: FixedTickerProps);
+    /**
+     * @description
+     * Returns how many ticks to run.
+     *
+     * @param deltaTime Delta time in seconds
+     * @returns {number} Amount of ticks to run
+     */
+    private getTicks;
+    /**
+     * @description
+     * Processes the ticks based on the elapsed time.
+     *
+     * @param deltaTime Delta time in seconds
+     */
+    tick(deltaTime: number): void;
+    /**
+     * @description
+     * Returns the number of ticks processed since the last reset.
+     *
+     * @returns {number} Number of ticks processed
+     */
+    get tickCount(): number;
+    /**
+     * @description
+     * Resets the tick count to zero.
+     */
+    resetTickCount(): void;
+    /**
+     * @description
+     * Returns the accumulated time in seconds, useful for interpolation.
+     *
+     * @returns {number} Accumulated time in seconds
+     */
+    get accumulatedTime(): number;
+}
+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;
+}
+export {};

package/dist/core/fixed-ticker/fixed-ticker.js

@@ -0,0 +1,91 @@
+/**
+ * @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 {
+    constructor({ rate, onTick }) {
+        /**
+         * @description Accumulator for the time passed since the last tick
+         */
+        this.accumulator = 0;
+        /**
+         * @description
+         * Internal counter for the number of ticks processed.
+         */
+        this._tickCount = 0;
+        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
+     */
+    getTicks(deltaTime) {
+        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) {
+        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() {
+        return this._tickCount;
+    }
+    /**
+     * @description
+     * Resets the tick count to zero.
+     */
+    resetTickCount() {
+        this._tickCount = 0;
+    }
+    /**
+     * @description
+     * Returns the accumulated time in seconds, useful for interpolation.
+     *
+     * @returns {number} Accumulated time in seconds
+     */
+    get accumulatedTime() {
+        return this.accumulator / 1000; // Convert to seconds
+    }
+}

package/dist/core/fixed-ticker/index.d.ts

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

package/dist/core/fixed-ticker/index.js

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

package/dist/core/generate-id/generate-id.d.ts

@@ -0,0 +1,21 @@
+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 declare function generateId(options?: GenerateIdOptions): string;
+export {};

package/dist/core/generate-id/generate-id.js

@@ -0,0 +1,25 @@
+/**
+ * @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 = {}) {
+    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/dist/core/generate-id/index.d.ts

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

package/dist/core/generate-id/index.js

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

package/dist/core/index.d.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/dist/core/index.js

@@ -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/dist/core/lerp/index.d.ts

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

package/dist/core/lerp/index.js

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

package/dist/core/lerp/lerp.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 declare function lerp(start: number, end: number, t: number): number;

package/dist/core/lerp/lerp.js

@@ -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, end, t) {
+    return start + (end - start) * t;
+}

package/dist/core/navmesh/index.d.ts

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

package/dist/core/navmesh/index.js

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

package/dist/core/navmesh/navmesh.d.ts

@@ -0,0 +1,116 @@
+type ObstacleId = number;
+export type Obstacle = CircleObstacle | RectObstacle | PolygonObstacle;
+export type ObstacleInput = Omit<CircleObstacle, 'id'> | Omit<RectObstacle, 'id'> | Omit<PolygonObstacle, 'id'>;
+interface Vec2 {
+    x: number;
+    y: number;
+}
+interface BaseObstacle {
+    id: ObstacleId;
+    type: 'circle' | 'rect' | 'polygon';
+    solid?: boolean;
+}
+export interface CircleObstacle extends BaseObstacle {
+    type: 'circle';
+    pos: Vec2;
+    radius: number;
+}
+export interface RectObstacle extends BaseObstacle {
+    type: 'rect';
+    pos: Vec2;
+    size: Vec2;
+    rotation?: number;
+}
+/**
+ * Polygon obstacle.
+ * IMPORTANT: `points` must be defined relative to local origin (0,0).
+ * The polygon will be rotated around (0,0) then translated to `pos`.
+ * Do NOT define points in world space.
+ */
+export interface PolygonObstacle extends BaseObstacle {
+    type: 'polygon';
+    points: Vec2[];
+    pos: Vec2;
+    rotation?: number;
+}
+/**
+ * Manages obstacles with spatial hashing for fast queries.
+ * Version tracking prevents unnecessary rebuilds.
+ */
+declare class Obstacles {
+    private items;
+    private spatial;
+    private _cachedItems;
+    dirty: boolean;
+    version: number;
+    add(obstacle: ObstacleInput): ObstacleId;
+    move(id: ObstacleId, pos: Vec2): void;
+    remove(id: ObstacleId): void;
+    /**
+     * Fast spatial query using hash grid.
+     * O(1) average case instead of O(n) linear scan.
+     */
+    at(pos: Vec2): Obstacle | undefined;
+    get values(): Obstacle[];
+}
+type NavType = 'grid' | 'graph';
+/**
+ * Navigation mesh with spatial hashing and smart rebuild.
+ *
+ * Features:
+ * - Spatial hash: O(1) obstacle queries
+ * - Version tracking: zero unnecessary rebuilds
+ * - Binary heap A*: handles 10k+ node searches
+ * - Simple full rebuild: correct and fast enough
+ *
+ * Performance characteristics:
+ * - Obstacle query: O(1) average via spatial hash
+ * - Grid rebuild: O(n * area), < 1ms for typical games
+ * - Pathfinding: O(b^d * log n) with binary heap
+ *
+ * Production ready for:
+ * - Grid-based games
+ * - RTS with < 1000 dynamic obstacles
+ * - Turn-based games
+ * - Moderate map sizes (< 1M cells)
+ */
+export declare class NavMesh {
+    private type;
+    private grid?;
+    private graph?;
+    private lastVersion;
+    obstacles: Obstacles;
+    constructor(type: NavType);
+    /**
+     * Adds an obstacle and returns its unique ID.
+     * For polygons: ensure points are defined relative to (0,0).
+     */
+    addObstacle(obstacle: ObstacleInput): ObstacleId;
+    /**
+     * Moves an existing obstacle to a new position.
+     */
+    moveObstacle(id: ObstacleId, pos: Vec2): void;
+    /**
+     * Removes an obstacle by ID.
+     */
+    removeObstacle(id: ObstacleId): void;
+    /**
+     * Returns all current obstacles.
+     */
+    getObstacles(): Obstacle[];
+    /**
+     * Finds a path from start to goal.
+     * Automatically rebuilds navigation data if obstacles changed.
+     * Returns empty array if no path exists.
+     */
+    findPath({ from, to }: {
+        from: Vec2;
+        to: Vec2;
+    }): Vec2[];
+    /**
+     * Smart rebuild - only rebuilds if obstacles changed.
+     * Version checking eliminates unnecessary work.
+     */
+    rebuild(): void;
+}
+export {};