Agones to Gameye migration guide

Gameye pulls images from Docker Hub or GitHub Container Registry. Push the same Linux x86-64 server image you deploy to Agones, create a Gameye application for it, and give Gameye read access. Gameye does not host a registry, so you keep using your own.

Use a new tag for every build, such as a build number or commit SHA. Nodes that already have a tag do not download it again, so re-pushing latest will not deliver a new build.

Getting started in Gameye Docs →

On Agones, your server talks to the SDK server that runs alongside it in the Pod. Take those calls out:

• SDK.Ready(): remove. A Gameye session is running once POST /session returns.
• SDK.Health() ping loop: remove. Gameye does not expect health pings.
• SDK.Shutdown(): replace with a normal process exit. When the server process exits, the session ends and billing stops.
• SDK.Allocate(), if your server self-allocates: remove. Your backend starts the session instead.

Keep your SIGTERM handler. When your backend calls DELETE /session/{id} or a session's ttl runs out, Gameye sends SIGTERM, then SIGKILL if the process is still running 50 seconds later. Save results and logs in that window, then exit.

The engine guides show the shutdown path for each engine: Unreal, Unity and Godot.

The ports list in your GameServer spec becomes the ports on your Gameye application: a protocol and a container port, for example UDP 7777.

• Bridge networking (the default) is closest to the Agones Dynamic port policy. Your server listens on a fixed container port and Gameye maps it to a free host port.
• Host networking is closest to Passthrough. Your server reads its assigned port at startup from a variable such as GAMEYE_PORT_UDP_7777 and listens on it.

Gameye sets the port variables in both modes, along with GAMEYE_IP, GAMEYE_REGION and GAMEYE_CONTAINER, so a server that advertises its own address can still do so.

Container environment variables →

Wherever your backend or matchmaker creates a GameServerAllocation, it calls the Gameye API instead. The response carries the address and ports, like the allocation status does.

apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
spec:
  selectors:
    - matchLabels:
        agones.dev/fleet: my-fleet
# status: state Allocated, gameServerName, address, ports

POST /session
{ "image": "my-game-server", "version": "build-142",
  "location": "europe", "env": { "MAX_PLAYERS": "16" },
  "labels": { "match": "m-8812" }, "ttl": "1h" }

201 Created
{ "id": "...", "host": "203.0.113.42",
  "ports": [{ "type": "udp", "container": 7777, "host": 49152 }] }

Match settings you put in GameServer labels, annotations or container args carry over to labels, env and args. Do not put secrets in env: the values are visible to anyone with Admin Panel access.

POST /session reference → · Custom matchmaker guide →

Instead of one cluster per region, you choose a region on each request. For a single-region game, pass a fixed location. For a global game, call GET /available-location/{image} to get the regions where your image is available and an IP for each, have clients ping those IPs, and start the session in the region with the best result for the match.

Region selection guide →

If you count connected players, report them from your backend with PUT /session/player/join and DELETE /session/player/leave, each taking a session ID and a players list.

Then run both platforms side by side. Send one region's matches to Gameye, compare session start, server behaviour and cost, and move the rest region by region. Your Agones clusters keep serving everything else until you switch them off.

Player join reference →