@colyseus/core 0.18.4 → 0.18.5

package/build/Room.d.ts

@@ -185,6 +185,41 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * @default 50ms (20fps)
      */
     patchRate: number | null;
+    /**
+     * Frequency to flush `@unreliable` state fields, in milliseconds.
+     *
+     * Those fields never ride a state patch — they go out over the transport's
+     * unreliable channel (a WebTransport datagram), so a dropped frame costs one
+     * stale value instead of stalling the reliable stream behind a retransmit.
+     * Setting this decouples them from {@link patchRate}, which is the point:
+     * 60Hz movement over a 20Hz structural patch.
+     *
+     * KNOWN COST of a rate faster than {@link patchRate}: an entity's ADD travels
+     * the reliable channel, so datagrams sent between patches can reference a
+     * refId the client hasn't been told about yet. Those frames are skipped by the
+     * client's decoder — safe (the ref graph can't desync, since `@unreliable` is
+     * primitives-only) but each one logs `"refId" not found`, and that entity's
+     * first value lands one mutation later. Measured at `patchRate/this` reports
+     * per mid-session spawn. Leave this unset and the flush rides
+     * {@link broadcastPatch}, which ships the ADD first and avoids it entirely.
+     *
+     * Requires a transport with a datagram channel — today only
+     * `@colyseus/h3-transport` (WebTransport), which is **experimental**. Every
+     * WebSocket transport lacks one, and those clients are skipped entirely (the
+     * room warns once), so `@unreliable` fields keep their join-time value there.
+     *
+     * @default null — flush alongside every {@link broadcastPatch}, and only when
+     * the state actually declares an `@unreliable` field.
+     */
+    unreliablePatchRate: number | null;
+    /**
+     * The unreliable flush, called unconditionally at the end of every
+     * {@link broadcastPatch}. Stays {@link NOOP} unless the state actually
+     * declares an `@unreliable` field, so a room that never uses the channel
+     * pays an empty call the engine inlines away — and there is no second
+     * entry point that could drift from `broadcastPatch()`.
+     */
+    private _flushUnreliable;
     /**
      * Maximum number of messages a client can send to the server per second.
      * If a client sends more messages than this, it will be disconnected.
@@ -661,6 +696,28 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * Checks whether mutations have occurred in the state, and broadcast them to all connected clients.
      */
     broadcastPatch(): boolean;
+    /**
+     * Encode and send the `@unreliable` state fields over each client's
+     * unreliable channel. Those fields never appear in a {@link broadcastPatch}
+     * frame, and clients on a transport without a datagram channel are skipped.
+     *
+     * Driven automatically once the state declares an `@unreliable` field — right
+     * after each {@link broadcastPatch}, or on its own timer when
+     * {@link unreliablePatchRate} is set. Public so a room driving
+     * `broadcastPatch()` by hand can drive this by hand too.
+     */
+    broadcastUnreliablePatch(): boolean;
+    /**
+     * Decide how the unreliable channel is driven — and, for the rooms that never
+     * touch it, decide to not drive it at all. Runs when the state is assigned
+     * (the serializer knows by then whether any `@unreliable` field exists) and
+     * whenever {@link unreliablePatchRate} changes.
+     *
+     * A room whose state declares no `@unreliable` field leaves
+     * {@link _flushUnreliable} at {@link NOOP}, so its patch tick costs exactly
+     * what it did before this feature existed.
+     */
+    private _armUnreliablePatches;
     /**
      * Register a message handler for a specific message type.
      * This method is used to handle messages sent by clients to the room.

package/build/Room.mjs

@@ -36,6 +36,8 @@ import {
 } from "./RoomPlugin.mjs";
 var DEFAULT_PATCH_RATE = 1e3 / 20;
 var DEFAULT_SIMULATION_INTERVAL = 1e3 / 60;
+var NOOP = () => {
+};
 var noneSerializer = new NoneSerializer();
 var AFTER_PATCH_OPTS = Object.freeze({ afterNextPatch: true });
 var DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
@@ -75,6 +77,42 @@ var Room = class _Room {
      * @default 50ms (20fps)
      */
     this.patchRate = DEFAULT_PATCH_RATE;
