murow 0.0.2 → 0.0.3

package/dist/protocol/rpc/define-rpc.js

@@ -0,0 +1,84 @@
+import { BinaryCodec } from "../../core/binary-codec";
+/**
+ * Simple codec implementation that uses BinaryCodec for encoding/decoding.
+ * @template T The RPC data type
+ */
+class RpcCodecImpl {
+    constructor(schema) {
+        this.schema = schema;
+    }
+    encode(value) {
+        return BinaryCodec.encode(this.schema, value);
+    }
+    decode(buf) {
+        // Create a target object with nil values
+        const target = {};
+        for (const key of Object.keys(this.schema)) {
+            const field = this.schema[key];
+            target[key] = field.toNil();
+        }
+        return BinaryCodec.decode(this.schema, buf, target);
+    }
+}
+/**
+ * Define a type-safe RPC with automatic schema generation.
+ *
+ * RPCs are bidirectional one-off events/commands for:
+ * - Meta-game events (achievements, notifications)
+ * - Match lifecycle (countdown, results)
+ * - Request/response patterns
+ * - System announcements
+ *
+ * NOT for game state synchronization (use Snapshots) or player inputs (use Intents)
+ *
+ * @template S The schema type
+ * @param definition RPC configuration with method and schema
+ * @returns A DefinedRpc object with method and codec
+ *
+ * @example Server → Client RPC
+ * ```ts
+ * const MatchCountdown = defineRpc({
+ *   method: 'matchCountdown',
+ *   schema: {
+ *     secondsRemaining: BinaryCodec.u8,
+ *   }
+ * });
+ *
+ * // Server sends
+ * server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 10 });
+ *
+ * // Client receives
+ * client.onRpc(MatchCountdown, (rpc) => {
+ *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
+ * });
+ * ```
+ *
+ * @example Client → Server RPC
+ * ```ts
+ * const BuyItem = defineRpc({
+ *   method: 'buyItem',
+ *   schema: {
+ *     itemId: BinaryCodec.string(32),
+ *   }
+ * });
+ *
+ * // Client sends
+ * client.sendRpc(BuyItem, { itemId: 'long_sword' });
+ *
+ * // Server receives
+ * server.onRpc(BuyItem, (peerId, rpc) => {
+ *   console.log(`${peerId} wants to buy ${rpc.itemId}`);
+ * });
+ * ```
+ */
+export function defineRpc(definition) {
+    // Create the schema from definition
+    const schema = definition.schema;
+    // Create the codec using BinaryCodec
+    const codec = new RpcCodecImpl(schema);
+    return {
+        method: definition.method,
+        codec,
+        _type: undefined, // Phantom type for inference
+    };
+}

package/dist/protocol/rpc/index.d.ts

@@ -0,0 +1,3 @@
+export * from './rpc';
+export * from './define-rpc';
+export * from './rpc-registry';

package/dist/protocol/rpc/index.js

@@ -0,0 +1,3 @@
+export * from './rpc';
+export * from './define-rpc';
+export * from './rpc-registry';

package/dist/protocol/rpc/rpc-registry.d.ts

