@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/BootSessionOwner.js

@@ -0,0 +1,116 @@
+// Decides which process of a numbered deploy runs the boot dedicated sessions. A rolling deploy gives no process number
+// a fixed role (Colyseus Cloud brings a new generation up on free numbers and restarts process 0 only after it drained,
+// or not at all), so a store lease picks the process. Without Redis the file store grants every lease, so a deploy of
+// one process always boots its sessions, whatever its number.
+import { LEADER_LEASE_TTL_MS, LEADER_RENEW_INTERVAL_MS } from "./admin/AdminConstants.js";
+import { getLogger } from "./GameServerLogger.js";
+/** The store lease whose holder runs the boot dedicated sessions. */
+export const BOOT_SESSION_LEASE_NAME = "dedicated-boot";
+/**
+ * Holds the boot session lease and starts the boot dedicated sessions on the process that gets it. A process that does
+ * not hold the lease keeps asking; a draining holder stops renewing, so a process of the next generation takes over
+ * within LEADER_LEASE_TTL_MS.
+ */
+export class BootSessionOwner {
+    /** What it needs from the running server. */
+    dependencies;
+    /** The renewal timer, while started. */
+    renewTimer = null;
+    /** What the last look at the lease found; logged only when it changes. */
+    leaseState = "unknown";
+    /** True once this process runs every boot session. */
+    areSessionsStarted = false;
+    /** True while a start runs: a scene can load for longer than a tick, and the lease must keep renewing meanwhile. */
+    isStarting = false;
+    /**
+     * Prepares the owner; nothing runs until start().
+     * @param dependencies What it needs from the running server.
+     */
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    /**
+     * Runs the first attempt and keeps trying every LEADER_RENEW_INTERVAL_MS. The timer starts first, so a slow scene
+     * load cannot let the lease lapse.
+     * @throws Error when this process gets the lease and a boot session cannot start; the owner is stopped first.
+     */
+    async start() {
+        this.renewTimer = this.dependencies.clock.setInterval(() => void this.tick(), LEADER_RENEW_INTERVAL_MS);
+        try {
+            await this.attempt();
+        }
+        catch (error) {
+            this.stop();
+            throw error;
+        }
+    }
+    /** Stops the timer. The lease runs out by itself after LEADER_LEASE_TTL_MS. */
+    stop() {
+        if (this.renewTimer != null)
+            this.dependencies.clock.clearInterval(this.renewTimer);
+        this.renewTimer = null;
+    }
+    /**
+     * One timer tick: renews the lease and starts the sessions when due, unless this process drains. A failure never
+     * reaches the running process: it is logged, and the next tick tries again.
+     */
+    async tick() {
+        if (this.dependencies.isDraining())
+            return;
+        try {
+            await this.attempt();
+        }
+        catch (error) {
+            getLogger().error("the boot dedicated sessions could not start; trying again", { error: String(error) });
+        }
+    }
+    /**
+     * Renews the lease, then starts the sessions when this process holds it and has not started them.
+     * @throws Error when a session cannot start.
+     */
+    async attempt() {
+        const holdsLease = await this.renewLease();
+        if (!holdsLease || this.areSessionsStarted || this.isStarting)
+            return;
+        this.isStarting = true;
+        try {
+            this.areSessionsStarted = await this.dependencies.startSessions();
+        }
+        finally {
+            this.isStarting = false;
+        }
+    }
+    /**
+     * Takes or renews the lease; a store failure counts as not holding it.
+     * @returns True while this process holds the lease.
+     */
+    async renewLease() {
+        const holderId = this.dependencies.holderId();
+        try {
+            const holdsLease = await this.dependencies.tryAcquireLease(holderId, LEADER_LEASE_TTL_MS);
+            this.reportLeaseState(holdsLease ? "held" : "waiting", holderId);
+            return holdsLease;
+        }
+        catch (error) {
+            this.reportLeaseState("unavailable", holderId, String(error));
+            return false;
+        }
+    }
+    /**
+     * Logs a change of the lease state, so a process that waits for hours writes one line.
+     * @param leaseState What this look found.
+     * @param holderId This process's id.
+     * @param failure Why the store could not answer, when it could not.
+     */
+    reportLeaseState(leaseState, holderId, failure) {
+        if (leaseState === this.leaseState)
+            return;
+        this.leaseState = leaseState;
+        if (leaseState === "held")
+            getLogger().info("this process holds the boot session lease", { process: holderId });
+        else if (leaseState === "waiting")
+            getLogger().info("another process holds the boot session lease; this one waits", { process: holderId });
+        else
+            getLogger().warn("the boot session lease could not be renewed", { process: holderId, error: failure });
+    }
+}

