modd-network 1.0.1 → 1.0.3

package/dist/input-codec.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compress = compress;
+exports.compressBatch = compressBatch;
+exports.decompress = decompress;
+exports.decompressBatch = decompressBatch;
+exports.canCompress = canCompress;
+// Message types
+const MSG = {
+    KEY: 0x01,
+    CAMERA: 0x02,
+    SHOOT: 0x03,
+    JOIN: 0x04,
+    LEAVE: 0x05,
+};
+// Key indices
+const KEY_MAP = {
+    '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,
+    'mouse0': 11, 'mouse1': 12, 'mouse2': 13,
+};
+const KEY_NAMES = [
+    'w', 'a', 's', 'd', 'space', 'shift', 'ctrl',
+    'e', 'q', 'r', 'f', 'mouse0', 'mouse1', 'mouse2'
+];
+const KEY_DOWN_BIT = 0x80;
+/**
+ * Compress a readable input to binary
+ */
+function compress(input) {
+    if (!input || !input.type)
+        return null;
+    switch (input.type) {
+        case 'keydown':
+        case 'keyup': {
+            const down = input.type === 'keydown';
+            const keyIdx = KEY_MAP[input.key?.toLowerCase()] ?? 0;
+            return new Uint8Array([MSG.KEY, keyIdx | (down ? KEY_DOWN_BIT : 0)]);
+        }
+        case 'camera': {
+            const buf = new Uint8Array(5);
+            buf[0] = MSG.CAMERA;
+            // Normalize yaw to [-π, π] to fit in Int16 range
+            let yaw = (input.yaw ?? 0) % (Math.PI * 2);
+            if (yaw > Math.PI)
+                yaw -= Math.PI * 2;
+            if (yaw < -Math.PI)
+                yaw += Math.PI * 2;
+            // Pitch is naturally bounded to [-π/2, π/2]
+            const pitch = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, input.pitch ?? 0));
+            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;
+        }
+        case 'shoot':
+            return new Uint8Array([MSG.SHOOT]);
+        case 'join':
+            return new Uint8Array([MSG.JOIN]);
+        case 'leave':
+            return new Uint8Array([MSG.LEAVE]);
+        default:
+            // Unknown type - can't compress
+            return null;
+    }
+}
+/**
+ * Compress multiple inputs into single buffer
+ */
+function compressBatch(inputs) {
+    if (inputs.length === 0)
+        return null;
+    if (inputs.length === 1)
+        return compress(inputs[0]);
+    // Calculate total size
+    const buffers = [];
+    for (const input of inputs) {
+        const buf = compress(input);
+        if (!buf)
+            return null; // Can't compress one = can't compress batch
+        buffers.push(buf);
+    }
+    // Concatenate with length prefix
+    const totalSize = buffers.reduce((sum, b) => sum + b.length, 0);
+    const result = new Uint8Array(1 + totalSize);
+    result[0] = 0x00; // Batch marker
+    let offset = 1;
+    for (const buf of buffers) {
+        result.set(buf, offset);
+        offset += buf.length;
+    }
+    return result;
+}
+/**
+ * Decompress binary back to readable input
+ */
+function decompress(buf, offset = 0) {
+    if (buf.length <= offset)
+        return null;
+    const type = buf[offset];
+    switch (type) {
+        case MSG.KEY: {
+            const keyByte = buf[offset + 1];
+            const down = (keyByte & KEY_DOWN_BIT) !== 0;
+            const keyIdx = keyByte & 0x7F;
+            return {
+                input: {
+                    type: down ? 'keydown' : 'keyup',
+                    key: KEY_NAMES[keyIdx] ?? 'unknown'
+                },
+                bytesRead: 2
+            };
+        }
+        case MSG.CAMERA: {
+            const yawLo = buf[offset + 1];
+            const yawHi = buf[offset + 2];
+            const pitchLo = buf[offset + 3];
+            const pitchHi = buf[offset + 4];
+            let yawInt = yawLo | (yawHi << 8);
+            let pitchInt = pitchLo | (pitchHi << 8);
+            // Sign extend
+            if (yawInt > 32767)
+                yawInt -= 65536;
+            if (pitchInt > 32767)
+                pitchInt -= 65536;
+            return {
+                input: {
+                    type: 'camera',
+                    yaw: yawInt / 10000,
+                    pitch: pitchInt / 10000
+                },
+                bytesRead: 5
+            };
+        }
+        case MSG.SHOOT:
+            return { input: { type: 'shoot' }, bytesRead: 1 };
+        case MSG.JOIN:
+            return { input: { type: 'join' }, bytesRead: 1 };
+        case MSG.LEAVE:
+            return { input: { type: 'leave' }, bytesRead: 1 };
+        default:
+            return null;
+    }
+}
+/**
+ * Decompress a batch of inputs
+ */
+function decompressBatch(buf) {
+    if (buf.length === 0)
+        return [];
+    // Check for batch marker
+    if (buf[0] === 0x00) {
+        const results = [];
+        let offset = 1;
+        while (offset < buf.length) {
+            const result = decompress(buf, offset);
+            if (!result)
+                break;
+            results.push(result.input);
+            offset += result.bytesRead;
+        }
+        return results;
+    }
+    // Single message
+    const result = decompress(buf, 0);
+    return result ? [result.input] : [];
+}
+/**
+ * Check if an input can be compressed
+ * Note: join/leave are excluded because they contain unique player ID data
+ */
+function canCompress(input) {
+    if (!input?.type)
+        return false;
+    // shoot has extra data (position, direction, snapshots) - must be JSON
+    // join/leave contain player ID that must be preserved - send as JSON
+    return ['keydown', 'keyup', 'camera'].includes(input.type);
+}

