@colyseus/core 0.18.0 → 0.18.1

package/src/serializer/SchemaSerializer.ts

@@ -1,11 +1,85 @@
-import { Protocol } from '@colyseus/shared-types';
+import { Protocol, ProtocolModifier } from '@colyseus/shared-types';
 
-import type { Serializer } from './Serializer.ts';
-import { type Client, ClientState } from '../Transport.ts';
+import type { PatchTimingContext, Serializer } from './Serializer.ts';
+import { type Client, type ClientPrivate, ClientState } from '../Transport.ts';
 
-import { type Iterator, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
+import { type Iterator, encode, Encoder, dumpChanges, Reflection, Schema, StateView } from '@colyseus/schema';
 import { debugPatch } from '../Debug.ts';
 
+/**
+ * Size of the {@link ProtocolModifier.TIMED} prefix that follows the
+ * protocol byte:
+ *   `[uint32 sNow][uint32 inputSeq]`
+ *
+ *   - `sNow`     — server clock as **milliseconds since room start**
+ *     (`room.clock.elapsedTime`), NOT raw `performance.now()`. A portable,
+ *     language-agnostic integer (C/C#/Lua have no `performance.now()`); the
+ *     server's own time-keyed logic uses the SAME `clock.elapsedTime` so the
+ *     client's reconstructed `serverNow()` stays in phase. Wraps at u32
+ *     (~49.7 days uptime) — irrelevant per session. Drives the client clock
+ *     offset / `serverNow()`.
+ *   - `inputSeq` — seq VALUE of the last input CONSUMED into the authoritative
+ *     state (the input buffer's `ackSeq`, i.e. last-PROCESSED input). Reliable:
+ *     equals the consumed count (inputs are sequenced implicitly by receive
+ *     order). Unreliable: the framework wire seq, so a fully-dropped input
+ *     doesn't make the ack lag the client's sent seq by the lost count. This
+ *     single number is the canonical reconciliation ack ("the sequence number
+ *     of the last input the server processed"); the client prunes its
+ *     pending-input buffer against it AND derives RTT from its round-trip
+ *     (`now − sendTime(inputSeq)`). No separate received-seq / received-time —
+ *     RTT-from-the-processed-ack is round-trip-inclusive, which is the standard.
+ */
+const TIMED_PREFIX_SIZE = 8;
+
+/**
+ * Construct a per-recipient TIMED buffer:
+ *   `[code|TIMED][sNow][inputSeq][...schema bytes]`
+ *
+ * `encodedBody` is the shared encoded buffer whose byte 0 already holds the
+ * base protocol code (ROOM_STATE or ROOM_STATE_PATCH); bytes 1.. are the
+ * schema payload. We construct a fresh per-client Buffer so the transport
+ * never sees a buffer that might mutate between queue and send.
+ *
+ * Uses the schema `encode.*` helpers to keep the wire layout symmetric with
+ * the SDK's `decode.*`-driven reader.
+ */
+function buildTimedFrame(
+  encodedBody: Uint8Array,
+  sNow: number,
+  inputSeq: number,
+): Buffer {
+  const schemaPayload = encodedBody.subarray(1);
+  const out = Buffer.allocUnsafe(1 + TIMED_PREFIX_SIZE + schemaPayload.length);
+  out[0] = encodedBody[0] | ProtocolModifier.TIMED;
+  const it: Iterator = { offset: 1 };
+  encode.uint32(out, sNow >>> 0, it); // ms since room start (clock.elapsedTime)
+  encode.uint32(out, inputSeq >>> 0, it);
+  out.set(schemaPayload, it.offset);
+  return out;
+}
+
+/** Seq VALUE of the last input consumed from the client's buffer — the
+ *  reconciliation ack (and RTT correlation key). Reliable: equals the consumed
+ *  count; unreliable: the framework wire seq (so packet loss doesn't skew it).
+ *  0 when the room doesn't buffer input. */
+function clientProcessedInputSeq(client: Client): number {
+  return (client as Client & ClientPrivate)._inputBuffer?.ackSeq ?? 0;
+}
+
+/**
+ * Send a per-recipient patch frame: a TIMED-prefixed buffer when `timing` is set,
+ * else the shared `encodedBody` passed straight through (no per-client copy). Any
+ * `afterNextPatch` frames staged on `client._pendingFrames` are NOT coalesced here
+ * — they go out standalone right after the patch via `Room._flushPendingClientFrames`.
+ */
+function sendClientFrame(client: Client, encodedBody: Uint8Array, timing?: PatchTimingContext): void {
+  if (timing) {
+    client.raw(buildTimedFrame(encodedBody, timing.sNow, clientProcessedInputSeq(client)));
+  } else {
+    client.raw(encodedBody);
+  }
+}
+
 const SHARED_VIEW = {};
 
 export class SchemaSerializer<T extends Schema> implements Serializer<T> {
@@ -38,27 +112,29 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
     }
   }
 
