Game Server Lifecycle

How game servers report health and state, and how that decides when the matchmaker queues players to them.

Every game server you run on SixTwenty moves through a lifecycle that the platform tracks with a built-in health and state module. The matchmaker reads this module to answer one question over and over: which servers are healthy, in service, and open to receiving players right now? Understanding the module is the key to understanding when and why players get queued to a particular server.

This model is the same no matter what engine your game runs on — Unity, Unreal Engine, or Minecraft. Only the SDK surface you use to drive it differs. This page describes the concepts; the engine-specific notes at the end point you to the right API for your stack.

The two layers of state

It helps to think about a server's state as two independent layers:

1. Lifecycle state — where the container is in its life. This is managed by the platform and answers "is this server provisioned, in service, or going away?" It moves through Provisioning → Ready → Allocated → Shutting Down.
2. Service status — what the running server is doing right now. This is set by your game as it plays out, and is the primary signal the matchmaker uses for routing. It is one of Lobby, In-Game, or Locked.

Layered on top of both are two more inputs the matchmaker always considers: the server's health (is it sending heartbeats?) and its capacity (does it have open player slots?).

A server is only a candidate for queuing when all of these line up — the right lifecycle state, the right service status, a healthy heartbeat, and room for more players.

Lifecycle states

These describe where a server is in its life. You advance through them with the server SDK; the Minecraft SDK advances them for you.

• Provisioning — The container has been placed on the fleet and is booting. It is not yet healthy and cannot receive players. Your server is expected to signal that it is ready (below) within its startup grace period. If it never does — a common mistake when a server doesn't integrate with the readiness hook — the platform assumes it failed to start, recycles it, and it can never be queued.
• Ready — Your server has reported that it has finished booting, is healthy, and can take players. It now counts as available capacity, and the platform can bring it into service the moment a match needs a home.
• Allocated — The server is in active service for your game mode. While allocated it is protected from being scaled down or reclaimed, because players are on it or about to be. A server only ever holds players while it is allocated.
• Shutting Down — The server is draining and being removed. It no longer accepts players.

Health and heartbeats

Independent of its lifecycle state, every server continuously sends a health heartbeat to the platform. This is the liveness contract: as long as the heartbeats arrive, the server is considered healthy.

If a server misses too many heartbeats in a row, it is marked unhealthy, pulled out of rotation, and recycled — so an unhealthy server is never queued, even if its other state looks correct. The startup grace period before the first check and the interval between checks can be tuned for games that take a long time to start or that may be slow to respond; see Project Configuration.

The Minecraft SDK responds to the heartbeat for you. On other engines, keeping the server SDK's health stream alive is part of your server's main loop.

Service status and queue eligibility

Once a server is allocated and healthy, your game tells the matchmaker whether it is open to players by setting its service status. This is the lever you control as your game progresses:

• Lobby — The server is in a pre-game / waiting state and is open to new players. This is the status that makes a server eligible for fresh matches.
• In-Game — A match is underway. By default the server is closed to new players in this status. If your game mode enables backfill, the matchmaker may still top it up with additional players mid-match.
• Locked — The server is temporarily closed to queuing — for example while a group of players is mid-transfer onto it. This is generally a very short-lived state that SixTwenty's services manage internally as part of routing; you rarely set it yourself. A locked server is not eligible for queuing.

The matchmaker combines this status with the lifecycle state, health, and open capacity to decide eligibility. There are two distinct ways players reach a server:

• New match placement — the matchmaker assembles a group of players and sends them to a server advertising the Lobby status with enough open slots. If no such server is running, the platform spins one up for them (see Auto-scaling below) — there does not need to be a server already waiting in Lobby. (If your mode allows backfill, an In-Game server may also receive a group this way.)
• Backfill — the matchmaker tops up a server that is already Allocated and reporting Lobby or In-Game, as long as it still has open slots. Backfill only happens for game modes that opt into it.

Auto-scaling: where new servers come from

A defining feature of SixTwenty is that you never pre-provision servers or keep idle ones running just in case players show up. The platform auto-scales your fleet to match real demand — bringing servers into service as players queue and reclaiming them as matches empty out. This is what lets a game mode go from zero players to a full match and back without you managing capacity by hand.

The important consequence for routing is the one called out under new match placement above: a new match does not need a server already alive in the Lobby status. When the matchmaker assembles a group and no eligible server is currently available, it brings one into service from your Ready pool — or, if none is ready, scales the fleet up and provisions a fresh container. That server boots, reports Ready, becomes Allocated for the match, and advertises Lobby; the queued players are placed onto it the moment it does. From the player's perspective, the match simply starts.

How aggressively the platform scales — and whether it creates new instances at all — depends on your game's allocation mode, set in Project Configuration:

• Dynamic — Instances are created on demand, directly in response to the queue. Players queue for the game mode itself and are routed to whichever instance becomes available; the platform spins up as many as the waiting players need and scales back down (after a grace window) when demand falls. This is the mode that most fully expresses auto-scaling.
• Static — A fixed set of individually named instances, up to a configured maxReplicas. The platform auto-scales the live count up and down within that ceiling based on load — deallocating an empty named instance and re-allocating it later, with its state restored, when someone queues for it again.
• Fixed — A constant number of instances is always running and auto-scaling is not applied. Useful for an always-on server where you want a predictable, steady footprint.

Capacity and player counts

Open slots are simply capacity − current players. For the matchmaker to route accurately, your server reports players as they connect and disconnect, and declares its overall player capacity. When the count reaches capacity the server stops being eligible until a slot frees up; when it empties out it can return to the Lobby status (or be recycled) to take a fresh match. The Minecraft SDK reports player connects and disconnects automatically.

How this works per engine

The lifecycle, health, status, and capacity concepts above are identical across engines — what changes is how you drive them.

• Minecraft — You almost never touch the lifecycle directly. The Game Engine Module maps its high-level game states onto this model for you: advancing your game to PRE_START is what marks the server available for queuing, and as your game starts and ends the SDK updates the underlying readiness, status, health, and player counts on your behalf. You focus on gameplay.
• Unity, Unreal Engine, and other engines — You drive the lifecycle explicitly through the SixTwenty server SDK inside your container: signal ready once you've booted, keep the health heartbeat alive, set your service status (Lobby / In-Game / Locked) as the match progresses, report player connects and disconnects, and signal shut down when you're done.

// With the Minecraft Game Engine Module you manage gameplay, not orchestration.
// Advancing your game to PRE_START is what advertises this server as available
// for queuing — the SDK marks the server ready and sets its status to Lobby for you.
game.setGameState(GameState.PRE_START);

// As your game starts and ends, the SDK keeps the underlying server status,
// health heartbeat, and player counts in sync — no orchestration calls required.
game.setGameState(GameState.STARTED);
game.setGameState(GameState.ENDED);

Related

• Queueing — how players enter the queue that ultimately routes them to an eligible server.
• Lobbies — the player-facing side of the Lobby status.
• Game Engine Module — the Minecraft SDK's game framework that drives this lifecycle for you.
• Project Configuration — tuning health checks and allocation behavior.