Skip to main content

Creating a Game

A game is the top-level resource in GameFlow. It holds your server configuration, builds, regions, and fleet settings.

Creating a game in the dashboard is a three-step flow: configure, install the SDK, and upload your server build.

Step 1: Configure the game​

From Home / Games, click Create Game and fill in the game form.

Basic info​

  • Title, display name for your game.
  • Description, short description shown in the dashboard.
  • Cover image, optional. Uploaded to GameFlow's CDN; you can change it later from game settings.
  • Tags, free-form tags for filtering and grouping.

Engine​

  • Game engine, Unity, Unreal, Godot, Colyseus, or Custom.
  • Engine version, the version your server is built against.

Networking​

  • Primary port + protocol, the port your server listens on. Supported protocols:
    • TCP, reliable, ordered transport.
    • UDP, low-latency, connectionless transport. Common for realtime games.
    • TLS, TCP wrapped in TLS termination for clients that require a secure connection, such as web browsers (WSS, HTTPS).
  • Additional ports, optional named ports for extra protocols (e.g. a separate query port).

Resources​

  • vCPU, defaults to 500m.
  • Memory, defaults to 512Mi.

Regions​

Pick one or more regions where servers should run. See Regions and Best Region.

Scaling strategy​

Choose how servers are provisioned:

  • On-demand (standalone), a fresh server starts each time you allocate.
  • Fleet, a warm pool of servers sized by buffer, minReplicas, and maxReplicas. Allocations are served from the pool.

For fleets you also choose a rollout strategy (RollingUpdate or Recreate) with maxSurge and maxUnavailable knobs.

Environment variables & launch options​

  • Environment variables, key/value pairs passed to your container.
  • Launch options, extra arguments appended to your server's command.

See Environment Variables.

Step 2: Install the Agones SDK​

Your server must integrate the Agones SDK so GameFlow can manage its lifecycle. At minimum, your server needs to call:

  • Ready(), once the server can accept players.
  • Health(), periodic ping so GameFlow knows the server is alive.
  • Shutdown(), when the game session ends.

The dashboard surfaces snippets for each supported engine and language:

Engines​

  • Unity, add com.googleforgames.agones to Packages/manifest.json, attach AgonesSdk to a GameObject, call Connect() then Ready().
  • Unreal, drop the Agones plugin into Plugins/, enable it in your .uproject, add the Agones dependency to your module's Build.cs, then use UAgonesSubsystem.
  • Godot, extract agones-sdk.zip into addons/agones/, enable the plugin, call AgonesSDK.start() and AgonesSDK.ready().
  • Colyseus, npm install @google-cloud/agones-sdk, connect before booting rooms, call shutdown() in onDispose.
  • REST API, for custom engines, POST to http://localhost:$AGONES_SDK_HTTP_PORT/ready, /health, /shutdown, /allocate, /reserve.

Other languages​

  • Go, go get agones.dev/agones/sdks/go, sdk.NewSDK(), s.Ready(), s.Health() on a ticker.
  • Rust, add the agones crate, agones::Sdk::new(...).await, sdk.ready().await.
  • Node.js, npm install @google-cloud/agones-sdk, agonesSDK.connect(), ready(), periodic health().

Step 3: Upload your server build​

Final step: upload a packaged build of your server. GameFlow builds it into a container image and stores it as the game's first build.

Accepted formats​

Compressed archives only, max 2GB:

  • .zip
  • .tar
  • .tar.gz
  • .gz
  • .pck

The archive must contain a Dockerfile at the root.

Upload methods​

Drag & drop the archive onto the upload zone in the dashboard, or browse to pick a file. Upload starts immediately.

CLI, for larger builds or CI pipelines, use the GameFlow CLI:

curl -fsSL https://install.gameflow.gg | sh && \
  gameflow builds create --game-id=<GAME_ID> --version v1.0.0 --file server.zip

See GameFlow CLI.

What happens during upload​

  1. Upload, archive is streamed to object storage.
  2. Build, GameFlow spins up a build container, pulls base images, installs dependencies, compiles, and pushes to the image registry.
  3. Ready, the build appears on the game's Builds page and is promoted to current automatically (since it's the first one).

You can watch live build logs in the dashboard. If a build fails, fix the issue and retry without re-uploading the archive.

After a successful build​

You can immediately launch a test server in any of the game's configured regions, or head to the game's detail page to allocate servers via the API or dashboard.

Custom Engine​

Selecting Custom gives you full control over your server's container image. Unlike the managed engines (Unity, Unreal, Godot, Colyseus), GameFlow does not apply a built-in Dockerfile template, you bring your own.

When to use Custom​

  • Your server is built with an in-house or proprietary engine
  • You need a runtime not covered by managed engines (e.g. a C++ dedicated server, a Python simulation, a Rust game server)
  • You want to control the base image, OS dependencies, or build steps that the managed templates don't expose

Dockerfile requirements​

Your uploaded archive must contain a Dockerfile at the root (detected case-insensitively). GameFlow uses it verbatim, no template is layered on top.

A minimal example for a compiled Linux binary:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

RUN useradd -u 1000 -m gameuser
WORKDIR /opt/game
COPY . /opt/game
RUN chmod +x /opt/game/server
RUN chown -R gameuser:gameuser /opt/game
USER 1000

EXPOSE 7777/udp

ENTRYPOINT ["/opt/game/server"]

A few things to keep in mind:

  • Run as UID 1000. Agones enforces non-root execution at runtime.
  • Expose the right port. Match the port you configured in the Networking step.
  • Keep the image lean. Larger images slow down cold starts and fleet rollouts.

Agones SDK integration​

Custom engines integrate via the Agones REST API, served locally on your server instance at localhost:$AGONES_SDK_HTTP_PORT.

Your server must call three endpoints at minimum:

EndpointWhen to call
POST /readyOnce your server can accept player connections
POST /healthPeriodically (every 2–5 s) to signal liveness
POST /shutdownWhen the game session ends and the server should terminate

All request bodies are empty JSON objects ({}):

# Mark ready
curl -d "{}" -H "Content-Type: application/json" \
  -X POST http://localhost:$AGONES_SDK_HTTP_PORT/ready

# Health ping, run on a timer inside your server
curl -d "{}" -H "Content-Type: application/json" \
  -X POST http://localhost:$AGONES_SDK_HTTP_PORT/health

# Shutdown
curl -d "{}" -H "Content-Type: application/json" \
  -X POST http://localhost:$AGONES_SDK_HTTP_PORT/shutdown

Two additional endpoints are available for allocation control:

EndpointDescription
POST /allocateSelf-allocate the server (mark it as in-use)
POST /reserveReserve the server for N seconds without a full allocation

If your server is written in Go, Rust, or Node.js, you can use the official Agones SDK for that language instead of raw HTTP, see Step 2 for the snippets.