+    /**
+     * Frequency to flush `@unreliable` state fields, in milliseconds.
+     *
+     * Those fields never ride a state patch — they go out over the transport's
+     * unreliable channel (a WebTransport datagram), so a dropped frame costs one
+     * stale value instead of stalling the reliable stream behind a retransmit.
+     * Setting this decouples them from {@link patchRate}, which is the point:
+     * 60Hz movement over a 20Hz structural patch.
+     *
+     * KNOWN COST of a rate faster than {@link patchRate}: an entity's ADD travels
+     * the reliable channel, so datagrams sent between patches can reference a
+     * refId the client hasn't been told about yet. Those frames are skipped by the
+     * client's decoder — safe (the ref graph can't desync, since `@unreliable` is
+     * primitives-only) but each one logs `"refId" not found`, and that entity's
+     * first value lands one mutation later. Measured at `patchRate/this` reports
+     * per mid-session spawn. Leave this unset and the flush rides
+     * {@link broadcastPatch}, which ships the ADD first and avoids it entirely.
+     *
+     * Requires a transport with a datagram channel — today only
+     * `@colyseus/h3-transport` (WebTransport), which is **experimental**. Every
+     * WebSocket transport lacks one, and those clients are skipped entirely (the
+     * room warns once), so `@unreliable` fields keep their join-time value there.
+     *
+     * @default null — flush alongside every {@link broadcastPatch}, and only when
+     * the state actually declares an `@unreliable` field.
+     */
+    this.unreliablePatchRate = null;
+    this.#_unreliablePatchRate = null;
+    /**
+     * The unreliable flush, called unconditionally at the end of every
+     * {@link broadcastPatch}. Stays {@link NOOP} unless the state actually
+     * declares an `@unreliable` field, so a room that never uses the channel
+     * pays an empty call the engine inlines away — and there is no second
+     * entry point that could drift from `broadcastPatch()`.
+     */
+    this._flushUnreliable = NOOP;
     /**
      * Maximum number of messages a client can send to the server per second.
      * If a client sends more messages than this, it will be disconnected.
@@ -169,6 +207,8 @@ var Room = class _Room {
   #_autoDispose;
   #_patchRate;
   #_patchInterval;
+  #_unreliablePatchRate;
+  #_unreliablePatchInterval;
   #_state;
   #_messages;
   // Re-expose the registry for @colyseus/playground introspection and
@@ -190,6 +230,7 @@ var Room = class _Room {
     this.#_state = this.state;
     this.#_autoDispose = this.autoDispose;
     this.#_patchRate = this.patchRate;
+    this.#_unreliablePatchRate = this.unreliablePatchRate;
     this.#_maxClients = this.maxClients;
     Object.defineProperties(this, {
       state: {
@@ -205,6 +246,7 @@ var Room = class _Room {
           }
           this._serializer.reset(newState);
           this.#_state = newState;
+          this._armUnreliablePatches();
         }
       },
       maxClients: {
@@ -239,6 +281,14 @@ var Room = class _Room {
             this.#_patchInterval = setInterval(() => this.clock.tick(), DEFAULT_SIMULATION_INTERVAL);
           }
         }
+      },
+      unreliablePatchRate: {
+        enumerable: true,
+        get: () => this.#_unreliablePatchRate,
+        set: (milliseconds) => {
+          this.#_unreliablePatchRate = milliseconds;
+          this._armUnreliablePatches();
+        }
       }
     });
     this.patchRate = this.#_patchRate;
@@ -798,6 +848,7 @@ var Room = class _Room {
       this.state,
       this._inputController !== void 0 ? { sNow } : void 0
     );
+    this._flushUnreliable();
     this._flushPendingClientFrames();
     this._flushAfterPatchBroadcasts();
     const rw = this.#rewind;
@@ -806,6 +857,52 @@ var Room = class _Room {
     }
     return hasChanges;
   }
+  /**
+   * Encode and send the `@unreliable` state fields over each client's
+   * unreliable channel. Those fields never appear in a {@link broadcastPatch}
+   * frame, and clients on a transport without a datagram channel are skipped.
+   *
+   * Driven automatically once the state declares an `@unreliable` field — right
+   * after each {@link broadcastPatch}, or on its own timer when
+   * {@link unreliablePatchRate} is set. Public so a room driving
+   * `broadcastPatch()` by hand can drive this by hand too.
+   */
+  broadcastUnreliablePatch() {
+    if (!this.state) {
+      return false;
+    }
+    return this._serializer.applyUnreliablePatches?.(this.clients) ?? false;
+  }
+  /**
+   * Decide how the unreliable channel is driven — and, for the rooms that never
+   * touch it, decide to not drive it at all. Runs when the state is assigned
+   * (the serializer knows by then whether any `@unreliable` field exists) and
+   * whenever {@link unreliablePatchRate} changes.
+   *
+   * A room whose state declares no `@unreliable` field leaves
+   * {@link _flushUnreliable} at {@link NOOP}, so its patch tick costs exactly
+   * what it did before this feature existed.
+   */
+  _armUnreliablePatches() {
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = void 0;
+    }
+    const armed = this._serializer?.hasUnreliableFields === true;
+    const rate = this.#_unreliablePatchRate;
+    const dedicated = armed && rate !== null && rate !== 0;
+    const inline = armed && !dedicated;
+    this._flushUnreliable = inline ? () => {
+      this.broadcastUnreliablePatch();
+    } : NOOP;
+    if (dedicated) {
+      this.#_unreliablePatchInterval = setInterval(() => this.broadcastUnreliablePatch(), rate);
+    } else if (inline && !this.#_patchRate) {
+      logger.warn(
+        "@colyseus/core: state has @unreliable fields but patchRate is disabled \u2014 set `room.unreliablePatchRate` to flush them, or they will never update."
+      );
+    }
+  }
   onMessage(_messageType, _validationSchema, _callback) {
     return this.#_messages.on(_messageType, _validationSchema, _callback);
   }
@@ -1272,6 +1369,10 @@ var Room = class _Room {
       clearInterval(this.#_patchInterval);
       this.#_patchInterval = void 0;
     }
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = void 0;
+    }
     if (this._simulationInterval) {
       clearInterval(this._simulationInterval);
       this._simulationInterval = void 0;