modd-network 1.0.1 → 1.0.3

package/dist/state-codec.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Binary State Codec
+ *
+ * Efficient encoding for player/entity state updates.
+ *
+ * Player State (variable, ~15-25 bytes vs ~150 JSON):
+ *   [0x10][id_len:1][id:var][flags:1][fields based on flags]
+ *   flags: bit0=pos, bit1=vel, bit2=rotY, bit3=hp, bit4=dead
+ *
+ * Entity State (variable, ~20-35 bytes vs ~200 JSON):
+ *   [0x11][id_len:1][id:var][flags:1][fields based on flags]
+ *   flags: bit0=pos, bit1=vel, bit2=quat, bit3=angvel
+ *
+ * Position Correction (compact, for periodic sync):
+ *   [0x12][id_len:1][id:var][x:4][y:4][z:4][rotY:2]
+ */
+export declare const StateType: {
+    readonly PLAYER_STATE: 16;
+    readonly ENTITY_STATE: 17;
+    readonly POSITION_CORRECTION: 18;
+    readonly INPUT_STATE: 19;
+};
+export interface PlayerStateData {
+    id: string;
+    x?: number;
+    y?: number;
+    z?: number;
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    rotY?: number;
+    hp?: number;
+    dead?: boolean;
+}
+export declare function encodePlayerState(data: PlayerStateData): Uint8Array;
+export declare function decodePlayerState(buf: Uint8Array, offset?: number): {
+    data: PlayerStateData;
+    bytesRead: number;
+} | null;
+export interface EntityStateData {
+    id: string;
+    x?: number;
+    y?: number;
+    z?: number;
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    qx?: number;
+    qy?: number;
+    qz?: number;
+    qw?: number;
+    avx?: number;
+    avy?: number;
+    avz?: number;
+}
+export declare function encodeEntityState(data: EntityStateData): Uint8Array;
+export declare function decodeEntityState(buf: Uint8Array, offset?: number): {
+    data: EntityStateData;
+    bytesRead: number;
+} | null;
+export interface InputStateData {
+    id: string;
+    keys: number;
+    rotY: number;
+}
+export declare const KEY_W = 1;
+export declare const KEY_A = 2;
+export declare const KEY_S = 4;
+export declare const KEY_D = 8;
+export declare const KEY_SPACE = 16;
+export declare const KEY_SHIFT = 32;
+export declare function encodeInputState(data: InputStateData): Uint8Array;
+export declare function decodeInputState(buf: Uint8Array, offset?: number): {
+    data: InputStateData;
+    bytesRead: number;
+} | null;
+export declare function decodeState(buf: Uint8Array, offset?: number): {
+    type: string;
+    data: any;
+    bytesRead: number;
+} | null;

