@colyseus/sdk 0.17.41 → 0.18.0

package/build/Room.d.ts

@@ -1,6 +1,8 @@
-import { type InferState, type NormalizeRoomType, type ExtractRoomMessages, type ExtractRoomClientMessages, type ExtractMessageType } from '@colyseus/shared-types';
+import { type InferState, type InferInput, type NormalizeRoomType, type ExtractRoomMessages, type ExtractRoomClientMessages, type ExtractMessageType, type ExtractResponseType } from '@colyseus/shared-types';
 import { Schema } from '@colyseus/schema';
-import { Packr } from '@colyseus/msgpackr';
+import { type ClientInputHandle, type ClientInputOptions } from './input/InputHandle.ts';
+export { type ClientInputHandle, type ClientInputOptions } from './input/InputHandle.ts';
+import { Packr } from 'msgpackr';
 import { Connection } from './Connection.ts';
 import { Serializer } from './serializer/Serializer.ts';
 import { SchemaConstructor, SchemaSerializer } from './serializer/SchemaSerializer.ts';
@@ -121,6 +123,13 @@ export declare class Room<T = any, State = InferState<T, never>> {
     protected joinedAtTime: number;
     protected onMessageHandlers: import("./core/nanoevents.ts").Emitter<import("./core/nanoevents.ts").EventsMap>;
     protected packr: Packr;
+    protected sharedBuffer: Uint8Array;
+    /**
+     * Default time (ms) a `room.request()` / `room.send(..., callback)` waits
+     * for a reply before rejecting. Override per-call with the `timeout`
+     * option. Tune globally by assigning to this field after joining.
+     */
+    requestTimeout: number;
     constructor(name: string, rootSchema?: SchemaConstructor<State>);
     connect(endpoint: string, options?: any, headers?: any): void;
     leave(consented?: boolean): Promise<number>;
@@ -129,9 +138,60 @@ export declare class Room<T = any, State = InferState<T, never>> {
     onMessage<Payload = any>(type: [keyof ExtractRoomClientMessages<NormalizeRoomType<T>>] extends [never] ? (string | number) : never, callback: (payload: Payload) => void): () => void;
     ping(callback: (ms: number) => void): void;
     send<MessageType extends keyof ExtractRoomMessages<NormalizeRoomType<T>>>(messageType: MessageType, payload?: ExtractMessageType<ExtractRoomMessages<NormalizeRoomType<T>>[MessageType]>): void;
+    send<MessageType extends keyof ExtractRoomMessages<NormalizeRoomType<T>>>(messageType: MessageType, payload: ExtractMessageType<ExtractRoomMessages<NormalizeRoomType<T>>[MessageType]>, callback: (response: ExtractResponseType<ExtractRoomMessages<NormalizeRoomType<T>>[MessageType]>, error?: Error) => void): void;
     send<Payload = any>(messageType: [keyof ExtractRoomMessages<NormalizeRoomType<T>>] extends [never] ? (string | number) : never, payload?: Payload): void;
+    send<Payload = any, Response = any>(messageType: [keyof ExtractRoomMessages<NormalizeRoomType<T>>] extends [never] ? (string | number) : never, payload: Payload, callback: (response: Response, error?: Error) => void): void;
+    /**
+     * Send a message and await the server's reply. The server answers by
+     * returning a value from its matching `onMessage(type, ...)` handler.
+     *
+     * Rejects if the handler throws, if no handler is registered, if the
+     * connection closes first, or if no reply arrives within `timeout`
+     * (defaults to {@link Room.requestTimeout}).
+     *
+     * @example
+     * ```typescript
+     * const profile = await room.request("get-profile", { id: 42 });
+     * ```
+     */
+    request<MessageType extends keyof ExtractRoomMessages<NormalizeRoomType<T>>>(messageType: MessageType, payload?: ExtractMessageType<ExtractRoomMessages<NormalizeRoomType<T>>[MessageType]>, options?: {
+        timeout?: number;
+    }): Promise<ExtractResponseType<ExtractRoomMessages<NormalizeRoomType<T>>[MessageType]>>;
+    request<Payload = any, Response = any>(messageType: [keyof ExtractRoomMessages<NormalizeRoomType<T>>] extends [never] ? (string | number) : never, payload?: Payload, options?: {
+        timeout?: number;
+    }): Promise<Response>;
     sendUnreliable<T = any>(type: string | number, message?: T): void;
     sendBytes(type: string | number, bytes: Uint8Array): void;
+    /**
+     * Get the per-room input handle. Lazily created on first call and cached;
+     * subsequent calls return the same handle (options on later calls are
+     * ignored).
+     *
+     * Schema discovery, in order:
+     * 1. `options.type` — explicit constructor (overrides everything).
+     * 2. Server-sent reflection from the JOIN handshake — populated when the
+     *    server room called `defineInput()`. The synthesized class has the
+     *    same fields as the server's input schema; `instanceof YourInput`
+     *    won't pass on it.
+     *
+     * Throws if neither source has produced a constructor.
+     *
+     * For rollback netcode, prefer `{ mode: "unreliable", delta: true,
+     * historySize: 4 }`: tiny per-tick payloads, redundancy across drops,
+     * idempotent under reordering.
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.joinOrCreate<typeof FpsRoom>("fps");
+     * const input = conn.input({ mode: "unreliable" });   // type from server
+     * // each simulation tick:
+     * input.data.seq++;
+     * input.data.vx = vx;
+     * input.data.vy = vy;
+     * input.send();
+     * ```
+     */
+    input<I = ([InferInput<T>] extends [never] ? any : InferInput<T>)>(options?: ClientInputOptions<I>): ClientInputHandle<I>;
     get state(): State;
     removeAllListeners(): void;
     protected onMessageCallback(event: MessageEvent): void;

package/build/Room.mjs

@@ -3,10 +3,12 @@
 // This software is released under the MIT License.
 // https://opensource.org/license/MIT
 //
-// colyseus.js@0.17.41
-import { CloseCode, Protocol } from '@colyseus/shared-types';
-import { Decoder, encode, decode } from '@colyseus/schema';
-import { Packr, unpack } from '@colyseus/msgpackr';
+// colyseus.js@0.18.0
+import { CloseCode, Protocol, HandshakeSection, ResponseStatus } from '@colyseus/shared-types';
+import { Decoder, encode, decode, Reflection } from '@colyseus/schema';
+import { InputEncoder } from '@colyseus/schema/input';
+import { ClientInputHandleImpl } from './input/InputHandle.mjs';
+import { Packr, RESERVE_START_SPACE, unpack } from 'msgpackr';
 import { Connection } from './Connection.mjs';
 import { getSerializer } from './serializer/Serializer.mjs';
 import { createNanoEvents } from './core/nanoevents.mjs';
@@ -46,13 +48,37 @@ class Room {
     joinedAtTime = 0;
     onMessageHandlers = createNanoEvents();
     packr;
+    sharedBuffer;
     #lastPingTime = 0;
     #pingCallback = undefined;
+    /**
+     * Default time (ms) a `room.request()` / `room.send(..., callback)` waits
+     * for a reply before rejecting. Override per-call with the `timeout`
+     * option. Tune globally by assigning to this field after joining.
+     */
+    requestTimeout = 10000;
+    /** Monotonic id correlating a {@link Protocol.ROOM_REQUEST} with its reply. @internal */
+    #nextRequestId = 0;
+    /** In-flight requests awaiting a {@link Protocol.ROOM_RESPONSE}. @internal */
+    #pendingRequests = new Map();
+    #inputHandle;
+    /**
+     * Schema constructor recovered via Reflection from the server's
+     * handshake (the `INPUT_REFLECTION` tagged section). Populated on JOIN
+     * when the server room called `defineInput()`; falls back to `undefined`
+     * otherwise. Survives reconnects that skip the handshake — the field is
+     * set on the original join and never cleared.
+     *
+     * Typed as `new () => any` (not `Schema`) on purpose — pinning to this
+     * SDK's Schema type would clash with user instances coming from a
+     * different copy of `@colyseus/schema` under multi-version installs.
+     * @internal
+     */
+    #inputCtorFromReflection;
     constructor(name, rootSchema) {
         this.name = name;
         this.packr = new Packr();
-        // msgpackr workaround: force buffer to be created.
-        this.packr.encode(undefined);
+        this.sharedBuffer = new Uint8Array(8192);
         if (rootSchema) {
             const serializer = new (getSerializer("schema"));
             this.serializer = serializer;
@@ -69,6 +95,8 @@ class Room {
         this.connection = new Connection(options.protocol);
         this.connection.events.onmessage = this.onMessageCallback.bind(this);
         this.connection.events.onclose = (e) => {
+            // the in-flight requests can't be answered on a closed socket
+            this.#rejectAllPending("connection closed before a response was received.");
             if (this.joinedAtTime === 0) {
                 console.warn?.(`Room connection was closed unexpectedly (${e.code}): ${e.reason}`);
                 this.onError.invoke(e.code, e.reason);
@@ -107,8 +135,8 @@ class Room {
             this.onLeave((code) => resolve(code));
             if (this.connection) {
                 if (consented) {
-                    this.packr.buffer[0] = Protocol.LEAVE_ROOM;
-                    this.connection.send(this.packr.buffer.subarray(0, 1));
+                    this.sharedBuffer[0] = Protocol.LEAVE_ROOM;
+                    this.connection.send(this.sharedBuffer.subarray(0, 1));
                 }
                 else {
                     this.connection.close();
@@ -129,23 +157,35 @@ class Room {
         }
         this.#lastPingTime = now();
         this.#pingCallback = callback;
-        this.packr.buffer[0] = Protocol.PING;
-        this.connection.send(this.packr.buffer.subarray(0, 1));
+        this.sharedBuffer[0] = Protocol.PING;
+        this.connection.send(this.sharedBuffer.subarray(0, 1));
     }
-    send(messageType, payload) {
+    send(messageType, payload, callback) {
+        // Request/response form: defer to `request()` and adapt to a
+        // (response, error) callback.
+        if (callback !== undefined) {
+            this.#request(messageType, payload, this.requestTimeout).then((response) => callback(response, undefined), (error) => callback(undefined, error));
+            return;
+        }
         const it = { offset: 1 };
-        this.packr.buffer[0] = Protocol.ROOM_DATA;
+        this.sharedBuffer[0] = Protocol.ROOM_DATA;
         if (typeof (messageType) === "string") {
-            encode.string(this.packr.buffer, messageType, it);
+            encode.string(this.sharedBuffer, messageType, it);
+        }
+        else {
+            encode.number(this.sharedBuffer, messageType, it);
+        }
+        const headerLength = it.offset;
+        let data;
+        if (payload !== undefined) {
+            // Reserve `headerLength` writable bytes at the front of msgpackr's
+            // output and prepend the protocol header into them.
+            data = this.packr.pack(payload, RESERVE_START_SPACE | headerLength);
+            data.set(this.sharedBuffer.subarray(0, headerLength), 0);
         }
         else {
-            encode.number(this.packr.buffer, messageType, it);
+            data = this.sharedBuffer.subarray(0, headerLength);
         }
-        // force packr to use beginning of the buffer
-        this.packr.position = 0;
-        const data = (payload !== undefined)
-            ? this.packr.pack(payload, 2048 + it.offset) // 2048 = RESERVE_START_SPACE
-            : this.packr.buffer.subarray(0, it.offset);
         // If connection is not open, buffer the message
         if (!this.connection.isOpen) {
             enqueueMessage(this, new Uint8Array(data));
@@ -154,51 +194,146 @@ class Room {
             this.connection.send(data);
         }
     }
+    request(messageType, payload, options) {
+        return this.#request(messageType, payload, options?.timeout ?? this.requestTimeout);
+    }
+    #request(messageType, payload, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            if (!this.connection.isOpen) {
+                reject(new Error(`cannot send request "${messageType}": connection is not open.`));
+                return;
+            }
+            const requestId = this.#nextRequestId;
+            this.#nextRequestId = (this.#nextRequestId + 1) >>> 0; // keep within uint32
+            const it = { offset: 1 };
+            this.sharedBuffer[0] = Protocol.ROOM_REQUEST;
+            encode.number(this.sharedBuffer, requestId, it);
+            if (typeof (messageType) === "string") {
+                encode.string(this.sharedBuffer, messageType, it);
+            }
+            else {
+                encode.number(this.sharedBuffer, messageType, it);
+            }
+            const headerLength = it.offset;
+            let data;
+            if (payload !== undefined) {
+                data = this.packr.pack(payload, RESERVE_START_SPACE | headerLength);
+                data.set(this.sharedBuffer.subarray(0, headerLength), 0);
+            }
+            else {
+                data = this.sharedBuffer.subarray(0, headerLength);
+            }
+            const timer = setTimeout(() => {
+                this.#pendingRequests.delete(requestId);
+                reject(new Error(`request "${messageType}" timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+            this.#pendingRequests.set(requestId, { resolve, reject, timer });
+            this.connection.send(data);
+        });
+    }
+    #rejectAllPending(reason) {
+        if (this.#pendingRequests.size === 0) {
+            return;
+        }
+        const error = new Error(reason);
+        for (const pending of this.#pendingRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#pendingRequests.clear();
+    }
     sendUnreliable(type, message) {
         // If connection is not open, skip
         if (!this.connection.isOpen) {
             return;
         }
         const it = { offset: 1 };
-        this.packr.buffer[0] = Protocol.ROOM_DATA;
+        this.sharedBuffer[0] = Protocol.ROOM_DATA;
         if (typeof (type) === "string") {
-            encode.string(this.packr.buffer, type, it);
+            encode.string(this.sharedBuffer, type, it);
+        }
+        else {
+            encode.number(this.sharedBuffer, type, it);
+        }
+        const headerLength = it.offset;
+        let data;
+        if (message !== undefined) {
+            data = this.packr.pack(message, RESERVE_START_SPACE | headerLength);
+            data.set(this.sharedBuffer.subarray(0, headerLength), 0);
         }
         else {
-            encode.number(this.packr.buffer, type, it);
+            data = this.sharedBuffer.subarray(0, headerLength);
         }
-        // force packr to use beginning of the buffer
-        this.packr.position = 0;
-        const data = (message !== undefined)
-            ? this.packr.pack(message, 2048 + it.offset) // 2048 = RESERVE_START_SPACE
-            : this.packr.buffer.subarray(0, it.offset);
         this.connection.sendUnreliable(data);
     }
     sendBytes(type, bytes) {
         const it = { offset: 1 };
-        this.packr.buffer[0] = Protocol.ROOM_DATA_BYTES;
+        this.sharedBuffer[0] = Protocol.ROOM_DATA_BYTES;
         if (typeof (type) === "string") {
-            encode.string(this.packr.buffer, type, it);
+            encode.string(this.sharedBuffer, type, it);
         }
         else {
-            encode.number(this.packr.buffer, type, it);
+            encode.number(this.sharedBuffer, type, it);
         }
-        // check if buffer needs to be resized
-        // TODO: can we avoid this?
-        if (bytes.byteLength + it.offset > this.packr.buffer.byteLength) {
-            const newBuffer = new Uint8Array(it.offset + bytes.byteLength);
-            newBuffer.set(this.packr.buffer);
-            this.packr.useBuffer(newBuffer);
+        const headerLength = it.offset;
+        // grow the scratch buffer if needed, preserving the header bytes
+        if (headerLength + bytes.byteLength > this.sharedBuffer.byteLength) {
+            const newBuffer = new Uint8Array(headerLength + bytes.byteLength);
+            newBuffer.set(this.sharedBuffer.subarray(0, headerLength));
+            this.sharedBuffer = newBuffer;
         }
-        this.packr.buffer.set(bytes, it.offset);
+        this.sharedBuffer.set(bytes, headerLength);
         // If connection is not open, buffer the message
         if (!this.connection.isOpen) {
-            enqueueMessage(this, this.packr.buffer.subarray(0, it.offset + bytes.byteLength));
+            enqueueMessage(this, this.sharedBuffer.subarray(0, headerLength + bytes.byteLength));
         }
         else {
-            this.connection.send(this.packr.buffer.subarray(0, it.offset + bytes.byteLength));
+            this.connection.send(this.sharedBuffer.subarray(0, headerLength + bytes.byteLength));
         }
     }
+    /**
+     * Get the per-room input handle. Lazily created on first call and cached;
+     * subsequent calls return the same handle (options on later calls are
+     * ignored).
+     *
+     * Schema discovery, in order:
+     * 1. `options.type` — explicit constructor (overrides everything).
+     * 2. Server-sent reflection from the JOIN handshake — populated when the
+     *    server room called `defineInput()`. The synthesized class has the
+     *    same fields as the server's input schema; `instanceof YourInput`
+     *    won't pass on it.
+     *
+     * Throws if neither source has produced a constructor.
+     *
+     * For rollback netcode, prefer `{ mode: "unreliable", delta: true,
+     * historySize: 4 }`: tiny per-tick payloads, redundancy across drops,
+     * idempotent under reordering.
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.joinOrCreate<typeof FpsRoom>("fps");
+     * const input = conn.input({ mode: "unreliable" });   // type from server
+     * // each simulation tick:
+     * input.data.seq++;
+     * input.data.vx = vx;
+     * input.data.vy = vy;
+     * input.send();
+     * ```
+     */
+    input(options) {
+        if (this.#inputHandle) {
+            return this.#inputHandle;
+        }
+        const Ctor = (options?.type ?? this.#inputCtorFromReflection);
+        if (!Ctor) {
+            throw new Error("conn.input(): no input schema available. The server room must call " +
+                "`defineInput(YourInput)`, or you can pass `{ type: YourInput }` explicitly.");
+        }
+        const instance = new Ctor();
+        const encoder = new InputEncoder(instance, options);
+        this.#inputHandle = new ClientInputHandleImpl(this, instance, encoder);
+        return this.#inputHandle;
+    }
     get state() {
         return this.serializer.getState();
     }
@@ -227,9 +362,31 @@ class Room {
                 const serializer = getSerializer(this.serializerId);
                 this.serializer = new serializer();
             }
-            // apply handshake on first join (no need to do this on reconnect)
-            if (buffer.byteLength > it.offset && this.serializer.handshake) {
-                this.serializer.handshake(buffer, it);
+            // State reflection is length-prefixed (varint). The schema decoder
+            // runs `while (offset < bytes.byteLength)` so without a boundary
+            // it would read past the state reflection into the trailing
+            // tagged-section bytes — see Protocol.ts for the wire layout.
+            const stateReflectionLen = decode.number(buffer, it);
+            if (stateReflectionLen > 0 && this.serializer.handshake) {
+                const stateReflectionEnd = it.offset + stateReflectionLen;
+                this.serializer.handshake(buffer.subarray(0, stateReflectionEnd), it);
+                it.offset = stateReflectionEnd;
+            }
+            // Parse trailing tagged sections (forward-compatible: unknown tags
+            // are skipped via length). See HandshakeSection in shared-types.
+            while (it.offset < buffer.byteLength) {
+                const tag = buffer[it.offset++];
+                const sectionLen = decode.number(buffer, it);
+                const sectionEnd = it.offset + sectionLen;
+                if (tag === HandshakeSection.INPUT_REFLECTION) {
+                    const inputDecoder = Reflection.decode(buffer.subarray(0, sectionEnd), it);
+                    // Install schema-builder field descriptors on the
+                    // reconstructed class so `InputEncoder` can read its
+                    // `$values` and emit non-empty packets.
+                    Reflection.makeEncodable(inputDecoder.state.constructor);
+                    this.#inputCtorFromReflection = inputDecoder.state.constructor;
+                }
+                it.offset = sectionEnd;
             }
             if (this.joinedAtTime === 0) {
                 this.joinedAtTime = Date.now();
@@ -242,8 +399,8 @@ class Room {
             }
             this.reconnectionToken = `${this.roomId}:${reconnectionToken}`;
             // acknowledge successfull JOIN_ROOM
-            this.packr.buffer[0] = Protocol.JOIN_ROOM;
-            this.connection.send(this.packr.buffer.subarray(0, 1));
+            this.sharedBuffer[0] = Protocol.JOIN_ROOM;
+            this.connection.send(this.sharedBuffer.subarray(0, 1));
             // Send any enqueued messages that were buffered while disconnected
             if (this.reconnection.enqueuedMessages.length > 0) {
                 for (const message of this.reconnection.enqueuedMessages) {
@@ -284,6 +441,34 @@ class Room {
                 : decode.number(buffer, it);
             this.dispatchMessage(type, buffer.subarray(it.offset));
         }
+        else if (code === Protocol.ROOM_RESPONSE) {
+            // reply to a pending `request()` / `send(..., callback)`
+            const requestId = decode.number(buffer, it);
+            const status = buffer[it.offset++];
+            const pending = this.#pendingRequests.get(requestId);
+            // already settled (e.g. timed out) or unknown id — ignore
+            if (pending !== undefined) {
+                this.#pendingRequests.delete(requestId);
+                clearTimeout(pending.timer);
+                const payload = (buffer.byteLength > it.offset)
+                    ? unpack(buffer, { start: it.offset })
+                    : undefined;
+                if (status === ResponseStatus.OK) {
+                    pending.resolve(payload);
+                }
+                else {
+                    // payload carries { name, message, code } from the server
+                    const error = new Error(payload?.message ?? "request failed");
+                    if (payload?.name) {
+                        error.name = payload.name;
+                    }
+                    if (payload?.code !== undefined) {
+                        error.code = payload.code;
+                    }
+                    pending.reject(error);
+                }
+            }
+        }
         else if (code === Protocol.PING) {
             this.#pingCallback?.(Math.round(now() - this.#lastPingTime));
             this.#pingCallback = undefined;