Getting started

GameOut makes outdoor treasure hunts the children play on their phones: a trail of stations on a map, a puzzle at each, a villain who writes to them, a clock that hints cost time from, and a treasure at the end. You build the game here, print its cards, send the players one link - and watch them from the live console while they play.

1. Sign in. There is no password to make up: sign in with a link sent to your e-mail, or with a Google or GitHub account. An account is created the first time you do. Sign in
2. Open the sample game. Every new account starts with one (Sample: Operation CHEST): a whole treasure hunt with six stations, the villain, the printables and the pictures. Open it to see how a game is built, try it on your phone through its player link, print its cards. It is yours - change it, copy it, or delete it. Games
3. Build your own. A game is written on tabs: the basics and the player link, the clock and the rules, the story and the villain's texts, the stations in the order they are played, the quiz, the pictures, the villain's face. Stand at each place with your phone and press "Save my position" to set its pin. Save as often as you like - a draft with problems is fine, it just cannot be started yet. Or let an AI assistant write the game for you and paste its JSON on the Import tab - the whole definition is one document.
4. Print and prepare. The printables give you a checklist of what to hide where, the station cards with the place codes (for when the GPS fails), the villain's letter, the mirror letter, the letters for the pegs, the key tags, the Morse table and the secret card for the red filter.
5. Send the link. Switch the player link on and give it to the players - as a QR code, a message, or printed on the letter. Nobody needs an account: a player types their name (from your roster, or any name if you opened the link) and the game code, if you set one. The children in one team share one clock and one progress.
6. Watch and steer. The live console shows every team's clock, station, players and chat. You can pause the clock, add time, mark a station solved when a phone gave up, answer a call for help as the villain, move players between teams.
7. Optionally, connect a script or an assistant. An api key lets your own scripts read your games and their live state - a scoreboard on a projector, say. An AI assistant that speaks MCP can build and change the games you open to it. Both are described below. Api Access

Playing is free: a free account holds one game and a handful of players per game, which is a birthday party. A paid period lifts those caps for a fixed number of days - nothing renews on its own. Pricing & Limits

Games in this app

A game is one document in three parts: the settings (the story, the clock, the look), the stations in the order they are played, and the quiz. Everything the edit page shows is a field of that document, and the whole of it can be copied out and pasted back as JSON - which is also how an AI assistant reads and writes a game.

A station

Each station has a place (a pin and a radius in metres), a way to find it, a task, the answers it accepts, hints that cost time, and a letter it reveals. The stations unlock one after another: the players see the next one only once they solved the one before.

• Finding it - three ways: a pin on the map with the distance (the ordinary one), a photo of the place with "warmer / colder" from the GPS and no pin (a riddle), or words and the distance only.
• Arriving - the task appears once the phone is within the radius (40 m by default - the GPS in a wood is not precise). Every station also has a place code, printed on its card, that the players type when the GPS fails. Switch "tasks appear only on arrival" off and the tasks are shown at once.
• Answers - one or more accepted answers; case and diacritics do not matter, so "Beruška", "beruska" and "BERUSKA" are the same answer. A wrong answer gets a taunt from the villain, a right one the station's own line or a random cheer.
• Hints - up to three per station, in order, each costing the time the clock settings say (2 and 3 minutes by default). The "free hint" joker pays for one.
• Letters - every station may reveal one letter; the letters of all stations are the clue to the final password. Leave a station's letter empty when the password is shorter than the trail.
• A phone tool - a station may call for one of the tools built into the player page: a mirror (the camera shows the world mirrored, to read a letter written backwards), a compass (for "20 steps north"), a Morse receiver that beeps and blinks a word you set, a red filter over the camera that reveals the text hidden on the printed secret card, and an alarm button for an obstacle course. The tools are always there; naming one on the station puts its button under the task.
• For you only - "what to prepare at the place" goes to the checklist, the printables (a mirror letter, a directions card, a key tag, letters for pegs) to the printing page. The players never see them.
• The id - a short handle (s1, s2, ...) the teams' progress is stored against. Renaming or removing a station of a game being played loses the progress at it. A disabled station is skipped by the players and kept for later.

The settings