@@ -0,0 +1,105 @@
+import type { DefinedRpc } from './rpc';
+/**
+ * Registry for managing RPC definitions with binary encoding/decoding
+ *
+ * Maps RPC method names to numeric IDs for efficient binary protocol:
+ * - Method names are assigned sequential IDs (0, 1, 2, ...)
+ * - Binary format: [methodId: u16][data: variable]
+ * - Supports bidirectional RPCs (client ↔ server)
+ *
+ * @example
+ * ```ts
+ * const registry = new RpcRegistry();
+ *
+ * // Register RPCs
+ * registry.register(MatchCountdown);
+ * registry.register(BuyItem);
+ *
+ * // Encode RPC to binary
+ * const binary = registry.encode(MatchCountdown, { secondsRemaining: 10 });
+ *
+ * // Decode RPC from binary
+ * const { method, data } = registry.decode(binary);
+ * console.log(method); // 'matchCountdown'
+ * console.log(data.secondsRemaining); // 10
+ * ```
+ */
+export declare class RpcRegistry {
+    private codecs;
+    private methodToId;
+    private idToMethod;
+    private nextId;
+    /**
+     * Register an RPC definition
+     *
+     * @param rpc The RPC definition created by defineRpc()
+     * @throws Error if method is already registered
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * registry.register(MatchCountdown);
+     * ```
+     */
+    register<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>): void;
+    /**
+     * Encode an RPC to binary format
+     *
+     * Binary format: [methodId: u16][data: variable]
+     *
+     * @param rpc The RPC definition
+     * @param data The RPC data to encode
+     * @returns Encoded binary data
+     * @throws Error if RPC is not registered
+     *
+     * @example
+     * ```ts
+     * const binary = registry.encode(MatchCountdown, {
+     *   secondsRemaining: 10
+     * });
+     * ```
+     */
+    encode<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, data: TSchema): Uint8Array;
+    /**
+     * Decode an RPC from binary format
+     *
+     * @param buffer Binary data to decode
+     * @returns Object with method name and decoded data
+     * @throws Error if method ID is unknown
+     *
+     * @example
+     * ```ts
+     * const { method, data } = registry.decode(binary);
+     * console.log(method); // 'matchCountdown'
+     * console.log(data.secondsRemaining); // 10
+     * ```
+     */
+    decode(buffer: Uint8Array): {
+        method: string;
+        data: any;
+    };
+    /**
+     * Check if an RPC method is registered
+     *
+     * @param method Method name to check
+     * @returns True if registered, false otherwise
+     */
+    has(method: string): boolean;
+    /**
+     * Get all registered RPC method names
+     *
+     * @returns Array of method names
+     */
+    getMethods(): string[];
+    /**
+     * Get the numeric ID for a method
+     *
+     * @param method Method name
+     * @returns Method ID or undefined if not registered
+     */
+    getMethodId(method: string): number | undefined;
+}

package/dist/protocol/rpc/rpc-registry.js

