@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/README.md

@@ -1,3 +1,1082 @@
-# Temporary Holding Version
+# Babylon Game Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@babylonjs-toolkit/server` is the multiplayer session server for Babylon Toolkit games. It hosts every session a
+`TOOLKIT.NetworkRunner` starts — Shared, Host/Client, AutoHostOrClient and dedicated Server mode — on Colyseus 0.18.
+
+- **One server for every game.** It holds no game code. It loads the Babylon Toolkit runtime headless, with Babylon
+  Toolkit Networking built in (the `TOOLKIT` namespace), so its relay, its Shared-mode state store and its dedicated
+  Server-mode runner run the same code as the browser. A game's own classes stay in its `PROJECT` script bundle.
+- **Safe defaults.** TLS, player authentication and UDP are each off until you turn them on. Abuse limits are on.
+- **Ready to operate.** Health and readiness endpoints, Prometheus metrics, a web [admin console](#admin-console) with
+  its admin API, graceful draining on `SIGTERM`, scale-out over Redis, structured JSON logs in production and
+  deployment recipes for common hosts.
+
+Node 22 or newer is required.
+
+## Quick start
+
+Run it with npx:
+
+```sh
+npx @babylonjs-toolkit/server
+# Babylon Game Server 9.30.1 listening on ws://localhost:2567
+#   HTTP:         http://localhost:2567
+#   WebTransport: off
+#   TLS: off   UDP: off   Auth: off   Redis: off
+```
+
+Or with Docker:
+
+```sh
+docker run -p 2567:2567 ghcr.io/mackeyk24/babylon-game-server
+```
+
+Or install it in your project and write a starter folder with a commented config file, an `.env.example`, a
+`Dockerfile` and deployment recipes:
+
+```sh
+npm install @babylonjs-toolkit/server
+npx babylon-game-server init            # writes ./babylon-game-server/
+npx babylon-game-server init deploy     # or into ./deploy/; existing files are kept unless --force
+```
+
+The CLI has three commands:
+
+| Command | What it does |
+|---|---|
+| `babylon-game-server [start] [flags]` | Starts the server (the default command). |
+| `babylon-game-server init [folder] [--force]` | Writes the starter folder. Existing files are listed as `skipped (exists)` and kept unless `--force`; the exit code is 1 when any were skipped. |
+| `babylon-game-server healthcheck [flags]` | Calls the running server's `/game-server/health` on `127.0.0.1` with the same config and exits 0 when it answers 200, else 1. The Docker image's `HEALTHCHECK` runs it. |
+
+A configuration problem prints every problem at once and exits with code 2.
+
+## Connect your game
+
+The game points its `NetworkRunner` at the server URL and, when the server requires it, passes a token.
+
+**UMD (exported pages and Unity-attached scripts).** Turn on the exporter's **Babylon Toolkit Networking** option so the page
+loads the Colyseus browser client (`scripts/colyseus.js`). The server URL is authored on the scene's `NetworkSettings`
+component, or set at start:
+
+```ts
+const runner: TOOLKIT.NetworkRunner = new TOOLKIT.NetworkRunner(scene);
+const result: TOOLKIT.StartGameResult = await runner.startGame({
+    gameMode: TOOLKIT.GameMode.AutoHostOrClient,
+    sessionName: "arena",
+    config: { serverUrl: "wss://game.example.com" },
+    authToken: playerToken,                                        // only when the server enables auth
+    transportPreference: TOOLKIT.NetworkTransportPreference.Auto   // the default
+});
+if (!result.ok) console.error(TOOLKIT.ShutdownReason[result.shutdownReason] + " " + result.errorMessage);
+```
+
+**ESM (web apps on `@babylonjs-toolkit/next`).** Install the browser client and hand it to the transport before the
+first `startGame`; the `startGame` call is the same, without the `TOOLKIT.` prefix:
+
+```sh
+npm install @colyseus/sdk@0.18.5
+```
+
+```ts
+import { ColyseusTransport, NetworkRunner, GameMode } from "@babylonjs-toolkit/next/project";
+
+ColyseusTransport.ClientModule = await import("@colyseus/sdk");
+```
+
+- `authToken` is sent with every matchmaking call, the session lobby included. With auth off the server ignores it.
+- `transportPreference` is `Auto` (WebTransport when the server offers it and the browser can use it, else
+  WebSocket), `WebSocket`, or `WebTransport` (refused with `ConnectionRefused` when it cannot be used).
+- The host's `onConnectRequest(runner, request, token)` (and a dedicated runner's) sees the server-verified identity
+  as `request.authIdentity` (`{ userId, claims }`, or `null` when auth is off). The server sets it; a value a client
+  sends is discarded.
+- A page served over `https://` needs a `wss://` server URL.
+
+**The toolkit's sample launcher** (`Assets/Networking/Samples`) reads these from the page URL:
+
+| Query parameter | Meaning | Default |
+|---|---|---|
+| `fusionMode` | A `GameMode` name: `Shared`, `Host`, `Client`, `AutoHostOrClient` | `Shared` |
+| `fusionSession` | The session name | `testbed` |
+| `fusionServer` | The server URL (URL-encoded) | `ws://localhost:2567` |
+| `fusionToken` | The auth token | none |
+| `fusionTransport` | `auto`, `websocket` or `webtransport` | `auto` |
+| `fusionDedicatedScene` | With `fusionMode=Client`: a dedicated scene the server starts on demand | none |
+| `fusionStats` | `1` shows the network stats overlay, which also names the active link | off |
+
+```text
+engine.html?scene=networktestbed.gltf&fusionMode=Shared&fusionSession=race1&fusionServer=wss%3A%2F%2Fgame.example.com&fusionToken=abc
+```
+
+## Configuration
+
+Settings come from, highest first: command-line flags, `GAME_SERVER_*` environment variables, a config file, the
+defaults. The config file is the one named by `--config <path>` or `GAME_SERVER_CONFIG`, else the first of
+`babylon-game-server.config.mjs`, `.js` or `.json` in the working directory. A `.mjs`/`.js` file's default export is an
+object, or a function (async allowed) that returns one. `PORT` is read when `GAME_SERVER_PORT` is unset, as most
+platforms set it. Boolean flags have a `--no-` form (`--no-tls`). List variables are comma-separated. Unknown keys,
+flags and wrongly typed values are refused at startup.
+
+Every option:
+
+| Option | Environment variable | Flag | Default | Description |
+|---|---|---|---|---|
+| `port` | `GAME_SERVER_PORT` | `--port` | `2567` | TCP (and UDP) port to listen on; 0 picks a free port. Falls back to PORT. |
+| `host` | `GAME_SERVER_HOST` | `--host` | `0.0.0.0` | Address to bind. |
+| `publicUrl` | `GAME_SERVER_PUBLIC_URL` | `--public-url` | none | Public ws:// or wss:// URL players use, shown in the banner. |
+| `publicAddress` | `GAME_SERVER_PUBLIC_ADDRESS` | `--public-address` | none | host[:port] this instance advertises for seat reservations when scaled out with Redis. |
+| `trustProxy` | `GAME_SERVER_TRUST_PROXY` | `--trust-proxy` | `false` | Trust x-forwarded-for / x-real-ip from a reverse proxy for the client address. |
+| `logFormat` | `GAME_SERVER_LOG_FORMAT` | `--log-format` | `auto` | Log format: auto (JSON when NODE_ENV=production), json or text. One of `auto`, `json`, `text`. |
+| `logLevel` | `GAME_SERVER_LOG_LEVEL` | `--log-level` | `info` | Least severe level logged. One of `error`, `warn`, `info`, `debug`. |
+| `tls.enabled` | `GAME_SERVER_TLS_ENABLED` | `--tls` | `false` | Serve https:// and wss:// from the server itself. |
+| `tls.certFile` | `GAME_SERVER_TLS_CERT_FILE` | `--tls-cert-file` | none | Path of the PEM certificate chain; reloaded when it changes. |
+| `tls.keyFile` | `GAME_SERVER_TLS_KEY_FILE` | `--tls-key-file` | none | Path of the PEM private key; reloaded when it changes. |
+| `tls.certPem` | `GAME_SERVER_TLS_CERT_PEM` | none | none | PEM certificate chain text, for container secrets. Secret: never logged. |
+| `tls.keyPem` | `GAME_SERVER_TLS_KEY_PEM` | none | none | PEM private key text, for container secrets. Secret: never logged. |
+| `tls.developmentCertificate` | `GAME_SERVER_TLS_DEVELOPMENT_CERTIFICATE` | `--tls-dev-cert` | `false` | Make a local development certificate with mkcert (refused when NODE_ENV=production). |
+| `udp.enabled` | `GAME_SERVER_UDP_ENABLED` | `--udp` | `false` | Also accept WebTransport over HTTP/3 (UDP) on the same port; needs TLS. |
+| `auth.enabled` | `GAME_SERVER_AUTH_ENABLED` | `--auth` | `false` | Require a valid player token on every join. |
+| `auth.mode` | `GAME_SERVER_AUTH_MODE` | `--auth-mode` | `shared-secret` | How tokens are verified: shared-secret, jwt, webhook or custom. One of `shared-secret`, `jwt`, `webhook`, `custom`. |
+| `auth.sharedSecret.tokens` | `GAME_SERVER_AUTH_SHARED_SECRET_TOKENS` | none | empty | Comma-separated tokens accepted in shared-secret mode. Secret: never logged. |
+| `auth.jwt.secret` | `GAME_SERVER_AUTH_JWT_SECRET` | none | none | HMAC secret (HS256/384/512) that signs player JWTs. Secret: never logged. |
+| `auth.jwt.jwksUrl` | `GAME_SERVER_AUTH_JWT_JWKS_URL` | none | none | JWKS URL of the identity provider that signs player JWTs. |
+| `auth.jwt.issuer` | `GAME_SERVER_AUTH_JWT_ISSUER` | none | none | Required JWT issuer (iss), or none. |
+| `auth.jwt.audience` | `GAME_SERVER_AUTH_JWT_AUDIENCE` | none | none | Required JWT audience (aud), or none. |
+| `auth.jwt.algorithms` | `GAME_SERVER_AUTH_JWT_ALGORITHMS` | none | empty | Comma-separated accepted JWT algorithms (empty: the key's defaults). |
+| `auth.webhook.url` | `GAME_SERVER_AUTH_WEBHOOK_URL` | none | none | URL that approves players in webhook mode. |
+| `auth.webhook.timeoutMs` | `GAME_SERVER_AUTH_WEBHOOK_TIMEOUT_MS` | none | `5000` | Milliseconds the auth webhook may take. |
+| `discordSignIn.enabled` | `GAME_SERVER_DISCORD_SIGN_IN_ENABLED` | `--discord-sign-in` | `false` | Let players sign in with Discord (website OAuth2, scope identify). |
+| `discordSignIn.clientId` | `GAME_SERVER_DISCORD_CLIENT_ID` | none | none | The Discord application's client id. |
+| `discordSignIn.clientSecret` | `GAME_SERVER_DISCORD_CLIENT_SECRET` | none | none | The Discord application's client secret. Secret: never logged. |
+| `discordSignIn.redirectUri` | `GAME_SERVER_DISCORD_REDIRECT_URI` | none | none | This server's Discord callback address, exactly as registered with Discord (…/game-server/discord/callback). |
+| `discordSignIn.returnOrigins` | `GAME_SERVER_DISCORD_RETURN_ORIGINS` | none | empty | Comma-separated game origins a Discord sign-in may return to. |
+| `discordSignIn.sessionDays` | `GAME_SERVER_DISCORD_SESSION_DAYS` | none | `30` | Days a player's Discord sign-in lasts before they sign in again. |
+| `admin.token` | `GAME_SERVER_ADMIN_TOKEN` | `--admin-token` | none | Bearer token of the admin endpoints (unset: the admin API is off). Secret: never logged. |
+| `admin.console` | `GAME_SERVER_ADMIN_CONSOLE` | none | `true` | Serve the web admin console at /game-server/admin/ when an admin account exists or a setup is pending. |
+| `admin.dataDir` | `GAME_SERVER_ADMIN_DATA_DIR` | `--admin-data-dir` | `./babylon-game-server-data` | Folder of the admin data (accounts, bans, audit) when Redis is not configured. |
+| `admin.sessionIdleMinutes` | `GAME_SERVER_ADMIN_SESSION_IDLE_MINUTES` | none | `30` | Console sign-out after this many idle minutes. |
+| `admin.sessionMaxHours` | `GAME_SERVER_ADMIN_SESSION_MAX_HOURS` | none | `12` | Console sign-out after this many hours in all. |
+| `admin.allowedNetworks` | `GAME_SERVER_ADMIN_ALLOWED_NETWORKS` | none | empty | Comma-separated addresses or CIDR ranges that may reach the console and its API (empty: any). |
+| `admin.logBufferEntries` | `GAME_SERVER_ADMIN_LOG_BUFFER_ENTRIES` | none | `10000` | Log entries each instance keeps for the console. |
+| `admin.metricsHistoryHours` | `GAME_SERVER_ADMIN_METRICS_HISTORY_HOURS` | none | `24` | Hours of metrics history kept for the console charts. |
+| `admin.grafanaUrl` | `GAME_SERVER_ADMIN_GRAFANA_URL` | none | none | An external Grafana dashboard URL the console links to. |
+| `admin.instanceLabel` | `GAME_SERVER_ADMIN_INSTANCE_LABEL` | none | none | A region or label the console shows beside this instance. |
+| `admin.oidc.enabled` | `GAME_SERVER_ADMIN_OIDC_ENABLED` | none | `false` | Offer OpenID Connect single sign-on on the console (needs issuer and clientId). |
+| `admin.oidc.issuer` | `GAME_SERVER_ADMIN_OIDC_ISSUER` | none | none | OpenID Connect issuer URL (with a /.well-known/openid-configuration). |
+| `admin.oidc.clientId` | `GAME_SERVER_ADMIN_OIDC_CLIENT_ID` | none | none | The console's OpenID Connect client id. |
+| `admin.oidc.clientSecret` | `GAME_SERVER_ADMIN_OIDC_CLIENT_SECRET` | none | none | The console's OpenID Connect client secret. Secret: never logged. |
+| `admin.oidc.label` | `GAME_SERVER_ADMIN_OIDC_LABEL` | none | `Single sign-on` | Label of the single sign-on button. |
+| `admin.oidc.roleClaim` | `GAME_SERVER_ADMIN_OIDC_ROLE_CLAIM` | none | `groups` | ID token claim that carries the groups or roles mapped to console roles. |
+| `admin.oidc.roleMapping` | `GAME_SERVER_ADMIN_OIDC_ROLE_MAPPING` | none | empty | Comma-separated claim value=role pairs, e.g. admins=admin,support=moderator. |
+| `admin.oidc.allowLocalSignIn` | `GAME_SERVER_ADMIN_OIDC_ALLOW_LOCAL_SIGN_IN` | none | `true` | Allow username and password sign-in besides single sign-on (the CLI always works). |
+| `admin.passkeys.enabled` | `GAME_SERVER_ADMIN_PASSKEYS_ENABLED` | none | `true` | Offer passkeys as a second factor and for password-less console sign-in. |
+| `admin.passkeys.rpId` | `GAME_SERVER_ADMIN_PASSKEYS_RP_ID` | none | none | Passkey relying party id (unset: the console host). |
+| `admin.colyseusCloud.apiToken` | `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_TOKEN` | none | none | Colyseus Cloud API token for the console's Colyseus Cloud page (read-only, team-wide; created under API tokens in the Colyseus Cloud dashboard). Falls back to `COLYSEUS_CLOUD_TOKEN`. Secret: never logged. |
+| `admin.colyseusCloud.application` | `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_APPLICATION` | none | none | Slug of the Colyseus Cloud application the page shows, for example `1234-my-game`. Empty: the team's only application. |
+| `admin.colyseusCloud.apiUrl` | `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_URL` | none | `https://cloud-prod.colyseus.io/api/v1` | Base URL of the Colyseus Cloud API. |
+| `metrics.enabled` | `GAME_SERVER_METRICS_ENABLED` | none | `true` | Serve Prometheus metrics on GET /metrics. |
+| `metrics.requireAdminToken` | `GAME_SERVER_METRICS_REQUIRE_ADMIN_TOKEN` | none | `false` | Require the admin token on /metrics. |
+| `limits.allowedOrigins` | `GAME_SERVER_ALLOWED_ORIGINS` | `--allowed-origins` | empty | Comma-separated browser origins allowed to join (empty: any). |
+| `limits.allowMissingOrigin` | `GAME_SERVER_ALLOW_MISSING_ORIGIN` | none | `true` | Accept joins that send no Origin header (native clients). |
+| `limits.joinRequestsPerMinutePerAddress` | `GAME_SERVER_JOIN_REQUESTS_PER_MINUTE` | none | `120` | Join requests one client address may make per minute. |
+| `limits.maxSessions` | `GAME_SERVER_MAX_SESSIONS` | none | `1000` | Sessions one process hosts. |
+| `limits.maxPlayersPerSession` | `GAME_SERVER_MAX_PLAYERS_PER_SESSION` | none | `255` | Players one session accepts; larger requests are clamped. |
+| `limits.maxDedicatedSessions` | `GAME_SERVER_MAX_DEDICATED_SESSIONS` | none | `4` | Dedicated sessions one process runs. |
+| `limits.maxMessageBytes` | `GAME_SERVER_MAX_MESSAGE_BYTES` | none | `65536` | Largest WebSocket message in bytes. |
+| `limits.maxMessagesPerSecond` | `GAME_SERVER_MAX_MESSAGES_PER_SECOND` | none | `2000` | Messages one client may send per second before it is disconnected (a live change applies to new sessions). |
+| `limits.maxSessionNameLength` | `GAME_SERVER_MAX_SESSION_NAME_LENGTH` | none | `128` | Longest session name in characters. |
+| `redis.url` | `GAME_SERVER_REDIS_URL` | `--redis-url` | none | redis:// URL shared by every instance when scaled out. Secret: never logged. |
+| `leaderboards.definitionsFile` | `GAME_SERVER_LEADERBOARDS_DEFINITIONS_FILE` | `--leaderboards-definitions-file` | none | JSON file of leaderboard boards created on start when missing (relative to the working directory). |
+| `leaderboards.signedInPlayersOnly` | `GAME_SERVER_LEADERBOARDS_SIGNED_IN_PLAYERS_ONLY` | `--leaderboards-signed-in-players-only` | `false` | Only signed-in players (an auth identity with a user id) may submit leaderboard scores; anonymous entries are hidden on start. See [Signed-in players only](#signed-in-players-only). |
+| `drainSeconds` | `GAME_SERVER_DRAIN_SECONDS` | `--drain-seconds` | `30` | Seconds running sessions may continue after SIGTERM. |
+
+The config file also holds the dedicated sessions, which have no environment variable or flag (see
+[Dedicated sessions](#dedicated-sessions)):
+
+| Option | Meaning | Default |
+|---|---|---|
+| `dedicated.scenes` | The scenes dedicated sessions may run: `{ name, sceneRoot, sceneFile, projectScripts, maxPlayers, onDemand, idleSeconds }` | empty |
+| `dedicated.boot` | Dedicated sessions started with the server: `{ sessionName, sceneName }` | empty |
+
+From code, `createGameServer` takes overrides of the defaults (it reads no file or environment unless you call
+`loadGameServerConfig` yourself):
+
+```ts
+import { createGameServer, loadGameServerConfig } from "@babylonjs-toolkit/server";
+
+const running = await createGameServer({ config: { port: 2567, limits: { allowedOrigins: ["https://game.example.com"] } } });
+console.log(running.urls.webSocket);   // ws://localhost:2567
+await running.drain();                 // or close() to stop at once
+
+// The CLI's way: defaults < Colyseus Cloud's defaults (on that host only) < file < env < flags.
+const config = await loadGameServerConfig({ argv: process.argv.slice(2), environment: process.env, workingDirectory: process.cwd() });
+```
+
+`createGameServer({ config, hooks, routes, handleSignals })` also takes lifecycle hooks (`onSessionCreated`,
+`onPlayerJoined`, `onPlayerLeft`, `onSessionClosed`, and `verifyToken` for custom auth), extra HTTP endpoints made with
+the re-exported `createEndpoint`, and `handleSignals` (drain on `SIGTERM`/`SIGINT` and exit; the CLI turns it on). One
+game server runs per process.
+
+## Enabling TLS
+
+Leave TLS off when a reverse proxy or the platform edge terminates it (Caddy, an AWS load balancer, Fly.io, Railway,
+Render, DigitalOcean, Heroku): players then use the platform's `wss://` address. Turn it on when the server itself is
+the public endpoint, and always for UDP.
+
+```sh
+# Certificate files (for example from certbot); they are polled every 30 s and reloaded without a restart.
+babylon-game-server --tls --tls-cert-file /etc/ssl/game/fullchain.pem --tls-key-file /etc/ssl/game/privkey.pem
+
+# PEM text from container secrets.
+GAME_SERVER_TLS_ENABLED=true GAME_SERVER_TLS_CERT_PEM="$(cat fullchain.pem)" GAME_SERVER_TLS_KEY_PEM="$(cat privkey.pem)" babylon-game-server
+
+# A local development certificate (needs mkcert: brew install mkcert && mkcert -install).
+babylon-game-server --tls --tls-dev-cert
+# Babylon Game Server 9.30.1 listening on wss://localhost:2567
+```
+
+- `--tls-dev-cert` is refused when `NODE_ENV=production`. Without mkcert it stops with
+  `install mkcert (brew install mkcert && mkcert -install) or set tls.certFile/keyFile`, unless UDP is on (below).
+- A renewed certificate reaches `https://` and `wss://` at once. With UDP on, HTTP/3 keeps the certificate it started
+  with until the next restart, and the server logs that.
+
+## Enabling authentication
+
+With auth on, every join — sessions and the lobby — must carry a token that the server verifies at matchmaking, before
+a seat is reserved. The game sends it with `startGame({ authToken })`. A refused join fails `startGame` with the
+reason named in the message (see [Troubleshooting](#troubleshooting)). A player reconnecting within the reconnect grace
+period resumes its seat and its original identity without a new check.
+
+**Shared secret** — a fixed list of accepted tokens, compared in constant time. Good for private builds and
+server-to-server games:
+
+```sh
+GAME_SERVER_AUTH_ENABLED=true GAME_SERVER_AUTH_MODE=shared-secret GAME_SERVER_AUTH_SHARED_SECRET_TOKENS=token-one,token-two babylon-game-server
+```
+
+The identity is `{ userId: null, claims: { method: "shared-secret", keyIndex } }`.
+
+**JWT** — tokens signed by your identity provider (Auth0, Cognito, Firebase, Clerk, your own) or by your backend with
+an HMAC secret. The identity is `{ userId: <sub>, claims: <the token's payload> }`. An expired token is refused with
+`AuthenticationTicketExpired`.
+
+A walk-through with a JWKS (the provider's public keys):
+
+1. Your provider publishes its keys at a JWKS URL, for example `https://login.example.com/.well-known/jwks.json`, and
+   signs tokens with issuer `https://login.example.com/` and an audience you choose, for example `my-game`.
+2. Configure the server with that URL and the claims it must check:
+   ```js
+   // babylon-game-server.config.mjs
+   export default {
+       auth: {
+           enabled: true,
+           mode: "jwt",
+           jwt: { jwksUrl: "https://login.example.com/.well-known/jwks.json", issuer: "https://login.example.com/", audience: "my-game", algorithms: ["RS256"] }
+       }
+   };
+   ```
+   The keys are fetched on the first join and cached for 10 minutes. A token signed by an unknown key refetches them,
+   at most once every 30 seconds.
+3. The game signs the player in with the provider, then passes the provider's access token:
+   `startGame({ gameMode, sessionName, authToken: accessToken })`.
+4. The host's `onConnectRequest` reads `request.authIdentity.userId` (the token's `sub`) and any claim it needs, for
+   example a display name or a team.
+
+With an HMAC secret instead (your backend signs `HS256` tokens):
+
+```sh
+GAME_SERVER_AUTH_ENABLED=true GAME_SERVER_AUTH_MODE=jwt GAME_SERVER_AUTH_JWT_SECRET="$(openssl rand -hex 32)" GAME_SERVER_AUTH_JWT_ISSUER=my-backend babylon-game-server
+```
+
+```js
+// Your backend, with jose: a 1-hour player token.
+import { SignJWT } from "jose";
+const secret = new TextEncoder().encode(process.env.GAME_SERVER_AUTH_JWT_SECRET);
+const token = await new SignJWT({ name: "Ada" }).setProtectedHeader({ alg: "HS256" }).setSubject("player-42").setIssuer("my-backend").setExpirationTime("1h").sign(secret);
+```
+
+**Webhook** — your service approves each player. The server POSTs JSON
+`{ token, kind, sessionName, gameMode, clientAddress, origin }` (`kind` is `"session"` or `"lobby"`) to
+`GAME_SERVER_AUTH_WEBHOOK_URL` and waits up to `GAME_SERVER_AUTH_WEBHOOK_TIMEOUT_MS`. A 2xx answer with a JSON object
+admits the player with the identity `{ userId: body.userId ?? null, claims: body }`. Anything else refuses it.
+
+**Custom** — your own verifier, when you start the server from code:
+
+```ts
+await createGameServer({
+    config: { auth: { enabled: true, mode: "custom" } },
+    hooks: {
+        async verifyToken(request) {
+            const player = await lookUpSession(request.token);           // your code
+            return (player != null) ? { userId: player.id, claims: { name: player.name } } : null;   // null refuses
+        }
+    }
+});
+```
+
+A verifier may also throw `new AuthRefusal("InvalidAuthentication", "<detail>")` to choose the reason. With
+`NODE_ENV=production`, auth off and a bind address other machines can reach, the server logs one warning at startup.
+
+## Discord sign-in
+
+### What it does
+
+Players can sign in with their Discord account. The server runs Discord's website OAuth2 flow (authorization code with
+PKCE) and asks for the `identify` scope only, so it learns a player's Discord id, username, display name and avatar,
+never their email or servers. Discord's own tokens are used once to read the profile and then dropped. The server then
+issues its own session token, which lasts `discordSignIn.sessionDays` (30 days by default) and needs no Discord call
+afterwards. Sign-in is optional: players who never sign in play exactly as before. The server shows no Discord presence.
+
+### Setting it up
+
+1. Create an application in the [Discord Developer Portal](https://discord.com/developers/applications).
+2. Under **OAuth2 → Redirects**, add each server's callback address exactly, for example
+   `https://game.example.com/game-server/discord/callback` (and `http://localhost:2567/game-server/discord/callback`
+   for local testing). Discord accepts only exact matches.
+3. Copy the application's client id and client secret, and set the six options:
+
+   | Option | Environment variable | Value |
+   |---|---|---|
+   | `discordSignIn.enabled` | `GAME_SERVER_DISCORD_SIGN_IN_ENABLED` | `true` to turn sign-in on (default `false`). |
+   | `discordSignIn.clientId` | `GAME_SERVER_DISCORD_CLIENT_ID` | The application's client id. |
+   | `discordSignIn.clientSecret` | `GAME_SERVER_DISCORD_CLIENT_SECRET` | The application's client secret. Secret: never logged. |
+   | `discordSignIn.redirectUri` | `GAME_SERVER_DISCORD_REDIRECT_URI` | This server's callback, exactly as registered in step 2. |
+   | `discordSignIn.returnOrigins` | `GAME_SERVER_DISCORD_RETURN_ORIGINS` | Comma-separated game origins a sign-in may return to, e.g. `https://game.example.com`. |
+   | `discordSignIn.sessionDays` | `GAME_SERVER_DISCORD_SESSION_DAYS` | Days a sign-in lasts, 1–365 (default `30`). |
+
+   ```sh
+   GAME_SERVER_DISCORD_SIGN_IN_ENABLED=true \
+   GAME_SERVER_DISCORD_CLIENT_ID=<your client id> \
+   GAME_SERVER_DISCORD_CLIENT_SECRET=<your client secret> \
+   GAME_SERVER_DISCORD_REDIRECT_URI=https://game.example.com/game-server/discord/callback \
+   GAME_SERVER_DISCORD_RETURN_ORIGINS=https://game.example.com \
+   babylon-game-server
+   ```
+
+   With sign-in on, the server refuses to start until the client id, the secret, a callback address ending in
+   `/game-server/discord/callback` and at least one plain origin (`scheme://host[:port]`, no path) are set.
+4. Keep the client secret in your host's environment or secret store only, never in the config file or the game.
+5. In the Discord application, set the **Privacy Policy URL** to your game's privacy page.
+
+`GET /game-server/info` answers `discordSignIn: true` once it is on, so a game can show its sign-in button only then.
+The session signing key is created on the first start and kept in the admin data (`admin.dataDir` or Redis), so every
+instance and every restart accept the same sessions. If that data is lost, players simply sign in again.
+
+### How it works with player auth
+
+The game sends the session token as its auth token, on joins (`startGame({ authToken })`) and on leaderboard calls
+(`Authorization: Bearer`). A token issued by this server's Discord sign-in is recognised first and verified by the
+server itself. Any other token goes to the configured auth mode, or the player is anonymous when auth is off. So Discord
+sign-in works beside every mode, and anonymous play stays exactly what each mode allows. An expired session is refused
+with `AuthenticationTicketExpired` and a tampered one with `InvalidAuthentication`; the player signs in again.
+
+The identity a host sees is `{ userId: "discord:<id>", claims }`, where the claims are the session token's payload:
+
+| Claim | Value |
+|---|---|
+| `sub` | `discord:<Discord user id>` |
+| `name` | The Discord display name (the global name, else the username) |
+| `avatar` | The Discord avatar hash, or `null` for the default avatar |
+| `provider` | `"discord"` |
+| `name_managed` | `true`: the name comes from the sign-in, so the player cannot rename themselves |
+
+The console's token tester and key tools test the configured auth mode only.
+
+### Routes
+
+All four answer 404 `{ reason: "discordSignInOff" }` while sign-in is off.
+
+| Method | Path | Answer |
+|---|---|---|
+| GET | `/game-server/discord/start?returnTo=<url>` | 302 to Discord's consent page (Discord skips it for a player who already approved). `returnTo` must be an absolute http(s) address on one of `returnOrigins`, with no query, fragment or user info; anything else answers 400 `{ reason: "returnNotAllowed" }` and redirects nowhere. Sets a short-lived `bt_discord_return` cookie (10 minutes, `HttpOnly`, `SameSite=Lax`). |
+| GET | `/game-server/discord/callback` | Discord's redirect back. 302 to `returnTo?code=<code>` on success, or to `returnTo?signin=cancelled` (the player pressed Cancel), `signin=busy` (Discord is rate limiting or down) or `signin=failed` (an expired, replayed or tampered sign-in, or Discord refused). Without a usable sign-in or cookie it answers a 400 text page. |
+| POST | `/game-server/discord/session` | Body `{ code, playerKey? }`, sent from the game's origin. Trades the single-use code (valid 2 minutes) for `{ session: { token, expiresAt, userId, discordId, displayName, avatarHash }, merged }`. 400 `invalidRequest`, 401 `handoffInvalid` (unknown, used or expired code), 403 `originNotAllowed` (another origin). |
+| GET | `/game-server/discord/session-players?sessionName=<name>` | `{ players: [{ playerId, userId, displayName, avatar }] }`: the players of a running session who joined signed in with Discord, so every page can mark verified names. Typed names are never listed. `{ players: [] }` for an unknown session; 400 without a name; 403 for an origin outside `limits.allowedOrigins`. |
+
+### Leaderboards
+
+A signed-in player's leaderboard player is `user:discord:<id>`, named with their Discord display name.
+
+- **First sign-in merge.** When the exchange sends the browser's anonymous player key (`playerKey`) and the Discord
+  player does not exist yet, the anonymous player's entries move onto the new Discord player once, by each board's keep
+  policy, and the anonymous player is erased (`merged: true`). An existing Discord player is never merged into: the
+  anonymous entries stay where they are, and the Discord player's name and avatar are refreshed from the sign-in.
+- **Avatars.** Public `entries`, `around` and `players` reads carry each Discord player's `avatar` (the hash; `null`
+  for everyone else).
+- **Names.** Renaming (`POST players/me/name`) answers 403 `{ reason: "nameManaged" }` for a signed-in player. Delete My
+  Data (`POST players/me/delete`) works with the session, as it does with an anonymous key.
+
+## Enabling UDP
+
+With UDP on, the server also accepts WebTransport over HTTP/3 on the same port number (UDP beside TCP). Frames on
+`RpcChannel.Unreliable` — snapshots, inputs, acks and unreliable RPCs — then travel as datagrams, so a lost packet no
+longer holds up the ones behind it. Reliable frames, and frames over 1000 bytes, keep the reliable stream. Players
+whose browser or network cannot use WebTransport connect over WebSocket and play in the same session.
+
+```sh
+babylon-game-server --tls --tls-cert-file fullchain.pem --tls-key-file privkey.pem --udp
+# Babylon Game Server 9.30.1 listening on wss://localhost:2567
+#   HTTP:         https://localhost:2567
+#   WebTransport: https://localhost:2567
+#   TLS: on (files)   UDP: on (WebTransport on https://localhost:2567, UDP 2567)   Auth: off   Redis: off
+```
+
+Requirements:
+
+- **TLS on the server itself.** HTTP/3 always uses TLS, and the QUIC connection must end at the server, so a proxy that
+  terminates TLS in front of it cannot carry UDP.
+- **The port open for UDP as well as TCP**: firewall, cloud security group, `docker run -p 443:443/tcp -p 443:443/udp`.
+- **A host that forwards inbound UDP.** VMs and bare metal (AWS EC2, DigitalOcean Droplets, Hetzner and similar),
+  Kubernetes with a UDP-capable load balancer, and AWS ECS behind a Network Load Balancer with `TCP_QUIC` listeners do.
+  Fly.io, Railway, Render, DigitalOcean App Platform and Heroku do not; there the server runs WebSocket only.
+- **A browser with WebTransport**: Chrome and Edge 97+, Firefox 115+, Safari 26.4+. Others fall back to WebSocket.
+- **The optional native package `@colyseus/h3-transport`**, installed automatically where it builds. Where it does not,
+  startup stops with `UDP needs @colyseus/h3-transport, which is not installed on this platform`.
+
+**Local development.** `--tls --tls-dev-cert --udp` works on one machine without a real certificate: HTTPS and WSS use
+the mkcert certificate, and HTTP/3 uses its own 10-day self-signed certificate whose SHA-256 hash the server sends at
+matchmaking and in `/game-server/info`, so the browser pins it (browsers refuse WebTransport to locally trusted roots
+such as mkcert's). Without mkcert that pinned certificate serves HTTPS too. HTTP/3 binds every IPv6 and IPv4 interface
+(`::`) when the machine has IPv6, because browsers resolve `localhost` to `::1` first.
+
+## Abuse limits
+
+These are on by default and checked at matchmaking. Every refusal is counted in
+`babylon_game_server_refusals_total{reason}` and logged.
+
+| Limit | Option | Default | Refusal |
+|---|---|---|---|
+| Browser origins allowed to join (empty: any) | `limits.allowedOrigins` | empty | 403 `ConnectionRefused` |
+| Joins with no `Origin` header (native clients, tools) | `limits.allowMissingOrigin` | `true` | 403 `ConnectionRefused` |
+| Join requests per client address per minute | `limits.joinRequestsPerMinutePerAddress` | `120` | 429 `ConnectionRefused` |
+| Sessions per process | `limits.maxSessions` | `1000` | 503 `MaxCcuReached` |
+| Players per session (larger requests are clamped) | `limits.maxPlayersPerSession` | `255` | — |
+| Dedicated sessions per process | `limits.maxDedicatedSessions` | `4` | 503 `MaxCcuReached` |
+| Largest WebSocket message, in bytes | `limits.maxMessageBytes` | `65536` | the connection closes |
+| Messages per client per second | `limits.maxMessagesPerSecond` | `2000` | the client is disconnected |
+| Session name length; control characters are refused | `limits.maxSessionNameLength` | `128` | 400 `InvalidArguments` |
+
+`allowedOrigins` also sets the CORS answer, so a browser on another origin cannot call the server at all. Set it to your
+game's origins in production, for example `GAME_SERVER_ALLOWED_ORIGINS=https://game.example.com`.
+
+The client address is the socket's own address. Behind your own reverse proxy, set `trustProxy` so the server reads
+`X-Forwarded-For` / `X-Real-IP` instead; never set it on a server clients reach directly, or any client could choose
+its address.
+
+## Endpoints
+
+Every endpoint answers on the server's port, over HTTP and HTTPS alike, with CORS.
+
+| Method | Path | Answer |
+|---|---|---|
+| GET | `/game-server/health` | 200 `{ "status": "ok" }` while the process runs (liveness). |
+| GET | `/game-server/ready` | 200 `{ "ready": true }`, or 503 `{ "ready": false, "reasons": [...] }` while draining, when Redis does not answer, or before it listens (readiness). |
+| GET | `/game-server/info` | `{ serverName, serverVersion, protocolVersion, transports: { webSocket, webTransport: { port, certificateHash } \| null }, authRequired, discordSignIn }`. Games read it before joining. |
+| GET, POST | `/game-server/leaderboards/*` | The [leaderboards public API](#public-api): boards, rankings, a player's own entries and score submissions. |
+| GET | `/game-server/discord/start` | [Discord sign-in](#discord-sign-in): 302 to Discord, or 400 `returnNotAllowed`. 404 while sign-in is off (all four Discord routes). |
+| GET | `/game-server/discord/callback` | Discord's redirect back: 302 to the game with `code=` or `signin=cancelled\|busy\|failed`. |
+| POST | `/game-server/discord/session` | `{ code, playerKey? }` → `{ session, merged }`; 401 `handoffInvalid`, 403 `originNotAllowed`. |
+| GET | `/game-server/discord/session-players?sessionName=` | `{ players: [{ playerId, userId, displayName, avatar }] }`: the verified Discord players of a session. |
+| GET | `/metrics` | Prometheus text. 404 when `metrics.enabled` is off; 403 without the admin token when `metrics.requireAdminToken` is on. |
+| GET | `/game-server/admin/sessions` | Admin: every session `{ roomId, sessionName, gameMode, players, maxPlayers, isDedicated }` (every instance when scaled out). |
+| POST | `/game-server/admin/sessions/:roomId/close` | Admin: disconnects that session's players. 200 `{ closed }`, 404 when there is no such session. |
+| POST | `/game-server/admin/dedicated` | Admin: body `{ sceneName, sessionName }` starts a dedicated session of a configured scene. 201 `{ roomId }`; 400, 404 (unknown scene) or 503 (it did not start). |
+| POST | `/game-server/admin/drain` | Admin: starts a drain without exiting the process. 202 `{ draining: true }`. |
+
+These four legacy admin endpoints exist only when `admin.token` is set; without it they answer 404. Admin calls send
+`Authorization: Bearer <token>`; a missing or wrong token answers 401. They keep their paths and answers; the
+[admin console](#admin-console) and its API at `/game-server/admin/api/` do everything they do and more, with accounts,
+roles and API keys.
+
+```sh
+curl -H "Authorization: Bearer $GAME_SERVER_ADMIN_TOKEN" https://game.example.com/game-server/admin/sessions
+```
+
+## Admin console
+
+The server ships a web console at `/game-server/admin/` for the people who run it: the fleet overview and its
+instances, sessions and players (kick, notices, bans), maintenance mode and drains, dedicated sessions, metrics charts,
+live logs, live-editable limits, auth tools, alerts with webhook, Slack, Discord, Teams and PagerDuty channels, users,
+API keys, an audit log of every action, your own [custom actions and panels](CUSTOM.md#custom-admin-actions-panels-and-admin-hooks),
+and these docs. It runs inside the server process on the server's own port; there is nothing extra to install or
+deploy. Every page is also an HTTP API at `/game-server/admin/api/`, which scripts call with an API key.
+
+The console is on (`admin.console`, default `true`) whenever an admin account exists or a first-owner setup is pending.
+With no account, no pending setup and no `admin.token`, every admin path answers 404.
+
+### The first Owner
+
+On the first start with no admin account, the server logs a one-time setup link at `warn`:
+
+```text
+[GameServer] admin setup link url=http://localhost:2567/game-server/admin/#/setup?token=…
+```
+
+Open it within 30 minutes (it works once) to create the first Owner: a username, a display name and a password of at
+least 12 characters that is not a common password and does not contain the username. Then scan the QR code with an
+authenticator app (or type its key), confirm a code, and keep the ten recovery codes it shows. Behind a TLS edge, open
+the link's path on your HTTPS address. With several processes on Redis, each logs its own link and any one works through
+the load balancer; the first Owner ends them all.
+
+Or create the Owner from the command line, where the server's data is (the same `--config`, Redis or data folder):
+
+```sh
+GAME_SERVER_OWNER_PASSWORD='…' npx babylon-game-server admin create-owner --username ada --display-name "Ada" --password-env GAME_SERVER_OWNER_PASSWORD
+```
+
+The new Owner enrols an authenticator at the first sign-in.
+
+### Signing in
+
+Every account signs in with two factors: its password, then a six-digit authenticator code (TOTP), a passkey, or one of
+its recovery codes. A passkey can also sign in without the password when `admin.passkeys.enabled` is on (the default).
+With `admin.oidc.*` set, the sign-in page also offers OpenID Connect single sign-on (authorization code with PKCE);
+roles come from `admin.oidc.roleClaim` through `admin.oidc.roleMapping`, and the account's own code is still asked
+unless the identity provider reports multi-factor sign-in.
+
+Ten failed sign-ins in 15 minutes lock an account (an Owner or Admin unlocks it, or `admin unlock`), and repeated
+failures from one address are slowed down. A console session ends after `admin.sessionIdleMinutes` (30) idle minutes
+or `admin.sessionMaxHours` (12) hours. Dangerous actions (users, API keys, fleet-wide maintenance and notices, drains,
+rolling updates, closing every session, importing bans, alert channels, audit retention) ask for a fresh code, which
+then covers 5 minutes.
+
+### Roles
+
+Each account has one fixed role. Every role can view the overview, instances, sessions, players, dedicated sessions,
+metrics, configuration, alerts and the Colyseus Cloud page except its billing.
+
+| Role | What it adds |
+|---|---|
+| Owner | Everything, including other Owners and the audit log retention. Colyseus Cloud billing. |
+| Admin | Everything except audit log retention; cannot grant or change the Owner role. Colyseus Cloud billing. |
+| Operator | Fleet (maintenance, drains, rolling updates, schedules), close and lock sessions, dedicated sessions, live config edits, alerts, log levels, logs, auth status, the audit log, the user list, player notes, custom actions. |
+| Moderator | Players (addresses, kick, notices, lobby kick), bans, close and lock sessions, player notes, logs, auth status, the audit log, the user list, custom actions. |
+| Developer | The session inspector, dedicated sessions, logs, auth status, the audit log, the user list, bans (read), player addresses, developer custom actions. |
+| Viewer | Read-only pages only. |
+
+Only an Owner may create, change or remove another Owner, and the last enabled Owner cannot be removed, demoted,
+disabled or locked. The permission names (`ADMIN_PERMISSIONS`) and each role's set (`ROLE_PERMISSIONS`) are exported
+from the package.
+
+### API keys and the legacy token
+
+For scripts and CI, create an API key on the console's API keys page or with
+`babylon-game-server admin create-api-key --name ci --permissions sessions.view,players.manage [--expires-days 90]`.
+A key looks like `bgsk_<id>_<secret>`, is shown once, holds only the permissions you give it, and can expire or be
+limited to networks. Only its hash is stored. Send it as a bearer token:
+
+```sh
+curl -H "Authorization: Bearer $GAME_SERVER_API_KEY" https://game.example.com/game-server/admin/api/sessions
+```
+
+The configured `admin.token` is accepted by the API too, as a key named "legacy admin token" with every permission
+except managing users and the audit log retention. Every change, by key, token or account, is in the audit log.
+
+### Command line
+
+`babylon-game-server admin <command> [--config <file>] [--redis-url <url>] [--admin-data-dir <folder>]` works on the
+same store as the server, running or not, and is the way back in when nobody can sign in:
+
+| Command | What it does |
+|---|---|
+| `list-users` | Lists the accounts with their roles and state. |
+| `create-owner --username <name> [--display-name <name>] [--password-env <VARIABLE>]` | Creates an Owner (asks for the password on a terminal). |
+| `reset-password --username <name> [--password-env <VARIABLE>]` | Sets a new password and ends the account's sessions. |
+| `reset-second-factor --username <name>` | The account enrols a new authenticator at its next sign-in. |
+| `unlock --username <name>` | Unlocks a locked account. |
+| `end-sessions --username <name>` | Signs the account out everywhere. |
+| `create-api-key --name <name> --permissions <comma list> [--expires-days <days>]` | Creates an API key and prints it once. |
+| `revoke-api-key --key-id <id>` | Revokes an API key. |
+
+Every command is written to the audit log.
+
+### Network restriction and HTTPS
+
+- The console and its API refuse plain HTTP with 403 `the console needs HTTPS`, except from a loopback address
+  (`127.0.0.1`, `::1`). Serve them over TLS on the server, or behind a TLS edge with `trustProxy` on (the edge's
+  `x-forwarded-proto: https` is trusted only then).
+- `admin.allowedNetworks` (`GAME_SERVER_ADMIN_ALLOWED_NETWORKS`, addresses or CIDR ranges) limits who can reach the
+  console and its API at all; other addresses get 404. With `trustProxy` on, the address is the forwarded one.
+- Console pages send a strict content security policy, `x-frame-options: DENY` and no referrer. The session cookie is
+  `HttpOnly` and `SameSite=Strict`, and every change carries a CSRF header.
+
+### Where the data lives
+
+Accounts, console sessions, API keys, bans, the audit log, alert rules, console config overrides and player notes live
+in one admin store:
+
+- **Redis**, when `redis.url` is set: every instance shares it, so the console sees and manages the whole fleet from
+  any instance. Turn on Redis persistence (append-only file or your provider's backups).
+- **Files** in `admin.dataDir` (`GAME_SERVER_ADMIN_DATA_DIR`, default `./babylon-game-server-data`) otherwise: one JSON
+  file per collection and a JSON-lines file per log stream, written atomically. The Docker image sets it to `/data`
+  and declares a volume there: mount one (`-v game-server-data:/data`), or the data goes with the container.
+
+The audit log is append-only with a hash chain the console can verify; it keeps 365 days by default (an Owner changes
+it).
+
+The [leaderboards](#storage-and-durability) keep their scores in the same Redis or data folder, and the console warns
+when that storage does not survive a restart.
+
+### Security advice
+
+- Serve the console over HTTPS only, and limit `admin.allowedNetworks` to your office or VPN, or block
+  `/game-server/admin/` at the edge and reach it from inside your network.
+- Give each person their own account with the lowest role that does their job; use API keys with only the permissions
+  a script needs, and an expiry. Keep `admin.token` only while old scripts need it.
+- Keep the recovery codes somewhere safe; the CLI resets a lost factor (`reset-second-factor`).
+- Back up the data folder or Redis: it holds the bans, the audit log and the leaderboards.
+- Treat the setup link like a password; it is valid for 30 minutes and works once.
+
+### Colyseus Cloud page
+
+When the server runs on Colyseus Cloud, or has a Colyseus Cloud API token anywhere else, the console's **Colyseus
+Cloud** page shows the application as Colyseus reports it: each location and instance and their status, each host
+process's status, restarts and Node.js version (silent instances flagged), charts of the last 30 days, traffic per day,
+recent deploys with their build output, an instance's latest host log lines (startup failures and crashes included), and
+the billing summary. Live players, rooms, CPU and memory stay on **Instances**, the last 24 hours on **Metrics**, and the
+server's own log lines on **Logs**.
+
+1. In the Colyseus Cloud dashboard, open **API tokens** and create a token. It is read-only and covers the whole team.
+2. Set `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_TOKEN` to it (on Colyseus Cloud, on the application's environment
+   variables; `COLYSEUS_CLOUD_TOKEN` works too). If the team has more than one application, also set
+   `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_APPLICATION` to the slug of the one this server runs, for example `1234-my-game`.
+3. Restart or redeploy.
+
+The server reads the Cloud API itself: one process reads it for all of them, no faster than Colyseus refreshes each
+figure, and the token never reaches a browser. Log lines and deploy output are read only when you ask, and Colyseus
+allows two log requests a minute for the whole team. Every role can view the page; billing needs Owner or Admin, and
+logs need a role that can view logs. When Colyseus is busy or unreachable, each part keeps its last figures and says
+why they are not current.
+
+### Leaderboards page
+
+The **Leaderboards** section, in the Players group after Bans, runs the [built-in leaderboards](#leaderboards). Every
+role can view it (`leaderboards.view`); Owner, Admin, Operator and Moderator can change it (`leaderboards.manage`).
+
+- A status strip above every tab shows scores accepted and refused per minute across the fleet, the storage (Redis or
+  files), a warning when it is not durable or a note when that is unknown (with what to change), and any problem with
+  the definitions file.
+- **Boards** lists every board. Create, edit, duplicate and delete boards here; a board whose current season has entries refuses a change of sort order, score format or keep rule
+  unless the edit starts a new season.
+- **A board** shows one ranking at a time: pick the season and the variant, search players, and add an entry, correct a
+  score or remove one (each with a reason), or restore a removed entry. Reset the season (with a reason) or delete an
+  archived one. Export CSV downloads the ranking shown.
+- **Players** lists every leaderboard player: rename, hide (their entries leave every ranking and their new scores are
+  discarded until they are shown again), merge one player into another (after a lost key, say), or erase all of a
+  player's data.
+- **Activity** lists every score the server accepted, recognised as a duplicate delivery, or refused, with the reason,
+  newest first. Client addresses show only to roles that can view player addresses.
+- **Settings** holds the fleet-wide abuse limits and blocked words, and the backups: export every board, season, entry
+  and player as `leaderboards.json`, and import a backup or a definitions file after a preview.
+
+The **Metrics** page charts accepted and refused scores. Deleting a board, resetting or deleting a season, merging or
+erasing a player and a real (not preview) import ask for a fresh code. Every change is in the audit log under
+`leaderboard.*` actions.
+
+### Help inside the console
+
+The console's Documentation page shows this README, [DEPLOY.md](DEPLOY.md) and [CUSTOM.md](CUSTOM.md) from the
+installed package, and each page's help panel (the `?` key) links to the section that explains it.
+
+## Leaderboards
+
+Every server ranks the scores games send it, with no code and no extra service: boards, seasons, trust levels, abuse
+limits, a [console page](#leaderboards-page) and backups. Leaderboards are on by default. Games talk to them over HTTP
+at `/game-server/leaderboards/` (the toolkit's `TOOLKIT.LeaderboardClient` does it for you), so a single-player menu
+needs no network session. Clients never create boards: they come from the [definitions file](#the-definitions-file) or
+the console.
+
+### Boards and seasons
+
+A board ranks one kind of score. Its definition sets:
+
+| Field | Meaning |
+|---|---|
+| `boardId` | Stable id, lower-case letters, digits and `-` (`/^[a-z0-9][a-z0-9-]{0,63}$/`). |
+| `displayName`, `description` | Shown to players and in the console (1–80 and 0–500 characters). |
+| `sortOrder` | `higherIsBetter` (points, counters) or `lowerIsBetter` (times). |
+| `scoreFormat` | `integer`, `points`, or `timeMilliseconds` (shown as a time). Scores are always whole numbers; times are milliseconds. |
+| `keepPolicy` | `best` (keep a player's best score), `latest` (always replace) or `sum` (add every score: a running total). |
+| `minimumScore`, `maximumScore` | Limits for each submitted score, or `null`. On a `sum` board they apply to each score, not to the total. |
+| `acceptedTrustLevels` | Which [trust levels](#players-and-trust-levels) the board accepts: any of `client`, `session`, `server`. |
+| `visibility` | `public`, or `hidden`: a hidden board is absent from the public API and refuses scores. |
+| `resetSchedule` | `never`, `manual`, `daily`, `weekly` or `monthly` (UTC). |
+| `dimensions` | Up to 4 ways to split the rankings, each `{ name, label, values }` with 1–100 allowed values. |
+
+**Variants.** A board with dimensions keeps one ranking per combination of values: `arena-high-score` split by `map`
+and `difficulty` has a ranking for `harbor` + `hard`, another for `canyon` + `normal`, and so on. A score names every
+dimension with an allowed value (`variant: { map: "harbor", difficulty: "hard" }`); anything else is refused
+`variantNotAllowed`. A board without dimensions has one ranking.
+
+**Ranking.** Better scores rank first; a tie goes to the score reached first. Ranks start at 1. Each score answers with
+the player's new rank, the ranking's size, and whether it was a personal best.
+
+**Seasons.** Every board starts at season 1. A reset, scheduled or from the console, archives the current season and
+starts the next one empty. Archived seasons stay readable (`?season=<id>`) until the console deletes them; the current
+season cannot be deleted. `daily` resets at 00:00 UTC, `weekly` on Monday 00:00 UTC and `monthly` on the 1st at 00:00
+UTC; with several processes exactly one of them runs the reset. `manual` boards reset only from the console, and a
+`never` board refuses resets until its schedule changes.
+
+### Players and trust levels
+
+**Players.** When the server's [authentication](#enabling-authentication) yields a user id (jwt, webhook or custom), the
+player is that user (`user:<userId>`), named from the token. Otherwise the game creates an anonymous player once (`POST
+players`), which answers a one-time `playerKey`. The game keeps it on the device and sends it in the JSON body of every
+request that names the player, never in a header or URL. The server stores only a hash of the key. A lost key means a
+new player; the console can merge the two. Players choose a display name of up to 24 characters (`POST
+players/me/name`); names with a blocked word are refused. A player can erase their own data (`POST
+players/me/delete`).
+
+**Trust levels.** The server decides how far each score can be trusted; a client cannot claim a level:
+
+| Level | When |
+|---|---|
+| `client` | A score from a game client with no session proof. Fine for single-player boards. |
+| `session` | A public submission whose `sessionName` names a session the player (their address, or their auth user) joined within the last 6 hours, early enough for the score: on a `timeMilliseconds` board the join must be at least the score's time before the submission, give or take 5 seconds. |
+| `server` | Only `POST /game-server/admin/api/leaderboards/submit`, called with an API key holding `leaderboards.submit` (for example from a dedicated session or your own backend). |
+
+Each board lists the levels it accepts; a score at any other level is refused `trustLevelNotAccepted`. A board of
+network results accepts `["session", "server"]`; a single-player board accepts all three.
+
+**Moderation.** Bans refuse every leaderboard request from a banned player or address. A hidden player's entries leave
+every ranking, and their new scores are discarded quietly (the game sees an accepted score with no rank) until the
+console shows them again.
+
+### Signed-in players only
+
+Set `leaderboards.signedInPlayersOnly` (`GAME_SERVER_LEADERBOARDS_SIGNED_IN_PLAYERS_ONLY`,
+`--leaderboards-signed-in-players-only`) to `true` to keep anonymous names off the boards. Guests can still play,
+networked sessions included; only their scores stay off.
+
+- **What it refuses.** A public `POST submissions` whose verified identity has no user id — the shared-secret token,
+  or a server with authentication off — answers 403 `{ reason: "signInRequired" }` and writes nothing. A
+  [Discord sign-in](#discord-sign-in) session, or a jwt, webhook or custom auth user, submits as before. Server-trust
+  submissions (`POST /game-server/admin/api/leaderboards/submit` with an API key) and entries added on the console are
+  not affected.
+- **The start-up sweep.** On every start with the option on, each anonymous player's (`anon-…`) live entry, in every
+  season of every board, moves to its ranking's Removed list (reason `anonymousPlayer`, removed by `server`). Ranks and
+  totals close up at once on every read; nothing is deleted and player records are untouched. The sweep is safe to
+  repeat and to run on several instances: a second start finds nothing left to move.
+- **Restoring an entry.** Open the board on the console's Leaderboards page, pick the season and variant, and restore
+  the entry from its Removed list. Turning the option off restores nothing by itself.
+
+### Submitting at key stages
+
+Send scores at key stages only — the end of a match, a round or a level, the end of a multi-part run — never per
+event, per kill or per frame. One stage is **one request**, carrying every board that stage updates: a match finish
+sends its high score and its win counter together. That keeps requests few, inside the rate limits, and lets the
+server check the whole run at once.
+
+Every submission is the same envelope:
+
+```json
+{
+    "playerKey": "anon-….<secret>",
+    "submissionId": "3f1c9a52-6f0e-4bd4-9d1e-0c2a7b4e8f10",
+    "gameMode": "arena",
+    "buildVersion": "1.4.0",
+    "sessionName": null,
+    "durationMs": 184000,
+    "clientTime": "2026-11-09T18:20:00.000Z",
+    "scores": [
+        { "boardId": "arena-high-score", "variant": { "map": "harbor", "difficulty": "hard" }, "score": 1840, "metadata": { "hero": "knight" } },
+        { "boardId": "arena-wins", "variant": null, "score": 1, "metadata": null }
+    ]
+}
+```
+
+- `submissionId` makes delivery exactly-once: a repeat of the same id within 7 days answers `duplicate` and writes
+  nothing, so a game can safely send again after a timeout.
+- `durationMs` is how long the run lasted. On a `timeMilliseconds` board, a time longer than the run (plus 5 seconds)
+  is refused `implausibleDuration`.
+- `sessionName` asks for the `session` trust level.
+- `metadata` is display-only: free JSON (1024 bytes by default) shown next to the entry, never ranked, filtered or
+  queried. Put the ranked facts in the score and the variant.
+- A submission carries at most 10 scores by default. Each answers `accepted` (with `created`, `improved`, `replaced`,
+  `added` or `kept`), `duplicate` or `refused` with its reason.
+
+### The definitions file
+
+Point `leaderboards.definitionsFile` (`GAME_SERVER_LEADERBOARDS_DEFINITIONS_FILE`, `--leaderboards-definitions-file`)
+at a JSON file in your repository, resolved against the working directory. Every server process reads it at start and
+creates the boards that do not exist yet; a board that exists, created by the file before or by the console, is left
+as it is, so console edits survive restarts. A missing or invalid file is logged as an error, the server starts anyway,
+and the console's Boards page shows the problem.
+
+```json
+{
+    "format": "babylon-game-server-leaderboard-definitions",
+    "version": 1,
+    "boards": [
+        {
+            "boardId": "arena-high-score", "displayName": "Arena High Score", "description": "Best score in one arena match.",
+            "sortOrder": "higherIsBetter", "scoreFormat": "points", "keepPolicy": "best",
+            "minimumScore": 0, "maximumScore": 1000000,
+            "acceptedTrustLevels": ["client", "session", "server"], "visibility": "public", "resetSchedule": "monthly",
+            "dimensions": [
+                { "name": "map", "label": "Map", "values": ["harbor", "canyon"] },
+                { "name": "difficulty", "label": "Difficulty", "values": ["normal", "hard"] }
+            ]
+        },
+        {
+            "boardId": "arena-wins", "displayName": "Arena Wins", "description": "Arena matches won.",
+            "sortOrder": "higherIsBetter", "scoreFormat": "integer", "keepPolicy": "sum",
+            "minimumScore": 1, "maximumScore": 1,
+            "acceptedTrustLevels": ["client", "session", "server"], "visibility": "public", "resetSchedule": "manual",
+            "dimensions": []
+        },
+        {
+            "boardId": "speedrun-time", "displayName": "Speedrun", "description": "Fastest full run.",
+            "sortOrder": "lowerIsBetter", "scoreFormat": "timeMilliseconds", "keepPolicy": "best",
+            "minimumScore": 1000, "maximumScore": 3600000,
+            "acceptedTrustLevels": ["client", "session", "server"], "visibility": "public", "resetSchedule": "never",
+            "dimensions": []
+        }
+    ]
+}
+```
+
+```js
+// babylon-game-server.config.mjs
+export default { leaderboards: { definitionsFile: "./leaderboards.json" } };
+```
+
+The console's backup export (`leaderboards.json` with every season, entry and player) is a different format; import it
+from the console's Settings tab.
+
+### Storage and durability
+
+Scores live where the admin store does: in Redis when `redis.url` is set (keys under `bgs:lb:`), otherwise in files
+under `admin.dataDir/leaderboards/`. The console reports, never assumes, whether that storage survives a restart:
+
+- **Files** are durable only when the data folder is persistent (a mounted volume). On a host without volumes, or a
+  container without one, every deploy loses the boards.
+- **Redis** is durable when it keeps an append-only file or RDB snapshots. When the server cannot ask (`INFO` or
+  `CONFIG` restricted, as on some managed hosts), durability shows as unknown.
+
+The Boards page shows a warning when the boards are not durable, a note when it cannot tell, and what to change. For
+production, use a Redis with persistence (on Colyseus Cloud, an external `REDIS_URI`; see DEPLOY.md) or a mounted
+volume, and export a backup from the console's Settings tab before risky changes.
+
+### Public API
+
+Paths are under `/game-server/leaderboards/`. With the server's [authentication](#enabling-authentication) on, every
+request sends `Authorization: Bearer <token>` (the token the game joins with). Requests that name a player are POSTs
+carrying `playerKey` in the JSON body (omitted for an auth user); anonymous reads of public data are GETs. Bodies are
+limited to 64 KB, browser origins follow `limits.allowedOrigins`, and each address may read 240 times a minute by
+default.
+
+| Method | Path | Body or query | Answer |
+|---|---|---|---|
+| POST | `players` | `{ playerKey? }` | `{ player, playerKey }`: creates an anonymous player when there is no auth user and no valid key (`playerKey` is non-null only then). |
+| POST | `players/me` | `{ playerKey? }` | The player `{ playerId, displayName, kind, createdAt }`. |
+| POST | `players/me/name` | `{ playerKey?, displayName }` | The renamed player. |
+| POST | `players/me/delete` | `{ playerKey? }` | `{ erasedEntries }`: the player's entries and record are erased. |
+| GET | `boards` | — | The public boards with their current season and next reset. |
+| GET | `boards/:boardId/seasons` | — | The board's seasons. |
+| GET | `boards/:boardId/entries` | `?variant=<JSON object>&season=<id>&offset=&limit=` | A page of one ranking `{ boardId, seasonId, variantKey, total, offset, entries }` (10 by default, at most 100). |
+| POST | `boards/:boardId/around` | `{ playerKey?, variant, seasonId?, window? }` | The entries around the player (up to 10 each side), with `playerRank` (null without an entry). |
+| POST | `boards/:boardId/players` | `{ variant, seasonId?, playerIds }` | Those players' entries (at most 50 ids), for a friends list. |
+| POST | `entries/mine` | `{ playerKey?, targets: [{ boardId, variant, seasonId? }] }` | The player's entry in each ranking (at most 20), or null. |
+| POST | `submissions` | The [submission envelope](#submitting-at-key-stages) | `{ submissionId, playerId, results }`, one result per score. |
+
+A refused request answers JSON `{ error, reason }` with its HTTP status: 400 for a bad request (`invalidRequest`,
+`tooManyScores`, `nameInvalid`, `nameBlocked`, …), 401 `authRequired`, `authRefused` or `invalidPlayer` (an unknown
+player key), 403 `banned`, `signInRequired` (a submission without a signed-in player while
+[`leaderboards.signedInPlayersOnly`](#signed-in-players-only) is on) or a disallowed origin, 404 `unknownBoard`, 429 `rateLimited`. A score refused inside a
+submission is reported in its own result instead, beside the accepted ones. Limits
+per minute (submissions per player and per address, reads per address), new players per hour per address, scores per
+submission, metadata size and blocked words are fleet-wide and editable on the console's Settings tab.
+
+## Metrics
+
+`GET /metrics` serves Prometheus metrics, all prefixed `babylon_game_server_`:
+
+| Metric | Type | Labels |
+|---|---|---|
+| `players` | gauge | `game_mode` |
+| `sessions` | gauge | `game_mode` |
+| `dedicated_sessions` | gauge | — |
+| `joins_total` | counter | `result` |
+| `refusals_total` | counter | `reason` (the `ShutdownReason` name) |
+| `auth_failures_total` | counter | `mode` |
+| `frames_total` | counter | `direction` (`in`/`out`), `transport` (`websocket`/`webtransport`), `channel` (`reliable`/`unreliable`) |
+| `bytes_total` | counter | `direction`, `transport` |
+| `dedicated_tick_overruns_total` | counter | — |
+| `dedicated_frame_seconds` | histogram | — |
+| `leaderboard_scores_total` | counter | `result` (`accepted`, `duplicate`, `refused`) |
+| `leaderboard_refusals_total` | counter | `reason` (the leaderboard refusal reason, for refused scores and refused requests) |
+
+The Node.js process metrics (CPU, memory, event-loop lag, garbage collection) carry the same prefix.
+
+## Scaling with Redis
+
+One process hosts many sessions; a session always lives in one process. To run several instances behind one address,
+give every instance the same Redis and its own public address:
+
+```sh
+GAME_SERVER_REDIS_URL=redis://redis.internal:6379 GAME_SERVER_PUBLIC_ADDRESS=game-1.example.com babylon-game-server
+GAME_SERVER_REDIS_URL=redis://redis.internal:6379 GAME_SERVER_PUBLIC_ADDRESS=game-2.example.com babylon-game-server
+```
+
+Matchmaking on any instance then finds every session, and a player joining a session on another instance is sent to
+that instance's public address (`host[:port]`, reachable by players). The lobby lists every instance's sessions, and
+the admin API sees and closes them. Readiness answers 503 while Redis does not answer. The Kubernetes recipe sets each
+pod's public address from the pod IP.
+
+Draining: on `SIGTERM` (or `POST /game-server/admin/drain`) the server stops taking joins (readiness 503, joins refused
+with `GameClosed`), lets running sessions continue for up to `drainSeconds`, then tells the remaining players the
+session closed (`GameClosed`) and exits. Give the platform's stop timeout a few seconds more than `drainSeconds`.
+
+## Dedicated sessions
+
+A dedicated session runs a headless `TOOLKIT.NetworkRunner` in **Server** mode: it loads the same exported scene the
+browsers load, on a Babylon.js `NullEngine` with Havok and no materials or textures, and simulates everything. Players
+join with `GameMode.Client` and its session name.
+
+Configure the scenes it may run, and the sessions it starts with:
+
+```js
+// babylon-game-server.config.mjs
+export default {
+    dedicated: {
+        scenes: [
+            { name: "arena", sceneRoot: "/app/scenes/arena/", sceneFile: "arena.gltf", projectScripts: [], maxPlayers: 8, onDemand: true, idleSeconds: 60 }
+        ],
+        boot: [
+            { sessionName: "arena-1", sceneName: "arena" }
+        ]
+    }
+};
+```
+
+- `sceneRoot` is an `http(s)://` URL or a folder on the server (mount the exported scene into the container). Only the
+  configured `sceneRoot` and `projectScripts` locations are ever loaded.
+- The scene's own project script bundle loads automatically. `projectScripts` names extra bundles to load first.
+- **At boot:** each `boot` entry starts with the server and never closes. On a host that numbers its processes (PM2,
+  with `NODE_APP_INSTANCE`) it starts on one process, the holder of the `dedicated-boot` lease in Redis, and moves to a
+  new process during a rolling deploy once the old session ends.
+- **Through the admin API:** `POST /game-server/admin/dedicated` with `{ sceneName, sessionName }`.
+- **On demand:** a `Client`-mode join whose session property `dedicatedScene` names a scene with `onDemand: true`
+  starts a dedicated session of it (one, however many players join at once). The sample launcher sends it from
+  `?fusionDedicatedScene=`; in code, `startGame({ gameMode: GameMode.Client, sessionName, sessionProperties: { dedicatedScene: "arena" } })`.
+  Once every player has left, the session closes after the reconnect grace period plus `idleSeconds`.
+- At most `limits.maxDedicatedSessions` run at once.
+
+The game's script bundle must register its input struct with `TOOLKIT.NetworkRunner.setDefaultInputDefinition(...)`,
+because no launcher starts the dedicated runner. A launcher in the scene adopts the running session's runner instead of
+starting its own, and guards presentation code (DOM, GUI, audio, input) with `runner.isPlayer`.
+
+The single-session flags from earlier versions still work, and become one scene named after the session plus one boot
+entry:
+
+```sh
+babylon-game-server --dedicated srv1 --scene-root http://localhost:8877/scenes/ --scene networktestbed.gltf --players 8
+```
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--dedicated <sessionName>` | Starts a dedicated session clients join by this name. | none |
+| `--scene-root <url>` | The folder URL or path the exported scene is served from. | `http://localhost:8877/scenes/` |
+| `--scene <file>` | The exported scene file. Required with `--dedicated`. | none |
+| `--project-script <url>` | An extra script bundle to load before the scene. Repeatable. | none |
+| `--players <n>` | The most players the session accepts. | `8` |
+
+## Deploying
+
+`babylon-game-server init` writes the deployment starter folder: a commented `babylon-game-server.config.mjs` (every
+setting at its default), `.env.example` (every environment variable), a `Dockerfile` built on the published image, and
+recipes for Docker Compose (WebSocket behind Caddy; or TLS + UDP + Redis), AWS (ECS Fargate behind an ALB for WebSocket,
+or behind an NLB with `TCP_QUIC` for UDP), Fly.io, Railway, Render, DigitalOcean App Platform, Heroku, Colyseus Cloud
+and Kubernetes. Its `DEPLOY.md` has the production checklist and each platform's steps.
+
+**Colyseus Cloud is the recommended host.** The server is built on Colyseus 0.18, and Colyseus Cloud is Colyseus's own
+hosting, at a fixed monthly price. Its recipe (`colyseus-cloud/`) is a small deploy repository that installs the
+published package: TLS at the edge, WebSocket only, one process per CPU sharing Redis, rolling deploys in which
+running sessions finish and new ones go to the new processes. The server picks its Cloud settings by itself, refuses
+`GAME_SERVER_TLS_ENABLED`, `GAME_SERVER_UDP_ENABLED` and `GAME_SERVER_PUBLIC_ADDRESS` there, and drains for 600 s, so a
+process holding a `boot` session holds each deploy that long. See
+[DEPLOY.md](DEPLOY.md#411-colyseus-cloud).
+
+The production checklist in short: set `NODE_ENV=production` (the image does), terminate TLS at the platform or on the
+server, turn on auth, set `allowedOrigins`, set an admin token if you use the legacy admin endpoints, serve the
+admin console over HTTPS with its data on a volume or Redis, `admin.allowedNetworks` and a first Owner, health-check
+`/game-server/health` and route traffic on `/game-server/ready`, give the stop timeout more than `drainSeconds`, and
+size the instance for its dedicated sessions (each runs a full scene simulation).
+
+The Docker image `ghcr.io/mackeyk24/babylon-game-server` is built for `linux/amd64` and `linux/arm64`, runs as the
+`node` user with `NODE_ENV=production`, exposes `2567/tcp` and `2567/udp`, keeps the admin console's data in the
+`/data` volume (`GAME_SERVER_ADMIN_DATA_DIR=/data`), and reads its settings from `GAME_SERVER_*` variables or a mounted
+config file (`GAME_SERVER_CONFIG=/config/babylon-game-server.config.json`).
+
+## Upgrading and protocol versions
+
+The server and the game's Babylon Toolkit runtime share a **network protocol version** (`TOOLKIT.NETWORK_PROTOCOL_VERSION`),
+separate from package versions. Patch and minor releases that keep it can be mixed freely. A release that changes it
+says so in its notes; then update the server and the game together. A game on another protocol version is refused at
+matchmaking with `IncompatibleConfiguration`, naming both versions and which side to update, and the game also checks
+`/game-server/info` before it joins.
+
+The package version follows the Babylon Toolkit runtime it ships with (`babylonjs-toolkit`). To upgrade, change the
+version you install (`npm install @babylonjs-toolkit/server@<version>`) or the image tag, and redeploy. Running
+sessions finish on the old instance while it drains.
+
+## Troubleshooting
+
+Refusals reach the game as a failed `startGame` (`result.shutdownReason`) with the message
+`"<ShutdownReason>: <detail>"`, and are logged by the server as `join refused` with the same reason.
+
+| Message | What to do |
+|---|---|
+| `InvalidAuthentication: no token was sent` | Auth is on and the game sent no token: pass `startGame({ authToken })` (`?fusionToken=` in the sample). |
+| `InvalidAuthentication: the token is not valid` | Shared secret: the token is not in `auth.sharedSecret.tokens`. Check for whitespace or a stale token. |
+| `InvalidAuthentication: the token is not valid (<code>)` | JWT: the signature, issuer, audience, algorithm or format is wrong (the code is jose's, for example `ERR_JWT_CLAIM_VALIDATION_FAILED` for a wrong `iss`/`aud`, `ERR_JWS_SIGNATURE_VERIFICATION_FAILED` for the wrong key). Compare the token's claims with `auth.jwt.*`. |
+| `AuthenticationTicketExpired: the token has expired` | JWT: get a fresh token from the identity provider and start again. |
+| `InvalidAuthentication: the identity provider's keys could not be loaded` | JWT: the server cannot fetch `auth.jwt.jwksUrl`. Check the URL and the server's outbound network. |
+| `CustomAuthenticationFailed: the auth webhook did not approve the player` | Webhook: it answered non-2xx, not a JSON object, or later than `auth.webhook.timeoutMs`. Check the webhook's logs. |
+| `CustomAuthenticationFailed: the custom verifier did not approve the player` | Custom: your `verifyToken` hook returned `null`. |
+| `CustomAuthenticationFailed: the token could not be verified` | The verifier itself threw an error; the server logs it as `token verifier failed`. Fix the hook or webhook code. |
+| `IncompatibleConfiguration: this server speaks network protocol <n> but the game sent <m>; update the …` | The server and the game's runtime differ in protocol version (see [Upgrading](#upgrading-and-protocol-versions)); update the side the message names. The game reports the same as `IncompatibleConfiguration: the game server speaks network protocol …` when it reads `/game-server/info`. |
+| `IncompatibleConfiguration` (no detail) | Peers have different prefab tables: re-export, then reload every page and restart dedicated sessions. |
+| `ConnectionRefused: the origin <origin> is not allowed` | Add the game's origin (scheme, host and port, no path) to `limits.allowedOrigins`. `(none)` means a native client sent no `Origin` while `allowMissingOrigin` is off. |
+| `ConnectionRefused: too many join requests from this address; try again in a minute` | Over `joinRequestsPerMinutePerAddress`. Behind a proxy where every player shares one address, set `trustProxy`; otherwise raise the limit or fix a retry loop. |
+| `ConnectionRefused: the game server does not offer WebTransport, or this browser cannot reach it` | The game asked for `transportPreference: WebTransport` and UDP is off, the browser has no WebTransport, or UDP is blocked. Use `Auto`. |
+| `InvalidArguments: session name is longer than <n> characters` / `… contains control characters` | Shorten the session name or remove control characters, or raise `maxSessionNameLength`. |
+| `GameNotFound: no on-demand dedicated scene named <name>` | The join's `dedicatedScene` is not in `dedicated.scenes`, or that scene has `onDemand: false`. |
+| `GameNotFound: the dedicated scene <name> failed to load` | The server could not load the scene; its log says why (a wrong `sceneRoot`, a missing file, a script error). |
+| `GameNotFound` (no detail) | A `Client` join found no session of that name: start the host or dedicated session first. |
+| `GameClosed: the server is shutting down` | The instance is draining; join again to reach another instance. |
+| `MaxCcuReached: this server is hosting its most sessions` | Over `limits.maxSessions`: add instances (Redis) or raise the limit. |
+| `MaxCcuReached: this server is running its most dedicated sessions` | Over `limits.maxDedicatedSessions`. |
+| `GameIsFull` | The session has its most players (`playerCount`, at most `maxPlayersPerSession`). |
+| `Colyseus client not loaded …` | The page does not load the Colyseus browser client: turn on the exporter's Babylon Toolkit Networking option, or set `ColyseusTransport.ClientModule` (ESM). |
+
+Startup problems:
+
+| Message | What to do |
+|---|---|
+| `Babylon Game Server configuration problems:` followed by a list | Each line names the option, where it came from and what it needs, for example `tls.enabled (GAME_SERVER_TLS_ENABLED) needs a certificate: …`, `udp.enabled (GAME_SERVER_UDP_ENABLED) needs tls.enabled (GAME_SERVER_TLS_ENABLED): …`, or `auth.mode (GAME_SERVER_AUTH_MODE) jwt needs auth.jwt.secret (…) or auth.jwt.jwksUrl (…)`. Fix them and start again (exit code 2). |
+| `auth.mode "custom" needs a verifyToken hook (createGameServer({ hooks: { verifyToken } }))` | Custom auth works only from code; pass the hook, or pick another mode. |
+| `install mkcert (brew install mkcert && mkcert -install) or set tls.certFile/keyFile` | `--tls-dev-cert` needs mkcert when UDP is off. |
+| `UDP needs @colyseus/h3-transport, which is not installed on this platform` | The optional native package did not build here. Reinstall where its native build succeeds, or run without `--udp`. |
+| `babylonjs-toolkit <version> is older than this server needs; …` | The installed runtime predates the protocol version: install the `babylonjs-toolkit` version this server was released with. |
+| `a Babylon Game Server is already running in this process` | Call `createGameServer` once per process. |
+| `auth is disabled and the server listens on 0.0.0.0: anyone who can reach it can join …` (a warning) | A production server is open to anyone; turn on auth, or bind a loopback address. |
+| `HTTP/3 uses the new certificate after a restart` (a warning) | The certificate files were renewed while UDP is on; restart when convenient. |
+
+Logs are one readable line per entry prefixed `[GameServer]`, or JSON lines in production (`logFormat: "auto"`), with
+`sessionName`, `roomId`, `playerId`, `userId` and `clientAddress` when known. Tokens, secrets and keys are never logged.
+Set `GAME_SERVER_LOG_LEVEL=debug` for more.
+
+## Developing this package
+
+In the Babylon Toolkit repository the server lives in `SVR/` and depends on the runtime bundle in `../UMD`
+(`file:../UMD`, replaced by the exact published version when the package is packed):
+
+```sh
+cd APP && npm run build-ts && npm run combine-umd && npm run build-umd   # the runtime bundle the server loads
+cd ../SVR && npm install && npm run build && npm start -- --port 2567   # build: the server and the console app
+npm test   # builds, then runs the server test suites with real @colyseus/sdk clients
+```
+
+The room names (`fusion_session`, `fusion_lobby`) and messages (`fusion:*`) are the wire protocol the runtime speaks and
+keep their names.