• The clock - the time limit (60 minutes by default), what hints cost, how long the freeze joker stops the clock (5 minutes), and from how many minutes left the players may win time back: dice against the villain, and quiz questions, each worth a bonus and each allowed a limited number of times. When the time is up the game goes on - the overtime is shown in red.
• The story - the villain's name and face, the letter the players read before the start, the rules, what the villain says after a wrong or a right answer, when time runs low and when it is up, and the final: the fake loading lines, the "taken over" banner, the speech, the reveal line and a postscript.
• The final - the accepted passwords, a hint, a photo of the place with the treasure and, optionally, where on the photo it is - a ring is drawn there after a countdown.
• The look - four colours of the player pages and the language of their buttons and labels (EN, CS, DE); the texts of the game are yours in whatever language you write them.
• Texts - plain, or with the tags b, i, u, em, strong, br and small; everything else is stripped. Emoji are welcome.

Pictures and the face

The pictures a station or the final shows are uploaded on the Pictures tab - JPEG or PNG up to 12 MB each, scaled down to 1600 pixels on upload - and chosen on the station from a picker with thumbnails. The villain's face is drawn for you in four moods (plain, a wink for the sign in page, sad for the final puzzle, laughing for the reveal): "Surprise me" draws a different villain every click - the shape of the head, the hair, the eyes, the nose, the mouth, the beard, the hat - or you pick a style, colours and parts yourself, and a seed draws the same villain again. Or upload one picture of a face and dress it up with a hat, glasses, a beard or a mask drawn over it.

Drafts, problems and the history

A game is written in several sittings, so it saves with problems - a station without an answer, a final without a password - and lists them. What a game with problems cannot do is be STARTED: the players' START button refuses until they are fixed.

Every save that changed something keeps the version before it on the game's history page - the last 20 changes, by you, by a shared editor or by an AI assistant, each saying what it changed. Restoring puts back the name, the language, the settings, the stations and the quiz; it never touches the switches, the pictures, the players or their progress.

The definition as JSON

The Import tab shows the current definition and takes a new one. It is one object with "settings", "stations" and "quiz"; a missing part keeps its defaults, every value is clamped to the same bounds the edit page enforces. The exact schema is what an AI assistant is handed as "capabilities" - and the sample game is the best example of all three parts filled in.

{
  "settings": {
    "villain": "Rascal",
    "time_limit_sec": 3600,
    "hint_penalty_sec": [120, 180],
    "final": {"answers": ["piano"], "hint": "It plays music."},
    "intro": {"title": "Top secret", "letter": "Hello, agents! ...", "rules": ["You have 60 minutes."]}
  },
  "stations": [
    {
      "id": "s1", "title": "The mirror message", "icon": "🪞",
      "lat": 49.8989, "lng": 18.0044, "radius": 45, "nav": "map",
      "nav_text": "Go to the end of the street...",
      "task": "Read the letter with the <b>Mirror</b> tool.",
      "tool": "mirror", "answers": ["squirrel"], "hints": ["Tap Tools - Mirror."], "letter": "P"
    }
  ],
  "quiz": [{"q": "How many legs does a spider have?", "o": ["6", "8", "10"], "a": 1}]
}

Sharing, copying and deleting

A game is shared with another account by its e-mail address, with one of two permissions. An address nobody holds yet gets the share the moment its owner first signs in.

Neither permission allows deleting the game, sharing it onward, renewing its player link or moving its AI switch - those stay with the owner, and so do the owner's size limits: a shared editor cannot add a station beyond the owner's cap. A copy is a game in the copier's account, with the same definition and pictures, no players, no progress, a new player link and play switched off - and it counts against the copier's caps.

Deleting a game removes its players, their progress, the chat, the history, the shares and the pictures, at once and for good.

Playing a game

The player link

Every game has one address - long, random and unguessable - that is the whole sign in for the players. It is off until you switch it on, and you can give it an end date. "New player link" on the edit page makes another one at once; the old one stops working and every phone is signed out.

A player opens the link and types a name. With the roster mode only the names you put on the roster (in the live console) get in; with an open link anybody with it may join by typing any name, up to the limit you set and the account's cap. A game code - a short word you tell the children - can be asked for in either mode. Names are not case sensitive, and a player who opens the link again on the same phone is still signed in for 7 days.

