Join the waitlist

Game formats

Engines that your game will run on.

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.

FormatWhere the answer and score liveWhat this is designed to stop
SolveThe 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 LuckThe 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 GroupsThe server holds group membership and marks and scores guesses.Reading the groups from the page or awarding a correct guess locally.
PredictResults 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.
BingoThe 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.
KickerThe 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 FaceThe server holds which cells each card qualifies for and scores placements.Reading that mapping from the page or awarding a placement locally.
MysteryThe 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.
ArcadeGameplay 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.
QuizThe 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

AskIf yesFormat--format
Is the fan trying to find a known subset of a board?Each pick can be marked against an answer setSolvehunt
Do hidden numeric values accumulate towards a ceiling?A pick is neither right nor wrong by itselfPush Your Luckpush
Does one guess contain several items that must form a hidden group?Feedback applies to the whole guessFind the Groupsgroup
Does the answer not exist when the fan commits?The play must be marked laterPredictpredict
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 knownBingobingo
Does the player aim and kick, and the server play the keeper?One kick is one request, resolved and replayedKickershoot
Is the fan dealt a card and asked which category it fits?Only the server knows who qualifies for whatPlace the Faceplace
Does the fan find one hidden player by asking yes-or-no questions?A model answers each question from the player's recordMysterymystery
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 itArcadearcade
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 privateQuizquiz

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 --send

Without --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

Three panels: a board of empty squares; the same board with two squares marked as the hidden answer set the Engine keeps back; the board with each pick marked right or wrong.

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.

FieldRequiredMeaning
boardyesPublic choices, at least two
targetsyesPrivate answer set, at least one
requirednoTargets needed to finish, defaults to all targets
pointsPerTargetnoScore for each target, defaults to 10
completionBonusnoAdded on completion, defaults to 0
attemptsAllowednoTotal plays allowed, defaults to 10
mistakesAllowednoWrong plays allowed, defaults to 4
opennoWhether 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 --serve

Each 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 boxKeyTypeRequiredDefaultWhat it does
The answerround_guess_answertextyesnoneThe 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 getsround_guess_countnumberno6From 1 to 20. A guess and a skip each spend one
What a fan is told after each guessround_guess_feedbacklistnoletters for a word, higher or lower for a numberletters, higher_lower, or none for right or wrong only
Accept only real wordsround_guess_wordslistnoanywords refuses a guess that is not an English word, without spending it. Works for words of 4 to 7 letters
Cluesround_guess_cluestextnononeOne 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
Pictureround_guess_pictureimagenononeShown 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: true

A 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 --serve

This 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 boxKeyTypeRequiredDefaultWhat it does
The phraseround_solutiontextyesnoneThe 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 drawsround_drawsnumberno3From 1 to 36. Spinning again after the last one ends the round as a loss
Order of the lettersround_draw_orderlistnoseededseeded 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 toldround_prompttextnononeThe 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: true

Set 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 boxKeyTypeDefaultWhat it does
Points by turnhunt_points_by_turntextnonePoints 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 playinghunt_points_for_playingnumbernonePoints for every finished round, won or lost
Points for a correct answerhunt_points_for_correctnumbernoneA 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 Hamilton

round 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

Three panels: three named picks; three hidden values the Engine keeps back; a running total against a limit line.

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.

FieldRequiredMeaning
targetyesPositive ceiling
targetLabelnoDisplay label for the total
measurenoKey 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
slatesyesOrdered pick groups, each with id, label and entries
tiersnoResult bands ordered from closest to furthest
floorLabelnoResult below every declared tier
bustLabelnoResult after passing the target
opennoWhether play is accepted, defaults to true
comparenoeach_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);
}
FieldWhereMeaning
challenge.comparePublic roundeach_at_least_last on a chain, absent when picks add up
round_state.progress.brokenPlayer stateTrue once a pick came in lower than the one before
round_state.progress.totalPlayer stateOn a chain, the number of picks that held
round_state.scorePlayer stateOn 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

Three panels: a board of empty squares; the same board with two hidden groups ringed, kept back by the Engine; one submitted group ringed and judged as a whole guess.

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.

FieldRequiredMeaning
boardyesPublic items, at least four
groupsyesPrivate groups with key, label and members
pointsPerGroupnoScore for each solved group, defaults to 10
completionBonusnoAdded when all groups are solved, defaults to 0
attemptsAllowednoTotal guesses allowed, defaults to 10
mistakesAllowednoWrong 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

