murow 0.0.1

package/README.md

@@ -0,0 +1,61 @@
+# Murow
+
+A lightweight TypeScript game engine for server-authoritative multiplayer games.
+
+## Installation
+
+```bash
+npm install murow
+```
+
+## Usage
+
+```typescript
+import {
+  FixedTicker,
+  EventSystem,
+  BinaryCodec,
+  generateId,
+  lerp,
+  NavMesh,
+  PooledCodec,
+  IntentTracker,
+  Reconciliator
+} from 'murow';
+// or
+import { FixedTicker } from 'murow/core';
+```
+
+## Modules
+
+### Core Utilities
+- `FixedTicker`: Deterministic fixed-rate update loop
+- `EventSystem`: High-performance event handling
+- `BinaryCodec`: Schema-driven binary serialization
+- `generateId`: Cryptographically secure ID generation
+- `lerp`: Linear interpolation utility
+- `NavMesh`: Pathfinding with dynamic obstacles
+- `PooledCodec`: Object-pooled binary codec
+- `IntentTracker` & `Reconciliator`: Client-side prediction
+
+### Protocol Layer
+Minimalist networking primitives:
+- `IntentRegistry`: Type-safe intent codec registry
+- `SnapshotCodec`: Binary encoding for state deltas
+- `Snapshot<T>`: Delta-based state updates
+- `applySnapshot()`: Deep merge snapshots into state
+
+Works harmoniously with core utilities (`FixedTicker`, `IntentTracker`, `Reconciliator`).
+
+See [Protocol Layer Documentation](./src/protocol/README.md) for usage.
+
+## Building
+
+```bash
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/dist/core/binary-codec/binary-codec.d.ts

@@ -0,0 +1,159 @@
+/**
+ * A binary field descriptor.
+ * Defines how a single value is serialized/deserialized
+ * at a fixed byte size.
+ */
+export type Field<T> = {
+    /** Size of the field in bytes */
+    size: number;
+    /**
+     * Writes a value into a DataView at the given offset.
+     * @param dv DataView to write into
+     * @param o Byte offset
+     * @param v Value to write
+     */
+    write(dv: DataView, o: number, v: T): void;
+    /**
+     * Reads a value from a DataView at the given offset.
+     * @param dv DataView to read from
+     * @param o Byte offset
+     */
+    read(dv: DataView, o: number): T;
+    /**
+     * Returns the nil value
+     */
+    toNil(): T;
+};
+/**
+ * A schema mapping object keys to binary fields.
+ * The order of iteration defines the binary layout.
+ *
+ * IMPORTANT:
+ * Property order is respected as insertion order.
+ * Do not rely on computed or dynamic keys.
+ */
+export type Schema<T> = {
+    [K in keyof T]: Field<T[K]>;
+};
+/**
+ * Base codec implementation.
+ * Handles schema-driven encoding/decoding.
+ */
+export declare class BaseBinaryCodec {
+    /**
+     * Encodes an object into a binary buffer using the given schema.
+     *
+     * Allocates a right-sized buffer per call.
+     * Safe for concurrent and re-entrant usage.
+     *
+     * @param schema Binary schema definition
+     * @param data Object to encode
+     * @returns A Uint8Array containing the encoded bytes
+     */
+    protected static encodeInto<T extends object>(schema: Schema<T>, data: T): Uint8Array;
+    /**
+     * Decodes a binary buffer into a target object using the given schema.
+     *
+     * Validates buffer size before reading.
+     * Does not mutate shared state.
+     *
+     * @param schema Binary schema definition
+     * @param buf Buffer containing encoded data
+     * @param target Target object to mutate
+     * @returns The mutated target object
+     */
+    static decodeInto<T extends object>(schema: Schema<T>, buf: Uint8Array, target: T): T;
+}
+/**
+ * Built-in binary primitive field definitions for multiplayer games.
+ */
+export declare class BinaryPrimitives {
+    /** Unsigned 8-bit integer */
+    static readonly u8: Field<number>;
+    /** Unsigned 16-bit integer (big-endian) */
+    static readonly u16: Field<number>;
+    /** Unsigned 32-bit integer (big-endian) */
+    static readonly u32: Field<number>;
+    /** Signed 8-bit integer */
+    static readonly i8: Field<number>;
+    /** Signed 16-bit integer (big-endian) */
+    static readonly i16: Field<number>;
+    /** Signed 32-bit integer (big-endian) */
+    static readonly i32: Field<number>;
+    /** 32-bit floating point number (IEEE 754, big-endian) */
+    static readonly f32: Field<number>;
+    /** 64-bit floating point number (double, big-endian) */
+    static readonly f64: Field<number>;
+    /** Boolean stored as 1 byte (0 = false, 1 = true) */
+    static readonly bool: Field<boolean>;
+    /**
+     * String field with UTF-8 encoding and 2-byte length prefix.
+     * @param maxLength Maximum number of bytes allowed
+     */
+    static string(maxLength: number): Field<string>;
+    /** 2D vector of f32 (x, y) */
+    static readonly vec2: Field<{
+        x: number;
+        y: number;
+    }>;
+    /** 3D vector of f32 (x, y, z) */
+    static readonly vec3: Field<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /** RGBA color packed as 4 u8 bytes */
+    static readonly color: Field<{
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    }>;
+    /** 32-bit floating point number (IEEE 754, little-endian) */
+    static readonly f32_le: Field<number>;
+    /** 64-bit floating point number (double, little-endian) */
+    static readonly f64_le: Field<number>;
+    /** Unsigned 16-bit integer (little-endian) */
+    static readonly u16_le: Field<number>;
+    /** Unsigned 32-bit integer (little-endian) */
+    static readonly u32_le: Field<number>;
+    /** Signed 16-bit integer (little-endian) */
+    static readonly i16_le: Field<number>;
+    /** Signed 32-bit integer (little-endian) */
+    static readonly i32_le: Field<number>;
+    /**
+     * 2D vector of f32 stored as a tuple [x, y] (little-endian).
+     * Useful for compact math data or shader-friendly layouts.
+     */
+    static readonly vec2_le: Field<[number, number]>;
+    /**
+     * 3D vector of f32 stored as a tuple [x, y, z] (little-endian).
+     * Commonly used for positions, velocities, or directions.
+     */
+    static readonly vec3_le: Field<[number, number, number]>;
+    /**
+     * 4D vector of f32 stored as a tuple [x, y, z, w] (little-endian).
+     * Useful for quaternions, colors in shaders, or homogeneous coordinates.
+     */
+    static readonly vec4_le: Field<[number, number, number, number]>;
+}
+/**
+ * Public codec API.
+ * Re-exports primitives and exposes encode/decode helpers.
+ */
+export declare class BinaryCodec extends BaseBinaryCodec {
+    /** Unsigned 8-bit integer field */
+    static readonly u8: Field<number>;
+    /** Unsigned 16-bit integer field */
+    static readonly u16: Field<number>;
+    /** 32-bit floating point field */
+    static readonly f32: Field<number>;
+    /**
+     * Encodes an object into a binary buffer.
+     */
+    static encode<T extends object>(schema: Schema<T>, data: T): Uint8Array;
+    /**
+     * Decodes a binary buffer into an existing object.
+     */
+    static decode<T extends object>(schema: Schema<T>, buf: Uint8Array, target: T): T;
+}

package/dist/core/binary-codec/binary-codec.js

@@ -0,0 +1,336 @@
+/**
+ * Internal symbol used to cache computed schema byte size.
+ */
+const SCHEMA_SIZE = Symbol("schemaSize");
+/**
+ * Computes and caches the total byte size of a schema.
+ * @param schema Binary schema definition
+ */
+function getSchemaSize(schema) {
+    const cached = schema[SCHEMA_SIZE];
+    if (cached !== undefined)
+        return cached;
+    let size = 0;
+    for (const k of Object.keys(schema)) {
+        size += schema[k].size;
+    }
+    schema[SCHEMA_SIZE] = size;
+    return size;
+}
+/**
+ * Base codec implementation.
+ * Handles schema-driven encoding/decoding.
+ */
+export class BaseBinaryCodec {
+    /**
+     * Encodes an object into a binary buffer using the given schema.
+     *
+     * Allocates a right-sized buffer per call.
+     * Safe for concurrent and re-entrant usage.
+     *
+     * @param schema Binary schema definition
+     * @param data Object to encode
+     * @returns A Uint8Array containing the encoded bytes
+     */
+    static encodeInto(schema, data) {
+        const size = getSchemaSize(schema);
+        const buffer = new ArrayBuffer(size);
+        const view = new DataView(buffer);
+        let o = 0;
+        for (const k of Object.keys(schema)) {
+            const f = schema[k];
+            f.write(view, o, data[k]);
+            o += f.size;
+        }
+        return new Uint8Array(buffer);
+    }
+    /**
+     * Decodes a binary buffer into a target object using the given schema.
+     *
+     * Validates buffer size before reading.
+     * Does not mutate shared state.
+     *
+     * @param schema Binary schema definition
+     * @param buf Buffer containing encoded data
+     * @param target Target object to mutate
+     * @returns The mutated target object
+     */
+    static decodeInto(schema, buf, target) {
+        const expectedSize = getSchemaSize(schema);
+        if (buf.byteLength < expectedSize) {
+            throw new RangeError(`Buffer too small: expected ${expectedSize} bytes, got ${buf.byteLength}`);
+        }
+        const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+        let o = 0;
+        for (const k of Object.keys(schema)) {
+            const f = schema[k];
+            target[k] = f.read(view, o);
+            o += f.size;
+        }
+        return target;
+    }
+}
+/**
+ * Built-in binary primitive field definitions for multiplayer games.
+ */
+export class BinaryPrimitives {
+    /**
+     * String field with UTF-8 encoding and 2-byte length prefix.
+     * @param maxLength Maximum number of bytes allowed
+     */
+    static string(maxLength) {
+        return {
+            size: maxLength + 2,
+            write(dv, o, v) {
+                const encoder = new TextEncoder();
+                const bytes = encoder.encode(v);
+                if (bytes.length > maxLength)
+                    throw new RangeError(`String too long, max ${maxLength} bytes`);
+                dv.setUint16(o, bytes.length, false);
+                for (let i = 0; i < bytes.length; i++)
+                    dv.setUint8(o + 2 + i, bytes[i]);
+                for (let i = bytes.length; i < maxLength; i++)
+                    dv.setUint8(o + 2 + i, 0);
+            },
+            read(dv, o) {
+                const length = dv.getUint16(o, false);
+                const bytes = new Uint8Array(length);
+                for (let i = 0; i < length; i++)
+                    bytes[i] = dv.getUint8(o + 2 + i);
+                return new TextDecoder().decode(bytes);
+            },
+            toNil: () => "",
+        };
+    }
+}
+/** Unsigned 8-bit integer */
+BinaryPrimitives.u8 = {
+    size: 1,
+    write: (dv, o, v) => dv.setUint8(o, v),
+    read: (dv, o) => dv.getUint8(o),
+    toNil: () => 0,
+};
+/** Unsigned 16-bit integer (big-endian) */
+BinaryPrimitives.u16 = {
+    size: 2,
+    write: (dv, o, v) => dv.setUint16(o, v, false),
+    read: (dv, o) => dv.getUint16(o, false),
+    toNil: () => 0,
+};
+/** Unsigned 32-bit integer (big-endian) */
+BinaryPrimitives.u32 = {
+    size: 4,
+    write: (dv, o, v) => dv.setUint32(o, v, false),
+    read: (dv, o) => dv.getUint32(o, false),
+    toNil: () => 0,
+};
+/** Signed 8-bit integer */
+BinaryPrimitives.i8 = {
+    size: 1,
+    write: (dv, o, v) => dv.setInt8(o, v),
+    read: (dv, o) => dv.getInt8(o),
+    toNil: () => 0,
+};
+/** Signed 16-bit integer (big-endian) */
+BinaryPrimitives.i16 = {
+    size: 2,
+    write: (dv, o, v) => dv.setInt16(o, v, false),
+    read: (dv, o) => dv.getInt16(o, false),
+    toNil: () => 0,
+};
+/** Signed 32-bit integer (big-endian) */
+BinaryPrimitives.i32 = {
+    size: 4,
+    write: (dv, o, v) => dv.setInt32(o, v, false),
+    read: (dv, o) => dv.getInt32(o, false),
+    toNil: () => 0,
+};
+/** 32-bit floating point number (IEEE 754, big-endian) */
+BinaryPrimitives.f32 = {
+    size: 4,
+    write: (dv, o, v) => dv.setFloat32(o, v, false),
+    read: (dv, o) => dv.getFloat32(o, false),
+    toNil: () => 0,
+};
+/** 64-bit floating point number (double, big-endian) */
+BinaryPrimitives.f64 = {
+    size: 8,
+    write: (dv, o, v) => dv.setFloat64(o, v, false),
+    read: (dv, o) => dv.getFloat64(o, false),
+    toNil: () => 0,
+};
+/** Boolean stored as 1 byte (0 = false, 1 = true) */
+BinaryPrimitives.bool = {
+    size: 1,
+    write: (dv, o, v) => dv.setUint8(o, v ? 1 : 0),
+    read: (dv, o) => dv.getUint8(o) !== 0,
+    toNil: () => false,
+};
+/** 2D vector of f32 (x, y) */
+BinaryPrimitives.vec2 = {
+    size: 8,
+    write(dv, o, v) {
+        dv.setFloat32(o, v.x, false);
+        dv.setFloat32(o + 4, v.y, false);
+    },
+    read(dv, o) {
+        return { x: dv.getFloat32(o, false), y: dv.getFloat32(o + 4, false) };
+    },
+    toNil: () => ({ x: 0, y: 0 }),
+};
+/** 3D vector of f32 (x, y, z) */
+BinaryPrimitives.vec3 = {
+    size: 12,
+    write(dv, o, v) {
+        dv.setFloat32(o, v.x, false);
+        dv.setFloat32(o + 4, v.y, false);
+        dv.setFloat32(o + 8, v.z, false);
+    },
+    read(dv, o) {
+        return {
+            x: dv.getFloat32(o, false),
+            y: dv.getFloat32(o + 4, false),
+            z: dv.getFloat32(o + 8, false),
+        };
+    },
+    toNil: () => ({ x: 0, y: 0, z: 0 }),
+};
+/** RGBA color packed as 4 u8 bytes */
+BinaryPrimitives.color = {
+    size: 4,
+    write(dv, o, v) {
+        dv.setUint8(o, v.r);
+        dv.setUint8(o + 1, v.g);
+        dv.setUint8(o + 2, v.b);
+        dv.setUint8(o + 3, v.a);
+    },
+    read(dv, o) {
+        return {
+            r: dv.getUint8(o),
+            g: dv.getUint8(o + 1),
+            b: dv.getUint8(o + 2),
+            a: dv.getUint8(o + 3),
+        };
+    },
+    toNil: () => ({ r: 0, g: 0, b: 0, a: 0 }),
+};
+/** 32-bit floating point number (IEEE 754, little-endian) */
+BinaryPrimitives.f32_le = {
+    size: 4,
+    write: (dv, o, v) => dv.setFloat32(o, v, true),
+    read: (dv, o) => dv.getFloat32(o, true),
+    toNil: () => 0,
+};
+/** 64-bit floating point number (double, little-endian) */
+BinaryPrimitives.f64_le = {
+    size: 8,
+    write: (dv, o, v) => dv.setFloat64(o, v, true),
+    read: (dv, o) => dv.getFloat64(o, true),
+    toNil: () => 0,
+};
+/** Unsigned 16-bit integer (little-endian) */
+BinaryPrimitives.u16_le = {
+    size: 2,
+    write: (dv, o, v) => dv.setUint16(o, v, true),
+    read: (dv, o) => dv.getUint16(o, true),
+    toNil: () => 0,
+};
+/** Unsigned 32-bit integer (little-endian) */
+BinaryPrimitives.u32_le = {
+    size: 4,
+    write: (dv, o, v) => dv.setUint32(o, v, true),
+    read: (dv, o) => dv.getUint32(o, true),
+    toNil: () => 0,
+};
+/** Signed 16-bit integer (little-endian) */
+BinaryPrimitives.i16_le = {
+    size: 2,
+    write: (dv, o, v) => dv.setInt16(o, v, true),
+    read: (dv, o) => dv.getInt16(o, true),
+    toNil: () => 0,
+};
+/** Signed 32-bit integer (little-endian) */
+BinaryPrimitives.i32_le = {
+    size: 4,
+    write: (dv, o, v) => dv.setInt32(o, v, true),
+    read: (dv, o) => dv.getInt32(o, true),
+    toNil: () => 0,
+};
+/**
+ * 2D vector of f32 stored as a tuple [x, y] (little-endian).
+ * Useful for compact math data or shader-friendly layouts.
+ */
+BinaryPrimitives.vec2_le = {
+    size: 8,
+    write: (dv, o, v) => {
+        dv.setFloat32(o, v[0], true);
+        dv.setFloat32(o + 4, v[1], true);
+    },
+    read: (dv, o) => [
+        dv.getFloat32(o, true),
+        dv.getFloat32(o + 4, true),
+    ],
+    toNil: () => [0, 0],
+};
+/**
+ * 3D vector of f32 stored as a tuple [x, y, z] (little-endian).
+ * Commonly used for positions, velocities, or directions.
+ */
+BinaryPrimitives.vec3_le = {
+    size: 12,
+    write: (dv, o, v) => {
+        dv.setFloat32(o, v[0], true);
+        dv.setFloat32(o + 4, v[1], true);
+        dv.setFloat32(o + 8, v[2], true);
+    },
+    read: (dv, o) => [
+        dv.getFloat32(o, true),
+        dv.getFloat32(o + 4, true),
+        dv.getFloat32(o + 8, true),
+    ],
+    toNil: () => [0, 0, 0],
+};
+/**
+ * 4D vector of f32 stored as a tuple [x, y, z, w] (little-endian).
+ * Useful for quaternions, colors in shaders, or homogeneous coordinates.
+ */
+BinaryPrimitives.vec4_le = {
+    size: 16,
+    write: (dv, o, v) => {
+        dv.setFloat32(o, v[0], true);
+        dv.setFloat32(o + 4, v[1], true);
+        dv.setFloat32(o + 8, v[2], true);
+        dv.setFloat32(o + 12, v[3], true);
+    },
+    read: (dv, o) => [
+        dv.getFloat32(o, true),
+        dv.getFloat32(o + 4, true),
+        dv.getFloat32(o + 8, true),
+        dv.getFloat32(o + 12, true),
+    ],
+    toNil: () => [0, 0, 0, 0],
+};
+/**
+ * Public codec API.
+ * Re-exports primitives and exposes encode/decode helpers.
+ */
+export class BinaryCodec extends BaseBinaryCodec {
+    /**
+     * Encodes an object into a binary buffer.
+     */
+    static encode(schema, data) {
+        return this.encodeInto(schema, data);
+    }
+    /**
+     * Decodes a binary buffer into an existing object.
+     */
+    static decode(schema, buf, target) {
+        return this.decodeInto(schema, buf, target);
+    }
+}
+/** Unsigned 8-bit integer field */
+BinaryCodec.u8 = BinaryPrimitives.u8;
+/** Unsigned 16-bit integer field */
+BinaryCodec.u16 = BinaryPrimitives.u16;
+/** 32-bit floating point field */
+BinaryCodec.f32 = BinaryPrimitives.f32;

package/dist/core/binary-codec/index.d.ts

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

package/dist/core/binary-codec/index.js

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

package/dist/core/events/event-system.d.ts

@@ -0,0 +1,71 @@
+type Callback<Props> = (props: Props) => void;
+type EventMapFromTuple<T extends [string, unknown][]> = {
+    [K in T[number] as K[0]]: K[1];
+};
+interface EventSystemProps<EventNames extends string> {
+    /**
+     * @description
+     * The list of events to ever be registered.
+     */
+    events: EventNames[];
+}
+/**
+ * @description
+ * A callback-based event handling system designed to simplify
+ * event-driven programming.
+ */
+export declare class EventSystem<EventTuple extends [string, unknown][]> {
+    /**
+     * @private
+     * @description
+     * The map of registered events and their callbacks.
+    */
+    private callbacks;
+    /**
+     * @private
+     * @description
+     * The list of events that were registered.
+    */
+    private events;
+    constructor({ events }: EventSystemProps<string>);
+    /**
+     * @description
+     * Registers a callback for an event.
+     *
+     * @param name Event name
+     * @param callback Callback to run when the event is emitted
+     */
+    on<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name: EventName, callback: Callback<EventMapFromTuple<EventTuple>[EventName]>): void;
+    /**
+     * @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<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name: EventName, callback: Callback<EventMapFromTuple<EventTuple>[EventName]>): void;
+    /**
+     * @description
+     * Emits an event, running all registered callbacks.
+     *
+     * @param name Event name
+     * @param data Event data
+     */
+    emit<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name: EventName, data: EventMapFromTuple<EventTuple>[EventName]): void;
+    /**
+     * @description
+     * Removes a callback from an event.
+     *
+     * @param name Event name
+     * @param callback Callback to remove
+     */
+    off<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name: EventName, callback: Callback<EventMapFromTuple<EventTuple>[EventName]>): void;
+    /**
+     * @description
+     * Removes all callbacks.
+     *
+     * @param name Optional event name
+     */
+    clear<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name?: EventName): void;
+}
+export {};