package/lib/ColyseusLoggerAdapter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The logger handed to Colyseus (`defineServer({ logger })`, game-server-admin-console D21): every Colyseus message goes
+ * through the game server's own logger with `source: "colyseus"`, so the console's log buffer captures it and its level
+ * and format apply. Colyseus's `trace` goes to `debug`.
+ */
+export declare const colyseusLoggerAdapter: {
+    /**
+     * Logs Colyseus detail.
+     * @param logArguments What Colyseus logged.
+     */
+    debug(...logArguments: unknown[]): void;
+    /**
+     * Logs a Colyseus trace, at debug.
+     * @param logArguments What Colyseus logged.
+     */
+    trace(...logArguments: unknown[]): void;
+    /**
+     * Logs a Colyseus lifecycle message.
+     * @param logArguments What Colyseus logged.
+     */
+    info(...logArguments: unknown[]): void;
+    /**
+     * Logs a Colyseus warning.
+     * @param logArguments What Colyseus logged.
+     */
+    warn(...logArguments: unknown[]): void;
+    /**
+     * Logs a Colyseus error.
+     * @param logArguments What Colyseus logged.
+     */
+    error(...logArguments: unknown[]): void;
+};

package/lib/ColyseusLoggerAdapter.js

@@ -0,0 +1,73 @@
+import { getLogger } from "./GameServerLogger.js";
+/** The source field of every entry that comes from Colyseus. */
+const COLYSEUS_SOURCE = "colyseus";
+/**
+ * Turns Colyseus's positional log arguments into one message: joined with spaces, an Error as its message, any other
+ * object as JSON.
+ * @param logArguments The arguments Colyseus passed.
+ * @returns The message.
+ */
+function joinLogArguments(logArguments) {
+    return logArguments.map((argument) => {
+        if (argument instanceof Error)
+            return argument.message;
+        if (argument !== null && typeof argument === "object")
+            return safeJson(argument);
+        return String(argument);
+    }).join(" ");
+}
+/**
+ * JSON text of an object, or its string form when it cannot be serialized (cycles).
+ * @param value The object.
+ * @returns The text.
+ */
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * The logger handed to Colyseus (`defineServer({ logger })`, game-server-admin-console D21): every Colyseus message goes
+ * through the game server's own logger with `source: "colyseus"`, so the console's log buffer captures it and its level
+ * and format apply. Colyseus's `trace` goes to `debug`.
+ */
+export const colyseusLoggerAdapter = {
+    /**
+     * Logs Colyseus detail.
+     * @param logArguments What Colyseus logged.
+     */
+    debug(...logArguments) {
+        getLogger().debug(joinLogArguments(logArguments), { source: COLYSEUS_SOURCE });
+    },
+    /**
+     * Logs a Colyseus trace, at debug.
+     * @param logArguments What Colyseus logged.
+     */
+    trace(...logArguments) {
+        getLogger().debug(joinLogArguments(logArguments), { source: COLYSEUS_SOURCE });
+    },
+    /**
+     * Logs a Colyseus lifecycle message.
+     * @param logArguments What Colyseus logged.
+     */
+    info(...logArguments) {
+        getLogger().info(joinLogArguments(logArguments), { source: COLYSEUS_SOURCE });
+    },
+    /**
+     * Logs a Colyseus warning.
+     * @param logArguments What Colyseus logged.
+     */
+    warn(...logArguments) {
+        getLogger().warn(joinLogArguments(logArguments), { source: COLYSEUS_SOURCE });
+    },
+    /**
+     * Logs a Colyseus error.
+     * @param logArguments What Colyseus logged.
+     */
+    error(...logArguments) {
+        getLogger().error(joinLogArguments(logArguments), { source: COLYSEUS_SOURCE });
+    }
+};

package/lib/DedicatedSceneRegistry.d.ts

