# Interactive game questions

A question can be a small game: a simulation to explore, a puzzle to solve, a
lab to experiment in. You paste ONE self-contained HTML file; we run it inside
a double sandbox and record the score it reports.

## The security model (why you can trust pasted code)

- The game is served with `Content-Security-Policy: sandbox allow-scripts;
  default-src 'none'` and embedded in `<iframe sandbox="allow-scripts">`:
  it runs on an **opaque origin** with **zero network access** — no cookies,
  no storage, no fetch, no way to reach our API or anyone else's.
- The ONLY channel out is `postMessage`. The player accepts a score solely
  from its own frame, and the server **clamps it to the question's max**.
- Game scores are recorded as **client-reported** (`evaluated_by: "client"`)
  and shown to you as such — fine for practice and engagement, not for
  certificate-grade assessment. Use ordinary question types when stakes are high.

## The contract (one line)

When the student finishes, the game calls:

```js
parent.postMessage({ type: 'amatya-game:score', score: 7 }, '*');
```

`score` is a number from 0 to the question's max score. Report once, when
the attempt inside the game is over (you can allow retries first — your call).

## Prompt library — paste into ChatGPT / Claude / Gemini

> Build a single-file HTML mini-game for a test question. Requirements:
> mobile-first, self-contained (inline CSS/JS, no external URLs, no fetch),
> works inside a sandboxed iframe, and when the player finishes it MUST call
> `parent.postMessage({type:'amatya-game:score', score: N}, '*')` where N is
> 0..MAX. Theme: **[your topic — e.g. "place the fraction on a number line,
> 3 rounds, score by accuracy, MAX=6"]**. Show clear feedback and the final
> score on screen. Reply with ONLY the HTML file.

Variations that work well:

- **Estimation**: "place 3/7 on a number line, closer = more points"
- **Simulation**: "a shop till — give correct change from 500 for three purchases"
- **Sequencing**: "arrange the steps of photosynthesis in order, 2 tries"
- **Lab**: "balance the chemical equation by choosing coefficients"

## Publishing one

1. **Question bank → Add question → Interactive game (HTML)**, paste the file.
2. Set the **max score** (what a perfect run earns).
3. **Preview game** runs it in the exact taker sandbox — play it once yourself.
4. Save; the upload is rejected if the HTML never mentions the score call.

Agents: `upload_asset` accepts games too — POST the HTML to
`/api/tests/bank/assets/game`, then `add_questions` with
`{"type":"interactive","answer_spec":{"asset_id":<id>,"max_score":N}}`.