# 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.