@@ -0,0 +1,142 @@
+/**
+ * Registry for managing RPC definitions with binary encoding/decoding
+ *
+ * Maps RPC method names to numeric IDs for efficient binary protocol:
+ * - Method names are assigned sequential IDs (0, 1, 2, ...)
+ * - Binary format: [methodId: u16][data: variable]
+ * - Supports bidirectional RPCs (client ↔ server)
+ *
+ * @example
+ * ```ts
+ * const registry = new RpcRegistry();
+ *
+ * // Register RPCs
+ * registry.register(MatchCountdown);
+ * registry.register(BuyItem);
+ *
+ * // Encode RPC to binary
+ * const binary = registry.encode(MatchCountdown, { secondsRemaining: 10 });
+ *
+ * // Decode RPC from binary
+ * const { method, data } = registry.decode(binary);
+ * console.log(method); // 'matchCountdown'
+ * console.log(data.secondsRemaining); // 10
+ * ```
+ */
+export class RpcRegistry {
+    constructor() {
+        this.codecs = new Map();
+        this.methodToId = new Map();
+        this.idToMethod = new Map();
+        this.nextId = 0;
+    }
+    /**
+     * Register an RPC definition
+     *
+     * @param rpc The RPC definition created by defineRpc()
+     * @throws Error if method is already registered
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * registry.register(MatchCountdown);
+     * ```
+     */
+    register(rpc) {
+        if (this.codecs.has(rpc.method)) {
+            throw new Error(`RPC "${rpc.method}" is already registered`);
+        }
+        const id = this.nextId++;
+        this.codecs.set(rpc.method, rpc.codec);
+        this.methodToId.set(rpc.method, id);
+        this.idToMethod.set(id, rpc.method);
+    }
+    /**
+     * Encode an RPC to binary format
+     *
+     * Binary format: [methodId: u16][data: variable]
+     *
+     * @param rpc The RPC definition
+     * @param data The RPC data to encode
+     * @returns Encoded binary data
+     * @throws Error if RPC is not registered
+     *
+     * @example
+     * ```ts
+     * const binary = registry.encode(MatchCountdown, {
+     *   secondsRemaining: 10
+     * });
+     * ```
+     */
+    encode(rpc, data) {
+        const codec = this.codecs.get(rpc.method);
+        if (!codec) {
+            throw new Error(`RPC "${rpc.method}" is not registered`);
+        }
+        const methodId = this.methodToId.get(rpc.method);
+        const encodedData = codec.encode(data);
+        // Message format: [methodId: u16][data]
+        const buffer = new Uint8Array(2 + encodedData.byteLength);
+        new DataView(buffer.buffer).setUint16(0, methodId, true);
+        buffer.set(new Uint8Array(encodedData), 2);
+        return buffer;
+    }
+    /**
+     * Decode an RPC from binary format
+     *
+     * @param buffer Binary data to decode
+     * @returns Object with method name and decoded data
+     * @throws Error if method ID is unknown
+     *
+     * @example
+     * ```ts
+     * const { method, data } = registry.decode(binary);
+     * console.log(method); // 'matchCountdown'
+     * console.log(data.secondsRemaining); // 10
+     * ```
+     */
+    decode(buffer) {
+        if (buffer.byteLength < 2) {
+            throw new Error('Buffer too small for RPC message');
+        }
+        const view = new DataView(buffer.buffer, buffer.byteOffset);
+        const methodId = view.getUint16(0, true);
+        const method = this.idToMethod.get(methodId);
+        if (!method) {
+            throw new Error(`Unknown RPC method ID: ${methodId}`);
+        }
+        const codec = this.codecs.get(method);
+        const data = codec.decode(buffer.slice(2));
+        return { method, data };
+    }
+    /**
+     * Check if an RPC method is registered
+     *
+     * @param method Method name to check
+     * @returns True if registered, false otherwise
+     */
+    has(method) {
+        return this.codecs.has(method);
+    }
+    /**
+     * Get all registered RPC method names
+     *
+     * @returns Array of method names
+     */
+    getMethods() {
+        return Array.from(this.codecs.keys());
+    }
+    /**
+     * Get the numeric ID for a method
+     *
+     * @param method Method name
+     * @returns Method ID or undefined if not registered
+     */
+    getMethodId(method) {
+        return this.methodToId.get(method);
+    }
+}

package/dist/protocol/rpc/rpc.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RPC (Remote Procedure Call) type definitions
+ *
+ * RPCs are bidirectional one-off events/commands for:
+ * - Meta-game events (achievements, notifications)
+ * - Match lifecycle (countdown, results)
+ * - Request/response patterns
+ * - System announcements
+ *
+ * NOT for game state synchronization (use Snapshots) or player inputs (use Intents)
+ */
+/**
+ * Codec interface for encoding/decoding RPCs
+ */
+export interface RpcCodec<T> {
+    encode(value: T): Uint8Array;
+    decode(buf: Uint8Array): T;
+}
+/**
+ * Runtime RPC message structure
+ */
+export interface Rpc<T = unknown> {
+    method: string;
+    data: T;
+}
+/**
+ * Compile-time RPC definition with type safety
+ * Created by defineRpc() helper
+ */
+export interface DefinedRpc<TSchema extends Record<string, any>> {
+    method: string;
+    codec: RpcCodec<TSchema>;
+    _type?: TSchema;
+}

package/dist/protocol/rpc/rpc.js