@@ -0,0 +1,52 @@
+import type { DedicatedSceneConfig } from "./GameServerConfig.js";
+/** A configured dedicated scene with its locations as URLs (D19). */
+export interface ResolvedDedicatedScene extends DedicatedSceneConfig {
+    /** sceneRoot as an http(s):// or file:// URL ending in "/". */
+    sceneRootUrl: string;
+}
+/**
+ * The dedicated scenes a server may run (D19): the config's `dedicated.scenes`, with each scene root turned into a URL
+ * the headless runtime loads from. An http(s):// root is used as it is (with a trailing "/"); any other root is a folder
+ * resolved against the working directory as a file:// URL. Project script paths resolve the same way. The registry is
+ * also the source of the headless runtime's URL allow-list, so a client can only ever name a scene, never a URL.
+ */
+export declare class DedicatedSceneRegistry {
+    /** The scenes by name. */
+    private readonly scenes;
+    /**
+     * Resolves the configured scenes.
+     * @param scenes The config's dedicated scenes.
+     * @param workingDirectory The folder relative scene roots and script paths resolve against.
+     */
+    constructor(scenes: DedicatedSceneConfig[], workingDirectory: string);
+    /**
+     * The scene of a name.
+     * @param sceneName The configured scene name.
+     * @returns The scene, or null when none has that name.
+     */
+    find(sceneName: string): ResolvedDedicatedScene | null;
+    /**
+     * Every configured scene, in config order (the console's dedicated page, game-server-admin-console T9).
+     * @returns The scenes.
+     */
+    listScenes(): ResolvedDedicatedScene[];
+    /**
+     * The URL prefixes the headless runtime may fetch (D19): every scene root URL and every project script URL.
+     * @returns The prefixes (possibly none).
+     */
+    allowedUrlPrefixes(): string[];
+    /**
+     * A scene root as a folder URL ending in "/".
+     * @param sceneRoot An http(s):// or file:// URL, or a folder path.
+     * @param workingDirectory The folder a relative path resolves against.
+     * @returns The URL.
+     */
+    private static toFolderUrl;
+    /**
+     * A location as a URL: a URL as it is, a path as a file:// URL.
+     * @param location An http(s):// or file:// URL, or a path.
+     * @param workingDirectory The folder a relative path resolves against.
+     * @returns The URL.
+     */
+    private static toFileUrl;
+}

package/lib/DedicatedSceneRegistry.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+/** URL schemes a scene root or project script may already use; anything else is a folder or file path. */
+const URL_SCHEME_PATTERN = /^(https?|file):\/\//i;
+/**
+ * The dedicated scenes a server may run (D19): the config's `dedicated.scenes`, with each scene root turned into a URL
+ * the headless runtime loads from. An http(s):// root is used as it is (with a trailing "/"); any other root is a folder
+ * resolved against the working directory as a file:// URL. Project script paths resolve the same way. The registry is
+ * also the source of the headless runtime's URL allow-list, so a client can only ever name a scene, never a URL.
+ */
+export class DedicatedSceneRegistry {
+    /** The scenes by name. */
+    scenes = new Map();
+    /**
+     * Resolves the configured scenes.
+     * @param scenes The config's dedicated scenes.
+     * @param workingDirectory The folder relative scene roots and script paths resolve against.
+     */
+    constructor(scenes, workingDirectory) {
+        for (const scene of scenes) {
+            const resolved = Object.assign({}, scene, {
+                sceneRootUrl: DedicatedSceneRegistry.toFolderUrl(scene.sceneRoot, workingDirectory),
+                projectScripts: scene.projectScripts.map((script) => DedicatedSceneRegistry.toFileUrl(script, workingDirectory))
+            });
+            this.scenes.set(scene.name, resolved);
+        }
+    }
+    /**
+     * The scene of a name.
+     * @param sceneName The configured scene name.
+     * @returns The scene, or null when none has that name.
+     */
+    find(sceneName) {
+        return this.scenes.get(sceneName) ?? null;
+    }
+    /**
+     * Every configured scene, in config order (the console's dedicated page, game-server-admin-console T9).
+     * @returns The scenes.
+     */
+    listScenes() {
+        return Array.from(this.scenes.values());
+    }
+    /**
+     * The URL prefixes the headless runtime may fetch (D19): every scene root URL and every project script URL.
+     * @returns The prefixes (possibly none).
+     */
+    allowedUrlPrefixes() {
+        const prefixes = [];
+        for (const scene of this.scenes.values())
+            prefixes.push(scene.sceneRootUrl, ...scene.projectScripts);
+        return prefixes;
+    }
+    /**
+     * A scene root as a folder URL ending in "/".
+     * @param sceneRoot An http(s):// or file:// URL, or a folder path.
+     * @param workingDirectory The folder a relative path resolves against.
+     * @returns The URL.
+     */
+    static toFolderUrl(sceneRoot, workingDirectory) {
+        const url = DedicatedSceneRegistry.toFileUrl(sceneRoot, workingDirectory);
+        return url.endsWith("/") ? url : url + "/";
+    }
+    /**
+     * A location as a URL: a URL as it is, a path as a file:// URL.
+     * @param location An http(s):// or file:// URL, or a path.
+     * @param workingDirectory The folder a relative path resolves against.
+     * @returns The URL.
+     */
+    static toFileUrl(location, workingDirectory) {
+        if (URL_SCHEME_PATTERN.test(location))
+            return location;
+        return pathToFileURL(path.resolve(workingDirectory, location)).href;
+    }
+}