The phones need HTTPS, location and the camera - the page asks for them when a station needs them. Chrome and Safari on a current phone work; an old browser may lack the compass or the camera, and the place codes and the printed cards are the backup for that.

Teams

Every game starts with one team, named as the settings say, and every player joins it unless you sort them into teams in the live console. A team shares one clock, one progress, one chat and its jokers: what one child solves counts for everybody, and the page of every phone follows along within a few seconds (the phones ask for the state every 5 seconds; a player counts as online for 90 seconds after the last word).

How a game goes

1. The briefing: the villain's letter, the rules, and the START button that starts the team's clock.
2. A station: the way there (the map, the distance, the compass arrow, or "warmer / colder"), then on arrival the task, the tool, the answer box and the hints.
3. The jokers: a free hint, and a freeze that stops the clock for a few minutes - each once per team.
4. Extra time: when the clock runs low, dice against the villain and quiz questions win minutes back; when it runs out, the game goes on in overtime.
5. The chat: the villain writes to the players (that is you, in the console), the players write back, and a "we need advice" button flags the team to you.
6. The final puzzle: the letters, shuffled, and the password - then the fake loading, the villain taking over, the villain's speech (it stays until the players press Next) with the villain laughing all along - a laugh made up on the spot, or a recorded one - until the players stop it on the last screen, the countdown, the photo of the place, the statistics.

The live console

One team at a time, refreshed every few seconds: the clock, which station the team is at and how many hints it took, who is signed in and online, the chat and the log of what happened. With the edit permission you have hands on it:

• the clock - start, pause, resume, add or take minutes, finish, reset;
• the stations - mark one arrived or solved when a phone gave up, reopen one, give the hints back;
• the jokers - give them back or take them;
• the chat - write to the team, or to every team, as the villain;
• the teams and the players - add names to the roster, move a player, rename or delete a team, wipe a team's progress;
• and WIPE - every team back to the start, with or without the players, for the next group.

The printables

A page of its own, meant for the printer: the checklist (what to hide where, built from the stations), the villain's letter with the link and the code, a card per station with its place code and the directions, the mirror letter printed mirrored, the letters for the pegs, the key tags, the Morse table and the secret card - blue text under red scribbles, which the red filter on the phone (or a piece of red foil) makes readable. Print the secret card in colour; laminate everything.

Games API

Your own scripts can read your games and watch them being played: a scoreboard on a projector in the clubhouse, a bot that cheers in a chat, a home automation that rings a bell when the treasure is found. Make an api key on the Api Access page with the "Games API" scope and send it in the Authorization header. Api Access

A game is reachable when its owner switched "API access" on for it and the key's owner owns it or has it shared with them. Everything is JSON; the shape of a game is the one an AI assistant sees, so a script and an assistant reading the same account read the same fields.

curl https://gameout.xklid.net/api/v1/games/42/status \
    -H "Authorization: ApiKey <your api key>"

Answers

• 200 - the JSON described above; 201 for a message that was sent.
• 401 - the key is missing, unknown, switched off or outside its validity dates.
• 403 - the key lacks the "Games API" scope, calls from an address its IP lists refuse, or the game is not reachable: not yours, not shared, or its API access is off.
• 404 - no such game, or no such team.
• 422 - the body is not what the endpoint takes - an empty message, say - with a code and a sentence.
• 429 / 402 - out of allowance - too fast, or the day or the month is spent - with Retry-After and the X-RateLimit headers. A refused call spends nothing. How the limits are counted

The api reads and messages; it does not build games or run the clock. Building is what the web app and an AI assistant are for, and the clock is the organizer's, in the live console. More endpoints follow the same shape when they are added.

AI access (MCP)

MCP is the way an AI assistant talks to an application. This app runs an MCP server, so an assistant you already use can write a whole treasure hunt for you - the story, the stations, the hints, the quiz - straight into your account, and change it as you talk, instead of you copying things back and forth.

What an assistant can do

• List the games you opened to it - your own and the ones shared with you - and read one in full.
• Create a new game, change an existing one, or copy one.
• Watch a game being played: the teams, their clocks, where they are, who is online.
• Read this documentation, your current limits and your recent activity.

