modd-network 1.0.2 → 1.0.3

package/dist/binary-input.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Binary Input Protocol
+ *
+ * Minimal bandwidth for game inputs. Server knows client from connection.
+ *
+ * Message format: [type:1][payload:variable]
+ *
+ * Types:
+ *   0x01 KEY      - [key:1] where bit7=down, bits0-6=keyIndex
+ *   0x02 CAMERA   - [yaw:2][pitch:2] as int16 (radians * 10000)
+ *   0x03 SHOOT    - no payload (uses current camera)
+ *   0x04 JOIN     - no payload
+ *   0x05 LEAVE    - no payload
+ *   0x06 KEYS     - [count:1][keys:count] batch of key changes
+ */
+export declare const InputType: {
+    readonly KEY: 1;
+    readonly CAMERA: 2;
+    readonly SHOOT: 3;
+    readonly JOIN: 4;
+    readonly LEAVE: 5;
+    readonly KEYS: 6;
+};
+export declare const KeyIndex: {
+    readonly W: 0;
+    readonly A: 1;
+    readonly S: 2;
+    readonly D: 3;
+    readonly SPACE: 4;
+    readonly SHIFT: 5;
+    readonly CTRL: 6;
+    readonly E: 7;
+    readonly Q: 8;
+    readonly R: 9;
+    readonly F: 10;
+};
+export declare function encodeKey(key: string, down: boolean): Uint8Array;
+export declare function encodeKeys(keys: Array<{
+    key: string;
+    down: boolean;
+}>): Uint8Array;
+export declare function encodeCamera(yaw: number, pitch: number): Uint8Array;
+export declare function encodeShoot(): Uint8Array;
+export declare function encodeJoin(): Uint8Array;
+export declare function encodeLeave(): Uint8Array;
+export interface DecodedInput {
+    type: 'key' | 'camera' | 'shoot' | 'join' | 'leave';
+    key?: string;
+    down?: boolean;
+    yaw?: number;
+    pitch?: number;
+}
+export declare function decodeInput(buf: Uint8Array): DecodedInput[];

