@colyseus/core 0.17.0 → 0.17.1

package/src/rooms/RankedQueueRoom.ts

@@ -0,0 +1,425 @@
+import { Room, type Client, matchMaker, type IRoomCache, debugMatchMaking, ServerError, ErrorCode, isDevMode, } from "@colyseus/core";
+
+export interface RankedQueueOptions {
+  /**
+   * number of players on each match
+   */
+  maxPlayers?: number;
+
+  /**
+   * name of the room to create
+   */
+  matchRoomName: string;
+
+  /**
+   * after these cycles, create a match with a bot
+   */
+  maxWaitingCycles?: number;
+
+  /**
+   * after this time, try to fit this client with a not-so-compatible group
+   */
+  maxWaitingCyclesForPriority?: number;
+
+  /**
+   * If set, teams must have the same size to be matched together
+   */
+  maxTeamSize?: number;
+
+  /**
+   * If `allowIncompleteGroups` is true, players inside an unmatched group (that
+   * did not reached `maxPlayers`, and `maxWaitingCycles` has been
+   * reached) will be matched together. Your room should fill the remaining
+   * spots with "bots" on this case.
+   */
+  allowIncompleteGroups?: boolean;
+
+  /**
+   * Comparison function for matching clients to groups
+   * Returns true if the client is compatible with the group
+   */
+  compare?: (client: ClientQueueData, matchGroup: MatchGroup) => boolean;
+
+  /**
+   *
+   * When onGroupReady is set, the "roomNameToCreate" option is ignored.
+   */
+  onGroupReady?: (this: RankedQueueRoom, group: MatchGroup) => Promise<IRoomCache>;
+}
+
+export interface MatchGroup {
+  averageRank: number;
+  clients: Array<Client<{ userData: ClientQueueData }>>,
+  ready?: boolean;
+  confirmed?: number;
+}
+
+export interface MatchTeam {
+  averageRank: number;
+  clients: Array<Client<{ userData: ClientQueueData }>>,
+  teamId: string | symbol;
+}
+
+export interface ClientQueueData {
+  /**
+   * Rank of the client
+   */
+  rank: number;
+
+  /**
+   * Timestamp of when the client entered the queue
+   */
+  currentCycle?: number;
+
+  /**
+   * Optional: if matching with a team, the team ID
+   */
+  teamId?: string;
+
+  /**
+   * Additional options passed by the client when joining the room
+   */
+  options?: any;
+
+  /**
+   * Match group the client is currently in
+   */
+  group?: MatchGroup;
+
+  /**
+   * Whether the client has confirmed the connection to the room
+   */
+  confirmed?: boolean;
+
+  /**
+   * Whether the client should be prioritized in the queue
+   * (e.g. for players that are waiting for a long time)
+   */
+  highPriority?: boolean;
+
+  /**
+   * The last number of clients in the queue sent to the client
+   */
+  lastQueueClientCount?: number;
+}
+
+const DEFAULT_TEAM = Symbol("$default_team");
+const DEFAULT_COMPARE = (client: ClientQueueData, matchGroup: MatchGroup) => {
+  const diff = Math.abs(client.rank - matchGroup.averageRank);
+  const diffRatio = (diff / matchGroup.averageRank);
+  // If diff ratio is too high, create a new match group
+  return (diff < 10 || diffRatio <= 2);
+}
+
+export class RankedQueueRoom extends Room {
+  maxPlayers = 4;
+  maxTeamSize: number;
+  allowIncompleteGroups: boolean = false;
+
+  maxWaitingCycles = 15;
+  maxWaitingCyclesForPriority?: number = 10;
+
+  /**
+   * Evaluate groups for each client at interval
+   */
+  cycleTickInterval = 1000;
+
+  /**
+   * Groups of players per iteration
+   */
+  groups: MatchGroup[] = [];
+  highPriorityGroups: MatchGroup[] = [];
+
+  matchRoomName: string;
+
+  protected compare = DEFAULT_COMPARE;
+  protected onGroupReady = (group: MatchGroup) => matchMaker.createRoom(this.matchRoomName, {});
+
+  messages = {
+    confirm: (client: Client, _: unknown) => {
+      const queueData = client.userData;
+
+      if (queueData && queueData.group && typeof (queueData.group.confirmed) === "number") {
+        queueData.confirmed = true;
+        queueData.group.confirmed++;
+        client.leave();
+      }
+    },
+  }
+
+  onCreate(options: RankedQueueOptions) {
+    if (typeof(options.maxWaitingCycles) === "number") {
+      this.maxWaitingCycles = options.maxWaitingCycles;
+    }
+
+    if (typeof(options.maxPlayers) === "number") {
+      this.maxPlayers = options.maxPlayers;
+    }
+
+    if (typeof(options.maxTeamSize) === "number") {
+      this.maxTeamSize = options.maxTeamSize;
+    }
+
+    if (typeof(options.allowIncompleteGroups) !== "undefined") {
+      this.allowIncompleteGroups = options.allowIncompleteGroups;
+    }
+
+    if (typeof(options.compare) === "function") {
+      this.compare = options.compare;
+    }
+
+    if (typeof(options.onGroupReady) === "function") {
+      this.onGroupReady = options.onGroupReady;
+    }
+
+    if (options.matchRoomName) {
+      this.matchRoomName = options.matchRoomName;
+
+    } else {
+      throw new ServerError(ErrorCode.APPLICATION_ERROR, "RankedQueueRoom: 'matchRoomName' option is required.");
+    }
+
+    debugMatchMaking("RankedQueueRoom#onCreate() maxPlayers: %d, maxWaitingCycles: %d, maxTeamSize: %d, allowIncompleteGroups: %d, roomNameToCreate: %s", this.maxPlayers, this.maxWaitingCycles, this.maxTeamSize, this.allowIncompleteGroups, this.matchRoomName);
+
+    /**
+     * Redistribute clients into groups at every interval
+     */
+    this.setSimulationInterval(() => this.reassignMatchGroups(), this.cycleTickInterval);
+  }
+
+  onJoin(client: Client, options: any, auth?: unknown) {
+    this.addToQueue(client, {
+      rank: options.rank,
+      teamId: options.teamId,
+      options,
+    });
+  }
+
+  addToQueue(client: Client, queueData: ClientQueueData) {
+    if (queueData.currentCycle === undefined) {
+      queueData.currentCycle = 0;
+    }
+    client.userData = queueData;
+
+    // FIXME: reassign groups upon joining [?] (without incrementing cycle count)
+    client.send("clients", 1);
+  }
+
+  createMatchGroup() {
+    const group: MatchGroup = { clients: [], averageRank: 0 };
+    this.groups.push(group);
+    return group;
+  }
+
+  reassignMatchGroups() {
+    // Re-set all groups
+    this.groups.length = 0;
+    this.highPriorityGroups.length = 0;
+
+    const sortedClients = (this.clients)
+      .filter((client) => {
+        // Filter out:
+        // - clients that are not in the queue
+        // - clients that are already in a "ready" group
+        return (
+          client.userData &&
+          client.userData.group?.ready !== true
+        );
+      })
+      .sort((a, b) => {
+        //
+        // Sort by rank ascending
+        //
+        return a.userData.rank - b.userData.rank;
+      });
+
+    //
+    // The room either distribute by teams or by clients
+    //
+    if (typeof(this.maxTeamSize) === "number") {
+      this.redistributeTeams(sortedClients);
+
+    } else {
+      this.redistributeClients(sortedClients);
+    }
+
+    this.evaluateHighPriorityGroups();
+    this.processGroupsReady();
+  }
+
+  redistributeTeams(sortedClients: Client<{ userData: ClientQueueData }>[]) {
+    const teamsByID: { [teamId: string | symbol]: MatchTeam } = {};
+
+    sortedClients.forEach((client) => {
+      const teamId = client.userData.teamId || DEFAULT_TEAM;
+
+      // Create a new team if it doesn't exist
+      if (!teamsByID[teamId]) {
+        teamsByID[teamId] = { teamId: teamId, clients: [], averageRank: 0, };
+      }
+
+      teamsByID[teamId].averageRank += client.userData.rank;
+      teamsByID[teamId].clients.push(client);
+    });
+
+    // Calculate average rank for each team
+    let teams = Object.values(teamsByID).map((team) => {
+      team.averageRank /= team.clients.length;
+      return team;
+    }).sort((a, b) => {
+      // Sort by average rank ascending
+      return a.averageRank - b.averageRank;
+    });
+
+    // Iterate over teams multiple times until all clients are assigned to a group
+    do {
+      let currentGroup: MatchGroup = this.createMatchGroup();
+      teams = teams.filter((team) => {
+        // Remove clients from the team and add them to the current group
+        const totalRank = team.averageRank * team.clients.length;
+
+        // currentGroup.averageRank = (currentGroup.averageRank === undefined)
+        //   ? team.averageRank
+        //   : (currentGroup.averageRank + team.averageRank) / ;
+        currentGroup = this.redistributeClients(team.clients.splice(0, this.maxTeamSize), currentGroup, totalRank);
+
+        if (team.clients.length >= this.maxTeamSize) {
+          // team still has enough clients to form a group
+          return true;
+        }
+
+        // increment cycle count for all clients in the team
+        team.clients.forEach((client) => client.userData.currentCycle++);
+
+        return false;
+      });
+    } while (teams.length >= 2);
+  }
+
+  redistributeClients(
+    sortedClients: Client<{ userData: ClientQueueData }>[],
+    currentGroup: MatchGroup = this.createMatchGroup(),
+    totalRank: number = 0,
+  ) {
+    for (let i = 0, l = sortedClients.length; i < l; i++) {
+      const client = sortedClients[i];
+      const userData = client.userData;
+      const currentCycle = userData.currentCycle++;
+
+      if (currentGroup.averageRank > 0) {
+        if (
+          !this.compare(userData, currentGroup) &&
+          !userData.highPriority
+        ) {
+          currentGroup = this.createMatchGroup();
+          totalRank = 0;
+        }
+      }
+
+      userData.group = currentGroup;
+      currentGroup.clients.push(client);
+
+      totalRank += userData.rank;
+      currentGroup.averageRank = totalRank / currentGroup.clients.length;
+
+      // Enough players in the group, mark it as ready!
+      if (currentGroup.clients.length === this.maxPlayers) {
+        currentGroup.ready = true;
+        currentGroup = this.createMatchGroup();
+        totalRank = 0;
+        continue;
+      }
+
+      if (currentCycle >= this.maxWaitingCycles && this.allowIncompleteGroups) {
+        /**
+         * Match long-waiting clients with bots
+         */
+        if (this.highPriorityGroups.indexOf(currentGroup) === -1) {
+          this.highPriorityGroups.push(currentGroup);
+        }
+
+      } else if (
+        this.maxWaitingCyclesForPriority !== undefined &&
+        currentCycle >= this.maxWaitingCyclesForPriority
+      ) {
+        /**
+         * Force this client to join a group, even if rank is incompatible
+         */
+        userData.highPriority = true;
+      }
+    }
+
+    return currentGroup;
+  }
+
+  evaluateHighPriorityGroups() {
+    /**
+     * Evaluate groups with high priority clients
+     */
+    this.highPriorityGroups.forEach((group) => {
+      group.ready = group.clients.every((c) => {
+        // Give new clients another chance to join a group that is not "high priority"
+        return c.userData?.currentCycle > 1;
+        // return c.userData?.currentCycle >= this.maxWaitingCycles;
+      });
+    });
+  }
+
+  processGroupsReady() {
+    this.groups.forEach(async (group) => {
+      if (group.ready) {
+        group.confirmed = 0;
+
+        try {
+          /**
+           * Create room instance in the server.
+           */
+          const room = await this.onGroupReady.call(this, group);
+
+          /**
+           * Reserve a seat for each client in the group.
+           * (If one fails, force all clients to leave, re-queueing is up to the client-side logic)
+           */
+          await matchMaker.reserveMultipleSeatsFor(
+            room,
+            group.clients.map((client) => ({
+              sessionId: client.sessionId,
+              options: client.userData.options,
+              auth: client.auth,
+            })),
+          );
+
+          /**
+           * Send room data for new WebSocket connection!
+           */
+          group.clients.forEach((client, i) => {
+            client.send("seat", matchMaker.buildSeatReservation(room, client.sessionId));
+          });
+
+        } catch (e: any) {
+          //
+          // If creating a room, or reserving a seat failed - fail all clients
+          // Whether the clients retry or not is up to the client-side logic
+          //
+          group.clients.forEach(client => client.leave(1011, e.message));
+        }
+
+      } else {
+        /**
+         * Notify clients within the group on how many players are in the queue
+         */
+        group.clients.forEach((client) => {
+          //
+          // avoid sending the same number of clients to the client if it hasn't changed
+          //
+          const queueClientCount = group.clients.length;
+          if (client.userData.lastQueueClientCount !== queueClientCount) {
+            client.userData.lastQueueClientCount = queueClientCount;
+            client.send("clients", queueClientCount);
+          }
+        });
+      }
+    });
+  }
+
+}