What an assistant can never do

It can never delete or share a game, add or remove players, touch the clock or message the players of a running game, upload pictures, manage api keys, change your account, see or make payments, or send e-mail. Those are not settings you have to get right - there is no way to do them at all, so nothing an assistant reads somewhere can talk it into one of them.

You decide which games it sees

Every game starts closed to AI. You switch AI access on per game, on that game's edit page. An assistant can hand a game back - it may switch AI access off - but it can never take one: switching AI access ON is always yours to do, in the web app. The one exception is a game the assistant itself created for you: that one starts open to it, so the conversation can go on, and with play switched OFF, so a half written game is never behind a live link.

Games other people share with you follow the same rule, with the switch belonging to whoever owns the game. An assistant can read and watch a shared game once its owner switched AI access on for it, and can change it only when the share gives you the "edit" permission.

The same is true of the key itself. A key allows AI access only while its "AI access" switch is on, and a new key starts without it, so no key of yours became AI-usable by being made. That one switch is all an assistant needs; the separate "Games API" switch on the same key covers your own scripts.

You can see what it did, and go back

Every change an assistant makes is marked on the game - when it happened, and whether the assistant created the game - and the version before each change is kept on the game's history page, where you can see what it changed and put it back with one click. Every call it makes is in your log.

A game an assistant writes is held to the same rules as one you write: the same bounds on every field, the same list of problems that stops a game from being started, the same caps on stations per game and games per account.

Limits

AI access has its own, tighter request limits, separate from your scripts' api limits and from anything the players do - so an assistant that misbehaves cannot use up anything else. Creating and changing games are limited far more tightly than reading. See the limits

Connecting an assistant

There are two ways, and which one you use depends on the AI app: some sign you in, some have a field for a key. Both open the same things.

By signing in

Give the AI app this address and nothing else. It sends you here to sign in, shows you what it is asking for, and you allow it. No key is made and nothing is copied anywhere:

https://gameout.xklid.net/api/mcp/

• Before you allow it, the page shows what the app calls itself and the address it will send you back to. The name is only what the app says; the address is where your approval is really delivered, so that is the one to check.
• Every app you allowed is listed under "Connected apps" on the API access page, with the day it was connected and when it was last used. "Disconnect" ends it at once - the app's next request is refused.
• You get an e-mail whenever an app is connected to your account, so a connection you did not mean to make does not go unnoticed.
• A connection ends by itself when it was not used for 30 days, and 365 days after you allowed it at the latest. Then the app asks you again.

With a key

For an AI app that has a field for a key or a header, give it the same address and one of your keys with "AI access" switched on:

POST https://gameout.xklid.net/api/mcp/
Authorization: Bearer <your api key with AI access>

The endpoint speaks JSON-RPC 2.0 over HTTP - an MCP client does the talking, you only paste the address and the key. Then ask: "write me a treasure hunt for eight year olds in the park behind our house, six stations, with a pirate as the villain" - and open the game it made on the Games page.

With a client ID and a client secret

Some AI apps sign you in but want to be set up by hand first, with a client ID and a client secret. Every key of yours has a client ID, printed on the API access page under "Use this key as an OAuth client"; the client secret is the key itself.

• Type the redirect addresses the AI app names into the key's list, one per line, exactly as the app gives them - up to 10 per key. With an empty list the key signs nobody in.
• Use one key per AI app. Each then has its own validity dates, its own on/off switch and its own IP lists, and ending one does not touch the others.
• Only you can allow an app that was set up with your key - nobody else can be signed in through it.
• Switching the key off, letting it run out or switching its "AI access" off stops every app connected through it at once. Regenerating the key ends those connections for good.

For the technical reader

The endpoint is an MCP server over the Streamable HTTP transport, in its simplest form: every message is a POST with a JSON-RPC 2.0 body and is answered with a plain JSON body. There is no event stream to subscribe to, no session id to keep, and nothing the server sends on its own - a notification is acknowledged with 202 and no body.