package/dist/modd-engine.d.ts

@@ -1,12 +1,20 @@
 /**
  * MODD Engine SDK
- * Game synchronization utilities for multiplayer games
- * - Proximity-based authority
- * - Delta compression
- * - Rest detection
- * - Soft sync / interpolation
+ * Unified game networking with state synchronization
+ *
+ * Usage:
+ *   const game = await moddEngine.connect('my-app-id', 'my-room', {
+ *       stateSync: { lerpSpeed: 0.3 },
+ *       onConnect: (snapshot, inputs, frame) => { ... }
+ *   });
+ *
+ *   game.setLocalPlayer(playerId);
+ *   game.addPlayer(playerId, { x, y, z });
+ *   game.registerEntity('box1', adapter);
+ *   game.tick();
  */
-import type { Connection } from './modd-network';
+import { type Connection, type ConnectOptions } from './modd-network';
+export { type Connection, type ConnectOptions, type Input } from './modd-network';
 export interface EntityState {
     x: number;
     y: number;
@@ -27,69 +35,82 @@ export interface PhysicsAdapter {
     getState(): EntityState;
     setState(state: EntityState): void;
 }
-export interface EngineOptions {
-    softSyncLerp?: number;
+export interface StateSyncConfig {
+    lerpSpeed?: number;
     positionThreshold?: number;
     velocityThreshold?: number;
     rotationThreshold?: number;
     restVelocityThreshold?: number;
     restFramesRequired?: number;
-    touchBonusScore?: number;
-    touchBonusDecay?: number;
+    authorityRadius?: number;
+    playerSendRate?: number;
+    entitySendRate?: number;
+    staleThreshold?: number;
 }
-export interface Entity {
+export interface GameConnectOptions extends ConnectOptions {
+    stateSync?: StateSyncConfig;
+}
+interface GameInternal extends Game {
+    setConnection(conn: Connection): void;
+}
+export interface TrackedEntity {
     id: string;
     adapter: PhysicsAdapter;
-    state: EntityState;
-    lastSentState?: EntityState;
+    localState: EntityState;
+    targetState: EntityState;
+    lastSentState: EntityState;
     restFrames: number;
-    lastTouchedBy?: string;
-    lastTouchFrame?: number;
+    isAuthority: boolean;
+    lastUpdate: number;
 }
-export interface Player {
+export interface TrackedPlayer {
     id: string;
-    x: number;
-    y: number;
-    z: number;
-    dead?: boolean;
+    state: EntityState;
+    targetState: EntityState;
+    lastUpdate: number;
 }
-export declare function createEngine(options?: EngineOptions): {
-    readonly config: {
-        softSyncLerp: number;
-        positionThreshold: number;
-        velocityThreshold: number;
-        rotationThreshold: number;
-        restVelocityThreshold: number;
-        restFramesRequired: number;
-        touchBonusScore: number;
-        touchBonusDecay: number;
-    };
-    setConnection(conn: Connection): void;
-    setLocalPlayer(playerId: string): void;
-    setFrame(frame: number): void;
+export interface Game {
+    readonly connected: boolean;
+    readonly room: string | null;
+    readonly node: string | null;
+    readonly bandwidthIn: number;
+    readonly bandwidthOut: number;
+    readonly frame: number;
+    readonly localPlayerId: string | null;
+    readonly config: StateSyncConfig;
+    disconnect(): void;
+    send(data: any): void;
+    setLocalPlayer(id: string): void;
+    addPlayer(id: string, initialState: EntityState): void;
+    removePlayer(id: string): void;
+    getPlayer(id: string): TrackedPlayer | undefined;
+    getPlayers(): TrackedPlayer[];
+    updateLocalPlayerState(state: EntityState): void;
+    isPlayerStale(id: string): boolean;
+    getStalePlayers(): TrackedPlayer[];
     registerEntity(id: string, adapter: PhysicsAdapter): void;
     unregisterEntity(id: string): void;
-    getEntity(id: string): Entity | undefined;
-    updatePlayer(id: string, x: number, y: number, z: number, dead?: boolean): void;
-    removePlayer(id: string): void;
-    computeAuthority: (entityId: string) => string | null;
-    isLocalAuthority: (entityId: string) => boolean;
-    syncFromPhysics(entityId: string): void;
-    syncAllFromPhysics(): void;
-    sendUpdates: () => void;
-    handleEntityState: (id: string, state: EntityState) => void;
-    handleEntityTouch: (id: string, touchedBy: string, frame: number) => void;
-    checkPlayerTouches(playerId: string, playerX: number, playerZ: number, touchDistance?: number): void;
-    checkEntityCollisions(touchDistance?: number): void;
-    wakeEntity: (entityId: string) => void;
-    isAtRest: (entityId: string) => boolean;
-    hasStateChanged: (entityId: string) => boolean;
-};
-/**
- * Rapier 3D physics adapter
- */
+    getEntity(id: string): TrackedEntity | undefined;
+    getEntities(): TrackedEntity[];
+    isAuthority(entityId: string): boolean;
+    tick(): void;
+    processInput(input: any): void;
+}
+declare function createStateSync(options?: StateSyncConfig): GameInternal;
+export declare function connect(appId: string, room: string, options?: GameConnectOptions): Promise<Game>;
 export declare function rapierAdapter(body: any): PhysicsAdapter;
-/**
- * Generic 2D physics adapter (for Matter.js, Planck, etc.)
- */
 export declare function generic2DAdapter(getBody: () => any, setBody: (state: any) => void): PhysicsAdapter;
+interface InitOptions {
+    threeUrl?: string;
+    rapierUrl?: string;
+    skipThree?: boolean;
+    skipRapier?: boolean;
+}
+export declare function init(options?: InitOptions): Promise<{
+    THREE: any;
+    RAPIER: any;
+}>;
+export declare function getThree(): any;
+export declare function getRapier(): any;
+export { createStateSync };
+export declare const connectToRoom: typeof connect;