package/lib/DedicatedSession.d.ts

@@ -0,0 +1,152 @@
+import { type FusionSessionLogicApi } from "./HeadlessRuntime.js";
+import type { DedicatedFrameBucketView, DedicatedStartedBy } from "./admin/AdminApiTypes.js";
+/** What a dedicated session runs. */
+export interface DedicatedSessionOptions {
+    /** The session name clients join by. */
+    sessionName: string;
+    /** The folder URL of the exported scene: http(s):// (for example "http://localhost:8877/scenes/") or file://. */
+    sceneRootUrl: string;
+    /** The exported scene file, the same one the clients load (for example "networktestbed.gltf"). */
+    sceneFile: string;
+    /** Most players (default 8). */
+    playerCount?: number;
+    /** Script bundles to load before the scene (the scene's own project bundle auto-loads without this). */
+    projectScripts?: string[];
+    /** The configured scene's name (game-server-admin-console T9); code that passes locations only leaves it out. */
+    sceneName?: string;
+    /** Who started the session, as the console shows it (default "code"). */
+    startedBy?: DedicatedStartedBy;
+    /**
+     * True creates the room on this process. By default the matchmaker picks the process with the fewest rooms, which
+     * with Redis can be another one, even one that is draining (it stays eligible until its final shutdown).
+     */
+    createOnThisProcess?: boolean;
+}
+/** The room creation options of a dedicated session (A17). */
+export interface DedicatedRoomOptions extends DedicatedSessionOptions {
+    /** TOOLKIT.GameMode.Server. */
+    gameMode: number;
+    /** Always true: the room runs a headless Server-mode runner. */
+    dedicated: true;
+}
+/** The result of TOOLKIT.NetworkRunner.startGame. */
+export interface DedicatedStartResult {
+    /** True when the runner started. */
+    ok: boolean;
+    /** A readable failure message, or null. */
+    errorMessage: string | null;
+}
+/** The members of TOOLKIT.NetworkObject the session inspector reads (game-server-admin-console DR §6.6). */
+export interface DedicatedNetworkObject {
+    /** The network id. */
+    readonly id: number;
+    /** The object's name. */
+    readonly name: string;
+    /** The prefab's guid; empty for a scene object. */
+    readonly prefabGuid: string;
+    /** The player with state authority. */
+    readonly stateAuthority: {
+        readonly playerId: number;
+    };
+    /** The object's state words, or null before it has any. */
+    readonly stateBuffer: {
+        readonly wordCount: number;
+    } | null;
+}
+/** The members of TOOLKIT.NetworkRunner a dedicated session uses. */
+export interface DedicatedRunner {
+    /** False on a dedicated server: it has no local player. */
+    provideInput: boolean;
+    /** Simulation ticks per second. */
+    readonly tickRate: number;
+    /** Starts the runner. */
+    startGame(args: object): Promise<DedicatedStartResult>;
+    /** Stops the runner. */
+    shutdown(): Promise<void>;
+    /** Every network object the runner simulates (read by the session inspector). */
+    getAllNetworkObjects?(): DedicatedNetworkObject[];
+}
+/** The Colyseus room type of sessions (D10). */
+export declare const SESSION_ROOM_NAME: string;
+/**
+ * The frame-time history of one dedicated runner (game-server-admin-console D23): DEDICATED_FRAME_BUCKET_SECONDS
+ * buckets on the wall-clock grid, the last DEDICATED_FRAME_BUCKET_COUNT of them (one hour). It is kept per session,
+ * apart from the Prometheus histogram, so the console can chart each session on its own.
+ */
+export declare class DedicatedFrameStatistics {
+    /** The buckets, oldest first; the last one may still be filling. */
+    private readonly frameBuckets;
+    /** Reads the current time, in milliseconds since the epoch. */
+    private readonly now;
+    /**
+     * Creates an empty history.
+     * @param now Reads the current time (default Date.now).
+     */
+    constructor(now?: () => number);
+    /**
+     * Adds one rendered frame.
+     * @param seconds The frame's duration, in seconds.
+     * @param tickSeconds The simulation tick length the frame must fit in, in seconds.
+     */
+    observe(seconds: number, tickSeconds: number): void;
+    /**
+     * The history for the console, oldest first, including the bucket still filling.
+     * @returns The buckets.
+     */
+    buckets(): DedicatedFrameBucketView[];
+    /**
+     * The bucket of the current time, started (and the oldest dropped) when a new grid step began.
+     * @returns The bucket.
+     */
+    private currentBucket;
+}
+/**
+ * A dedicated Server-mode session (T13): a headless NetworkRunner in Server mode inside a session room, on the same exported
+ * scene the clients load. The server spawns every joining player's objects (the scene's scripts do it, as on a host), and
+ * clients join it as Client.
+ *
+ * @example
+ * await createGameServer({ config: { port: 2567 } });
+ * await DedicatedSession.start({ sessionName: "srv1", sceneRootUrl: "http://localhost:8877/scenes/", sceneFile: "networktestbed.gltf" });
+ */
+export declare class DedicatedSession {
+    /** The headless scene and its engine. */
+    private readonly headless;
+    /** The Server-mode runner. */
+    private readonly serverRunner;
+    /** The runner's frame-time history (D23). */
+    private readonly frameStatistics;
+    /**
+     * Wraps a running dedicated session. Use DedicatedSession.start (or attach, from the room).
+     * @param headless The headless scene.
+     * @param serverRunner The running Server-mode runner.
+     * @param frameStatistics The frame-time history the render loop feeds.
+     */
+    private constructor();
+    /** The Server-mode runner (tests read its prefab table and objects). */
+    get runner(): DedicatedRunner;
+    /** The runner's frame-time and overrun history for the last hour (D23). */
+    get statistics(): DedicatedFrameStatistics;
+    /**
+     * Creates a dedicated session room (A17): the room loads the scene headless and starts its Server-mode runner before
+     * it accepts players. The server must be listening (createGameServer). The scene root and project scripts are added to
+     * the headless runtime's URL allow-list: this is trusted server code, unlike a client's join.
+     * @param options The session name, scene and player count.
+     * @returns The room id.
+     * @throws Error when the scene cannot be loaded or the runner does not start.
+     */
+    static start(options: DedicatedSessionOptions): Promise<string>;
+    /**
+     * Runs a dedicated session inside a session room (the room's onCreate calls it): loads the extra script bundles and
+     * the scene headless (rendering once ready), then starts a Server-mode runner on a RoomServerTransport to the room's
+     * logic. The scene's scripts find the runner on the scene (NetworkRunner.instances) and become its callbacks. Each
+     * rendered frame's duration feeds the dedicated frame metrics (D16) and the session's own frame statistics (D23).
+     * @param logic The room's session logic.
+     * @param options The room creation options.
+     * @returns The running session.
+     * @throws Error when the runner does not start.
+     */
+    static attach(logic: FusionSessionLogicApi, options: DedicatedRoomOptions): Promise<DedicatedSession>;
+    /** Stops the runner, the render loop and the engine. */
+    stop(): Promise<void>;
+}