-  public getFullState(client?: Client) {
+  public getFullState(client?: Client, timing?: PatchTimingContext) {
     if (this.needFullEncode || this.encoder.root.changes.next !== undefined) {
       this.sharedOffsetCache = { offset: 1 };
       this.fullEncodeCache = this.encoder.encodeAll(this.sharedOffsetCache, this.fullEncodeBuffer);
       this.needFullEncode = false;
     }
 
-    if (this.hasFilters && client?.view) {
-      return this.encoder.encodeAllView(
-        client.view,
-        this.sharedOffsetCache.offset,
-        { ...this.sharedOffsetCache },
-        this.fullEncodeBuffer
-      );
-
-    } else {
-      return this.fullEncodeCache;
+    const body = (this.hasFilters && client?.view)
+      ? this.encoder.encodeAllView(
+          client.view,
+          this.sharedOffsetCache.offset,
+          { ...this.sharedOffsetCache },
+          this.fullEncodeBuffer
+        )
+      : this.fullEncodeCache;
+
+    if (timing && client) {
+      return buildTimedFrame(body, timing.sNow, clientProcessedInputSeq(client));
     }
+    return body;
   }
 
-  public applyPatches(clients: Client[]) {
+  public applyPatches(clients: Client[], _state?: unknown, timing?: PatchTimingContext) {
     let numClients = clients.length;
 
     if (numClients === 0) {
@@ -92,11 +168,26 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           this.encoder.sharedBuffer[0] = Protocol.ROOM_STATE_PATCH;
 
           clientsWithViewChange.forEach((client) => {
-            client.raw(this.encoder.encodeView(client.view, sharedOffset, it));
+            const encodedView = this.encoder.encodeView(client.view, sharedOffset, it);
+            sendClientFrame(client, encodedView, timing);
           });
         }
       }
 
+      // Heartbeat: clients that advertised CLIENT_TIMING still need
+      // periodic timing samples to keep their clock offset / RTT estimate
+      // fresh during quiet ticks. Emit a TIMED-prefixed ROOM_STATE_PATCH
+      // with an empty schema body — 1 byte protocol + 12 bytes prefix.
+      // No-op for rooms without `defineInput()` (timing is undefined).
+      if (timing) {
+        const heartbeatBody = Buffer.from([Protocol.ROOM_STATE_PATCH]);
+        for (let i = 0; i < clients.length; i++) {
+          const client = clients[i];
+          if (client.state !== ClientState.JOINED) continue;
+          sendClientFrame(client, heartbeatBody, timing);
+        }
+      }
+
       // skip patching state if:
       // - no clients are connected
       // - no changes were made
@@ -129,7 +220,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           continue;
         }
 
-        client.raw(encodedChanges);
+        sendClientFrame(client, encodedChanges, timing);
       }
 
     } else {
@@ -159,7 +250,7 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
           this.encodedViews.set(view, encodedView);
         }
 
-        client.raw(encodedView);
+        sendClientFrame(client, encodedView, timing);
       }
 
       // clear views

package/src/serializer/Serializer.ts

@@ -1,9 +1,20 @@
 import type { Client } from '../Transport.ts';
 
+/**
+ * Per-tick timing context, populated by the Room when
+ * {@link Room.defineInput} was called. The serializer uses it to emit a
+ * {@link ProtocolModifier.TIMED} prefix for clients that advertised
+ * the {@link HandshakeSection.CLIENT_TIMING} capability.
+ */
+export interface PatchTimingContext {
+  /** `performance.now()` at the moment the patch is being applied. */
+  sNow: number;
+}
+
 export interface Serializer<T> {
   id: string;
   reset(data: any): void;
-  getFullState(client?: Client): Uint8Array;
-  applyPatches(clients: Client[], state: T): boolean;
+  getFullState(client?: Client, timing?: PatchTimingContext): Uint8Array;
+  applyPatches(clients: Client[], state: T, timing?: PatchTimingContext): boolean;
   handshake?(): Uint8Array;
 }

package/src/utils/DevMode.ts

