Join the waitlist

Build and deploy

Move authority into the Engine

Use this route when the game already works in a browser and the browser still owns something a fan could change or inspect: answers, scoring, play limits, locks or settlement.

The migration keeps the interface. It moves the decisions into the Engine and changes the page to render what the Engine returns.

The result

BeforeAfter
Answers or pick values ship to the browserSolution material stays in the Engine
The page calculates its own scoreThe Engine returns the committed score
Device storage enforces attemptsThe Engine holds player state
The device clock decides whether play is openServer-derived capability decides whether play is accepted
Retrying a request can count twiceOne idempotency key identifies one intent

1. Inspect the project

Get the tool, then let it inspect the game:

curl -fsSL https://gamestage.ai/cli -o gamestage.mjs
node gamestage.mjs inspect . --write

Downloading the bundle gives you one file rather than a command on your PATH, so every later gamestage <command> in this chapter is node gamestage.mjs <command> for you. npx gamestage <command> is the other route and needs no download. Getting started has both.

The inspection of source files is read-only. --write adds gamestage.yaml. It refuses to replace an existing manifest unless --force is present, because a later manifest may contain a complete container that the inspection cannot reconstruct.

If the CLI is already signed in, inspect also makes a best-effort registration with Backstage. A failed registration does not prevent the local report or file write.

Read the report in this order:

  • Keep as yours: presentation, interaction, copy, sound and animation stay in the game.
  • Move behind authority: each finding names the source file, line and consequence.
  • Add platform support: the report notes missing identity, consent or platform integration.
  • Ask a person: licensing, intended audience and operating decisions cannot be inferred from code.

2. Confirm the game format

The format is the Engine rule set, and it is the mechanic rather than the theme or the words on screen. A game about basketball can be a Solve, a Push Your Luck, a Find the Groups, a Predict, a Bingo or a Kicker.

The formats that run today:

  • Solve (hunt): pick the right few from a board.
  • Push Your Luck (push): make picks whose hidden values build towards a ceiling.
  • Find the Groups (group): submit a set and receive whole-guess feedback such as a near miss.
  • Predict (predict): commit a call before the result exists, then mark it at settlement.
  • Bingo (bingo): each fan is dealt their own board from a shared pool and races for a line.
  • Kicker (shoot): aim, choose a power, kick. The Engine plays the keeper and decides every penalty.
  • Quiz (quiz): answer a set of questions and get one score for the set. The Quiz Engine holds each right answer.

Read Game formats before editing the manifest. Do not force a game into the nearest pattern when its rules differ.

3. Move the answers out of the page

inspect can infer a format. It cannot infer the intended content or rules. The answers leave the page and go to one of two places, and neither is gamestage.yaml, which describes the game and holds no round:

  • Studio, for the game fans play. A game's rounds are written in Interaction Cloud elements, where a producer changes them without a deploy, and the Engine reads them from there.
  • practice/round.yaml, beside gamestage.yaml, for trying the game on your own machine. dev, verify and review play it, and deploy never uploads the practice/ folder, so its answers never reach a fan. gamestage round push <game> copies it into Studio if you want to start the live game from it.

For a hunt, the answer set goes into the round's targets. For a push, each pick's value goes into the game's dataset, which only the Engine reads. For a group round, the groups and their labels go into groups. A predict has no hidden answer while it is open, so the protected fact is the committed call and the lock.

Do not delete solution material before it has moved. A clean client with no server-owned answer leaves the Engine nothing to mark.

A manifest that still carries backend.round is refused by every command with "Rounds don't go in gamestage.yaml. Put practice rounds in practice/round.yaml, and real ones in Studio." Move the block into practice/round.yaml, at the top level of that file, and delete it from the manifest.

Validate the file after each material edit:

gamestage manifest validate gamestage.yaml

See the App Manifest reference.

4. Replace browser-owned decisions

Write the generated browser clients beside the game:

gamestage client

This writes two generated files:

  • gamestage.js: the Gamestage client, for round updates, identity, consent, storage and analytics routing.
  • gamestage-player.js: the smaller player API client for a game that only needs Engine reads and plays.

Generated files are replaced when the command runs again. Keep game logic out of them.

The page should read the public challenge from the Engine, send the fan's pick, and render the returned round_state, feedback and outcome. It must not recalculate the result as a second opinion.

See the player API guide for the Gamestage client, raw routes, identity headers and retry rules.