@@ -0,0 +1,12 @@
+/**
+ * RPC (Remote Procedure Call) type definitions
+ *
+ * RPCs are bidirectional one-off events/commands for:
+ * - Meta-game events (achievements, notifications)
+ * - Match lifecycle (countdown, results)
+ * - Request/response patterns
+ * - System announcements
+ *
+ * NOT for game state synchronization (use Snapshots) or player inputs (use Intents)
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murow",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A lightweight TypeScript game engine for server-authoritative multiplayer games",
   "main": "dist/core.js",
   "module": "dist/core.esm.js",

package/src/net/README.md

@@ -18,8 +18,9 @@ Transport-agnostic networking layer for multiplayer games. Provides generic clie
   - Custom transports
 
 - **Type-Safe Protocol** - Integrates with `@mococa/protocol`:
-  - Intent encoding/decoding
-  - Snapshot encoding/decoding
+  - Intent encoding/decoding (client inputs)
+  - Snapshot encoding/decoding (state sync)
+  - RPC encoding/decoding (one-off events)
   - Binary serialization
 
 - **Connection Lifecycle** - Built-in handling for:
@@ -34,15 +35,21 @@ Transport-agnostic networking layer for multiplayer games. Provides generic clie
 │ Game Client │                    │ Game Server │
 └──────┬──────┘                    └──────┬──────┘
        │                                  │
-       │  Intents (MoveIntent, etc)       │
+       │  Intents (MoveIntent)            │
        ├─────────────────────────────────>│
        │                                  │
        │  Snapshots (GameState)           │
        │<─────────────────────────────────┤
        │                                  │
+       │  RPCs (BuyItem)                  │
+       ├─────────────────────────────────>│
+       │                                  │
+       │  RPCs (MatchCountdown)           │
+       │<─────────────────────────────────┤
+       │                                  │
        ▼                                  ▼
 ┌─────────────┐                    ┌─────────────┐
-│ ClientNetwork  │                    │ ServerNetwork  │
+│ ClientNetwork│                   │ServerNetwork│
 │   Class     │                    │   Class     │
 └──────┬──────┘                    └──────┬──────┘
        │                                  │
@@ -167,6 +174,74 @@ client.sendIntent({
 });
 ```
 
+## RPCs (Remote Procedure Calls)
+
+For one-off events that don't fit intents (inputs) or snapshots (state sync), use RPCs. See [Protocol README](../protocol/README.md#rpcs-remote-procedure-calls) for full documentation.
+
+### Quick Example
+
+```typescript
+import { defineRpc, RpcRegistry } from '@mococa/gamedev-utils';
+
+// Define RPCs
+const MatchCountdown = defineRpc({
+  method: 'matchCountdown',
+  schema: {
+    secondsRemaining: BinaryCodec.u8,
+  }
+});
+
+const BuyItem = defineRpc({
+  method: 'buyItem',
+  schema: {
+    itemId: BinaryCodec.string(32),
+  }
+});
+
+// Register RPCs
+const rpcRegistry = new RpcRegistry();
+rpcRegistry.register(MatchCountdown);
+rpcRegistry.register(BuyItem);
+
+// Add to client/server config
+const client = new ClientNetwork({
+  transport,
+  intentRegistry,
+  snapshotRegistry,
+  rpcRegistry, // ← Optional
+});
+
+// Client: Send RPC to server
+client.sendRpc(BuyItem, { itemId: 'long_sword' });
+
+// Client: Receive RPC from server
+client.onRpc(MatchCountdown, (rpc) => {
+  showCountdownUI(rpc.secondsRemaining);
+});
+
+// Server: Receive RPC from client
+server.onRpc(BuyItem, (peerId, rpc) => {
+  handlePurchase(peerId, rpc.itemId);
+});
+
+// Server: Send RPC to specific client
+server.sendRpc(peerId, MatchCountdown, { secondsRemaining: 10 });
+
+// Server: Broadcast RPC to all clients
+server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 3 });
+```
+
+**When to use:**
+- ✅ Match lifecycle events (countdown, pause, end)
+- ✅ Meta-game events (achievements, notifications)
+- ✅ Chat messages
+- ✅ UI feedback (purchase confirmations, errors)
+
+**When NOT to use:**
+- ❌ Game state (use Snapshots)
+- ❌ Player inputs (use Intents)
+- ❌ Anything late joiners need to know
+
 ## Per-Peer Snapshot Registries
 
 The killer feature! Each peer automatically gets their own snapshot registry via the factory function, enabling powerful optimizations:

package/src/net/client.ts

@@ -2,6 +2,8 @@ import type { IntentRegistry } from "../protocol/intent/intent-registry";
 import type { SnapshotRegistry } from "../protocol/snapshot/snapshot-registry";
 import type { Snapshot } from "../protocol/snapshot/snapshot";
 import type { Intent } from "../protocol/intent/intent";
+import type { RpcRegistry } from "../protocol/rpc/rpc-registry";
+import type { DefinedRpc } from "../protocol/rpc/rpc";
 import { MessageType, type TransportAdapter, type NetworkConfig } from "./types";
 
 /**
@@ -17,6 +19,9 @@ export interface ClientNetworkConfig<TSnapshots> {
 	/** Snapshot registry for decoding server snapshots */
 	snapshotRegistry: SnapshotRegistry<TSnapshots>;
 
