@colyseus/core 0.18.3 → 0.18.5

package/build/Room.cjs

@@ -1,3 +1,4 @@
+const __cjsImportMetaUrl = require('node:url').pathToFileURL(__filename).href;
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -64,6 +65,8 @@ var import_RoomPlugin = require("./RoomPlugin.cjs");
 var import_RoomPlugin2 = require("./RoomPlugin.cjs");
 var DEFAULT_PATCH_RATE = 1e3 / 20;
 var DEFAULT_SIMULATION_INTERVAL = 1e3 / 60;
+var NOOP = () => {
+};
 var noneSerializer = new import_NoneSerializer.NoneSerializer();
 var AFTER_PATCH_OPTS = Object.freeze({ afterNextPatch: true });
 var DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
@@ -103,6 +106,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.
@@ -197,6 +236,8 @@ var Room = class _Room {
   #_autoDispose;
   #_patchRate;
   #_patchInterval;
+  #_unreliablePatchRate;
+  #_unreliablePatchInterval;
   #_state;
   #_messages;
   // Re-expose the registry for @colyseus/playground introspection and
@@ -218,6 +259,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: {
@@ -233,6 +275,7 @@ var Room = class _Room {
           }
           this._serializer.reset(newState);
           this.#_state = newState;
+          this._armUnreliablePatches();
         }
       },
       maxClients: {
@@ -267,6 +310,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;
@@ -826,6 +877,7 @@ var Room = class _Room {
       this.state,
       this._inputController !== void 0 ? { sNow } : void 0
     );
+    this._flushUnreliable();
     this._flushPendingClientFrames();
     this._flushAfterPatchBroadcasts();
     const rw = this.#rewind;
@@ -834,6 +886,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) {
+      import_Logger.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);
   }
@@ -1093,7 +1191,7 @@ var Room = class _Room {
    * Allow the specified client to reconnect into the room. Must be used inside `onLeave()` method.
    * If seconds is provided, the reconnection is going to be cancelled after the provided amount of seconds.
    *
-   * @param client - The client that is allowed to reconnect into the room.
+   * @param previousClient - The client that is allowed to reconnect into the room.
    * @param seconds - The time in seconds that the client is allowed to reconnect into the room.
    *
    * @returns Deferred<Client> - The differed is a promise like type.
@@ -1300,6 +1398,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;
@@ -1360,7 +1462,12 @@ var Room = class _Room {
   #_forciblyCloseClient(client, closeCode, reason) {
     client.ref.removeAllListeners("message");
     client.ref.removeListener("close", client.ref["onleave"]);
-    this._onLeave(client, closeCode).then(() => client.leave(closeCode, reason));
+    const ref = client.ref;
+    this._onLeave(client, closeCode).then(() => {
+      if (client.ref === ref) {
+        client.leave(closeCode, reason);
+      }
+    });
   }
   async _onLeave(client, code) {
     const method = code === import_shared_types.CloseCode.CONSENTED || client.state === import_Transport.ClientState.RECONNECTING ? this.onLeave : this.onDrop || this.onLeave;
@@ -1381,11 +1488,14 @@ var Room = class _Room {
         this.#_onLeaveConcurrent--;
       }
     }
+    if (client.state === import_Transport.ClientState.RECONNECTED) {
+      return;
+    }
     if (this._reconnections[client.reconnectionToken]) {
       this._reconnections[client.reconnectionToken][1].catch(async () => {
         await this.#_onAfterLeave(client, code, method === this.onDrop);
       });
-    } else if (client.state !== import_Transport.ClientState.RECONNECTED) {
+    } else {
       await this.#_onAfterLeave(client, code, method === this.onDrop);
     }
   }