Apply what a producer set

Above the Starter plan, a game's words belong to whoever runs it. A producer sets them in Monterosa Studio. There are ten, listed below, and they cover the game's name and lines, the word on every button a fan can press, a colour, and what this edition is called. The values arrive on the object start() returns, and the page chooses which element each one lands on.

import { applyPresentation, start } from "./gamestage.js";

const game = await start();

applyPresentation(game.presentation, {
  displayName: document.getElementById("game-name"),
  strapline: document.getElementById("strapline"),
  playButtonLabel: document.getElementById("submit"),
});

All ten settings

Every one of these arrives on game.presentation, and the spelling in the first column is what a producer's field is called under the covers. Seven of the ten are offered to every game whether the page uses them or not, so a target you do not name is a box a producer fills in and nothing shows.

Studio field keyTarget you passWhere a producer sets itWhat it is
display_namedisplayNameThe gameThe heading, and the browser title with it
straplinestraplineThe gameA line under the heading
how_to_playhowToPlayThe gameThe rules text
primary_colourrootThe gameA colour, applied as --gamestage-primary
play_button_labelplayButtonLabelThe gameThe word on the main button
play_again_labelplayAgainLabelThe gameThe word on the button that starts the next round
result_button_labelresultButtonLabelThe gameThe word on the link back to a finished round
share_button_labelshareButtonLabelThe gameThe word on the share button
edition_nameeditionNameThis editionWhat a fan sees this edition called
edition_straplineeditionStraplineThis editionA line for this edition only: a sponsor, a fixture, a date

The colour is the one that does not take an element of its own. It is written as a custom property on whatever you pass as root, which defaults to the document element, so the game decides what the colour is for: background: var(--gamestage-primary, var(--red)) uses the producer's colour when there is one and the game's own when there is not.

Studio writes primary_colour, spelled the British way. The client also accepts primary_color from an existing payload. If both arrive, the Studio field wins.

The last three are offered only to a game that has the control. A page that names no shareButtonLabel target has no share button, so a producer is never handed a word for one. Nominate the target and the box appears on their next deploy.

A line the page draws empty can carry hidden, which a filled field removes.

Your game's own words and checkboxes

A game needs more words than these ten, and sometimes a choice for the producer to make. Name a setting in the page and Studio offers a box for it on the next deploy:

The page namesStudio offersIt arrives as
label_<key>A text box under Wordinggame.presentation.labels.<key>, text
option_<key>A checkbox under Optionsgame.presentation.options.<key>, true or false

<key> is lower case letters, digits and underscores. Write the whole setting name in the page, because a deploy finds it by reading your source. A box nobody has filled in or ticked is absent, so the page decides what absent means:

// "option_game_feel" is named in full so the deploy offers its checkbox.
const option = (setting) => game.presentation.options?.[setting.slice("option_".length)];
const gameFeel = option("option_game_feel") !== false;

Seed each in gamestage.settings.json with the value fans should get, as "option_game_feel": true, so a producer opening Studio sees it ticked.

A producer saving in Studio announces it over the same connection that carries a round change, so a fan with the game open need not reload. Keep the targets in a variable and apply them again when it fires:

game.onPresentationChanged((presentation) => {
  applyPresentation(presentation, presentationTargets);
});

A field nobody has filled in is absent rather than empty, and applyPresentation leaves that element as the game built it. Copying values out by hand with ?? "" instead blanks the heading the first time a producer saves the form without typing anything.

Load when Studio is slow or down

The library remembers the last settings Studio gave each fan's device, so a page needs no words or colours of its own. Leave elements empty in the page and let applyPresentation fill them.

VisitStudioWhat the fan sees
ReturningAnswersThe remembered settings at once, replaced by Studio's when they arrive.
ReturningSlow or downThe remembered settings. The game plays.
FirstAnswersStudio's settings. Play appears once they arrive.
FirstDownThe library's "Can't load the game right now" screen with Try again.

Remembering needs the fan's "functional" consent. Without it the settings stay in memory and every visit waits for Studio, as a first visit does.

On a first visit with Studio down, start() throws GamestageUnavailableError after drawing its screen. Check error.handled and show nothing of your own:

try {
  game = await start();
} catch (error) {
  if (error.handled) return;
  throw error;
}

