README
¶
ggscale
ggscale is an open source backend for multiplayer games. It has player accounts and auth, game sessions and lobbies, matchmaking and parties, peer-to-peer relay, dedicated servers (beta), cloud saves, leaderboards, friends, and a control panel to manage it all.
ggscale Cloud
If you prefer a managed service, run your game on ggscale Cloud and leave the hosting to us.
Documentation
Full documentation is in the ggscale wiki: architecture, features, API routes, and onboarding guides.
The HTTP API reference is generated from openapi.yaml.
Operators running relay nodes or rolling deploys should read Relay Operations, Process Lifecycle, and Operator Tokens in the wiki. Developers changing /v1 routes should read OpenAPI spec generation.
For more technical detail, ask DeepWiki:
SDKs
- Go: ggscale-go
- C# (Unity, MonoGame, Godot): gg-scale-sdk-C-Sharp
Local development and quickstart
You need Docker and make. The tests also need Go 1.26.10 or later, the version in go.mod.
git clone https://github.com/automoto/gg-scale.git
cd gg-scale
cp .env.example .env
make up
curl -s localhost:8080/v1/healthz
The health check returns "status": "ok" with the server version and commit, and the header X-API-Version: v1.
make up starts the basic stack: ggscale-server, Postgres, and Mailpit, an SMTP catcher with a web UI at http://localhost:8025. If the Mailpit ports are already in use, set MAILPIT_SMTP_PORT and MAILPIT_HTTP_PORT.
Control panel setup
- Read the one-time token with
make bootstrap-token. The server logs show the token file path (./data/bootstrap.token) but never the token value. - Open
http://localhost:8080/v1/control-panel/setup, create the first platform admin, and sign in. - Create an Account Tenant, a Game Project, and a publishable API key. Your game client sends the publishable key on every call as
Authorization: Bearer <api_key>. Create a secret key only for a game server or backend, and never ship it in a game.
The wiki onboarding guide covers the rest.
Common commands
Run make help for the full list.
| Target | What it does |
|---|---|
make up / make down / make clean |
Basic dev stack (server, Postgres, SMTP). |
make bootstrap-token |
Print the control panel bootstrap token from ./data/bootstrap.token. |
make test |
Unit tests with -race. |
make coverage |
Create coverage/coverage.out and coverage/coverage.html. |
make test-integration |
Integration tests (Postgres via Testcontainers). |
make test-e2e |
End-to-end suite against the running make up stack. |
make check |
Lint and unit tests, the same gate as CI. |
Testing
Every test target runs with only Docker and this checkout. Together they cover the GA features: auth and players, game sessions and signaling, matchmaking and parties, P2P relay, cloud saves, leaderboards, friends and invites, and the control panel.
The game server fleet feature is beta and not ready for production.
Contributing and license
See CONTRIBUTING.md. ggscale is licensed under the GNU GPL v3.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ggscale-server
command
Command ggscale-server is the ggscale control-plane HTTP server.
|
Command ggscale-server is the ggscale control-plane HTTP server. |
|
openapi-dump
command
Command openapi-dump writes the /v1 OpenAPI document to a file by building the huma-registered operations in-process (no apispec, no live deps).
|
Command openapi-dump writes the /v1 OpenAPI document to a file by building the huma-registered operations in-process (no apispec, no live deps). |
|
examples
|
|
|
ggscale-fleet-example
command
Command ggscale-fleet-example is the reference fleet plugin: a noop backend that succeeds instantly with a hard-coded address.
|
Command ggscale-fleet-example is the reference fleet plugin: a noop backend that succeeds instantly with a hard-coded address. |
|
internal
|
|
|
auditlog
Package auditlog writes append-only audit_log rows.
|
Package auditlog writes append-only audit_log rows. |
|
auth
Package auth signs and verifies the short-lived JWT issued to players after login (or anonymous signup).
|
Package auth signs and verifies the short-lived JWT issued to players after login (or anonymous signup). |
|
billing
Package billing holds the OSS side of the external-billing handoff: a signed, short-lived token the dashboard mints so the (separate, closed) billing service knows which authenticated tenant is upgrading.
|
Package billing holds the OSS side of the external-billing handoff: a signed, short-lived token the dashboard mints so the (separate, closed) billing service knows which authenticated tenant is upgrading. |
|
cache
Package cache defines the process-local fast tier for rate-limit buckets, per-player connection counters, and short-lived memoised values.
|
Package cache defines the process-local fast tier for rate-limit buckets, per-player connection counters, and short-lived memoised values. |
|
cache/instrument
Package instrument wraps the process-local cache.Store with Prometheus counters.
|
Package instrument wraps the process-local cache.Store with Prometheus counters. |
|
cache/memory
Package memory implements the process-local cache.Store used by every deployment.
|
Package memory implements the process-local cache.Store used by every deployment. |
|
cache/storetest
Package storetest holds the cache.Store contract test suite.
|
Package storetest holds the cache.Store contract test suite. |
|
config
Package config loads runtime configuration from environment variables.
|
Package config loads runtime configuration from environment variables. |
|
controlpanel
templ: version: v0.3.1070
|
templ: version: v0.3.1070 |
|
customtoken
Package customtoken holds the shared pieces of the public-key custom-token scheme: the developer's backend signs a JWT with its private key and ggscale verifies it against the tenant's stored public key, so the database holds no signing capability at all.
|
Package customtoken holds the shared pieces of the public-key custom-token scheme: the developer's backend signs a JWT with its private key and ggscale verifies it against the tenant's stored public key, so the database holds no signing capability at all. |
|
db
Package db wraps pgxpool with a tenant-aware transaction helper.
|
Package db wraps pgxpool with a tenant-aware transaction helper. |
|
entitlement
Package entitlement serves the internal declarative entitlement API an external billing service calls to converge a tenant onto "tier N with features […]".
|
Package entitlement serves the internal declarative entitlement API an external billing service calls to converge a tenant onto "tier N with features […]". |
|
fleet
Package fleet allocates and tracks game-server instances on behalf of the matchmaker.
|
Package fleet allocates and tracks game-server instances on behalf of the matchmaker. |
|
fleet/agones
Package agones implements a fleet.Backend backed by an Agones-controlled Kubernetes cluster.
|
Package agones implements a fleet.Backend backed by an Agones-controlled Kubernetes cluster. |
|
fleet/build
Package build wires a concrete fleet.Backend from runtime configuration.
|
Package build wires a concrete fleet.Backend from runtime configuration. |
|
fleet/plugin
Package plugin glues the fleet.Backend contract to hashicorp/go-plugin's subprocess+gRPC model.
|
Package plugin glues the fleet.Backend contract to hashicorp/go-plugin's subprocess+gRPC model. |
|
gamesession
Package gamesession owns game-session creation so both the player-facing HTTP handler and the matchmaker worker can mint sessions through one code path (join-code generation, per-project open-session cap, peer seeding).
|
Package gamesession owns game-session creation so both the player-facing HTTP handler and the matchmaker worker can mint sessions through one code path (join-code generation, per-project open-session cap, peer seeding). |
|
httpapi
Package httpapi assembles the ggscale-server HTTP router.
|
Package httpapi assembles the ggscale-server HTTP router. |
|
jobs
Package jobs holds background jobs run via River (github.com/riverqueue/river).
|
Package jobs holds background jobs run via River (github.com/riverqueue/river). |
|
lifecycle
Package lifecycle is the process lifecycle contract shared by the relay node and the API server: a starting → active ⇄ draining → stopping state machine, the /readyz and /lifecycle HTTP routes, their bearer guard, the lifecycle metrics, and the SIGTERM drain wait.
|
Package lifecycle is the process lifecycle contract shared by the relay node and the API server: a starting → active ⇄ draining → stopping state machine, the /readyz and /lifecycle HTTP routes, their bearer guard, the lifecycle metrics, and the SIGTERM drain wait. |
|
mailer
Package mailer sends transactional email.
|
Package mailer sends transactional email. |
|
mailer/noop
Package noop registers the "noop" mailer provider, which silently discards all mail.
|
Package noop registers the "noop" mailer provider, which silently discards all mail. |
|
mailer/smtp
Package smtp registers the "smtp" mailer provider.
|
Package smtp registers the "smtp" mailer provider. |
|
matchmaker
Package matchmaker turns player "find me a match" requests into match results.
|
Package matchmaker turns player "find me a match" requests into match results. |
|
matchmaker/query
Package query implements the matchmaker ticket criteria language: a small boolean expression grammar over string and numeric properties, parsed to an AST and evaluated in Go against candidate tickets.
|
Package query implements the matchmaker ticket criteria language: a small boolean expression grammar over string and numeric properties, parsed to an AST and evaluated in Go against candidate tickets. |
|
mcp
Package mcp serves the Model Context Protocol endpoint (POST /mcp) for coding agents.
|
Package mcp serves the Model Context Protocol endpoint (POST /mcp) for coding agents. |
|
middleware
Package middleware holds HTTP middleware shared across the ggscale-server router, such as version, rate-limit, tenant, and observability middleware.
|
Package middleware holds HTTP middleware shared across the ggscale-server router, such as version, rate-limit, tenant, and observability middleware. |
|
migrate
Package migrate is a thin wrapper around golang-migrate/migrate so the command and tests share one entry point.
|
Package migrate is a thin wrapper around golang-migrate/migrate so the command and tests share one entry point. |
|
observability
Package observability holds in-tree metrics adapters that need to hook into third-party packages (pgx tracer) — orthogonal to the middleware in internal/middleware which lives at the HTTP layer.
|
Package observability holds in-tree metrics adapters that need to hook into third-party packages (pgx tracer) — orthogonal to the middleware in internal/middleware which lives at the HTTP layer. |
|
party
Package party manages project-scoped groups that queue as one unit.
|
Package party manages project-scoped groups that queue as one unit. |
|
period
Package period computes leaderboard period reset boundaries.
|
Package period computes leaderboard period reset boundaries. |
|
playerauth
Package playerauth holds the middleware that authenticates a player via a JWT in the X-Session-Token header.
|
Package playerauth holds the middleware that authenticates a player via a JWT in the X-Session-Token header. |
|
players
templ: version: v0.3.1070
|
templ: version: v0.3.1070 |
|
projectadmin
Package projectadmin holds the project settings writes that the dashboard and MCP tokens share.
|
Package projectadmin holds the project settings writes that the dashboard and MCP tokens share. |
|
quota
Package quota holds the per-class limit ladder for enforced tenants and the growth checks that back it.
|
Package quota holds the per-class limit ladder for enforced tenants and the growth checks that back it. |
|
ratelimit
Package ratelimit applies a per-API-key token bucket to /v1/* requests.
|
Package ratelimit applies a per-API-key token bucket to /v1/* requests. |
|
realtime
Package realtime is the WebSocket fan-out for ggscale.
|
Package realtime is the WebSocket fan-out for ggscale. |
|
relay
Package relay wraps a pion/turn/v5 TURN server with ggscale's tenant + player identity model.
|
Package relay wraps a pion/turn/v5 TURN server with ggscale's tenant + player identity model. |
|
relaymeter
Package relaymeter meters managed-relay credential issuances against the class RelaySessionsPerMonth allowance.
|
Package relaymeter meters managed-relay credential issuances against the class RelaySessionsPerMonth allowance. |
|
relaynode
Package relaynode is the API server's registry of standalone relay nodes.
|
Package relaynode is the API server's registry of standalone relay nodes. |
|
remoteaddr
Package remoteaddr parses, validates, and classifies the typed remote addresses players share for peer-to-peer play: IP addresses, DNS names, and Iroh endpoint IDs.
|
Package remoteaddr parses, validates, and classifies the typed remote addresses players share for peer-to-peer play: IP addresses, DNS names, and Iroh endpoint IDs. |
|
secretseal
Package secretseal encrypts stored provider credentials that must be replayed to a third party (the Steam Web API key today, the itch key later) with AES-256-GCM.
|
Package secretseal encrypts stored provider credentials that must be replayed to a third party (the Steam Web API key today, the itch key later) with AES-256-GCM. |
|
serverlist
Package serverlist holds the in-memory registry of game-server heartbeats that powers the server-browser endpoint.
|
Package serverlist holds the in-memory registry of game-server heartbeats that powers the server-browser endpoint. |
|
signedcookie
Package signedcookie is the MAC-signed cookie framing shared by the flows that park short-lived state in a cookie: email verification and the 2FA pending challenge.
|
Package signedcookie is the MAC-signed cookie framing shared by the flows that park short-lived state in a cookie: email verification and the 2FA pending challenge. |
|
sso
Package sso holds the provider protocol mechanics for single sign-on: the OAuth 2.0 code flow with PKCE and the signed state cookie that binds a browser to one attempt.
|
Package sso holds the provider protocol mechanics for single sign-on: the OAuth 2.0 code flow with PKCE and the signed state cookie that binds a browser to one attempt. |
|
sso/ssotest
Package ssotest is a fake OAuth 2.0 provider for tests.
|
Package ssotest is a fake OAuth 2.0 provider for tests. |
|
steamauth
Package steamauth verifies Steam session tickets against Valve's ISteamUserAuth Web API.
|
Package steamauth verifies Steam session tickets against Valve's ISteamUserAuth Web API. |
|
storagelimit
Package storagelimit resolves and persists per-tenant and per-project overrides for the maximum storage-object value size.
|
Package storagelimit resolves and persists per-tenant and per-project overrides for the maximum storage-object value size. |
|
tenant
Package tenant houses the load-bearing tenant-isolation middleware.
|
Package tenant houses the load-bearing tenant-isolation middleware. |
|
twofactor
Package twofactor holds the TOTP two-factor primitives shared by the control panel and player-account login surfaces: secret encryption at rest, RFC 6238 code validation with replay protection, backup codes, and QR rendering for enrollment.
|
Package twofactor holds the TOTP two-factor primitives shared by the control panel and player-account login surfaces: secret encryption at rest, RFC 6238 code validation with replay protection, backup codes, and QR rendering for enrollment. |
|
verifycode
Package verifycode provides the shared primitives for 6-digit email verification codes used by both the operator control panel and the player-facing player flow:
|
Package verifycode provides the shared primitives for 6-digit email verification codes used by both the operator control panel and the player-facing player flow: |
|
webassets
Package webassets serves the shared front-end assets (Pico CSS, the ggscale stylesheet, and web fonts) used by both the control panel and the player-facing site.
|
Package webassets serves the shared front-end assets (Pico CSS, the ggscale stylesheet, and web fonts) used by both the control panel and the player-facing site. |
|
webutil
Package webutil holds the small HTTP helpers shared by every server-rendered surface in ggscale: the operator control panel, the player-facing site, and the JSON auth handlers in internal/httpapi.
|
Package webutil holds the small HTTP helpers shared by every server-rendered surface in ggscale: the operator control panel, the player-facing site, and the JSON auth handlers in internal/httpapi. |
|
scripts
|
|
|
ggscale-seed
command
Command ggscale-seed populates the database with realistic demo data.
|
Command ggscale-seed populates the database with realistic demo data. |
Click to show internal directories.
Click to hide internal directories.