@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/CUSTOM.md

@@ -0,0 +1,1690 @@
+# Running your own code on the Babylon Game Server
+
+`@babylonjs-toolkit/server` runs every multiplayer session of a Babylon Toolkit game, and it holds no code of any one
+game. This guide is for developers who installed it for their game and now need some code of their own on the server:
+what kind of code that usually is, where each kind runs, and how to write it. Every API named here is in the package
+or in the Babylon Toolkit runtime; where something you might want does not exist, the guide says so and names the
+closest thing that does.
+
+Read the [README](README.md) first for installing, configuring and deploying the server.
+
+## Contents
+
+- [What server-side code does a game need?](#what-server-side-code-does-a-game-need)
+- [The design rule: one server for every game](#the-design-rule-one-server-for-every-game)
+- [Choosing a mechanism](#choosing-a-mechanism)
+- [1. Dedicated Server-mode sessions: your gameplay code on the server](#1-dedicated-server-mode-sessions-your-gameplay-code-on-the-server)
+  - [What runs](#what-runs)
+  - [Configure the scenes](#configure-the-scenes)
+  - [Four ways to start a session](#four-ways-to-start-a-session)
+  - [How your scripts are loaded](#how-your-scripts-are-loaded)
+  - [What the headless runtime has, and what it lacks](#what-the-headless-runtime-has-and-what-it-lacks)
+  - [Writing code that runs on the server](#writing-code-that-runs-on-the-server)
+  - [Complete example: an arena with a server-side referee](#complete-example-an-arena-with-a-server-side-referee)
+  - [Getting results out of a session, and logging](#getting-results-out-of-a-session-and-logging)
+  - [Limits, metrics and lifetime](#limits-metrics-and-lifetime)
+- [2. Server hooks](#2-server-hooks)
+- [3. Custom HTTP endpoints](#3-custom-http-endpoints)
+- [4. Wrapping the server in your own Node app](#4-wrapping-the-server-in-your-own-node-app)
+- [5. Custom auth: verifyToken and the webhook](#5-custom-auth-verifytoken-and-the-webhook)
+- [Custom admin actions, panels and admin hooks](#custom-admin-actions-panels-and-admin-hooks)
+- [Security](#security)
+- [Testing your code locally](#testing-your-code-locally)
+- [Versioning](#versioning)
+- [Limits and what is not supported](#limits-and-what-is-not-supported)
+
+## What server-side code does a game need?
+
+Most multiplayer games end up needing some of these. Each maps to one mechanism of the server.
+
+| Kind of code | Examples | Mechanism |
+|---|---|---|
+| **Gameplay authority** | Physics, hit detection, movement limits, scoring, round timers, spawning, AI and bots, input validation and anti-cheat | [Dedicated Server-mode session](#1-dedicated-server-mode-sessions-your-gameplay-code-on-the-server): your game's own script components, run headless on the server |
+| **Persistence** | Match results, player stats, progression | Dedicated-session code reports results ([bridge or `fetch`](#getting-results-out-of-a-session-and-logging)); [hooks](#2-server-hooks) record who played; [routes](#3-custom-http-endpoints) serve the data. Leaderboards are built in: [README › Leaderboards](README.md#leaderboards) |
+| **Identity and access** | Checking logins, banning accounts or addresses, invite-only rooms | [`verifyToken` or the auth webhook](#5-custom-auth-verifytoken-and-the-webhook); per session, `onConnectRequest` in the dedicated session |
+| **Operations and integration** | Analytics, Discord or Slack notices, a status page, a "create private room" button, starting sessions on a schedule | [Hooks](#2-server-hooks), [routes](#3-custom-http-endpoints), the [admin console and its API](README.md#admin-console) and [custom admin actions](#custom-admin-actions-panels-and-admin-hooks), in [your own Node app](#4-wrapping-the-server-in-your-own-node-app) |
+
+## The design rule: one server for every game
+
+The server never contains your game. It loads the Babylon Toolkit runtime headless, with Babylon Toolkit Networking
+built in (the `TOOLKIT` namespace), and runs the same session code as the browser. Your code reaches it in exactly
+these ways:
+
+1. **Dedicated Server-mode sessions.** The server loads your exported scene and your game's script bundle and
+   simulates the game itself. This is the only place where **your gameplay code** runs on the server.
+2. **Server hooks.** Functions you pass to `createGameServer` that hear about sessions and players coming and going.
+3. **Custom HTTP endpoints.** Routes you pass to `createGameServer`, served on the game server's own port.
+4. **Your own Node app around the server.** A `server.mjs` that calls `createGameServer` with the above, plus whatever
+   else your process needs.
+5. **Custom auth.** A `verifyToken` hook in your app, or an auth webhook: a service of yours that approves each join.
+
+Items 2 to 5 need you to start the server from code (`createGameServer`). The `babylon-game-server` CLI and the plain
+Docker image run no code of yours except dedicated-session scripts.
+
+## Choosing a mechanism
+
+In Shared, Host/Client and AutoHostOrClient sessions the game logic runs **in the players' browsers**. The server only
+relays their messages, and in Shared mode keeps the latest state of each object for late joiners. So **server-side
+game logic means a dedicated Server-mode session**.
+
+| I want to … | Mechanism | Runs where | Authoritative? |
+|---|---|---|---|
+| Simulate physics and movement that players cannot fake | Dedicated session: a `TOOLKIT.NetworkBehaviour` in your script bundle | Dedicated session (server process) | Yes |
+| Run AI or bots | Dedicated session: objects the server spawns and simulates | Dedicated session | Yes |
+| Validate input, stop speed hacks | Dedicated session: clamp input in `fixedUpdateNetwork` | Dedicated session | Yes |
+| Keep score, run round timers, decide who wins | Dedicated session | Dedicated session | Yes |
+| Spawn and despawn players and items | Dedicated session (`runner.spawn`) | Dedicated session | Yes |
+| The same gameplay without a dedicated server | The same scripts in Host/Client mode | The host player's browser | Only as far as you trust the host |
+| Casual co-op where cheating does not matter | Shared mode | Every browser, each for its own objects | No |
+| Save match results to a database | Dedicated-session code calls your [bridge](#getting-results-out-of-a-session-and-logging) or `fetch`es your backend | Dedicated session, then server process | Yes: the numbers come from the server's simulation |
+| Count players, time sessions, send analytics | `onSessionCreated` / `onPlayerJoined` / `onPlayerLeft` / `onSessionClosed` | Server process | Yes for who joined and left; hooks see no game state |
+| Post "match started" to Discord | Hooks | Server process | Not game state |
+| Ban an account or address | `verifyToken` (auth mode `custom`) or the auth webhook | Server process, or your service | Yes, at join time |
+| Refuse a joiner by game rules (team full, not invited) | `onConnectRequest` → `request.refuse()` | Dedicated session (or the host's browser) | Yes in a dedicated session |
+| Serve custom stats or a status page (leaderboards are built in) | `routes` | Server process | Not applicable |
+| Create a private room | A route that hands out a session name for an on-demand scene, or calls `startDedicatedSession` | Server process | Not applicable |
+| Read or change the messages players send each other | Not supported | — | Use a dedicated session: the server then owns the state |
+| Swap game code without a restart | Not supported | — | Restart the process |
+
+## 1. Dedicated Server-mode sessions: your gameplay code on the server
+
+### What runs
+
+A dedicated session is one `fusion_session` room whose authority is a headless `TOOLKIT.NetworkRunner` in
+`TOOLKIT.GameMode.Server`:
+
+- It loads **the same exported scene file the browsers load**, from a folder or URL you configure.
+- The scene's own **project script bundle** (the exporter's `PROJECT` bundle, your game classes) loads with it, plus any
+  extra bundles you list.
+- It runs on a Babylon.js `NullEngine` with Havok physics, with no materials or textures (nothing is drawn).
+- The server runner simulates every networked object and is player 0. Players join with `GameMode.Client` and the
+  session name, send input, predict locally, and keep the server's result.
+
+Your script components run there exactly as in a browser: `awake`, `start`, `update`, and for network behaviours
+`spawned`, `fixedUpdateNetwork`, `render` and the runner callbacks.
+
+### Configure the scenes
+
+Dedicated scenes are listed in the config file only (there is no environment variable or flag for them, apart from the
+legacy single-session flags in the README):
+
+```js
+// babylon-game-server.config.mjs
+export default {
+    dedicated: {
+        scenes: [
+            { name: "arena", sceneRoot: "./scenes/arena/", sceneFile: "Arena.gltf", projectScripts: [], maxPlayers: 8, onDemand: true, idleSeconds: 60 }
+        ],
+        boot: [
+            { sessionName: "arena-1", sceneName: "arena" }
+        ]
+    }
+};
+```
+
+| Field | Meaning | Default |
+|---|---|---|
+| `name` | The name clients, the admin API and `startDedicatedSession` use | required |
+| `sceneRoot` | An `http(s)://` URL or a folder. A folder becomes a `file://` URL, resolved against the **process working directory** (not the config file's folder) | required |
+| `sceneFile` | The exported scene file in that folder (`.gltf` or `.glb`) | required |
+| `projectScripts` | Extra script bundles, loaded in order **before** the scene. URLs or paths (paths resolve like `sceneRoot`) | `[]` |
+| `maxPlayers` | Most players the session accepts | `8` |
+| `onDemand` | `true` lets a Client join start a session of this scene | `false` |
+| `idleSeconds` | Seconds an **on-demand** session stays open once empty (after the reconnect grace) | `60` |
+
+`dedicated.boot` entries are `{ sessionName, sceneName }`. The config is validated at startup: a duplicate scene name,
+a boot entry naming an unknown scene, or a missing field stops the server with exit code 2.
+
+### Four ways to start a session
+
+| How | Call | Closes |
+|---|---|---|
+| **At boot** | Each `dedicated.boot` entry starts once the server listens. A boot session that fails to load stops the server (`createGameServer` rejects). | Never by itself |
+| **On demand** | A `GameMode.Client` join whose `sessionProperties.dedicatedScene` names a scene with `onDemand: true` creates the session (one per session name, however many join at once). The sample launcher sends it from `?fusionDedicatedScene=`. | When empty for `TOOLKIT.NETWORK_RECONNECT_GRACE_SECONDS` (20) plus `idleSeconds` |
+| **Admin API** | `POST /game-server/admin/dedicated` with `{ "sceneName": "arena", "sessionName": "arena-7" }` and `Authorization: Bearer <admin token>`. Answers 201 `{ roomId }`, 400, 404 (unknown scene) or 503 (it did not start). | Never by itself |
+| **From your code** | `await server.startDedicatedSession(sessionName, sceneName)` on the object `createGameServer` returned; resolves the room id | Never by itself |
+
+In game code, the on-demand join looks like this (`TOOLKIT.NETWORK_DEDICATED_SCENE_PROPERTY` is `"dedicatedScene"`):
+
+```ts
+const result: TOOLKIT.StartGameResult = await runner.startGame({
+    gameMode: TOOLKIT.GameMode.Client,
+    sessionName: "arena-7",
+    sessionProperties: { [TOOLKIT.NETWORK_DEDICATED_SCENE_PROPERTY]: "arena" },
+    config: { serverUrl: "wss://game.example.com" }
+});
+```
+
+Things to know:
+
+- Sessions started at boot, by the admin API or by `startDedicatedSession` **never close by themselves**. Close them
+  with `POST /game-server/admin/sessions/:roomId/close` (admin token), or they run until the process stops.
+- Neither the admin API nor `startDedicatedSession` checks whether a session of that name already exists. Starting
+  the same name twice gives two rooms, and Client joins land in either. Use unique names.
+- An on-demand join of a scene that is not configured, or not `onDemand`, is refused with
+  `GameNotFound: no on-demand dedicated scene named <name>`. A scene that fails to load refuses its joiners with
+  `GameNotFound: the dedicated scene <name> failed to load`, and the server log says why.
+- **Advanced:** the exported class `DedicatedSession` has `DedicatedSession.start({ sessionName, sceneRootUrl,
+  sceneFile, playerCount, projectScripts })`, which runs a scene that is **not** in the config. It needs a running
+  server, takes URLs only (`http(s)://` or `file://`, no plain paths), and adds them to the allow-list for the rest of
+  the process. The admin API cannot start such scenes, and they never close by themselves.
+
+### How your scripts are loaded
+
+When a dedicated session starts, the server:
+
+1. Loads each `projectScripts` entry in order.
+2. Loads the scene. The toolkit's glTF loader reads the scene's metadata and loads its project bundle (the exporter's
+   `PROJECT` bundle, the file the metadata names) **from the same `sceneRoot`**, exactly as a browser page does.
+3. Creates the scene's script components and waits until the scene is ready.
+4. Only then creates the Server-mode runner and starts it, which registers the scene's networked objects (their
+   `spawned()` runs now) and opens the session to players.
+
+How a script runs:
+
+- Each file is fetched (or read from disk for `file://`) and run with Node's `vm.runInThisContext`: a **classic
+  script in the server's own global scope**, where `BABYLON` and `TOOLKIT` are globals. That is the form of the
+  exporter's UMD project bundle (`namespace MY { … }` classes that call `TOOLKIT.SceneManager.RegisterClass`).
+- **ES modules do not run.** A file with `import` / `export` statements fails, and dynamic `import()` throws
+  `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`. Game classes written for an ESM web app (`@babylonjs-toolkit/next`) must
+  also be built into a classic bundle to run on the server.
+- **Each file loads once per process**, keyed by its lower-cased file name. A second session of the same scene reuses
+  the classes already loaded; a re-exported bundle is not picked up until the process restarts.
+- **The URL allow-list.** Once the server runs, the headless runtime only fetches `data:` URLs and URLs under a
+  configured `sceneRoot` or `projectScripts` entry. Anything else fails with `URL is not on the dedicated allow-list:
+  <url>`. Keep every file the scene needs (buffers, the project bundle, prefab asset containers) under its `sceneRoot`.
+  The allow-list guards only these loaders; your own code's `fetch` is not restricted.
+- A project bundle that fails to load only logs a warning (`CVTOOLS: project script bundle not found: …`); the scene
+  still loads, its components then fail with `Failed to locate script class: …`. Watch for both in the log.
+
+Server-only classes: a `projectScripts` bundle can hold classes that browsers never download. A component authored on
+a scene node whose class only that bundle defines then runs on the server, and browsers log
+`Failed to locate script class: <name>` for it and carry on.
+
+### What the headless runtime has, and what it lacks
+
+| Available on the server | Not available on the server |
+|---|---|
+| `BABYLON` (with the glTF loader; `BABYLON.GUI` is loaded too, but nothing is drawn) | `window`, `document` and every DOM API (`typeof window === "undefined"`) |
+| `TOOLKIT`, with Babylon Toolkit Networking | Materials and textures: the glTF loader skips them, so meshes have no material |
+| Your scene graph, meshes and colliders | Drawing anything: the `NullEngine` renders nothing |
+| Havok physics (`globalThis.HavokPhysics`, `globalThis.HK`) | Keyboard, mouse, touch and gamepad input (`TOOLKIT.InputController` is not enabled, and enabling it needs a DOM) |
+| Script component lifecycle, the network tick, physics steps, node animation | Web Audio, so no sound |
+| Node's globals: `process`, `fetch`, `setTimeout` / `setInterval`, `console`, `Buffer`, `URL`, `TextEncoder`, `crypto`, `performance` | `require` and `import()` (classic script, see above) |
+| `process.getBuiltinModule("node:fs")` and the other built-in modules (Node 22.3+) | A separate sandbox: scripts share the server's global scope |
+
+Frames are driven by Node timers (Babylon.js falls back to `setTimeout(…, 16)` without `requestAnimationFrame`), so a
+session renders about 60 frames per second. The runner runs the due network ticks each frame (60 Hz by default, at most
+8 per frame).
+
+### Writing code that runs on the server
+
+**Know where you are.** The runner tells you:
+
+| Member | True when |
+|---|---|
+| `runner.isServer` | `Single`, `Server` or `Host` mode: this peer has state authority over what it simulates |
+| `runner.isClient` | A Client or Shared peer |
+| `runner.isPlayer` | Any mode except `Server`: there is a local player, a screen and input |
+| `runner.gameMode === TOOLKIT.GameMode.Server` | Only on a dedicated server |
+| `typeof window === "undefined"` | In the headless runtime, before any runner exists |
+
+Use `isServer` for authority logic (it is also true on a Host, so the same code serves Host/Client games), and
+`gameMode === TOOLKIT.GameMode.Server` only for code that must never run in a player's browser. Guard every piece of
+presentation (DOM, GUI, audio, cameras, particles, input) with `runner.isPlayer`.
+
+**Register the input struct when the bundle loads.** No launcher starts the dedicated runner, so it decodes player
+input with the default definition. Call this at the top level of your bundle, not inside a component:
+
+```ts
+TOOLKIT.NetworkRunner.setDefaultInputDefinition(ARENA_INPUT_DEFINITION);
+```
+
+Without it the server ignores every player's input. The default definition is **process-wide**: every dedicated
+session in one process uses the last one registered.
+
+**Get hold of the server's runner.** Two patterns work:
+
+- **A network behaviour on a scene object (recommended).** Put a `NetworkObject` and your `TOOLKIT.NetworkBehaviour` on
+  a node in the scene. When the runner starts it registers the scene's networked objects, so the behaviour's
+  `spawned()` runs on every peer with `this.runner` set. On the server, call `this.runner.addCallbacks(this)` there to
+  receive `onPlayerJoined`, `onPlayerLeft`, `onConnectRequest` and the rest.
+- **Adopting the runner from a plain script component**, as the toolkit's networking sample launcher does. On a
+  dedicated server, `start()` runs before the runner exists (the runner is created once the scene is ready), so look
+  for it in `update()` until it appears:
+  `TOOLKIT.NetworkRunner.instances.find((runner) => runner.scene === this.scene && runner.isRunning)`, then
+  `addCallbacks(this)` and call your `onPlayerJoined` for `runner.activePlayers` already present.
+
+**Rules that matter more on a server:**
+
+- Gameplay state lives in networked properties (`getNetworkedProperties()`), simulated in `fixedUpdateNetwork()`.
+  Clients predict and re-simulate; the server never re-simulates, so **server-only** code may keep plain fields
+  (cooldown maps, user ids) without breaking prediction.
+- Code that only the server runs (random crown positions, scoring, spawning) is not predicted by clients: they see its
+  result one round trip later. Keep movement that must feel instant in the object's own `fixedUpdateNetwork`, which
+  the owner's browser predicts, and validate there (the server's run is the one that counts).
+- RPCs default to `invokeLocal: true`, so an RPC with `targets: RpcTargets.All` sent by the server also runs its
+  receiver on the server. Guard presentation in receivers with `this.runner.isPlayer`.
+- Classes and top-level variables of a bundle are **shared by every dedicated session in the process** (one global
+  scope). Keep per-session state on component instances or keyed by scene, never in top-level variables. Static RPCs
+  (`registerStaticRpc`) and the default input definition are process-wide too. Run games with different input
+  structs in different processes.
+- **An exception thrown in a frame ends the process**, and with it every session it hosts (it is an uncaught exception
+  in a timer callback). Write server code defensively, and run the server under a supervisor that restarts it
+  (Docker, Kubernetes, systemd, your platform).
+
+### Complete example: an arena with a server-side referee
+
+A small king-of-the-hill game. Players move with WASD and press Space next to the crown to claim it. The server alone
+decides claims, moves the crown, keeps score, runs a 90-second round timer, announces the winner by RPC and reports the
+result to the server process.
+
+Authoring in Unity (Add Component → Babylon Toolkit → Content Components → Network for the network components):
+
+- A `NetworkSettings` component in the scene, with the avatar prefab's asset container in its prefab containers.
+- A node with `MY.ArenaLauncher` (the browser's join).
+- A node named `Referee` with `NetworkObject` and `MY.ArenaReferee`.
+- A node named `Crown` with `NetworkObject` and `NetworkTransform`.
+- A prefab named `ArenaAvatar` with `NetworkObject`, `NetworkTransform` and `MY.ArenaAvatar`.
+
+The four scripts are project scripts, compiled by the exporter into the scene's project bundle, so browsers and the
+server run the same code.
+
+`ArenaInput.ts`, the input struct and the server bridge interface:
+
+```ts
+namespace MY {
+    /** Button bit of the claim action in the arena input struct. */
+    export const ARENA_BUTTON_CLAIM: number = 0;
+
+    /** One tick of a player's input. Clients send it; the server reads it. */
+    export interface ArenaInput {
+        /** The claim button. */
+        buttons: TOOLKIT.NetworkButtons;
+        /** Move direction on X, from -1 to 1. */
+        moveX: number;
+        /** Move direction on Z, from -1 to 1. */
+        moveZ: number;
+    }
+
+    /** The input struct's networked fields, identical in every browser and on the server. */
+    export const ARENA_INPUT_DEFINITION: TOOLKIT.NetworkedStructDefinition = {
+        buttons: TOOLKIT.Networked.buttons(),
+        moveX: TOOLKIT.Networked.float(),
+        moveZ: TOOLKIT.Networked.float()
+    };
+
+    // No launcher starts the dedicated runner, so the bundle registers the input struct when it loads.
+    TOOLKIT.NetworkRunner.setDefaultInputDefinition(ARENA_INPUT_DEFINITION);
+
+    /** What server.mjs puts on globalThis for server-side game code. Absent in browsers and under the plain CLI. */
+    export interface ArenaServerBridge {
+        /**
+         * Receives a finished round.
+         * @param result The round's outcome.
+         */
+        reportRoundResult(result: ArenaRoundResult): void;
+        /**
+         * Writes a line to the game server's structured log.
+         * @param message What happened.
+         * @param fields Context fields.
+         */
+        log(message: string, fields?: Record<string, unknown>): void;
+    }
+
+    /** A finished round, as the referee reports it. */
+    export interface ArenaRoundResult {
+        /** The session the round was played in. */
+        sessionName: string;
+        /** The round number, from 1. */
+        roundNumber: number;
+        /** The winner's player id, or 0 when nobody scored. */
+        winnerPlayerId: number;
+        /** The winner's verified user id, or null (auth off, or nobody scored). */
+        winnerUserId: string | null;
+        /** Every player's score by player id. */
+        scores: Record<number, number>;
+    }
+
+    /**
+     * The server bridge, when the game server process provides one.
+     * @returns The bridge, or null.
+     */
+    export function findArenaServerBridge(): ArenaServerBridge | null {
+        const bridge: unknown = (globalThis as unknown as Record<string, unknown>)["ArenaServerBridge"];
+        return (bridge != null) ? bridge as ArenaServerBridge : null;
+    }
+}
+```
+
+`ArenaLauncher.ts`, browser only:
+
+```ts
+namespace MY {
+    /** The dedicated scene name in the server's dedicated.scenes, and the defaults the page query can override. */
+    const ARENA_SCENE_NAME: string = "arena";
+    const DEFAULT_SESSION_NAME: string = "arena-1";
+    const DEFAULT_SERVER_URL: string = "ws://localhost:2567";
+    /** Key codes the launcher reads. */
+    const KEY_W: number = 87;
+    const KEY_A: number = 65;
+    const KEY_S: number = 83;
+    const KEY_D: number = 68;
+    const KEY_SPACE: number = 32;
+
+    /**
+     * Joins the arena as a Client of a dedicated session and sends the keyboard as input. It does nothing on the
+     * server: there the session's own runner simulates the scene and the ArenaReferee runs the match.
+     */
+    export class ArenaLauncher extends TOOLKIT.ScriptComponent implements TOOLKIT.INetworkRunnerCallbacks {
+        /** The browser's runner, or null. */
+        private runner: TOOLKIT.NetworkRunner = null;
+
+        constructor(transform: BABYLON.TransformNode, scene: BABYLON.Scene, properties: any = {}, alias: string = "MY.ArenaLauncher") {
+            super(transform, scene, properties, alias);
+        }
+
+        /** Starts the browser's runner; a headless server has no window and returns at once. */
+        protected start(): void {
+            if (typeof window === "undefined") return;
+            if (!TOOLKIT.InputController.IsUserInputEnabled()) TOOLKIT.InputController.EnableUserInput(this.scene.getEngine(), this.scene);
+            this.join().catch((error: unknown) => console.error("[Arena] startGame threw", error));
+        }
+
+        /** Leaves the session with the scene. */
+        protected destroy(): void {
+            if (this.runner != null) void this.runner.shutdown();
+            this.runner = null;
+        }
+
+        /**
+         * Sends this tick's input: WASD moves, Space claims.
+         * @param runner The runner.
+         * @param input The tick's input to fill.
+         */
+        public onInput(runner: TOOLKIT.NetworkRunner, input: TOOLKIT.NetworkInput): void {
+            const buttons: TOOLKIT.NetworkButtons = new TOOLKIT.NetworkButtons(0).set(MY.ARENA_BUTTON_CLAIM, TOOLKIT.InputController.GetKeyboardInput(KEY_SPACE));
+            const moveX: number = (TOOLKIT.InputController.GetKeyboardInput(KEY_D) ? 1 : 0) - (TOOLKIT.InputController.GetKeyboardInput(KEY_A) ? 1 : 0);
+            const moveZ: number = (TOOLKIT.InputController.GetKeyboardInput(KEY_W) ? 1 : 0) - (TOOLKIT.InputController.GetKeyboardInput(KEY_S) ? 1 : 0);
+            const arenaInput: MY.ArenaInput = { buttons: buttons, moveX: moveX, moveZ: moveZ };
+            input.set(arenaInput);
+        }
+
+        /**
+         * Logs why the runner stopped.
+         * @param runner The runner.
+         * @param reason The reason.
+         */
+        public onShutdown(runner: TOOLKIT.NetworkRunner, reason: TOOLKIT.ShutdownReason): void {
+            console.log("[Arena] left the session: " + TOOLKIT.ShutdownReason[reason]);
+        }
+
+        /** Joins the session named by ?fusionSession= (the server starts it on demand when it does not exist yet). */
+        private async join(): Promise<void> {
+            const query: URLSearchParams = new URLSearchParams(window.location.search);
+            this.runner = new TOOLKIT.NetworkRunner(this.scene);
+            this.runner.addCallbacks(this);
+            const result: TOOLKIT.StartGameResult = await this.runner.startGame({
+                gameMode: TOOLKIT.GameMode.Client,
+                sessionName: query.get("fusionSession") ?? DEFAULT_SESSION_NAME,
+                sessionProperties: { [TOOLKIT.NETWORK_DEDICATED_SCENE_PROPERTY]: ARENA_SCENE_NAME },
+                config: { serverUrl: query.get("fusionServer") ?? DEFAULT_SERVER_URL },
+                authToken: query.get("fusionToken") ?? ""
+            });
+            if (!result.ok) console.error("[Arena] startGame failed: " + TOOLKIT.ShutdownReason[result.shutdownReason] + " " + result.errorMessage);
+        }
+    }
+    TOOLKIT.SceneManager.RegisterClass("MY.ArenaLauncher", ArenaLauncher);
+}
+```
+
+`ArenaAvatar.ts`, predicted movement with server-side validation:
+
+```ts
+namespace MY {
+    /** Avatar speed in m/s and the arena's radius in meters. */
+    const AVATAR_SPEED: number = 6;
+    const ARENA_RADIUS: number = 12;
+
+    /**
+     * A player's avatar (a prefab with NetworkObject + NetworkTransform). It moves itself from its owner's input, so the
+     * owner's browser predicts it and the server's result is the one everyone keeps. The score is written only by the
+     * server's ArenaReferee.
+     */
+    export class ArenaAvatar extends TOOLKIT.NetworkBehaviour {
+        /** Crowns claimed this round; the server writes it, every peer reads it. */
+        public declare score: number;
+
+        constructor(transform: BABYLON.TransformNode, scene: BABYLON.Scene, properties: any = {}, alias: string = "MY.ArenaAvatar") {
+            super(transform, scene, properties, alias);
+        }
+
+        /** Networked state. */
+        protected static getNetworkedProperties(): TOOLKIT.NetworkedPropertyDefinitions {
+            return {
+                score: TOOLKIT.Networked.int({ onChangedRender: "onScoreChanged" })
+            };
+        }
+
+        /** One tick: move along the input direction, never faster than AVATAR_SPEED, never outside the arena. */
+        public fixedUpdateNetwork(): void {
+            const input: MY.ArenaInput | null = this.getInput<MY.ArenaInput>();
+            if (input == null) return;
+            const direction: BABYLON.Vector3 = new BABYLON.Vector3(input.moveX, 0, input.moveZ);
+            const length: number = direction.length();
+            // A tampered client can send any float; normalising here is the server-side validation.
+            if (length > 1) direction.scaleInPlace(1 / length);
+            const position: BABYLON.Vector3 = this.transform.position;
+            position.addInPlace(direction.scaleInPlace(AVATAR_SPEED * this.runner.deltaTime));
+            const distanceFromCenter: number = Math.sqrt(position.x * position.x + position.z * position.z);
+            if (distanceFromCenter > ARENA_RADIUS) {
+                position.x *= ARENA_RADIUS / distanceFromCenter;
+                position.z *= ARENA_RADIUS / distanceFromCenter;
+            }
+        }
+
+        /** onChangedRender of score: presentation only, so the server skips it. */
+        public onScoreChanged(): void {
+            if (!this.runner.isPlayer) return;
+            console.log("[Arena] player " + this.object.inputAuthority.playerId + " has " + this.score);
+        }
+    }
+    TOOLKIT.SceneManager.RegisterClass("MY.ArenaAvatar", ArenaAvatar);
+}
+```
+
+`ArenaReferee.ts`, the server-only component: it reads player input, moves the crown, scores, times rounds and calls
+an RPC:
+
+```ts
+namespace MY {
+    /** The avatar prefab (in a NetworkSettings prefab container) and the crown's node name in the scene. */
+    const AVATAR_PREFAB_NAME: string = "ArenaAvatar";
+    const CROWN_NODE_NAME: string = "Crown";
+    /** Round rules: length in seconds, crowns to win, claim distance and cooldown, crown drop radius. */
+    const ROUND_SECONDS: number = 90;
+    const WINNING_SCORE: number = 5;
+    const CLAIM_DISTANCE: number = 2;
+    const CLAIM_COOLDOWN_SECONDS: number = 1;
+    const CROWN_DROP_RADIUS: number = 10;
+    /** Avatars spawn on a ring of this radius. */
+    const SPAWN_RADIUS: number = 6;
+
+    /**
+     * The match rules, on a scene object (NetworkObject + ArenaReferee). It exists on every peer, but all of its logic
+     * runs on the server only: spawning avatars, reading claims from player input, moving the crown, scoring, the round
+     * timer, and announcing the winner by RPC.
+     */
+    export class ArenaReferee extends TOOLKIT.NetworkBehaviour implements TOOLKIT.INetworkRunnerCallbacks {
+        /** Runs while a round lasts. */
+        public declare roundTimer: TOOLKIT.TickTimer;
+        /** The current round, from 1. */
+        public declare roundNumber: number;
+        /** The crown's NetworkTransform (server only), or null when the scene has no crown. */
+        private crown: TOOLKIT.NetworkTransform = null;
+        /** Claim cooldowns by player id (server only: the server never re-simulates, so plain fields are safe here). */
+        private readonly claimCooldowns: Map<number, TOOLKIT.TickTimer> = new Map<number, TOOLKIT.TickTimer>();
+        /** Verified user ids by player id, from onConnectRequest (server only). */
+        private readonly userIds: Map<number, string | null> = new Map<number, string | null>();
+
+        constructor(transform: BABYLON.TransformNode, scene: BABYLON.Scene, properties: any = {}, alias: string = "MY.ArenaReferee") {
+            super(transform, scene, properties, alias);
+        }
+
+        /** Networked state. */
+        protected static getNetworkedProperties(): TOOLKIT.NetworkedPropertyDefinitions {
+            return {
+                roundTimer: TOOLKIT.Networked.tickTimer(),
+                roundNumber: TOOLKIT.Networked.int()
+            };
+        }
+
+        /** RPCs: the server tells every player who won a round. */
+        protected static getRpcDefinitions(): TOOLKIT.RpcDefinitions {
+            return {
+                rpcRoundOver: TOOLKIT.Rpc.define({ sources: TOOLKIT.RpcSources.StateAuthority, targets: TOOLKIT.RpcTargets.All }, [TOOLKIT.Networked.int(), TOOLKIT.Networked.int()])
+            };
+        }
+
+        /** On the server: become a runner callback object, find the crown and start round 1. Elsewhere: nothing. */
+        public spawned(): void {
+            if (!this.runner.isServer) return;
+            this.runner.addCallbacks(this);
+            const crownNode: BABYLON.TransformNode = this.scene.getTransformNodeByName(CROWN_NODE_NAME);
+            this.crown = (crownNode != null) ? TOOLKIT.SceneManager.FindScriptComponent<TOOLKIT.NetworkTransform>(crownNode, "TOOLKIT.NetworkTransform") : null;
+            // Scene objects spawn when the runner starts, before anyone joins; this covers players already present anyway.
+            for (const player of this.runner.activePlayers) this.onPlayerJoined(this.runner, player);
+            this.startRound(1);
+        }
+
+        /**
+         * Records the server-verified identity of a joining player (null when the game server's auth is off).
+         * @param runner The runner.
+         * @param request The join request.
+         * @param token The client's connection token bytes.
+         */
+        public onConnectRequest(runner: TOOLKIT.NetworkRunner, request: TOOLKIT.NetworkConnectRequestArgs, token: Uint8Array): void {
+            const userId: unknown = (request.authIdentity != null) ? request.authIdentity["userId"] : null;
+            this.userIds.set(request.player.playerId, (typeof userId === "string") ? userId : null);
+        }
+
+        /**
+         * Spawns the joined player's avatar on a ring around the arena center.
+         * @param runner The runner.
+         * @param player The player who joined.
+         */
+        public onPlayerJoined(runner: TOOLKIT.NetworkRunner, player: TOOLKIT.PlayerRef): void {
+            if (runner.getPlayerObject(player) != null) return;
+            const angle: number = player.playerId * 1.7;
+            const position: BABYLON.Vector3 = new BABYLON.Vector3(Math.cos(angle) * SPAWN_RADIUS, 0, Math.sin(angle) * SPAWN_RADIUS);
+            const avatar: TOOLKIT.NetworkObject = runner.spawn(AVATAR_PREFAB_NAME, position, BABYLON.Quaternion.Identity(), player);
+            runner.setPlayerObject(player, avatar);
+        }
+
+        /**
+         * Removes the leaving player's avatar and bookkeeping.
+         * @param runner The runner.
+         * @param player The player who left.
+         */
+        public onPlayerLeft(runner: TOOLKIT.NetworkRunner, player: TOOLKIT.PlayerRef): void {
+            const avatar: TOOLKIT.NetworkObject | null = runner.getPlayerObject(player);
+            if (avatar != null) runner.despawn(avatar);
+            this.claimCooldowns.delete(player.playerId);
+            this.userIds.delete(player.playerId);
+        }
+
+        /** One server tick: end the round on time, else read every player's claim button. */
+        public fixedUpdateNetwork(): void {
+            if (!this.runner.isServer) return;
+            if (this.roundTimer.expired(this.runner)) {
+                this.endRound(this.findLeader());
+                return;
+            }
+            if (this.crown == null) return;
+            for (const avatar of this.runner.getAllBehaviours(MY.ArenaAvatar)) {
+                const player: TOOLKIT.PlayerRef = avatar.object.inputAuthority;
+                const input: MY.ArenaInput | null = this.runner.getInputForPlayer<MY.ArenaInput>(player);
+                if (input == null || !input.buttons.isSet(MY.ARENA_BUTTON_CLAIM)) continue;
+                const cooldown: TOOLKIT.TickTimer | undefined = this.claimCooldowns.get(player.playerId);
+                if (cooldown != null && !cooldown.expiredOrNotRunning(this.runner)) continue;
+                if (BABYLON.Vector3.Distance(avatar.transform.position, this.crown.transform.position) > CLAIM_DISTANCE) continue;
+                this.claimCooldowns.set(player.playerId, TOOLKIT.TickTimer.createFromSeconds(this.runner, CLAIM_COOLDOWN_SECONDS));
+                avatar.score = avatar.score + 1;
+                this.dropCrownSomewhereElse();
+                if (avatar.score >= WINNING_SCORE) {
+                    this.endRound(avatar);
+                    return;
+                }
+            }
+        }
+
+        /**
+         * Receives the round result on every peer (invokeLocal also runs it on the server, which has no screen).
+         * Calling this.rpcRoundOver(...) on the server SENDS it.
+         * @param winnerPlayerId The winner's player id, or 0.
+         * @param winningScore The winner's score.
+         * @param info Who sent it, and on which tick.
+         */
+        public rpcRoundOver(winnerPlayerId: number, winningScore: number, info?: TOOLKIT.RpcInfo): void {
+            if (!this.runner.isPlayer) return;
+            const isMe: boolean = winnerPlayerId === this.runner.localPlayer.playerId;
+            console.log("[Arena] round over: " + (winnerPlayerId === 0 ? "nobody scored" : (isMe ? "you won" : "player " + winnerPlayerId + " won")) + " with " + winningScore);
+        }
+
+        /**
+         * Starts a round: resets the timer and every score.
+         * @param roundNumber The round to start.
+         */
+        private startRound(roundNumber: number): void {
+            this.roundNumber = roundNumber;
+            this.roundTimer = TOOLKIT.TickTimer.createFromSeconds(this.runner, ROUND_SECONDS);
+            for (const avatar of this.runner.getAllBehaviours(MY.ArenaAvatar)) avatar.score = 0;
+            this.dropCrownSomewhereElse();
+        }
+
+        /**
+         * Announces and reports the round, then starts the next one.
+         * @param winner The winning avatar, or null when nobody scored.
+         */
+        private endRound(winner: MY.ArenaAvatar | null): void {
+            const winnerPlayerId: number = (winner != null) ? winner.object.inputAuthority.playerId : 0;
+            const winningScore: number = (winner != null) ? winner.score : 0;
+            this.rpcRoundOver(winnerPlayerId, winningScore);
+            const scores: Record<number, number> = {};
+            for (const avatar of this.runner.getAllBehaviours(MY.ArenaAvatar)) scores[avatar.object.inputAuthority.playerId] = avatar.score;
+            const bridge: MY.ArenaServerBridge | null = MY.findArenaServerBridge();
+            if (bridge != null) {
+                bridge.reportRoundResult({
+                    sessionName: this.runner.sessionInfo.name,
+                    roundNumber: this.roundNumber,
+                    winnerPlayerId: winnerPlayerId,
+                    winnerUserId: this.userIds.get(winnerPlayerId) ?? null,
+                    scores: scores
+                });
+            } else {
+                console.log("[Arena] round " + this.roundNumber + " won by player " + winnerPlayerId);
+            }
+            this.startRound(this.roundNumber + 1);
+        }
+
+        /** @returns The avatar with the highest score above 0, or null. */
+        private findLeader(): MY.ArenaAvatar | null {
+            let leader: MY.ArenaAvatar | null = null;
+            for (const avatar of this.runner.getAllBehaviours(MY.ArenaAvatar)) {
+                if (avatar.score > 0 && (leader == null || avatar.score > leader.score)) leader = avatar;
+            }
+            return leader;
+        }
+
+        /** Teleports the crown to a random point: server-only randomness that clients never need to reproduce. */
+        private dropCrownSomewhereElse(): void {
+            if (this.crown == null) return;
+            const angle: number = Math.random() * Math.PI * 2;
+            const radius: number = Math.random() * CROWN_DROP_RADIUS;
+            this.crown.teleport(new BABYLON.Vector3(Math.cos(angle) * radius, this.crown.transform.position.y, Math.sin(angle) * radius), null);
+        }
+    }
+    TOOLKIT.SceneManager.RegisterClass("MY.ArenaReferee", ArenaReferee);
+}
+```
+
+The server config for it:
+
+```js
+// babylon-game-server.config.mjs
+export default {
+    dedicated: {
+        scenes: [{ name: "arena", sceneRoot: "./scenes/arena/", sceneFile: "Arena.gltf", maxPlayers: 8, onDemand: true, idleSeconds: 60 }]
+    }
+};
+```
+
+What makes it server-authoritative:
+
+- The referee's `spawned()` and `fixedUpdateNetwork()` return at once unless `runner.isServer`, so browsers never
+  decide a claim, a score or a round.
+- Input carries only a direction and a button. The server normalises the direction, so a modified client cannot move
+  faster, and it checks the claim distance and cooldown itself.
+- Scores are networked properties written by the server, and `rpcRoundOver` is sent by the state authority (the
+  server) to everyone.
+- `onConnectRequest` sees the identity the game server verified (`request.authIdentity`, `{ userId, claims }`, or
+  `null` with auth off), never a name the client chose.
+
+To also refuse joiners by game rules, call `request.refuse()` in `onConnectRequest`; an unanswered request is
+accepted.
+
+### Getting results out of a session, and logging
+
+Dedicated-session code has no import of the server package, but two ways out work:
+
+**1. A bridge object on `globalThis` (in-process).** Project scripts run in the server process's own global scope, so
+an object your `server.mjs` puts on `globalThis` before `createGameServer` is visible to them. The example's
+`MY.findArenaServerBridge()` reads `globalThis.ArenaServerBridge`, which the [complete server.mjs](#complete-servermjs)
+defines. It needs your own Node app; under the plain CLI or image the bridge is absent and the referee falls back to
+`console.log`. This is a property of how scripts are loaded, not a published API of the package: keep the bridge
+small, check for it before calling it, and never put a secret on it that game code should not hold.
+
+**2. `fetch` to your backend.** `fetch` is available and not limited by the allow-list. Read the endpoint and its
+credential from `process.env` at run time, never from constants: browsers download the very same project bundle.
+
+```ts
+/**
+ * Posts a round result to the game's backend, on the server only.
+ * @param result The round's outcome.
+ */
+async function postRoundResult(result: MY.ArenaRoundResult): Promise<void> {
+    if (typeof process === "undefined" || process.env.ARENA_RESULTS_URL == null) return;
+    const response: Response = await fetch(process.env.ARENA_RESULTS_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Bearer " + process.env.ARENA_RESULTS_TOKEN },
+        body: JSON.stringify(result)
+    });
+    if (!response.ok) console.error("[Arena] results upload failed: " + response.status);
+}
+```
+
+(The exporter's TypeScript setup may not include Node's typings; declare `process` yourself or read it through
+`globalThis` if `process` does not compile.)
+
+**Logging.** `console.log` / `console.error` from project scripts (and Babylon's `BABYLON.Tools.Log` / `Warn`) go to
+the process's stdout and stderr as plain lines, outside the server's structured log, without `sessionName` fields. In
+production, give game code a logging function on the bridge that calls the package's `getLogger()`, as the example's
+`log(message, fields)` does. The server itself logs `dedicated session "<sessionName>" running <scene URL>` when a
+session is up, and `the dedicated scene <name> failed to load` with the cause when it is not.
+
+### Limits, metrics and lifetime
+
+| Limit | Option | Default | When exceeded |
+|---|---|---|---|
+| Dedicated sessions one process runs | `limits.maxDedicatedSessions` | `4` | The start is refused with `MaxCcuReached: this server is running its most dedicated sessions` (503) |
+| Sessions of every kind one process hosts | `limits.maxSessions` | `1000` | `MaxCcuReached: this server is hosting its most sessions` |
+| Players of a dedicated session | the scene's `maxPlayers` | `8` | `GameIsFull` |
+
+Prometheus metrics on `GET /metrics` that concern dedicated sessions:
+
+| Metric | Meaning |
+|---|---|
+| `babylon_game_server_dedicated_sessions` | Dedicated sessions running now |
+| `babylon_game_server_dedicated_frame_seconds` | Histogram of how long each headless frame took |
+| `babylon_game_server_dedicated_tick_overruns_total` | Frames that took longer than one network tick |
+
+Every session of a process, every hook and every route share **one Node event loop**. A slow frame in one dedicated
+session delays every other session and the relay of every Shared or Host session in that process. Size instances for
+their dedicated sessions (each is a full scene simulation), keep `maxDedicatedSessions` honest, and watch the overrun
+counter.
+
+How long a dedicated session lives:
+
+| Started | Ends |
+|---|---|
+| On demand | Once empty for the reconnect grace (20 s) plus `idleSeconds` |
+| At boot, by the admin API or from code | Only when closed through `POST /game-server/admin/sessions/:roomId/close`, a drain, or when the process stops |
+
+During a drain (`SIGTERM`, `server.drain()` or `POST /game-server/admin/drain`) new joins are refused with
+`GameClosed`, running sessions get `drainSeconds` (30) to end by themselves, then their players are told `GameClosed`
+and the runners stop.
+
+## 2. Server hooks
+
+Hooks are functions you pass to `createGameServer({ hooks })`. They are plain properties of one object, of type
+`GameServerHooks`:
+
+```ts
+interface GameServerHooks {
+    verifyToken?(request: AuthRequest): Promise<AuthIdentity | null>;
+    onSessionCreated?(event: SessionEvent): void;
+    onPlayerJoined?(event: PlayerEvent): void;
+    onPlayerLeft?(event: PlayerEvent): void;
+    onSessionClosed?(event: SessionEvent): void;
+}
+```
+
+`verifyToken` is covered in [Custom auth](#5-custom-auth-verifytoken-and-the-webhook). The four lifecycle hooks get:
+
+| `SessionEvent` field | Type | Meaning |
+|---|---|---|
+| `roomId` | `string` | The room id (the admin API's `:roomId`) |
+| `sessionName` | `string` | The session name players join by |
+| `gameMode` | `number \| null` | The `TOOLKIT.GameMode` value the **creating** join sent: `1` Shared, `2` Server (every dedicated session), `3` Host, `4` Client, `5` AutoHostOrClient |
+| `isDedicated` | `boolean` | True when a dedicated Server-mode runner hosts the session |
+
+`PlayerEvent` has every `SessionEvent` field plus:
+
+| `PlayerEvent` field | Type | Meaning |
+|---|---|---|
+| `playerId` | `number` | The player id in the session (the runtime's `PlayerRef.playerId`) |
+| `identity` | `AuthIdentity \| null` | `{ userId: string \| null, claims: Record<string, unknown> }` as the server verified it, or `null` with auth off |
+
+After `createGameServer` resolves, `globalThis.TOOLKIT` is the runtime, so `TOOLKIT.GameMode[event.gameMode]` gives
+the mode's name.
+
+### When each hook fires
+
+| Hook | Fires | Does not fire |
+|---|---|---|
+| `onSessionCreated` | A session room was created in this process: the first join of a Shared, Host or AutoHostOrClient session; a dedicated session started at boot, by the admin API or from code, **after** its scene loaded and its runner started; an on-demand session as soon as the first Client join creates it, **before** its scene has loaded | For the lobby; when creation is refused (session or dedicated cap, unknown on-demand scene); when a boot, admin or code start fails to load |
+| `onPlayerJoined` | A client was admitted (after the join gate and auth; for on-demand sessions, after the scene loaded) | For a reconnect within the grace period (the player keeps its seat); for the dedicated runner itself |
+| `onPlayerLeft` | A player left for good: it left, or it dropped and the reconnect grace (`TOOLKIT.NETWORK_RECONNECT_GRACE_SECONDS`, 20 s) ran out, or its session was closed | — |
+| `onSessionClosed` | The room was disposed: the last player of a Shared or Host session left; an on-demand session idled out; an admin close; a drain. For dedicated sessions, after the runner stopped | — |
+
+In a Host session, a host migration makes the remaining players' runners leave and join again, so expect
+`onPlayerLeft` / `onPlayerJoined` pairs with the same `playerId`.
+
+With Redis scale-out, each process calls the hooks for the sessions it hosts only.
+
+### Rules for hook code
+
+- **Hooks are called synchronously and never awaited.** Their return value is ignored, so a hook cannot delay or
+  refuse anything (only `verifyToken` can refuse, at join time).
+- **A synchronous throw is caught**: the server logs `hook <name> threw` with the error and carries on.
+- **An `async` hook's rejection is not caught by the server.** In the package as built, an optional handler that
+  Colyseus loads prints it to stderr; without that handler, Node's default ends the process. Catch inside every async
+  hook, or hand the work to a helper that catches, like `track()` below.
+- **Hooks share the event loop with every session.** Never do heavy synchronous work in them. Start I/O and return.
+- Hooks see sessions and players only: **no game messages, no networked state, no Shared-mode store.** Game data
+  reaches your code from a dedicated session ([bridge or `fetch`](#getting-results-out-of-a-session-and-logging)).
+- Work still in flight when the process exits is lost. With `handleSignals: true` the process exits right after the
+  drain; to flush writes first, handle the signals yourself ([shutdown](#shutdown-and-signals)).
+
+### Example: player analytics in PostgreSQL
+
+`pg` is your dependency (`npm install pg`). The table and columns are yours to define.
+
+```js
+// analytics-server.mjs: records every player's time in every session.
+import pg from "pg";
+import { createGameServer, getLogger } from "@babylonjs-toolkit/server";
+
+/** The analytics database (DATABASE_URL, for example postgres://user:password@host/game). */
+const database = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+/** When each player joined, by "<roomId>/<playerId>". */
+const joinedAt = new Map();
+
+/**
+ * Runs a write without letting a failure escape the hook.
+ * @param {Promise<unknown>} write The write.
+ */
+function track(write) {
+    write.catch((error) => getLogger().error("analytics write failed", { error: String(error) }));
+}
+
+const server = await createGameServer({
+    config: { port: 2567 },
+    handleSignals: true,
+    hooks: {
+        onPlayerJoined(event) {
+            joinedAt.set(event.roomId + "/" + event.playerId, Date.now());
+        },
+        onPlayerLeft(event) {
+            const key = event.roomId + "/" + event.playerId;
+            const startedAt = joinedAt.get(key) ?? Date.now();
+            joinedAt.delete(key);
+            track(database.query(
+                "INSERT INTO player_sessions (session_name, game_mode, is_dedicated, user_id, seconds_played) VALUES ($1, $2, $3, $4, $5)",
+                [event.sessionName, event.gameMode, event.isDedicated, event.identity?.userId ?? null, Math.round((Date.now() - startedAt) / 1000)]
+            ));
+        }
+    }
+});
+getLogger().info("analytics server listening", { url: server.urls.webSocket });
+```
+
+### Example: a Discord notifier
+
+```js
+// discord-server.mjs: posts to a Discord channel when a session opens and closes.
+import { createGameServer, getLogger } from "@babylonjs-toolkit/server";
+
+/** The channel's webhook URL (Server Settings → Integrations → Webhooks in Discord). */
+const DISCORD_WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL;
+
+/**
+ * Posts one message, logging a failure instead of throwing it.
+ * @param {string} content The message.
+ */
+function notify(content) {
+    fetch(DISCORD_WEBHOOK_URL, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ content: content }), signal: AbortSignal.timeout(5000) })
+        .then((response) => { if (!response.ok) throw new Error("Discord answered " + response.status); })
+        .catch((error) => getLogger().warn("Discord notice failed", { error: String(error) }));
+}
+
+await createGameServer({
+    config: { port: 2567 },
+    handleSignals: true,
+    hooks: {
+        onSessionCreated(event) {
+            notify("Session **" + event.sessionName + "** opened" + (event.isDedicated ? " (dedicated)" : ""));
+        },
+        onSessionClosed(event) {
+            notify("Session **" + event.sessionName + "** closed");
+        }
+    }
+});
+```
+
+Session names come from players. Discord renders Markdown, so escape or quote them if that matters to you.
+
+### Example: bans, and session bookkeeping
+
+Bans belong in `verifyToken` (see [the bans example](#example-bans-with-a-custom-verifier)), because hooks cannot
+refuse anyone. Session bookkeeping, a live map of who is where, is part of the
+[complete server.mjs](#complete-servermjs) and served by its `/api/sessions` route.
+
+## 3. Custom HTTP endpoints
+
+Pass extra endpoints as `createGameServer({ routes })`, a record whose values come from the re-exported
+`createEndpoint`. They answer on the game server's own port, over HTTP and HTTPS alike, next to `/game-server/*`.
+
+```ts
+createEndpoint(path: string, options: { method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | … }, handler: (context) => Promise<Response | object>)
+```
+
+`createEndpoint` is Colyseus's router endpoint (built on `better-call`). The handler's context has:
+
+| Member | What it is |
+|---|---|
+| `context.params` | Path parameters: `/api/rooms/:roomId` gives `context.params.roomId` |
+| `context.query` | The parsed query string |
+| `context.body` | The parsed JSON body of a `POST` / `PUT` / `PATCH` |
+| `context.getHeader(name)` | A request header, or `null` |
+
+Return a plain object to answer `200` with it as JSON, `jsonResponse(status, body)` (exported by the package) for
+another status, or any `Response` (for HTML or text).
+
+```js
+import { createEndpoint, createGameServer, jsonResponse } from "@babylonjs-toolkit/server";
+
+await createGameServer({
+    routes: {
+        hello: createEndpoint("/api/hello", { method: "GET" }, async (context) => ({ greeting: "hello " + (context.query.name ?? "player") })),
+        echo: createEndpoint("/api/echo/:id", { method: "POST" }, async (context) => jsonResponse(201, { id: context.params.id, body: context.body }))
+    }
+});
+```
+
+Things to know:
+
+- **Your routes get no auth, no rate limit and no admin check.** The admin-token check is internal (no helper is
+  exported), and `limits.joinRequestsPerMinutePerAddress` applies to joins only. Check credentials yourself, as below.
+- They get the same CORS answer as the built-in endpoints: with `limits.allowedOrigins` set, only those origins'
+  pages can call them from a browser.
+- Use your own path prefix (for example `/api/`). A route on a built-in path (`/game-server/health`) is never reached,
+  and a route whose **key** equals a built-in one (`gameServerHealth`, `gameServerReady`, `gameServerInfo`,
+  `gameServerMetrics`, `gameServerAdminSessions`, `gameServerAdminCloseSession`, `gameServerAdminDedicated`,
+  `gameServerAdminDrain`) replaces it.
+- With Redis scale-out, each instance serves its own routes from its own memory.
+
+### Checking a bearer token yourself
+
+The same constant-time compare the admin API uses:
+
+```js
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * Whether a route request carries the expected bearer token.
+ * @param {{ getHeader(name: string): string | null }} context The route context.
+ * @param {string | undefined} expectedToken The configured token; unset turns the route off.
+ * @returns {boolean}
+ */
+export function hasBearerToken(context, expectedToken) {
+    const authorization = context.getHeader("authorization");
+    if (expectedToken == null || expectedToken === "" || authorization == null || !authorization.startsWith("Bearer ")) return false;
+    const digest = (text) => createHash("sha256").update(text, "utf8").digest();
+    return timingSafeEqual(digest(authorization.substring("Bearer ".length).trim()), digest(expectedToken));
+}
+```
+
+For player-facing routes, verify the player's token the way your auth does (for example `jwtVerify` from `jose`, as
+in [the bans example](#example-bans-with-a-custom-verifier)).
+
+### Example: a custom stats endpoint
+
+Prefer the built-in leaderboards ([README › Leaderboards](README.md#leaderboards)): boards, seasons, trust levels and a
+console page, with no code. A dedicated session's own results can be posted at the server trust level with an API key
+holding `leaderboards.submit`. The example below stays as a custom stats endpoint.
+
+In the [complete server.mjs](#complete-servermjs): `GET /api/leaderboard` returns the top entries of what dedicated
+sessions reported through the bridge.
+
+### Example: a status page
+
+```js
+// Add to the routes of your server.mjs. liveSessions is the bookkeeping map the hooks fill.
+/**
+ * Escapes text for HTML (session names come from players).
+ * @param {string} text The text.
+ * @returns {string}
+ */
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (character) => "&#" + character.charCodeAt(0) + ";");
+}
+
+const statusPage = createEndpoint("/status", { method: "GET" }, async () => {
+    const rows = Array.from(liveSessions.values()).map((session) => "<tr><td>" + escapeHtml(session.sessionName) + "</td><td>" + session.players.size + "</td><td>" + (session.isDedicated ? "dedicated" : "relay") + "</td></tr>").join("");
+    const html = "<!doctype html><meta charset=\"utf-8\"><title>Arena status</title><h1>" + liveSessions.size + " sessions</h1><table><tr><th>Session</th><th>Players</th><th>Kind</th></tr>" + rows + "</table>";
+    return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
+});
+```
+
+A public page shows what anyone may see. Keep user ids and addresses behind a token, as `/api/sessions` does.
+
+### Example: create a private room
+
+Two ways, both in code you own:
+
+- **Hand out an on-demand session (recommended).** The route returns an unguessable session name for a scene with
+  `onDemand: true`; the first player's Client join (with `dedicatedScene`) starts it, and it closes itself once empty.
+  This is `/api/rooms` in the [complete server.mjs](#complete-servermjs).
+- **Start it at once** with `server.startDedicatedSession(sessionName, sceneName)`, when the session must be running
+  before anyone joins. Remember that such a session never closes by itself. Close it later through the admin API:
+
+```js
+/**
+ * Closes a session through this server's own admin API (needs admin.token / GAME_SERVER_ADMIN_TOKEN).
+ * @param {string} httpUrl The server's http(s):// URL (server.urls.http).
+ * @param {string} roomId The room id startDedicatedSession resolved.
+ * @returns {Promise<boolean>} True when it was closed.
+ */
+async function closeSession(httpUrl, roomId) {
+    const response = await fetch(httpUrl + "/game-server/admin/sessions/" + encodeURIComponent(roomId) + "/close", {
+        method: "POST",
+        headers: { authorization: "Bearer " + process.env.GAME_SERVER_ADMIN_TOKEN }
+    });
+    return response.ok;
+}
+```
+
+"Private" here means unguessable, not hidden: dedicated sessions are always listed in the session lobby
+(`runner.joinSessionLobby()`), visible and open. To keep strangers out, refuse them at join time: in `verifyToken`
+(it sees `request.sessionName` and the token) or in the dedicated session's `onConnectRequest`.
+
+## 4. Wrapping the server in your own Node app
+
+### What createGameServer returns
+
+```ts
+createGameServer(options?: { config?: DeepPartial<GameServerConfig>; hooks?: GameServerHooks; routes?: Record<string, Endpoint>; handleSignals?: boolean; admin?: AdminExtensions }): Promise<GameServer>
+```
+
+| `GameServer` member | What it is |
+|---|---|
+| `config` | The resolved, validated `GameServerConfig` |
+| `port` | The port it listens on (the free one picked for `port: 0`) |
+| `urls` | `{ webSocket, http, webTransport }`: `ws(s)://` and `http(s)://` URLs, and the `https://` WebTransport URL or `null` when UDP is off. `publicUrl` replaces the derived URL when set |
+| `close()` | Stops at once and disconnects everyone |
+| `drain()` | Refuses new joins, gives running sessions `drainSeconds`, tells the rest `GameClosed`, then stops. It does not exit the process |
+| `startDedicatedSession(sessionName, sceneName)` | Starts a dedicated session of a configured scene; resolves the room id |
+
+That is all of it. The underlying Colyseus server, its HTTP server and Express are **not reachable**: there is no
+accessor for them, and custom Express routes are not supported (the WebTransport transport has no Express app). Use
+`routes` for HTTP.
+
+Rules:
+
+- **One game server per process.** A second `createGameServer` throws `a Babylon Game Server is already running in
+  this process`; after `close()` (or a finished drain) you may create another.
+- `createGameServer` loads the toolkit runtime into the process and sets `globalThis.BABYLON` and `globalThis.TOOLKIT`.
+- It rejects with `GameServerConfigError` (its `problems` list every problem) for an invalid config, and with the
+  error when a boot dedicated session cannot start (the server is stopped again first).
+
+### Configuration from code
+
+`createGameServer({ config })` takes overrides of the defaults and reads **no file and no environment**. To get the
+CLI's behaviour (defaults < config file < `GAME_SERVER_*` variables < flags), load the config yourself and pass it:
+
+```js
+import { createGameServer, loadGameServerConfig } from "@babylonjs-toolkit/server";
+
+const config = await loadGameServerConfig({ argv: process.argv.slice(2), environment: process.env, workingDirectory: process.cwd() });
+const server = await createGameServer({ config: config, hooks: hooks, routes: routes });
+```
+
+Hooks and routes cannot go in the config file: unknown keys are refused at startup. `resolveGameServerConfig(overrides)`
+validates a config without starting anything.
+
+Also exported, for advanced use: `DEFAULT_GAME_SERVER_CONFIG`, `CONFIG_OPTIONS` (every option with its variable and
+flag), `getLogger` / `setLogger` / `GameServerLogger` (`createGameServer` installs its own logger; call `setLogger`
+after it to replace it), `buildServerInfo`, `jsonResponse`, `reloadTlsNow`, `DedicatedSession`,
+`DedicatedSceneRegistry`, `allowScriptUrlPrefixes` and `isUrlAllowed`, `AuthRefusal`, `GameServerMetrics` and
+`UNKNOWN_CLIENT_ADDRESS`, plus their types.
+
+### Shutdown and signals
+
+- `handleSignals: true` (what the CLI uses): on `SIGTERM` or `SIGINT` the server drains, then calls
+  `process.exit(0)`; a watchdog exits with code 1 if the drain takes more than `drainSeconds` plus 5 seconds.
+- `handleSignals: false` (the default from code): nothing is installed. Handle the signals yourself when you have
+  work to finish, as the complete `server.mjs` does: `await server.drain()`, flush your writes, then exit.
+
+### Complete server.mjs
+
+Everything above in one file: the server bridge for dedicated-session code, bookkeeping hooks, a leaderboard, an
+operator-only session list, private rooms, and a shutdown that flushes pending writes.
+
+```js
+// server.mjs: the Babylon Game Server with this game's own hooks, routes and server bridge.
+// Run: node server.mjs   (settings: flags, GAME_SERVER_* variables and babylon-game-server.config.mjs, as with the CLI)
+import { appendFile } from "node:fs/promises";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { createEndpoint, createGameServer, getLogger, jsonResponse, loadGameServerConfig } from "@babylonjs-toolkit/server";
+
+/** Where finished rounds are appended, one JSON object per line (swap for your database). */
+const RESULTS_FILE = process.env.ARENA_RESULTS_FILE ?? "./arena-results.jsonl";
+/** Discord channel webhook for round announcements, or unset for none. */
+const DISCORD_WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL ?? null;
+/** Bearer token of this game's own operator routes, or unset to turn them off. */
+const OPERATOR_TOKEN = process.env.ARENA_OPERATOR_TOKEN ?? null;
+/** The dedicated scene private rooms run (a dedicated.scenes entry with onDemand: true). */
+const PRIVATE_ROOM_SCENE = "arena";
+/** Entries the leaderboard returns. */
+const LEADERBOARD_SIZE = 10;
+
+/** Round wins by verified user id (kept in memory for this example). */
+const winsByUser = new Map();
+/** Live sessions of this process by room id: what the hooks saw. */
+const liveSessions = new Map();
+/** Writes still in flight; shutdown waits for them. */
+const pendingWrites = new Set();
+
+/**
+ * Remembers an async write until it settles, and logs its failure instead of letting it escape.
+ * @param {Promise<unknown>} write The write.
+ */
+function track(write) {
+    const settled = write.catch((error) => getLogger().error("background write failed", { error: String(error) }));
+    pendingWrites.add(settled);
+    settled.finally(() => pendingWrites.delete(settled));
+}
+
+/**
+ * Posts a message to the Discord channel webhook, when one is configured.
+ * @param {string} content The message.
+ * @returns {Promise<void>}
+ */
+async function notifyDiscord(content) {
+    if (DISCORD_WEBHOOK_URL == null) return;
+    const response = await fetch(DISCORD_WEBHOOK_URL, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ content: content }), signal: AbortSignal.timeout(5000) });
+    if (!response.ok) throw new Error("Discord answered " + response.status);
+}
+
+/**
+ * Whether a route request carries the operator bearer token (constant-time compare, as the admin API does).
+ * @param {{ getHeader(name: string): string | null }} context The route context.
+ * @returns {boolean}
+ */
+function hasOperatorToken(context) {
+    const authorization = context.getHeader("authorization");
+    if (OPERATOR_TOKEN == null || authorization == null || !authorization.startsWith("Bearer ")) return false;
+    const digest = (text) => createHash("sha256").update(text, "utf8").digest();
+    return timingSafeEqual(digest(authorization.substring("Bearer ".length).trim()), digest(OPERATOR_TOKEN));
+}
+
+// 1. The bridge server-side game code calls (MY.findArenaServerBridge). Set it before createGameServer, which starts
+//    the boot sessions. Game code runs in this process's global scope, so it sees this object.
+globalThis.ArenaServerBridge = {
+    reportRoundResult(result) {
+        if (result.winnerUserId != null) winsByUser.set(result.winnerUserId, (winsByUser.get(result.winnerUserId) ?? 0) + 1);
+        track(appendFile(RESULTS_FILE, JSON.stringify(Object.assign({ time: new Date().toISOString() }, result)) + "\n"));
+        if (result.winnerPlayerId !== 0) track(notifyDiscord("Round " + result.roundNumber + " of " + result.sessionName + " won by player " + result.winnerPlayerId));
+        getLogger().info("round finished", { sessionName: result.sessionName, roundNumber: result.roundNumber, winnerPlayerId: result.winnerPlayerId });
+    },
+    log(message, fields) {
+        getLogger().info(message, fields);
+    }
+};
+
+// 2. Lifecycle hooks: bookkeeping only, synchronous, never throwing.
+/** @type {import("@babylonjs-toolkit/server").GameServerHooks} */
+const hooks = {
+    onSessionCreated(event) {
+        liveSessions.set(event.roomId, { sessionName: event.sessionName, gameMode: event.gameMode, isDedicated: event.isDedicated, createdAt: Date.now(), players: new Map() });
+    },
+    onPlayerJoined(event) {
+        liveSessions.get(event.roomId)?.players.set(event.playerId, event.identity?.userId ?? null);
+    },
+    onPlayerLeft(event) {
+        liveSessions.get(event.roomId)?.players.delete(event.playerId);
+    },
+    onSessionClosed(event) {
+        liveSessions.delete(event.roomId);
+    }
+};
+
+// 3. This game's HTTP endpoints, on the game server's own port.
+const routes = {
+    arenaLeaderboard: createEndpoint("/api/leaderboard", { method: "GET" }, async () => {
+        const entries = Array.from(winsByUser.entries()).map(([userId, wins]) => ({ userId: userId, wins: wins }));
+        entries.sort((left, right) => right.wins - left.wins);
+        return { entries: entries.slice(0, LEADERBOARD_SIZE) };
+    }),
+    arenaSessions: createEndpoint("/api/sessions", { method: "GET" }, async (context) => {
+        if (!hasOperatorToken(context)) return jsonResponse(401, { error: "unauthorized" });
+        const sessions = Array.from(liveSessions.entries()).map(([roomId, session]) => ({ roomId: roomId, sessionName: session.sessionName, gameMode: session.gameMode, isDedicated: session.isDedicated, players: session.players.size, ageSeconds: Math.round((Date.now() - session.createdAt) / 1000) }));
+        return { sessions: sessions };
+    }),
+    arenaPrivateRoom: createEndpoint("/api/rooms", { method: "POST" }, async () => {
+        // An unguessable session name; the first Client join that names the on-demand scene starts the session.
+        return jsonResponse(201, { sessionName: "room-" + randomUUID(), dedicatedScene: PRIVATE_ROOM_SCENE });
+    })
+};
+
+// 4. Start it with the CLI's settings, and drain on SIGTERM/SIGINT ourselves so pending writes finish first.
+const config = await loadGameServerConfig({ argv: process.argv.slice(2), environment: process.env, workingDirectory: process.cwd() });
+const server = await createGameServer({ config: config, hooks: hooks, routes: routes, handleSignals: false });
+getLogger().info("arena server listening", { url: server.urls.webSocket });
+
+/**
+ * Drains the server, waits for pending writes, then exits.
+ * @param {NodeJS.Signals} signalName The signal.
+ */
+async function shutDown(signalName) {
+    getLogger().info("draining", { signal: signalName });
+    await server.drain();
+    await Promise.allSettled(Array.from(pendingWrites));
+    process.exit(0);
+}
+process.once("SIGTERM", shutDown);
+process.once("SIGINT", shutDown);
+```
+
+The game's page then asks for a room with `POST /api/rooms` and joins it:
+`startGame({ gameMode: GameMode.Client, sessionName: room.sessionName, sessionProperties: { dedicatedScene: room.dedicatedScene } })`.
+`/api/rooms` here is open to anyone who can reach the server; check the player's token in it for a real game.
+
+### Packaging
+
+`package.json`:
+
+```json
+{
+    "name": "my-game-server",
+    "private": true,
+    "type": "module",
+    "scripts": { "start": "node server.mjs" },
+    "dependencies": { "@babylonjs-toolkit/server": "9.30.1" }
+}
+```
+
+Pin the server version that matches your game's Babylon Toolkit runtime ([Versioning](#versioning)).
+
+**Dockerfile on `node:22`** (recommended when your `server.mjs` has npm dependencies of its own). Installing the
+package needs `git` in the build stage: a Colyseus peer dependency is fetched from GitHub.
+
+```dockerfile
+FROM node:22-bookworm-slim AS build
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --no-audit --no-fund
+
+FROM node:22-bookworm-slim
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build /app/node_modules node_modules
+COPY package.json server.mjs babylon-game-server.config.mjs ./
+COPY scenes/ scenes/
+USER node
+EXPOSE 2567/tcp 2567/udp
+HEALTHCHECK --interval=15s --timeout=5s --start-period=20s CMD ["node", "node_modules/@babylonjs-toolkit/server/lib/cli.js", "healthcheck"]
+CMD ["node", "server.mjs"]
+```
+
+The `healthcheck` command reads the same config file and `GAME_SERVER_*` variables to find the port, so keep the port
+in those (not hard-coded in `server.mjs`) and the health check probes the right one.
+
+**Dockerfile on the published image** (only when `server.mjs` needs nothing beyond Node and the server package). The
+image keeps the package in `/app/SVR`, not in `node_modules`, so import it by path there:
+`import { createGameServer, … } from "/app/SVR/lib/index.js";`. That path is the image's layout, not a published
+API: check it when you change image versions.
+
+```dockerfile
+FROM ghcr.io/mackeyk24/babylon-game-server:9.30.1
+COPY server.mjs /app/server.mjs
+COPY babylon-game-server.config.mjs /app/config/
+COPY scenes/ /app/scenes/
+ENV GAME_SERVER_CONFIG=/app/config/babylon-game-server.config.mjs
+ENTRYPOINT ["node", "/app/server.mjs"]
+```
+
+The base image's health check, non-root `node` user, `NODE_ENV=production` and exposed ports carry over. Its working
+directory is `/app`, so a relative `sceneRoot` such as `./scenes/arena/` means `/app/scenes/arena/`.
+
+**Environment and config.**
+
+- Server settings: `GAME_SERVER_*` variables, flags or the config file, as in the README. `GAME_SERVER_ADMIN_TOKEN`,
+  `GAME_SERVER_AUTH_JWT_SECRET` and the other secrets belong in the platform's secret store.
+- Your own settings (`DATABASE_URL`, `DISCORD_WEBHOOK_URL`, `ARENA_OPERATOR_TOKEN`): your own variable names, read
+  from `process.env`.
+- Colyseus, which the server is built on, loads a `.env.<NODE_ENV>` or `.env` file into `process.env` when the package
+  is imported, and prints `optional .env file not found: …` when there is none. Don't depend on that; set variables
+  explicitly in production.
+
+## 5. Custom auth: verifyToken and the webhook
+
+Both are code you own that approves each join at matchmaking, before a seat is reserved, for session joins **and**
+lobby joins. Turn auth on with `auth.enabled: true`. The identity you return is what hooks see as `event.identity` and
+what host or dedicated code sees as `request.authIdentity`.
+
+### verifyToken (auth mode "custom")
+
+```ts
+verifyToken?(request: AuthRequest): Promise<AuthIdentity | null>;
+```
+
+| `AuthRequest` field | Type | Meaning |
+|---|---|---|
+| `token` | `string` | The token the game passed as `startGame({ authToken })` (an empty token is refused before your hook runs) |
+| `kind` | `"session" \| "lobby"` | Which room the join is for |
+| `sessionName` | `string \| null` | The session, or `null` for the lobby |
+| `gameMode` | `number \| null` | The joiner's `TOOLKIT.GameMode`, or `null` for the lobby |
+| `clientAddress` | `string` | The client's address (from `X-Forwarded-For` / `X-Real-IP` only with `trustProxy`) |
+| `origin` | `string \| null` | The `Origin` header |
+
+- Return `{ userId, claims }` to admit, or `null` to refuse with
+  `CustomAuthenticationFailed: the custom verifier did not approve the player`.
+- Throw `new AuthRefusal(reasonName, detail)` to choose the refusal. The client's `startGame` fails with
+  `"<reasonName>: <detail>"`; use a `TOOLKIT.ShutdownReason` name (`InvalidAuthentication`,
+  `CustomAuthenticationFailed`, `AuthenticationTicketExpired`, `ConnectionRefused`, …) so the runtime maps it, or the
+  game sees `ShutdownReason.Error`.
+- Any other error is logged as `token verifier failed` and refuses with
+  `CustomAuthenticationFailed: the token could not be verified`.
+- It runs **only** with `auth.enabled: true` and `auth.mode: "custom"`. In any other mode the hook is ignored, without
+  a warning. Mode `custom` without the hook stops startup.
+- It is awaited, with no time limit of the server's own: a slow verifier delays the join. Put your own timeout on
+  network calls.
+- A player who reconnects within the grace period keeps its seat and identity **without** a new check, so a ban takes
+  effect on the next full join.
+- The request does not include the session properties, so a verifier cannot see which on-demand scene a join would
+  start.
+
+#### Example: bans with a custom verifier
+
+`jose` is your dependency (`npm install jose`). Your backend signs player tokens with `PLAYER_TOKEN_SECRET`.
+
+```js
+// bans.mjs: custom auth that verifies your backend's JWTs and refuses banned accounts and addresses.
+import { jwtVerify } from "jose";
+import { AuthRefusal, createGameServer } from "@babylonjs-toolkit/server";
+
+/** The HMAC secret your backend signs player tokens with, and the issuer it writes. */
+const PLAYER_TOKEN_SECRET = new TextEncoder().encode(process.env.PLAYER_TOKEN_SECRET ?? "");
+const PLAYER_TOKEN_ISSUER = "my-backend";
+/** Banned user ids and client addresses (load these from your database). */
+const bannedUserIds = new Set(["user-13"]);
+const bannedAddresses = new Set(["203.0.113.7"]);
+
+const server = await createGameServer({
+    config: { auth: { enabled: true, mode: "custom" } },
+    handleSignals: true,
+    hooks: {
+        /**
+         * Verifies one join (sessions and the lobby alike).
+         * @param {import("@babylonjs-toolkit/server").AuthRequest} request The token and what the server knows about the join.
+         * @returns {Promise<import("@babylonjs-toolkit/server").AuthIdentity | null>} The identity, or null to refuse.
+         */
+        async verifyToken(request) {
+            if (bannedAddresses.has(request.clientAddress)) throw new AuthRefusal("ConnectionRefused", "this address is banned");
+            let payload;
+            try {
+                ({ payload } = await jwtVerify(request.token, PLAYER_TOKEN_SECRET, { issuer: PLAYER_TOKEN_ISSUER }));
+            } catch {
+                throw new AuthRefusal("InvalidAuthentication", "the token is not valid");
+            }
+            if (typeof payload.sub !== "string") return null;
+            if (bannedUserIds.has(payload.sub)) throw new AuthRefusal("ConnectionRefused", "this account is banned");
+            return { userId: payload.sub, claims: { name: payload.name ?? null } };
+        }
+    }
+});
+console.log("listening on " + server.urls.webSocket);
+```
+
+A banned player's `startGame` fails with `ConnectionRefused: this account is banned`, and the server logs
+`join refused reason=ConnectionRefused detail="this account is banned"`. A custom verifier's ban works at join time
+only: it does not remove a player who is already connected. To remove one, kick the player from the
+[admin console](README.md#admin-console) (Players, or a session's player list) or its API
+(`POST /game-server/admin/api/players/kick` with `{ roomId, playerId, message, allowRejoin }`); the game shows the
+message. The console's own bans (Bans page, `POST /game-server/admin/api/bans`) refuse at join time **and** disconnect
+matching players who are already playing, on every instance, so you may not need a custom verifier for bans at all.
+
+If plain JWT checks are all you need, the built-in `jwt` mode does them without code (README, "Enabling
+authentication").
+
+### The auth webhook (auth mode "webhook")
+
+The server POSTs each join to your service and waits up to `auth.webhook.timeoutMs` (5000):
+
+```json
+{ "token": "…", "kind": "session", "sessionName": "arena-1", "gameMode": 4, "clientAddress": "203.0.113.20", "origin": "https://game.example.com" }
+```
+
+A 2xx answer with a JSON object admits the player with the identity `{ userId: body.userId (when it is a string,
+else null), claims: <the whole body> }`. Anything else (another status, not a JSON object, a timeout, a network error)
+refuses with `CustomAuthenticationFailed: the auth webhook did not approve the player`; the webhook cannot choose the
+reason or the text.
+
+```js
+// auth-webhook.mjs: approves Babylon Game Server joins in auth mode "webhook". Run it where only the game server reaches it.
+import { createServer } from "node:http";
+
+/** Port of this service, and the longest request body it reads. */
+const PORT = Number(process.env.AUTH_WEBHOOK_PORT ?? 8787);
+const MAX_BODY_BYTES = 16384;
+/** Session tokens your login flow issued, by token (use your database or cache). */
+const sessionsByToken = new Map([["token-ada", { userId: "user-1", name: "Ada", banned: false }], ["token-mallory", { userId: "user-13", name: "Mallory", banned: true }]]);
+
+/**
+ * Reads a JSON request body.
+ * @param {import("node:http").IncomingMessage} request The request.
+ * @returns {Promise<any>} The parsed body.
+ */
+async function readJson(request) {
+    let text = "";
+    for await (const chunk of request) {
+        text += chunk;
+        if (text.length > MAX_BODY_BYTES) throw new Error("body too large");
+    }
+    return JSON.parse(text);
+}
+
+createServer(async (request, response) => {
+    try {
+        // The game server POSTs { token, kind, sessionName, gameMode, clientAddress, origin }.
+        const join = await readJson(request);
+        const player = sessionsByToken.get(join.token);
+        if (player == null || player.banned) {
+            response.writeHead(403).end();
+            return;
+        }
+        // A 2xx JSON object approves: userId becomes the identity's userId, the whole object its claims.
+        response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ userId: player.userId, name: player.name }));
+    } catch {
+        response.writeHead(400).end();
+    }
+}).listen(PORT, "127.0.0.1", () => console.log("auth webhook on http://127.0.0.1:" + PORT));
+```
+
+```sh
+GAME_SERVER_AUTH_ENABLED=true GAME_SERVER_AUTH_MODE=webhook GAME_SERVER_AUTH_WEBHOOK_URL=http://127.0.0.1:8787/ npx babylon-game-server
+```
+
+The webhook works with the plain CLI and image, so it is the way to own auth without writing a `server.mjs`. The
+server sends no signature or shared secret with the request: anyone who can reach the webhook can ask it about a
+token. Keep it on a private network or loopback, and put it behind your own check if it must be public.
+
+## Custom admin actions, panels and admin hooks
+
+Your own Node app (section 4) can add buttons, read-only panels and event listeners to the
+[admin console](README.md#admin-console) with `createGameServer({ admin })`. The console shows them on the page they
+belong to, checks permissions, asks for confirmation and writes every run to the audit log, so operators get your
+game's tools without a separate admin site. The types are exported from `@babylonjs-toolkit/server`
+(`AdminExtensions`, `AdminActionDefinition`, `AdminPanelDefinition`, `AdminEventHooks` and the rest).
+
+| `admin` member | What it adds |
+|---|---|
+| `actions: AdminActionDefinition[]` | A button with a typed form. `target` places it: `"server"` (the Extensions page), `"instance"`, `"session"` or `"player"` (that page). |
+| `panels: AdminPanelDefinition[]` | A read-only table or list of values, on the `"overview"`, a `"session"` or a `"player"` page. |
+| `hooks: AdminEventHooks` | `onPlayerKicked`, `onBanCreated`, `onBanRemoved`, `onMaintenanceChanged` and `onAlertFired`, called after the console action succeeded, to mirror it into your own systems. |
+
+An action:
+
+| Field | What it is |
+|---|---|
+| `name` | Unique, `/^[a-z][a-zA-Z0-9-]{2,40}$/`; the API runs it at `POST /game-server/admin/api/extensions/actions/<name>` with `{ target, inputs }` |
+| `label`, `description` | The button text and the form's explanation |
+| `target` | `"server"`, `"instance"`, `"session"` or `"player"`; the handler gets that page's ids in `context.target` (`processId`, `roomId`, or `roomId` + `playerId` + `userId`) |
+| `fields` | The form: each `{ name, label, type, required, options?, defaultValue? }`, with `type` one of `"text"`, `"number"`, `"boolean"`, `"select"` (with `options`) or `"secret"`. Values arrive typed in `context.inputs`; a `secret` value is never written to the audit log |
+| `audience` | `"operators"` (default: every role with `extensions.run` — Owner, Admin, Operator, Moderator) or `"developer"` (`extensions.runDeveloper` — Owner, Admin, Developer) |
+| `confirm` | Ask before running (default `true`) |
+| `handler(context)` | Does the work and resolves `{ ok, message, data? }`; the console shows the message and the `data` values. `context.caller` says who ran it |
+
+A panel has a `name`, a `title`, a `placement` and a `handler({ target })` that resolves either
+`{ kind: "table", columns, rows }` or `{ kind: "values", values: [{ label, value }] }`. Panels are read-only: every
+signed-in account sees them, so show nothing secret.
+
+```js
+// server.mjs (excerpt): the arena's admin tools.
+import { createGameServer, getLogger, loadGameServerConfig } from "@babylonjs-toolkit/server";
+
+/** Rounds a player has won, by user id (swap for your database). */
+const winsByUserId = new Map();
+/** Most rows the leaderboard panel shows. */
+const LEADERBOARD_PANEL_ROWS = 10;
+
+/** @type {import("@babylonjs-toolkit/server").AdminExtensions} */
+const admin = {
+    actions: [
+        {
+            name: "grant-wins",
+            label: "Grant wins",
+            description: "Adds wins to this player's record, for example after a disputed round.",
+            target: "player",
+            fields: [
+                { name: "wins", label: "Wins to add", type: "number", required: true, defaultValue: 1 },
+                { name: "reason", label: "Reason", type: "select", required: true, options: ["disputed round", "server fault", "event prize"] }
+            ],
+            handler: async (context) => {
+                const userId = context.target.userId;
+                if (userId == null) return { ok: false, message: "this player is anonymous (turn on auth to track wins)" };
+                const total = (winsByUserId.get(userId) ?? 0) + Number(context.inputs.wins);
+                winsByUserId.set(userId, total);
+                getLogger().info("wins granted", { userId: userId, total: total, by: context.caller.name });
+                return { ok: true, message: "granted " + context.inputs.wins + " win(s): " + context.inputs.reason, data: { userId: userId, totalWins: total } };
+            }
+        },
+        {
+            name: "reset-leaderboard",
+            label: "Reset leaderboard",
+            description: "Clears every recorded win. Developers only.",
+            target: "server",
+            audience: "developer",
+            fields: [{ name: "confirmText", label: "Type RESET to confirm", type: "text", required: true }],
+            handler: async (context) => {
+                if (context.inputs.confirmText !== "RESET") return { ok: false, message: "type RESET to confirm" };
+                winsByUserId.clear();
+                return { ok: true, message: "the leaderboard is empty" };
+            }
+        }
+    ],
+    panels: [
+        {
+            name: "arena-leaderboard",
+            title: "Arena leaderboard",
+            placement: "overview",
+            handler: async () => {
+                const leaders = [...winsByUserId.entries()].sort((first, second) => second[1] - first[1]).slice(0, LEADERBOARD_PANEL_ROWS);
+                return { kind: "table", columns: ["Player", "Wins"], rows: leaders.map(([userId, wins]) => [userId, wins]) };
+            }
+        },
+        {
+            name: "player-record",
+            title: "Arena record",
+            placement: "player",
+            handler: async (context) => ({ kind: "values", values: [{ label: "Wins", value: winsByUserId.get(context.target.userId ?? "") ?? 0 }] })
+        }
+    ],
+    hooks: {
+        onPlayerKicked: (event) => getLogger().info("arena kick", { roomId: event.roomId, userId: event.userId, by: event.by }),
+        onBanCreated: (event) => getLogger().info("arena ban", { kind: event.kind, value: event.value, expiresAt: event.expiresAt, by: event.by })
+    }
+};
+
+const config = await loadGameServerConfig({ argv: process.argv.slice(2), environment: process.env, workingDirectory: process.cwd() });
+const server = await createGameServer({ config: config, admin: admin, handleSignals: true });
+console.log("listening on " + server.urls.webSocket + "; admin console at " + server.urls.http + "/game-server/admin/");
+```
+
+Rules:
+
+- **Extensions come from code only**, like hooks and routes: the plain CLI and the config file cannot add them. A bad
+  definition (a duplicate or malformed name, an unknown target, field type or placement) stops `createGameServer`
+  with `admin extension <name>: <problem>`.
+- **Handlers run in the instance that received the request**, in the server process, unsandboxed, with the caller's
+  permission already checked. With Redis, each instance must register the same extensions; keep shared state in your
+  database, not in memory, when you run more than one instance.
+- **A handler that throws** answers 500 `the action <name> failed: <message>` and logs `admin action <name> threw`
+  (`admin panel <name> threw` for a panel). Return `{ ok: false, message }` for an expected refusal instead.
+- **Hooks never block the console.** A hook's throw, or a returned promise's rejection, is logged as
+  `admin hook <name> threw`; the promise is not awaited.
+- Every run is in the audit log with the caller, the target, the inputs (without `secret` fields) and `ok`.
+
+## Security
+
+- **Project scripts and hooks run in the server's own Node process, unsandboxed.** A dedicated-session script can read
+  `process.env`, reach every built-in module through `process.getBuiltinModule` and call any URL with `fetch`. Load
+  only bundles you build, from a `sceneRoot` and `projectScripts` you control (your own folder or bucket). The URL
+  allow-list stops clients from naming files to load; it does not make a script safe.
+- **Dedicated sessions share one process.** One session's globals are every session's globals, and an exception in
+  one session's frame stops the process. Do not mix games you don't trust in one process.
+- **Secrets go in environment variables**, read at run time. Never put a secret in a project bundle: browsers
+  download the same file. Never log tokens: the server never does, and `LogFields` notes "Never put tokens, secrets or
+  PEM text here".
+- **Your routes are open by default.** Join rate limits, origin checks and auth apply to joins only. Check tokens in
+  each route, limit request rates yourself if the route is public, and escape anything player-provided (session names)
+  in HTML.
+- **On-demand scenes can be started by any client allowed to join**, up to `maxDedicatedSessions`. Turn on auth in
+  production, and use `verifyToken` (which sees `sessionName` and `gameMode`) to limit who may create sessions.
+- **The auth webhook is unauthenticated.** Keep it private.
+- **Trust identities the server verified** (`event.identity`, `request.authIdentity`), never names or ids a client
+  sends in game data.
+
+## Testing your code locally
+
+1. **Export the scene** with the exporter's Babylon Toolkit Networking option on. The scene file, its project bundle
+   and its asset containers land in the exporter's output folder (for example `<UnityProject>/export/scenes/`).
+2. **Point a dedicated scene at that folder.** A folder path is the simplest locally: the server reads the files from
+   disk. (Pointing `sceneRoot` at an `https://` dev server with a local certificate also works only when Node trusts
+   that certificate, for example through `NODE_EXTRA_CA_CERTS`.)
+   ```js
+   // babylon-game-server.config.mjs
+   export default {
+       logLevel: "debug",
+       dedicated: { scenes: [{ name: "arena", sceneRoot: "../MyGame/export/scenes/", sceneFile: "Arena.gltf", onDemand: true }] }
+   };
+   ```
+3. **Run your server**: `node server.mjs` (or `npx babylon-game-server` when you have no code of your own). Expect
+   Colyseus's start-up banner, then your own log lines.
+4. **Open the game page** from the exporter's dev server, in two browser tabs. With the toolkit's networking sample
+   launcher (or the arena launcher above, which reads the same query names):
+   ```text
+   engine.html?scene=Arena.gltf&fusionMode=Client&fusionSession=arena-1&fusionDedicatedScene=arena&fusionServer=ws%3A%2F%2Flocalhost%3A2567&fusionStats=1
+   ```
+   A page served over `https://` needs a `wss://` server: run the server with `tls: { enabled: true,
+   developmentCertificate: true }` (mkcert), or open the page over `http://`.
+5. **Read the server log.** The first join logs `dedicated session "arena-1" running file:///…/Arena.gltf`; load
+   problems log `the dedicated scene arena failed to load` with the cause; refusals log `join refused` with the
+   reason; your script's `console.log` lines appear as plain lines; a failed hook logs `hook <name> threw`.
+6. **Inspect it**: `curl -H "Authorization: Bearer $GAME_SERVER_ADMIN_TOKEN" http://localhost:2567/game-server/admin/sessions`
+   lists the sessions (with `isDedicated`), and `curl http://localhost:2567/metrics` shows the dedicated frame metrics.
+7. **After every re-export, restart the server.** Script bundles load once per process, and a changed prefab table is
+   refused with `IncompatibleConfiguration` until browsers reload and the dedicated session restarts.
+
+## Versioning
+
+- **The network protocol version must match.** The server and the game runtime share `TOOLKIT.NETWORK_PROTOCOL_VERSION`
+  (separate from package versions). A game on another protocol version is refused with
+  `IncompatibleConfiguration: this server speaks network protocol <n> but the game sent <m>; update the …`, and the game
+  reads the server's from `GET /game-server/info` (`protocolVersion`) before joining.
+- **Your server-side code runs on the server's runtime, not the browser's.** A dedicated session executes your
+  project bundle against the `babylonjs` and `babylonjs-toolkit` versions installed with the server package (the
+  package version follows the toolkit runtime it ships with). Install the server version that matches the toolkit your
+  game is exported with, so the APIs your scripts call exist on both sides.
+- **Prefab tables must match.** Browsers and the dedicated session must load the same export. Re-export, reload every
+  page, restart the server.
+- **Upgrades**: change `@babylonjs-toolkit/server` (or the image tag) and redeploy; sessions on the old instance finish
+  while it drains.
+
+## Limits and what is not supported
+
+Not available, with the closest real mechanism:
+
+| You might want | Status | Closest mechanism |
+|---|---|---|
+| A per-session server plugin or custom room class | Not supported: every session is the same room type | A dedicated session runs your game code per session |
+| A hook that sees game messages, inputs, RPCs or networked state | Not supported: hooks see sessions and players only; messages other than the runtime's own are ignored | Dedicated-session code, which owns the state, reporting through a bridge or `fetch` |
+| Custom client-to-server messages outside the networking API | Not supported | RPCs to the state authority, or reliable data (`runner.sendReliableDataToServer`) in a dedicated session |
+| Hot reload of project scripts | Not supported: a bundle loads once per process | Restart the process (drain first) |
+| Per-session parameters for a dedicated session (map, mode, rules) | Not supported: on-demand and admin starts pass no session properties to the server runner | Encode it in the session name, or keep a map in `server.mjs` keyed by session name and read it through the bridge |
+| Hidden or closed dedicated sessions | Not supported: they are listed in the lobby, visible and open | Refuse strangers in `verifyToken` or `onConnectRequest` |
+| Kicking a connected player | Supported through the [admin console](README.md#admin-console) and its API (`POST /game-server/admin/api/players/kick`); the game shows the message, and a rejoin is blocked for 5 minutes unless allowed | The console's bans also disconnect matching players already playing |
+| A hook when a dedicated scene finished loading or failed | Not available (on-demand `onSessionCreated` fires before the load) | The server log; `startDedicatedSession` resolves or rejects for boot, admin and code starts |
+| Listing or closing sessions from code | Not on `GameServer` | The console API (`/game-server/admin/api/sessions`, an API key), or the legacy admin endpoints, called with `fetch`; or a [custom admin action](#custom-admin-actions-panels-and-admin-hooks) in the console |
+| Adding scenes to the registry at run time | Not supported (the config's `dedicated.scenes` is read once) | `DedicatedSession.start(…)` for a scene outside the config |
+| Custom Prometheus metrics on `/metrics` | Not supported: the registry is private | Serve your own metrics route |
+| Hooks or routes in the config file, or with the plain CLI | Not supported | Your own `server.mjs` |
+| Access to Colyseus, its HTTP server or Express | Not exposed | `routes` |
+| Isolating sessions from each other | Not supported: one process, one global scope, one event loop | Separate processes or instances per game |
+| ES module game code on the server | Not supported: scripts run as classic scripts | Build the server-side classes into a classic bundle |
+
+Other limits worth knowing:
+
+- One game server per process; one default input definition per process.
+- Sessions started at boot, by the admin API or from code never idle-close, and starting an existing session name again
+  creates a second room.
+- An exception in a dedicated session's frame ends the process; an `async` hook's rejection is not handled by the
+  server.
+- A relative `sceneRoot` resolves against the process's working directory.
+- The legacy admin endpoints exist only when `admin.token` is set; the admin console and its API exist when an admin
+  account exists or a first-owner setup is pending (README, "Admin console").
+- Your routes and hooks live in each instance; with Redis, nothing is shared between instances except what the server
+  shares itself (matchmaking, the lobby, the admin list).