Nothing in verify checks this, and under dev there is no producer, so the game correctly keeps every word it shipped with. To see the values applied locally, set the Studio keys on window.GAMESTAGE_PRESENTATION before the game starts:

window.GAMESTAGE_PRESENTATION = { display_name: "Derby Day", play_button_label: "Lock it in" };

A real producer's settings reach a fan only on a game provisioned into Interaction Cloud.

5. Run the real rules locally

gamestage login
gamestage dev

dev needs a signed-in session, as verify and deploy do. Without one it refuses with "You are not signed in." login is described in full at step 7; run it once and it lasts.

dev plays practice/round.yaml on the deployed Engine, the one fans play, under the game's own practice slot so the live round is never touched. Every play is a test play and reaches no leaderboard. It needs a network connection; without one it says it cannot reach the Engine and that nothing about the game is wrong. With no practice file it plays a stand-in round of the game's format. Either way it says which in one line, for example "Round: practice/round.yaml (practice only, fans never see it)", and --serve shows a "Practice round, not live" bar on the page. It prints window.GAMESTAGE_API and window.GAMESTAGE_GAME for the page. Stop and restart after changing the round. There is no watch mode.

With no readable manifest, dev stops and says how to write one.

To prove an identified player, deploy the game with its own identity.jwt issuer and play the deployed page. dev --as, which signed a player in with keys served from the creator's laptop, was retired when dev moved to the deployed Engine, because that Engine cannot fetch keys from a laptop.

6. Prove the migration

gamestage verify

Verification checks nine things:

  • Round is the game's own: the round played here is this game's own content, not a fixture or a leftover from somebody else's.
  • Attempt cap chosen: the attempt cap was set deliberately rather than left to the Engine's default.
  • Solution absent: nothing a deploy would publish contains the private material for its game format.
  • Settings read: every setting a producer can change in Monterosa Studio is read by the page. A producer changing an offered field and seeing nothing happen is a broken game rather than a matter of taste, so this fails rather than warns.
  • Client present: a page using a Gamestage API imports a generated client.
  • Client is the door: the game reaches Monterosa through the client rather than importing a platform kit directly.
  • Server time: a lock or a countdown is decided by the server's clock rather than the device's.
  • Outcome rendered: a browser makes a real play and the screen shows the score the Engine committed.
  • Connection noticed: the page notices the connection going and coming back.

The solution check reads the whole publish set, not just the page: the same list of files deploy --dir uploads, walked with the same call, so the two cannot disagree about what ships. It reports how many files are in the set and how many it opened.

A file is read on its contents rather than its extension, so a manifest copied to answers or round.dat is still found. A manifest is found by parsing, under any name, and a source map is searched inside its own copy of your sources. A credential is a fault. A .git, node_modules, .next, .nuxt, .svelte-kit, dist or build directory is reported rather than failed, because a game may legitimately live at the root of a repository, but deploy --dir would upload it whole.

What it cannot promise: binaries and very large files are listed but not opened, encoded content is not decoded, and the leak patterns for a hand-written data file work line by line. A copy of your round is caught wherever it is; an arbitrary re-encoding of the answers may not be. Treat it as a strong net over the directory, not a proof about it.

--dir <path> names the directory when it is not the game's own.

If no browser is available, the last two checks are skipped. verify exits 0 only when every check verifies, 1 when a check is open, and 2 when no check is open but the result is unverified. --no-browser also yields 2, because asking not to inspect the screen does not prove it.

7. Deploy it

Deploying runs on the CLI's own defaults. There is no environment variable to set: the CLI points at https://api.gamestage.ai and that is the service that answers.

gamestage login
gamestage link github
gamestage manifest register gamestage.yaml
gamestage deploy <game-id> --dir .

The first two commands open a device flow a person approves in a browser: login opens the browser itself, and link github prints a code and a URL for the person to open. Registration is safe to repeat and is needed when a manifest was created while signed out.

Signing in is not the same as being allowed to deploy. login creates an account and leaves it pending, and the commands that reach the Engine refuse a pending account and say so. Somebody at Monterosa approves it. Once approved, the four commands above run through with nothing else to configure.

GAMESTAGE_CONTROL_URL exists only to point the CLI at a different environment, which is a Monterosa concern rather than a step in this route.

Choose one publish shape:

  • One HTML file: --file index.html uploads the page, both generated clients and a starter favicon.
  • A static directory: --dir . preserves relative paths, requires a top-level index.html, withholds gamestage.yaml and environment files, and removes stale files left by an older deploy. It does not invent missing generated clients.