package/src/rooms/RelayRoom.ts

@@ -0,0 +1,90 @@
+import { defineTypes, MapSchema, Schema } from '@colyseus/schema';
+
+import { Room } from '../Room.ts';
+import type { Client } from '../Transport.ts';
+import { CloseCode } from '../Protocol.ts';
+
+class Player extends Schema {
+  public connected: boolean;
+  public name: string;
+  public sessionId: string;
+}
+defineTypes(Player, {
+  connected: 'boolean',
+  name: 'string',
+  sessionId: 'string',
+});
+
+class State extends Schema {
+  public players = new MapSchema<Player>();
+}
+defineTypes(State, {
+  players: { map: Player },
+});
+
+/**
+ * client.joinOrCreate("relayroom", {
+ *   maxClients: 10,
+ *   allowReconnectionTime: 20
+ * });
+ */
+
+export class RelayRoom extends Room {
+  public state = new State();
+  public allowReconnectionTime: number = 0;
+
+  public onCreate(options: Partial<{
+    maxClients: number,
+    allowReconnectionTime: number,
+    metadata: any,
+  }>) {
+    if (options.maxClients) {
+      this.maxClients = options.maxClients;
+    }
+
+    if (options.allowReconnectionTime) {
+      this.allowReconnectionTime = Math.min(options.allowReconnectionTime, 40);
+    }
+
+    if (options.metadata) {
+      this.setMetadata(options.metadata);
+    }
+
+    this.onMessage('*', (client: Client, type: string | number, message: any) => {
+      this.broadcast(type, [client.sessionId, message], { except: client });
+    });
+  }
+
+  public onJoin(client: Client, options: any = {}) {
+    const player = new Player();
+
+    player.connected = true;
+    player.sessionId = client.sessionId;
+
+    if (options.name) {
+      player.name = options.name;
+    }
+
+    this.state.players.set(client.sessionId, player);
+  }
+
+  public async onLeave(client: Client, code: number) {
+    if (this.allowReconnectionTime > 0) {
+      const player = this.state.players.get(client.sessionId);
+      player.connected = false;
+
+      try {
+        if (code === CloseCode.CONSENTED) {
+          throw new Error('consented leave');
+        }
+
+        await this.allowReconnection(client, this.allowReconnectionTime);
+        player.connected = true;
+
+      } catch (e) {
+        this.state.players.delete(client.sessionId);
+      }
+    }
+  }
+
+}