@@ -31,11 +31,24 @@ export async function reloadFromCache() {
   debugDevMode("rooms to restore: %i", roomHistoryList.length);
 
   for (const [roomId, value] of roomHistoryList) {
-    const roomHistory = JSON.parse(value);
-    debugDevMode("restoring room %s (%s)", roomHistory.roomName, roomId);
-
-    const recreatedRoomListing = await handleCreateRoom(roomHistory.roomName, roomHistory.clientOptions, roomId);
-    const recreatedRoom = getLocalRoomById(recreatedRoomListing.roomId);
+    let roomHistory: any;
+    let recreatedRoom: Room;
+    let recreatedRoomListing: any;
+
+    try {
+      roomHistory = JSON.parse(value);
+      debugDevMode("restoring room %s (%s)", roomHistory.roomName, roomId);
+
+      recreatedRoomListing = await handleCreateRoom(roomHistory.roomName, roomHistory.clientOptions, roomId);
+      recreatedRoom = getLocalRoomById(recreatedRoomListing.roomId);
+
+    } catch (e: any) {
+      // unrestorable entry (e.g. room type renamed/removed) — drop it
+      // instead of wedging the boot
+      debugAndPrintError(`❌ couldn't restore room '${roomId}':\n${e.stack}`);
+      await presence.hdel(getRoomRestoreListKey(), roomId);
+      continue;
+    }
 
     // Restore previous state
     if (roomHistory.hasOwnProperty("state")) {
@@ -144,14 +157,6 @@ export async function cacheRoomHistory(rooms: { [roomId: string]: Room }) {
   }
 }
 
-export async function getPreviousProcessId(hostname: string = '') {
-  return await presence.hget(getProcessRestoreKey(), hostname);
-}
-
 export function getRoomRestoreListKey() {
   return 'roomhistory';
 }
-
-export function getProcessRestoreKey() {
-  return 'processhistory';
-}

package/src/utils/Env.ts

@@ -1,3 +1,4 @@
+import os from 'os';
 import { LocalPresence } from '../presence/LocalPresence.ts';
 import { LocalDriver, type MatchMakerDriver } from '../matchmaker/LocalDriver/LocalDriver.ts';
 import { logger } from '../Logger.ts';
@@ -7,16 +8,23 @@ export function isColyseusCloud(): boolean {
   return process.env.COLYSEUS_CLOUD !== undefined;
 }
 
+// On Colyseus Cloud, only opt into Redis when there's more than one CPU
+// (multi-process deploys) or when REDIS_URI is explicitly provided.
+// Single-CPU instances without REDIS_URI keep using Local presence/driver.
+function shouldUseRedisOnCloud(): boolean {
+  return os.cpus().length > 1 || process.env.REDIS_URI !== undefined;
+}
+
 export async function getDefaultPresence(): Promise<Presence> {
-  if (isColyseusCloud()) {
+  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
     try {
       const RedisPresence = await import('@colyseus/redis-presence');
       return new RedisPresence.RedisPresence(process.env.REDIS_URI);
     } catch (e) {
       console.error(e);
       logger.warn("");
-      logger.warn("❌ could not initialize RedisDriver.");
-      logger.warn("👉 npm install --save @colyseus/redis-driver");
+      logger.warn("❌ could not initialize RedisPresence.");
+      logger.warn("👉 npm install --save @colyseus/redis-presence");
       logger.warn("");
     }
   }
@@ -24,7 +32,7 @@ export async function getDefaultPresence(): Promise<Presence> {
 }
 
 export async function getDefaultDriver(): Promise<MatchMakerDriver> {
-  if (isColyseusCloud()) {
+  if (isColyseusCloud() && shouldUseRedisOnCloud()) {
     try {
       const RedisDriver = await import('@colyseus/redis-driver');
       return new RedisDriver.RedisDriver(process.env.REDIS_URI);

package/src/utils/Utils.ts

@@ -26,6 +26,15 @@ export type ExtractMethodOrPropertyType<
 export const REMOTE_ROOM_SHORT_TIMEOUT = Number(process.env.COLYSEUS_PRESENCE_SHORT_TIMEOUT || 2000);
 export const MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME = Number(process.env.COLYSEUS_MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME || 0.5);
 
+/**
+ * The well-known `Symbol.metadata` (TC39 decorator metadata), falling back to the
+ * registered symbol on runtimes that don't expose it globally yet. `@colyseus/schema`
+ * stores each class's field metadata under this key — read it via
+ * `instance.constructor[$METADATA]`. Shared so every reader resolves the IDENTICAL
+ * symbol (InputBuffer's field-name walk, Rewind's field-index lookup).
+ */
+export const $METADATA: symbol = (Symbol as { metadata?: symbol }).metadata ?? Symbol.for("Symbol.metadata");
+
 export function generateId(length: number = 9) {
   return nanoid(length);
 }