Upload happens before the deployment gate. A refusal can therefore leave new files in storage without making the game live. A refusal exits successfully and carries a stable code in JSON because it is an expected decision, not a transient fault.

What a deploy publishes besides the game

A deploy also builds the game its own App Spec, named for the game and declaring the one format that game runs. Before this, every project pointed at a single app called Gamestage, so a producer opening the Apps list in Monterosa Studio saw our product's name and no way to tell which row was theirs, and was handed every format's element types for a game running one.

Each spec is versioned 0.0.<manifest revision>, so a game's spec history is its deploy history, and every published version is stored rather than worked out later: a registered app holds one version's URL for ever and Studio fetches it each time it draws a producer's screens. A new app is registered when the shape changes, so a rename or a format change earns a new row in the Apps list while a changed round reuses the one that is there.

Port a React or Vite app

Keep the app in its own framework. A React and Tailwind quiz stays React and Tailwind: its components, its classes, its package.json and its build stay as they are, and its own code calls the Gamestage client. gamestage create writes a starter page for each format. Read it for the calls it makes, and do not replace the app with it.

The changes, for a Vite app:

gamestage client --out public     # writes public/gamestage.js
<!-- index.html, inside <head> -->
<script>
  window.gamestageClient = import(new URL("gamestage.js", document.baseURI).href);
</script>
// vite.config.js
export default defineConfig({
  base: "./",
  plugins: [react()],
})
// src/useGamestage.js
import { useEffect, useState } from "react"

let started
const startOnce = () => (started ??= window.gamestageClient.then((client) => client.start()))

export function useGamestage() {
  const [state, setState] = useState({ game: null, error: null })
  useEffect(() => {
    let live = true
    startOnce().then(
      (game) => live && setState({ game, error: null }),
      (error) => live && setState({ game: null, error }),
    )
    return () => { live = false }
  }, [])
  return state
}

Each line has a reason:

  • public/gamestage.js: Vite serves it at /gamestage.js while you work and copies it into dist unchanged.
  • A plain <script>, not a type="module" import: Vite bundles anything a module imports, and a bundled client is a copy under a hashed name that the deploy cannot point at the hosted client, so the game would run whatever version was on your laptop. Vite leaves a plain script's import() alone, and the deploy points it at the hosted client pinned for the game. Do not name the promise gamestageReady: the client uses that name.
  • base: "./": a deployed game is served under /games/<game id>/, so an asset path that starts with / misses.
  • startOnce: React runs an effect twice in development, and the game starts once.
  • The error: when Studio cannot be reached on a first visit, the client draws its own "Can't load the game right now" screen and the error carries handled: true. Render nothing of your own for it.

Move a quiz's answers into Studio

Delete every right answer from the source: the answer key, and any comparison with it such as option === q.answer. A build ships whatever src/ holds, so an answer left in a component is in the bundle every fan downloads. The questions, their options and the right one go into the game's quiz in Studio after the first deploy, and the page reads them back:

const { game } = useGamestage()
const quizId = game?.eventId

// The producer's words, joined to the ids the Engine marks.
const questions = await game.quiz.questions(quizId)
await game.quiz.nickname(nickname)   // a fan needs one before they play
await game.quiz.start(quizId)

// The Engine marks the pick and says which option was right.
const reply = await game.quiz.answer(quizId, [{ question: q.id, option: option.id }])
const mark = reply.marks?.find((one) => one.question === q.id)
// mark.correct, mark.correctOption, reply.points, reply.standing

The score the page shows is reply.points, never a count the page kept. The Quiz starter, from gamestage create --format quiz, shows the rest: the board, a returning fan's result and each refusal in the producer's words.

Build, check and deploy the build folder

Run each command from the game's folder, where gamestage.yaml and gamestage.settings.json sit:

npm run build
gamestage verify --dir dist
gamestage deploy <game> --dir dist

Deploy dist, never .: the folder holds src/, and a deploy publishes every file in the folder it is given. If you keep a copy of the original game, keep it outside the game's folder.

What finished means

There are two separate finishes today:

  • Verified locally: verify ran all nine checks, every check is verified, and a person has played the result in a browser.
  • Hosted and operating: the deployment was accepted, the container was provisioned, and a person opened the returned Playground URL.

Do not report the second when only the first has happened.