CosmicClash/docs/MATCHMAKING.md

Matchmaking — casual and ranked queues

Design scope for online casual and ranked play. This is a 1.0 launch blocker, not a post-launch addition.

Nothing described here is implemented yet. This doc exists to record the decisions and the reasoning before code is written; per-task implementation evidence belongs in multiplayer-todo.md once work starts, and the live checklist lives in multiplayer-next.md.

The model change

The multiplayer that exists today is a community-server model. A dedicated server runs forever: it waits for --min-players by roster, counts down --start-countdown, loads the next arena from the rotation, plays a match, returns to the lobby, and repeats (server_match_loop.gd). Players reach it by direct IP, and after Phase 7 by a Steam server browser. The server is the durable thing and players come and go around it.

Queued matchmaking inverts that. Players are the durable thing: they enter a queue, a matchmaker groups them by rating and region, and a server is allocated for that one match and torn down afterwards. Both models can coexist — community servers via the browser, queues via the matchmaker — and they should, because the server browser is already most of the way to done.

Hard prerequisite: verified identity

Ranked cannot ship before Phase 7's Steam auth tickets.

Slot reclaim is currently keyed by display name (see --slot-reservation-seconds, and the known-issues list in multiplayer-next.md). A rating attached to a spoofable identity is worse than no rating at all: it is trivially farmed, and it invites players to invest in a ladder that cannot be defended. "Ranked is critical" therefore raises the priority of Steam identity rather than routing around it.

Casual queueing has a weaker requirement — it still needs stable identity for abandon penalties and ban enforcement, but the cost of a compromise is lower.

Architecture

Decided: Steam for identity, a project-owned backend for everything else.

This reverses the "no backend" position stated in TECH_STACK.md and README.md, which described the state of the project before matchmaking was scoped. The dedicated server remains a Godot export; the new service is separate from it.

The alternative — Steam-native matchmaking (lobbies plus Leaderboards or User Stats as the rating store) — was rejected on two grounds. Steam lobby matchmaking has no real concept of a skill distribution to match against, and Leaderboards are a display surface rather than a rating store with the transactional guarantees a ladder needs. It would also permanently bind the game to Steam, foreclosing other platforms.

Components

Component	Runs where	Responsibility
Steam auth ticket validation	backend	Turn a client-supplied ticket into a verified SteamID via the Steamworks Web API. The only trusted source of identity.
Queue / matchmaker	backend	Hold queued players per playlist and region; form matches on rating proximity with a widening tolerance over wait time.
Rating store	backend (DB)	Per-identity, per-playlist rating and match history. Written only by the backend, never by a game client.
Server allocator	backend	Start a dedicated-server instance per formed match, hand its address to the matched clients, reclaim it on exit.
Dedicated server	Godot export	Unchanged simulation. Gains a mode where the roster is assigned rather than open, and reports a result at the end.
Game client	Godot	Queue UI, estimated wait, accept/decline, connect-on-assignment, post-match rating delta.

What already exists and gets reused

The server side needs less new work than it looks:

• --max-matches=1 already makes the server drain and exit(0) after a single match. That is precisely the lifecycle a per-match allocator wants; it was built for CI, and it generalises for free.
• ServerConfig is a single-source-of-truth flag table with strict validation — new allocation flags are declared in one place and are automatically parsed, type-checked, config-file-backed and documented.
• --min-players / --start-countdown / --slot-reservation-seconds are the match-formation primitives, and they already count roster members rather than raw peers.
• MatchNet's roster already survives the lobby→match transition, which is the structure an assigned roster slots into.
• MatchState already has a legal-transition table with wire-stable integer values, so new lifecycle states append cleanly.

What is genuinely new

• The backend service itself (process, deploy, DB, ops) — nothing like it exists in this repo today.
• Server-authoritative match results: the dedicated server must report the outcome to the backend over a channel a client cannot forge. This is the first non-ENet/SDR network path in the project (see TECH_STACK's "no HTTP layer" note, which this supersedes).
• An assigned-roster server mode: only the matched SteamIDs may take a slot, replacing the current first-come model.
• Client-side queue UI and the accept/decline flow.

Server orchestration and autoscaling

Requirement: game servers scale horizontally and automatically, spin up fast on demand, serve exactly one match, and shut down — so cost is incurred only while a match is being played. Docker and the existing CI gates must keep working unchanged.

Why this is achievable: the server is already shaped for it

Two properties of the current build make per-match allocation practical rather than aspirational:

• The container is small. The server image target is a slim ubuntu:24.04 runtime with three shared libraries and the exported binary — about 148 MB of content, not the ~2.6 GB godot-ci build image. Pulling it onto a fresh node is cheap.
• Boot to listening is sub-second. Measured on this repo's cosmicclash-server:latest: ~870 ms from container start to the server_started log line, averaged over three runs, read from the container's own clock. That measurement was taken under x86_64 emulation on an arm64 host, so it is a pessimistic bound — native x86_64 Linux should be faster. Re-measure on the real target before setting timeouts.

Combined with --max-matches=1, which already drains and exit(0)s after a single match, the lifecycle the allocator needs mostly exists: start container → serve one match → process exits → orchestrator reclaims.

The cold-start tension, stated honestly

"Only pay during a match" and "a player never waits" are in tension. A server must be listening before the matched players connect, so some cost always precedes the match. Sub-second boot makes the gap small enough that a pure scale-to-zero design is plausible — but the risk is not the container, it is everything around it: image pull on a cold node, scheduler placement, and network/port programming can each dwarf 870 ms.

Recommendation: scale to zero at the node level is the wrong target; scale to zero at the match level is the right one. Keep a small warm pool of nodes sized to the current queue depth, and start a per-match container on demand within it. The per-match process genuinely exists only for the match; the node pool absorbs the cold-start variance. Revisit only if measured allocation latency on real infrastructure shows the warm pool is unnecessary.

Findings that block a naive implementation

Readiness cannot be detected from the log line. Godot's stdout is block-buffered when it is not attached to a TTY. Run the server image detached without -t and docker logs shows nothing at all — the server_started line does not appear even after 35 seconds, because the buffer never flushes. An orchestrator readiness probe that greps for that line will hang forever, and this was reproduced directly while measuring the boot time above. Either probe the UDP socket instead, or make the server flush explicitly. This also means container logs are not a reliable observability channel for a short-lived match server; treat log shipping as a separate problem.

One fixed port per container does not scale on a shared host. --port defaults to 7777 and the Dockerfile hardcodes EXPOSE 7777/udp. Packing several matches onto one node needs either a port range allocated per container, or one address per container. This is a UDP service, so the usual HTTP ingress/L7 routing answers do not apply — the allocator must hand the client a concrete host:port.

The match cannot start on a schedule the players do not control. Today the loop waits for --min-players then counts down. An allocated server is told which identities to expect, and needs a no-show timeout: if a matched player never connects, the server must abandon and exit rather than sit idle burning the cost this design is trying to avoid.

Keeping Docker and CI green

The existing gates must not regress. make verify-phase6 builds the export, runs it in Compose, joins two headless clients and asserts both saw both goals and that the arena rotated between matches; make verify-enet-integration runs the source-build ENet matrix. Both depend on current behaviour: compose.phase6-smoke.yml hardcodes --port=7777, relies on first-come slot assignment, and uses --max-matches=2 to prove rotation.

The rule that keeps them passing: every allocation feature is opt-in via a new ServerConfig flag whose default reproduces today's behaviour. An assigned roster, a no-show timeout and result reporting must each be inert unless explicitly enabled. ServerConfig is built for exactly this — a flag declared once is parsed, validated, type-checked, config-file-backed and documented — and tests/cases/ can cover the new parsing without a live server. A second Compose file should cover the allocated-match path rather than mutating the Phase 6 one, so the community-server model stays tested alongside the matchmade one.

Open questions

• Orchestrator. Kubernetes (with Agones, which exists for precisely this game-server lifecycle), Nomad, or direct cloud-API container starts. Not chosen. Agones is the strongest default because it models allocation, readiness and per-match lifetime natively.
• Port strategy — port range per node versus one IP per match.
• Bin-packing. SERVER.md's Phase 1 sizing estimate is 6–10 match processes per modern core and 150–250 MB RSS each. That estimate predates any allocation work and should be re-measured under real concurrency before it sizes a bill.
• Draining and deploys. How a server version rolls out without killing matches in flight.

Casual vs ranked

They are different playlists, not a difficulty toggle, and their rules diverge in ways that affect the server:

	Casual	Ranked
Rating	Hidden, used only for matching	Visible, with tiers
Backfill on disconnect	Yes — keep the match playable	No — the match is rating-bearing and must not change shape mid-way
Bots filling empty slots	Acceptable (--fill-bots exists)	Never
Abandon penalty	Light (short queue cooldown)	Real (rating loss, escalating cooldown)
Arena selection	Full rotation	Restricted set, so a variant nobody has practised can't decide a ladder match
Party / premade	Unrestricted	Constrained by size and rating spread

Note the arena constraint interacts with an existing rule: elevated-goal variants are Free-Play-only until a checkpoint trained on training_elevated.tscn is promoted (arena_registry.gd). Ranked's arena set should be drawn from "random": true arenas only.

Open questions

• Rating algorithm. Glicko-2 is the default recommendation over plain Elo: it models rating uncertainty, which matters enormously for a small launch population where most players have few games. Not yet decided.
• Team rating from individual ratings. How a 3v3 match's outcome distributes across six players is a separate design problem from the rating system itself.
• Server cost. Allocated servers cost real money per match, unlike community servers that players host themselves. README.md's original note about a subscription to fund servers is suddenly load-bearing again. Population size and match length set the bill; this needs a number before launch, not after.
• Region / ping policy. How much rating tolerance to trade for latency, and whether cross-region is ever allowed at low population.
• Placement matches and whether ranked has a soft reset per season.
• Backend language and hosting. Not chosen. It does not have to be C# despite the original README framing — that framing was aspirational and predates every real decision in this project.

Explicitly out of scope

Tournaments, in-game leaderboards beyond a personal rank display, cross-platform play with non-Steam identity providers, and spectator/observer tooling for ranked matches. None are precluded by this design; none are launch scope.