A format is the set of rules a game is scored by. Pick your format before you change any code. It settles what the server keeps hidden from a player, what counts as one go, and when a player finds out how they did.
On the command line, choose a format with --format, for example --format group.
How each Engine protects a game
Gamestage gives creators Engines that make common forms of cheating hard. The page draws the game and sends the fan's actions. The table describes where the private material and score live, and what that arrangement is designed to stop.
| Format | Where the answer and score live | What this is designed to stop |
|---|---|---|
| Solve | The server holds the answer set and marks and scores guesses, including word, number and phrase variants. | Reading the answer from the page or editing the score. |
| Push Your Luck | The server holds the dataset's hidden values and works out the score. | Reading every value from the page or changing a pick's value. |
| Find the Groups | The server holds group membership and marks and scores guesses. | Reading the groups from the page or awarding a correct guess locally. |
| Predict | Results live on the server when known; the Engine records picks, applies deadlines and scores them. | Changing a pick after the deadline or editing its score. |
| Bingo | The server deals and records boards, holds outcomes and scores completed lines. | Replacing a dealt board or claiming a line the recorded outcomes do not support. |
| Kicker | The server chooses the keeper's dive, resolves each shot and holds the score; the browser sends aim and power. | Choosing the keeper's response in the page or awarding a goal locally. |
| Place the Face | The server holds which cells each card qualifies for and scores placements. | Reading that mapping from the page or awarding a placement locally. |
| Mystery | The server holds the hidden player and dataset, answers questions and records the result and score. | Reading the hidden player from the page or editing the result. |
| Arcade | Gameplay and score calculation run in the browser. The server starts and times runs, checks submitted scores and stores accepted scores. There is no correct answer to hold back. | Reusing a run, submitting a score without a run or posting a score outside the configured limits. |
| Quiz | The server holds each question's right answer and points, marks every answer and keeps the boards. The page reads the questions and answers from Studio. | Reading the right answer from the page or editing the score. |
Monterosa makes reasonable efforts to prevent common forms of cheating, gives no guarantee, and the terms apply.
Decision guide
| Ask | If yes | Format | --format |
|---|---|---|---|
| Is the fan trying to find a known subset of a board? | Each pick can be marked against an answer set | Solve | hunt |
| Do hidden numeric values accumulate towards a ceiling? | A pick is neither right nor wrong by itself | Push Your Luck | push |
| Does one guess contain several items that must form a hidden group? | Feedback applies to the whole guess | Find the Groups | group |
| Does the answer not exist when the fan commits? | The play must be marked later | Predict | predict |
| Is each fan dealt their own board from a shared pool? | A line or a full board is scored once the pool's outcomes are known | Bingo | bingo |
| Does the player aim and kick, and the server play the keeper? | One kick is one request, resolved and replayed | Kicker | shoot |
| Is the fan dealt a card and asked which category it fits? | Only the server knows who qualifies for what | Place the Face | place |
| Does the fan find one hidden player by asking yes-or-no questions? | A model answers each question from the player's record | Mystery | mystery |
| Is the game played in real time on the phone, steering or dodging, and scored as it goes? | The phone works out the score; the server times the run and checks it | Arcade | arcade |
| Does the fan answer several questions and get one score for the set? | Each answer is marked on the server against an answer the producer keeps private | Quiz | quiz |
Already know which one you want?
Solve: find the marked few among many
Push Your Luck: add hidden value towards a limit, and stop before you bust
Find the Groups: form the hidden sets in a board
Predict: call it before it happens
Bingo: each fan gets their own board, dealt from a pool
Kicker: aim, choose a power, kick; the Engine plays the keeper
Place the Face: drop a dealt card on a category it fits- Mystery: find the hidden player by asking yes-or-no questions
Arcade: a real-time game on the phone, with a leaderboard of each fan's best run- Quiz: answer a set of questions, marked on the server, on one board
If none fits, describe the missing rule. A person decides whether it becomes a new format, a Variant or customer-specific work.
To suggest a new format or feature, run gamestage suggest. It needs no account:
gamestage suggest "a game where a fan ranks five players, scored on how close the order is"
gamestage suggest "..." --closest group --sendWithout --send it prints the exact payload and sends nothing, so you can see what leaves your machine before it does. That payload is four strings: what you were building, the format that came nearest, the CLI version, and a marker saying it is a suggestion. The payload never includes the game: it has no manifest, round, answers or source, and no field could hold them.
Where your game's answer lives
Every game runs on an Engine that records accepted play and scores and serves the leaderboard. For games with a correct answer, the server marks against private material. Arcade checks scores calculated by the browser, as described above.
For games with an answer, where it lives depends on what the game needs:
- A producer can write a correct option or a result in Studio. The control plane reads it for the Engine to mark against.
- A game such as The Limit works out its result from hidden values in a private dataset. The control plane reads the dataset and provisions the Engine with the values it needs, while the browser receives public choices and feedback.
Keeping private answers and values on the server is designed to stop a player reading them from the page. Keep them out of the game's own published files too.
Live formats
The schema and the Engine accept the same fields for each container. The headings below are the names a creator sees.
Monterosa Studio shows older names for the container type of a deployed game: Find the answer, Under the limit, Puzzle, Prediction, Bingo, Penalties, Place the Face, Mystery or Quiz question. The label is declared in a published App Spec version, and changing it needs a new version. The formats are the same and appear in the same order.
謎解きSolve