• Protocol revision - the server speaks 2026-07-28, which has no handshake: every request names its revision and its client's capabilities in "_meta" and mirrors revision, method and name into the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers, and "server/discover" answers what the handshake used to. Headers that do not match the body are refused with 400. Clients of the earlier revisions are served as before: "initialize" negotiates one of 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. A revision the server does not speak is refused with the list of those it does.
• Authentication - a credential in the Authorization header, and nothing else - there is no session. It is either an api key, as "Bearer <key>" or "ApiKey <key>", or an OAuth access token, as "Bearer <token>". A key needs "AI access" switched on; its validity dates, its on/off switch and its IP lists apply exactly as on the games api. Mind that a cloud AI service calls from the vendor's own addresses, not from yours - an allow list on such a key has to hold the ranges the vendor publishes, in CIDR notation.
• Origin - a request without an Origin header is an ordinary agent client and is let through. A request with one is a browser, and then the origin has to be this app's own or one the deployment allows.
• Request size - a JSON-RPC body of up to 1 MB - a whole game of thirty stations with their texts is well under a hundred kilobytes.

Signing in (OAuth 2.1)

A client that is given nothing but the endpoint's address calls it, is answered 401, and finds the rest from there: the WWW-Authenticate header of that answer names the protected resource metadata, which names the authorization server - this same application.

• Flow - the authorization code grant with PKCE, method S256, required of every client. A request without a code challenge is refused; the "plain" method is not accepted. The answer of the approval carries "iss" (RFC 9207).
• Clients - three kinds, told apart by the shape of the client ID. An https address is a Client ID Metadata Document: it is fetched, without following redirects, and has to name itself and its redirect addresses. Such a client is public (auth method "none") or signs (private_key_jwt, with its keys in the document or at its jwks_uri); a shared secret is not accepted. A client may register itself at the registration endpoint (RFC 7591); one that asks for no secret is a public client, one that will sign has to bring its keys. A registration nobody approved is deleted after a day. And every api key with "AI access" is a client: its ID is printed on the API access page, its secret is the key, its redirect addresses are the list typed there.
• Client authentication - client_secret_basic, client_secret_post, private_key_jwt (RFC 7523, algorithms RS256, RS384, RS512, ES256, ES384, ES512; the assertion names this token endpoint or issuer as its audience, is valid for at most 60 minutes and works once), or none. A client that declared how it proves itself is held to it at every exchange.
• Redirect addresses - matched character for character. Accepted are https addresses, loopback addresses over plain http (localhost, 127.0.0.1, [::1] - any port), and an app's own scheme in reversed domain name form or one of: cursor, vscode, vscode-insiders. Never a fragment, never a pattern.
• Tokens - opaque, and stored as a hash only. A code works once and for 60 seconds, an access token for 60 minutes. A refresh token is exchanged once and replaced with every exchange; it runs out after 30 days without one, and the connection 365 days after it was allowed.
• A token used twice - a code that is exchanged a second time, or a refresh token that comes back more than 60 seconds after it was exchanged, ends the whole connection: two parties held it, and nobody can tell which of them should not have.
• Without a person - the client credentials grant, for an api key only: the key's client ID and the key as the secret, in the Authorization header (Basic) or in the body. It answers with an access token and no refresh token. The key decides throughout - switched off or out of its validity dates, the token stops working on the next call.
• What a token opens - the MCP endpoint and nothing else. The games api takes api keys only, and the pages of the web app take neither.

The tools

Besides the tools, five read only resources are listed under the "gameout://" scheme: this documentation, the fixed rules of a definition (its JSON schema, the navigation modes, the phone tools), and the account's own allowance, games and activity.

Rules an assistant meets

• A game without AI access does not exist for it: not listed, not readable. A shared game is reachable once its owner switched AI access on, and writable only with the "edit" permission.
• A definition it sends is normalized by the same rules the edit page applies - a value out of bounds is clamped, an unknown tag stripped - and saved even with problems, which every answer lists. A game with problems cannot be started by the players.
• The caps of the account apply: at most so many games, so many stations per game. The answer says what the cap is and that only the account holder can lift it.
• Pictures cannot be sent; a station may name one the organizer uploaded, and get_game lists the names.
• Renaming or dropping a station of a game being played loses the teams' progress at it; the answer of update_game names the stations that went.

