@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/ServerInit.d.ts

@@ -0,0 +1,28 @@
+/** What `writeRecipes` did with each file of the starter folder. */
+export interface InitResult {
+    /** Absolute paths of the files written. */
+    written: string[];
+    /** Absolute paths of the files left alone because they already existed (no `force`). */
+    skipped: string[];
+}
+/**
+ * The version of this package (the banner, and the image tag the recipes pin).
+ * @returns The version from package.json.
+ */
+export declare function readPackageVersion(): string;
+/**
+ * Writes the starter folder of `babylon-game-server init`: every file under `templates/init/` (relative paths kept,
+ * except the renames in TEMPLATE_FILE_NAMES, and `{{version}}` replaced with the package version) plus a `.env.example`
+ * generated from CONFIG_OPTIONS (D3, D27).
+ * TLS, UDP and auth are disabled in everything it writes (D2).
+ * @param targetFolder The folder to write into (created when missing).
+ * @param force True to overwrite files that already exist; otherwise they are skipped.
+ * @returns The files written and the files skipped, as absolute paths.
+ */
+export declare function writeRecipes(targetFolder: string, force: boolean): Promise<InitResult>;
+/**
+ * The text of `.env.example`: one `# <description>` line and one `GAME_SERVER_<…>=<default>` line per option. Secrets
+ * and unset (null) options are left empty, so nothing secret or misleading is ever suggested.
+ * @returns The file text.
+ */
+export declare function buildEnvironmentExample(): string;