package/dist/binary-input.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Binary Input Protocol
+ *
+ * Minimal bandwidth for game inputs. Server knows client from connection.
+ *
+ * Message format: [type:1][payload:variable]
+ *
+ * Types:
+ *   0x01 KEY      - [key:1] where bit7=down, bits0-6=keyIndex
+ *   0x02 CAMERA   - [yaw:2][pitch:2] as int16 (radians * 10000)
+ *   0x03 SHOOT    - no payload (uses current camera)
+ *   0x04 JOIN     - no payload
+ *   0x05 LEAVE    - no payload
+ *   0x06 KEYS     - [count:1][keys:count] batch of key changes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyIndex = exports.InputType = void 0;
+exports.encodeKey = encodeKey;
+exports.encodeKeys = encodeKeys;
+exports.encodeCamera = encodeCamera;
+exports.encodeShoot = encodeShoot;
+exports.encodeJoin = encodeJoin;
+exports.encodeLeave = encodeLeave;
+exports.decodeInput = decodeInput;
+exports.InputType = {
+    KEY: 0x01,
+    CAMERA: 0x02,
+    SHOOT: 0x03,
+    JOIN: 0x04,
+    LEAVE: 0x05,
+    KEYS: 0x06,
+};
+// Key indices - extendable
+exports.KeyIndex = {
+    W: 0,
+    A: 1,
+    S: 2,
+    D: 3,
+    SPACE: 4,
+    SHIFT: 5,
+    CTRL: 6,
+    E: 7,
+    Q: 8,
+    R: 9,
+    F: 10,
+    // Add more as needed, up to 127
+};
+const KEY_DOWN_BIT = 0x80;
+// Reverse lookup for decoding
+const keyIndexToName = {
+    0: 'w', 1: 'a', 2: 's', 3: 'd',
+    4: 'space', 5: 'shift', 6: 'ctrl',
+    7: 'e', 8: 'q', 9: 'r', 10: 'f'
+};
+const keyNameToIndex = {
+    'w': 0, 'a': 1, 's': 2, 'd': 3,
+    'space': 4, ' ': 4,
+    'shift': 5, 'ctrl': 6, 'control': 6,
+    'e': 7, 'q': 8, 'r': 9, 'f': 10
+};
+// ============================================
+// Encoding (Client -> Server)
+// ============================================
+function encodeKey(key, down) {
+    const buf = new Uint8Array(2);
+    buf[0] = exports.InputType.KEY;
+    const keyIdx = keyNameToIndex[key.toLowerCase()] ?? 0;
+    buf[1] = keyIdx | (down ? KEY_DOWN_BIT : 0);
+    return buf;
+}
+function encodeKeys(keys) {
+    if (keys.length === 1) {
+        return encodeKey(keys[0].key, keys[0].down);
+    }
+    const buf = new Uint8Array(2 + keys.length);
+    buf[0] = exports.InputType.KEYS;
+    buf[1] = keys.length;
+    for (let i = 0; i < keys.length; i++) {
+        const keyIdx = keyNameToIndex[keys[i].key.toLowerCase()] ?? 0;
+        buf[2 + i] = keyIdx | (keys[i].down ? KEY_DOWN_BIT : 0);
+    }
+    return buf;
+}
+function encodeCamera(yaw, pitch) {
+    const buf = new Uint8Array(5);
+    buf[0] = exports.InputType.CAMERA;
+    // Convert radians to int16 (multiply by 10000 for ~0.0001 precision)
+    const yawInt = Math.round(yaw * 10000);
+    const pitchInt = Math.round(pitch * 10000);
+    buf[1] = yawInt & 0xFF;
+    buf[2] = (yawInt >> 8) & 0xFF;
+    buf[3] = pitchInt & 0xFF;
+    buf[4] = (pitchInt >> 8) & 0xFF;
+    return buf;
+}
+function encodeShoot() {
+    return new Uint8Array([exports.InputType.SHOOT]);
+}
+function encodeJoin() {
+    return new Uint8Array([exports.InputType.JOIN]);
+}
+function encodeLeave() {
+    return new Uint8Array([exports.InputType.LEAVE]);
+}
+function decodeInput(buf) {
+    if (buf.length === 0)
+        return [];
+    const type = buf[0];
+    const results = [];
+    switch (type) {
+        case exports.InputType.KEY: {
+            const keyByte = buf[1];
+            const down = (keyByte & KEY_DOWN_BIT) !== 0;
+            const keyIdx = keyByte & 0x7F;
+            results.push({
+                type: 'key',
+                key: keyIndexToName[keyIdx] ?? 'unknown',
+                down
+            });
+            break;
+        }
+        case exports.InputType.KEYS: {
+            const count = buf[1];
+            for (let i = 0; i < count; i++) {
+                const keyByte = buf[2 + i];
+                const down = (keyByte & KEY_DOWN_BIT) !== 0;
+                const keyIdx = keyByte & 0x7F;
+                results.push({
+                    type: 'key',
+                    key: keyIndexToName[keyIdx] ?? 'unknown',
+                    down
+                });
+            }
+            break;
+        }
+        case exports.InputType.CAMERA: {
+            const yawInt = buf[1] | (buf[2] << 8);
+            const pitchInt = buf[3] | (buf[4] << 8);
+            // Convert from uint16 to int16
+            const yaw = (yawInt > 32767 ? yawInt - 65536 : yawInt) / 10000;
+            const pitch = (pitchInt > 32767 ? pitchInt - 65536 : pitchInt) / 10000;
+            results.push({ type: 'camera', yaw, pitch });
+            break;
+        }
+        case exports.InputType.SHOOT:
+            results.push({ type: 'shoot' });
+            break;
+        case exports.InputType.JOIN:
+            results.push({ type: 'join' });
+            break;
+        case exports.InputType.LEAVE:
+            results.push({ type: 'leave' });
+            break;
+    }
+    return results;
+}
+// ============================================
+// Size comparison
+// ============================================
+// JSON keypress: ~65 bytes
+// Binary keypress: 2 bytes (32x smaller)
+//
+// JSON camera: ~50 bytes
+// Binary camera: 5 bytes (10x smaller)
+//
+// JSON shoot: ~40 bytes
+// Binary shoot: 1 byte (40x smaller)