The fan picks the right selections from a board of options. Trivia with one question per container uses this rule set.
The Engine keeps targets private and returns per-pick feedback and the committed score.
| Field | Required | Meaning |
|---|---|---|
board | yes | Public choices, at least two |
targets | yes | Private answer set, at least one |
required | no | Targets needed to finish, defaults to all targets |
pointsPerTarget | no | Score for each target, defaults to 10 |
completionBonus | no | Added on completion, defaults to 0 |
attemptsAllowed | no | Total plays allowed, defaults to 10 |
mistakesAllowed | no | Wrong plays allowed, defaults to 4 |
open | no | Whether play is accepted, defaults to true |
Validation rejects unreachable or repeated targets and a required count larger than the answer set.
Build a word or number guess game
gamestage create --name "Daily Word" --format word_guess
gamestage create --name "Guess the Year" --format number_guess
cd daily-word && gamestage dev --serveEach command writes a Solve game with a starter page and a practice round: word_guess is a Wordle board, and number_guess is a guess-the-year board with a picture and clues. The fan types a word or a number. The Engine holds the answer, marks every guess, and sends back only the marks: each letter's colour for a word, higher or lower for a number. The server withholds the answer from the page, and reveals it only once the fan has finished.
Write each day's round in Studio. A page that reads challenge.guesses_allowed, as both starters do, gets six extra boxes on its rounds:
| Studio box | Key | Type | Required | Default | What it does | |
|---|---|---|---|---|---|---|
| The answer | round_guess_answer | text | yes | none | The word or number to guess, such as CRANE or 1966. A whole number makes a number round; anything else is a word. Case and accents are ignored. Never sent to a browser before the fan finishes | |
| Guesses a fan gets | round_guess_count | number | no | 6 | From 1 to 20. A guess and a skip each spend one | |
| What a fan is told after each guess | round_guess_feedback | list | no | letters for a word, higher or lower for a number | letters, higher_lower, or none for right or wrong only | |
| Accept only real words | round_guess_words | list | no | any | words refuses a guess that is not an English word, without spending it. Works for words of 4 to 7 letters | |
| Clues | round_guess_clues | text | no | none | One per line, or split with `\ | `. The fan earns the next clue with each wrong guess or skip. Never sent to a browser before it is earned |
| Picture | round_guess_picture | image | no | none | Shown above the guess from the start, so choose one that does not give the answer away. Must be an https address |
The same round in practice/round.yaml, which dev and verify play:
archetype: hunt
prompt: Which year did England win the World Cup?
guess:
kind: number # word or number
answer: 1966
guessesAllowed: 5 # default 6
feedback: higher_lower # default: letters for a word, higher_lower for a number
clues:
- It was played in England.
- The final was at Wembley.
picture: https://example.com/wembley.jpg
open: trueA win scores the guesses left plus one, so 6 for a first-guess win of six and 1 for a last-guess win; a loss scores 0. To change that, fill in the game's Points boxes in Studio, described under build a solve the phrase game, where a turn is a guess.
When a guess is refused. A guess of the wrong length, one that is not a word, not a number, not in the word list, or already tried comes back rejected with a reason and spends nothing. The starters show each reason as a short message from Studio and shake the row, so the fan types again. A guess that does not reach the Engine says so and keeps what the fan typed.
When the round is over. The fan's state carries the answer, a share grid made only of marks (🟩🟨⬛ for a word, ⬆️⬇️✅ for a number, ⏭️ for a skip), and a score such as 3/6. The starters show the answer, the score, a Share button, and "Better than 62% of players", worked out with guessBetterThan from the round's crowd figures (game.client.getRoundStats). That line is left out for a loss, and while the fan is the only one to have finished.
Make your own page. Send a guess with game.guess(value) and a skip with game.skip(). Mark the board with data-guess="word" or data-guess="number", each committed move with data-move, a word's tiles with the Engine's data-mark and a number's move with its data-direction, so gamestage verify can play one guess and check the screen against the Engine. Every word the fan reads is a label_* setting, seeded in gamestage.settings.json.
Build a solve the phrase game
gamestage create --name "Grid Guess" --format phrase_solve
cd grid-guess && gamestage dev --serveThis writes a Solve game with a starter page and a practice round. The fan sees a hint and one blank tile per letter of a hidden phrase, grouped by word. They press Spin and the Engine reveals a letter that is in the phrase, everywhere it appears. After each letter they type one answer at the whole phrase and press Solve, or spin again. A right answer wins. A wrong answer, or spinning again after the last letter, loses. The public round withholds the phrase and carries only its shape, and the fan learns the phrase once they have finished.
Write each day's round in Studio. A page that reads challenge.draws_allowed, as the starter does, gets three extra boxes on its rounds, beside the hint:
| Studio box | Key | Type | Required | Default | What it does |
|---|---|---|---|---|---|
| The phrase | round_solution | text | yes | none | The word or phrase to solve, such as George Russell. Up to 120 characters. Accents and punctuation are kept for the reveal and ignored when marking, so sergio perez solves Sergio Pérez. Never sent to a browser before the fan finishes |
| Letters a fan draws | round_draws | number | no | 3 | From 1 to 36. Spinning again after the last one ends the round as a loss |
| Order of the letters | round_draw_order | list | no | seeded | seeded gives every fan the same letters in the same order, so results compare and share without a spoiler. random gives each fan their own order |
| What a fan is told | round_prompt | text | no | none | The hint above the tiles, such as Team nickname |
The same round in practice/round.yaml, which dev and verify play:
archetype: hunt
prompt: Team nickname
solve:
solution: Silver Arrows
drawsAllowed: 3 # default 3
drawOrder: seeded # seeded or random
open: trueSet the points for the whole game. With no points set, a win scores the letters left plus one, so 3 for a solve after the first of three letters and 1 after the last, and a loss scores 0. To change that, fill in the game's Points boxes in Studio, under the project's settings. They apply to every round, so you set them once for a season. A guess game gets the same boxes, where a turn is a guess.
| Studio box | Key | Type | Default | What it does |
|---|---|---|---|---|
| Points by turn | hunt_points_by_turn | text | none | Points for a right answer after the first letter, the second, and so on, such as 10, 6, 3. A right answer after more letters than you list earns nothing from this box |
| Points for playing | hunt_points_for_playing | number | none | Points for every finished round, won or lost |
| Points for a correct answer | hunt_points_for_correct | number | none | A flat amount for a right answer, on top of points by turn. Use it alone to give every winner the same |
If a box is filled in wrongly, such as 10; 6; 3, the game does not start a new round. Its log names the box and what it says. Fix the box and the next fan's visit picks it up.
Load a season at once. Write each day's round, with its date, in practice/season.yaml, then run gamestage round season <game>. Each day becomes its own edition in Studio, from midnight to midnight in your time zone, so on 2 November fans play the 2 November phrase. A producer changes one day by opening that day's edition in Studio.
timezone: Europe/London
days:
- date: 2026-11-01
prompt: Team nickname
solve:
solution: Silver Arrows
- date: 2026-11-02
prompt: Seven-time champion
solve:
solution: Lewis Hamiltonround season in the CLI reference has the options.
When an answer is refused. An empty answer, an answer before the first letter, or a second answer on the same letter comes back rejected with a reason and spends nothing. The starter shows each reason as a short message from Studio. A spin or an answer that does not reach the Engine says so and keeps what the fan typed.
When the round is over. The fan's state carries the phrase, and the starter shows the result, the phrase, the score, a Share button and Play next. The share line says how many letters the fan took and never the phrase.
Make your own page. Spin with game.draw(), which returns the letter and every [word, index] it sits at as drawn, and answer with game.solve(text). Mark the board with data-solve, each tile with data-tile="word:index", the spin button with data-solve-draw and the answer button with data-solve-submit, so gamestage verify can spin, answer and check the screen against the Engine. Every word the fan reads is a label_* setting, seeded in gamestage.settings.json.
運試しPush Your Luck

Each pick adds a private value to a running total.
The fan tries to get close to target without going over.
The Engine keeps entries[].value private. The public challenge contains the entry keys and labels, not their values.
| Field | Required | Meaning |
|---|---|---|
target | yes | Positive ceiling |
targetLabel | no | Display label for the total |
measure | no | Key of the dataset measure the round is counted on, such as season_points. Name it when the dataset holds more than one measure and the game names none in Studio. Without one, round push and round season write nothing and list the measures to choose from |
slates | yes | Ordered pick groups, each with id, label and entries |
tiers | no | Result bands ordered from closest to furthest |
floorLabel | no | Result below every declared tier |
bustLabel | no | Result after passing the target |
open | no | Whether play is accepted, defaults to true |
compare | no | each_at_least_last for a chain (below). Absent means picks add up |
Entry keys must be unique across the whole container. Validation also rejects a container whose cheapest possible total already exceeds its target, except on a chain, which reads no target.
Make each pick beat the last
A chain is the other way to play Push Your Luck. Each pick must be worth at least as much as the one before it. The first lower pick ends the round, and the score is how many picks held. An equal value holds.
Turn it on for the whole game in Studio, under Rules, with How picks are judged set to Chain: each pick at least the last. Every round in the game then carries the rule, and you can leave each round's target empty.
Studio shows that box only when your page can draw a chain. The page has to branch on the rule, which arrives on the public challenge:
if (round.challenge.compare === "each_at_least_last") {
drawChain(round.challenge.slates); // no target to show
} else {
drawTotal(round.challenge.target);
}| Field | Where | Meaning |
|---|---|---|
challenge.compare | Public round | each_at_least_last on a chain, absent when picks add up |
round_state.progress.broken | Player state | True once a pick came in lower than the one before |
round_state.progress.total | Player state | On a chain, the number of picks that held |
round_state.score | Player state | On a chain, the number of picks that held |
Each pick's value still stays on the Engine until that pick is made, and every value is revealed once the round finishes, as on a round that adds up.
When a round is refused. A chain round is left out of the game, with the reason in the deploy output, when nobody can finish it (no pick on a later slate is high enough) or nobody can lose it (every pick on every slate beats every pick before it). A value in How picks are judged other than the two it offers refuses the whole game and names the box.
共通点探しFind the Groups