package/src/router/default_routes.ts

@@ -0,0 +1,58 @@
+import { createEndpoint, createRouter } from "@colyseus/better-call";
+import * as matchMaker from "../MatchMaker.ts";
+import { getBearerToken } from "../utils/Utils.ts";
+
+export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName", { method: "POST" }, async (ctx) => {
+  // do not accept matchmaking requests if already shutting down
+  if (matchMaker.state === matchMaker.MatchMakerState.SHUTTING_DOWN) {
+    throw ctx.error(503);
+  }
+
+  const requestHeaders = ctx.request.headers;
+  const headers = Object.assign(
+    {},
+    matchMaker.controller.DEFAULT_CORS_HEADERS,
+    matchMaker.controller.getCorsHeaders(requestHeaders)
+  );
+
+  const method = ctx.params.method;
+  const roomName = ctx.params.roomName;
+
+  Object.entries(headers).forEach(([key, value]) => {
+    ctx.setHeader(key, value);
+  })
+  ctx.setHeader('Content-Type', 'application/json');
+
+  try {
+    const clientOptions = ctx.body;
+    const response = await matchMaker.controller.invokeMethod(
+      method,
+      roomName,
+      clientOptions,
+      {
+        token: getBearerToken(ctx.request.headers.get('authorization')),
+        headers: ctx.request.headers,
+        ip: requestHeaders.get('x-forwarded-for') ?? requestHeaders.get('x-client-ip') ?? requestHeaders.get('x-real-ip'),
+        req: ctx.request as any,
+      },
+    );
+
+    //
+    // TODO: respond with protocol, if available
+    //
+    // // specify protocol, if available.
+    // if (this.transport.protocol !== undefined) {
+    //   response.protocol = this.transport.protocol;
+    // }
+
+    return response;
+
+  } catch (e: any) {
+    throw ctx.error(e.code, { code: e.code, error: e.message, });
+  }
+
+});
+
+export function getDefaultRouter() {
+  return createRouter({ postMatchmakeMethod });
+}