package/dist/game-input-codec.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Game Input Codec - Ultra-compact binary encoding for game inputs
+ *
+ * Instead of sending 180+ byte JSON:
+ *   {"type":"move","keys":{"w":true,"a":false},"mouseX":400,"mouseY":300,"yaw":1.5}
+ *
+ * We send ~10 bytes binary:
+ *   [type:1][keys:2][mouseX:2][mouseY:2][yaw:2][pitch:2] = 11 bytes
+ *
+ * This is a 15-20x reduction in bandwidth for move inputs.
+ */
+export interface MoveInput {
+    type?: 'move' | 'input';
+    keys?: Record<string, boolean>;
+    mouseX?: number;
+    mouseY?: number;
+    x?: number;
+    y?: number;
+    yaw?: number;
+    pitch?: number;
+    seq?: number;
+    pid?: string;
+}
+export interface JoinInput {
+    type: 'join';
+    user?: {
+        id: string;
+        name?: string;
+    };
+    id?: string;
+}
+export interface LeaveInput {
+    type: 'leave';
+    id?: string;
+}
+export type GameInput = MoveInput | JoinInput | LeaveInput | {
+    type: string;
+    [key: string]: any;
+};
+/**
+ * Encode a game input to compact binary
+ * Returns null if input cannot be encoded (will fall back to JSON)
+ */
+export declare function encodeGameInput(input: GameInput, playerId?: string): Uint8Array;
+/**
+ * Decode binary input back to object
+ */
+export declare function decodeGameInput(buf: Uint8Array | ArrayBuffer, offset?: number): {
+    input: GameInput;
+    bytesRead: number;
+} | null;
+/**
+ * Check if an input will use compact binary encoding (vs JSON fallback)
+ */
+export declare function isCompactInput(input: GameInput): boolean;