A credential that is missing or not good answers 401 and one that may not use the endpoint 403, both as JSON-RPC errors (codes 4010 and 4030) with a WWW-Authenticate header. A tool that ran and refused - a game it may not touch, a cap reached, arguments its schema does not accept - answers 200 with an error result the model can read and act on. Running out of allowance is a 429 or a 402, described under How the limits are counted.

How the limits are counted

Nothing here is metered and there is no balance to run out of. What exists is two kinds of limits: caps on how MUCH an account holds, and counters on how FAST its scripts and assistants may call. Playing - the children's phones - is counted against neither.

The size caps

How many games the account may hold, and how many stations, players, teams and pictures one game may have. These are what a free account notices: a few games and a handful of players is a birthday party, a paid period is a school. They are caps on what EXISTS, which is why sharing, copying and replaying a game cannot get around them:

• a game counts in the account that OWNS it, and its stations, players, teams and pictures are bounded by its owner's caps - a shared editor cannot add a ninth station to a free account's game;
• a copy is a new game in the copier's account and counts there;
• wiping a game and playing it again with the next group costs nothing - the players on the roster are the cap, not the number of times they play;
• when a period runs out the games stay as they are; what the account cannot do any more is add beyond the free caps.

The numbers themselves are on the pricing page. One account per person. Fair use

Three separate allowances

• The web app - how many of the heavier actions you take on the pages of this application per day: making or copying a game, uploading a picture, drawing or dressing up the villain's face. Saving a game you already have spends nothing, whatever the day looks like.
• Api calls - what your own scripts read through the games api.
• AI calls - every call an assistant makes through the MCP endpoint, with two tighter counters inside it: one for calls that CHANGE a game and one for calls that CREATE or copy one.

They are separate counters, not slices of one number. An assistant that misbehaves cannot use up the allowance your own scripts run on - that separation is the whole point of the AI counter.

What one call spends

How a window is counted

A daily limit runs for 24 hours from the first call that starts it, not from midnight; a monthly ceiling - the free account's - for 30 days from the first call. Every counter is asked BEFORE the work and counted AFTER it, and only when the work was done: a refused call, a failed one, a 403 and a 404 all spend nothing. The dashboard shows every counter and the moment it resets.

A script that is too fast is answered 429, one that spent its day or its month 402, both with Retry-After in seconds and the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers on every counted answer. An assistant gets the same as a JSON-RPC error (codes 4290 and 4020) and, on every ordinary answer, the remaining allowance - so it can say "there is room for two more games today" instead of being refused nine times.

The phones of one game together, and each phone on its own, are bounded per minute at numbers sized for a class polling at once - never reached by children, only by a script - and sign in attempts at one game are bounded per hour and address, since a game code is a word a child types and a word a script could guess. None of that is yours to run out of.

Your account

Signing in

Three ways, all without a password of their own: a magic link sent to your e-mail address, a Google account, or a GitHub account. Whichever you use first creates the account; the profile page lets you add more e-mail addresses and link the other sign-ins to the same account later. A game shared to any of your addresses lands in that one account. The players never sign in to anything - the player link is their whole sign in. Profile Settings

The dashboard and the log

The dashboard shows how much of the account's size you use, how much of each daily allowance is used and when it resets, what the players did lately - games started, treasures found, stations solved - the games played most, and the state of your api keys and access. Before an api key runs out you get an e-mail. Dashboard

The user log is the full record behind those numbers: every call an assistant or a script made, and the account events. The players' own events - who solved what when - are in each game's live console. Log records are kept for the period the legal notice names and then deleted. User Log

Access and billing

Every account is free, with caps that fit a family. Buying a period of days lifts the caps for its length and changes nothing else; there is no subscription and nothing to cancel. Periods bought while one is running are appended to its end. When a period runs out the games stay; adding beyond the free caps stops. Pricing & Limits

Getting help

Signed in, the contact form reaches the operator directly. Questions about how a game is built are usually answered on this page - and an AI assistant connected to your account can search it for you. Contact us

Deleting the account

Deleting the account removes the games with their pictures, players, progress, chats and history, the shares given and received, the api keys - every script and assistant using them stops at once - the addresses, the linked sign-ins and any remaining paid period, which is not refunded. It cannot be undone. What is kept, and why, is stated in the legal notice. Legal notice