package/src/router/index.ts

@@ -0,0 +1,43 @@
+import type { Server } from "http";
+import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint } from "@colyseus/better-call";
+import { toNodeHandler } from "@colyseus/better-call/node";
+
+export {
+  createEndpoint,
+  createMiddleware,
+  createInternalContext,
+} from "@colyseus/better-call";
+
+export { type Router, toNodeHandler };
+
+export function bindRouterToServer(server: Server, router: Router) {
+  // check if the server is bound to an express app
+  const expressApp: any = server.listeners('request').find((listener: Function) =>
+    listener.name === "app" && listener['mountpath'] === '/');
+
+  if (expressApp) {
+    // bind the router to the express app
+    expressApp.use(toNodeHandler(router.handler));
+
+  } else {
+    // otherwise, bind the router to the http server
+    server.on('request', toNodeHandler(router.handler));
+  }
+}
+
+/**
+ * Do not use this directly. This is used internally by `@colyseus/playground`.
+ * TODO: refactor. Avoid using globals.
+ * @internal
+ */
+export let __globalEndpoints: Record<string, Endpoint>;
+
+export function createRouter<
+  E extends Record<string, Endpoint>,
+  Config extends RouterConfig
+>(endpoints: E, config?: Config) {
+  // TODO: refactor. Avoid using globals.
+  __globalEndpoints = endpoints;
+
+  return createBetterCallRouter({ ...endpoints, }, config);
+}

package/src/serializer/NoneSerializer.ts

@@ -0,0 +1,16 @@
+import type { Client } from '../Transport.ts';
+import type { Serializer } from './Serializer.ts';
+
+export class NoneSerializer<T= any> implements Serializer<T> {
+  public id: string = 'none';
+
+  public reset(data: any) {}
+
+  public getFullState(client?: Client) {
+    return null;
+  }
+
+  public applyPatches(clients: Client[], state: T): boolean {
+    return false;
+  }
+}