@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/HeadlessRuntime.d.ts

@@ -0,0 +1,316 @@
+import type { AuthIdentity } from "./Authentication.js";
+/** A session's public description, as TOOLKIT.SessionInfo. */
+export interface FusionSessionInfo {
+    /** Session name players join by. */
+    name: string;
+    /** True when new players may join. */
+    isOpen: boolean;
+    /** True when the session is listed in the lobby. */
+    isVisible: boolean;
+    /** Players connected now. */
+    playerCount: number;
+    /** Most players the session accepts. */
+    maxPlayers: number;
+    /** Custom session properties. */
+    properties: Record<string, string | number | boolean>;
+}
+/** What a client sends when it joins, as TOOLKIT.NetworkConnectRequest (the join options of a session room). */
+export interface FusionConnectRequest {
+    /** Session to create or join. */
+    sessionName: string;
+    /** The joiner's TOOLKIT.GameMode value. */
+    gameMode: number;
+    /** Most players. */
+    playerCount: number;
+    /** True when new players may join. */
+    isOpen: boolean;
+    /** True when the session is listed in the lobby. */
+    isVisible: boolean;
+    /** Custom session properties. */
+    sessionProperties: Record<string, string | number | boolean>;
+    /** The joiner's tick rate. */
+    tickRate: number;
+    /** The joiner's prefab table hash. */
+    prefabTableHash: number;
+    /** Bytes the host sees in onConnectRequest, as base64. */
+    connectionTokenBase64: string;
+    /** The player id to resume after a drop, or 0 for a new player. */
+    reconnectPlayerId: number;
+    /** True when a runner restarts after a host migration: it resumes reconnectPlayerId (D31). */
+    hostMigration?: boolean;
+    /** The joiner's TOOLKIT.NETWORK_PROTOCOL_VERSION; missing from runtimes that predate it (counts as 0, D5). */
+    protocolVersion?: number;
+    /** The identity the server verified from the join's token; the room overwrites any client-sent value (D12). */
+    authIdentity?: AuthIdentity | null;
+}
+/** The session's answer to a join, as TOOLKIT.NetworkWelcome (the fields the room reads). */
+export interface FusionWelcome {
+    /** The joiner's player id. */
+    playerId: number;
+}
+/** Where the session logic sends its output, as TOOLKIT.FusionSessionOutputs. */
+export interface FusionSessionOutputs {
+    /**
+     * Delivers a frame to one client.
+     * @param clientKey The receiving client's session id.
+     * @param sourcePlayerId The sending player (0 = the session).
+     * @param frame The frame.
+     * @param channel The TOOLKIT.RpcChannel it travels on (default Reliable); Unreliable may go as a datagram (D7).
+     */
+    sendFrame(clientKey: string, sourcePlayerId: number, frame: Uint8Array, channel?: number): void;
+    /**
+     * Delivers a control message to one client.
+     * @param clientKey The receiving client's session id.
+     * @param name The control message name.
+     * @param payload The JSON-able payload.
+     */
+    sendControl(clientKey: string, name: string, payload: object): void;
+    /**
+     * Publishes the session description (lobby listing).
+     * @param session The description.
+     */
+    setSessionMetadata(session: FusionSessionInfo): void;
+    /**
+     * Locks or unlocks the session against new joins.
+     * @param locked True when full or closed.
+     */
+    lockSession(locked: boolean): void;
+    /** @returns The session clock, in milliseconds. */
+    nowMilliseconds(): number;
+}
+/** The rules of one networked session, as TOOLKIT.FusionSessionLogic (the members the room calls). */
+export interface FusionSessionLogicApi {
+    /**
+     * Admits a joining client.
+     * @throws Error named after the TOOLKIT.ShutdownReason that refuses the join.
+     */
+    join(clientKey: string, request: FusionConnectRequest): FusionWelcome;
+    /** Routes a client's envelope (route byte + uint16 target + frame) received on a TOOLKIT.RpcChannel (default Reliable, D7). */
+    receiveFrame(clientKey: string, payload: Uint8Array, channel?: number): void;
+    /** Applies a client's control message. */
+    receiveControl(clientKey: string, name: string, payload: object): void;
+    /** Expires reconnect holds. */
+    update(nowMilliseconds: number): void;
+    /** Holds a dropped client's slot for a reconnect. */
+    drop(clientKey: string): void;
+    /** Removes a client for good (during a host migration: holds its slot for the restarted runner). */
+    leave(clientKey: string): void;
+    /** True while a host migration waits for the elected host to rejoin (D31). */
+    readonly isMigratingHost: boolean;
+    /** The session's TOOLKIT.GameMode, or null before the first join. */
+    readonly gameMode: number | null;
+    /** Every player the session knows, connected or held for a reconnect (game-server-admin-console DR §6.6). */
+    readonly players: FusionSessionPlayer[];
+    /** The Shared-mode master client's player id, or 0 when there is none. */
+    readonly masterClientPlayerId: number;
+    /**
+     * Makes a dedicated server runner the session's authority (A17): it is player 0 and answers connect requests.
+     * @param endpoint The server runner's side of the session.
+     * @param request The server runner's connect request (session name, players, tick rate, prefab table hash).
+     * @returns The server runner's welcome.
+     */
+    attachDedicatedServer(endpoint: FusionSessionServerEndpoint, request: FusionConnectRequest): FusionWelcome;
+    /** Sends a frame from the dedicated server on a TOOLKIT.RpcChannel: ToPlayer to that client, any other route to every client. */
+    sendFromServer(route: number, targetPlayerId: number, frame: Uint8Array, channel?: number): void;
+    /** Sends a control message from the dedicated server to one player, or to everyone with target 0. */
+    sendControlFromServer(name: string, payload: object, targetPlayerId: number): void;
+}
+/** One player of a session, as TOOLKIT.FusionSessionClient. */
+export interface FusionSessionPlayer {
+    /** The client's session id. */
+    clientKey: string;
+    /** The player id. */
+    playerId: number;
+    /** False while the player is held for a reconnect. */
+    connected: boolean;
+    /** True for the Host-mode host. */
+    isHost: boolean;
+}
+/** The dedicated runner's side of a session, as TOOLKIT.FusionSessionServerEndpoint (T13). */
+export interface FusionSessionServerEndpoint {
+    /** Receives a frame a player sent to the server. */
+    receiveFrame(sourcePlayerId: number, frame: Uint8Array): void;
+    /** Receives a control message for the server. */
+    receiveControl(name: string, payload: object): void;
+}
+/** The Babylon Toolkit Networking members of the runtime's TOOLKIT namespace the server uses (built into the toolkit bundle). */
+export interface NetworkingToolkitApi {
+    /** The session rules class (D10). */
+    FusionSessionLogic: new (outputs: FusionSessionOutputs) => FusionSessionLogicApi;
+    /** The wire codecs; the room prefixes room-to-client frames with their source player (D11). */
+    NetworkProtocol: {
+        prefixSource(sourcePlayerId: number, frame: Uint8Array): Uint8Array;
+    };
+    /** Bytes message type of client-to-room frames. */
+    FUSION_BYTES_TO_ROOM: number;
+    /** Bytes message type of room-to-client frames. */
+    FUSION_BYTES_FROM_ROOM: number;
+    /** Seconds a dropped player's slot is held for a reconnect. */
+    NETWORK_RECONNECT_GRACE_SECONDS: number;
+    /** Version of the wire format and session rules; client and server must match (D5). */
+    NETWORK_PROTOCOL_VERSION: number;
+    /** Message type of client-to-room frames on the unreliable channel (D7). */
+    FUSION_UNRELIABLE_TO_ROOM: number;
+    /** Message type of room-to-client frames on the unreliable channel (D7). */
+    FUSION_UNRELIABLE_FROM_ROOM: number;
+    /** Largest prefixed frame, in bytes, sent as a datagram (D7). */
+    NETWORK_MAX_UNRELIABLE_FRAME_BYTES: number;
+    /** Session property naming the dedicated scene a Client-mode join starts on demand (D19). */
+    NETWORK_DEDICATED_SCENE_PROPERTY: string;
+    /** The delivery channels, as TOOLKIT.RpcChannel. */
+    RpcChannel: {
+        Reliable: number;
+        Unreliable: number;
+    };
+    /** The shutdown reasons by name, as TOOLKIT.ShutdownReason. */
+    ShutdownReason: Record<string, number>;
+    /** The game modes the server checks, as TOOLKIT.GameMode (a TypeScript enum, so it also maps values to names). */
+    GameMode: {
+        Client: number;
+        Server: number;
+        Shared: number;
+        [value: number]: string;
+    };
+    /** Control message that ends the session for its receiver. */
+    FUSION_CONTROL_SHUTDOWN: string;
+    /** Control message of a notice from the server's operators (protocol 2, game-server-admin-console D13). */
+    FUSION_CONTROL_NOTICE: string;
+}
+/** The runtime globals the server shares with the browser build. */
+export interface ToolkitGlobals {
+    /** The Babylon.js namespace (babylonjs, with loaders and GUI). */
+    BABYLON: object;
+    /** The toolkit namespace of the UMD bundle, with Babylon Toolkit Networking built in. A game's own classes are PROJECT's. */
+    TOOLKIT: NetworkingToolkitApi;
+}
+/**
+ * Loads the browser runtime into Node (D25): babylonjs, its loaders and GUI, then the toolkit UMD bundle, which publishes
+ * TOOLKIT (networking included) on globalThis. The session logic and protocol the server runs are therefore the same code as the
+ * browser's. Loads once; later calls return the same globals.
+ * @returns The BABYLON and TOOLKIT namespaces.
+ */
+export declare function loadToolkitRuntime(): Promise<ToolkitGlobals>;
+/**
+ * The loaded runtime, for code that runs after createGameServer has loaded it (rooms).
+ * @returns The runtime globals.
+ * @throws Error when loadToolkitRuntime has not completed.
+ */
+export declare function getToolkitRuntime(): ToolkitGlobals;
+/** The engine of a headless scene: a Babylon.js NullEngine. */
+export interface HeadlessEngine {
+    /** The device limits the engine reports (a NullEngine invents them). */
+    getCaps(): {
+        maxTexturesImageUnits: number;
+    };
+    /** Calls the render function every frame (timer-driven in Node). */
+    runRenderLoop(renderFunction: () => void): void;
+    /** Stops every render loop. */
+    stopRenderLoop(): void;
+    /** Releases the engine and its scenes. */
+    dispose(): void;
+}
+/** A headless scene: a Babylon.js Scene on a NullEngine. */
+export interface HeadlessScene {
+    /** The scene's cameras; Babylon renders a frame only with one. */
+    readonly cameras: object[];
+    /** Renders one frame (scripts, physics, the network runner's ticks; nothing is drawn). */
+    render(): void;
+    /** Resolves once the scene is ready. */
+    whenReadyAsync(): Promise<void>;
+    /** Releases the scene. */
+    dispose(): void;
+}
+/** A loaded headless scene and its engine. */
+export interface HeadlessSceneHandle {
+    /** The NullEngine. */
+    engine: HeadlessEngine;
+    /** The scene, with its render loop running. */
+    scene: HeadlessScene;
+}
+/** A Babylon.js scene loader plugin, as the glTF loader exposes it to OnPluginActivatedObservable. */
+interface HeadlessLoaderPlugin {
+    /** The plugin name ("gltf" for the glTF loader). */
+    name: string;
+    /** True to load no materials (and so no textures). */
+    skipMaterials?: boolean;
+    /** Maps every URL the loader fetches (buffers, images) before it is loaded. */
+    preprocessUrlAsync?: (url: string) => Promise<string>;
+}
+/** The parts of BABYLON.SceneLoader the headless runtime adapts. */
+interface HeadlessSceneLoaderApi {
+    /** Notifies every activated loader plugin. */
+    OnPluginActivatedObservable: {
+        add(callback: (plugin: HeadlessLoaderPlugin) => void): unknown;
+    };
+    /** The scene loader's entry points, by name. */
+    [entryPoint: string]: unknown;
+}
+/** The parts of Babylon.js the headless runtime drives. */
+interface HeadlessBabylonApi {
+    /** The engine class that renders nothing. */
+    NullEngine: new () => HeadlessEngine;
+    /** The camera class engine.html adds to a scene without a camera. */
+    FreeCamera: new (name: string, position: object, scene: HeadlessScene) => object;
+    /** The vector class. */
+    Vector3: new (x: number, y: number, z: number) => object;
+    /** Script loading, replaced by the Node script loader. */
+    Tools: {
+        LoadScriptAsync: (scriptUrl: string, scriptId?: string) => Promise<void>;
+        LoadScript: (scriptUrl: string, onSuccess?: () => void, onError?: (message?: string, exception?: unknown) => void, scriptId?: string) => void;
+    };
+    /** The scene loader. */
+    SceneLoader: HeadlessSceneLoaderApi;
+}
+/**
+ * Adds URL prefixes to the allow-list of the fetch helpers (D19). The first call turns the allow-list on: from then on
+ * only data: URLs and URLs under an allowed prefix load.
+ * @param prefixes The URL prefixes (scene roots and project scripts); none turns the allow-list on with only data: URLs.
+ */
+export declare function allowScriptUrlPrefixes(prefixes: string[]): void;
+/**
+ * Turns the allow-list off again (every URL allowed), as before any game server ran. createGameServer's close calls it.
+ */
+export declare function resetScriptUrlAllowList(): void;
+/**
+ * Whether the fetch helpers may load a URL (D19).
+ * @param url The URL.
+ * @returns True for a data: URL, for any URL while the allow-list is off, else when the URL starts with an allowed prefix.
+ */
+export declare function isUrlAllowed(url: string): boolean;
+/**
+ * The cache key of a script URL: its lower-cased file name, as the toolkit keys its project bundles (CanvasTools.ts).
+ * @param scriptUrl The script URL.
+ * @returns The key.
+ */
+export declare function scriptCacheKey(scriptUrl: string): string;
+/**
+ * Loads a script in Node, as Babylon's LoadScriptAsync does in a page (T13 step 2): fetches it and runs it in this context,
+ * once per file name; a file name already loaded resolves at once.
+ * @param scriptUrl The script URL.
+ * @returns Resolves once it ran.
+ * @throws Error when the server answers with an error status (the toolkit then warns that the bundle was not found), or
+ *     when the URL is not on the dedicated allow-list (D19).
+ */
+export declare function loadNodeScriptAsync(scriptUrl: string): Promise<void>;
+/**
+ * Replaces Babylon's DOM-based loaders with Node ones, once (T13 step 2): BABYLON.Tools.LoadScriptAsync / LoadScript use
+ * the Node script loader, so the toolkit's project bundle auto-load works unchanged; BABYLON.SceneLoader's entry points
+ * fetch the scene file over HTTP and hand it over as data, and the glTF loader fetches its buffers the same way and loads
+ * no materials (no textures headless). Babylon's own versions use a script element and XMLHttpRequest, which Node lacks.
+ * @param babylon The BABYLON namespace.
+ */
+export declare function installNodeLoaders(babylon: HeadlessBabylonApi): void;
+/**
+ * Loads an exported toolkit scene headless (T13 step 2): the same .gltf the browser loads, fetched over HTTP, on a
+ * NullEngine with Havok, the toolkit runtime initialised without a page (A18) and no materials or textures; the scene's
+ * project script bundle auto-loads through the Node script loader. As engine.html does, a scene without a camera gets a
+ * default one and the render loop starts; it resolves once the toolkit has created the scene's components and the scene
+ * is ready (TOOLKIT.SceneManager.WhenSceneReady).
+ * @param sceneRootUrl The folder URL of the scene: http(s):// (for example "http://localhost:8877/scenes/") or file://.
+ * @param sceneFile The scene file (for example "networktestbed.gltf").
+ * @param onFrameRendered Receives each frame's duration in seconds (the dedicated frame metrics, D16).
+ * @returns The engine and the ready, rendering scene.
+ * @throws Error when the toolkit does not report the scene ready.
+ */
+export declare function loadHeadlessScene(sceneRootUrl: string, sceneFile: string, onFrameRendered?: (seconds: number) => void): Promise<HeadlessSceneHandle>;
+export {};