package/lib/ServerInit.js

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_OPTIONS, DEFAULT_GAME_SERVER_CONFIG, readPath } from "./GameServerConfig.js";
+/** The recipe templates shipped with the package (`templates/init/`, D27). */
+const TEMPLATE_FOLDER = fileURLToPath(new URL("../templates/init/", import.meta.url));
+/** The package manifest, read for the version stamped into the recipes. */
+const PACKAGE_MANIFEST_URL = new URL("../package.json", import.meta.url);
+/** The placeholder every template uses for the package (and image) version. */
+const VERSION_PLACEHOLDER = /\{\{version\}\}/g;
+/** The generated environment file name. */
+const ENVIRONMENT_EXAMPLE_FILE = ".env.example";
+/** Separator of list values in an environment variable. */
+const LIST_SEPARATOR = ",";
+/**
+ * Templates written under another name, keyed by their path under `templates/init/`. npm drops a real `.gitignore`
+ * from a published package, so that template ships as `gitignore`.
+ */
+const TEMPLATE_FILE_NAMES = new Map([
+    [path.join("colyseus-cloud", "gitignore"), path.join("colyseus-cloud", ".gitignore")]
+]);
+/**
+ * The version of this package (the banner, and the image tag the recipes pin).
+ * @returns The version from package.json.
+ */
+export function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(PACKAGE_MANIFEST_URL, "utf8"));
+    return packageJson.version;
+}
+/**
+ * Writes the starter folder of `babylon-game-server init`: every file under `templates/init/` (relative paths kept,
+ * except the renames in TEMPLATE_FILE_NAMES, and `{{version}}` replaced with the package version) plus a `.env.example`
+ * generated from CONFIG_OPTIONS (D3, D27).
+ * TLS, UDP and auth are disabled in everything it writes (D2).
+ * @param targetFolder The folder to write into (created when missing).
+ * @param force True to overwrite files that already exist; otherwise they are skipped.
+ * @returns The files written and the files skipped, as absolute paths.
+ */
+export async function writeRecipes(targetFolder, force) {
+    const result = { written: [], skipped: [] };
+    const absoluteTarget = path.resolve(targetFolder);
+    const version = readPackageVersion();
+    const templatePaths = await listTemplateFiles(TEMPLATE_FOLDER);
+    for (const relativePath of templatePaths) {
+        const templateText = readFileSync(path.join(TEMPLATE_FOLDER, relativePath), "utf8");
+        const writtenPath = TEMPLATE_FILE_NAMES.get(relativePath) ?? relativePath;
+        await writeRecipeFile(path.join(absoluteTarget, writtenPath), templateText.replace(VERSION_PLACEHOLDER, version), force, result);
+    }
+    await writeRecipeFile(path.join(absoluteTarget, ENVIRONMENT_EXAMPLE_FILE), buildEnvironmentExample(), force, result);
+    return result;
+}
+/**
+ * The text of `.env.example`: one `# <description>` line and one `GAME_SERVER_<…>=<default>` line per option. Secrets
+ * and unset (null) options are left empty, so nothing secret or misleading is ever suggested.
+ * @returns The file text.
+ */
+export function buildEnvironmentExample() {
+    const lines = [
+        "# Babylon Game Server environment variables (every option; generated from CONFIG_OPTIONS).",
+        "# Precedence: defaults < Colyseus Cloud's defaults (on that host only) < config file < environment < command-line flags. Unset variables keep the default.",
+        ""
+    ];
+    for (const definition of CONFIG_OPTIONS) {
+        lines.push("# " + definition.description);
+        lines.push(definition.environmentVariable + "=" + exampleValue(definition));
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * The value `.env.example` shows for an option: its default, or empty for secrets and nulls.
+ * @param definition The option.
+ * @returns The text after `=`.
+ */
+function exampleValue(definition) {
+    if (definition.isSecret)
+        return "";
+    const defaultValue = readPath(DEFAULT_GAME_SERVER_CONFIG, definition.path);
+    if (defaultValue == null)
+        return "";
+    if (Array.isArray(defaultValue))
+        return defaultValue.join(LIST_SEPARATOR);
+    return String(defaultValue);
+}
+/**
+ * Writes one recipe file, or records it as skipped when it exists and `force` is off.
+ * @param filePath Absolute path of the file.
+ * @param text The file text.
+ * @param force True to overwrite an existing file.
+ * @param result The result the file is recorded in.
+ */
+async function writeRecipeFile(filePath, text, force, result) {
+    if (existsSync(filePath) && !force) {
+        result.skipped.push(filePath);
+        return;
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, text);
+    result.written.push(filePath);
+}
+/**
+ * Lists every file under a folder, as paths relative to it, sorted so the output order is stable.
+ * @param folder The folder.
+ * @returns The relative file paths.
+ */
+async function listTemplateFiles(folder) {
+    const entries = await readdir(folder, { recursive: true, withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(folder, path.join(entry.parentPath, entry.name)));
+    return files.sort();
+}

package/lib/SessionRoom.d.ts

@@ -0,0 +1,391 @@
+import { Room, type AuthContext, type Client } from "colyseus";
+import { type DedicatedRoomOptions } from "./DedicatedSession.js";
+import type { DiscordSessionPlayerView } from "./discord/DiscordSignInRoutes.js";
+import { type FusionConnectRequest } from "./HeadlessRuntime.js";
+import { type JoinGateResult } from "./JoinGate.js";
+import type { AdminNoticePayload, DedicatedRestartOptions, SessionDetailView, SessionInspectorView, SessionSummaryView } from "./admin/AdminApiTypes.js";
+/** What a session room is created with: a joiner's request (the creator's join options), or DedicatedRoomOptions. */
+type SessionCreateOptions = Partial<DedicatedRoomOptions> & Partial<FusionConnectRequest>;
+/**
+ * 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 declare class SessionRoom extends Room {
+    /** The runtime's TOOLKIT namespace (Babylon Toolkit Networking). */
+    private toolkit;
+    /** The session rules. */
+    private logic;
+    /** Seats by client session id, for reconnects. */
+    private readonly seats;
+    /** The headless Server-mode session a dedicated room runs, or null (T13). */
+    private dedicatedSession;
+    /** True for a room that runs a headless Server-mode runner (DedicatedSession). */
+    private hostsDedicatedRunner;
+    /** The game server this room belongs to (limits, hooks, metrics). */
+    private serverState;
+    /** The session name, for hooks and logs. */
+    private sessionName;
+    /** The TOOLKIT.GameMode of the joiner that created the session, or null. */
+    private creatorGameMode;
+    /** Seconds an on-demand room stays open empty, or null for every other room (they never idle-close, D19). */
+    private idleSeconds;
+    /** The configured scene an on-demand room runs, for logs. */
+    private onDemandSceneName;
+    /** The scene a dedicated room runs (its configured name, else its scene file), or null for other rooms. */
+    private dedicatedSceneName;
+    /** Who started this room's dedicated runner (game-server-admin-console T9). */
+    private dedicatedStartedBy;
+    /** The pending idle close of an empty on-demand room, or null. */
+    private idleTimer;
+    /** Settles once an on-demand room's runner has loaded (rejects when it failed), or null for other rooms. */
+    private dedicatedRunnerReady;
+    /** True once the room was disposed. */
+    private isDisposed;
+    /** ISO time the room was created. */
+    private createdAt;
+    /** The last session description the logic published, or null before the first. */
+    private lastSessionInfo;
+    /** Frame totals since creation (counted whether or not metrics are on). */
+    private readonly traffic;
+    /** Start of the current traffic window, in performance.now() milliseconds. */
+    private trafficWindowStartedAt;
+    /** Total bytes at the start of the current traffic window. */
+    private trafficWindowBytes;
+    /** Bytes per second over the last full ROOM_TRAFFIC_WINDOW_MS. */
+    private bytesPerSecond;
+    /** Host migrations seen in updateSession (logic.isMigratingHost turning false). */
+    private readonly hostMigrationLog;
+    /** The host seen while no migration ran, or null. */
+    private lastHostPlayerId;
+    /** Whether a host migration was running at the last update. */
+    private wasMigratingHost;
+    /** True when a dedicated Server-mode runner hosts this session. */
+    get isDedicated(): boolean;
+    /** The session's TOOLKIT.GameMode name ("Shared", "Host", "Server", …), or "Pending" before its first join. */
+    get gameModeName(): string;
+    /** Clients connected to the room now. */
+    get playerCount(): number;
+    /**
+     * 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 onAuth(token: string, options: FusionConnectRequest, context: AuthContext): Promise<JoinGateResult>;
+    /**
+     * 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.
+     */
+    onCreate(options?: SessionCreateOptions): Promise<void>;
+    /** Stops a dedicated room's server runner with the room, and leaves the server's live sessions. */
+    onDispose(): Promise<void>;
+    /**
+     * 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.
+     */
+    onJoin(client: Client, options: FusionConnectRequest): Promise<void>;
+    /**
+     * 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.
+     */
+    closeForShutdown(): Promise<void>;
+    /**
+     * 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: Client): void;
+    /**
+     * A dropped client came back within the grace period: it resumes its player id.
+     * @param client The reconnected client.
+     */
+    onReconnect(client: Client): void;
+    /**
+     * A client left for good (or its reconnect window closed).
+     * @param client The leaving client.
+     */
+    onLeave(client: Client): void;
+    /**
+     * This session as a row of the admin session list (game-server-admin-console R18).
+     * @returns The row.
+     */
+    adminSummary(): SessionSummaryView;
+    /**
+     * 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: boolean): SessionDetailView;
+    /**
+     * 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(): DiscordSessionPlayerView[];
+    /**
+     * 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(): SessionInspectorView;
+    /**
+     * 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.
+     */
+    adminKickPlayer(playerId: number, message: string, allowRejoin: boolean): Promise<boolean>;
+    /**
+     * 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.
+     */
+    adminClose(message: string): Promise<void>;
+    /**
+     * Locks or unlocks the session against new joins from the console.
+     * @param locked True to lock.
+     */
+    adminSetLocked(locked: boolean): Promise<void>;
+    /**
+     * 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: AdminNoticePayload, playerId: number): number;
+    /**
+     * 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: string): DedicatedRestartOptions | null;
+    /**
+     * 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: string[], addresses: string[], message: string): number;
+    /**
+     * 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.
+     */
+    private createSession;
+    /**
+     * 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").
+     */
+    private loadOnDemandRunner;
+    /**
+     * 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.
+     */
+    private resolveOnDemandScene;
+    /**
+     * 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).
+     */
+    private recentLogLines;
+    /**
+     * Keeps a dedicated room's scene and starter for the console.
+     * @param options The dedicated room options.
+     */
+    private rememberDedicatedScene;
+    /**
+     * 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.
+     */
+    private describeDedicated;
+    /**
+     * 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: …").
+     */
+    private checkDedicatedCap;
+    /**
+     * Closes an on-demand room after idleSeconds without clients (D19); a join before then cancels it (onJoin).
+     */
+    private startIdleTimer;
+    /**
+     * Expires reconnect holds (A9). A room kept open for a host migration that ended with nobody left (the elected host
+     * never came back) closes.
+     */
+    private updateSession;
+    /**
+     * 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.
+     */
+    private refreshAutoDispose;
+    /**
+     * 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.
+     */
+    private admit;
+    /**
+     * 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.
+     */
+    private admitCounted;
+    /**
+     * 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.
+     */
+    private receiveControl;
+    /**
+     * The session logic's outputs, bound to this room's clients and listing.
+     * @returns The outputs.
+     */
+    private createOutputs;
+    /**
+     * 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.
+     */
+    private receiveFrame;
+    /**
+     * 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).
+     */
+    private sendFrameTo;
+    /**
+     * 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.
+     */
+    private countFrame;
+    /**
+     * 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.
+     */
+    private sendControlTo;
+    /**
+     * 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.
+     */
+    private publishSession;
+    /**
+     * Locks or unlocks the room against new joins (full or closed sessions).
+     * @param locked True to lock.
+     */
+    private setLocked;
+    /**
+     * Clamps a requested player count to limits.maxPlayersPerSession (D14).
+     * @param requestedPlayerCount The count the joiner asked for.
+     * @returns The count the session may use.
+     */
+    private clampPlayerCount;
+    /**
+     * Measures the room's byte rate once per ROOM_TRAFFIC_WINDOW_MS (R18).
+     */
+    private sampleTraffic;
+    /**
+     * Records a host migration when logic.isMigratingHost turns false with a different host than before (R18).
+     */
+    private watchHostMigration;
+    /**
+     * The Host-mode host's player id.
+     * @returns The id, or null when no player is the host.
+     */
+    private currentHostPlayerId;
+    /**
+     * The client session id of a player.
+     * @param playerId The player.
+     * @returns The session id, or null when no seat has that player.
+     */
+    private sessionIdOfPlayer;
+    /**
+     * 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.
+     */
+    private describePlayers;
+    /**
+     * 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.
+     */
+    private blockRejoin;
+    /**
+     * 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.
+     */
+    private reportPlayerSession;
+    /**
+     * This session's description for the hooks.
+     * @returns The event.
+     */
+    private sessionEvent;
+    /**
+     * Calls a session hook, if the server has it.
+     * @param hookName The hook.
+     */
+    private callSessionHook;
+    /**
+     * 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.
+     */
+    private callPlayerHook;
+    /**
+     * 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.
+     */
+    private callHook;
+}
+export {};