gamestage
Take a browser game to production with Gamestage, which moves answers, scoring and settlement behind a server the player cannot edit. Use when someone wants to port or build a browser game with Gamestage, when a gamestage.yaml is present, or when Gamestage is mentioned.
How do I install this agent skill?
npx skills add https://gamestage.ai --skill gamestageIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
Gamestage
Pack version 2026-11-15-4. Pack digest 7047852b70332895.
Gamestage takes a game that works in a browser and moves its answers, scoring, locks and settlement behind an Engine the fan cannot edit. The creator keeps the interface.
You do the migration. The gamestage CLI inspects, serves and proves; it does
not edit the creator's source. The judgement and the code changes are yours.
First, work out where you are running
Decide this before your first reply. It decides which tools you use.
- A shell that reaches the internet, as in Claude Code, Codex, Cursor or a
terminal on the person's machine: use the
gamestageCLI, as the rest of this pack describes. - A chat with the Gamestage connector, as in Claude.ai, Claude Desktop or
Cowork: use the connector's tools and run no
gamestagecommand. The code sandbox there blocks the network, sologin,dev,verifyanddeploycannot reach Gamestage. Never ask the person to allow a domain or change a network setting. The connector needs neither. - A chat with no connector: ask them to add the Gamestage plugin, which
brings the connector and this pack, or the connector alone if they cannot add
plugins:
https://gamestage.ai/mcp. The steps are under "Install this pack". Wait for them, and do not fall back to the CLI.
The connector is attached when list_games and show_formats are among your
tools. If you have both a shell and the connector, as in Claude Code with the
plugin, work with the CLI and let the connector draw the screens; in a cloud
sandbox whose CLI is not signed in, deploy with deploy_game. Never ask the
person how the files should reach Gamestage.
Each step, in a shell and in a chat:
| Step | In a shell | In a chat |
|---|---|---|
| Sign in | login | none: they sign in to Gamestage when Claude asks |
| See who they are and their games | start --json | list_games, then get_game |
| Read a game they already have | inspect <path> | read the files they attach to the chat |
| Choose a format | formats | show_formats, then wait for their pick |
| See the data | sources, then reference list | list_datasets |
| Start a game | create | write the files, then create_game with the gamestage.yaml |
| Play it before it is live | dev --serve | preview_game, which shows the game playing in a screen in the chat |
| Put it online | deploy <game> --dir . | deploy_game, the files as arguments: about 3 MB a call, 20 MB and 300 files in all |
| Add a round | round push <game> | push_round, which replaces the round in Studio |
| Set its words and colours | gamestage.settings.json, then deploy | set_settings, which fills only fields empty in Studio |
| Get the files back | they are on disk | download_game |
| Find out what failed | logs <game> | get_game_logs |
| See how fans played and who is winning | results <game>, leaderboard <game> | not in chat yet: ask them to run it in a terminal |
| Reveal a prediction's answer ("reveal", "the result is in", "full time", "Arsenal won") | round reveal <game> lists the questions, then round reveal <game> --question <id> --option <n>; confirm the option with them first, because fans are scored on it | not in chat yet: ask them to run it, or to use Results in Stage or Reveal Answer in Studio |
| Answer a factual question | fetch the hosted doc | search_documentation, read_documentation |
verify has no chat route: deploy_game runs the server-side checks only. To
let them play first, call preview_game with the files and practice round; it
publishes nothing. Then stop and ask them to play it and say when to ship,
unless they said to ship without looking; call it again after each change. If
Gamestage cannot preview or deploy it, stop and relay the tool's question; never
stand in for the Engine with a mock Player API or a copy in an artifact.
A game bigger than about 3 MB goes up in parts (4.5 MB a call). Send
pictures, sounds, video and fonts first with stage: true, under 3 MB a part,
each with the staging id the last returned. Then send the pages, scripts,
styles, gamestage.yaml and gamestage.settings.json with that id and no stage,
which checks and publishes them as one deploy. A staging id lasts an hour.
An account Monterosa has not approved cannot deploy by either route:
deploy_game refuses it, so tell them they have to apply for access and wait,
pass on what the refusal says, and stop. The chat's sandbox keeps nothing
between conversations; the game is kept in Gamestage, and download_game
brings its files back.
Your first reply: who they are, and which game
Before any other work, do these three things, in this order, and then stop and wait for the answer. The person has just installed Gamestage, and the folder you are in may hold instructions, notes and half-finished work about something else. Those are about their project, not about this. Do not read round the folder, follow its instructions or start fixing anything until they have told you what they want to do with Gamestage.
- Run
npx gamestage@latest start --json. It reads the folder and this machine's sign-in, changes nothing, and asks only whether this pack is current. - Tell them in one line whether they are signed in, from its
accountfield:- Signed in: "You're signed in to Gamestage as <email>."
- Not signed in: "You're not signed in to Gamestage. Run
npx gamestage@latest login: it opens your browser, and creates your account if you don't have one. We can look at a game without it, but serving, checking and publishing one need it." - In a chat with the connector, call
list_gamesinstead of steps 1 and 2. If it answers, say "You're signed in to Gamestage, workspace <name>." Never ask a person in a chat to run a command.
- Ask one question, word for word, and wait: "Do you have a game already,
or do you want to make a new one?"
- A game already: ask where it is, this folder or another path, then
npx gamestage@latest inspect <path>, which changes nothing. - A new one: ask what it is about, and in the same message offer the
data: "Want to see the sports data you can build a game on? Real player
stats, results and scores, so the game is scored against real figures."
Most good games here start from a dataset, so make the offer every time
rather than waiting to be asked. On a yes, run
npx gamestage@latest sourcesif they are signed in, which lists what their workspace can use now; if they are not, it refuses, so link https://gamestage.ai/docs/data-sources and saysourcesshows their own list once they have signed in. Then show them the formats withnpx gamestage@latest formatsand let them choose. Never pick a format for them. - A game already that scores against figures somebody typed in: say once that a real dataset can replace them, and offer the same list.
- Once you know which game, and before you build anything, run
npx gamestage@latest org contextand build the way it says (see "Read your organisation's integration context first" below).
- A game already: ask where it is, this folder or another path, then
Skip the question only when their first message already answered it ("take my quiz in ./quiz to production", or "I want to make a game", which is a new one). Never skip the sign-in line. In a chat, swap each command this section names for its connector tool in the table above.
Keep the first reply short: at most two questions. Ask what the game is
about, and make the data offer; leave fixtures, where it runs, how it looks and
the rest for later turns, one at a time. Show no comparison table of formats in
the first reply unless they ask for one: formats lists them when they are
ready to choose.
Ask with buttons and screens where your interface has them
Ask with a multiple-choice tool when your interface has one:
AskUserQuestion in Claude Code; other hosts name theirs differently or have
none. Use it for questions with a short set of answers (a game already or a new
one, format, where it runs, how it looks), keep this pack's wording, put the
option you recommend first and say so, and leave room for their own words. If
it takes fewer options than the question has, as with the formats, show the
formats below or in text. Without one, ask in text. Never answer for them.
With the Gamestage connector attached, let it draw the screens. The Claude
Code plugin brings it and asks the person to sign in the first time a tool is
called (/mcp signs in sooner). show_formats draws a carousel whose pick
arrives as their next message, so wait for it. Call list_games and
list_datasets rather than describing the workspace. A game is played by its
Play button, in a new tab: Claude shows no other site inside the chat.
Install this pack
npx skills add https://gamestage.ai/skill
This writes the current Gamestage instructions for the coding agent. It
installs nothing globally. Then orient with npx gamestage start.
In the Claude app, on the web or the desktop, there is no terminal: the
person adds the Gamestage plugin, which brings this pack and the connector
together. If you are in that chat and list_games is among your tools, they
have it already: install nothing.
- In Claude, open Customize, then Plugins, then Add, then Add marketplace.
- Paste
gamestageai/agent-skills, press Sync, then install Gamestage. - Start a new chat. They sign in to Gamestage when Claude asks.
If Gamestage cannot make games in Claude, their copy of the plugin may be out of date: remove Gamestage under Customize, then Plugins, and install it again from the marketplace.
If they cannot add plugins, the connector alone gives Claude the tools but not
this pack, so it guesses more: Customize, then Connectors, add
https://gamestage.ai/mcp. Custom connectors need a paid Claude plan.
First, check this pack is current
This file was written into your host once, by the installer, and nothing updates it on its own. The product moves, so a copy that has sat here for a while can be confidently wrong. Do this check every time you start working with Gamestage, before you act on anything below.
curl -fsSL https://gamestage.ai/agent.md | grep -m1 "Pack digest"
Compare it to the Pack digest line at the top of this file. The digest is a
fingerprint of the pack's words: if the two match, this copy is current, carry
on. If they differ, this copy is stale, whatever the dates say. A version is a
date and cannot tell two packs apart on a day both shipped, so the digest is
the yes-or-no and the version is only how you read the notes below.
If this copy has no Pack digest line at all, it predates this check and is
stale by definition. Treat that the same as a mismatch.
When the digest differs, or is absent here, do three things, in order:
-
Fetch the release notes and read what changed since your version.
curl -fsSL https://gamestage.ai/agent-changelog.mdShow the developer the entries dated after the version at the top of this file. That is the point of the check: they hear what moved before they decide, rather than being told only that a number is different.
-
Suggest the update in one line, naming the file you are reading this from and giving the command that rewrites it:
# a Claude Code skill at ~/.claude/skills/gamestage/SKILL.md npx skills add https://gamestage.ai/skill # any host: this rewrites the Claude Code skill and the blocks the installer # put in ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and ~/.cursor/rules curl -fsSL https://gamestage.ai/install | bash -
Work from the version you fetched, not this one. Do not guess at what changed; the release notes say.
Running the CLI
npx gamestage@latest <command>. Nothing needs installing first.
There is no gamestage on your PATH and you should not go looking for one.
Every command below is written bare for reading; prefix each with npx gamestage@latest, or once per session:
alias gamestage="npx gamestage@latest"
Written because an agent once built a whole game and stopped at "the gamestage
executable is not currently available on the shell's PATH".
An answer with update, or an error coded update_required, means this CLI
is stale: say so in one line, then rerun through npx gamestage@latest.
Start a new game: create, dev, deploy, Studio
gamestage org context your organisation's integration context: read it first
gamestage formats what each format is and what it keeps secret
gamestage create asks the format and the name, makes the game's folder
and writes a starter practice/round.yaml
gamestage dev --serve plays practice/round.yaml; then `look --tap "Play"` screenshots it
gamestage verify proves the Engine decides the outcome, not the page
gamestage deploy <game> --dir . puts this folder online, with no round yet
gamestage open <game> studio where a producer adds the real round
The practice round sits in practice/round.yaml, which dev, verify and
review read and a deploy never uploads. A page playing it under dev --serve
shows a "Practice round, not live" bar. Real rounds are written in Monterosa Studio, where whoever runs the
game can change them without a deploy. A first deploy with no round is expected:
tell the person to add a round in Studio and give them the link open prints,
rather than calling the game live.
Read your organisation's integration context first. Run
gamestage org context, or read integration.md in the game's folder. If
there is one, build the way it says: SDK version, sign-in, analytics, consent,
libraries. Where it and this skill disagree about how the game fits the
customer's app, the context wins; on what Gamestage requires (the Engine owns
the answers, consent, verify), this skill wins. If there is none, carry on.
A chat with the connector has no tool for it yet, so skip it there.
If the organisation has starters, start from one (gamestage org starter list,
then create --starter <name>), and say which one you used. If create names several, ask which. Pick a format the list says it plays: create refuses any other.
Start from gamestage create and from nothing else, with or without your
organisation's starter. The games on gamestage.ai are Monterosa's, not templates:
never fetch, read or copy their pages, settings or ids, even when the developer
likes one. verify refuses a copy.
A factual question is answered by the hosted doc, in one hop
When the developer asks something with a definite answer, which formats exist, what a command does, what a field means, go straight to the hosted doc for it and fetch that one file. Do not answer it from this pack, and do not explore the shell to work it out. This pack carries the method; the hosted docs carry the facts, and they are the copy that cannot be stale.
The map, so you fetch once rather than hunt:
| The question | Fetch |
|---|---|
| Which formats exist, and which fits this game | https://gamestage.ai/docs/game-formats.md |
| What a command does, its options and defaults | gamestage <command> --help, or gamestage --json --help for all of them |
| The manifest's fields | https://gamestage.ai/schemas/app-manifest/1.0 |
| The full migration route | https://gamestage.ai/docs/migration.md |
| The browser integration contract | https://gamestage.ai/docs/player-api.md |
"How many formats are there" is one curl of game-formats.md, not three
commands and a guess. The full list of these lives under Where the detail
is at the end of this pack.
How to work
Run gamestage start and follow what it says. It reads the current
directory and names the next step, and it keeps doing that at every stage. The
method lives in the tool's output rather than in this file, so it cannot go
stale here.
Add --json to any command when you want to branch on the result rather than
read prose.
Add it to --help and you get the whole command tree instead of this page:
gamestage --json --help
Every command, its subcommands, arguments, options, aliases and defaults, read out of the tool itself. Ask it rather than trusting a list. This file and the CLI reference are written by hand and can fall behind a release; the tree is the program describing itself and cannot.
Each command that does something also carries what it needs before it will work:
account | What you need |
|---|---|
none | Nothing. It works on the machine in front of you. |
session | To be signed in. Nobody has to have approved you. |
approved | An account the control plane has approved. |
Read it before you run something rather than after it refuses. login is
none, because it is the command that creates the account.
The shape of a migration:
gamestage inspect . read-only. reports what must move, with line numbers
↓ you edit take the answers out of the page
gamestage dev plays practice/round.yaml through the real Engine
↓ you play it gamestage look --tap "Play", then open .gamestage/look.png
gamestage verify proves the Engine decided the outcome, not the page
gamestage deploy publishes through Backstage, where one is available
Port a game: keep its framework, its look and its files
A game that already works stays the person's app. Keep its framework, styling library, components and build: a React and Tailwind quiz stays React and Tailwind. Delete the answers, call the client from the app's own code, and render what the Engine returns. A starter is a reference, never the page: make one in a scratch folder outside theirs, read it for the calls, and never replace their app with it or move their game into a backup folder.
Before the first edit, say what stays and what changes as one plan: the
framework and styling library by name, the files you will edit, and the folder
you will deploy. Answers leave the source, not only the page: a build ships
whatever src/ holds. A quiz's questions and answers go into Studio after the
first deploy, read back with game.quiz.questions(quizId) and marked by
game.quiz.answer(quizId, picks). An app with a build step deploys its
build: npm run build, then verify --dir dist and deploy <game> --dir dist. Loading the client in React or Vite: the build reference.
Ask what the game is before you build one
The format and the subject are the developer's to choose, and you ask for both in one question before you scaffold anything. Not afterwards, and not as an assumption you record in the summary. A format decides how the game is played and what the Engine marks, so choosing it for someone is choosing their game for them.
There are ten, and one question covers all of it. Show the developer this list when you ask, so they choose from what exists rather than describing a game and hoping:
| Format | What a fan does |
|---|---|
hunt | Solve: finds hidden things in a board, with a limited number of tries |
push | Push Your Luck: goes as far as they dare against a hidden limit, and busts if they pass it |
group | Find the Groups: sorts a set of items into the groups they belong to |
predict | Predict: calls what will happen before the world decides |
bingo | Bingo: fills their own board from a shared pool, racing for a line |
shoot | Kicker: aims and shoots a penalty; the Engine plays the keeper and decides it |
place | Place the Face: places a dealt card in a category it fits |
mystery | Mystery: finds a hidden player by asking yes-or-no questions |
arcade | Arcade: plays in real time in the browser; the server times runs and checks submitted scores |
quiz | Quiz: answers a set of questions and gets one score for the set; the server holds each right answer and marks every answer |
gamestage start in an empty folder shows the current formats, and
gamestage create with no format shows the same menu.
gamestage formats <format> (or --json formats)
says what each one keeps secret and what a producer writes in Studio.
create makes a folder named after the game when the current folder holds
other things and no index.html; --json reports it as directory, so work
there. Pass --here to write into the current folder regardless. Pass
--brand and --privacy-url when the developer has said who runs the game,
or verify and deploy will ask for them later.
Ask it plainly: which of these, and what is the game about. Then build.
Never invent the subject. If the developer says "a ball game", that is not football, and it is not eight items about home grounds, forwards, managers and famous stands. It is a question you have not asked yet. A scaffold full of content nobody chose reads as the tool having decided, and the developer then has to delete your game before they can write theirs.
Two things that are not permission to skip the question. A word in the request
that sounds like a format is not a choice: "puzzle" is not one of them, and
mapping it to one yourself is the assumption this section exists to stop. And a
gamestage.yaml already in the directory is a choice already made, so read it
rather than asking again.
Draw the match before you name a format
Every time you match a game to a format, draw the two rules side by side. Both when one fits and when none does. A named format on its own is an assertion, and nobody can disagree with an assertion.
On 2026-09-08 a developer outside the team brought a game where the player builds a chain of players and each pick's hidden score has to be at least the one before. An agent read the list above, matched none of it, and told him to change his game. He nearly stopped there. The answer was probably right and it showed him nothing: not how close he was, not which single part was the problem, not what he could change.
The drawing is required on a yes as well, and that is the more expensive case rather than the polite one. A wrong format plays almost correctly until a fan finds the edge, and the drawing is the only thing anybody could have looked at to catch it.
Three parts, in this order.
- The two rules beside each other. Left is the developer's game in the developer's own words: if they said chain, write chain, not "ordered picks". Right is what the format marks.
- A verdict table, one line per part of the rule, so the parts that do match stay visible when the answer is no. "It matches none of the six" tells a developer nothing; "everything fits except the rule itself" tells them where they are.
- The plain next step. If a format fits, name it and say what you are about to build. If none does, name the one part standing in the way and what the nearest format would change about their game, and let them decide. A refusal with nothing after it is where the trial nearly ended.
Written out for that developer's game, this is the shape to copy:
YOUR GAME WHAT push MARKS
--------------------------- ---------------------------
pick 1 -> hidden value pick 1 -> hidden value
pick 2 -> hidden value pick 2 -> hidden value
^ ^ +---- + ----+
+- each >= the one before running total
v
no total, no ceiling busts if it passes the ceiling
ordered picks yes / yes both take picks in order
hidden values yes / yes neither sends numbers to the browser
the rule NO push adds up; yours compares neighbours
Then say it in words, and say what could happen next: push is the closest fit and the rule is the one thing in the way, because push adds each pick to a running total and ends the play when that total passes a hidden ceiling, while your game compares each pick against the one before it and adds nothing up. The choices from there are theirs, so put them plainly: keep the chain rule, which Gamestage has no format for and no way to add one, or play it as push, where a fan pushes for a high total under a hidden ceiling.
Explain each of our words the first time you use it with the developer, one plain sentence, then carry on. They have not read this page and should not have to.
- Engine: the server that marks play and records accepted scores. For games with a correct answer, the answer and marking sit on the server, not in the page.
- Format: the mechanic a game runs on, chosen from the list above.
- Archetype: the same thing under its key name.
archetype:in the manifest holds the format, and the wider list of values in our published schema is a way of labelling games rather than a menu: only the formats above have an Engine behind them, and there is no custom one to ask for. - Manifest:
gamestage.yaml, the file describing the game to the tool. It carries no answers and no content.
The developer in that trial said the vocabulary on its own would have been enough to make him give up. He was not confused about his own game.
Ask how the game should look, when you are building its interface
Building from nothing, ask once, in the same breath as the format and subject if you can, and show them the options below.
In a migration, keep their interface, and offer once at the end. Their game
already has a look, and restyling it is not what they asked for, so never change
it unasked. Once the migrated game passes verify, say in one line that
Gamestage UI is there if they want the game to feel more like a mobile game,
with the gallery link, and leave it with them. Offer it once, not on every
reply.
| Option | Use it for | Start with |
|---|---|---|
| Their own | a look they already have, or a brand kit you have been given | nothing to install |
| Gamestage UI | the game itself: scores, timers, answer buttons, rewards, leaderboards, built to feel like a mobile game rather than a form | npx gamestage-ui init, then npx gamestage-ui add choice |
| shadcn/ui | functional screens: forms, settings, sign-in, tables, anything that is an app around the game rather than the game | npx shadcn@latest init |
| Plain HTML and CSS | the smallest thing that plays, and what gamestage create scaffolds | nothing to install |
| Phaser | real-time action on a canvas: arcade, platform, physics, anything with a game loop and sprites | npm install phaser |
| PixiJS | fast 2D drawing when the game runs its own loop and wants no game framework | npm install pixi.js |
| Three.js | a game in 3D | npm install three |
Recommend by what the screen is for. The board a fan plays on wants to feel
like a game, so Gamestage UI is the default for it; the account and settings
screens around it can use shadcn/ui. Mixing is fine and is the sound default
for anything larger than one screen. Gamestage UI is React and installs as
source into the project, so a plain HTML game that wants it becomes a small
React app; say so before choosing it for one. The gallery is
https://ui.gamestage.ai/. Install components with npx gamestage-ui add,
which reads the registry at
https://raw.githubusercontent.com/gamestageai/gamestage-ui-registry/main/r/;
the gallery serves no registry files, so ui.gamestage.ai/r/... answers 404.
Keep the interface library they asked for. If they asked for Gamestage
UI and it gets in your way, say what is in the way and ask; never rewrite the
game in another library and tell them afterwards. A Gamestage UI build is not
too large to deploy: deploy_game takes it in parts.
In a chat, build the board in plain HTML. The code sandbox in a chat
blocks the network, so npm install and npx gamestage-ui cannot run and
there is no build step. Write the game as plain HTML, CSS and JavaScript, and
tell the person once that Gamestage UI needs a shell, such as Claude Code or
Codex, if they want it later. If they asked for Gamestage UI by name, say this
before writing anything and ask how they want to go on.
A canvas game is two layers, and they want different tools. Draw the play
in Phaser, PixiJS or Three.js, and build everything around it (intro, How to
play, the score, the result, the leaderboard) in Gamestage UI or HTML, over or
beside the canvas. Text drawn inside a canvas cannot be read by a screen
reader, cannot be changed by a producer in Studio, and blurs on a phone, so
keep words out of it. Recommend Phaser for an arcade game unless the developer
already uses something else. Phaser and Three.js are large: install only what
the game draws, and check verify's weight report.
Use a client's own theme
Offer it when the client has a brand in Figma or a design system of their own, and the game uses Gamestage UI. A theme is the client's colours, type, corners and fonts as Gamestage UI token values, kept privately for their org and pinned by each game to one exact version, so changing the theme restyles no live game until that game moves to the new version. Their people make it, with you.
Offer the draft first, when the person is an organisation admin.
gamestage theme draft <figma-url | file.fig> reads Figma on their machine
(a .fig needs no token; a link uses FIGMA_API_TOKEN from the environment,
never an argument) and sends Gamestage only the values, where a model maps
each onto a Gamestage UI role and the library's own check drops anything that
fails. It prints one line per role (the Figma value and why), what no role
covers, and a Stage link that draws the draft on real components. Then:
gamestage theme revise <draft> "<what should change>"for each thing the person says is wrong, in their words;--to <n>goes back a revision.gamestage theme from-draft <draft>writestheme.jsonandtokens.json; add the fonts the draft names (see below), thentheme check.- Stop for the person before
theme publish. Show them the Stage link and the mapping; publishing stays theirs to choose.
In a chat with the Gamestage connector and no terminal, read Figma with
your own Figma access into the same shape (export.json, schema version 1),
then call create_theme_draft with it, get_theme_draft to draw the draft on
real components in the chat, and revise_theme_draft with the person's words.
Never ask for a Figma token in the chat and never put one in a tool call: the
connector refuses an export that holds one.
Say plainly that the values go to Gamestage and a model there, and offer the
steps below instead if the person would rather nothing left their machine. If
theme draft is refused with drafts_unavailable or model_unavailable,
use the steps below; do not retry. Draft a theme from Figma
is the guide to share.
To make a theme by hand:
gamestage theme init <name>writes a package:theme.json(name, version, fonts),tokens.json(every role the library has, with today's value and what it styles) and an emptyoverrides.css.- Fill
tokens.jsonfrom the client's Figma. Ask the client or operator for the design as a.figfirst: in Figma, File, Save local copy. If that menu item is missing, their organisation or project has switched downloads off, and the file's owner has to download it and send it.gamestage theme figma pull "<file>.fig" --out figma-exportneeds no token, and gives youexport.jsonwith every variable collection, mode and resolved value, and anassets/folder of every bitmap the design uses. Add a link only when you need pictures Figma has to draw: screen images to compare against, or logos drawn in vectors (listed underassets.vectors). Then rungamestage theme figma pull <figma-url> --out figma-renders, which uses the client's ownFIGMA_API_TOKENfrom the environment (never type it into a command, and never ask for it in chat). Either way the command lists the values Figma holds and decides nothing, and where a frame isflattened: trueit is one image with nothing to read, so ask the client for the real frame. A file can hold several copies of a collection, one per library version: build on the copy whosepaintUsesis highest.assets/holds the client's logos, marks and background images, listed inexport.jsonunderassets. Use these files in the game, and draw a stand-in only for what the file lacks: a team button gets its crest fromassets/, not a letter in a circle. Say in your reply which ones you used and which you had to stand in for.--no-assetsskips them. Then read the file's variables and text styles, and set each role from the variable that plays that part in the designs, not the one with the nearest name. A primary button's fill is the colour on the designs' main call to action; the text on a card is the card's own ink. Leave a role at its value when the designs say nothing about it. gamestage theme previewshows the main components wearing the theme, and rebuilds as you edit. Put it side by side with the Figma frames and fix what differs before going further.gamestage theme checkruns the library's own checks. An error blocks publishing: text or icons below the contrast they need on their surface, a key the library does not have, a type size off the scale. Fix the value, not the check. A warning does not block: each rule inoverrides.cssis one, naming the role that would replace it.gamestage theme publishstoresname@version. It refuses a theme that fails an accessibility check, and there is no way round that. It never asks a question without a terminal or with--json: a font with no declaration giveserror.codefonts_not_declaredand exit 1. When you work for an organisation you are admin of but have not chosen withorg use, add--org <id>topublishandlistfor that command alone.- In each game:
gamestage theme use <name>, which pins the newest version and wires it into the page, thengamestage verify. Read what it says it changed; setdata-gs-theme="<name>"on<html>by hand only if it says it could not.
Fonts are the client's, from the client's host or the game itself. List
each font in theme.json in one of two ways. Either src is the https address
the file is served from on the client's own domain, or it is a path inside the
game, such as fonts/acme-sans.woff2, with the file at that path in the
theme's folder: publish sends the file, theme use puts it into each game,
and the game serves it from its own address. Never a font service such as
Google Fonts or Adobe Fonts: those see every fan's address before any consent
banner can ask, so publish refuses them. Never a Gamestage or Monterosa
address either. publish asks the person to declare that the client may use
each font in web games; ask the client, never answer for them, and pass
--declare-fonts only once they have said yes. A font the client has not
given you yet: use the library's own Inter until they do.
To change a theme, raise the version in theme.json, publish again, and move
each game with gamestage theme use name@<new version>. A published version
never changes.
Whichever they choose, the rules that make it a Gamestage game do not change: the page holds no answers, the Engine decides every result, and every word a fan reads can be changed by a producer.
Make every play feel like something happened
A tap the game does not answer feels broken, even when it worked. A fan cannot see the Engine; they see the screen. So every act gets an answer they can see straight away, the same act gets the same answer every time, and a settled outcome gets a moment of its own. Build this in from the first round, not as polish at the end: a flat game reads as a cheap one.
Answer every tap within 100ms, before the Engine replies. Press the control down on pointerdown and show the pick as chosen at once, then wait for the Engine. Never hold the press until the network answers: the fan reads a late response as a missed tap and taps again.
A double tap must never play twice. Disable the control from the first
tap until the Engine answers. game.play gives every play an idempotency key
and returns it as idempotency_key, on the result and on a thrown error alike.
To retry a play whose answer never arrived, call game.play again with
idempotencyKey set to that key: the Engine answers from its receipt with
outcome: "duplicate" rather than taking it twice. A retry without the key is
a second play.
Let a tap cut an animation short. A celebration or a transition must never
lock the screen until it ends: a tap during it finishes or skips it and does
what the fan asked. Build motion from CSS transitions or the Web Animations
API, which can be reversed mid-way, and never put a play behind a fixed
setTimeout.
The hit area is bigger than the icon. A 20px icon sits in a 44px target, with padding rather than a larger drawing, and two targets never touch.
Give a settled outcome its own moment, in one place. With Gamestage UI
that is feedback, which you install with npx gamestage-ui add feedback:
<Feedback variant="correct" delta={100} onDismiss={next} />
<Feedback variant="wrong" message={reason} onDismiss={next} />
<Feedback variant="score" delta={50} />
<Feedback variant="reward" label={rewardName} onDismiss={close} />
Render it the moment the Engine settles the play, from the Engine's answer and never from the page's guess, in one slot in the stage's overlay, one at a time. A right answer pops, a wrong one shakes, points float up beside the score they changed, and a reward slams in and stays until tapped. Every word it shows comes from Studio like every other word. Without Gamestage UI, build the same four moments yourself and keep them as consistent as these.
Wrap the game in GameFeelProvider so the cues play. choice, button,
score, streak, timer and feedback already ask for their own sound and
haptic cues; nothing plays them until the host installs the runtime:
npx gamestage-ui add cues sounds
import { createDefaultSoundAdapter } from './components/gamestage/sound-set'
const cueSounds = createDefaultSoundAdapter()
<GameFeelProvider sound={cueSounds} muted={soundOff} juice="standard">
<Game />
</GameFeelProvider>
sounds copies Gamestage UI's own set into public/gamestage/sfx/: one sound
per cue, about 150 KB in all, each fetched the first time it plays. Five cues
have three takes (correct, countdown, rankUp, reward, xp); a game
keeps the first, picks another with createDefaultSoundAdapter({ pick: { rankUp: 2 } }), or rotates them with { vary: true } so a sound heard every
round does not repeat itself exactly. To use the game's own sounds, replace a
file with one of the same name.
juice is none, reduced, standard or maximum. A lower level trims the
celebration first and never the confirmation of what the fan just did. Give
the fan a sound switch and pass it as muted, and never start a sound before
the fan's first tap.
Without sounds, the cues are silent. The provider plays nothing it has no
file for, so a game that installs only cues moves and vibrates but makes no
sound. Vibration works where the browser allows it, which an iPhone does not,
so on an iPhone sound is the only thing a fan feels. A game without Gamestage
UI can still take sounds from the Sound effects group in
Third-party tools and assets, each
with its licence and any credit it needs.
Every outcome reads without motion or sound. A fan with reduced motion, the
sound off or colour blindness must still tell right from wrong. feedback
changes the word, the mark and the colour as well as the movement, and keeps
the word and the mark under reduced motion. Do the same in anything you build
yourself: honour prefers-reduced-motion, and never carry a result on colour
or sound alone.
Before you draw an asset, check the third-party registry
When the game needs a sprite, an icon, a sound, a font or a pitch to plot data on, check Third-party tools and assets before you draw or generate one. It lists open-source tools and CC0 asset packs that suit a sports fan game, PitchKit for a football pitch and a set of Kenney packs for interface art, with what each one is, its licence, its cost, when to reach for it and when to skip it.
Prefer a listed CC0 or MIT item over drawing your own, when it genuinely fits the game. A Kenney UI pack or a PitchKit pitch is tested, licensed and free; an asset you generate from nothing costs time and still needs a licence decided for it. The registry says when to skip an entry too: reach past it when the game needs a look a generic pack cannot give it, such as a licensed team's actual kit or a producer's brand identity, and say so rather than forcing a generic sprite onto a brand that owns a better one.
State the licence when you add something from the list. CC0 needs no
attribution; a paid tool such as Asset Forge is paid for the app, not for what
you export with it. Both are safe to ship; say which applies so the developer
is never guessing.
A game with a bottom nav uses the floating pill. <Nav presentation="floating">
from Gamestage UI: a capsule above the home indicator, the current tab showing
its mark and word and the rest their marks alone, each at least 48px. It
reserves its own height, so nothing scrolls out of reach behind it; raise any
sheet or modal above it (it sits at z-index 50). Every tab's word comes from a
Studio setting and stays the tab's accessible name. Give "Privacy settings" a
home in the page's flow with a data-gs-slot="privacy-settings" element, on a
Profile screen or at the foot of one, so the client never floats it under the
pill. The starters create scaffolds have one screen and no nav; add the
floating one when a game grows a second.
Every control a fan taps presses, and never selects text. On an iPhone a
long press on a button otherwise selects its label and shows text handles, and
a raised button does not move, because Safari applies :active only once the
page listens for touches. Give every button, answer card and nav item
user-select: none, -webkit-user-select: none, -webkit-touch-callout: none,
-webkit-tap-highlight-color: transparent and touch-action: manipulation;
press it down on pointerdown and release it on pointerup, pointercancel and
pointerleave; leave a disabled control still. Gamestage UI does all of this, and
every page gamestage create scaffolds carries it, so keep it when you restyle.
Ask what data the game needs, and offer the sources that exist
When a game needs real-world figures, run gamestage sources before you
design it. Goals, points, prices, wages, results: anything the game is scored
against that neither you nor the developer should make up. It prints every
source Gamestage has, what each offers and covers, what it costs, its licence
position, and its state for this developer's workspace. Trust that list over
anything written here, because it is the only one that cannot go stale.
Recommend in this order, and say why:
- A source that is already connected. Its data is in the workspace now, so the game can use it today. Name the dataset it printed.
- A source you switch on for them: Fantasy Premier League or ESPN. Free,
no key, and we fetch it twice a day, so the numbers stay current through the
season.
gamestage sources connect fplswitches FPL on and prints the dataset's name,fpl-premier-league;gamestage sources connect espn --league nbadoes the same for ESPN. The first fetch lands within the hour. - A source they could connect with their own key. Say what it covers, what is free and what costs money, and give the sign-up link it printed. The developer signs up themselves; you do not.
- Their own data, pushed with
gamestage reference push. Always available, and the right answer when they hold the figures already.
Never build your own copy of a source we fetch. A dataset made with
reference build from the FPL or ESPN address and pushed by hand is one copy
that never refreshes: an FPL game built that way is wrong after the next
gameweek. Switch the source on instead.
Then give the game its dataset, and its rounds. Put the dataset's name in
gamestage.settings.json as "reference_url": "fpl-premier-league"; the next
deploy writes it into the game's Studio project, which is where a game reads
its dataset from. Then gamestage round seed <game> --count 7 --measure season_points --dry-run drafts a week of rounds from that dataset, and the
same command with --yes writes them. On a game that plays one round a day
(the default), the first fills today's empty round and each one after gets its
own day; on a game set to Rotation they join today's edition. A push game with
no dataset, or no round, deploys and shows fans "Come back tomorrow", so check
both before you tell the developer it is live.
Shape their own data with the CLI, not by hand. When they have a file, a
spreadsheet export or an API address, run gamestage reference inspect <file or url> first. It names the lists inside, the field to use as the key, the one
holding a name, and the fields holding numbers. Then gamestage reference build <file or url> --key <field> --measure <field> --label <field> --out dataset.json, gamestage reference check dataset.json <keys> with the keys
the round will use, and gamestage reference push <name> dataset.json. Write a
round's entry keys from what inspect printed, never from memory of a player's
name: a key the dataset does not hold is left out of its group, so that player
is never offered. A key for their
API goes in --header, typed by them in their own terminal, never pasted into a
chat.
gamestage reference list shows what the workspace already holds and which
games read it, and reference status <name> shows one dataset's measures,
the games that read it and the rounds built from it. Once the developer has connected a
source, reference run <name> pulls its dataset now and prints the entries,
measures and first keys that landed, so you can write entry keys from it
without waiting for the schedule. It never prints a value, and a dataset can
be pulled this way once every 15 minutes.
reference download <name> gives back a file they uploaded. Run reference delete only when they ask you to remove a named dataset, and let them confirm
it.
Say the licence position plainly, in the words the list uses. A source they license is their terms, not ours.
An unofficial source is for prototyping only. When you suggest one, such as Fantasy Premier League, tell the developer this, word for word, before they build on it:
Requests to this source are made on behalf of you, the game builder. You are responsible for the data you consume, and for securing the legal rights and licence to use it. We recommend using it for testing only, and not launching with it unless you have explicit permission from the data owner.
Recommend it for a prototype or a test, and recommend a licensed source or
their own data before they launch. verify, deploy and promote will say
the same thing again; it is a warning, and nothing is blocked.
Design around what the source actually has. A source offers some measures
and not others: Fantasy Premier League has points and prices and no wages. Pick
the game's measure from what gamestage sources printed, and if the idea
needs a figure no source has, say so before building rather than inventing it.
Never ask for, accept or type an access key. Not in the chat, not in a
file, not as a command argument. A source that needs a key is connected with
gamestage sources connect <id>, which prints a link to the Data area in
Stage, where the developer pastes the key themselves and can later replace or
disconnect it. Give them that link, wait until they
tell you it says "Connected", then run gamestage sources again to see it. If
they paste a key into the chat anyway, tell them to revoke it with the provider
and connect a new one through the page.
There is one other route and it is not yours: gamestage sources connect <id> --from-op <op://...> reads the key from the developer's own 1Password at their
own terminal. Never run it, and never write or suggest the op:// reference
for them. It exists for a person away from a browser, and 1Password asking
that person to approve the read is the protection. Recommend the page; mention
this only if they say they cannot use one, and then leave it to them.
Never hand over a URL you have not fetched
Fetch it, read what came back, and only then put it in front of a person. One line of curl, every time:
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4000
gamestage dev prints its address as API, and that is what it is: the player
API the page talks to, not the page. Opening it in a browser gives a fan
{"error":{"code":"not_found"}}, which is the correct answer to the wrong
question. The three window.GAMESTAGE_* lines beside it are what a page needs;
the page itself is served by whatever the developer already runs.
A port that was taken is a step that did not happen. If the server you meant to start could not bind, say so and pick another, then fetch the new one. Do not report a different port's address as the thing to look at, and never write "see it here" against a URL you have not just proved answers. An address that returns JSON to somebody expecting a game is worse than saying the server did not start.
Where the account sits in the journey
A human registers, and gets approved before you can publish. Registering is their job and it takes a browser, so it is never yours to do. But do not assume it has happened: plenty of people install the tool and point an agent at a game before they have an account, which is the right way round, because most of the work needs nobody. You may meet registration in the middle and approval at the end, and both are a sentence to the developer rather than a stop.
human 1 install the tool and this pack npx skills add, or the installer
human 2 register, if they have not gamestage login may come later
─────────── from here the work is yours ───────────────────────────────────────────
agent 3 orient gamestage start no account
agent 4 inspect the prototype gamestage inspect . no account
agent 5 decide what must move your reasoning no account
if the game is scored against numbers a fan must not see:
agent 5a switch on FPL or ESPN gamestage sources connect fpl approved account
or, for their own file:
agent 5b see what their data holds gamestage reference inspect no account
agent 5c build the dataset from it gamestage reference build no account
agent 5d prove the round's keys exist gamestage reference check no account
agent 5e upload their own data gamestage reference push approved account
human 5f connect a source with their key gamestage sources connect approved account, their key
agent 6 write the round practice/round.yaml no account
agent 7 rewrite the page edit the html and js no account
agent 8 run it gamestage dev signed in
agent 9 prove it gamestage verify signed in
agent 10 repair on failure your reasoning
agent 11 publish gamestage deploy approved account
agent 12 confirm a fan can play a real browser
human 13 operate the live game Monterosa Studio
Steps 3 to 7 need no account, apart from 5a, 5e and 5f, so get on with them. Do not stop partway through a migration to ask whether the developer has signed in for these. Orient, inspect, work out what must move, write the round and rewrite the page. That is most of the work and none of it touches our backend.
Steps 5a to 5f are for a game scored against hidden numbers: prices,
career totals, wages, anything the fan picks between without seeing. When the
game is about Premier League players or ESPN's leagues, 5a is the whole of it:
switch the source on and skip 5b to 5e. Building your own copy of FPL or ESPN
is the wrong route, because it never refreshes. For their own file, inspect,
build and check run on this machine, so build the dataset and write the
round's entry keys from it before anybody is approved, and 5e can wait until
step 11. 5f is the developer's, because it takes their supplier key. When the
developer has no data of their own, run gamestage sources first: "Ask what
data the game needs" above says which source to offer. sources needs an
approved account too, so before approval say so.
Only push and hunt can use a dataset today. A push game must name one: its values are what a fan's picks add up to. A hunt round uses one when its Answer from data field names a measure, and the right answer is then worked out from the dataset rather than typed. Group and predict cannot read a dataset yet, so never build either against one: the round would provision with nothing reading the data.
You already know whether they are registered, so do not ask. start
reports it, in account and first_reply, read from this machine's token file
with no network call:
"account": { "signed_in": false, "email": null, "sign_in": "npx gamestage@latest login" }
Tell them, in the one line your first reply opens with (see "Your first reply" at the top), and then act on it:
- Signed in. Name the address, so a wrong account is caught now rather than at a refusal. Then run the journey. The only thing left to meet is approval, at step 11, and the refusal there says so.
- Not signed in. Say so, give
login, which creates the account too, and say you can carry on without it for now. Do not wait for them to sign in: do steps 4 to 7. When you reachdev, remind them once, in a line, that running it needs the account, and carry on when they say it is done.
This said "say nothing about accounts until dev" until 2026-09-29. Tom
changed it: a new creator could not tell whether they were bound to an
account at all, and a line at the start costs nothing if it does not block.
Steps 8 and 9 need a signed-in account, and play on the deployed Engine.
dev puts the practice round on the same Engine a fan will play, under a
practice name of its own, and serves the page through a small proxy on
localhost; verify marks a play with it. Nothing reaches fans, Studio or
the game's leaderboard. Neither needs the account approved, only signed in:
gamestage login registers and signs in in one step, so if the developer has
never run it, that is the whole ask. If dev or verify refuses with "You
are not signed in", that is the entire fix; nothing about the migration itself
is wrong.
Before approval an account can register three games and play each practice
round up to 100 times a day. If create or manifest register refuses
because the account already has three games, run gamestage status --json:
its games lists the ones registered and gameLimit says how many of the three
are used. Tell the developer which they could archive, or to wait for approval;
do not delete anything to make room.
Step 11 is the first one that needs an approved account. deploy is the
moment the game becomes something a fan can reach, and that is ours to allow.
An unapproved account is handed back rather than worked around.
Let the tool tell you which side of the line you are on. Run the command. If it works, keep going. If it refuses for want of an approved account, the refusal names the account state and the next move; read it and hand over.
What to say to the human at a refusal
Stop, and say these four things in a couple of lines:
- which command was refused, and the account state it reported;
- that the migration up to this point is done and their files are edited;
- what they do next:
gamestage loginif they have never registered, or wait for approval and rerun if they are pending; - that you will pick the run back up from that command when they tell you the account is approved.
Then stop. Do not poll, and do not start unrelated work to fill the time.
A refusal is a hand-over, never an obstacle
Four things you must not do, in the order you are most likely to be tempted:
- Never put the answers back in the page. Not to see the game work, not temporarily, not behind a flag. A page a fan can read the answers out of is the exact thing this product exists to remove, and it is worse than an unfinished migration.
- Never invent a local runtime. No stub Engine, no mock server, no fixture that returns "correct", no rewriting the client to score in the browser. A game proved against something we did not build is not proved.
- Never edit the manifest to make
verifypass. Removing a check, weakening a rule or renaming a field to dodge a refusal makes the report lie, and the report is the only evidence anybody has. - Never report a step you did not complete. Say plainly which steps ran and which are blocked. "Blocked at step 11, waiting on approval" is a good outcome. A green summary over a blocked run is not.
Rules the output cannot teach you
Answers never reach the client. Not in the HTML, not in a bundle, not in a
JSON file next to the game. If a player can download it, treat it as public.
Take the answers out of the page; do not move them into gamestage.yaml
either, because a manifest describes the game and carries no content.
Where the round lives. A game's rounds are written in Monterosa Studio, where
whoever runs the game changes them without a deploy, and the Engine reads them
from there. On this machine the one round is practice/round.yaml, beside
gamestage.yaml: create writes a starter one, dev, verify and review
play it on the deployed Engine as test plays that reach no leaderboard, and
deploy never uploads the practice/ folder. Those three need a network
connection. If they say they cannot reach the Engine, that is an outage or no
network, not a fault in the game: tell the human, and never build a local
Engine or edit the manifest to get past it. With no practice
file they play a stand-in round of the game's format. Each names its round in
one line, "Round: practice/round.yaml (practice only, fans never see it)"
or "Round: stand-in round". gamestage round push <game> copies the practice
round into Studio, into the game's own round. gamestage round seed <game>
writes rounds from the game's dataset: one a day on a one-round-a-day game,
starting with today's if it is empty.
A manifest carrying 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 the file.
A first deploy with no round in Studio is expected: it says "No round yet: add one in Studio" and prints the link, so tell the person that rather than calling the game live. Once there is one it says "Round: Studio, edition <name>".
Put tomorrow's round in tomorrow's edition, never as a draft inside today's. The Engine serves no round before its edition opens, so a future edition is the way to prepare a round without fans seeing it.
Never invent a player id. An id a page picks for itself is one anybody can send on someone else's behalf. Anonymous play is supported and the Engine issues a signed session for it. Where a game needs identified players, it names its own issuer and JWKS in the manifest and the Engine validates the token the creator's own login system already gives them. Gamestage ships no identity provider at any plan.
That identified-player route is proved by the shared validator. On a deployed game it needs the issuer and keys configured on that deployment, which Monterosa sets: do not tell a developer identified play works on their deployment unless you know that has been configured.
verify is the arbiter. Your own reading of the code is not. When a browser
is available it makes a real play. A status code, a green build and a page that
looks right can all hide a broken game. Exit code 0 means every check was
verified, 1 means a check is open, and 2 means the result could not be
fully proved. A skipped browser check is not browser proof.
Two of its checks are worth knowing before you write the page. verify
takes the browser's network away and asks whether anything on the screen
changed, in both directions, so the reconnection handling below is a check
rather than advice: a page that says nothing when a fan loses their signal is
refused, and so is one that says something and never takes it back. And a game
whose manifest carries no round is checked against a stand-in Gamestage
supplies, which proves the wiring and nothing about the game, so that run ends
at 2 rather than at "done".
Do not weaken a refusal to get past it. Starter refusing a second live game, an invalid manifest, a rejected play: these are the product working. Read the reason, which is written to be acted on, and change the cause.
A dataset key the data does not hold is left out of its group, and the page
never computes a score. The player is never offered, and if that leaves a
group with no real choice the round is refused. Never scored as zero. Write
entry keys from what gamestage reference inspect or reference check
printed, never from memory, and check them before the round goes to Studio. The page shows the total the Engine returns: adding up
the values itself would need every value, and every value is the answer.
Ask where the game runs, and make it load smoothly and fast
Ask this with the format, before you scaffold. Where a game is opened and how it sits on the screen change how it is built, and they are expensive to change later. Ask the developer where fans will open it, and show them the choices:
| Where it runs | --host | What they get by default |
|---|---|---|
| Full screen, from a carousel, a Hub or a link | fullscreen | a screen game that fills the phone |
| A card in an article that opens full screen | article-launch | launch |
| A box inside an article | article-embed | card |
| Inside their own native app, in a web view | app-webview | a screen game that fills the phone |
Then pass it: gamestage create --name "…" --format hunt --host app-webview.
gamestage deploy minifies the game's own scripts, styles and pages and
removes their comments on the way up, names unchanged, so write readable,
commented source and never minify it by hand. --no-minify publishes the files
as written, for debugging a deployed game. deploy_game publishes them as
written for now.
Add --layout only if they want other than the default.
Recommend full screen, and say why in plain words: players come back to a
game they can play properly; a widget in an article reads as throwaway and gets
scrolled past. For an article, recommend launch over card, and use card
only when their host cannot open a game full screen. create prints the same
advice, and docs/layout-and-loading is the chapter to point them at.
Build for the layout you chose. A screen game fits 360×640, 390×844 and
landscape without the page scrolling; if a list must scroll, it scrolls inside
the game. verify measures this and warns.
A game that needs the phone held sideways says so. Most fans hold a phone upright and do not turn it unless asked. Prefer a design that plays upright. When the play area is wider than it is tall (an artillery or worms game, a side-scroller, a racing track, a pitch seen from the side), do all of these:
- Ask before you build it whether it must be landscape, and say what an upright fan will see.
- Show a "turn your phone sideways" screen when the phone is upright:
full screen, a rotating-phone picture, one short line, and nothing to tap.
Detect it with
matchMedia("(orientation: portrait)")and listen for the change, so the screen goes the moment the phone turns. Do not rely onscreen.orientation.lock(): iPhones refuse it, and Android allows it only in full screen. The line is a Studio setting like every other word, ingamestage.settings.json, never written into the page. - Pause while it shows. A turn timer, a clock or a run must not count down behind it, and a fan who turns back finds the game where they left it.
- Never shrink a landscape game into an upright screen. A wide play area drawn across the middle of an upright phone, with black above and below, is the failure this rule exists for. Its text ends up too small to read and the targets too small to hit.
- Keep text readable at 640×360, the smallest landscape phone: at least 12px for anything a fan reads, including names, health bars and the turn clock, and 44px for anything they tap.
- Check both ways round before calling it done: upright at 390×844, where the sideways screen shows and the game is paused, then landscape at 844×390 and 640×360, where it plays with every word readable.
Learned on 14 October from an Arcade game that, upright on a phone, drew the match as a thin strip with unreadable text and no hint to turn the phone.
Load smoothly. Do this without being asked:
- The game's colour from the first frame. In the head, before any script:
<meta name="color-scheme">,<meta name="theme-color">with the background colour, and a<style>paintinghtml, bodyin it. Inside a native app this is the difference between the game appearing and a white flash first. - A loading state, never text. A centred spinner, or a bar when progress is
known, in a box the game's size, so the game replaces it in one step. Never
"Loading…" on its own. Scaffolds from
createdo both of these already; keep them. With Gamestage UI, useLoading. - Say when it is playable. When the round is drawn or has failed, call
window.gamestageReady()(scaffolds define it), orperformance.mark("gamestage:playable")if your page does not have it. - Keep clear of the notch and the home bar. Add
viewport-fit=coverto the viewport meta and pad the edges withenv(safe-area-inset-top)and its right, bottom and left siblings. A landscape game on an iPhone otherwise puts its score under the camera and its buttons under the home bar. - Reserve the space for anything that arrives late. A player photo or
badge gets a fixed
width,heightoraspect-ratioand a background in the game's colour while it loads, so nothing on screen jumps when it lands. A list that loads after the round, such as the leaderboard, shows grey placeholder rows the shape of the real ones, not a spinner. Once a list has loaded, show it while it refreshes rather than blanking it. - Back closes what is open before it leaves the game. On Android, and in
most apps' web views, the back button leaves the page. When a sheet or
dialog opens, push a history entry, and on
popstateclose it, so back takes the fan out of How to play rather than out of the game.
Every scaffold from create opens on an intro screen: a full-screen
gradient, the game's name in its own font, a progress bar, then a Play button.
You do not build this; call gamestageReady() correctly and it appears. Pass
{ resume: true } when the fan has a round in progress (button reads
"Continue") and { failed: true } when the game could not load (shows the
error state and a retry button). Wait for window.gamestageStart or the
gamestage:start event before opening anything that asks the fan something,
such as How to play: the tap on Play is what unlocks sound and starts the
game. A layout: card game has no intro and no Play: it shows a small
progress bar, starts as soon as gamestageReady() is called (so
gamestageStart resolves without a tap), and unlocks sound on the fan's first
touch inside the box. Its colours and words are the game's Brand and Wording settings in
Studio (title_font, logo_text, splash_gradient_start and the rest); see
docs/layout-and-loading for the full list.
Load fast. verify loads the game on a mid-range phone over 4G and warns
when it goes over its layout's budget: for a screen game, 350 KB of
JavaScript, 150 KB of fonts, 900 KB in all, something on screen within 1.8
seconds and playable within 3.5. Keep fonts to one family in two weights,
install only the Gamestage UI components the game draws, and size images for a
phone. When verify warns, fix what it names before you call the game done.
Never hang a logo on a webfont. A logo is the first thing a player sees, and a font server is the thing most likely to be slow or blocked in the browser a chat app opens. Set the logo in Studio's title and logo settings and let the intro screen draw it: a deploy writes that font into the page, cut down to the letters a logo uses, so it paints with the first frame. If your page draws its own logo, make it one of these, never text in a font fetched from another origin:
- an inline SVG, when the artwork is fixed. To animate the game's own
logo, or make a loader or busy indicator from it, use the plugin's
logo-animateskill: it keeps the logo as it is and builds the font in; - text in a font served from the game's own files, subset to the logo's
characters and preloaded with
<link rel="preload" as="font" crossorigin>; - text that shows a close system font after 800ms at most.
A blank space where the logo should be is the one outcome that is always wrong, worse than a fallback face.
Set every size on the one type scale: 14, 17, 20, 28 and 40. A screen
uses at most those five sizes, one typeface for all its text with tabular
figures for numbers, plus the game's own logo face, and two weights, 400 and
600. Gamestage UI's roles already sit on it; in the game's own stylesheet read
var(--gs-type-scale-step1) to var(--gs-type-scale-step5) rather than a
number, and never a size under 14px. 14 is for labels and chrome; anything a
fan reads as a sentence, a name or a button is 17 or more. Headings are
sentence case ("Pick your name"), not capitals, and set text-wrap: balance
so no heading ends on one word; body text takes text-wrap: pretty. A field
for a code a fan receives by text message is inputmode="numeric" with
autocomplete="one-time-code", so the phone offers the code above the
keyboard. A game that grew a size for
each screen ends up with sixteen of them and reads as three different games.
Serve every font from the game's own files, never from Google Fonts or a
CDN. A <link> or @import to fonts.googleapis.com, Adobe Fonts or a
public CDN loads before the consent banner can ask anything, so it hands that
company the player's IP address with no way to ask first, and a German court
has fined a site for exactly that. Download the .woff2 files into the game
(Google Fonts are under the SIL Open Font License, which allows it), write
@font-face rules that point at them, and remove the remote link. A Google
font from this list is also available ready-made at
https://gamestage.ai/fonts/<family>.css, for example
https://gamestage.ai/fonts/bebas-neue.css: abril-fatface, anton,
archivo-black, archivo-narrow, barlow-condensed, bebas-neue, bungee,
chakra-petch, dm-sans, dm-serif-display, figtree, fraunces, oswald,
playfair-display, russo-one, space-grotesk, teko and unbounded. Any other
family answers 404, so download its .woff2 files into the game. verify fails a page
that loads a font from a third party (fonts-self-hosted), and deploy
refuses it.
Give the game a strapline so a pasted link looks like the game. Slack,
WhatsApp and iMessage read the page's Open Graph and Twitter tags without
running any script. deploy writes them from display_name and strapline
in gamestage.settings.json, and draws a centred 1200x630 share-card.png
from the intro screen's colours. Tags you write yourself are kept, so only
write them if you want something different, and then write the whole set with
absolute https image addresses and twitter:card set to
summary_large_image. Keep anything that matters in the middle 600px of your
own card: Slack often shows a small square cut from the middle. verify fails
a game whose published page would lack a tag or carry a relative image
(share-tags).
For a native app, tell the developer what their app team must do, because it is in the app rather than the page: set the web view's background to the game's background colour, and create the web view before the player taps.
Give anonymous players a way back to their progress
Any game whose players are anonymous gets recovery, on a Profile screen or the page's menu. Without it a fan who clears their browser or changes phone loses their name, scores, streak and achievements, and nothing can bring them back.
Two halves, and include both:
- "Keep your progress":
game.client.issueRecoveryCode()returns a code, four words and two digits. Show it once, large, with Copy and Share, and tell the fan to keep it private. - "I've played before": take the saved code in a text field (a word
keyboard, not a number pad; case and spaces don't matter) and call
game.client.restoreFromRecoveryCode(code). A refusal throwscode_not_recognised: say plainly that the code isn't recognised.
In a plain page, mountRecovery(game, element) from the client draws both as a
dialog in one line. In a Gamestage UI game, npx gamestage-ui add recovery-code
draws the same two screens. Every word is a Studio setting; put them in
gamestage.settings.json.
Tell the developer the three limits, because each changes what the screen should say: it is for anonymous players only; restoring does not merge the progress the device already had; and a code is effectively a password.
Build the loading state and the reconnection handling
Not optional. A game that paints a playable board before it is connected is a game that lies to a fan, and one that never notices the connection dropping lies for the rest of the session. Both have happened.
start() is asynchronous: it resolves identity, reads the round and connects to
Interaction Cloud. Until it resolves your page knows nothing, so it must not
draw a board that looks ready.
// Before start(): the page shows its loading state and nothing playable.
showLoading();
const game = await start({ identity: () => window.GAMESTAGE_TOKEN });
// After start(): the board is real, so it can be drawn and touched.
render(game.round);
hideLoading();
// Playable now: removes a scaffold's loading shell and marks the moment
// verify times load by.
window.gamestageReady?.();
Then check what you are connected to. game.platform is monterosa on a
deployed game and local under gamestage dev. A deployed page that resolves
to local is not connected: it will never receive a producer's change and will
poll on a timer instead. Say so rather than playing on.
// The addresses a game is played from while it is being built.
const developing =
location.protocol === "file:" ||
["localhost", "127.0.0.1", "[::1]", "::1", ""].includes(location.hostname);
if (game.platform === "local" && !developing) {
showDisconnected(); // your own words; the game is not live
}
That case is not hypothetical. Every game deployed before 2026-08-14 was in it: playing correctly, polling every few seconds, connected to nothing, with no error anywhere and a page that returned 200 to every check we had.
Handle the connection coming and going. The SDK reconnects by itself when the tab is brought forward or the device comes back online, and it exposes no event for it, so the browser's own signals are what you have. A fan on a train loses the connection and gets it back, and the round may have moved while they were gone.
addEventListener("offline", () => showOffline());
addEventListener("online", async () => {
showReconnecting();
// The fan's progress is on the Engine, so re-read it rather than trusting
// what is on screen, and never start them again. A round that moved while
// they were away arrives through `onRoundChanged`, which the client re-reads
// from the Engine for you.
renderState(await game.client.getRoundState(game.round.id));
hideReconnecting();
});
verify drives both of those: it takes the browser's network away and asks
whether the screen changed, then gives it back and asks again. Showing something
on offline and never taking it down replaces a silent failure with a permanent
one, and is refused for the same reason.
Three rules for what you draw:
- Never a playable board before
start()resolves. A tap on a board that is not connected is a tap the Engine never sees. - Never a silent failure. A fan who cannot connect should be told, and a disconnected deployed game is a fault rather than a mode.
- Never lose their progress on a reconnect. The Engine holds the play; the page re-reads it rather than starting the fan again.
Load the client in a React or Vite app
Load the client outside the bundle, so the deploy can point it at the hosted client pinned for the game. Bundled, it is a hashed copy of whatever version was on the laptop, and the deploy cannot move it.
gamestage client --out public # public/gamestage.js, copied into dist by the build
<!-- index.html, in <head>: a plain script, which Vite leaves alone -->
<script>
window.gamestageClient = import(new URL("gamestage.js", document.baseURI).href);
</script>
// 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
}
Set base: "./" in vite.config.js, because a deployed game is served under
/games/<game id>/. Never import ... from "./gamestage.js" in a bundled
file, and never name the promise gamestageReady, which the client uses. An
error with handled: true means the client is already showing its own screen:
render nothing of yours for it. The quiz calls and the rest:
https://gamestage.ai/docs/migration.md, "Port a React or Vite app".
Wire the producer's settings while you wire the client
You do not need a copy of the client to deploy. A page imports
./gamestage.js, and every deploy, by the CLI or deploy_game, points that
import at the hosted Gamestage client pinned for the game. A deployed game's
own address answers 403 for gamestage.js, so do not fetch it from there.
No copy is ever hard coded, and that includes labels. This is a hard rule and nothing launches without it. Not the round's words, not a button's label, not a heading, an empty state, an error a fan reads or the name of the game. Every word a fan sees is a producer's to change, which means it arrives at runtime and the page renders what it is given.
The game's words and colours start in Studio, not in the page. Put the
values a fan sees by default (the game's name, its how-to-play text, its button
labels, its colours) in gamestage.settings.json beside gamestage.yaml, keyed
by the Studio field keys:
{
"display_name": "Wages",
"how_to_play": "Pick one player from each line. Stay under £1,000,000 a week.",
"play_button_label": "Select Player",
"primary_colour": "#1D428A",
"css_variables_backgroundMainColour": "#0B1620"
}
A deploy writes each value into the game's Studio project where that field is
empty, so a producer opening Studio sees exactly what a fan sees and edits it
there, and their edit is never overwritten by a later deploy. gamestage create
writes this file for you from the scaffold's own page. manifest validate and
deploy refuse a key Studio does not have and name the ones it does.
Put no copy of any of these in the page. Not a heading's text, not a
button's word, not a fallback colour inside var(--gs-…, #hex). Leave the
element empty and let applyPresentation fill it from game.presentation.
Studio is the only home of a game's words and colours:
- A returning fan gets the settings their device remembered from the last visit at once, while Studio answers behind the page (with the fan's "functional" consent).
- A first visit with Studio unreachable gets the library's own "Can't load
the game right now" screen with a Try again button.
start()then throwsGamestageUnavailableErrorwithhandled: true: stop your start-up and show nothing of your own. gamestage dev --servefeedsgamestage.settings.jsonto the page as Studio would, so a local page renders the same words.
A copy in the page is a second home that drifts: a producer edits a word in
Studio and a fan still reads the old one first. gamestage verify fails a page
that keeps one (settings-seeded), and gamestage deploy refuses it before
uploading, naming each setting and the file it is in. Both read the source as written, so
never split a string to get past the check: the fix is to read the word from
Studio. A colour counts only as a
literal fallback on the setting's own variable, as in
var(--gs-highlightMainColour, #fff); a variable behind it, as in
var(--gs-highlightMainColour, var(--gamestage-primary)), is fine. Until 2026-09-27 a copy was
allowed as a safety net if it equalled the file. Tom removed that the same day.
A customer's first request is always to change the wording. A game that needs an engineer for that is a game we run rather than one they run.
A producer can change seven things about a game from Monterosa Studio: its name,
a strapline, the how-to-play text, the word on the main button, a primary
colour, and per edition a name and a line. They arrive on the object start()
returns, and applyPresentation puts them on the elements the page nominates.
Do it in the same edit that wires the Gamestage client, because nothing later
will tell you it is missing. verify proves that solution material is gone,
that a client is imported and that an outcome is rendered; a game that ignores
every setting passes all three.
From the reference game:
import { applyPresentation, start } from "./gamestage.js";
const game = await start();
applyPresentation(game.presentation, {
displayName: el("game-name"),
strapline: el("strapline"),
playButtonLabel: el("submit"),
});
The other target keys are howToPlay, editionName, editionStrapline and
root, which is where --gamestage-primary is set and defaults to the document
element. The colour reaches a fan only where the game's CSS reads it:
background: var(--gamestage-primary, var(--red)) keeps the game's own colour
until a producer chooses one. An element the page draws empty can ship with
hidden, and a filled field un-hides it.
A producer's save reaches an open page. Studio announces a settings change over the same connection that carries a round change, so hold the targets in a variable and apply them again:
game.onPresentationChanged((presentation) => {
applyPresentation(presentation, presentationTargets);
});
Without it a fan with the game open keeps the old words until they reload, which
on a phone left on a game screen is until the round is over. Applying twice is
safe. It never fires under gamestage dev, where there is no producer.
Absence is not emptiness. Call applyPresentation rather than reading
game.presentation.displayName yourself and assigning it with ?? "". A field
nobody has filled in is missing rather than empty, and a page that treats the two
alike blanks its own heading the first time a producer saves the form without
typing anything.
Under gamestage dev --serve there is no producer, so the page is given
gamestage.settings.json in Studio's place and shows those words. That is the
correct result and the wire is fine. These settings reach a fan only on a game provisioned into
Interaction Cloud, which is above the Starter plan.
A game may hold more than one round, and a fan can be sent to the next
A game is not one board for ever. The Engine holds a pool and rounds/current
answers with the one the game considers live, so a fan who finishes today's
round can be offered one they have not played rather than left on a spent
board.
const next = await player.getNextRound();
if (next.status === "ready") show(next.round);
Read status rather than testing whether round is there. A response that
simply omitted the round when the pool was empty would look identical to one
that failed to include it, and every client would have to guess whether to draw
an empty state or an error. ready and exhausted say which, and the Engine
answers 200 either way.
So draw Play next on ready, and on exhausted draw the same button greyed
and disabled, reading "Come back tomorrow" (from Studio). Decide it before the
button renders, so a fan never taps and gets refused. A button offering another
round that then cannot produce one is worse than either.
The Engine picks: a round this player has never opened before one they left half done, never one they finished, and never one that has stopped accepting plays. You do not order the pool yourself.
rounds lists the pool as summaries carrying no challenge and no solution, and
rounds/mine says which this player has played and which they finished. Most
games need neither: rounds/next is the whole feature for a Play Another
button.
Ask how the game runs over time: always on, editions or live
Ask this once the format is chosen, because it decides how many editions a producer makes in Studio and which board a fan lands on. Offer three answers:
| Type | What a fan meets |
|---|---|
| Always on | One game that never goes dark, with one board for its whole life |
| Edition | A new edition each day, week or fixture; the page plays the current one, with a board per edition |
| Live | Questions pushed one at a time during a show or a match, each closing after a few seconds |
Not every type works for every format yet. Read the format's section of the game formats doc for what works today, and tell the person plainly when the type they pick does not: for a quiz today, only Edition works.
Reveal a prediction's answer from the terminal. On a predict game,
"reveal", "the result is in", "settle it", "full time" or "Arsenal won" all
mean: run gamestage round reveal <game> to list the questions and their
options, confirm the right option with the person, then run
gamestage round reveal <game> --question <id> --option <n>. It reveals one
question per run; fans' result for the round waits until every question has
an answer. Running it again with another option corrects the answer: fans are
re-scored and anyone signed up for results gets a correction email, so it
suits a test loop. After deploying a predict game, end with one line: "When the
match is over, ask me to reveal the answer."
Reveal automatically from a real match, for development only. When they
want answers revealed by themselves after the match, run gamestage fixtures
to see which sports and leagues can be revealed and say which are not, then
gamestage fixtures --league <sport/league> --date <day> --team <name> for the
match id, and gamestage round auto-reveal <game> --fixture <id>. It sets the
match and each question's rule; tell them any question it left and why. Say
this to them every time, before setting it up: "Automatic reveals use ESPN's
public data. They are not suitable for production and are for development
only." For a real game, they reveal by hand or a producer uses Studio.
Tell them what to expect, so a short wait does not read as broken:
- The answer appears about one to two minutes after ESPN marks the match finished. We read a live match once a minute and wait for a second reading that agrees. ESPN's own delay after the whistle comes on top and varies.
- Football is settled on the 90 minutes, so extra time and penalties do not change the answer. Other sports count overtime, and ESPN's winner settles a tie.
- A postponed, cancelled or abandoned match voids the question, and fans' picks are returned.
- To reveal sooner, or to correct it, use
gamestage round reveal. An answer set by hand is kept: the automatic reveal does not overwrite it. - "ESPN has not been checked yet" means our servers have not finished their first check of ESPN's leagues. Wait, then try again within the hour.
Design a game fans come back to
The rules the most successful daily games share, from Wordle and Connections to Candy Crush and Duolingo, as things you check before deploying. The reasons and sources are in the Game design chapter (https://gamestage.ai/docs/game-design).
- A fan reaches their first answer within 30 seconds, in 3 taps or fewer. The round is on the first screen. How to play is a button, never a gate.
- One main action per screen. After a round it is Play next: filled, full width, the loudest thing on the screen. "Come back tomorrow" greyed in the same place when the pool is empty. Share result and See the story sit beneath it, quieter.
- Reveal the answer after every round. The story, if any, is 1 to 3 slides (the answer, the closest miss, one fact) and opens only when the fan taps it. Revealing the moment a fan finishes is right for a puzzle whose answer is known in advance and is the same for everyone (hunt, push): delaying it spoils the game and protects little, because once anyone solves a shared puzzle the answer spreads anyway. Bingo and predict have nothing to reveal early, because their answer does not exist until the real event happens.
- Design the scoring so ties are rare. Score by closeness, fewer guesses or speed rather than pass or fail, and let the leaderboard rank the week's total.
- Give fans a reason to come back. A round a day or per fixture, the same for everyone. A streak shown from two, forgiving a day with no match.
- Mix easy and hard, and give a pick-one quiz six options, not four.
- Share without spoiling. The share card shows the score and how the fan got there, never the answer.
- Nothing manipulative. No lives or energy that stop play, no offers at the moment of failure, no paid random rewards, no guilt notifications. Many fans are children and the rights holder carries the reputation.
Ask the creator: "Will this game carry a prize?" If it will, the leaderboard is worth cheating, and sessions are free: a fan can use a spare one to see the answer and then score perfectly on another. So a prize game takes entries only from signed-in fans, counts each account's first play of a round, and its producer watches for perfect first-try plays from brand-new sessions. Say this to the creator before they announce a prize, not after.
Run gamestage review before gamestage deploy. It plays the built game
against a real Engine and reports advice against these rules, each with a fix.
It never fails a deploy: read its advice, fix what you agree with, and tell the
human what you left and why.
Name the four moments worth measuring, and nothing else
Analytics needs no work from you. On the Publisher and Enterprise plans,
once the workspace's Signal switch is on, Monterosa Analytics captures a fan's
activity without a single line in the game: clicks, views and submissions are
trapped from the page itself and translated, so a game that never calls
anything still reports. The switch is on Stage's Analytics page, or gamestage workspace signal on, and a paid
plan leaves it off until somebody turns it on. It is not part of Starter. There
is nothing to switch on in the game. Do not add a tracking library, and do not ask the human for an
analytics account.
What that gives them is activity. What it cannot give them is meaning. A trapped click knows a button was pressed and its label; it does not know the fan went over the limit, or ran out of guesses on the last one, or came back a second day and finished. Those are the questions a creator actually asks, and they are the ones only the game can answer.
So name a few. Four is usually the whole list, and more is worse:
game.track("round_started", { round: round.number });
game.track("round_finished", { outcome: result.outcome, score: result.score });
game.track("attempt_spent", { remaining: state.attempts_allowed - state.attempts_used });
game.track("gave_up", { at: state.progress });
Name the moment, not the mechanism. round_finished with an outcome
survives you rewriting the board; clicked_submit_button_v2 does not, and a
creator reading a chart six months later cannot tell what it meant. The name is
the thing a person would say out loud about their own game.
Never put a solution in a property. A tracked event leaves the browser and
goes to a third party. { answer: "jokic" } in an event is the same leak as
{ answer: "jokic" } in the page, and everything else this pack says about
keeping solutions server-side applies here unchanged. Send the outcome, never
the thing that decided it.
Do not gate it on consent yourself. The client holds one consent gate in front of every destination, fed by the consent banner described below, and an event refused by it is refused everywhere at once. A second check in the game is a second thing to get wrong, and a game that withheld its own events would report less than the fan agreed to.
If the human asks for PostHog or Google Analytics, those are switches on their Analytics screen rather than code you write: the same captured stream is routed to them, so turning one on needs no change to the game and no redeploy. Say so rather than writing an integration.
Every game asks for consent before it records anything
A game must ask a fan before anything records them, and deploy refuses a
game that does not. The Gamestage client asks for you: it draws a consent
card with Accept, Reject, Manage preferences and a × the moment the page
connects, whenever nobody has answered yet, in the game's own colours and
type, floating clear of the game's pill nav and pinned main button. The game stays playable underneath it. Leave it on. You write no consent
code.
Ask the human two things before the first deploy, and put both in
gamestage.settings.json: the brand the banner names as asking
(consent_brand_name, e.g. "Arsenal"), and the address of their privacy
policy (privacy_policy_url, https). verify fails and deploy refuses
while either is empty. Never invent either one. Monterosa's name and a
monterosa.co privacy policy belong only to Monterosa's own games, and verify
and deploy refuse them on any other.
const game = await gamestage.start({
consentBanner: { settingsIn: document.querySelector("footer") },
});
settingsIn puts the "Privacy settings" button where a fan will find it, such
as the Profile screen or beside a bottom nav. Without it the banner pins a
small pill in the bottom corner of the screen, so every game has a way back to
the choices. Pass it in a game with a bottom nav, where the corner is taken.
In a Gamestage UI game, use the consent component and pass
consentBanner: false, because the component draws the same banner itself.
The fan's answer is one object, game.consent.record(): the categories
necessary, analytics, marketing and functional, who decided (host,
fan or default), when, and the producer's policy version. Every gate in the
client reads it: analytics, storage and Monterosa Analytics all wait for a yes.
An app that embeds the game has usually asked already, and the game then
never asks again. A Monterosa SDK host calls setConsentState from
@monterosa/sdk-consent-kit in its own page and the answer reaches the game.
A host without the SDK posts it into the frame:
frame.contentWindow.postMessage(
{ type: "gamestage:consent", categories: { analytics: true, marketing: false, functional: true } },
new URL(frame.src).origin,
);
The host's answer always beats the game's banner.
The words are the producer's, in Studio under Wording (consent_title,
consent_accept_label and the rest), and consent_policy_version asks every
fan again when the privacy policy changes. Do not hard code them.
Never turn the banner off and ask nobody. gamestage verify loads the game
as a new fan and fails it if analytics leaves the page before the fan answers,
if no consent control appears, or if anything is sent after they say no.
gamestage deploy runs the same check before it publishes a single file.
Offer partner products once, at the first deploy
Ask the human once per game, in the message where you ask whether to ship it for the first time: do they want partner products on the result screen, subject to approval and commercial terms? Say it in those words. Products are in preview: Monterosa and the retail partner must approve each game, and use is subject to commercial terms agreed with Monterosa. Never promise them money, a share of sales or a commission: none is agreed, and Ads says so.
Before asking, run gamestage --json ads status <game>. If asked is true,
the game already has a request or a recorded no, so do not ask again. A game
that is not registered yet answers "No game with id", which means nobody has
asked.
-
Yes. Ask for the four facts Monterosa and the retail partner need, then run the request straight after the first deploy succeeds, because the game has to exist in their workspace first:
gamestage ads request <game> --audience "Club fans in the UK, mostly adults" \ --where "the club app and website" --countries "United Kingdom" --no-prizeUse
--prizeif the game has a prize. Never invent an answer: if they do not know where the game will be played, ask. Pass on the two lines the command prints, which say where the request is and what happens next. -
No. Run
gamestage ads skip <game>after the deploy, so nobody asks again for this game. Do not mention products again unless they do. -
Not now. Run nothing, and tell them they can ask later with
gamestage ads request <game>or from Stage.
Products follow the teams the round names, by full name (team:Buffalo Bills, not BUF), at most five per request. Teams outside the Premier League,
such as NFL and NBA teams, work too: request with --countries "United States"
and they are searched in the US catalogue only. A team the game has never named
shows products from the night after it first asks, because the catalogue is
searched overnight.
Nothing about the deploy waits for this, and a request changes nothing a fan sees until staff approve it. In chat there is no tool for it yet: tell them to use Partner products on the game's Settings tab in Stage instead.
Offer the accessibility, security, secrets and privacy checks
Let verify play an arcade run to the end. It presses the start button
(data-gamestage-arcade-start) and waits for the run to end. If a run ends only
when a player does something, such as surrendering, mark the controls that end
it with data-gamestage-finish, numbered when it takes more than one press:
data-gamestage-finish="1" on the menu button, data-gamestage-finish="2" on
its Surrender. verify and the live check after a deploy press them in order,
so "the screen shows what the server decided" is proved rather than skipped.
They are ordinary buttons a fan can press too; add nothing that only a test sees.
Gamestage does not test a game's accessibility, security or privacy, and does
not certify them. After its verdict, verify lists four checks worth running
and says which the developer has recorded. Offer them before a game goes in
front of fans; do not run one without asking, because installing a skill
changes the developer's machine.
| Check | Run it with |
|---|---|
| Accessibility | npx skills add addyosmani/web-quality-skills@accessibility |
| Security review | npx skills add getsentry/skills@security-review |
| Secrets | gitleaks detect --source . |
| Privacy | npx skills add wshobson/agents@gdpr-data-handling |
When one has run, record it under assurance: in gamestage.yaml with tool,
ran_at (YYYY-MM-DD) and result (passed, issues_fixed or
issues_open), plus owner and evidence if the developer gives them. Record
what happened, including open issues: the record is the developer's, it shows
on the game's page in Stage, and it never affects verify, deploy or the
build stage, so there is nothing to gain by rounding it up. Fields:
https://gamestage.ai/docs/app-manifest.md.
Put the leaderboard on a screen a crowd can see
A Gamestage game publishes a read-only leaderboard feed, and Monterosa Live Graphics can follow one. So a stadium screen, a lower third over a live stream, or a panel down the side of a TV app is a command rather than a piece of work: you do not write a bridge, the game holds no credential, and nothing about the game changes.
npx gamestage@latest graphic templates
npx gamestage@latest graphic create kickoff --template bigscreen --consent
npx gamestage@latest graphic list kickoff
npx gamestage@latest graphic remove kickoff <id>
What comes back is a web address. Open it on the screen; it needs no sign-in and it redraws by itself as fans play.
| Template | Made for |
|---|---|
bigscreen | A stadium screen or a Jumbotron. Ten rows at large type. The default |
lowerthird | A lower third over live video, for TV and streaming. Transparent and keyed |
panel | A right-hand panel pulled out over the picture, for TV and CTV |
vertical | A portrait panel in a concourse, 9:16 |
promo | A QR code that sends a crowd to the game. No live data |
The game must be deployed first, and the refusal is not a fault. A
leaderboard graphic follows the game's own feed and a QR code sends people to
the game's own page. Neither exists before a deploy, so graphic create on an
undeployed game is refused with This game has not been deployed. Deploy, then
create.
--consent is the developer's to give, never yours. A leaderboard puts
fans' names on a screen other people can see, and the account that runs the
command is recorded as having confirmed those people agreed to that. You cannot
know whether they did. So hand the command over with the flag on it and let the
developer run it, exactly as you would gamestage promote. There is no
--json route around this and there will not be one: a confirmation produced
as a side effect of an agent running a command is a record saying somebody
agreed when nobody was asked.
The structure is Monterosa's and the paint is the creator's. You cannot add
a graphic type or move a column. What you can change is the styling:
gamestage graphic dev serves the real renderer on the developer's machine
against a made-up board, and gamestage graphic push <game> hands a producer
the published address of the stylesheet. See
https://gamestage.ai/docs/live-graphics.md.
Put a live contest into the game
Live data puts a real contest into a game as it happens, in any sport: the score, the clock, each side's numbers and every moment, seconds after it happens. It is one way: offer it only to show a contest that is being played, such as a scoreboard, a momentum chart, a stadium screen or a TV graphic. Never offer it to score plays or settle predictions; nothing a fan's result depends on comes from live data. Say contest, moment and side; never match or goal in anything the developer's fans read, because the same game may follow a race.
npx gamestage@latest live on
npx gamestage@latest deploy <game> --dir .
live on adds live: { provider: sportmonks } to gamestage.yaml and changes
nothing else. After the deploy, each edition has a Live contest setting in
Studio, where a producer types the provider's id for the contest. In the page,
game.live() hands it over: contest.on("state", draw) for the contest so far
and every change, contest.on("moment", celebrate) for what happens from now
on, and contest.onStatus(badge) for the connection. Draw a moment that
arrived as part of the contest so far in the score; never celebrate it.
gamestage dev --serve plays a made-up contest, so build and test it locally
with no key. To rehearse the deployed game, gamestage live simulate starts a
made-up contest on the deployed feed and prints an id: tell the developer to put
it in the edition's Live contest in Studio. live list, live pause <id>,
live play <id> and live stop <id> control it. Live data is open to Monterosa workspaces today, and a deploy from
any other is refused with live_not_enabled: say so plainly and offer the game
without it. See https://gamestage.ai/docs/live-data.md.
Human handoffs
gamestage login is the one you run rather than hand over, when start
said this machine is not signed in. Running it beats handing over a command to
type: it is a few seconds of the developer's attention instead of a
conversation to resume. It is still their approval, though, so you run the
command and they do the approving. In a chat with the connector there is no
login to run: they signed in when they added the connector.
What it does, and the part you must not skip. It emits a JSON notice on
standard error with status: "awaiting_approval", a verification_uri_complete
and a user_code, then waits. Put that address in front of the developer
immediately, with the code beside it. It also tries to open their browser,
and that is best effort: over SSH, in a container or in a sandbox it opens
nothing, and a developer who was never shown the address is waiting on a window
that will not appear. When they approve, the command returns signed in and you
carry on.
Two things it can return instead. The code expires after a couple of minutes,
which comes back as a plain message rather than an error: run it again and give
them the new address, because each run mints its own and older ones stop
working. And awaiting_approval is not signed in. It is the notice, not the
result, so do not read it as a green light and run the next command.
A brand-new account is a longer wait than that. login creates the account as
well as signing in, so there is nothing for them to do first, but a new
workspace is approved by a person at Monterosa. Signing in will work; deploy
at step 11 will not until that approval lands. Say so when you see a new
account rather than letting them discover it eight steps later.
Do not run it on a machine that start said is already signed in. It rebinds
the machine to whichever account the browser is holding, and a developer who
has two is now working in the wrong workspace with nothing saying so.
gamestage link github still needs a person: it is the same device flow. It
stopped being a first deploy's gate on 2026-09-15 and nothing is blocked
without it, so hand it over only if a refusal actually names it. Approval of a registered
account is ours to give, not yours to wait out. gamestage suspend, wake and
archive change what a live audience can reach. gamestage promote is the same family and the largest of them: it
approves a game to move from dev to prod, which is a real audience's game
changing under them. None of these is yours to approve alone. Stop and hand
over the exact command and its consequence.
gamestage graphic create --consent is one of these. The flag says the fans
named on the board agreed to appear on a public screen, and the account running
it is recorded as having said so. Hand over the whole command and let them run
it.
The developer must accept the Terms of Service themselves in a browser. You
must never accept them. When login or a refusal names
https://gamestage.ai/terms, give that address to the developer and wait; do
not read, summarise or accept the terms on their behalf. There is no
command-line option for accepting the terms, and there will not be one.
A refusal at step 11 is an account waiting for approval, not a service that is shut. The route runs on the CLI's own default with nothing to configure. Read what the command said, tell the developer what it was, and stop. Never report a deploy, or a hosted game, on the strength of a command you did not run to completion.
Read deploy's result, then run gamestage status <game> --json. A non-zero
exit, a tool error or lastProblem means the pickup needs attention: tell the
developer the reason and what did work. A live page alone does not prove the
Engine can store scores. In a chat, follow deploy_game with get_game.
A playground link that answers 403 AccessDenied means the page's files were
never uploaded, not that the game is waiting for approval. gamestage promote
will not fix it: promote moves the game from dev to prod and has nothing to do
with whether its page loads. Redeploy from the game's folder with
gamestage deploy <game> --dir ., then open the link again.
Where the detail is
https://gamestage.ai/start.md: the full entry point.https://gamestage.ai/schemas/app-manifest/1.0: the manifest schema, which describes the game and holds no round.https://gamestage.ai/docs/migration.md: the full migration route.https://gamestage.ai/docs/game-formats.md: whether this needs an Engine at all, and if so which rule fits. Read the first section before the decision guide: a game whose answer does not have to be computed from data a fan cannot see is a plain Monterosa element and needs none of this.https://gamestage.ai/docs/player-api.md: the browser integration contract.gamestage <command> --helpfor any command.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/gamestage.ai/gamestage">View gamestage on skillZs</a>