package/dist/game-input-codec.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Game Input Codec - Ultra-compact binary encoding for game inputs
+ *
+ * Instead of sending 180+ byte JSON:
+ *   {"type":"move","keys":{"w":true,"a":false},"mouseX":400,"mouseY":300,"yaw":1.5}
+ *
+ * We send ~10 bytes binary:
+ *   [type:1][keys:2][mouseX:2][mouseY:2][yaw:2][pitch:2] = 11 bytes
+ *
+ * This is a 15-20x reduction in bandwidth for move inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeGameInput = encodeGameInput;
+exports.decodeGameInput = decodeGameInput;
+exports.isCompactInput = isCompactInput;
+// Input types
+const INPUT_TYPE = {
+    MOVE: 0x01, // Standard movement input
+    JOIN: 0x02, // Player joined
+    LEAVE: 0x03, // Player left
+    CUSTOM: 0xFF, // Fallback to JSON for unknown types
+};
+// Key bitmask positions (16 keys max with 2 bytes)
+const KEY_BITS = {
+    'w': 0,
+    'a': 1,
+    's': 2,
+    'd': 3,
+    'space': 4,
+    ' ': 4,
+    'shift': 5,
+    'ctrl': 6,
+    'control': 6,
+    'e': 7,
+    'q': 8,
+    'r': 9,
+    'f': 10,
+    'tab': 11,
+    'mouse0': 12, // Left click
+    'mouse1': 13, // Right click
+    'mouse2': 14, // Middle click
+    'jump': 4, // Alias for space
+};
+const KEY_NAMES = ['w', 'a', 's', 'd', 'space', 'shift', 'ctrl', 'e', 'q', 'r', 'f', 'tab', 'mouse0', 'mouse1', 'mouse2'];
+/**
+ * Encode a game input to compact binary
+ * Returns null if input cannot be encoded (will fall back to JSON)
+ */
+function encodeGameInput(input, playerId) {
+    if (!input) {
+        return encodeCustom(input);
+    }
+    const type = input.type || 'move';
+    switch (type) {
+        case 'move':
+        case 'input':
+        case undefined:
+            return encodeMove(input, playerId);
+        case 'join':
+            return encodeJoin(input);
+        case 'leave':
+            return encodeLeave(input);
+        default:
+            return encodeCustom(input);
+    }
+}
+/**
+ * Encode move/input - the most common and bandwidth-critical input type
+ * Format: [MOVE:1][keys:2][mouseX:2][mouseY:2][yaw:2][pitch:2][pidLen:1][pid:var] = 12+ bytes
+ */
+function encodeMove(input, playerId) {
+    const pid = playerId || input.pid || '';
+    const pidBytes = new TextEncoder().encode(pid);
+    // 1 + 2 + 2 + 2 + 2 + 2 + 1 + pidLen = 12 + pidLen bytes
+    const buf = new Uint8Array(12 + pidBytes.length);
+    const view = new DataView(buf.buffer);
+    buf[0] = INPUT_TYPE.MOVE;
+    // Encode keys as bitmask
+    let keyBits = 0;
+    if (input.keys) {
+        for (const [key, pressed] of Object.entries(input.keys)) {
+            if (pressed) {
+                const bit = KEY_BITS[key.toLowerCase()];
+                if (bit !== undefined) {
+                    keyBits |= (1 << bit);
+                }
+            }
+        }
+    }
+    view.setUint16(1, keyBits, true);
+    // Mouse position as uint16 (0-65535 range, plenty for screens)
+    const mouseX = Math.max(0, Math.min(65535, Math.round(input.mouseX ?? input.x ?? 0)));
+    const mouseY = Math.max(0, Math.min(65535, Math.round(input.mouseY ?? input.y ?? 0)));
+    view.setUint16(3, mouseX, true);
+    view.setUint16(5, mouseY, true);
+    // Yaw/pitch as int16 (scaled by 10000 for precision)
+    // Yaw range: [-π, π] -> [-31416, 31416] fits in int16
+    const yawScaled = Math.round((input.yaw ?? 0) * 10000);
+    const pitchScaled = Math.round((input.pitch ?? 0) * 10000);
+    view.setInt16(7, Math.max(-32768, Math.min(32767, yawScaled)), true);
+    view.setInt16(9, Math.max(-32768, Math.min(32767, pitchScaled)), true);
+    // Player ID
+    buf[11] = pidBytes.length;
+    buf.set(pidBytes, 12);
+    return buf;
+}
+/**
+ * Encode join event
+ * Format: [JOIN:1][pidLen:1][pid:var][nameLen:1][name:var]
+ */
+function encodeJoin(input) {
+    const pid = input.user?.id || input.id || '';
+    const name = input.user?.name || '';
+    const pidBytes = new TextEncoder().encode(pid);
+    const nameBytes = new TextEncoder().encode(name);
+    const buf = new Uint8Array(3 + pidBytes.length + nameBytes.length);
+    buf[0] = INPUT_TYPE.JOIN;
+    buf[1] = pidBytes.length;
+    buf.set(pidBytes, 2);
+    buf[2 + pidBytes.length] = nameBytes.length;
+    buf.set(nameBytes, 3 + pidBytes.length);
+    return buf;
+}
+/**
+ * Encode leave event
+ * Format: [LEAVE:1][pidLen:1][pid:var]
+ */
+function encodeLeave(input) {
+    const pid = input.id || '';
+    const pidBytes = new TextEncoder().encode(pid);
+    const buf = new Uint8Array(2 + pidBytes.length);
+    buf[0] = INPUT_TYPE.LEAVE;
+    buf[1] = pidBytes.length;
+    buf.set(pidBytes, 2);
+    return buf;
+}
+/**
+ * Encode custom/unknown input types as JSON (fallback)
+ * Format: [CUSTOM:1][len:2][json:var]
+ */
+function encodeCustom(input) {
+    const json = JSON.stringify(input);
+    const jsonBytes = new TextEncoder().encode(json);
+    const buf = new Uint8Array(3 + jsonBytes.length);
+    const view = new DataView(buf.buffer);
+    buf[0] = INPUT_TYPE.CUSTOM;
+    view.setUint16(1, jsonBytes.length, true);
+    buf.set(jsonBytes, 3);
+    return buf;
+}
+/**
+ * Decode binary input back to object
+ */
+function decodeGameInput(buf, offset = 0) {
+    const data = buf instanceof ArrayBuffer ? new Uint8Array(buf) : buf;
+    if (data.length <= offset)
+        return null;
+    const type = data[offset];
+    switch (type) {
+        case INPUT_TYPE.MOVE:
+            return decodeMove(data, offset);
+        case INPUT_TYPE.JOIN:
+            return decodeJoin(data, offset);
+        case INPUT_TYPE.LEAVE:
+            return decodeLeave(data, offset);
+        case INPUT_TYPE.CUSTOM:
+            return decodeCustom(data, offset);
+        default:
+            return null;
+    }
+}
+function decodeMove(data, offset) {
+    if (data.length < offset + 12)
+        return null;
+    const view = new DataView(data.buffer, data.byteOffset + offset);
+    const keyBits = view.getUint16(1, true);
+    const mouseX = view.getUint16(3, true);
+    const mouseY = view.getUint16(5, true);
+    const yawScaled = view.getInt16(7, true);
+    const pitchScaled = view.getInt16(9, true);
+    const pidLen = data[offset + 11];
+    if (data.length < offset + 12 + pidLen)
+        return null;
+    const pid = new TextDecoder().decode(data.slice(offset + 12, offset + 12 + pidLen));
+    // Decode keys
+    const keys = {};
+    for (let i = 0; i < KEY_NAMES.length; i++) {
+        keys[KEY_NAMES[i]] = (keyBits & (1 << i)) !== 0;
+    }
+    return {
+        input: {
+            type: 'input',
+            keys,
+            mouseX,
+            mouseY,
+            yaw: yawScaled / 10000,
+            pitch: pitchScaled / 10000,
+            pid: pid || undefined,
+        },
+        bytesRead: 12 + pidLen
+    };
+}
+function decodeJoin(data, offset) {
+    if (data.length < offset + 3)
+        return null;
+    const pidLen = data[offset + 1];
+    if (data.length < offset + 2 + pidLen + 1)
+        return null;
+    const pid = new TextDecoder().decode(data.slice(offset + 2, offset + 2 + pidLen));
+    const nameLen = data[offset + 2 + pidLen];
+    if (data.length < offset + 3 + pidLen + nameLen)
+        return null;
+    const name = new TextDecoder().decode(data.slice(offset + 3 + pidLen, offset + 3 + pidLen + nameLen));
+    return {
+        input: {
+            type: 'join',
+            user: { id: pid, name: name || undefined },
+            id: pid,
+        },
+        bytesRead: 3 + pidLen + nameLen
+    };
+}
+function decodeLeave(data, offset) {
+    if (data.length < offset + 2)
+        return null;
+    const pidLen = data[offset + 1];
+    if (data.length < offset + 2 + pidLen)
+        return null;
+    const pid = new TextDecoder().decode(data.slice(offset + 2, offset + 2 + pidLen));
+    return {
+        input: {
+            type: 'leave',
+            id: pid,
+        },
+        bytesRead: 2 + pidLen
+    };
+}
+function decodeCustom(data, offset) {
+    if (data.length < offset + 3)
+        return null;
+    const view = new DataView(data.buffer, data.byteOffset + offset);
+    const jsonLen = view.getUint16(1, true);
+    if (data.length < offset + 3 + jsonLen)
+        return null;
+    const json = new TextDecoder().decode(data.slice(offset + 3, offset + 3 + jsonLen));
+    try {
+        return {
+            input: JSON.parse(json),
+            bytesRead: 3 + jsonLen
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if an input will use compact binary encoding (vs JSON fallback)
+ */
+function isCompactInput(input) {
+    const type = input?.type;
+    return type === 'move' || type === 'input' || type === 'join' || type === 'leave' || type === undefined;
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from './modd-network';
+export { connect as networkConnect, modd, type Connection, type ConnectOptions, type Input } from './modd-network';
 export * from './modd-engine';

package/dist/index.js

@@ -14,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./modd-network"), exports);
+exports.modd = exports.networkConnect = void 0;
+// Re-export modd-network (but rename connect to avoid conflict)
+var modd_network_1 = require("./modd-network");
+Object.defineProperty(exports, "networkConnect", { enumerable: true, get: function () { return modd_network_1.connect; } });
+Object.defineProperty(exports, "modd", { enumerable: true, get: function () { return modd_network_1.modd; } });
+// Re-export modd-engine (this is the main API)
 __exportStar(require("./modd-engine"), exports);
+// modd-engine.connect is the primary connect function

package/dist/input-codec.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Input Codec - Compresses readable inputs to binary
+ *
+ * Game sends: { type: 'keydown', key: 'w' }
+ * Wire sends: [0x01, 0x80] (2 bytes)
+ *
+ * Game sends: { type: 'camera', yaw: 1.5, pitch: 0.3 }
+ * Wire sends: [0x02, yaw_lo, yaw_hi, pitch_lo, pitch_hi] (5 bytes)
+ */
+/**
+ * Compress a readable input to binary
+ */
+export declare function compress(input: any): Uint8Array | null;
+/**
+ * Compress multiple inputs into single buffer
+ */
+export declare function compressBatch(inputs: any[]): Uint8Array | null;
+/**
+ * Decompress binary back to readable input
+ */
+export declare function decompress(buf: Uint8Array, offset?: number): {
+    input: any;
+    bytesRead: number;
+} | null;
+/**
+ * Decompress a batch of inputs
+ */
+export declare function decompressBatch(buf: Uint8Array): any[];
+/**
+ * Check if an input can be compressed
+ * Note: join/leave are excluded because they contain unique player ID data
+ */
+export declare function canCompress(input: any): boolean;