package/dist/state-codec.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * Binary State Codec
+ *
+ * Efficient encoding for player/entity state updates.
+ *
+ * Player State (variable, ~15-25 bytes vs ~150 JSON):
+ *   [0x10][id_len:1][id:var][flags:1][fields based on flags]
+ *   flags: bit0=pos, bit1=vel, bit2=rotY, bit3=hp, bit4=dead
+ *
+ * Entity State (variable, ~20-35 bytes vs ~200 JSON):
+ *   [0x11][id_len:1][id:var][flags:1][fields based on flags]
+ *   flags: bit0=pos, bit1=vel, bit2=quat, bit3=angvel
+ *
+ * Position Correction (compact, for periodic sync):
+ *   [0x12][id_len:1][id:var][x:4][y:4][z:4][rotY:2]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_SHIFT = exports.KEY_SPACE = exports.KEY_D = exports.KEY_S = exports.KEY_A = exports.KEY_W = exports.StateType = void 0;
+exports.encodePlayerState = encodePlayerState;
+exports.decodePlayerState = decodePlayerState;
+exports.encodeEntityState = encodeEntityState;
+exports.decodeEntityState = decodeEntityState;
+exports.encodeInputState = encodeInputState;
+exports.decodeInputState = decodeInputState;
+exports.decodeState = decodeState;
+exports.StateType = {
+    PLAYER_STATE: 0x10,
+    ENTITY_STATE: 0x11,
+    POSITION_CORRECTION: 0x12,
+    INPUT_STATE: 0x13, // Full input state snapshot
+};
+// Flags for player state
+const PLAYER_HAS_POS = 0x01;
+const PLAYER_HAS_VEL = 0x02;
+const PLAYER_HAS_ROTY = 0x04;
+const PLAYER_HAS_HP = 0x08;
+const PLAYER_HAS_DEAD = 0x10;
+// Flags for entity state
+const ENTITY_HAS_POS = 0x01;
+const ENTITY_HAS_VEL = 0x02;
+const ENTITY_HAS_QUAT = 0x04;
+const ENTITY_HAS_ANGVEL = 0x08;
+// ============================================
+// Float encoding helpers
+// ============================================
+function writeFloat32(buf, offset, value) {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    view.setFloat32(offset, value, true);
+}
+function readFloat32(buf, offset) {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    return view.getFloat32(offset, true);
+}
+function writeInt16(buf, offset, value) {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    view.setInt16(offset, value, true);
+}
+function readInt16(buf, offset) {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    return view.getInt16(offset, true);
+}
+function encodePlayerState(data) {
+    const idBytes = new TextEncoder().encode(data.id);
+    // Calculate flags and size
+    let flags = 0;
+    let dataSize = 0;
+    const hasPos = data.x !== undefined || data.y !== undefined || data.z !== undefined;
+    const hasVel = data.vx !== undefined || data.vy !== undefined || data.vz !== undefined;
+    const hasRotY = data.rotY !== undefined;
+    const hasHp = data.hp !== undefined;
+    const hasDead = data.dead !== undefined;
+    if (hasPos) {
+        flags |= PLAYER_HAS_POS;
+        dataSize += 12;
+    } // 3 floats
+    if (hasVel) {
+        flags |= PLAYER_HAS_VEL;
+        dataSize += 12;
+    } // 3 floats
+    if (hasRotY) {
+        flags |= PLAYER_HAS_ROTY;
+        dataSize += 2;
+    } // int16
+    if (hasHp) {
+        flags |= PLAYER_HAS_HP;
+        dataSize += 1;
+    } // uint8
+    if (hasDead) {
+        flags |= PLAYER_HAS_DEAD;
+        dataSize += 1;
+    } // uint8
+    const buf = new Uint8Array(1 + 1 + idBytes.length + 1 + dataSize);
+    let offset = 0;
+    buf[offset++] = exports.StateType.PLAYER_STATE;
+    buf[offset++] = idBytes.length;
+    buf.set(idBytes, offset);
+    offset += idBytes.length;
+    buf[offset++] = flags;
+    if (hasPos) {
+        writeFloat32(buf, offset, data.x ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.y ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.z ?? 0);
+        offset += 4;
+    }
+    if (hasVel) {
+        writeFloat32(buf, offset, data.vx ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.vy ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.vz ?? 0);
+        offset += 4;
+    }
+    if (hasRotY) {
+        writeInt16(buf, offset, Math.round((data.rotY ?? 0) * 10000));
+        offset += 2;
+    }
+    if (hasHp) {
+        buf[offset++] = Math.min(255, Math.max(0, data.hp ?? 100));
+    }
+    if (hasDead) {
+        buf[offset++] = data.dead ? 1 : 0;
+    }
+    return buf;
+}
+function decodePlayerState(buf, offset = 0) {
+    if (buf[offset] !== exports.StateType.PLAYER_STATE)
+        return null;
+    let pos = offset + 1;
+    const idLen = buf[pos++];
+    const id = new TextDecoder().decode(buf.slice(pos, pos + idLen));
+    pos += idLen;
+    const flags = buf[pos++];
+    const data = { id };
+    if (flags & PLAYER_HAS_POS) {
+        data.x = readFloat32(buf, pos);
+        pos += 4;
+        data.y = readFloat32(buf, pos);
+        pos += 4;
+        data.z = readFloat32(buf, pos);
+        pos += 4;
+    }
+    if (flags & PLAYER_HAS_VEL) {
+        data.vx = readFloat32(buf, pos);
+        pos += 4;
+        data.vy = readFloat32(buf, pos);
+        pos += 4;
+        data.vz = readFloat32(buf, pos);
+        pos += 4;
+    }
+    if (flags & PLAYER_HAS_ROTY) {
+        data.rotY = readInt16(buf, pos) / 10000;
+        pos += 2;
+    }
+    if (flags & PLAYER_HAS_HP) {
+        data.hp = buf[pos++];
+    }
+    if (flags & PLAYER_HAS_DEAD) {
+        data.dead = buf[pos++] === 1;
+    }
+    return { data, bytesRead: pos - offset };
+}
+function encodeEntityState(data) {
+    const idBytes = new TextEncoder().encode(data.id);
+    let flags = 0;
+    let dataSize = 0;
+    const hasPos = data.x !== undefined || data.y !== undefined || data.z !== undefined;
+    const hasVel = data.vx !== undefined || data.vy !== undefined || data.vz !== undefined;
+    const hasQuat = data.qx !== undefined || data.qy !== undefined || data.qz !== undefined || data.qw !== undefined;
+    const hasAngvel = data.avx !== undefined || data.avy !== undefined || data.avz !== undefined;
+    if (hasPos) {
+        flags |= ENTITY_HAS_POS;
+        dataSize += 12;
+    }
+    if (hasVel) {
+        flags |= ENTITY_HAS_VEL;
+        dataSize += 12;
+    }
+    if (hasQuat) {
+        flags |= ENTITY_HAS_QUAT;
+        dataSize += 16;
+    } // 4 floats
+    if (hasAngvel) {
+        flags |= ENTITY_HAS_ANGVEL;
+        dataSize += 12;
+    }
+    const buf = new Uint8Array(1 + 1 + idBytes.length + 1 + dataSize);
+    let offset = 0;
+    buf[offset++] = exports.StateType.ENTITY_STATE;
+    buf[offset++] = idBytes.length;
+    buf.set(idBytes, offset);
+    offset += idBytes.length;
+    buf[offset++] = flags;
+    if (hasPos) {
+        writeFloat32(buf, offset, data.x ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.y ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.z ?? 0);
+        offset += 4;
+    }
+    if (hasVel) {
+        writeFloat32(buf, offset, data.vx ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.vy ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.vz ?? 0);
+        offset += 4;
+    }
+    if (hasQuat) {
+        writeFloat32(buf, offset, data.qx ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.qy ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.qz ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.qw ?? 1);
+        offset += 4;
+    }
+    if (hasAngvel) {
+        writeFloat32(buf, offset, data.avx ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.avy ?? 0);
+        offset += 4;
+        writeFloat32(buf, offset, data.avz ?? 0);
+        offset += 4;
+    }
+    return buf;
+}
+function decodeEntityState(buf, offset = 0) {
+    if (buf[offset] !== exports.StateType.ENTITY_STATE)
+        return null;
+    let pos = offset + 1;
+    const idLen = buf[pos++];
+    const id = new TextDecoder().decode(buf.slice(pos, pos + idLen));
+    pos += idLen;
+    const flags = buf[pos++];
+    const data = { id };
+    if (flags & ENTITY_HAS_POS) {
+        data.x = readFloat32(buf, pos);
+        pos += 4;
+        data.y = readFloat32(buf, pos);
+        pos += 4;
+        data.z = readFloat32(buf, pos);
+        pos += 4;
+    }
+    if (flags & ENTITY_HAS_VEL) {
+        data.vx = readFloat32(buf, pos);
+        pos += 4;
+        data.vy = readFloat32(buf, pos);
+        pos += 4;
+        data.vz = readFloat32(buf, pos);
+        pos += 4;
+    }
+    if (flags & ENTITY_HAS_QUAT) {
+        data.qx = readFloat32(buf, pos);
+        pos += 4;
+        data.qy = readFloat32(buf, pos);
+        pos += 4;
+        data.qz = readFloat32(buf, pos);
+        pos += 4;
+        data.qw = readFloat32(buf, pos);
+        pos += 4;
+    }
+    if (flags & ENTITY_HAS_ANGVEL) {
+        data.avx = readFloat32(buf, pos);
+        pos += 4;
+        data.avy = readFloat32(buf, pos);
+        pos += 4;
+        data.avz = readFloat32(buf, pos);
+        pos += 4;
+    }
+    return { data, bytesRead: pos - offset };
+}
+// Key bitmask
+exports.KEY_W = 0x01;
+exports.KEY_A = 0x02;
+exports.KEY_S = 0x04;
+exports.KEY_D = 0x08;
+exports.KEY_SPACE = 0x10;
+exports.KEY_SHIFT = 0x20;
+function encodeInputState(data) {
+    const idBytes = new TextEncoder().encode(data.id);
+    const buf = new Uint8Array(1 + 1 + idBytes.length + 1 + 2);
+    let offset = 0;
+    buf[offset++] = exports.StateType.INPUT_STATE;
+    buf[offset++] = idBytes.length;
+    buf.set(idBytes, offset);
+    offset += idBytes.length;
+    buf[offset++] = data.keys;
+    writeInt16(buf, offset, Math.round(data.rotY * 10000));
+    return buf;
+}
+function decodeInputState(buf, offset = 0) {
+    if (buf[offset] !== exports.StateType.INPUT_STATE)
+        return null;
+    let pos = offset + 1;
+    const idLen = buf[pos++];
+    const id = new TextDecoder().decode(buf.slice(pos, pos + idLen));
+    pos += idLen;
+    const keys = buf[pos++];
+    const rotY = readInt16(buf, pos) / 10000;
+    pos += 2;
+    return { data: { id, keys, rotY }, bytesRead: pos - offset };
+}
+// ============================================
+// Generic decode
+// ============================================
+function decodeState(buf, offset = 0) {
+    if (buf.length <= offset)
+        return null;
+    const type = buf[offset];
+    switch (type) {
+        case exports.StateType.PLAYER_STATE: {
+            const result = decodePlayerState(buf, offset);
+            if (!result)
+                return null;
+            return { type: 'playerState', data: result.data, bytesRead: result.bytesRead };
+        }
+        case exports.StateType.ENTITY_STATE: {
+            const result = decodeEntityState(buf, offset);
+            if (!result)
+                return null;
+            return { type: 'entityState', data: result.data, bytesRead: result.bytesRead };
+        }
+        case exports.StateType.INPUT_STATE: {
+            const result = decodeInputState(buf, offset);
+            if (!result)
+                return null;
+            return { type: 'inputState', data: result.data, bytesRead: result.bytesRead };
+        }
+        default:
+            return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modd-network",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "SDK for connecting to mesh network for multiplayer applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,8 @@
   "scripts": {
     "build": "tsc",
     "build:browser": "node build-browser.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -33,6 +35,7 @@
     "@types/node": "^20.10.6",
     "@types/ws": "^8.5.10",
     "esbuild": "^0.27.2",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^2.1.0"
   }
 }