+	/** RPC registry for bidirectional remote procedure calls (optional) */
+	rpcRegistry?: RpcRegistry;
+
 	/** Network configuration */
 	config?: NetworkConfig;
 }
@@ -47,11 +52,15 @@ export class ClientNetwork<TSnapshots = unknown> {
 	private transport: TransportAdapter;
 	private intentRegistry: IntentRegistry;
 	private snapshotRegistry: SnapshotRegistry<TSnapshots>;
+	private rpcRegistry?: RpcRegistry;
 	private config: Required<NetworkConfig>;
 
 	/** Snapshot type handlers: type -> handler[] (supports multiple handlers) */
 	private snapshotHandlers = new Map<string, Array<(snapshot: Snapshot<any>) => void>>();
 
+	/** RPC method handlers: method -> handler[] (supports multiple handlers) */
+	private rpcHandlers = new Map<string, Array<(data: any) => void>>();
+
 	/** Connection lifecycle handlers */
 	private connectHandlers: Array<() => void> = [];
 	private disconnectHandlers: Array<() => void> = [];
@@ -77,6 +86,7 @@ export class ClientNetwork<TSnapshots = unknown> {
 		this.transport = config.transport;
 		this.intentRegistry = config.intentRegistry;
 		this.snapshotRegistry = config.snapshotRegistry;
+		this.rpcRegistry = config.rpcRegistry;
 		this.config = {
 			maxMessageSize: config.config?.maxMessageSize ?? 65536,
 			debug: config.config?.debug ?? false,
@@ -204,6 +214,105 @@ export class ClientNetwork<TSnapshots = unknown> {
 		};
 	}
 
+	/**
+	 * Send an RPC to the server (type-safe)
+	 *
+	 * @template TSchema The RPC data type
+	 * @param rpc The RPC definition created by defineRpc()
+	 * @param data The RPC data to send
+	 *
+	 * @example
+	 * ```ts
+	 * const BuyItem = defineRpc({
+	 *   method: 'buyItem',
+	 *   schema: { itemId: BinaryCodec.string(32) }
+	 * });
+	 *
+	 * client.sendRpc(BuyItem, { itemId: 'long_sword' });
+	 * ```
+	 */
+	sendRpc<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, data: TSchema): void {
+		if (!this.rpcRegistry) {
+			throw new Error('RpcRegistry not configured. Pass rpcRegistry to ClientNetworkConfig.');
+		}
+
+		if (!this.connected) {
+			this.log("Cannot send RPC: not connected");
+			return;
+		}
+
+		// Client-side rate limiting
+		if (!this.checkRateLimit()) {
+			this.log("Rate limit exceeded, dropping RPC");
+			return;
+		}
+
+		try {
+			// Encode RPC
+			const rpcData = this.rpcRegistry.encode(rpc, data);
+
+			// Wrap with message type header
+			const message = new Uint8Array(1 + rpcData.byteLength);
+			message[0] = MessageType.CUSTOM;
+			message.set(rpcData, 1);
+
+			// Send to server
+			this.transport.send(message);
+
+			this.log(`Sent RPC (method: ${rpc.method})`);
+		} catch (error) {
+			this.log(`Failed to send RPC: ${error}`);
+		}
+	}
+
+	/**
+	 * Register a handler for incoming RPCs from the server (type-safe)
+	 * Supports multiple handlers per RPC method
+	 *
+	 * @template TSchema The RPC data type
+	 * @param rpc The RPC definition created by defineRpc()
+	 * @param handler Callback function to handle the RPC
+	 * @returns Unsubscribe function to remove this handler
+	 *
+	 * @example
+	 * ```ts
+	 * const MatchCountdown = defineRpc({
+	 *   method: 'matchCountdown',
+	 *   schema: { secondsRemaining: BinaryCodec.u8 }
+	 * });
+	 *
+	 * client.onRpc(MatchCountdown, (rpc) => {
+	 *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
+	 * });
+	 * ```
+	 */
+	onRpc<TSchema extends Record<string, any>>(
+		rpc: DefinedRpc<TSchema>,
+		handler: (data: TSchema) => void
+	): () => void {
+		if (!this.rpcRegistry) {
+			throw new Error('RpcRegistry not configured. Pass rpcRegistry to ClientNetworkConfig.');
+		}
+
+		let handlers = this.rpcHandlers.get(rpc.method);
+		if (!handlers) {
+			handlers = [];
+			this.rpcHandlers.set(rpc.method, handlers);
+		}
+		handlers.push(handler as (data: any) => void);
+
+		// Return unsubscribe function
+		return () => {
+			const handlers = this.rpcHandlers.get(rpc.method);
+			if (handlers) {
+				const index = handlers.indexOf(handler as (data: any) => void);
+				if (index > -1) {
+					handlers.splice(index, 1);
+				}
+			}
+		};
+	}
+
 	/**
 	 * Register a handler for connection events
 	 */
@@ -349,8 +458,7 @@ export class ClientNetwork<TSnapshots = unknown> {
 				this.log("Received heartbeat from server");
 				break;
 			case MessageType.CUSTOM:
-				// Could add custom message handlers here
-				this.log("Received custom message from server");
+				this.handleRpc(payload);
 				break;
 			default:
 				this.log(`Unknown message type: ${messageType}`);
@@ -385,6 +493,39 @@ export class ClientNetwork<TSnapshots = unknown> {
 		}
 	}
 
+	/**
+	 * Handle incoming RPC message from server
+	 */
+	private handleRpc(data: Uint8Array): void {
+		if (!this.rpcRegistry) {
+			this.log("Received RPC but RpcRegistry not configured");
+			return;
+		}
+
+		try {
+			// Decode using RPC registry (returns { method, data })
+			const decoded = this.rpcRegistry.decode(data);
+
+			this.log(`Received RPC (method: ${decoded.method})`);
+
+			// Call all method-specific handlers if registered
+			const handlers = this.rpcHandlers.get(decoded.method);
+			if (handlers && handlers.length > 0) {
+				for (const handler of handlers) {
+					try {
+						handler(decoded.data);
+					} catch (error) {
+						this.log(`Error in RPC handler: ${error}`);
+					}
+				}
+			} else {
+				this.log(`No handler registered for RPC method: ${decoded.method}`);
+			}
+		} catch (error) {
+			this.log(`Failed to decode RPC: ${error}`);
+		}
+	}
+
 	/**
 	 * Handle disconnection from server
 	 */