Submit a set, find the hidden groups and receive whole-guess feedback, for example a near miss.
The Engine keeps group labels and membership private until a group is solved. A round publishes the board, how many groups there are and how many items are in one; which items belong together, and what any group is called, reach a player only once they have found it.
gamestage create --format group scaffolds this one. Its round is two groups of two, small enough that gamestage verify can play the page it wrote: verify makes a guess by clicking the first two picks. A real board is usually four groups of four, and the scaffolded page reads the size from the round, so growing the groups needs no change to the page.
| Field | Required | Meaning |
|---|---|---|
board | yes | Public items, at least four |
groups | yes | Private groups with key, label and members |
pointsPerGroup | no | Score for each solved group, defaults to 10 |
completionBonus | no | Added when all groups are solved, defaults to 0 |
attemptsAllowed | no | Total guesses allowed, defaults to 10 |
mistakesAllowed | no | Wrong guesses allowed, defaults to 4 |
Groups cannot overlap, every member must be on the board and every board item must belong to a group.
予想Predict

The fan commits a call before the result exists. Marking happens at settlement rather than at commit.
The options are public. result is absent while the outcome is unknown and is added when settling the same container. A committed play then returns marked: false until the result exists. The client must render that as pending, not as a loss.
| Field | Required | Meaning |
|---|---|---|
options | one of | Public options with a unique key and label |
questions | one of | Several questions in one round, see below |
result | no | Winning option once known, where the round asks one thing |
pointsForCorrect | no | Default score for a correct call |
attemptsAllowed | no | Calls a player may make, defaults to one |
open | no | Whether new calls are accepted |
Validation rejects a result that was not one of the available options.
Run a question live in Studio
A producer runs a predict question with options from its edition's timeline in Studio, the same way as any live question:
- Write it in the Library. Open the question, set its words and options on the Question tab, and save. A deploy creates each question here with placeholder words.
- Publish it when fans should start picking. Use Publish in the question's editor. It moves to Active on the timeline. Its words cannot change after this, so check them first.
- Close it when picks should stop. Actions, then Close.
- Reveal the answer. Actions, then Reveal Answer, and choose the winning option. Gamestage scores every fan who picked within about half a minute.
Until a question is published it has no Reveal Answer, so the result cannot be set in Studio.
Leave scoreline and number questions in the Library. Their result is set on the question's Result tab, and Studio does not allow that once a question is published, so a published scoreline or number question can never be settled. Studio labels each option "Option" in the reveal list, in the order you wrote them; check the order on the Question tab before revealing.
Several questions in one round
A round asks one thing or several. options is the one-question form and questions is the several-question form, and a round declares one or the other: two homes for one question is how they come apart.
questions:
- id: winner
kind: choice
prompt: Who lifts it?
options:
- { key: real, label: Real Madrid }
- { key: city, label: Manchester City, points: 25 }
- id: goals
kind: number
prompt: Goals in the final?
min: 0
max: 10
tolerance: 2id is how a play names the question it answered, so it has to stay put across a settlement. A round written the one-question way is read as a single question with the id 1, so nothing already provisioned changes.
A number is marked by distance, not by equality. tolerance is how far out a fan can be and still score: points fall away linearly and reach nothing at the edge of the band. A result of 20 with a tolerance of 5 pays in full at 20, sixty per cent at 18 or 22, and nothing at 15 or 25. Without a tolerance a number is exact, which is right for a count and wrong for anything a fan moves a slider to: nobody hits a number on a continuum, so exact-only marking makes the slider decorative.
min and max are required on a number and are enforced on the way in. A value past either end is refused rather than clamped, because a clamped answer is one the fan did not give.
A prediction commits whole. Every question is answered in one play, not one play each: three plays would let a fan answer two and lose the third to a dropped request, leaving a prediction half made against a round that has taken their one attempt. A play missing an answer is refused and costs nothing.
A round settles when every question has a result, not when the first does. Until then a play stays pending, because a fan told they scored 10 while two questions are open has been given a number that will change.
Outcomes gain partial: a round of three where a fan called two right is neither won nor lost. It counts as played, never as won, and it breaks a win streak, because a win streak that survives not winning is not a win streak.
ビンゴBingo

Each fan is dealt several whole boards from a shared pool of cards, swipes between them, and locks the one they want. They never see the rest of the pool. Which cards come true is decided later, on the pool rather than on any one fan's board, so every locked board is marked against the same decision.
A line, or the whole board, scores as soon as every card on it has a result. That happens during the game rather than at the end: a bingo line stays complete once complete, so a fan's score climbs as the world decides. The outcome stays pending until every card on their board is settled.
A card is a Studio element, and a producer resolves it
The round is the edition. Each card is one element on it. That is the same shape predict uses, and for the same reason: a card is resolved as a prediction, so it is a prediction element, and the platform's own correct_option holds its outcome.
So a producer opens the edition in Studio, sees one element per card, and marks each one as it happens. Setting correct_option on a card is what makes it come true for every fan whose board holds it, live, without republishing anything.
A deploy creates the pool for you: every card in your manifest's cardPool becomes an element. Cards a producer has already written are matched on their own words and left alone, so a redeploy tops the edition up rather than replacing it.
The board's shape is the edition's settings rather than any card's, because a three by three board is a fact about the round:
| Setting | Default | Meaning |
|---|---|---|
bingo_rows, bingo_columns | 3 | The board's size |
bingo_centre_mode | free | none, free or choice |
bingo_shuffle_allowance | 3 | How many times a fan may redeal; with the first deal, that's how many boards they see in total |
bingo_prompt | empty | What the page says above the board |
bingo_points_per_line | 10 | Score for each completed line |
bingo_points_for_full_board | 0 | Added once the whole board is correct |
The lock deadline is not a field you set. It is the edition's own scheduled end.
The practice round fields
For local play with gamestage dev, write these fields in practice/round.yaml. Live content is written in Studio. Every command refuses a round in the manifest.
| Field | Required | Meaning |
|---|---|---|
rows, columns | yes | The board's size, at least 2 by 2 |
cardPool | yes | Every card that could be dealt, at least enough to fill the board |
centreMode | no | none, free or choice, defaults to none |
centreOptions | one of | Cards the fan may choose for the centre, required when centreMode is choice |
allowCentreDuplicate | no | Whether the centre may repeat a card already on the board, defaults to false |
lineTypes | no | Which of row, column, diagonal, full_board score, defaults to row and column |
pointsPerLine | no | Score for each completed line, defaults to 10 |
pointsForFullBoard | no | Added once the whole board is correct, defaults to 0 |
shuffleAllowance | no | How many times a fan may redeal. Defaults to 3, so with the first deal a fan sees four |
open | no | Whether play is accepted, defaults to true |
What a fan's page has to do
Two operations rather than a list of picks, because there is no public board to choose from.
deal asks for the carousel. It is refused a second time: the offer is made whole, and a top-up would be a fan rerolling the set they were meant to choose within. The boards come back in progress.boards, and the words for every card on them in progress.cards.
lock commits one of them, and must name which by its position in the carousel. A lock that names no board is refused rather than defaulting to the first, because a page that lost track of which board a fan was looking at would otherwise commit a different one silently, and the fan would find out at settlement.
await game.play({ op: "deal" });
await game.play({ op: "lock", board: 2 });キッカーKicker
Kicker was called Penalties until 2026-10. Its format key is still shoot, and Studio still labels it Penalties until the next App Spec version.

The fan picks a spot in the goal and a power, and shoots. The Engine plays the keeper: it decides where the keeper dives, resolves goal, save, wide or off the frame, scores it, and returns a short replay the page animates. One shot is one request. The fan takes a fixed number of penalties and the shootout is won by reaching a threshold of goals; every shot still scores after that, so the round ends on the last shot and not the moment it is won.
What the first release is, plainly
penalty_v1 is a bounded arcade approximation, and the name is the promise. The ball is adjudicated at the goal line: power sets how long it takes to get there and how far it can stray from the aim, and a ball touching a post or the bar is a miss. The keeper's dive, and how far the ball strays, are drawn from entropy the Engine mints when the round is provisioned, before any shot is taken, so the keeper’s distribution is chosen before the fan aims. Two fans on the same round face the same keeper distribution and different actual dives: comparable difficulty rather than identical challenges, and the leaderboard should be read that way.
Nothing is timed. A power control chooses power, and the Engine awards nothing for how fast a fan pressed or how close to a mark a meter stopped, because a request cannot prove a browser's input event and a number the page chose is a number the page can choose again. What the Engine can stand behind is server-authoritative outcomes over bounded inputs and a bounded number of shots. Bot resistance and one-person-one-entry are separate requirements.
The manifest fields
| Field | Required | Meaning |
|---|---|---|
shotsAllowed | no | Penalties a fan takes, 1 to 20. Defaults to 5, and gamestage verify asks you to write it down |
goalsToWin | no | Goals that win the shootout. Defaults to 3. Must be reachable from shotsAllowed |
pointsPerGoal | no | What each goal scores. Defaults to 100 |
difficulty | no | The keeper: easy_v1, balanced_v1 or hard_v1. Defaults to balanced_v1 |
model | no | penalty_v1, the only model. Naming another is refused rather than defaulted |
open | no | Whether play is accepted, defaults to true |
This format has no answer field. The keeper's randomness belongs to the Engine and does not appear in a manifest, an element or a browser.
The Studio settings
Every one of these sits on the round's element and every one is public, because none is an answer. A producer who leaves a box empty gets the default the box names.
| Setting | Default | Meaning |
|---|---|---|
round_prompt | empty | The line above the goal |
shoot_shots_allowed | 5 | How many penalties a fan takes |
shoot_goals_to_win | 3 | How many goals win the shootout |
shoot_points_per_goal | 100 | What each goal is worth |
shoot_difficulty | balanced_v1 | Which keeper the fan faces |
What a fan's page has to do
Send the aim, the power and which shot it is, and draw what comes back. Aim is two whole numbers, aimX from -1200 to 1200 with the posts at ±1000 and aimY from -200 to 1200 with the bar at 1000, so a fan may aim wide and miss. Power is 0 to 1000. A value outside those bounds is refused rather than clamped, and so is any extra field: a page that sends goal: true or a score of its own has its whole shot refused.
const result = await game.shoot({ shotIndex: state.attempts_used, aimX: 800, aimY: 200, power: 650 });
result.shot.result; // "goal", "saved", "wide" or "frame"
result.shot.replay; // where the ball and the keeper ended, and whenshotIndex must be the next shot; the Engine refuses an out-of-order shot. The replay carries the ball's end position, the keeper's start and end, the flight time and where any contact happened, all in the same units the Engine adjudicated in; animate those and never compute an outcome. The whole history is in round_state.progress.shots, so a reload draws settled state without replaying anything.
The scaffold gamestage create --format shoot writes offers six aim zones and three powers as real buttons, with sliders to fine-tune, and keeps a shot whose response was lost so a reload retries the same penalty under the same key. gamestage verify drives those buttons, watches the request, and fails a page whose screen shows a result or a score the Engine did not commit.
Place the Face
The fan is dealt a deck one card at a time and drops each onto a board of category cells. A drop is right when that card qualifies for that category, and only the Engine holds the map of who qualifies for what. A right drop fills the cell and scores; a wrong drop spends a life and wastes the card; a fan may pass a limited number of cards. The board is won by filling every cell and lost by running out of lives, or of cards. A round can lift either limit, so a wrong drop or a pass only wastes the card and the deck is the one limit. A page reads that from the fan's state: with no mistake limit mistakes_allowed is absent while mistakes_used still counts, so show a count, not lives left. The round sends no skip allowance, so a page that shows skips left takes it from the same producer settings it shows. Creating a new round in Studio with gamestage round push --create or a season needs the game deployed since its boxes were added.
The map from a card to the cells it may fill is the answer, so the server withholds it from the public round. It works like a group round's hidden membership. The board's labels and the deck's faces are public; which cells a card fits is not.
There is no gamestage create scaffold for this format, so a place game is built without a starter template. Its round is written in Studio for the live game, or in practice/round.yaml to play it on your own machine; the manifest holds no round. The Studio boxes for wildcards and deep cuts appear only for a game whose page reads wildcards_allowed or a placement's deep cut. gamestage round push copies a practice/round.yaml round into Studio, where each box and card is keyed by its words rather than by the key the file gave it, and refuses a round whose box labels contain a comma or repeat.
In Studio, a box and a card are named by their own words, so no two boxes and no two cards may read the same, and "Which boxes each card fits" names them exactly as they are written. A round whose "The boxes" is empty is not set up yet, and the game keeps the round it already had.
Dealing a card from a pool
A round can deal its card from a pool instead of playing the boxes and cards as written. Give it a deal, and board, deck and qualifies become the pool: the server deals a card from them when the round goes live, and every fan plays that card for as long as the round runs. A new round deals a new card. In Studio, turn on "Build the card from lists"; the round's card is seeded by its element, so the same round always deals the same card while its lists are unchanged. Editing the lists, or "New cards per player", while the round is live deals a new card and restarts the round for every fan, so set them before it goes live.
The shape of a card is set on the round, never in code. deal.boxes is how many boxes a card has ("Number of boxes"). deal.tiers groups the boxes by a difficulty you name and says how many of each a card takes, in order ("Boxes from each difficulty"); a box carries its difficulty as board[].tier. The card is then topped up from any box left. Every box on a dealt card has a different card in the deck that fits it, so a card can always be finished, and the deck adds deal.multiFit cards that fit two boxes or more ("Cards that fit more than one box") and deal.decoys that fit one at most ("Cards that fit no more than one box"). deal.pool ("Only use cards from") deals only from cards whose deck[].tags ("Card groups") include it, and leaves out any box none of those cards fit, or all of them do.
A page is told its card was dealt by challenge.dealt_from_pool, and only a game whose page reads it is offered the deal boxes in Studio. The page receives the dealt card exactly as it receives a written one: the rest of the pool, the difficulties and the groups never reach it. A pool that cannot give a card of the size asked for is refused where it is set up, with the shortfall named.
A New card
With deal.newCard ("Allow New card"), a fan who has finished the round's card can ask for a New card: their own, dealt from the same pool and built the same way, once the round's card is finished or its clock has run out. It is played with the round's limits but no timer, keeps its own result, and earns nothing: the fan's score, leaderboard place and outcome stay the round's card. Off by default, so a round without it is one card per fan.
A page offers it by reading challenge.new_card_allowed, and only a game whose page reads that is given the tick in Studio. { op: "new_card" } deals one, and closes any open New card with its result as it stands; a New card not yet played is kept rather than swapped (new_card_open), and a fan gets at most deal.newCardLimit ("New cards per player"), 20 when it is not set (new_cards_exhausted). place, skip and wildcard then play it, each naming the card it is on as newCard (its number), with itemIndex counting from 0 on the New card's own deck. The card is in the fan's state, never on the challenge: progress.newCard has its board and deck, the fan's placements, filled, attemptsUsed, mistakesUsed, skipsUsed, and finished and outcome once done. progress.newCards keeps the last 20 finished results as { number, boxes, filled, outcome }. Neither ever holds an answer.
A new card each day
With deal.daily ("New card each day"), one round deals a fresh card every day by itself, the same for every fan that day, so a producer sets the event up once. A day starts at deal.dayStarts ("Day starts at", an hour from 0 to 23, midnight when empty) in deal.timeZone ("Time zone", an IANA name such as America/New_York, Europe/London when empty). A fan plays the day's card once; the next day it is a new card, and their score, finish and New cards start again. An event runs at most 366 days.
A page offers it by reading challenge.deals_daily, which also gives challenge.day_starts and challenge.time_zone for saying when the next card comes; only such a page is given the boxes in Studio. The day's card is in the fan's state, not the challenge. On a daily round challenge.board and challenge.deck still hold the card dealt when the round went live, which is not the day's card after the first switch, so draw from the state: progress.card holds its day, board and deck, beside the fan's placements and counts on it, and progress.days keeps the last 31 days played as { day, boxes, filled, score, outcome }. Each place, skip and wildcard names the card's day; a play naming another day, or none, is refused as day_changed and spends nothing, so a page reads the state again and shows the new card. The round's leaderboard shows each fan's latest day played, so a fan who has not played today still shows yesterday's score: it is not a board for today alone. A fan whose play an operator retracted stays out of the round on later days too. The profile's day streak counts UTC days, not the round's days. Once the round stops taking plays, each fan's last day stands as it was.
Lock in
With lockIn ("Lock in"), every drop fills the box it lands on, right or wrong, and nothing is marked until the card is done: every box is filled, or the deck is spent. Until then a play's feedback is empty, the fan's score and mistakes_used are 0, and no placement says whether it was right or is a deep cut. The play that finishes the card marks every box at once: its feedback lists each placed box as correct or wrong, and each of progress.placements gains correct, and deepCut where it earned one. The full board bonus then needs every box right, and only such a card is won.
A lock-in round counts no mistake in time to end on one, so it takes no mistake limit: mistakesAllowed must be unlimited, and in Studio "Mistakes allowed" is ignored once "Lock in" is ticked. A page offers it by reading challenge.lock_in, and only a game whose page reads it is given the tick in Studio. A day's card and a New card are locked in when their round is.
wildcardScores: false ("Wildcards score no points") makes a wildcard's box score nothing while it still counts as right, towards the full board bonus too, on any place round. A page learns it from challenge.wildcard_scores, and the tick comes with "Wildcards allowed".
wildcardBonus: false ("Wildcards lose the full board bonus") means a card with a wildcard on it earns no full board bonus, even when every box is right. The wildcard's box still counts as right and the card is still won, so a page can tell it from a card with a box wrong. A page learns it from challenge.wildcard_bonus, and the tick comes with "Wildcards allowed".
The next event
A place game whose round is set up in Studio keeps going by itself. When its current event is six hours or less from ending and nothing is scheduled after it, Gamestage makes the next event, the same length, starting when the current one ends, and carries the round onto it. If the game has no current or upcoming event at all, the next one starts at once and the channel is told. So an event created later than six hours before the current one ends overlaps the one Gamestage made: schedule the next event earlier than that. The project's "How the live round is chosen" set to rotation, archiving the game, or fourteen days without a play stop it.
The round's fields
| Field | Studio box | Required | Meaning |
|---|---|---|---|
board | The boxes | yes | The cells, each with a key and a shown label. In Studio the label is the key |
deck | The cards | yes | The cards, in deal order, each with a key and a shown name. In Studio the name is the key |
qualifies | Which boxes each card fits | yes | For each card, the cells it may fill. Every cell needs at least one card; a card with none is a decoy. Private; never sent to a browser |
pointsPerPlacement | Points per box | no | What each correct placement scores. Defaults to 1 |
fullHouseBonus | Full board bonus | no | Added when every cell is filled. Defaults to 0 |
mistakesAllowed | Mistakes allowed, or tick "No limit on mistakes" | no | Wrong drops before the board is lost. Defaults to 4. unlimited for no limit: a wrong drop still wastes the card and is counted, and the round ends when the board is full or the deck runs out |
skipsAllowed | Skips allowed, or tick "No limit on skips" | no | Cards a fan may pass. Defaults to 3. unlimited for no limit; each card passed is still spent |
wildcardsAllowed | Wildcards allowed | no | Wildcards a fan may play: the dealt card goes into any open cell and counts as right, never as a deep cut. Defaults to 0. A page plays one with { op: "wildcard", itemIndex, cell } |
deck[].deepCut | Deep cuts | no | Marks a card few fans would know. Placing it right, without a wildcard, adds deepCutBonus and counts in progress.deepCuts. Private until placed |
deepCutBonus | Deep cut bonus | no | Added for each deep cut placed right. Defaults to 0 |
lockIn | Lock in | no | Every drop fills its box and nothing is marked until the card is done. Needs mistakesAllowed: unlimited. Off by default. See "Lock in" |
wildcardScores | Wildcards score no points | no | false for a wildcard's box to score nothing while counting as right. Defaults to true |
wildcardBonus | Wildcards lose the full board bonus | no | false for a card with a wildcard on it to earn no fullHouseBonus, while still won. Defaults to true |
deal | Build the card from lists, and the boxes below it | no | Deal the card from board, deck and qualifies as a pool. Has boxes (Number of boxes), tiers (Boxes from each difficulty), multiFit (Cards that fit more than one box), decoys (Cards that fit no more than one box), pool (Only use cards from), newCard (Allow New card), newCardLimit (New cards per player), and daily, dayStarts and timeZone (New card each day, Day starts at, Time zone). See "Dealing a card from a pool" and "A New card" |
board[].tier | Boxes from each difficulty | no | The difficulty a box is dealt in, on a round with deal |
deck[].tags | Card groups | no | The groups a card is in, on a round with deal |
open | no | Whether play is accepted, defaults to true |
Validation rejects a qualification naming a cell or a card that does not exist, a cell no card can fill, and a deck shorter than the board. A round set up in Studio, or written there by gamestage round push, is also refused when its cells cannot each be given a different card that fits, for example two cells only one card fits; the refusal names them. A round played from practice/round.yaml with gamestage dev, and a round a game already holds from its manifest, are never checked this way. A refusal leaves the round a game is already serving in place, so fans keep playing, and a redeploy is refused until the board is fixed, as for any round in Studio that will not assemble.
Mystery
The fan is looking for one player among every player in the game's dataset. They ask yes-or-no questions in their own words ("Has he won the league?"), and Jev, a model that answers questions from data, judges each one against every player's record. Asking is free and shows how much the answer would narrow the field; paying coins reveals the answer. The field narrows with every answer, the photo sharpens as it does, and a wrong guess costs a life.
Mystery runs on the Deduction Engine, not the Engine the other formats share. The Engine withholds the answer until a fan has finished: a fan's browser gets the count of players still in it, never the list, until a dozen or fewer are left.
A game names its dataset on the project in Studio, in the Dataset field. Every player in it is a candidate, with his public facts (club, position, nationality, previous clubs) and his numbers. Each edition is a Studio event and each of its elements is one mystery, up to five a day. The edition copies that morning's dataset when it is made, so the numbers never change under a fan who is part of the way through.
There is no gamestage create scaffold for this format.
What a producer sets on a mystery
| Field | Required | Meaning |
|---|---|---|
| The answer | yes | The player, as the dataset names him, or his dataset key. Private |
| Free clue | yes | The sentence every fan starts with, 200 characters at most |
| Free clue is about | no | The dataset field the free clue gives away. Defaults to team |
| Second clue | yes | The sentence a fan gets when their coins run low, 200 characters at most |
| Second clue is about | no | The field the second clue gives away. Defaults to position |
| Difficulty | no | 1, 2 or 3. Defaults to 1 |
A missing clue, an answer the dataset does not hold, a clue about a field it does not have and two clues about the same field are refused, and the reason is logged against the game: gamestage logs <game> shows it.
Arcade