package/lib/DedicatedSession.js

@@ -0,0 +1,173 @@
+import { matchMaker } from "colyseus";
+import { getLogger } from "./GameServerLogger.js";
+import { findGameServerState } from "./GameServerState.js";
+import { allowScriptUrlPrefixes, getToolkitRuntime, loadHeadlessScene, loadNodeScriptAsync } from "./HeadlessRuntime.js";
+import { RoomServerTransport } from "./RoomServerTransport.js";
+import { DEDICATED_FRAME_BUCKET_COUNT, DEDICATED_FRAME_BUCKET_SECONDS } from "./admin/AdminConstants.js";
+/** The Colyseus room type of sessions (D10). */
+export const SESSION_ROOM_NAME = "fusion_session";
+/** Players a dedicated session accepts when the options do not say. */
+const DEFAULT_PLAYER_COUNT = 8;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** Length of one frame statistics bucket, in milliseconds. */
+const FRAME_BUCKET_MILLISECONDS = DEDICATED_FRAME_BUCKET_SECONDS * MILLISECONDS_PER_SECOND;
+/**
+ * The frame-time history of one dedicated runner (game-server-admin-console D23): DEDICATED_FRAME_BUCKET_SECONDS
+ * buckets on the wall-clock grid, the last DEDICATED_FRAME_BUCKET_COUNT of them (one hour). It is kept per session,
+ * apart from the Prometheus histogram, so the console can chart each session on its own.
+ */
+export class DedicatedFrameStatistics {
+    /** The buckets, oldest first; the last one may still be filling. */
+    frameBuckets = [];
+    /** Reads the current time, in milliseconds since the epoch. */
+    now;
+    /**
+     * Creates an empty history.
+     * @param now Reads the current time (default Date.now).
+     */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /**
+     * Adds one rendered frame.
+     * @param seconds The frame's duration, in seconds.
+     * @param tickSeconds The simulation tick length the frame must fit in, in seconds.
+     */
+    observe(seconds, tickSeconds) {
+        const bucket = this.currentBucket();
+        const milliseconds = seconds * MILLISECONDS_PER_SECOND;
+        bucket.frameCount += 1;
+        bucket.totalMilliseconds += milliseconds;
+        bucket.maximumMilliseconds = Math.max(bucket.maximumMilliseconds, milliseconds);
+        if (seconds > tickSeconds)
+            bucket.tickOverruns += 1;
+    }
+    /**
+     * The history for the console, oldest first, including the bucket still filling.
+     * @returns The buckets.
+     */
+    buckets() {
+        return this.frameBuckets.map((bucket) => ({
+            at: new Date(bucket.startedAt).toISOString(),
+            averageFrameMilliseconds: (bucket.frameCount > 0) ? bucket.totalMilliseconds / bucket.frameCount : 0,
+            maximumFrameMilliseconds: bucket.maximumMilliseconds,
+            tickOverruns: bucket.tickOverruns
+        }));
+    }
+    /**
+     * The bucket of the current time, started (and the oldest dropped) when a new grid step began.
+     * @returns The bucket.
+     */
+    currentBucket() {
+        const startedAt = Math.floor(this.now() / FRAME_BUCKET_MILLISECONDS) * FRAME_BUCKET_MILLISECONDS;
+        const newest = this.frameBuckets[this.frameBuckets.length - 1];
+        if (newest != null && newest.startedAt === startedAt)
+            return newest;
+        const bucket = { startedAt: startedAt, frameCount: 0, totalMilliseconds: 0, maximumMilliseconds: 0, tickOverruns: 0 };
+        this.frameBuckets.push(bucket);
+        if (this.frameBuckets.length > DEDICATED_FRAME_BUCKET_COUNT)
+            this.frameBuckets.shift();
+        return bucket;
+    }
+}
+/**
+ * A dedicated Server-mode session (T13): a headless NetworkRunner in Server mode inside a session room, on the same exported
+ * scene the clients load. The server spawns every joining player's objects (the scene's scripts do it, as on a host), and
+ * clients join it as Client.
+ *
+ * @example
+ * await createGameServer({ config: { port: 2567 } });
+ * await DedicatedSession.start({ sessionName: "srv1", sceneRootUrl: "http://localhost:8877/scenes/", sceneFile: "networktestbed.gltf" });
+ */
+export class DedicatedSession {
+    /** The headless scene and its engine. */
+    headless;
+    /** The Server-mode runner. */
+    serverRunner;
+    /** The runner's frame-time history (D23). */
+    frameStatistics;
+    /**
+     * Wraps a running dedicated session. Use DedicatedSession.start (or attach, from the room).
+     * @param headless The headless scene.
+     * @param serverRunner The running Server-mode runner.
+     * @param frameStatistics The frame-time history the render loop feeds.
+     */
+    constructor(headless, serverRunner, frameStatistics) {
+        this.headless = headless;
+        this.serverRunner = serverRunner;
+        this.frameStatistics = frameStatistics;
+    }
+    /** The Server-mode runner (tests read its prefab table and objects). */
+    get runner() {
+        return this.serverRunner;
+    }
+    /** The runner's frame-time and overrun history for the last hour (D23). */
+    get statistics() {
+        return this.frameStatistics;
+    }
+    /**
+     * Creates a dedicated session room (A17): the room loads the scene headless and starts its Server-mode runner before
+     * it accepts players. The server must be listening (createGameServer). The scene root and project scripts are added to
+     * the headless runtime's URL allow-list: this is trusted server code, unlike a client's join.
+     * @param options The session name, scene and player count.
+     * @returns The room id.
+     * @throws Error when the scene cannot be loaded or the runner does not start.
+     */
+    static async start(options) {
+        // Server code chose these locations, so they join the headless runtime's allow-list (D19).
+        allowScriptUrlPrefixes([options.sceneRootUrl, ...(options.projectScripts ?? [])]);
+        const toolkit = getToolkitRuntime().TOOLKIT;
+        const { createOnThisProcess, ...sessionOptions } = options;
+        const roomOptions = Object.assign({}, sessionOptions, { gameMode: toolkit.GameMode.Server, dedicated: true, playerCount: options.playerCount ?? DEFAULT_PLAYER_COUNT });
+        const room = (createOnThisProcess === true) ? await matchMaker.handleCreateRoom(SESSION_ROOM_NAME, roomOptions) : await matchMaker.createRoom(SESSION_ROOM_NAME, roomOptions);
+        return room.roomId;
+    }
+    /**
+     * Runs a dedicated session inside a session room (the room's onCreate calls it): loads the extra script bundles and
+     * the scene headless (rendering once ready), then starts a Server-mode runner on a RoomServerTransport to the room's
+     * logic. The scene's scripts find the runner on the scene (NetworkRunner.instances) and become its callbacks. Each
+     * rendered frame's duration feeds the dedicated frame metrics (D16) and the session's own frame statistics (D23).
+     * @param logic The room's session logic.
+     * @param options The room creation options.
+     * @returns The running session.
+     * @throws Error when the runner does not start.
+     */
+    static async attach(logic, options) {
+        const runtime = getToolkitRuntime();
+        for (const scriptUrl of options.projectScripts ?? [])
+            await loadNodeScriptAsync(scriptUrl);
+        let runner = null;
+        const frameStatistics = new DedicatedFrameStatistics();
+        const observeFrame = (seconds) => {
+            if (runner == null)
+                return;
+            const tickSeconds = 1 / runner.tickRate;
+            findGameServerState()?.metrics?.observeDedicatedFrame(seconds, tickSeconds);
+            frameStatistics.observe(seconds, tickSeconds);
+        };
+        const headless = await loadHeadlessScene(options.sceneRootUrl, options.sceneFile, observeFrame);
+        const toolkit = runtime.TOOLKIT;
+        runner = new toolkit.NetworkRunner(headless.scene);
+        runner.provideInput = false;
+        const result = await runner.startGame({
+            gameMode: toolkit.GameMode.Server,
+            sessionName: options.sessionName,
+            playerCount: options.playerCount ?? DEFAULT_PLAYER_COUNT,
+            transport: new RoomServerTransport(logic)
+        });
+        if (!result.ok) {
+            headless.engine.dispose();
+            throw new Error("[GameServer] the dedicated runner did not start: " + result.errorMessage);
+        }
+        getLogger().info("dedicated session \"" + options.sessionName + "\" running " + options.sceneRootUrl + options.sceneFile, { sessionName: options.sessionName });
+        return new DedicatedSession(headless, runner, frameStatistics);
+    }
+    /** Stops the runner, the render loop and the engine. */
+    async stop() {
+        await this.serverRunner.shutdown();
+        this.headless.engine.stopRenderLoop();
+        this.headless.scene.dispose();
+        this.headless.engine.dispose();
+    }
+}