@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/templates/init/aws/ecs-fargate-nlb-quic.yml

@@ -0,0 +1,210 @@
+# TLS: server (the game server terminates TLS with a PEM certificate from Secrets Manager; the NLB passes QUIC through)
+# UDP: supported (a Network Load Balancer TCP_QUIC listener carries WSS over TCP and HTTP/3 over UDP on 443)
+# Auth: set GAME_SERVER_AUTH_* to enable (add them to the container Environment below, secrets through Secrets Manager)
+#
+# Babylon Game Server {{version}} on ECS Fargate behind a Network Load Balancer with a TCP_QUIC listener, so browsers
+# can use WebTransport datagrams. Players connect with wss://<your domain>, which you point at the
+# LoadBalancerDnsName output; the certificate in TlsSecretArn must cover that domain.
+# TlsSecretArn is a Secrets Manager secret whose JSON has two keys, certPem (the full chain) and keyPem (the key):
+#   aws secretsmanager create-secret --name babylon-game-server-tls \
+#     --secret-string "$(jq -n --rawfile certPem fullchain.pem --rawfile keyPem privkey.pem '{certPem: $certPem, keyPem: $keyPem}')"
+# Long-form intrinsics only (Ref: / Fn::GetAtt:), so any YAML parser can check the template.
+# QUIC listeners do not accept security groups on the NLB, so the task security group admits 2567 TCP + UDP.
+# Check the current Elastic Load Balancing QUIC requirements for your region before production (see aws/README.md).
+AWSTemplateFormatVersion: "2010-09-09"
+Description: Babylon Game Server {{version}} on ECS Fargate behind a Network Load Balancer TCP_QUIC listener (WSS + HTTP/3, TLS on the server)
+
+Parameters:
+  VpcId:
+    Type: AWS::EC2::VPC::Id
+    Description: The VPC the load balancer and the tasks run in.
+  SubnetIds:
+    Type: List<AWS::EC2::Subnet::Id>
+    Description: Two or more public subnets in different availability zones.
+  CertificateArn:
+    Type: String
+    Default: ""
+    Description: Not used by this template (the server terminates TLS from TlsSecretArn); kept so both AWS recipes take the same parameters.
+  TlsSecretArn:
+    Type: String
+    Description: ARN of the Secrets Manager secret with the certPem and keyPem keys.
+  Image:
+    Type: String
+    Default: ghcr.io/mackeyk24/babylon-game-server:{{version}}
+    Description: The server image (or your own image built from the init Dockerfile).
+  DesiredCount:
+    Type: Number
+    Default: 1
+    Description: Number of server tasks.
+
+Resources:
+  Cluster:
+    Type: AWS::ECS::Cluster
+
+  LogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      RetentionInDays: 14
+
+  TaskExecutionRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: ecs-tasks.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
+      Policies:
+        - PolicyName: read-tls-secret
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: secretsmanager:GetSecretValue
+                Resource:
+                  Ref: TlsSecretArn
+
+  TaskDefinition:
+    Type: AWS::ECS::TaskDefinition
+    Properties:
+      Family: babylon-game-server-quic
+      RequiresCompatibilities:
+        - FARGATE
+      NetworkMode: awsvpc
+      Cpu: "512"
+      Memory: "1024"
+      ExecutionRoleArn:
+        Fn::GetAtt: [TaskExecutionRole, Arn]
+      ContainerDefinitions:
+        - Name: game-server
+          Image:
+            Ref: Image
+          Essential: true
+          # Longer than the 30 s drain, so running sessions finish before the task is stopped.
+          StopTimeout: 45
+          PortMappings:
+            - ContainerPort: 2567
+              Protocol: tcp
+            - ContainerPort: 2567
+              Protocol: udp
+          Environment:
+            - Name: GAME_SERVER_LOG_FORMAT
+              Value: json
+            # Admin console data (accounts, bans, audit log). Fargate task storage is lost when the task stops: add
+            # GAME_SERVER_REDIS_URL (ElastiCache, see aws/README.md) so the console keeps its data in Redis.
+            - Name: GAME_SERVER_ADMIN_DATA_DIR
+              Value: /data
+            - Name: GAME_SERVER_TLS_ENABLED
+              Value: "true"
+            - Name: GAME_SERVER_UDP_ENABLED
+              Value: "true"
+          Secrets:
+            - Name: GAME_SERVER_TLS_CERT_PEM
+              ValueFrom:
+                Fn::Join:
+                  - ""
+                  - - Ref: TlsSecretArn
+                    - ":certPem::"
+            - Name: GAME_SERVER_TLS_KEY_PEM
+              ValueFrom:
+                Fn::Join:
+                  - ""
+                  - - Ref: TlsSecretArn
+                    - ":keyPem::"
+          LogConfiguration:
+            LogDriver: awslogs
+            Options:
+              awslogs-group:
+                Ref: LogGroup
+              awslogs-region:
+                Ref: AWS::Region
+              awslogs-stream-prefix: game-server
+
+  ServiceSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: Babylon Game Server tasks (2567 TCP + UDP; the NLB keeps the player's address)
+      VpcId:
+        Ref: VpcId
+      SecurityGroupIngress:
+        - IpProtocol: tcp
+          FromPort: 2567
+          ToPort: 2567
+          CidrIp: 0.0.0.0/0
+        - IpProtocol: udp
+          FromPort: 2567
+          ToPort: 2567
+          CidrIp: 0.0.0.0/0
+
+  LoadBalancer:
+    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
+    Properties:
+      Type: network
+      Scheme: internet-facing
+      Subnets:
+        Ref: SubnetIds
+
+  TargetGroup:
+    Type: AWS::ElasticLoadBalancingV2::TargetGroup
+    Properties:
+      VpcId:
+        Ref: VpcId
+      Protocol: TCP_QUIC
+      Port: 2567
+      TargetType: ip
+      HealthCheckProtocol: HTTPS
+      HealthCheckPath: /game-server/ready
+      HealthCheckIntervalSeconds: 15
+      HealthyThresholdCount: 2
+      UnhealthyThresholdCount: 3
+      TargetGroupAttributes:
+        - Key: deregistration_delay.timeout_seconds
+          Value: "45"
+
+  QuicListener:
+    Type: AWS::ElasticLoadBalancingV2::Listener
+    Properties:
+      LoadBalancerArn:
+        Ref: LoadBalancer
+      Port: 443
+      Protocol: TCP_QUIC
+      DefaultActions:
+        - Type: forward
+          TargetGroupArn:
+            Ref: TargetGroup
+
+  Service:
+    Type: AWS::ECS::Service
+    DependsOn: QuicListener
+    Properties:
+      Cluster:
+        Ref: Cluster
+      LaunchType: FARGATE
+      DesiredCount:
+        Ref: DesiredCount
+      TaskDefinition:
+        Ref: TaskDefinition
+      HealthCheckGracePeriodSeconds: 30
+      NetworkConfiguration:
+        AwsvpcConfiguration:
+          # A public IP lets the task pull the image from ghcr.io without a NAT gateway.
+          AssignPublicIp: ENABLED
+          Subnets:
+            Ref: SubnetIds
+          SecurityGroups:
+            - Ref: ServiceSecurityGroup
+      LoadBalancers:
+        - ContainerName: game-server
+          ContainerPort: 2567
+          TargetGroupArn:
+            Ref: TargetGroup
+
+Outputs:
+  LoadBalancerDnsName:
+    Description: Point your game server domain (CNAME or Route 53 alias) here.
+    Value:
+      Fn::GetAtt: [LoadBalancer, DNSName]

package/templates/init/babylon-game-server.config.mjs

@@ -0,0 +1,158 @@
+// Babylon Game Server {{version}} configuration.
+//
+// Every setting is shown at its default. Precedence: defaults < this file < GAME_SERVER_* environment variables <
+// command-line flags, so a platform can override any value here with an environment variable (see .env.example).
+// The server finds this file through --config <path>, GAME_SERVER_CONFIG, or babylon-game-server.config.mjs in the
+// working directory. The default export may also be a function (async allowed) that returns this object.
+//
+// TLS, UDP and auth are all disabled. Each section below says how to turn it on and what it needs.
+
+/** @type {import("@babylonjs-toolkit/server").DeepPartial<import("@babylonjs-toolkit/server").GameServerConfig>} */
+export default {
+    // TCP (and UDP) port. Platforms that set PORT are honoured when GAME_SERVER_PORT is unset.
+    port: 2567,
+    // Address to bind. "0.0.0.0" accepts connections from other machines (containers need it).
+    host: "0.0.0.0",
+    // Public ws:// or wss:// URL players use, shown in the banner (null: derived from host, port and TLS).
+    publicUrl: null,
+    // host[:port] this instance advertises for seat reservations when scaled out with Redis (one per instance).
+    publicAddress: null,
+    // Trust x-forwarded-for / x-real-ip for the client address. Turn on only behind your own reverse proxy.
+    trustProxy: false,
+    // "auto" (JSON when NODE_ENV=production), "json" or "text".
+    logFormat: "auto",
+    // "error", "warn", "info" or "debug".
+    logLevel: "info",
+
+    // TLS on the server itself (https:// and wss://). Leave it off when a proxy or the platform edge terminates TLS.
+    // To enable it, set enabled: true and give it a certificate, one of:
+    //   - certFile + keyFile: paths of PEM files (for example from certbot); they are reloaded when they change.
+    //   - certPem + keyPem: the PEM text itself, for container secrets (GAME_SERVER_TLS_CERT_PEM / _KEY_PEM).
+    //   - developmentCertificate: true for local testing only (needs mkcert; refused when NODE_ENV=production).
+    tls: {
+        enabled: false,
+        certFile: null,
+        keyFile: null,
+        certPem: null,
+        keyPem: null,
+        developmentCertificate: false
+    },
+
+    // HTTP/3 WebTransport (UDP datagrams for snapshots and inputs) on the same port as the WebSocket.
+    // To enable it, set enabled: true. It needs:
+    //   - TLS enabled on the server (above): browsers only speak HTTP/3 over TLS.
+    //   - The port open for UDP as well as TCP (firewall, security group, `-p 443:443/udp`).
+    //   - A host that forwards inbound UDP to the server; most PaaS hosts do not (see DEPLOY.md).
+    // Players whose browser or network cannot use it fall back to the WebSocket automatically.
+    udp: {
+        enabled: false
+    },
+
+    // Player authentication: every join must carry a valid token (the game sets StartGameArgs.authToken).
+    // To enable it, set enabled: true and pick a mode with its fields:
+    //   - "shared-secret": sharedSecret.tokens lists the accepted tokens.
+    //   - "jwt": jwt.secret (HMAC) or jwt.jwksUrl (your identity provider), plus optional issuer / audience / algorithms.
+    //   - "webhook": webhook.url approves each player (POST), within webhook.timeoutMs.
+    //   - "custom": your own verifier, the hooks.verifyToken of createGameServer({ hooks }) when you start it from code.
+    auth: {
+        enabled: false,
+        mode: "shared-secret",
+        sharedSecret: { tokens: [] },
+        jwt: { secret: null, jwksUrl: null, issuer: null, audience: null, algorithms: [] },
+        webhook: { url: null, timeoutMs: 5000 }
+    },
+
+    // Discord sign-in for players: off by default. Set the client secret on your host's environment (GAME_SERVER_DISCORD_CLIENT_SECRET), never in this file.
+    // To enable it, create a Discord application, add this server's callback under OAuth2 -> Redirects, and set:
+    //   - clientId: the application's client id.
+    //   - redirectUri: "https://<your server>/game-server/discord/callback", exactly as registered with Discord.
+    //   - returnOrigins: the game origins a sign-in may return to, e.g. ["https://game.example.com"].
+    // discordSignIn: {
+    //     enabled: false,
+    //     clientId: null,
+    //     clientSecret: null,
+    //     redirectUri: null,
+    //     returnOrigins: [],
+    //     sessionDays: 30
+    // },
+
+    // Admin console at /game-server/admin/ and the admin API. The first start logs a one-time "admin setup link" for the
+    // first Owner (or run `babylon-game-server admin create-owner`). The console needs HTTPS (or a loopback address).
+    // token: the legacy bearer token of the four original admin endpoints; prefer GAME_SERVER_ADMIN_TOKEN.
+    // dataDir: accounts, bans and the audit log when redis.url is not set; keep it on a volume (the image uses /data).
+    // allowedNetworks: addresses or CIDR ranges that may reach the console, e.g. ["10.0.0.0/8"] (empty: any).
+    admin: {
+        token: null,
+        console: true,
+        dataDir: "./babylon-game-server-data",
+        sessionIdleMinutes: 30,
+        sessionMaxHours: 12,
+        allowedNetworks: [],
+        logBufferEntries: 10000,
+        metricsHistoryHours: 24,
+        grafanaUrl: null,
+        instanceLabel: null,
+        // Single sign-on (OpenID Connect). roleMapping: ["admins=admin", "support=moderator"].
+        oidc: {
+            enabled: false,
+            issuer: null,
+            clientId: null,
+            clientSecret: null,
+            label: "Single sign-on",
+            roleClaim: "groups",
+            roleMapping: [],
+            allowLocalSignIn: true
+        },
+        passkeys: {
+            enabled: true,
+            rpId: null
+        },
+        // The console's Colyseus Cloud page. Set the token on your host's environment
+        // (GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_TOKEN), never in this file.
+        colyseusCloud: {
+            apiToken: null,
+            application: null,
+            apiUrl: "https://cloud-prod.colyseus.io/api/v1"
+        }
+    },
+
+    // Prometheus metrics on GET /metrics.
+    metrics: {
+        enabled: true,
+        requireAdminToken: false
+    },
+
+    // Abuse limits. Set allowedOrigins to your game's origins in production, e.g. ["https://game.example.com"].
+    limits: {
+        allowedOrigins: [],
+        allowMissingOrigin: true,
+        joinRequestsPerMinutePerAddress: 120,
+        maxSessions: 1000,
+        maxPlayersPerSession: 255,
+        maxDedicatedSessions: 4,
+        maxMessageBytes: 65536,
+        maxMessagesPerSecond: 2000,
+        maxSessionNameLength: 128
+    },
+
+    // Multi-instance scaling: every instance shares one Redis (redis://host:6379) and sets its own publicAddress.
+    redis: {
+        url: null
+    },
+
+    // Dedicated (Server-mode) sessions that run the exported scene on the server.
+    //   scenes: [{ name: "arena", sceneRoot: "/app/scenes/arena/", sceneFile: "arena.gltf", projectScripts: [],
+    //              maxPlayers: 8, onDemand: true, idleSeconds: 60 }]
+    //   boot:   [{ sessionName: "arena-1", sceneName: "arena" }]
+    dedicated: {
+        scenes: [],
+        boot: []
+    },
+
+    // JSON file of leaderboard boards created on start when missing (relative to the working directory), and whether
+    // only signed-in players (an auth identity with a user id) may submit scores.
+    leaderboards: { definitionsFile: null, signedInPlayersOnly: false },
+
+    // Seconds running sessions may continue after SIGTERM before the server exits.
+    drainSeconds: 30
+};

package/templates/init/colyseus-cloud/README.md

@@ -0,0 +1,133 @@
+# Babylon Game Server on Colyseus Cloud
+
+This folder is a small deploy repository. It installs the published `@babylonjs-toolkit/server` package {{version}} and
+tells Colyseus Cloud how to run it. There is no server code to write or build here.
+
+| File | What it does |
+|---|---|
+| `package.json` | Pins the server version. |
+| `ecosystem.config.cjs` | Tells Colyseus Cloud what to start: one server process per CPU. |
+| `babylon-game-server.config.mjs` | Your server settings. It starts empty. |
+| `.gitignore` | Keeps `node_modules/`, environment files and your deploy credentials out of the repository. |
+
+Colyseus Cloud serves `wss://` for you, and TLS, UDP (HTTP/3 WebTransport) and player authentication are off until you
+choose otherwise. On this host UDP cannot reach the server, so players use the WebSocket.
+
+## Before you start
+
+- You need a Colyseus Cloud account with an application created for this server.
+- Check that the application runs Node 22 or newer, which the server requires.
+
+## 1. Push this folder to git
+
+Colyseus Cloud deploys only from git: it clones the branch, runs `npm install` and the `build` script, then starts the
+server. Push this folder as a repository of its own, as below, or keep it as a subfolder of an existing repository
+(your game's, for example) and set the application's **Root directory** to that subfolder on the panel. With a
+subfolder, set the panel's watch paths to it as well, so only changes here deploy.
+
+```bash
+npm install
+git init
+git add .
+git commit -m "Babylon Game Server on Colyseus Cloud"
+git branch -M main
+git remote add origin <your repository URL>
+git push -u origin main
+```
+
+Keep the `package-lock.json` that `npm install` wrote, so every deploy installs the same packages.
+
+## 2. Connect it to Colyseus Cloud
+
+Pick one of these two ways:
+
+- **From the panel:** connect the repository to your application in the Colyseus Cloud panel. Each push to the branch
+  you choose then deploys.
+- **From this folder:** run `npx @colyseus/cloud deploy`. It writes `.colyseus-cloud.json`, which holds your deploy
+  credentials. The `.gitignore` here already keeps that file out of the repository. Do not commit it. The command only
+  asks Colyseus Cloud to deploy the branch you already pushed, and it returns before the deploy finishes, even when
+  it fails. Read the result on the panel's deployments page.
+
+## 3. Set the panel variables
+
+Add these to your application's environment variables on the Colyseus Cloud panel, then deploy again:
+
+| Variable | Value |
+|---|---|
+| `NODE_ENV` | `production` |
+| `GAME_SERVER_ALLOWED_ORIGINS` | The web address of your game, such as `https://game.example.com`. Separate several with commas. |
+| `GAME_SERVER_ADMIN_TOKEN` | A long random secret. It turns on the admin endpoints. |
+
+Every `GAME_SERVER_*` variable works here. The `.env.example` that `babylon-game-server init` wrote beside this folder
+lists them all. To require player sign-in, set the `GAME_SERVER_AUTH_*` variables.
+
+Leave `GAME_SERVER_TLS_ENABLED`, `GAME_SERVER_UDP_ENABLED` and `GAME_SERVER_PUBLIC_ADDRESS` unset. Colyseus Cloud
+handles all three, so the server refuses to start with any of them turned on and says which one to change.
+
+Optional: to see this application's status, host processes, deploys, host logs and billing on the admin console's **Colyseus Cloud**
+page, create a token under **API tokens** in the Colyseus Cloud dashboard and set `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_TOKEN`
+to it. If your team has several applications, also set `GAME_SERVER_ADMIN_COLYSEUS_CLOUD_APPLICATION` to this one's slug.
+
+## 4. Point your game at the server
+
+Open the application's logs on the panel. The startup banner shows the server's `wss://` address. Put that address in
+your game's build settings, then rebuild the game:
+
+```bash
+VITE_FUSION_SERVER_URL=wss://<your-application-address>
+```
+
+Start two players from two browsers and join the same session to confirm it works.
+
+## The admin console
+
+The server has a web console at `/game-server/admin/` on your application's address. To create its first Owner, open the
+`admin setup link` line from the application's logs within 30 minutes of the deploy. Each process logs its own link and
+any one of them works; the first Owner ends them all. There is no shell on Colyseus Cloud, so this link is the way in.
+
+If the console answers `the console needs HTTPS`, Colyseus Cloud is not telling the server that the request was HTTPS.
+See the first deploy checklist in the server's `DEPLOY.md`.
+
+## Dedicated sessions
+
+A dedicated session runs your exported scene on the server. It needs no extra port or container, because it runs
+inside the same server processes.
+
+1. Open `babylon-game-server.config.mjs` and copy the `limits` and `dedicated` example into the exported object.
+2. Keep each scene either in this repository, with a `sceneRoot` such as `./scenes/arena/`, or at an `https://`
+   address.
+3. Set `limits.maxDedicatedSessions`, which is the number of dedicated sessions one process may run. It defaults to 4.
+   Run your scene, watch the memory one process uses, and choose a number that leaves room to spare. Colyseus Cloud
+   restarts a process that passes its memory limit, and that ends every session on the process. It sizes that limit
+   from the plan's memory: about 1.1 GB per process on plans with 2 GB per CPU, but only 256 MB on the smallest 1 GB
+   plan. `ecosystem.config.cjs` explains how to set the limit yourself.
+4. Commit and push.
+
+A session listed under `boot` starts once, on one process, however many processes are running. A larger plan
+with more CPUs runs more processes, which is how you add dedicated capacity.
+
+## Leaderboards
+
+The server ranks the scores your game sends at key stages (a match or level finish), with seasons, trust levels and a
+**Leaderboards** page on the admin console. They are on by default. To create your boards on deploy:
+
+1. Write a `leaderboards.json` definitions file in this folder (the format is in the server's README, "The definitions
+   file"). The server creates the boards that are missing at start and keeps the console's edits to existing ones.
+2. Open `babylon-game-server.config.mjs` and copy its `leaderboards: { definitionsFile: "./leaderboards.json", signedInPlayersOnly: true }`
+   line into the exported object (drop `signedInPlayersOnly` to let players who are not signed in post scores too).
+3. Commit both files and push.
+
+The scores live in the same place as the console's data. For production, set `REDIS_URI` on the panel to an external
+Redis that persists its data (a managed Redis with snapshots or an append-only file). Without it, the scores sit in the
+machine's local Redis or in files, which a deploy or restart may lose. The console's Leaderboards page warns when the
+storage is not durable, and its Settings tab exports a backup.
+
+## Deploying an update
+
+To move to a newer server, change the `@babylonjs-toolkit/server` version in `package.json`, run `npm install`, then
+commit and push. Running sessions get up to 10 minutes to finish before the old processes stop, so a race in progress
+is not cut off. New sessions go to the new processes only. To change that time, set `GAME_SERVER_DRAIN_SECONDS`
+(keep it under 30 minutes, the `kill_timeout` in `ecosystem.config.cjs`).
+
+A deploy whose new processes do not start listening within two minutes fails, and the old version keeps serving. The
+very first deploy is not checked that way, so read its logs for the startup banner.

package/templates/init/colyseus-cloud/babylon-game-server.config.mjs

@@ -0,0 +1,36 @@
+// Babylon Game Server {{version}} configuration for Colyseus Cloud.
+//
+// The server picks its Colyseus Cloud settings by itself (public URL, client address, Redis, drain time and admin
+// data folder), so this file starts empty. Anything set here, or as a GAME_SERVER_* variable on the Colyseus Cloud
+// panel, wins over those settings. The panel is the better place for secrets, because this file lives in the repository.
+//
+// TLS, UDP and publicAddress stay unset: Colyseus Cloud handles them, and the server refuses to start with them.
+//
+// Dedicated sessions run the exported scene on the server, and they are configured only in this file. The scene is
+// either in this repository or at an https:// address. This example shows both:
+//
+//   limits: {
+//       // Dedicated sessions one process runs. Size it by measuring your scene: see README.md.
+//       maxDedicatedSessions: 4
+//   },
+//   dedicated: {
+//       scenes: [
+//           // A scene exported into this repository, in the folder ./scenes/arena/
+//           { name: "arena", sceneRoot: "./scenes/arena/", sceneFile: "arena.gltf", projectScripts: [], maxPlayers: 8, onDemand: true, idleSeconds: 60 },
+//           // A scene hosted on your own storage
+//           { name: "harbor", sceneRoot: "https://assets.example.com/scenes/harbor/", sceneFile: "harbor.gltf", projectScripts: [], maxPlayers: 8, onDemand: true, idleSeconds: 60 }
+//       ],
+//       // Sessions started with the server. They start once, on one process.
+//       boot: [
+//           { sessionName: "arena-1", sceneName: "arena" }
+//       ]
+//   }
+//
+// Leaderboards are on by default. To create your boards from a definitions file committed beside this one, copy this
+// line into the exported object (see README.md, "Leaderboards"). signedInPlayersOnly: true accepts scores only from
+// signed-in players (an auth identity with a user id, such as Discord sign-in); drop it to let guests post too:
+//
+// leaderboards: { definitionsFile: "./leaderboards.json", signedInPlayersOnly: true },
+
+/** @type {import("@babylonjs-toolkit/server").DeepPartial<import("@babylonjs-toolkit/server").GameServerConfig>} */
+export default {};

package/templates/init/colyseus-cloud/ecosystem.config.cjs

@@ -0,0 +1,35 @@
+// TLS: edge (Colyseus Cloud serves wss:// through NGINX)
+// UDP: not supported on this host
+// Auth: set GAME_SERVER_AUTH_* to enable
+//
+// Babylon Game Server {{version}} on Colyseus Cloud. See README.md for the deploy steps.
+// One process runs on one thread, so one process per CPU gives every core to sessions. The processes share Redis,
+// which the server finds by itself on Colyseus Cloud.
+//
+// kill_timeout and listen_timeout are set here, not left to Colyseus Cloud's deploy agent, so they also hold on the
+// fallback path that runs PM2 with its own defaults (a 1.6 s kill timeout, which would cut a drain off). A stopping
+// process drains for GAME_SERVER_DRAIN_SECONDS (600 s on Colyseus Cloud) and then exits by itself.
+// max_memory_restart stays unset: Colyseus Cloud sizes it from the machine's memory. To set it yourself, add for
+// example max_memory_restart: "700M", and keep the total below the plan's memory, because a deploy briefly runs
+// half as many processes again and the machine has no swap.
+const os = require("node:os");
+
+/** Milliseconds a stopping process may drain before PM2 kills it: 30 minutes, Colyseus Cloud's own default. */
+const KILL_TIMEOUT_MS = 30 * 60 * 1000;
+/** Milliseconds a new process has to listen before the deploy counts it as failed (loading Havok and scenes). */
+const LISTEN_TIMEOUT_MS = 120 * 1000;
+
+module.exports = {
+    apps: [{
+        name: "babylon-game-server",
+        script: "node_modules/@babylonjs-toolkit/server/lib/cli.js",
+        args: "start",
+        exec_mode: "fork",
+        instances: os.cpus().length,
+        wait_ready: true,
+        kill_timeout: KILL_TIMEOUT_MS,
+        listen_timeout: LISTEN_TIMEOUT_MS,
+        watch: false,
+        time: true
+    }]
+};

package/templates/init/colyseus-cloud/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+# Written by `npx @colyseus/cloud deploy`. It holds deploy credentials.
+.colyseus-cloud.json
+.env*
+# The list of every GAME_SERVER_* variable, with no values: safe to commit.
+!.env.example

package/templates/init/colyseus-cloud/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "babylon-game-server-cloud",
+  "version": "1.0.0",
+  "description": "Deploy repository of a Babylon Game Server on Colyseus Cloud",
+  "private": true,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node -e \"console.log('The Babylon Game Server ships compiled, so there is nothing to build.')\""
+  },
+  "dependencies": {
+    "@babylonjs-toolkit/server": "{{version}}"
+  }
+}

package/templates/init/digitalocean-app.yaml

@@ -0,0 +1,30 @@
+# TLS: edge (App Platform terminates TLS for the app's ondigitalocean.app domain and your custom domains)
+# UDP: not supported on this host (App Platform routes inbound HTTP only: https://docs.digitalocean.com/products/app-platform/details/limits/)
+# Auth: set GAME_SERVER_AUTH_* to enable (add them under envs, secrets with type: SECRET)
+#
+# Babylon Game Server {{version}} on DigitalOcean App Platform, WebSocket only. Commit this folder to a GitHub
+# repository, set github.repo below, then:
+#   doctl apps create --spec digitalocean-app.yaml
+# Players use wss://<app>.ondigitalocean.app.
+name: babylon-game-server
+services:
+  - name: game-server
+    github:
+      repo: your-account/your-game-server
+      branch: main
+      deploy_on_push: true
+    source_dir: /
+    dockerfile_path: Dockerfile
+    http_port: 2567
+    instance_count: 1
+    instance_size_slug: apps-s-1vcpu-1gb
+    health_check:
+      http_path: /game-server/ready
+      initial_delay_seconds: 20
+      period_seconds: 15
+    envs:
+      - key: GAME_SERVER_PORT
+        value: "2567"
+      # App Platform's proxy sends the player's address in x-forwarded-for.
+      - key: GAME_SERVER_TRUST_PROXY
+        value: "true"

package/templates/init/docker-compose.full.yml

@@ -0,0 +1,45 @@
+# Babylon Game Server {{version}}, full setup: TLS on the server, WebSocket + HTTP/3 WebTransport on 443, and Redis.
+# TLS: server (certbot writes ./certs/fullchain.pem and ./certs/privkey.pem; they are reloaded when renewed)
+# UDP: supported (443/udp is published; the host and firewall must allow inbound UDP 443)
+# Auth: off until set; set GAME_SERVER_AUTH_* to enable
+#
+#   docker compose -f docker-compose.full.yml up -d
+# The server runs as user "node": make privkey.pem readable to it (for example copy the renewed files into ./certs
+# with mode 0644 from a certbot deploy hook). Players use wss://<your domain>; browsers that can use HTTP/3 switch to
+# WebTransport automatically.
+services:
+  game-server:
+    image: ${GAME_SERVER_IMAGE:-ghcr.io/mackeyk24/babylon-game-server:{{version}}}
+    restart: unless-stopped
+    depends_on:
+      - redis
+    environment:
+      GAME_SERVER_CONFIG: /app/config/babylon-game-server.config.mjs
+      GAME_SERVER_TLS_ENABLED: "true"
+      GAME_SERVER_TLS_CERT_FILE: /certs/fullchain.pem
+      GAME_SERVER_TLS_KEY_FILE: /certs/privkey.pem
+      GAME_SERVER_UDP_ENABLED: "true"
+      GAME_SERVER_PORT: "443"
+      # With Redis set, the admin console keeps its data (accounts, bans, audit log) in Redis; the /data volume holds
+      # it only if you remove GAME_SERVER_REDIS_URL.
+      GAME_SERVER_REDIS_URL: redis://redis:6379
+      GAME_SERVER_ADMIN_DATA_DIR: /data
+    ports:
+      - "443:443/tcp"
+      - "443:443/udp"
+    volumes:
+      - ./babylon-game-server.config.mjs:/app/config/babylon-game-server.config.mjs:ro
+      - ./certs:/certs:ro
+      - game-server-data:/data
+
+  redis:
+    image: redis:7
+    restart: unless-stopped
+    # Append-only persistence on the redis-data volume, so admin accounts, bans and the audit log survive a restart.
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+
+volumes:
+  game-server-data:
+  redis-data: