Feature Guides

Feature Guides

ggscale bundles the backend services a multiplayer game needs, so you do not assemble them yourself. All data lives in Postgres and is isolated by tenant and project, so one game's records are never visible to another.

This page is the map. Each feature below links to its own guide, and every guide covers one thing: what it does, the auth and config it needs, one example of the common case, and the errors you will hit. The guides stay small on purpose. For exact request and response fields, every parameter, and every status code, read the API reference.

Player and session management

Who a player is, and who they play with.

• Authentication and Players covers email/password, anonymous, and custom-token sign-in. A global player account links one person's identity across your games.
• Player Profiles hold the per-project identity fields: a player's email and an optional external console id (xuid). The display name lives on the global account and shows in friends lists.
• Friends and Presence handle friend requests, blocks, online state, and short status updates pushed over WebSocket.
• Game Sessions and Invites let players open a pre-game room with a 6-character join code and send short-lived invites.
• Remote addresses store a player's opaque connect handles, such as a Steam id. A player reads and replaces their own at /v1/account/remote-addrs and reads an accepted friend's at /v1/friends/{player_id}/remote-addrs. This one has no separate guide; see the API reference.

Data storage

Saving player state, and ranking players against each other.

• Cloud Saves give each player a JSON store for saves and settings, with If-Match optimistic concurrency so a stale write fails instead of overwriting newer data.
• Leaderboards are ranked scoreboards with server-authoritative submission. A read returns the top slice and an around-me window centered on the caller.

Multiplayer connectivity

Getting players into the same match and keeping them connected.

• Matchmaking pairs a player with compatible others from a queue. A ticket returns one of three results: the matched roster (match_only), a joinable game session (game_session), or a dedicated server (fleet_allocation, beta).
• Realtime WebSocket Events push presence, invites, and match results over one hub. A missed event is recoverable by polling.
• P2P Connectivity and TURN Relay cover the direct peer handshake, with an optional TURN relay for players that NAT keeps apart.
• Server Browser suits persistent dedicated servers. A server heartbeats into a registry, and players list it and join directly.

Game server fleet (beta)

• Game Server Fleet allocates dedicated servers on demand against infrastructure you already run. The backend is a config switch: Docker for a single VPS, Agones for Kubernetes autoscaling, or a gRPC plugin for custom infrastructure. It is gated by the fleet key scope and the dedicated_servers entitlement. This feature is beta.

Common headers

Two headers cover almost every call. See Core Concepts for how they fit.

• Authorization: Bearer <api_key> on every request.
• X-Session-Token: <access_token> on calls that act for a signed-in player.

Errors

Every error returns application/problem+json (RFC 7807) with a status, a title, and a detail string. The feature pages call out the ones you meet most. The complete list is in the API reference.

API reference

The full API reference documents every /v1 endpoint: its path, parameters, request and response bodies, and status codes. It is grouped into the same feature sections as this page.

The reference is generated from openapi.yaml at the repository root, which is the source of truth. Run make openapi to regenerate it.