@colyseus/core 0.18.4 → 0.18.6

package/src/serializer/SchemaSerializer.ts

@@ -3,8 +3,9 @@ import { Protocol, ProtocolModifier } from '@colyseus/shared-types';
 import type { PatchTimingContext, Serializer } from './Serializer.ts';
 import { type Client, type ClientPrivate, ClientState } from '../Transport.ts';
 
-import { type Iterator, encode, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
+import { type Iterator, $numFields, encode, Encoder, dumpChanges, Metadata, Reflection, Schema, StateView, TypeContext } from '@colyseus/schema';
 import { debugPatch } from '../Debug.ts';
+import { logger } from '../Logger.ts';
 
 /**
  * Size of the {@link ProtocolModifier.TIMED} prefix that follows the
@@ -80,6 +81,38 @@ function sendClientFrame(client: Client, encodedBody: Uint8Array, timing?: Patch
   }
 }
 
+/**
+ * Size of the {@link ProtocolModifier.UNRELIABLE} header that follows the
+ * protocol byte: `[uint16 seq]`. See {@link ProtocolModifier.UNRELIABLE} for
+ * the wrap-safe freshness rule the client applies to `seq`.
+ */
+const UNRELIABLE_HEADER_SIZE = 2;
+
+/**
+ * Does any Schema class reachable from the state root declare an `@unreliable`
+ * field? Walked once per room, in {@link SchemaSerializer.reset} — the result
+ * gates whether the unreliable channel is wired up at all, so rooms that don't
+ * use it never reach any of the code below.
+ */
+function stateHasUnreliableFields(context: TypeContext): boolean {
+  for (const klass of context.schemas.keys()) {
+    const metadata = klass[Symbol.metadata];
+    if (metadata === undefined) { continue; }
+
+    // `$numFields` is the last index, inclusive (matches `Metadata.getFields`).
+    for (let i = 0; i <= metadata[$numFields]; i++) {
+      if (Metadata.hasUnreliableAtIndex(metadata, i)) { return true; }
+    }
+  }
+  return false;
+}
+
+/** Can this client receive the unreliable channel right now? Its transport
+ *  exposing {@link Client.rawUnreliable} IS the capability check. */
+function canReceiveUnreliable(client: Client): boolean {
+  return client.state === ClientState.JOINED && client.rawUnreliable !== undefined;
+}
+
 const SHARED_VIEW = {};
 
 export class SchemaSerializer<T extends Schema> implements Serializer<T> {
@@ -100,15 +133,34 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
 
   protected encodedViews: Map<StateView | typeof SHARED_VIEW, Uint8Array>;
 
+  /** @see {@link Serializer.hasUnreliableFields} */
+  public hasUnreliableFields: boolean = false;
+
+  /** Room-wide counter stamped into every unreliable frame so the client can
+   *  drop reordered datagrams. Wraps at 65536 — see {@link ProtocolModifier.UNRELIABLE}. */
+  protected unreliableSeq: number = 0;
+
+  protected encodedUnreliableViews: Map<StateView | typeof SHARED_VIEW, Uint8Array>;
+
+  /** The `@unreliable`-with-no-datagram-transport warning fires once per room. */
+  protected warnedNoUnreliableTransport = false;
+
   public reset(newState: T & Schema) {
     this.encoder = new Encoder(newState);
     this.hasFilters = this.encoder.context.hasFilters;
+    this.hasUnreliableFields = stateHasUnreliableFields(this.encoder.context);
 
     // cache ROOM_STATE byte as part of the encoded buffer
     this.fullEncodeBuffer[0] = Protocol.ROOM_STATE;
 
     if (this.hasFilters) {
       this.encodedViews = new Map();
+
+      if (this.hasUnreliableFields) {
+        // Separate from `encodedViews`: the two channels encode on independent
+        // cadences, so a reliable tick's cache must never be served to one.
+        this.encodedUnreliableViews = new Map();
+      }
     }
   }
 
@@ -273,6 +325,99 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
     return true;
   }
 
+  /**
+   * Encode and send the UNRELIABLE channel — the `@unreliable` fields, which
+   * `applyPatches` never emits. Frames go out via {@link Client.rawUnreliable}
+   * (a WebTransport datagram); clients whose transport has no unreliable
+   * channel are skipped entirely.
+   *
+   * Runs on its own cadence, independent of `applyPatches`. Only ever called on
+   * rooms where {@link hasUnreliableFields} is true.
+   */
+  public applyUnreliablePatches(clients: Client[]): boolean {
+    if (!this.encoder.hasUnreliableChanges) { return false; }
+
+    // These mutations are visible to `encodeAll`, so the cached full state is
+    // stale — even though `root.changes` (the reliable queue) is empty and
+    // `getFullState`'s own guard would therefore miss it.
+    this.needFullEncode = true;
+
+    if (!clients.some(canReceiveUnreliable)) {
+      this.warnNoUnreliableTransport(clients);
+      // Drain regardless: the queue is not self-clearing, and an un-discarded
+      // tick would grow it without bound.
+      this.encoder.discardUnreliableChanges();
+      return false;
+    }
+
+    this.unreliableSeq = (this.unreliableSeq + 1) & 0xFFFF;
+
+    // Stamp the header before encoding, as the reliable path does. Safe across
+    // a buffer overflow: `Encoder._resizeBuffer` copies the old bytes forward.
+    const it: Iterator = { offset: 1 + UNRELIABLE_HEADER_SIZE };
+    this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH | ProtocolModifier.UNRELIABLE;
+    encode.uint16(this.encoder.sharedBuffer, this.unreliableSeq, { offset: 1 });
+
+    // encode changes once, for all clients
+    const encodedChanges = this.encoder.encodeUnreliable(it);
+
+    let numClients = clients.length;
+
+    if (!this.hasFilters) {
+      while (numClients--) {
+        const client = clients[numClients];
+        if (canReceiveUnreliable(client)) { client.rawUnreliable!(encodedChanges); }
+      }
+
+    } else {
+      // cache shared offset
+      const sharedOffset = it.offset;
+
+      while (numClients--) {
+        const client = clients[numClients];
+        if (!canReceiveUnreliable(client)) { continue; }
+
+        const view = client.view || SHARED_VIEW;
+
+        let encodedView = this.encodedUnreliableViews.get(view);
+
+        // allow to pass the same encoded view for multiple clients
+        if (encodedView === undefined) {
+          encodedView = (view === SHARED_VIEW)
+            ? encodedChanges
+            : this.encoder.encodeUnreliableView(client.view, sharedOffset, it);
+          this.encodedUnreliableViews.set(view, encodedView);
+        }
+
+        client.rawUnreliable!(encodedView);
+      }
+
+      // clear views
+      this.encodedUnreliableViews.clear();
+    }
+
+    // discard changes after sending
+    this.encoder.discardUnreliableChanges();
+
+    return true;
+  }
+
+  /**
+   * The state declares `@unreliable` fields but not one connected client can
+   * receive them — every WebSocket transport lacks a datagram channel. Those
+   * fields keep their join-time value and never update, which is silent
+   * otherwise. Warns once per room.
+   */
+  private warnNoUnreliableTransport(clients: Client[]) {
+    if (this.warnedNoUnreliableTransport || clients.length === 0) { return; }
+    this.warnedNoUnreliableTransport = true;
+    logger.warn(
+      "@colyseus/core: state has @unreliable fields, but no connected client's transport" +
+      " provides an unreliable channel — those fields will not be patched." +
+      " Use @colyseus/h3-transport (WebTransport) to enable them."
+    );
+  }
+
   public handshake() {
     /**
      * Cache handshake to avoid encoding it for each client joining

package/src/serializer/Serializer.ts

@@ -17,4 +17,21 @@ export interface Serializer<T> {
   getFullState(client?: Client, timing?: PatchTimingContext): Uint8Array;
   applyPatches(clients: Client[], state: T, timing?: PatchTimingContext): boolean;
   handshake?(): Uint8Array;
+
+  /**
+   * Whether the state declares at least one `@unreliable` field. Computed once
+   * in {@link Serializer.reset}; the Room reads it once to decide whether to arm
+   * the unreliable flush at all. Never consulted on the tick path — a room that
+   * doesn't use the channel must not pay for it.
+   */
+  hasUnreliableFields?: boolean;
+
+  /**
+   * Encode and send the UNRELIABLE channel to every client whose transport
+   * exposes {@link Client.rawUnreliable}. Only called on rooms where
+   * {@link Serializer.hasUnreliableFields} is true.
+   *
+   * Runs on its own cadence, independent of {@link Serializer.applyPatches}.
+   */
+  applyUnreliablePatches?(clients: Client[]): boolean;
 }