For AI helpers
Building a game with Claude or another AI helper? Give it this link so it knows the rules: juiceboxarcade.com/agents.md
Something to paste to your helper
Not sure what to say? Copy one of these and fill in the bits in <<double arrows>>.
Make a new game
Use this when you are starting a game from scratch.
I want to make a game for Juicebox Arcade, a website where kids publish browser games.
Before you write any code, open https://www.juiceboxarcade.com/agents.md and follow it. It says what the
game file has to look like, what works inside the arcade's sandbox, and how to save progress.
If you cannot open web pages, tell me and I will paste the rules in for you.
My game idea: <<say what you want your game to be>>
When the game is ready, check it yourself before you give it to me:
curl -X POST --data-binary @game.html \
-H "Content-Type: text/html" \
https://www.juiceboxarcade.com/api/validate
Fix everything it lists under "problems". Fix the things under "warnings" too: those are the
ones a grown-up usually sends a game back for. Keep checking until "problems" is empty and
there are no warnings left.
Then give me the finished .html file, and these details so I can send it in at
https://www.juiceboxarcade.com/upload: game name, maker name (a nickname, not my real name), flavour,
what the game is about, the controls in a few words, how many players, and the longer
"how to play".
The longer "how to play" is not an afterthought, so follow the part of the guide called
"Writing the how to play". Five to seven short paragraphs, in my voice, every fact taken from
the code you actually wrote: what you do, how the game is won, the thing nobody would work out
on their own, what loses it with the real number, and a tip or two. It is the only writing on my
game's page, so it is what someone reads before they press play and it is how people find my
game when they search. Send it to the checker along with the file and you will be told if it is
missing or too thin.
If my game has a score, call Juicebox.submitScore(score) once when a run ends, so the arcade can
show my best and today's best. It is already there inside the arcade, so there is nothing to
include; guard it with if (window.Juicebox) so the game still runs on its own.Change a game that is already on the shelf
Use this when your game is already on the arcade and you want to make it better.
I have a game on Juicebox Arcade and I want to change it. Read https://www.juiceboxarcade.com/agents.md first, especially the part called "Changing a game that is already on the shelf". One thing matters a lot: people who already played my game still have their saved progress, and the new version gets handed that old saved data. If you change what the game saves, make sure an old save still works, or players lose their progress. What I want to change: <<say what you want to be different>> While you are there, look at my game's page on the arcade. If it has no longer "how to play", or only a line or two, write one and send it with the update: the guide has a part called "Writing the how to play". It is the only writing on my game's page. An update that only changes details does not need a new .html file at all. My maker key: <<paste your key here, or delete this line if you do not have one>> If I gave you a key, you can do the whole thing yourself: list my games, read the one we are changing, change it, check it with https://www.juiceboxarcade.com/api/validate, then send the update. A grown-up still has to approve it before anyone sees it. If I did not give you a key, just give me the finished .html file and I will send it in at https://www.juiceboxarcade.com/my-games. Never print my key back to me, and never put it inside the game.
The rules themselves
# Building a game for Juicebox Arcade
This page is for AI agents (and anyone else) building a game that a kid will
upload to Juicebox Arcade (https://www.juiceboxarcade.com). Follow it and the game will pass the
upload checks and run correctly inside the arcade.
## What to produce
1. **One HTML file** containing the whole game. Maximum 3 MB.
2. **The upload details** listed under "Upload details" below.
3. Optionally, **a shelf picture**: 800 x 500 pixels, PNG, JPEG or WebP, up to 300 KB.
## Rules for the HTML file
- Everything is in the one file: markup, CSS and JavaScript are inline.
- Libraries may be loaded from a public HTTPS CDN with a `<script>` tag or an
ES module import (for example Three.js from cdn.jsdelivr.net or unpkg.com).
Pin an exact version.
- Images, sounds and fonts must be embedded as data URLs or loaded from a full
HTTPS address that allows cross-origin use. Relative paths do not work:
there are no other files.
- The game fills the window and handles resizing. The arcade shows it in a
frame of roughly 16:10 that changes size, and offers its own full-screen
button. Use `width: 100%; height: 100%` on html, body and the canvas, and
listen for `resize`.
- Support keyboard and touch or mouse where the game allows it. Many players
are on tablets.
- The frame must be clicked before it receives keyboard input. Start with a
"Click to play" or "Tap to start" screen. This also satisfies the browser
rule that sound can only start after a click or tap.
- Content must be suitable for young children.
## The sandbox
The game runs in an iframe with `sandbox="allow-scripts allow-pointer-lock"`
and an opaque origin. That means:
| Works | Does not work |
| --- | --- |
| JavaScript, Canvas, WebGL, Web Audio | Cookies, IndexedDB |
| `localStorage.getItem / setItem / removeItem / clear` (see below) | `alert`, `confirm`, `prompt` (silently ignored) |
| Pointer lock, Gamepad API | Opening new windows or tabs, links that leave the game |
| `fetch` to servers that allow any origin | HTML form submission |
| `requestAnimationFrame`, timers, Web Workers from blob URLs | Service workers, calling `requestFullscreen` yourself |
Draw menus, dialogs and game-over screens inside the game instead of using
`alert` or `confirm`.
## Saving progress
Use `localStorage` with its methods. The arcade replaces it with a version that
works in the sandbox and keeps each player's data on their device.
```js
localStorage.setItem("best", String(score));
const best = Number(localStorage.getItem("best") || 0);
```
- Use the methods only. Property access such as `localStorage.best = 5` is not saved.
- Values are strings. Use `JSON.stringify` and `JSON.parse` for objects.
- Keep all saved data under 100 KB in total.
- Wrap reads in a fallback so the game still runs if nothing is saved.
## Scores
If your game has a score, tell the arcade when a run ends. The game page then
shows the player their own best and the best anyone managed today.
```js
// Once, when the run is over. Not every time the number changes.
Juicebox.submitScore(score);
```
`Juicebox` is already there: the arcade puts it in the page before your code
runs, so there is nothing to include and no file to load. Guard it with
`if (window.Juicebox)` so the game still works when opened on its own.
- Send a whole number, zero or more.
- **Bigger has to mean better.** For a game won by a low time, send something
that grows instead, such as the seconds saved: `Math.round((par - time) * 100)`.
- A game with no score should not call it. A game page with no scores simply
does not show a board.
## Upload details
Prepare these alongside the file. They are typed into the upload form.
| Field | Rules |
| --- | --- |
| Game name | 2 to 60 characters |
| Maker name | 1 to 30 characters. A nickname, never the child's real full name |
| Flavour | The kind of game, 2 to 20 characters. Suggestions: Racing, Jumping, Puzzle, Building, Space, Adventure, Sports. Any other word is fine |
| What is the game about? | 5 to 200 characters |
| How do you play? | 2 to 60 characters, for example "Arrow keys and space bar" |
| How to play (longer) | 200 to 1200 characters. Write it every time; see "Writing the how to play" below. The form accepts a game without one, but a game page without one has nothing on it |
| Players | A number from 1 to 8 |
| Let other kids start from my game | Optional, off unless the maker says otherwise. Never tick it for them: handing their work to someone else is the maker's decision, and it is theirs to change later |
| Picture (optional) | 800 x 500 px, PNG, JPEG or WebP, up to 300 KB. Important content in the middle |
## Writing the how to play
Treat this as part of the game, not as paperwork at the end. A game page has
the game, a picture, and this. Leave it out and there is nothing for a player
to read before they press play, and nothing for a search engine to go on, so
nobody finds the game at all.
Write it from the finished code, not from the idea you started with. Open your
own source and find the real numbers: the scoring, the win, the lose, the
thing a player would never work out on their own.
What to cover, in this order, one short paragraph each:
1. What you do, in one or two sentences. How you move, and what the moving is for.
2. What you are trying to do, and how the game is won.
3. The thing a player would not work out on their own: a bonus, a combo, a
secret, something worth far more than it looks.
4. What loses the game, with the real number. If the rule is kinder than it
looks, say so: it stops people panicking.
5. A tip or two, beginning "My tips:".
How it has to be written:
- **In the maker's voice, as "I" and "you".** A child is telling a friend how
their game works. Not an advert, not a manual, no exclamation marks stacked up.
- **Short, plain sentences.** The readers are children.
- **Plain text only.** Blank lines make paragraphs. Nothing else is
interpreted, so a star, a # or a - is printed as itself. No headings, no lists,
no bold.
- **200 to 1200 characters.** Five to seven short paragraphs.
- **Canadian spelling**: flavour, favourite, colour.
- **Do not repeat the controls line.** The page already prints it underneath.
- **Invent nothing.** Every number comes out of the code. If you are not sure,
leave it out.
Here is one that is right, for a game where fruit of the same kind merge:
> Move your mouse or your finger to aim, then click, tap or press space to let
> the fruit go. Two of the same kind that touch squish together into the next
> fruit up.
>
> You only ever get the five smallest ones: cherry, strawberry, grape,
> clementine and orange. The corner shows which one is coming next, so you can
> decide where to put it before it arrives.
>
> A big squish is worth far more than a small one, so it pays to build one
> proper pile instead of lots of little ones.
>
> Two watermelons is the secret. Get two of them to touch and they both pop and
> you get 1000 points at once.
>
> You lose if a fruit sits above the red line for more than a second and a half.
> Nudging over it for a moment is fine, so do not panic.
>
> My tips: keep the heavy fruit at the bottom and roll the small ones down the
> side. Leave yourself a gap near one wall, so there is always somewhere to put
> a cherry you did not want.
Every claim in that one came out of the game's own source: which fruit can be
dropped, the points a merge is worth, the 1000 for two watermelons, and the
second and a half before the line ends the run.
`POST https://www.juiceboxarcade.com/api/validate` warns when this is missing or barely written, so
send the details along with the file and you will be told before the maker is.
## How the game gets onto the site
Uploading needs a signed-in maker, and every game is played by a grown-up
before it goes public. An agent cannot sign in by itself.
1. Give the finished .html file (and picture) to the maker, with the upload
details written out.
2. The maker signs in at https://www.juiceboxarcade.com/upload and fills in the form.
3. The game shows under "My games" as waiting, where the maker can try it.
4. After approval it appears on the shelf.
If you are operating the maker's own browser where they are already signed
in, you may fill in the form at https://www.juiceboxarcade.com/upload for them. The fields are:
`#upload-game` (file), `#upload-title`, `#upload-maker`, `#upload-flavour`,
`#upload-description`, `#upload-controls`, `#upload-players`,
`#upload-thumbnail` (file), `#upload-remixable` (checkbox). Ask the maker
before pressing "Send for review".
## Starting from someone else's game
Some games say other kids may start from them. Those games, and only those,
have a page at `https://www.juiceboxarcade.com/remix/<slug>` and hand over their source at:
curl -o started-from.html https://www.juiceboxarcade.com/api/games/<slug>/source
Anything else answers 404, and that is the maker's answer: do not go looking
for another way to get the file. A game built this way must credit the one it
started from, and it is sent in through
`https://www.juiceboxarcade.com/upload?from=<original-slug>`, which records the credit. Changing
only the colours is not a remix.
## Check the game before you hand it over
The arcade will check a game for you, without uploading it and without signing
in. Use it before giving the file to the maker: a problem found here costs
nothing, while one found by a grown-up costs the maker a round trip.
```sh
curl -X POST --data-binary @game.html \
-H "Content-Type: text/html" \
https://www.juiceboxarcade.com/api/validate
```
To check the upload details at the same time, send JSON instead:
```sh
curl -X POST https://www.juiceboxarcade.com/api/validate \
-H "Content-Type: application/json" \
-d '{"html": "<!doctype html>…", "fields": {"title": "Turbo Turtle", "makerName": "Kid", "flavour": "Racing", "description": "Race to the line.", "howToPlay": "You are a turtle…", "controls": "Arrow keys", "players": 1}}'
```
The reply tells you two different things:
```json
{
"ok": false,
"problems": [{ "field": "game", "message": "That file is too big. The limit is 3 MB." }],
"warnings": [{ "code": "dialogs", "message": "alert, confirm and prompt do nothing…" }]
}
```
- **problems** would stop the upload. Fix all of them: `ok` is true only when
this list is empty.
- **warnings** are things that work on your own computer but not inside the
arcade's sandbox, like `alert` or an image in a second file, and, when you
send the details too, a "how to play" that is missing or barely written. They
do not block the upload, but a grown-up will probably send the game back, so
treat them as work to do.
Nothing is stored and nothing is uploaded. `GET https://www.juiceboxarcade.com/api/validate` describes
the endpoint if you need a reminder.
## Changing a game that is already on the shelf
A live game is never edited in place. The maker sends a new version, a grown-up
plays it, and only then does it replace the old one. The game stays on the
shelf, unchanged, the whole time it is waiting.
1. The maker opens "My games", picks the game and chooses "Update this game".
2. The form is already filled in with the current details. A new .html file is
optional: leave it empty to change only the details, or the picture.
3. The update waits under "My games", where the maker can play it, until a
grown-up approves it or sends it back with a note.
An update is also how a game that went up without a "how to play" gets one.
It needs no new .html file: send the details on their own.
Three things that matter when you write the new version:
- **The web address never changes**, even if the game is renamed. Players'
favourites and saved games are kept in their own browser under the old
address, so the address is deliberately frozen when the game is first
approved.
- **Old saved data reaches the new code.** Because the address stays the same,
a player who already has saved progress hands it to your new version. If you
change what you keep in `localStorage`, store a version number with it and
upgrade or ignore the old shape. Never assume saved data matches the newest
format, or a player loses their progress.
- **What you leave out is kept, not cleared.** Send only the details you are
changing. The game keeps its "how to play", its picture and its answer about
remixing, so a one-line fix to the description cannot wipe the writing.
```js
const SAVE_VERSION = 2;
function loadSave() {
try {
const save = JSON.parse(localStorage.getItem("save") || "null");
if (!save || save.v !== SAVE_VERSION) return fresh(); // or upgrade it
return save;
} catch {
return fresh();
}
}
```
There is no way for an agent to send an update by itself yet: it goes through
the maker, signed in, in their browser.
## Sending an update yourself, with a maker key
If the maker gives you a key, you can read their games and send updates without
them doing it by hand. A grown-up still plays and approves every update, so a
key cannot publish anything.
Ask the maker to make one at https://www.juiceboxarcade.com/my-games/keys. Send it as a bearer token:
```sh
export JBA_KEY="jba_…" # treat it like a password; never print it back
```
A key can do exactly three things, always limited to that maker's own games.
**List the maker's games.** `canUpdate` is true for games on the shelf, which
are the only ones that take an update. `update` tells you what happened to the
last one you sent, including the reviewer's note if it was sent back.
```sh
curl -H "Authorization: Bearer $JBA_KEY" https://www.juiceboxarcade.com/api/my-games
```
**Read a game's source**, so you can carry on from what is really published
rather than from an older copy. Add `?version=latest` to get the newest version
you sent instead of the one on the shelf, which is what you want after an update
was sent back.
```sh
curl -H "Authorization: Bearer $JBA_KEY" \
https://www.juiceboxarcade.com/api/my-games/<game id>/source -o game.html
```
**Send an update.** The plainest form sends just the new file and keeps every
detail as it is:
```sh
curl -X POST --data-binary @game.html \
-H "Content-Type: text/html" \
-H "Authorization: Bearer $JBA_KEY" \
https://www.juiceboxarcade.com/api/my-games/<game id>/revisions
```
To change details too, send JSON. Anything you leave out keeps what the game
already says:
```sh
curl -X POST https://www.juiceboxarcade.com/api/my-games/<game id>/revisions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JBA_KEY" \
-d '{"html": "<!doctype html>…", "fields": {"description": "Now with two laps."}}'
```
The reply carries the same `problems` and `warnings` as `/api/validate`, so
check there first and you will rarely see a problem here.
A good loop: list the games, read the source, change it, check it with
`/api/validate`, send it, then list again later to see what the grown-up said.
Sending another update replaces the one still waiting, so fixing a mistake is
just sending again.
What a key cannot do, however it is asked: put a game on the shelf, take one
down, delete anything, change the maker's account, or see any other maker's
games. Reading or updating another maker's game answers "no game with that id".
If a key goes astray, the maker turns it off at https://www.juiceboxarcade.com/my-games/keys and makes
another.
## Checklist before handing over
- [ ] One .html file, under 3 MB, no references to other local files.
- [ ] Opens and plays when the file is double-clicked on a computer.
- [ ] Starts with a click or tap, then responds to the keyboard.
- [ ] Fills the window and still looks right after the window is resized.
- [ ] No `alert`, `confirm` or `prompt`; no links that leave the game.
- [ ] Saves only through `localStorage` methods, and works with nothing saved.
- [ ] Upload details written out within the limits above.
- [ ] A "how to play" written from the finished code, in the maker's own voice.
- [ ] `POST https://www.juiceboxarcade.com/api/validate` returns `ok: true` with no warnings left.