@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/SessionRoom.js

@@ -0,0 +1,930 @@
+import { CloseCode, getMessageBytes, matchMaker, Protocol, Room, ServerError } from "colyseus";
+import { DedicatedSession } from "./DedicatedSession.js";
+import { getLogger } from "./GameServerLogger.js";
+import { DISCORD_SESSION_ISSUER } from "./discord/DiscordSignInConstants.js";
+import { getGameServerState } from "./GameServerState.js";
+import { getToolkitRuntime } from "./HeadlessRuntime.js";
+import { authorizeJoin, requestedDedicatedScene } from "./JoinGate.js";
+import { normalizeAddress } from "./NetworkAddresses.js";
+import { KICK_REJOIN_BLOCK_SECONDS, ROOM_TRAFFIC_WINDOW_MS } from "./admin/AdminConstants.js";
+import { toLogEntryView } from "./admin/LogBuffer.js";
+/** Milliseconds between session logic updates, which expire reconnect holds (A9). */
+const SESSION_UPDATE_INTERVAL_MS = 250;
+/** Close code of a refused join; the error message names the TOOLKIT.ShutdownReason. */
+const JOIN_REFUSED_CODE = 4011;
+/** Prefix of the control messages the room forwards to the session logic (D11). */
+const CONTROL_MESSAGE_PREFIX = "fusion:";
+/** HTTP status of a session refused because the process is at a session cap (D14) or its scene failed to load. */
+const SERVICE_UNAVAILABLE_STATUS = 503;
+/** HTTP status of a Client join naming a dedicated scene the server cannot start on demand (D6). */
+const NOT_FOUND_STATUS = 404;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** The game mode name the metrics and the admin listing show before a session's first join. */
+const PENDING_GAME_MODE_NAME = "Pending";
+/** Bytes of one state word in the session logic's stored blocks (the inspector counts words). */
+const STATE_WORD_BYTES = 4;
+/** How many of a room's newest log lines its admin page shows. */
+const ROOM_LOG_LINE_COUNT = 50;
+/** Why Shared-mode inspection may be missing. */
+const NO_STORED_STATE_REASON = "this session keeps no object state on the server (only Shared mode does)";
+/** Why a dedicated session's objects may be missing from the inspector. */
+const DEDICATED_INSPECTION_MISSING_REASON = "the dedicated runner does not list its network objects";
+/**
+ * Settles a reconnection window that closed unused or ended because the room is disposing. Nothing is left to do: the
+ * player's onLeave (or the room's disposal) already cleans up, and an unhandled rejection would crash strict runtimes.
+ */
+function ignoreEndedReconnection() {
+    return;
+}
+/**
+ * Settles a promise whose failure is already reported elsewhere (an on-demand load failure reaches each joiner through
+ * onJoin, and locking a room that is closing has nothing left to do), so it never becomes an unhandled rejection.
+ */
+function ignoreReportedFailure() {
+    return;
+}
+/**
+ * The Colyseus room of one network session ("fusion_session", D10). It hosts TOOLKIT.FusionSessionLogic, the same class
+ * the in-process LoopbackHub runs: the room only carries bytes and control messages between the sockets and the logic.
+ * Client-to-room frames arrive as bytes type FUSION_BYTES_TO_ROOM; room-to-client frames leave as FUSION_BYTES_FROM_ROOM
+ * prefixed with their source player (D11). Unreliable frames travel as WebTransport datagrams (FUSION_UNRELIABLE_TO_ROOM /
+ * FUSION_UNRELIABLE_FROM_ROOM) when the client is on WebTransport, else on the same reliable bytes messages (D7).
+ */
+export class SessionRoom extends Room {
+    /** The runtime's TOOLKIT namespace (Babylon Toolkit Networking). */
+    toolkit;
+    /** The session rules. */
+    logic;
+    /** Seats by client session id, for reconnects. */
+    seats = new Map();
+    /** The headless Server-mode session a dedicated room runs, or null (T13). */
+    dedicatedSession = null;
+    /** True for a room that runs a headless Server-mode runner (DedicatedSession). */
+    hostsDedicatedRunner = false;
+    /** The game server this room belongs to (limits, hooks, metrics). */
+    serverState;
+    /** The session name, for hooks and logs. */
+    sessionName = "";
+    /** The TOOLKIT.GameMode of the joiner that created the session, or null. */
+    creatorGameMode = null;
+    /** Seconds an on-demand room stays open empty, or null for every other room (they never idle-close, D19). */
+    idleSeconds = null;
+    /** The configured scene an on-demand room runs, for logs. */
+    onDemandSceneName = "";
+    /** The scene a dedicated room runs (its configured name, else its scene file), or null for other rooms. */
+    dedicatedSceneName = null;
+    /** Who started this room's dedicated runner (game-server-admin-console T9). */
+    dedicatedStartedBy = "code";
+    /** The pending idle close of an empty on-demand room, or null. */
+    idleTimer = null;
+    /** Settles once an on-demand room's runner has loaded (rejects when it failed), or null for other rooms. */
+    dedicatedRunnerReady = null;
+    /** True once the room was disposed. */
+    isDisposed = false;
+    /** ISO time the room was created. */
+    createdAt = null;
+    /** The last session description the logic published, or null before the first. */
+    lastSessionInfo = null;
+    /** Frame totals since creation (counted whether or not metrics are on). */
+    traffic = { framesIn: 0, framesOut: 0, bytesIn: 0, bytesOut: 0 };
+    /** Start of the current traffic window, in performance.now() milliseconds. */
+    trafficWindowStartedAt = performance.now();
+    /** Total bytes at the start of the current traffic window. */
+    trafficWindowBytes = 0;
+    /** Bytes per second over the last full ROOM_TRAFFIC_WINDOW_MS. */
+    bytesPerSecond = 0;
+    /** Host migrations seen in updateSession (logic.isMigratingHost turning false). */
+    hostMigrationLog = [];
+    /** The host seen while no migration ran, or null. */
+    lastHostPlayerId = null;
+    /** Whether a host migration was running at the last update. */
+    wasMigratingHost = false;
+    /** True when a dedicated Server-mode runner hosts this session. */
+    get isDedicated() {
+        return this.hostsDedicatedRunner;
+    }
+    /** The session's TOOLKIT.GameMode name ("Shared", "Host", "Server", …), or "Pending" before its first join. */
+    get gameModeName() {
+        const gameMode = (this.logic != null) ? this.logic.gameMode : null;
+        if (gameMode == null)
+            return PENDING_GAME_MODE_NAME;
+        return this.toolkit.GameMode[gameMode] ?? String(gameMode);
+    }
+    /** Clients connected to the room now. */
+    get playerCount() {
+        return this.clients.length;
+    }
+    /**
+     * The join gate of sessions (D10): runs at matchmaking, before a seat is reserved.
+     * @param token The bearer token the client sent.
+     * @param options The join request.
+     * @param context Colyseus' matchmaking context.
+     * @returns The identity and client address, stored as client.auth.
+     * @throws ServerError when the gate refuses the join.
+     */
+    static async onAuth(token, options, context) {
+        return authorizeJoin(token, options, context, "session");
+    }
+    /**
+     * Creates the session logic and wires the message handlers. The first join creates the session itself (A10); a room
+     * created with `dedicated` (DedicatedSession.start) runs a headless Server-mode runner first, and stays open while
+     * empty. A Client-mode join naming a configured on-demand scene (NETWORK_DEDICATED_SCENE_PROPERTY) starts that
+     * scene's dedicated runner here, and the room closes once it has been empty for the scene's idleSeconds (D19).
+     * @param options The creation options: a joiner's request, or DedicatedRoomOptions.
+     * @throws ServerError(503, "MaxCcuReached: …") when the process already hosts limits.maxSessions sessions, or
+     *     limits.maxDedicatedSessions dedicated ones.
+     * @throws ServerError(404, "GameNotFound: …") when a Client join names a scene that is not configured for on demand.
+     */
+    async onCreate(options) {
+        const state = getGameServerState();
+        this.serverState = state;
+        this.toolkit = getToolkitRuntime().TOOLKIT;
+        if (state.sessionRooms.size >= state.config.limits.maxSessions)
+            throw new ServerError(SERVICE_UNAVAILABLE_STATUS, "MaxCcuReached: this server is hosting its most sessions");
+        state.sessionRooms.add(this);
+        this.createdAt = new Date().toISOString();
+        this.maxMessagesPerSecond = state.config.limits.maxMessagesPerSecond;
+        this.sessionName = options?.sessionName ?? "";
+        this.creatorGameMode = (typeof options?.gameMode === "number") ? options.gameMode : null;
+        try {
+            const onDemandOptions = this.resolveOnDemandScene(options);
+            if (onDemandOptions != null || options?.dedicated === true)
+                this.checkDedicatedCap();
+            await this.createSession(options, onDemandOptions);
+        }
+        catch (error) {
+            state.sessionRooms.delete(this);
+            throw error;
+        }
+        if (this.idleSeconds != null)
+            this.startIdleTimer();
+        this.callSessionHook("onSessionCreated");
+    }
+    /** Stops a dedicated room's server runner with the room, and leaves the server's live sessions. */
+    async onDispose() {
+        this.isDisposed = true;
+        this.serverState.sessionRooms.delete(this);
+        const dedicatedSession = this.dedicatedSession;
+        this.dedicatedSession = null;
+        if (dedicatedSession != null)
+            await dedicatedSession.stop();
+        this.callSessionHook("onSessionClosed");
+    }
+    /**
+     * Admits a client through the session logic (A10). The requested player count is clamped to the server's cap and the
+     * identity is always the one the gate verified, never a client-sent value (D12, D14). A join of an on-demand room waits
+     * until its dedicated runner has loaded.
+     * @param client The joining client.
+     * @param options Its join request.
+     * @throws ServerError with JOIN_REFUSED_CODE and the ShutdownReason name when the session refuses the join.
+     * @throws ServerError(503, "GameNotFound: …") when the on-demand scene failed to load.
+     */
+    async onJoin(client, options) {
+        if (this.dedicatedRunnerReady != null)
+            await this.dedicatedRunnerReady;
+        // Only a runner restarting after a host migration names the player it resumes; the logic accepts that only for
+        // the players it is waiting for (D31). Other reconnects go through Colyseus reconnection (onReconnect).
+        const reconnectPlayerId = (options != null && options.hostMigration === true) ? options.reconnectPlayerId : 0;
+        const gateResult = client.auth;
+        const identity = gateResult?.identity ?? null;
+        const request = Object.assign({}, options, { reconnectPlayerId: reconnectPlayerId, authIdentity: identity });
+        request.playerCount = this.clampPlayerCount(request.playerCount);
+        const welcome = this.admitCounted(client.sessionId, request);
+        this.idleTimer?.clear();
+        this.idleTimer = null;
+        const seat = {
+            request: Object.assign({}, request, { hostMigration: false }),
+            playerId: welcome.playerId,
+            clientAddress: gateResult?.clientAddress ?? "",
+            transport: transportOf(client),
+            joinedAt: new Date().toISOString()
+        };
+        this.seats.set(client.sessionId, seat);
+        this.refreshAutoDispose();
+        this.serverState.metrics?.countJoin("accepted", null);
+        this.callPlayerHook("onPlayerJoined", welcome.playerId, identity);
+        this.reportPlayerSession("joined", seat);
+    }
+    /**
+     * Ends the session at the end of a drain (D17): every client is told GameClosed (FUSION_CONTROL_SHUTDOWN), then the
+     * room disconnects them with CloseCode.SERVER_SHUTDOWN.
+     */
+    async closeForShutdown() {
+        const payload = { reason: this.toolkit.ShutdownReason.GameClosed };
+        for (const client of this.clients)
+            client.send(this.toolkit.FUSION_CONTROL_SHUTDOWN, payload);
+        await this.disconnect(CloseCode.SERVER_SHUTDOWN);
+    }
+    /**
+     * A client dropped without leaving: the logic holds its slot and the room keeps its seat for the grace period (D8).
+     * Colyseus also calls it for a join that onJoin refused; such a client has no seat and nothing to hold.
+     * @param client The dropped client.
+     */
+    onDrop(client) {
+        if (!this.seats.has(client.sessionId))
+            return;
+        this.logic.drop(client.sessionId);
+        this.refreshAutoDispose();
+        this.allowReconnection(client, this.toolkit.NETWORK_RECONNECT_GRACE_SECONDS).catch(ignoreEndedReconnection);
+    }
+    /**
+     * A dropped client came back within the grace period: it resumes its player id.
+     * @param client The reconnected client.
+     */
+    onReconnect(client) {
+        const seat = this.seats.get(client.sessionId);
+        if (seat == null)
+            return;
+        this.admit(client.sessionId, Object.assign({}, seat.request, { reconnectPlayerId: seat.playerId }));
+    }
+    /**
+     * A client left for good (or its reconnect window closed).
+     * @param client The leaving client.
+     */
+    onLeave(client) {
+        const seat = this.seats.get(client.sessionId);
+        this.seats.delete(client.sessionId);
+        this.logic.leave(client.sessionId);
+        this.refreshAutoDispose();
+        if (seat != null)
+            this.callPlayerHook("onPlayerLeft", seat.playerId, seat.request.authIdentity ?? null);
+        if (seat != null)
+            this.reportPlayerSession("left", seat);
+        if (this.idleSeconds != null && this.clients.length === 0)
+            this.startIdleTimer();
+    }
+    /**
+     * This session as a row of the admin session list (game-server-admin-console R18).
+     * @returns The row.
+     */
+    adminSummary() {
+        return {
+            roomId: this.roomId,
+            sessionName: this.sessionName,
+            gameMode: this.gameModeName,
+            players: this.clients.length,
+            maxPlayers: this.maxClients,
+            processId: matchMaker.processId,
+            publicAddress: this.serverState.config.publicAddress,
+            createdAt: this.createdAt,
+            dedicatedScene: this.dedicatedSceneName,
+            hostPlayerId: this.currentHostPlayerId(),
+            isOpen: this.lastSessionInfo?.isOpen ?? true,
+            isVisible: this.lastSessionInfo?.isVisible ?? true,
+            locked: this.locked,
+            bytesPerSecond: this.bytesPerSecond
+        };
+    }
+    /**
+     * This session with its players for the admin session page (DR §6.6).
+     * @param includeAddresses False hides each player's address (callers without players.viewAddresses).
+     * @returns The session page.
+     */
+    adminDescribe(includeAddresses) {
+        const firstSeat = this.seats.values().next().value;
+        return Object.assign(this.adminSummary(), {
+            properties: Object.assign({}, this.lastSessionInfo?.properties ?? {}),
+            tickRate: firstSeat?.request.tickRate ?? null,
+            playerList: this.describePlayers(includeAddresses),
+            traffic: Object.assign({}, this.traffic),
+            dedicated: this.describeDedicated(),
+            hostMigrations: this.hostMigrationLog.slice(),
+            logLines: this.recentLogLines(includeAddresses)
+        });
+    }
+    /**
+     * The verified Discord players of this session (discord-sign-in D17): each seat whose identity is one of this
+     * server's Discord sessions. Typed names and other auth identities are left out.
+     * @returns The players, by player id.
+     */
+    discordPlayers() {
+        const players = [];
+        for (const seat of this.seats.values()) {
+            const identity = seat.request.authIdentity ?? null;
+            if (identity == null || identity.userId == null || identity.claims.iss !== DISCORD_SESSION_ISSUER)
+                continue;
+            const avatarClaim = identity.claims.avatar;
+            players.push({ playerId: seat.playerId, userId: identity.userId, displayName: displayNameOf(identity) ?? "", avatar: (typeof avatarClaim === "string") ? avatarClaim : null });
+        }
+        return players.sort((left, right) => left.playerId - right.playerId);
+    }
+    /**
+     * The session's network objects (the inspector, spec 4): a dedicated runner's objects, or the object state a
+     * Shared-mode session stores for late joiners.
+     * @returns The objects, or available false with the reason.
+     */
+    adminInspect() {
+        if (this.dedicatedSession != null)
+            return inspectDedicatedObjects(this.dedicatedSession.runner.getAllNetworkObjects?.() ?? null);
+        const storedObjects = this.logic.sharedObjects;
+        if (storedObjects == null || this.logic.gameMode !== this.toolkit.GameMode.Shared)
+            return { available: false, reason: NO_STORED_STATE_REASON, objects: [] };
+        return { available: true, reason: null, objects: Array.from(storedObjects.values()).map(describeSharedObject) };
+    }
+    /**
+     * Kicks a player (D12): it is told DisconnectedByPluginLogic with the admin's message, refused a fresh join to this
+     * session for KICK_REJOIN_BLOCK_SECONDS unless allowRejoin, and disconnected with CloseCode.CONSENTED, so no
+     * reconnect seat is held.
+     * @param playerId The player.
+     * @param message Shown to the player.
+     * @param allowRejoin True to let the player join again at once.
+     * @returns False when no connected player has that id.
+     */
+    async adminKickPlayer(playerId, message, allowRejoin) {
+        const sessionId = this.sessionIdOfPlayer(playerId);
+        const client = (sessionId != null) ? this.clients.getById(sessionId) : undefined;
+        const seat = (sessionId != null) ? this.seats.get(sessionId) : undefined;
+        if (client == null || seat == null)
+            return false;
+        client.send(this.toolkit.FUSION_CONTROL_SHUTDOWN, { reason: this.toolkit.ShutdownReason.DisconnectedByPluginLogic, message: message });
+        if (!allowRejoin)
+            await this.blockRejoin(seat);
+        client.leave(CloseCode.CONSENTED);
+        return true;
+    }
+    /**
+     * Closes the session from the console (D12): every player is told GameClosed with the admin's message, then the room
+     * disconnects them with CloseCode.SERVER_SHUTDOWN.
+     * @param message Shown to the players.
+     */
+    async adminClose(message) {
+        const payload = { reason: this.toolkit.ShutdownReason.GameClosed, message: message };
+        for (const client of this.clients)
+            client.send(this.toolkit.FUSION_CONTROL_SHUTDOWN, payload);
+        await this.disconnect(CloseCode.SERVER_SHUTDOWN);
+    }
+    /**
+     * Locks or unlocks the session against new joins from the console.
+     * @param locked True to lock.
+     */
+    async adminSetLocked(locked) {
+        if (locked)
+            await this.lock();
+        else
+            await this.unlock();
+    }
+    /**
+     * Sends a notice to one player or to everyone (FUSION_CONTROL_NOTICE, D13).
+     * @param notice The notice.
+     * @param playerId The player, or 0 for everyone.
+     * @returns How many connected players were targeted.
+     */
+    adminSendNotice(notice, playerId) {
+        this.logic.sendControlFromServer(this.toolkit.FUSION_CONTROL_NOTICE, notice, playerId);
+        const connected = this.logic.players.filter((player) => player.connected);
+        if (playerId === 0)
+            return connected.length;
+        return connected.some((player) => player.playerId === playerId) ? 1 : 0;
+    }
+    /**
+     * Stops a dedicated session from the console (D23, R17): every player is told GameClosed with the admin's message,
+     * and the room disconnects on the next turn of the event loop, so this call's reply reaches the caller first.
+     * onDispose then stops the runner. Nothing restarts it by itself, boot sessions included (DR §9).
+     * @param message Shown to the players.
+     * @returns What a restart needs, or null when this room runs no dedicated runner (nothing is stopped).
+     */
+    adminStopDedicated(message) {
+        if (!this.hostsDedicatedRunner || this.dedicatedSceneName == null)
+            return null;
+        const payload = { reason: this.toolkit.ShutdownReason.GameClosed, message: message };
+        for (const client of this.clients)
+            client.send(this.toolkit.FUSION_CONTROL_SHUTDOWN, payload);
+        setImmediate(() => {
+            this.disconnect(CloseCode.SERVER_SHUTDOWN).catch((error) => getLogger().warn("a stopped dedicated session did not close cleanly", { roomId: this.roomId, error: String(error) }));
+        });
+        return { sceneName: this.dedicatedSceneName, sessionName: this.sessionName, processId: matchMaker.processId };
+    }
+    /**
+     * Disconnects the playing clients a new ban matches (D15): each is told ConnectionRefused with the message.
+     * @param userIds Banned user ids.
+     * @param addresses Banned addresses (concrete addresses of this room's clients; ranges are resolved by the caller).
+     * @param message Shown to the players.
+     * @returns How many clients were disconnected.
+     */
+    adminDisconnectBanned(userIds, addresses, message) {
+        const bannedAddresses = new Set(addresses.map(normalizeAddress));
+        let disconnected = 0;
+        for (const client of Array.from(this.clients)) {
+            const seat = this.seats.get(client.sessionId);
+            if (seat == null)
+                continue;
+            const userId = seat.request.authIdentity?.userId ?? null;
+            const isBanned = (userId != null && userIds.includes(userId)) || bannedAddresses.has(normalizeAddress(seat.clientAddress));
+            if (!isBanned)
+                continue;
+            client.send(this.toolkit.FUSION_CONTROL_SHUTDOWN, { reason: this.toolkit.ShutdownReason.ConnectionRefused, message: message });
+            client.leave(CloseCode.CONSENTED);
+            disconnected += 1;
+        }
+        return disconnected;
+    }
+    /**
+     * Builds the session logic and its message handlers. A room created by DedicatedSession.start loads its headless
+     * runner before it is listed; an on-demand room starts loading and is listed at once, so concurrent joinOrCreate
+     * calls for the same session find this room instead of starting a second runner (Colyseus waits only about half a
+     * second for a concurrent create, less than a scene takes to load). Its joins wait for the runner in onJoin.
+     * @param options The creation options: a joiner's request, or DedicatedRoomOptions.
+     * @param onDemandOptions The runner options of an on-demand scene, or null.
+     */
+    async createSession(options, onDemandOptions) {
+        this.logic = new this.toolkit.FusionSessionLogic(this.createOutputs());
+        this.clock.setInterval(() => this.updateSession(), SESSION_UPDATE_INTERVAL_MS);
+        this.onMessageBytes(this.toolkit.FUSION_BYTES_TO_ROOM, (client, bytes) => this.receiveFrame(client, bytes, this.toolkit.RpcChannel.Reliable));
+        this.onMessage(this.toolkit.FUSION_UNRELIABLE_TO_ROOM, (client, payload) => {
+            if (payload instanceof Uint8Array)
+                this.receiveFrame(client, payload, this.toolkit.RpcChannel.Unreliable);
+        });
+        this.onMessage("*", (client, type, payload) => this.receiveControl(client, type, payload));
+        if (onDemandOptions != null) {
+            this.rememberDedicatedScene(onDemandOptions);
+            this.hostsDedicatedRunner = true;
+            this.autoDispose = false;
+            this.dedicatedRunnerReady = this.loadOnDemandRunner(onDemandOptions);
+            // A failed load is reported to each joiner by onJoin; this handler only keeps it from being unhandled.
+            this.dedicatedRunnerReady.catch(ignoreReportedFailure);
+            return;
+        }
+        if (options == null || options.dedicated !== true)
+            return;
+        this.rememberDedicatedScene(options);
+        this.hostsDedicatedRunner = true;
+        this.autoDispose = false;
+        this.dedicatedSession = await DedicatedSession.attach(this.logic, options);
+    }
+    /**
+     * Loads an on-demand room's headless runner. A scene that fails to load is logged with its cause, the room is locked
+     * (a later join creates a fresh room and tries again) and it closes after its idle time (§Error policy).
+     * @param options The runner options from the registry.
+     * @throws ServerError(503, "GameNotFound: the dedicated scene <name> failed to load").
+     */
+    async loadOnDemandRunner(options) {
+        let dedicatedSession;
+        try {
+            dedicatedSession = await DedicatedSession.attach(this.logic, options);
+        }
+        catch (error) {
+            getLogger().error("the dedicated scene " + this.onDemandSceneName + " failed to load", { sessionName: this.sessionName, roomId: this.roomId, error: String(error) });
+            this.lock().catch(ignoreReportedFailure);
+            throw new ServerError(SERVICE_UNAVAILABLE_STATUS, "GameNotFound: the dedicated scene " + this.onDemandSceneName + " failed to load");
+        }
+        // The room may have closed while the scene loaded (every joiner left and the idle time passed).
+        if (this.isDisposed)
+            await dedicatedSession.stop();
+        else
+            this.dedicatedSession = dedicatedSession;
+    }
+    /**
+     * The dedicated room options of a Client-mode join that names an on-demand scene (D19), built from the registry entry,
+     * never from client-sent locations.
+     * @param options The creation options.
+     * @returns The options, or null when the join names no dedicated scene.
+     * @throws ServerError(404, "GameNotFound: …") when the scene is not configured, or not for on demand.
+     */
+    resolveOnDemandScene(options) {
+        if (options == null || options.dedicated === true)
+            return null;
+        const sceneName = requestedDedicatedScene(options);
+        if (sceneName == null)
+            return null;
+        const scene = this.serverState.registry.find(sceneName);
+        if (scene == null || !scene.onDemand)
+            throw new ServerError(NOT_FOUND_STATUS, "GameNotFound: no on-demand dedicated scene named " + sceneName);
+        this.onDemandSceneName = sceneName;
+        this.idleSeconds = scene.idleSeconds;
+        this.creatorGameMode = this.toolkit.GameMode.Server;
+        return {
+            sessionName: this.sessionName,
+            sceneRootUrl: scene.sceneRootUrl,
+            sceneFile: scene.sceneFile,
+            projectScripts: scene.projectScripts,
+            playerCount: scene.maxPlayers,
+            sceneName: sceneName,
+            startedBy: "onDemand",
+            gameMode: this.toolkit.GameMode.Server,
+            dedicated: true
+        };
+    }
+    /**
+     * The newest buffered log lines of this room for its admin page (R18).
+     * @param includeAddresses False removes client addresses (callers without players.viewAddresses).
+     * @returns The lines, oldest first (none while the console is off).
+     */
+    recentLogLines(includeAddresses) {
+        const entries = this.serverState.logBuffer?.read({ roomId: this.roomId }, 0, ROOM_LOG_LINE_COUNT) ?? [];
+        return entries.map((entry) => toLogEntryView(entry, matchMaker.processId, includeAddresses));
+    }
+    /**
+     * Keeps a dedicated room's scene and starter for the console.
+     * @param options The dedicated room options.
+     */
+    rememberDedicatedScene(options) {
+        this.dedicatedSceneName = options.sceneName ?? options.sceneFile;
+        this.dedicatedStartedBy = options.startedBy ?? "code";
+    }
+    /**
+     * The dedicated part of the session page (D23): the scene, who started it and the frame history (empty while an
+     * on-demand runner still loads).
+     * @returns The part, or null for a session without a dedicated runner.
+     */
+    describeDedicated() {
+        if (this.dedicatedSceneName == null)
+            return null;
+        const frameStatistics = this.dedicatedSession?.statistics.buckets() ?? [];
+        return { sceneName: this.dedicatedSceneName, startedBy: this.dedicatedStartedBy, frameStatistics: frameStatistics };
+    }
+    /**
+     * Refuses another dedicated room once the process runs limits.maxDedicatedSessions of them (D14). This room is
+     * already in the live set, so only the others count.
+     * @throws ServerError(503, "MaxCcuReached: …").
+     */
+    checkDedicatedCap() {
+        const otherDedicatedRooms = Array.from(this.serverState.sessionRooms).filter((room) => room !== this && room.isDedicated).length;
+        if (otherDedicatedRooms < this.serverState.config.limits.maxDedicatedSessions)
+            return;
+        throw new ServerError(SERVICE_UNAVAILABLE_STATUS, "MaxCcuReached: this server is running its most dedicated sessions");
+    }
+    /**
+     * Closes an on-demand room after idleSeconds without clients (D19); a join before then cancels it (onJoin).
+     */
+    startIdleTimer() {
+        this.idleTimer?.clear();
+        const idleMilliseconds = (this.idleSeconds ?? 0) * MILLISECONDS_PER_SECOND;
+        this.idleTimer = this.clock.setTimeout(() => {
+            if (this.clients.length === 0)
+                void this.disconnect();
+        }, idleMilliseconds);
+    }
+    /**
+     * Expires reconnect holds (A9). A room kept open for a host migration that ended with nobody left (the elected host
+     * never came back) closes.
+     */
+    updateSession() {
+        this.logic.update(performance.now());
+        this.sampleTraffic();
+        this.watchHostMigration();
+        const wasKeptOpen = !this.autoDispose && !this.hostsDedicatedRunner;
+        this.refreshAutoDispose();
+        if (wasKeptOpen && this.autoDispose && this.clients.length === 0)
+            void this.disconnect();
+    }
+    /**
+     * Keeps the room open while a host migration waits for the restarted runners (they all leave and rejoin, D31); a
+     * dedicated room never closes by itself.
+     */
+    refreshAutoDispose() {
+        this.autoDispose = !this.hostsDedicatedRunner && !this.logic.isMigratingHost;
+    }
+    /**
+     * Joins a client to the session logic, turning a refusal into a join error the client's join call rejects with.
+     * @param sessionId The client's session id.
+     * @param request The join request.
+     * @returns The welcome (the logic has already sent it to the client).
+     * @throws ServerError with JOIN_REFUSED_CODE and the ShutdownReason name.
+     */
+    admit(sessionId, request) {
+        try {
+            return this.logic.join(sessionId, request);
+        }
+        catch (error) {
+            const reasonName = (error instanceof Error) ? error.message : String(error);
+            throw new ServerError(JOIN_REFUSED_CODE, reasonName);
+        }
+    }
+    /**
+     * Joins a new client to the session logic, counting a refusal in the metrics by its ShutdownReason name.
+     * @param sessionId The client's session id.
+     * @param request The join request.
+     * @returns The welcome.
+     * @throws ServerError with JOIN_REFUSED_CODE and the ShutdownReason name.
+     */
+    admitCounted(sessionId, request) {
+        try {
+            return this.admit(sessionId, request);
+        }
+        catch (error) {
+            const reasonName = (error instanceof Error) ? error.message : String(error);
+            this.serverState.metrics?.countJoin("refused", reasonName);
+            throw error;
+        }
+    }
+    /**
+     * Forwards a client's session control message (fusion:*) to the session logic; other message types are ignored.
+     * @param client The sending client.
+     * @param type The message type.
+     * @param payload The payload.
+     */
+    receiveControl(client, type, payload) {
+        if (typeof type !== "string" || !type.startsWith(CONTROL_MESSAGE_PREFIX))
+            return;
+        this.serverState.metrics?.countMessage?.("in");
+        this.logic.receiveControl(client.sessionId, type, payload);
+    }
+    /**
+     * The session logic's outputs, bound to this room's clients and listing.
+     * @returns The outputs.
+     */
+    createOutputs() {
+        return {
+            sendFrame: (clientKey, sourcePlayerId, frame, channel) => this.sendFrameTo(clientKey, sourcePlayerId, frame, channel),
+            sendControl: (clientKey, name, payload) => this.sendControlTo(clientKey, name, payload),
+            setSessionMetadata: (session) => this.publishSession(session),
+            lockSession: (locked) => this.setLocked(locked),
+            nowMilliseconds: () => performance.now()
+        };
+    }
+    /**
+     * Passes a client's frame to the session logic on the channel it arrived on (D7), counting it.
+     * @param client The sending client.
+     * @param payload The envelope (route byte + uint16 target + frame).
+     * @param channel The TOOLKIT.RpcChannel it arrived on.
+     */
+    receiveFrame(client, payload, channel) {
+        this.countFrame("in", client, channel, payload.byteLength);
+        this.serverState.metrics?.countMessage?.("in");
+        this.logic.receiveFrame(client.sessionId, payload, channel);
+    }
+    /**
+     * Sends a frame to one client, prefixed with its source player (D11). An Unreliable frame goes as a WebTransport
+     * datagram when the client has one and the prefixed frame fits NETWORK_MAX_UNRELIABLE_FRAME_BYTES; every other frame
+     * uses the reliable bytes message (D7).
+     * @param clientKey The receiving client's session id.
+     * @param sourcePlayerId The sending player.
+     * @param frame The frame.
+     * @param channel The TOOLKIT.RpcChannel the frame was sent on (default Reliable).
+     */
+    sendFrameTo(clientKey, sourcePlayerId, frame, channel = this.toolkit.RpcChannel.Reliable) {
+        const client = this.clients.getById(clientKey);
+        if (client == null)
+            return;
+        const prefixed = this.toolkit.NetworkProtocol.prefixSource(sourcePlayerId, frame);
+        const sendsAsDatagram = channel === this.toolkit.RpcChannel.Unreliable && client.rawUnreliable != null && prefixed.byteLength <= this.toolkit.NETWORK_MAX_UNRELIABLE_FRAME_BYTES;
+        this.countFrame("out", client, sendsAsDatagram ? channel : this.toolkit.RpcChannel.Reliable, prefixed.byteLength);
+        this.serverState.metrics?.countMessage?.("out");
+        if (sendsAsDatagram && client.rawUnreliable != null) {
+            client.rawUnreliable(getMessageBytes.raw(Protocol.ROOM_DATA, this.toolkit.FUSION_UNRELIABLE_FROM_ROOM, prefixed));
+            return;
+        }
+        client.sendBytes(this.toolkit.FUSION_BYTES_FROM_ROOM, prefixed);
+    }
+    /**
+     * Counts one frame in the server metrics, when they are on (D16).
+     * @param direction "in" from the client, "out" to it.
+     * @param client The client.
+     * @param channel The TOOLKIT.RpcChannel it travels on.
+     * @param byteLength The frame size in bytes.
+     */
+    countFrame(direction, client, channel, byteLength) {
+        if (direction === "in") {
+            this.traffic.framesIn += 1;
+            this.traffic.bytesIn += byteLength;
+        }
+        else {
+            this.traffic.framesOut += 1;
+            this.traffic.bytesOut += byteLength;
+        }
+        const metrics = this.serverState.metrics;
+        if (metrics == null)
+            return;
+        const transportName = transportOf(client);
+        const channelName = (channel === this.toolkit.RpcChannel.Unreliable) ? "unreliable" : "reliable";
+        metrics.countFrame(direction, transportName, channelName, byteLength);
+    }
+    /**
+     * Sends a control message to one client.
+     * @param clientKey The receiving client's session id.
+     * @param name The control message name.
+     * @param payload The payload.
+     */
+    sendControlTo(clientKey, name, payload) {
+        const client = this.clients.getById(clientKey);
+        if (client == null)
+            return;
+        this.serverState.metrics?.countMessage?.("out");
+        client.send(name, payload);
+    }
+    /**
+     * Publishes the session description to the lobby listing: metadata, visibility and capacity in one update. The
+     * metadata keeps the sessionName filter value: Colyseus matches filterBy fields against the listing's metadata, which
+     * setMatchmaking replaces rather than merges.
+     * @param session The description.
+     */
+    publishSession(session) {
+        this.lastSessionInfo = session;
+        const metadata = Object.assign({}, session, { sessionName: session.name, gameMode: this.gameModeName, isDedicated: this.hostsDedicatedRunner });
+        this.setMatchmaking({ metadata: metadata, unlisted: !session.isVisible, maxClients: session.maxPlayers }).catch((error) => getLogger().error("session listing update failed", { roomId: this.roomId, sessionName: this.sessionName, error: String(error) }));
+    }
+    /**
+     * Locks or unlocks the room against new joins (full or closed sessions).
+     * @param locked True to lock.
+     */
+    setLocked(locked) {
+        const change = locked ? this.lock() : this.unlock();
+        change.catch((error) => getLogger().error("session lock update failed", { roomId: this.roomId, sessionName: this.sessionName, error: String(error) }));
+    }
+    /**
+     * Clamps a requested player count to limits.maxPlayersPerSession (D14).
+     * @param requestedPlayerCount The count the joiner asked for.
+     * @returns The count the session may use.
+     */
+    clampPlayerCount(requestedPlayerCount) {
+        const maxPlayers = this.serverState.config.limits.maxPlayersPerSession;
+        if (requestedPlayerCount <= maxPlayers)
+            return requestedPlayerCount;
+        getLogger().debug("player count clamped", { sessionName: this.sessionName, roomId: this.roomId, requested: requestedPlayerCount, maxPlayers: maxPlayers });
+        return maxPlayers;
+    }
+    /**
+     * Measures the room's byte rate once per ROOM_TRAFFIC_WINDOW_MS (R18).
+     */
+    sampleTraffic() {
+        const now = performance.now();
+        const elapsedMilliseconds = now - this.trafficWindowStartedAt;
+        if (elapsedMilliseconds < ROOM_TRAFFIC_WINDOW_MS)
+            return;
+        const totalBytes = this.traffic.bytesIn + this.traffic.bytesOut;
+        this.bytesPerSecond = (totalBytes - this.trafficWindowBytes) / (elapsedMilliseconds / MILLISECONDS_PER_SECOND);
+        this.trafficWindowStartedAt = now;
+        this.trafficWindowBytes = totalBytes;
+    }
+    /**
+     * Records a host migration when logic.isMigratingHost turns false with a different host than before (R18).
+     */
+    watchHostMigration() {
+        const isMigrating = this.logic.isMigratingHost;
+        const hostPlayerId = this.currentHostPlayerId();
+        const migrationEnded = this.wasMigratingHost && !isMigrating;
+        if (migrationEnded && hostPlayerId != null && this.lastHostPlayerId != null && hostPlayerId !== this.lastHostPlayerId) {
+            this.hostMigrationLog.push({ at: new Date().toISOString(), fromPlayerId: this.lastHostPlayerId, toPlayerId: hostPlayerId });
+        }
+        this.wasMigratingHost = isMigrating;
+        if (!isMigrating && hostPlayerId != null)
+            this.lastHostPlayerId = hostPlayerId;
+    }
+    /**
+     * The Host-mode host's player id.
+     * @returns The id, or null when no player is the host.
+     */
+    currentHostPlayerId() {
+        if (this.logic == null)
+            return null;
+        const host = this.logic.players.find((player) => player.isHost);
+        return host?.playerId ?? null;
+    }
+    /**
+     * The client session id of a player.
+     * @param playerId The player.
+     * @returns The session id, or null when no seat has that player.
+     */
+    sessionIdOfPlayer(playerId) {
+        for (const [sessionId, seat] of this.seats)
+            if (seat.playerId === playerId)
+                return sessionId;
+        return null;
+    }
+    /**
+     * The players of the session page, from the seats and the logic's player list.
+     * @param includeAddresses False hides the addresses.
+     * @returns The players, by player id.
+     */
+    describePlayers(includeAddresses) {
+        const logicPlayers = this.logic.players;
+        const masterClientPlayerId = this.logic.masterClientPlayerId;
+        const players = [];
+        for (const [sessionId, seat] of this.seats) {
+            const logicPlayer = logicPlayers.find((player) => player.clientKey === sessionId);
+            const identity = seat.request.authIdentity ?? null;
+            players.push({
+                playerId: seat.playerId,
+                userId: identity?.userId ?? null,
+                displayName: displayNameOf(identity),
+                clientAddress: includeAddresses ? seat.clientAddress : null,
+                transport: seat.transport,
+                joinedAt: seat.joinedAt,
+                connected: logicPlayer?.connected ?? false,
+                isHost: logicPlayer?.isHost ?? false,
+                isMasterClient: seat.playerId === masterClientPlayerId
+            });
+        }
+        return players.sort((left, right) => left.playerId - right.playerId);
+    }
+    /**
+     * Refuses a kicked player's fresh joins to this session (R19); a presence failure is logged and the kick goes on.
+     * @param seat The kicked player's seat.
+     */
+    async blockRejoin(seat) {
+        const userId = seat.request.authIdentity?.userId ?? null;
+        try {
+            await this.serverState.kickBlocks.block(this.sessionName, { userId: userId, clientAddress: seat.clientAddress }, KICK_REJOIN_BLOCK_SECONDS);
+        }
+        catch (error) {
+            getLogger().warn("the kick block could not be stored", { sessionName: this.sessionName, roomId: this.roomId, error: String(error) });
+        }
+    }
+    /**
+     * Tells the admin console and the leaderboard service a player joined or left (player history and session presence,
+     * game-server-leaderboards D10).
+     * @param kind "joined" or "left".
+     * @param seat The player's seat.
+     */
+    reportPlayerSession(kind, seat) {
+        const userId = seat.request.authIdentity?.userId ?? null;
+        getLogger().info("player " + kind, { roomId: this.roomId, sessionName: this.sessionName, playerId: seat.playerId, userId: userId, clientAddress: seat.clientAddress });
+        const event = { kind: kind, roomId: this.roomId, sessionName: this.sessionName, processId: matchMaker.processId, playerId: seat.playerId, userId: userId, clientAddress: seat.clientAddress, at: new Date().toISOString() };
+        this.serverState.onPlayerSessionEvent?.(event);
+        this.serverState.onLeaderboardSessionPresence?.(event);
+    }
+    /**
+     * This session's description for the hooks.
+     * @returns The event.
+     */
+    sessionEvent() {
+        return { roomId: this.roomId, sessionName: this.sessionName, gameMode: this.creatorGameMode, isDedicated: this.hostsDedicatedRunner };
+    }
+    /**
+     * Calls a session hook, if the server has it.
+     * @param hookName The hook.
+     */
+    callSessionHook(hookName) {
+        const event = this.sessionEvent();
+        this.callHook(hookName, (hooks) => hooks[hookName]?.(event));
+    }
+    /**
+     * Calls a player hook, if the server has it.
+     * @param hookName The hook.
+     * @param playerId The player.
+     * @param identity The player's verified identity, or null.
+     */
+    callPlayerHook(hookName, playerId, identity) {
+        const event = Object.assign(this.sessionEvent(), { playerId: playerId, identity: identity });
+        this.callHook(hookName, (hooks) => hooks[hookName]?.(event));
+    }
+    /**
+     * Runs a hook call; a hook that throws is logged with its name and the session carries on (§Error policy).
+     * @param hookName The hook, for the log.
+     * @param invoke Calls the hook on the server's hooks.
+     */
+    callHook(hookName, invoke) {
+        try {
+            invoke(this.serverState.hooks);
+        }
+        catch (error) {
+            getLogger().error("hook " + hookName + " threw", { sessionName: this.sessionName, roomId: this.roomId, error: String(error) });
+        }
+    }
+}
+/**
+ * How a client is connected.
+ * @param client The client.
+ * @returns "webtransport" when it has a datagram channel, else "websocket".
+ */
+function transportOf(client) {
+    return (client.rawUnreliable != null) ? "webtransport" : "websocket";
+}
+/**
+ * A player's display name from its verified claims: name, else preferred_username.
+ * @param identity The verified identity, or null.
+ * @returns The name, or null.
+ */
+function displayNameOf(identity) {
+    const claims = identity?.claims ?? {};
+    const name = claims.name ?? claims.preferred_username;
+    return (typeof name === "string") ? name : null;
+}
+/**
+ * The inspector rows of a dedicated runner's network objects.
+ * @param objects The runner's objects, or null when the runner cannot list them.
+ * @returns The inspector view.
+ */
+function inspectDedicatedObjects(objects) {
+    if (objects == null)
+        return { available: false, reason: DEDICATED_INSPECTION_MISSING_REASON, objects: [] };
+    return {
+        available: true,
+        reason: null,
+        objects: objects.map((networkObject) => ({
+            networkId: String(networkObject.id),
+            kind: (networkObject.prefabGuid !== "") ? "prefab" : "scene",
+            name: networkObject.name,
+            stateAuthorityPlayerId: (networkObject.stateAuthority.playerId > 0) ? networkObject.stateAuthority.playerId : null,
+            lastChangedTick: null,
+            stateWordCount: networkObject.stateBuffer?.wordCount ?? 0
+        }))
+    };
+}
+/**
+ * The inspector row of one object a Shared-mode session stores.
+ * @param stored The stored object.
+ * @returns The row.
+ */
+function describeSharedObject(stored) {
+    const isPrefab = stored.spawnHeader.prefabId > 0;
+    return {
+        networkId: String(stored.spawnHeader.networkId),
+        kind: isPrefab ? "prefab" : "scene",
+        name: isPrefab ? "prefab " + stored.spawnHeader.prefabId : "scene object " + stored.spawnHeader.networkId,
+        stateAuthorityPlayerId: (stored.authorityPlayerId > 0) ? stored.authorityPlayerId : null,
+        lastChangedTick: stored.senderTick,
+        stateWordCount: Math.ceil(stored.deltaBytes.byteLength / STATE_WORD_BYTES)
+    };
+}