Variant → Live: the complete component walkthrough

One question, answered end to end: what exactly happens — component by component, file by file — between the moment a builder saves a spec in the dashboard and the moment a player launches the game in an operator's lobby? This page traces that path through the two real repositories as they stand today (standout-platform, this repo; and vhslab/standout-games, the engine), names every artefact and the tool that produces it, marks honestly what is automated versus done by hand, and ends with the changes that would close the gap. Almost everything here is GROUNDED · matches main; the proposals at the end are CONCEPT · proposed. The audience includes external Game Builders — terms are glossed on first use.

The component map

"Going live" is not one system — it is a baton passed across two repositories and a cloud runtime. The dashboard (this repo, standout-platform) is where a builder authors a GameSpec and saves it. The CLI bridge (standout scaffold-game, which lives in standout-platform's apps/cli) turns that spec into source code inside the engine repo (vhslab/standout-games) — a Bun + Turborepo monorepo holding 15 games today. CI (three GitHub Actions workflows) builds container images from the engine repo and ships them to GCP, where three Cloud Run services run the engine, the game clients, and the launcher API. An operator then mints a signed launch URL and the player connects. The diagram below shows the artefact flow across those lanes; the table beneath names every component with its exact path.

Read it as a relay: blue lane authors and stores the spec; the flame edges are where a human carries the baton (export the spec, run the scaffold, run sync-games.ts, set the CI GAMES arg, merge the PR); the green lane is fully automated once the PR lands. The two flame boxes inside the engine lane — sync-games.ts and the CI GAMES argument — are the friction this whole page exists to make legible.

What a game physically is

A "game" in production is not a single file — it is a set of artefacts that must all exist and agree for one manifest.id to be launchable. The table below is the definitive checklist. For each artefact it records who creates it today: ✅ scaffold means scaffold-game writes it; ⚠ manual means a human does it by hand after scaffolding; 🤖 automatic means the runtime derives it with no per-game action. The manual rows are the gap story.

Count the colours: of the fourteen artefacts, the scaffold produces eight outright, the catalogue row is automatic, and five are manual — theme application, the two sync-games outputs, the CI GAMES arg, and operator config. A variant is therefore roughly "scaffold gets you to source-complete; a human gets you to deployable." Section 5 proposes collapsing the manual rows.

The walkthrough, today

Let us trace one concrete build all the way to a player. The worked example is Neon Heist — the suite's reskin of Crash (see examples · Reskin — Neon Heist): same certified shared-world mechanic and RTP 97.0%, a cyan/violet palette (c1 #38e8ff, c2 #7a5cff) replacing Crash's flame. Five stages, A through E.

The builder opens the Builder UI, picks the Crash template, sets the theme colours and the variant name "Neon Heist", and saves. The save is a POST /api/specs handled in apps/mcp/src/api.ts; the spec is written to the D1 game_specs table as a JSON blob and the action is appended to audit_log as create_spec (attributed to the authenticated actor). The shape persisted is the GameSpec:

{
  "name": "Neon Heist",
  "templateId": "crash",
  "config": { "minCrashPoint": 1.0, "maxCrashPoint": 100.0 },
  "theme": { "c1": "#38e8ff", "c2": "#7a5cff", "name": "Neon Heist" }
}

To feed the next stage, the builder exports this record to a spec.json file. That hand-off — dashboard to CLI — is the first flame edge in diagram 1: there is no automated trigger from the dashboard into the scaffold today.

The engineer runs standout scaffold-game --spec spec.json --games-repo ../standout-games. The CLI executes twelve steps (verified against apps/cli/src/scaffold.ts), grouped into four bands — Copy, Rewrite, Wire, Ship:

1. Resolve + validate spec. Read spec.json; require name and templateId. fail-fast if missing
2. Look up the GameTemplate. getTemplate(templateId) → resolves baseGame ("crash") and base manifest id. packages/shared/src/templates.ts
3. Resolve the games repo. --games-repo → $STANDOUT_GAMES_REPO → sibling ../standout-games. existence-checked
4. Slug + collision guard. slugify("Neon Heist") → neon-heist; refuse if games/neon-heist exists. games/<slug> reserved
5. Copy the base game. cpSync the whole games/crash/ tree, excluding node_modules/dist/.turbo. → games/neon-heist/  [Copy]
6. Rename package identities. Rewrite every package.json name + workspace dep + script: @standout/crash-* → @standout/neon-heist-*. server/client/shared + root  [Rewrite]
7. Re-ID the plugin manifest. In server/src/plugin.ts, set manifest id: "neon-heist" and name: "Neon Heist" (anchored regex). other manifest fields inherited
8. Config surgery into DEFAULT_CONFIG. Balanced-brace extract the literal; per-key regex replace scalars and {min,max} ranges; warn on keys not found. …/server/src/types.ts
9. Write variant.meta.json. id, name, templateId, baseGame, theme, createdAt. theme lands here — and only here  [Wire]
10. Insert the registry entry. Inserts PLUGIN_MAP["neon-heist"] = { pkg: "@standout/neon-heist-server", exportName } at the top of PLUGIN_MAP (exportName copied from the base entry). apps/game-engine/src/plugins/registry.ts
11. Branch + commit. git checkout -b builder/neon-heist; stage the new folder + registry; commit. never on main  [Ship]
12. Optional PR. With --pr and gh available, open the PR; otherwise print the command.

Output of Stage B: a committed branch builder/neon-heist in standout-games with a source-complete game folder and a registry entry — and a flame-coloured reminder that the scaffold's job ends there. What it deliberately does not do becomes Stage C.

With the PR merged, the staging deploy workflows run. _deploy-engine.yml builds apps/game-engine/Dockerfile with --build-arg GAMES=… (now including neon-heist), tags the image, pushes it to GCP Artifact Registry, and runs gcloud run services replace to roll out the royale-game-engine Cloud Run service. _deploy-games.yml builds games/Dockerfile (every client's Vite bundle + nginx) and deploys the clients service. _deploy-games-service.yml ships the launcher API. Backing services are fixed: Postgres on Cloud SQL, Redis on Memorystore, assets on the GCS bucket. Once the engine boots with the game loaded, its manifest is served at GET /games; the games-service catalogue picks it up within its 60-second cache window — no per-game launcher change.

Now a player can play. The operator calls POST /supplier/launch on the games-service with an HMAC-signed request (verified by verifyHmac); the body carries operatorId, playerId, gameId: "neon-heist", currency, optional betLimits, callbackUrl, and a correlation sessionId. The service confirms the gameId exists in the catalogue, then mintSessionToken(...) issues a session JWT (subject operatorId:playerId) and returns a launch URL: {playBaseUrl}/neon-heist?token=<jwt>. The player's browser loads that URL — nginx serves the neon-heist client bundle — and the client opens a Socket.IO connection to the engine, which verifies the launch JWT (GAME_SESSION_JWT_SECRET) on auth. From there, every bet/win flows through the ExternalAdapter to the operator's wallet REST endpoints (/wallet/{balance,bet,win,rollback}), HMAC-signed both directions, with the bet state machine persisted in Postgres.

The gaps

Each row is one gap: where it bites (with a path), what it costs today, the fix, and which suite proposal already covers it. Amber "NOT YET COVERED" marks a gap no current proposal owns.

What we should change in how we build

Six changes, in priority order. Effort is a rough guess (S / M / L). All are CONCEPT · proposed.

Today vs target

The same game, two runtimes. The left column is what ships today (GROUNDED · matches main); the right is the decided edge target (CONCEPT · proposed, fully specified in architecture.html · Edge delivery).

The point of the two columns is not that today is wrong — Cloud Run ships real games to real operators right now. The point is that the migration is credible and incremental: the edge experiments (trunk-raider-edge, edge-game-sdk, edge-do) already run the target runtime, so the path from here to there is per-game, not a rewrite. See build-change #6.