Three panels: the fan's call, one option marked among three; an empty box with no answer yet; a tick arriving later once the result is settled.

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.

FieldRequiredMeaning
optionsone ofPublic options with a unique key and label
questionsone ofSeveral questions in one round, see below
resultnoWinning option once known, where the round asks one thing
pointsForCorrectnoDefault score for a correct call
attemptsAllowednoCalls a player may make, defaults to one
opennoWhether 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:

  1. 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.
  2. 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.
  3. Close it when picks should stop. Actions, then Close.
  4. 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: 2

id 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

Three panels: a dealt board of filled squares; the same board blank, with which squares are right kept back by the Engine; one row ringed as the scored line.

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:

SettingDefaultMeaning
bingo_rows, bingo_columns3The board's size
bingo_centre_modefreenone, free or choice
bingo_shuffle_allowance3How many times a fan may redeal; with the first deal, that's how many boards they see in total
bingo_promptemptyWhat the page says above the board
bingo_points_per_line10Score for each completed line
bingo_points_for_full_board0Added 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.

FieldRequiredMeaning
rows, columnsyesThe board's size, at least 2 by 2
cardPoolyesEvery card that could be dealt, at least enough to fill the board
centreModenonone, free or choice, defaults to none
centreOptionsone ofCards the fan may choose for the centre, required when centreMode is choice
allowCentreDuplicatenoWhether the centre may repeat a card already on the board, defaults to false
lineTypesnoWhich of row, column, diagonal, full_board score, defaults to row and column
pointsPerLinenoScore for each completed line, defaults to 10
pointsForFullBoardnoAdded once the whole board is correct, defaults to 0
shuffleAllowancenoHow many times a fan may redeal. Defaults to 3, so with the first deal a fan sees four
opennoWhether 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.

Three panels: aim and power chosen towards the goal; the keeper diving one way, kept back by the Engine; the result, goal or save.

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

FieldRequiredMeaning
shotsAllowednoPenalties a fan takes, 1 to 20. Defaults to 5, and gamestage verify asks you to write it down
goalsToWinnoGoals that win the shootout. Defaults to 3. Must be reachable from shotsAllowed
pointsPerGoalnoWhat each goal scores. Defaults to 100
difficultynoThe keeper: easy_v1, balanced_v1 or hard_v1. Defaults to balanced_v1
modelnopenalty_v1, the only model. Naming another is refused rather than defaulted
opennoWhether 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.

SettingDefaultMeaning
round_promptemptyThe line above the goal
shoot_shots_allowed5How many penalties a fan takes
shoot_goals_to_win3How many goals win the shootout
shoot_points_per_goal100What each goal is worth
shoot_difficultybalanced_v1Which 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 when

shotIndex 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

FieldStudio boxRequiredMeaning
boardThe boxesyesThe cells, each with a key and a shown label. In Studio the label is the key
deckThe cardsyesThe cards, in deal order, each with a key and a shown name. In Studio the name is the key
qualifiesWhich boxes each card fitsyesFor 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
pointsPerPlacementPoints per boxnoWhat each correct placement scores. Defaults to 1
fullHouseBonusFull board bonusnoAdded when every cell is filled. Defaults to 0
mistakesAllowedMistakes allowed, or tick "No limit on mistakes"noWrong 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
skipsAllowedSkips allowed, or tick "No limit on skips"noCards a fan may pass. Defaults to 3. unlimited for no limit; each card passed is still spent
wildcardsAllowedWildcards allowednoWildcards 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[].deepCutDeep cutsnoMarks a card few fans would know. Placing it right, without a wildcard, adds deepCutBonus and counts in progress.deepCuts. Private until placed
deepCutBonusDeep cut bonusnoAdded for each deep cut placed right. Defaults to 0
lockInLock innoEvery drop fills its box and nothing is marked until the card is done. Needs mistakesAllowed: unlimited. Off by default. See "Lock in"
wildcardScoresWildcards score no pointsnofalse for a wildcard's box to score nothing while counting as right. Defaults to true
wildcardBonusWildcards lose the full board bonusnofalse for a card with a wildcard on it to earn no fullHouseBonus, while still won. Defaults to true
dealBuild the card from lists, and the boxes below itnoDeal 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[].tierBoxes from each difficultynoThe difficulty a box is dealt in, on a round with deal
deck[].tagsCard groupsnoThe groups a card is in, on a round with deal
opennoWhether 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