Use Arcade for a game that runs in real time on the phone, such as a runner, a dodger or a flying game, where reaction speed is the game. A phone has to run it at sixty frames a second, so the phone works out the score. Every other format here is decided by the server, one action at a time; this one is not.
const { run, seed } = await game.arcade.start({ build: "tunnel@1.4.2" });
// ...play, building the level from `seed`...
const result = await game.arcade.finish(run, { score: 387, playedMs: 93800 });
const board = await game.arcade.board("all-time");gamestage create --format arcade gives you a small runner with all three calls wired. Arcade runs on the Arcade Engine, not the Engine the other formats share. For each run, the Engine:
- starts the run on its own clock and gives you a seed for the level;
- takes one score per run, and refuses one the game could not have reached in the time the run took, a run used twice, or a score with no run behind it;
- keeps each fan's best score, or the total of their runs, on an all-time board and one board per edition.
Show the score finish returns, not your own. If the Engine refused the run, it did not count, and the page should say so.
What "checked" means. Most arcade games rely on gameplay in the browser. Unlike puzzles and games with a correct answer, there is no correct answer to hold back. The Arcade Engine applies a range of mitigations that make the game more secure:
- the run is started and timed on the Engine's own clock, with a seed it issues;
- it accepts one score per run, refuses a reused run and refuses a score with no run behind it;
- it checks the score against what the run's length allows, using
points_per_second,max_run_seconds,min_run_ms,score_maxandscore_min; max_runs_per_daycan cap runs per fan per day;- the limits are fixed for the life of an edition;
- a moderator can void a run.
Use a checked board for play without prizes. A fair-looking score inside the limits is accepted, which is why a checked board carries no prize. Server replay of each run from the fan's inputs is planned. Wait for replay to ship before offering prizes on an Arcade board.
The limits you set, in gamestage.yaml
The limits are yours, not a producer's, because you know how fast your game can score.
backend:
archetype: arcade
arcade:
points_per_second: 10
max_run_seconds: 300| Field | Type | Required | Meaning |
|---|---|---|---|
points_per_second | number | no, 1,000 when the highest score wins | The fastest a fair run can score. A score above this times the run's length is refused. The default is generous, so set your own |
max_run_seconds | whole number, 5 to 3600 | no, off | The longest a run may last. With points_per_second, it sets the largest believable score anybody could post. Off, a run may last up to 3,600 seconds |
min_run_ms | whole number | no | A run shorter than this is refused |
score_max | whole number | no | No score above this, however long the run |
score_min | whole number | when the lowest score wins | The best score a fair run can reach, for a time trial. Below 0 needs signed_scores |
ranking | highest or lowest | no, highest | Which way the board ranks. A time trial ranks lowest |
max_runs_per_day | whole number | no | Runs a fan may start in a day |
rank_by | best or total | no, best | What a fan's place is worked out from: their single best run, or the total of every run that counts. Fixed once the game has runs |
signed_scores | true or false | no, false | Whether a run may score below 0. Without it, a score below 0 is refused |
on_breach | refuse or flag | no, refuse | What a run that breaks a limit does. refuse: it does not count. flag: it counts and is marked for review. See below |
A game that sets none of these still deploys and is still checked, with the defaults above. Your game's log and gamestage dev say which defaults it is judged by.
Arcade may not suit a long-running game. The Engine checks each score against how long its run took, which works for short runs. With max_run_seconds off, a run may last up to an hour, the longest the Engine allows, so a game a fan leaves open for hours cannot be checked this way. Set max_run_seconds to the longest a fair run lasts.
Rank fans by the total of their runs
For a season of races, rank each fan by the sum of their runs rather than their best one. Each race here scores a gap, which is negative when the fan finishes behind:
backend:
archetype: arcade
arcade:
points_per_second: 50
max_run_seconds: 120
score_min: -6000
rank_by: total
signed_scores: true
max_runs_per_day: 12Each fan has one row on the board: the total of every run that counted, with equal totals sharing a place. finish returns the fan's new total as best on each board, and board() says rankBy: "total". A run the Engine refused, or a run a moderator voids, is left out of the total.
A total rewards playing more, so use max_runs_per_day to cap how many runs a fan can add in a day. rank_by is fixed once fans have played, so choose it before you launch.
Keep points_per_second and max_run_seconds as tight as fair play allows: the two together are the largest score a cheat could post without playing.
A run that breaks any of these limits is refused: it does not count and does not reach the board.
Flag instead of refuse when no limit fits your fair runs. Some games have no natural end, or score faster the longer a run goes, so any ceiling is either too loose to catch anything or tight enough to refuse a fan's best run. Set on_breach: flag and a run that breaks a limit still counts and ranks, and is marked for review with the limit it broke. A result that arrives up to ten minutes after the longest run is taken too, marked late. The fan sees the same reply as for any other run.
backend:
archetype: arcade
arcade:
points_per_second: 860
on_breach: flagThe trade is that a cheat's score also reaches the board until somebody looks. Flagged runs are reviewed by the Gamestage team, who can void them; there is no view of them for creators yet. gamestage dev marks a flagged run in the terminal and names the limit it broke.
A change to the limits, on_breach included, takes effect between editions. While an edition that fans have played is live, the Engine keeps judging runs by the limits that edition started with, and deploy says so. The new limits, and any edition added in Studio meanwhile, apply once it ends.
What a producer sets in Studio
| Field | Meaning |
|---|---|
| Equal scores share a place | On by default: two fans on the same score share a place. Off: the fan who got there first is placed higher |
Each Studio event is an edition with its own board. A run counts on the edition that was live when it started.
Let a fan choose the name on the board
Every fan starts on the board as Player 3F9A1C. Let them choose a name from the Engine's two word lists, exactly as on any other format, and the client puts it on the board for you:
const options = await game.client.getIdentityOptions();
// Offer options.adjectives and options.animals as two lists.
await game.client.setIdentity({ name: { adjective: "Swift", animal: "Otter" } });
const board = await game.arcade.board("all-time"); // other fans now see Swift OtterThe starter from gamestage create --format arcade has this picker beside its board, with its words in Studio (label_choose_name, label_name_prompt, label_name_save, label_name_saved, label_name_failed). It works for guests and signed-in fans alike, and gamestage dev shows the name on its local board.
The Arcade Engine takes a name only as a name ticket the Gamestage Engine signed, which is designed to stop a page submitting a name outside that choice. Put a chosen name on an arcade board has the ticket's fields. If the board refuses the name or does not answer, setIdentity still returns the profile, the client logs the failure, and play carries on. An arcade game that signs its players in with its own login cannot use names yet: its name routes answer 404.
When a call is refused
finish and start throw an ArcadeError. Its code is the Engine's:
| Case | code | What to show |
|---|---|---|
| The score was impossible, or the run had ended | score_above_ceiling, duration_impossible, run_expired, … (runDidNotCount is true) | The run did not count. Offer another |
| A guest started a run | sign_in_required (needsSignIn is true) | Ask the fan to sign in. The game stays playable |
| Too many runs, or the Engine is busy | rate_limited, engine_busy (retryable is true) | Try again after retryAfterSeconds |
Quiz
Use Quiz for a set of questions with right answers, played on demand: a daily news quiz or a match-day quiz. Each quiz is an edition in Studio and each of its elements is one question. A fan answers them all and gets one score for the set, on the quiz's board and on the game's board. A single trivia question stays on Solve.
Quiz runs on the Quiz Engine, not the Engine the other formats share. The Engine holds each question's right answer and points, and marks every answer. It holds no words: the page reads the questions and answers from Studio. A question's right answer reaches a fan only once their answer is marked, at the end of the quiz, or at once for a question set to "Show on answer". A fan's first play counts; later plays are practice and never reach a board.
Choose how the quiz runs over time
A quiz runs in one of three ways. Pick one before you write questions, because it decides how many editions a producer makes and which board a fan lands on.
| Type | What a fan meets | What a producer does | Today |
|---|---|---|---|
| Always on | One quiz that never goes dark, and one board for the life of the game | Writes the questions once and leaves "Quiz closes" empty | Not yet. An edition ends, at 366 days at most, and the game goes dark until a producer makes the next one |
| Edition | A new quiz each day, week or fixture. The page plays whichever edition is current | Makes an edition per period in Studio, writes its questions and publishes them | Works. Each edition has its own board, and the game's board adds them up |
| Live | Questions pushed one at a time during a show or a match, each open for a few seconds and revealed to everyone at once | Pushes each question from Studio as it happens | Not yet. The Quiz Engine runs live questions; Gamestage does not yet tell it when a producer pushes one |
Studio lists a question under Active for one day after it is published, and then under Finished. Fans can still play it after that: "Quiz closes" decides when answers stop, not the question's place in Studio. For an edition longer than a day, set each question's duration in Studio to the edition's length so Studio shows it as Active for the whole edition.
await game.quiz.nickname("Kestrel");
const quiz = await game.quiz.get(game.eventId); // question and answer ids
const words = await game.quiz.questions(game.eventId); // the words, from Studio
await game.quiz.start(game.eventId); // when the fan opens it
const play = await game.quiz.answer(game.eventId, [{ question: "q1", option: "b" }]);
const board = await game.quiz.board(game.eventId);Give each fan different questions
Set "Questions per play" on an edition to make it a Question Bank. Write more questions than a play needs, up to 300, and each play draws that many at random. A fan gets questions they have not had before, until they have had every one; after that, the ones they have seen least come back first. Two fans playing side by side get different questions.
For example, write 200 questions and set "Questions per play" to 10. Every fan answers 10, and their first play is the one that counts.
- Every question is worth the same. Every play then has the same possible total, so the board is fair. A bank of mixed points is refused.
- Show the questions the Engine drew.
startreturns them inquestionIds, in the order to show them. The page reads every question's words withquestionsand shows the drawn ones:
const words = await game.quiz.questions(game.eventId);
const play = await game.quiz.start(game.eventId);
const drawn = play.questionIds.map((id) => words.find((q) => q.id === id));- Start before you answer. The draw happens at the start, so answers sent with no play started are refused with
play_not_started. - You can add questions later. Once fans have played, you can still add questions to the bank. "Questions per play" is then fixed.
Without "Questions per play", every fan answers every question, up to 50.
Tell each fan which one they are
A personality quiz has no right answers. Each answer counts towards one or more results, and a fan gets the result their answers counted towards most: "Which Real Housewife are you?" rather than "How many did you get right?".
const words = await game.quiz.questions(game.eventId);
const results = await game.quiz.outcomes(game.eventId); // each result's words, from Studio
await game.quiz.start(game.eventId);
const play = await game.quiz.answer(game.eventId, picks); // every answer in one write
const mine = results.find((one) => one.id === play.outcome);
// mine: { id, name, verdict, why, image: { url, alt } }To make an edition a personality quiz, add a Quiz result element to it for each result, with its name, a one-line verdict, a few lines on why, and a picture. Then, on each question, fill in each answer's counts towards box in its Personality tab, naming results exactly as they are named, each with its points:
| Answer | Counts towards |
|---|---|
| Head-to-toe sequins. Subtle is for quitters. | Lisa Barlow 2, Meredith Marks 1 |
| Vintage couture and my own statement necklace. | Meredith Marks 2, Erin Lichy 1 |
- An edition with results is a personality quiz. One with none is marked right or wrong, and ignores the counts boxes.
- The Quiz Engine works out the result, never the page. The counts boxes are private, so a fan's browser cannot read which answer leads where.
- A tie goes to the result the latest answer counted towards most, looking back one question at a time, and then to the result that comes first on the edition's timeline. The same answers always give the same result.
- No score, no board, no nickname. A fan plays straight away, and can play again for a new result.
- Fixed once played. After fans have played, the results and counts cannot change: put changed ones in a new edition. The words, pictures and names of results can still be edited, but a renamed result must be renamed in every counts box too, or the next deploy says which box no longer matches.
- Every answer goes in one write, so a fan can change their mind until they finish. "Questions per play" must be empty.
To say what everyone else got, game.quiz.outcomeShares returns each result's share of the quiz's first plays, so a page can say "you are Lisa, and so did 6 in 10 fans":
const shares = await game.quiz.outcomeShares(game.eventId);
const lisa = shares.find((one) => one.outcomeId === play.outcome);
// lisa: { outcomeId: "lisa", share: 0.6 }Only a fan's first play counts, so replays never move the shares. It answers [] when the Quiz Engine the Space runs does not have the route yet, or the call fails, so a page that has nothing to say can simply say nothing.
Add pictures, video and audio
A question can carry a picture, a video or an audio clip, and each answer can be a picture. The starter shows them all.
| Studio box | Key | Limits | What the starter does |
|---|---|---|---|
| Picture | quiz_image | 500 KB, 2,000 by 2,000 pixels | Shows it above the question |
| Picture description | quiz_image_alt | text | Reads it to a fan who cannot see the picture |
| Video or audio | quiz_media | MP4, under 50 MB | Plays it above the question when the fan presses play |
| Answer A picture to Answer F picture | quiz_option_a_image to quiz_option_f_image | 500 KB each | Shows the answers as pictures, each with its words underneath |
game.quiz.questions returns each question's image (url and alt), media (url), and each answer's image.
- Upload an MP4, for video and for audio. Studio takes JPEG, PNG and MP4 files, and refuses MP3, M4A, WAV and Ogg. For audio, export an MP4 with sound and no picture, for example
ffmpeg -i chant.mp3 -c:a aac chant.mp4. The starter plays it in an audio player. - Keep a clip under 50 MB, and smaller for phones. On studio-dev Studio accepted 60 MB and failed from 100 MB. A fan on mobile data downloads the whole clip, so 10 MB or less plays more reliably.
- Studio's address does not say what the file is, so the starter opens it as a video and switches to an audio player if it has no picture. If the browser cannot play it, the fan reads "This clip won't play in your browser", in your words from Studio.
- A picture can be the question. "Who is this?" with a photo is fine, because the right answer stays private on the Engine. Studio serves an upload at an address with no file name, so naming the file after the answer gives nothing away. Write the picture description so it does not name the answer.
- Picture answers need words too. The starter shows pictures only when every answer has one, and each answer's words describe its picture.
- Upload rather than link. A video hosted elsewhere, such as YouTube, loads a third party, which needs the fan's consent first. The quiz does not offer a link box yet.
gamestage create --format quiz gives you a page with every call wired. dev shows the page on your machine, but there is no local Quiz Engine: deploy the game and write a quiz in Studio to play it.
What a producer sets on a question
| Studio box | Key | Type | Required | Default | What it does |
|---|---|---|---|---|---|
| Question | quiz_question | text | yes | none | The words fans read |
| Answer A to Answer F | quiz_option_a to quiz_option_f | text | at least two | none | The answers fans choose from. The Engine knows each by its letter |
| The right answer | quiz_answer | list | yes | none | Which letter is right. Private: never sent to a browser |
| Points | quiz_points | number | no | 10 | What a right answer scores, from 0 to 1000 |
| Show on answer | quiz_show_on_answer | yes or no | no | no | Show right or wrong as soon as the fan answers, rather than at the end |
What a producer sets on a quiz
| Studio box | Key | Type | Required | Default | What it does |
|---|---|---|---|---|---|
| Quiz closes | quiz_closes_at | text | no | stays open | A date and time with its time zone, such as 2026-11-05T18:00:00Z. Answers after it are refused |
| Who can play | quiz_guests | list | no | anyone | Anyone under a nickname, or signed-in fans only. A board anyone can play on carries no prize |
| Suspicious plays | quiz_flagged | list | no | ranked | Rank a play the Engine flags and mark it for a person, or hold it off the board until a person checks |
| Questions per play | quiz_questions_per_play | number | no | every question | Makes the edition a Question Bank: each play draws this many, from 1 to 50 |
A question with no words, fewer than two answers or no right answer is refused, and the reason is logged against the game: gamestage logs <game> shows it. Once a quiz has plays, its questions, right answers and points are fixed; put a changed question in a new edition. A Question Bank is the exception: it takes new questions after the ones it holds. verify refuses a game whose right-answer field is not private.
When a call is refused
Every call throws a QuizError. Its code is the Engine's. The client already waits and tries again for rate_limited, engine_busy and nickname_check_unavailable, so the page sees those only when they persist, and for question_not_open (a live question shown before the Engine has opened it) for up to five seconds.
| Case | code | What to show |
|---|---|---|
| The nickname is not allowed, or taken | nickname_refused, nickname_taken (needsNickname is true) | Ask for another |
| The quiz takes signed-in fans only | sign_in_required (needsSignIn is true) | Offer sign-in |
| The quiz has closed | quiz_closed | Show the quiz as closed |
| A question was already answered | already_answered | Show the stored result |
| Question Bank: answers sent with no play started | play_not_started | Call start, then show its questionIds |
| Question Bank: an answer to a question this play did not draw | question_not_drawn | Answer only the play's questionIds |
We can build Engines for custom game formats. Get in touch if you want one.
Shared fields
Every container has:
archetype: the discriminator the Engine uses.number: a positive human-facing number, default 1. The stored id is derived asround-<number>.prompt: player-facing instruction, default empty.open: whether the container accepts plays when provisioned.playsPerSecond: the per-second ceiling. If you leave it out, a deploy sets 2,560, which is far above any real audience and low enough to stop a runaway before it becomes a bill. Plays over it are refused withcapped. Held at the ceiling across four shards and four addresses for thirty seconds inside a two-minute window is the fair-use limit: on Starter the game stops taking plays for half an hour and tells us, and on a paid plan it tells us and keeps playing. Two shards for ten seconds warns first.playsPerDay: a daily limit you choose for your own round. It refuses plays past it withcapped_today. A Starter round without one is given 100, which is counted rather than refused.
Use the game's experience.container_label in creator-facing copy. The wire type remains Round until a deliberate breaking change.
Where a round's content lives, and how to protect it
Live rounds come from the content a producer writes in Studio. The control plane reads those fields and, where needed, joins them to a private dataset. Every command refuses a round in gamestage.yaml.
gamestage dev is the local practice exception: it reads practice/round.yaml beside the manifest. A deploy does not upload practice/. Use gamestage round push <game> to copy practice content into Studio for live play.
Content source is not fetched in deployed games yet
Content source, source_url, is a private field on the element for a URL pointing to round JSON. The deployed control plane does not fetch it yet. If you set it on a round Gamestage builds from Studio, your deploy is refused with round_source_unsupported. A round that is already live keeps playing, and the refusal is logged once against the game. A game still taking its round from the manifest does not read the element, so the field is ignored there. Clear source_url in Studio and enter the round's content in its own fields.
The prototype control plane used by tests has a URL reader, but that is not the deployed path. Do not build live operations around it. The project's Dataset field, reference_url, holds a dataset name which the deployed control plane reads from a private bucket, rather than an arbitrary URL fetched by the Engine.
Keep answers and datasets out of the page, the published directory and public repositories. A private field alone does not protect a document hosted at a public URL. Holding the answer and marking on the server is designed to stop a player reading the answer from the page or editing their score.
Implementation notes
A format describes a mechanic. A game's own board, options, copy and values are content in Monterosa Studio for live operations. The App Manifest (gamestage.yaml) describes the game and carries no round.
In the manifest and on the wire, a format is spelled archetype. Both words mean a format. --archetype still works on the command line and no longer appears in --help.