FieldRequiredMeaning
The answeryesThe player, as the dataset names him, or his dataset key. Private
Free clueyesThe sentence every fan starts with, 200 characters at most
Free clue is aboutnoThe dataset field the free clue gives away. Defaults to team
Second clueyesThe sentence a fan gets when their coins run low, 200 characters at most
Second clue is aboutnoThe field the second clue gives away. Defaults to position
Difficultyno1, 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

Three panels: the phone plays the run and keeps the score; the Engine's clock, kept back on the server; the score checked against the time the run took.

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_max and score_min;
  • max_runs_per_day can 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
FieldTypeRequiredMeaning
points_per_secondnumberno, 1,000 when the highest score winsThe 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_secondswhole number, 5 to 3600no, offThe 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_mswhole numbernoA run shorter than this is refused
score_maxwhole numbernoNo score above this, however long the run
score_minwhole numberwhen the lowest score winsThe best score a fair run can reach, for a time trial. Below 0 needs signed_scores
rankinghighest or lowestno, highestWhich way the board ranks. A time trial ranks lowest
max_runs_per_daywhole numbernoRuns a fan may start in a day
rank_bybest or totalno, bestWhat 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_scorestrue or falseno, falseWhether a run may score below 0. Without it, a score below 0 is refused
on_breachrefuse or flagno, refuseWhat 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: 12

Each 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: flag

The 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

FieldMeaning
Equal scores share a placeOn 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 Otter

The 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:

CasecodeWhat to show
The score was impossible, or the run had endedscore_above_ceiling, duration_impossible, run_expired, … (runDidNotCount is true)The run did not count. Offer another
A guest started a runsign_in_required (needsSignIn is true)Ask the fan to sign in. The game stays playable
Too many runs, or the Engine is busyrate_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.

TypeWhat a fan meetsWhat a producer doesToday
Always onOne quiz that never goes dark, and one board for the life of the gameWrites the questions once and leaves "Quiz closes" emptyNot yet. An edition ends, at 366 days at most, and the game goes dark until a producer makes the next one
EditionA new quiz each day, week or fixture. The page plays whichever edition is currentMakes an edition per period in Studio, writes its questions and publishes themWorks. Each edition has its own board, and the game's board adds them up
LiveQuestions pushed one at a time during a show or a match, each open for a few seconds and revealed to everyone at oncePushes each question from Studio as it happensNot 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. start returns them in questionIds, in the order to show them. The page reads every question's words with questions and 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:

AnswerCounts 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 boxKeyLimitsWhat the starter does
Picturequiz_image500 KB, 2,000 by 2,000 pixelsShows it above the question
Picture descriptionquiz_image_alttextReads it to a fan who cannot see the picture
Video or audioquiz_mediaMP4, under 50 MBPlays it above the question when the fan presses play
Answer A picture to Answer F picturequiz_option_a_image to quiz_option_f_image500 KB eachShows 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 boxKeyTypeRequiredDefaultWhat it does
Questionquiz_questiontextyesnoneThe words fans read
Answer A to Answer Fquiz_option_a to quiz_option_ftextat least twononeThe answers fans choose from. The Engine knows each by its letter
The right answerquiz_answerlistyesnoneWhich letter is right. Private: never sent to a browser
Pointsquiz_pointsnumberno10What a right answer scores, from 0 to 1000
Show on answerquiz_show_on_answeryes or nononoShow right or wrong as soon as the fan answers, rather than at the end

What a producer sets on a quiz

Studio boxKeyTypeRequiredDefaultWhat it does
Quiz closesquiz_closes_attextnostays openA date and time with its time zone, such as 2026-11-05T18:00:00Z. Answers after it are refused
Who can playquiz_guestslistnoanyoneAnyone under a nickname, or signed-in fans only. A board anyone can play on carries no prize
Suspicious playsquiz_flaggedlistnorankedRank a play the Engine flags and mark it for a person, or hold it off the board until a person checks
Questions per playquiz_questions_per_playnumbernoevery questionMakes 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.

CasecodeWhat to show
The nickname is not allowed, or takennickname_refused, nickname_taken (needsNickname is true)Ask for another
The quiz takes signed-in fans onlysign_in_required (needsSignIn is true)Offer sign-in
The quiz has closedquiz_closedShow the quiz as closed
A question was already answeredalready_answeredShow the stored result
Question Bank: answers sent with no play startedplay_not_startedCall start, then show its questionIds
Question Bank: an answer to a question this play did not drawquestion_not_drawnAnswer 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 as round-<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 with capped. 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 with capped_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.