# paprika3D: the toolset that makes your coding agent a better three.js developer
https://paprika3d.com/docs/

paprika3D is a Claude Code plugin and MCP server that lets a coding agent open, look at, play, measure and fix the three.js, React Three Fiber and WebGL pages it writes, before it tells you they are done: it **sees** the scene as data, **plays** the page on an exact clock, **inspects** any mesh or value, **builds** shapes with real geometry, and **speeds up** the frame.

## Install

Needs Google Chrome and Node 20.11 or later.

```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
```

Chrome is found at its usual macOS path; elsewhere, set `PAPRIKA3D_CHROME` to the Chrome executable. For other agents, see [Other agents](#other-agents).

Docs: [https://paprika3d.com/docs](https://paprika3d.com/docs). The `window.__game` convention: [https://paprika3d.com/docs/convention](https://paprika3d.com/docs/convention). For LLMs: [https://paprika3d.com/docs/llms.txt](https://paprika3d.com/docs/llms.txt).

It works on any three.js, React Three Fiber or WebGL page: a game, a product viewer or configurator, a simulation, a shader or post-processing demo. The page needs no changes to be opened, looked at, driven and inspected.

## What your agent gets

A three.js page is one `<canvas>`: from outside it is a picture. paprika3D works inside it, with the 3D scene itself.

| Your agent asks | paprika3D answers |
|---|---|
| What is on screen? | Every named object with its share of the image and its box, plus each one that never appears, with its size and whether it is behind the camera, outside the view or too small to draw |
| Did my model load? | Reported when the page opens: the model, texture and sound files fetched, and every load that failed |
| What happens when I press Space? | The key goes in on an exact frame of a paused, seeded clock (1/60 s per frame), so the same inputs give the same frames and state every run |
| What is the game's state? | The state as JSON before and after each input |
| How big is this mesh? Is it closed? | Found without changes to the page: triangles, bounds, closed or open edges, volume and genus per mesh, and any JavaScript run against `scene`, `camera` and `renderer` |
| Is it fast enough? | Frame time, draw calls, triangles and asset size against a desktop, mobile or Quest budget |
| How do I make it faster? | `game_optimize` tries resolution scaling, instancing, LOD and disposal, and keeps only what helps without changing the picture |
| Does the hit feel like anything? | Camera shake, scale pops, eased moves versus teleports, flashes, spawned objects and sounds after an event |
| Can it build the shape I need? | `geo.js` in the project: booleans, hull, extrude, revolve and seeded scatter, with Manifold built in |

It never captures your screen: every picture is of its own headless page.

## What it catches

Here is `game_look` on a mini golf page an agent wrote from a spec that said "scale the car to 0.8":

```
On screen (14):
Mesh 17.4% [399, 240, 880, 771]
…
Never visible: ToyCar (0.0338 units, in view), Glass (0.0168 units, in view)
```

The car is there, in view, and 3 cm long on an 8-metre course. In the runs below, two agents opened a page like this, looked at the screenshot and still missed the car; this line names it.

Measured with Sonnet 5.5 in clean installs, on long, exact three.js specs that each ship a glTF model:

| | Agent alone | With paprika3D |
|---|---|---|
| Imported model left at the wrong scale or not loaded | 10 of 11 runs | 2 of 11 runs |
| Draco-compressed model that never loaded ("No DRACOLoader instance provided") | 3 of 3 runs | 0 of 3 runs |

With the tools installed but no reminder, the agent opened its page in 0 of 6 runs; with the reminder the plugin now gives once per session, 10 of 11. Game logic was right in every arm on these tasks, so the gain is in what only looking shows: imported assets, scale, framing and failed loads. A run costs about 1.5 to 2 times the dollars and 2 to 7 times the wall time. These are small samples (3 to 5 runs per task, one model).

## For agents: the loop

To ask for it in a prompt, say **use paprika3d to playtest**.

Use these tools after writing or changing any three.js, React Three Fiber or WebGL page, before saying it is done.

1. **Open it:** `game_open` with `url: "index.html"` (the folder is served) or `command: "bunx vite"`. Read the `Loaded:` and `Failed to load:` lines.
2. **Look:** `game_look`. Read `Never visible:`. An object of 0.07 units in a scene 8 units wide is at the wrong scale; `behind the camera` or `outside the view` is a framing problem. Open the picture it saves.
3. **Drive it:** for each interaction the request names, call `game_act` and read the state it returns. Use `game_clock` to step time.
4. **Ask the scene:** `game_eval` answers questions about sizes, materials and positions, and can try a change in the page before you write it into the source.
5. **Fix it, then look again.** Call `game_perf` when performance matters.

For a game with exact rules (scoring, collisions, turn order, stated numbers), lock a **game contract** with `game_contract` and call `game_check` after each change. A hook also checks after each edit in the background. The `threejs-game` skill has the full method and templates for plain three.js, React Three Fiber and Rapier.

## Tools

| Tool | What it does |
|---|---|
| `game_open` | Opens the page (a file or folder, an http URL, or a dev-server command) in headless Chrome on a paused, seeded clock, and lists the model, texture and sound files the page fetched and every fetch that failed |
| `game_look` | A picture, an ID image (one colour per object) and the list of named objects on screen, plus the named objects no look has seen yet with their size and where they are (behind the camera, outside the view, or in view but drawing no pixel); with `target`, one named object alone from the front, right, top and a three-quarter angle in one picture |
| `game_act` | Sends keys, mouse, touch or `__game.act` actions frame by frame, with the state before and after |
| `game_observe` | The page's state (its `__game.observe()`, or its named three.js objects), renderer counts, new console errors and what changed since the last observe |
| `game_eval` | Runs JavaScript in the page with `scene`, `camera`, `renderer`, `find(name)` and `stats(target)` in scope, and replies with what it returns; `stats` gives each mesh's vertices, triangles, bounds, attributes, materials, closed or open edges, volume and genus. Replies are capped at 2,048 characters, with the full text saved in the run folder |
| `game_clock` | Steps frames, pauses or resumes real-time play, sets the time scale |
| `game_feel` | Sends the steps that cause an event, then watches the next frames for camera shake, scale pops, eased moves versus teleports, colour flashes, spawned objects, HUD text ticks and sounds |
| `game_perf` | Frame time, draw calls, triangles and asset size against a budget (desktop, mobile, quest, or the contract's) |
| `game_optimize` | Only when a check says the frame is over budget, or the user asks about performance: measures, tries the runtime's switches, keeps those that help without failing a keypoint or changing the picture, writes `game-runtime.json`, and ends with the final check |
| `game_contract` | Turns the user's prompt into `game-contract.json`, written by a fresh subagent that has seen no game code; its hash is kept outside the project, so a hand-edited contract is refused |
| `game_check` | Runs the contract, each keypoint on a freshly loaded page; its last line is the frame time the keypoints stepped at, against the budget |

## Making a game checkable

Any page can be opened, looked at and driven. To check its rules, a game also exposes `window.__game` once its page has loaded:

```js
window.__game = {
  describe(),        // a short description: name, controls, units
  observe(),         // the state, exactly the keys of game-contract.json's schema, as plain JSON
  act(input),        // performs one input object: { key, down? } or { action, ...args }
  setState(partial), // sets any of the schema's keys at once; keys left out keep their values
};
// Starts playing on load: no title screen, no click to start.
// Time comes only from requestAnimationFrame / performance.now (faked, 1/60 s per frame, never more than 0.1 s a frame).
// Randomness comes only from Math.random (seeded). Keys listen on window and match event.key.
```

The full rules are in `skills/threejs-game/SKILL.md` and at [https://paprika3d.com/docs/convention](https://paprika3d.com/docs/convention).

## The runtime import

A game needs it only once a check says the frame is over budget. Then `game_optimize`, on a game without it, puts the built runtime in the project as `three-runtime.js` and asks for the import; add it once at the top of the entry file, before the renderer is made, and reopen the game:

```js
import { install } from "./three-runtime.js";
install();
```

It does nothing until `game_optimize` has written `game-runtime.json` (also into `public/` when the project has one, since vite copies only that); then it runs the switches kept there: `resolution`, `defaults`, `instancing`, `lod` and `dispose`.

## Procedural geometry

`game_open` puts `geo.js` in the project: one file with Manifold built in, for booleans, hull, extrude and revolve, plus a seeded `scatter`. Import it with `import { geo, scatter } from "./geo.js";` (`"../geo.js"` from `src/` in a vite project). Recipes are in `skills/threejs-game/references/geometry.md`.

## Other agents

The MCP server is on npm as [`paprika3d`](https://www.npmjs.com/package/paprika3d) and runs on Node 20.11 or later with Google Chrome. Point any MCP client at it:

```json
{
  "mcpServers": {
    "paprika3d": {
      "command": "npx",
      "args": ["-y", "paprika3d", "serve"]
    }
  }
}
```

| Client | One line |
|---|---|
| Codex CLI | `codex mcp add paprika3d -- npx -y paprika3d serve` |
| Gemini CLI | `gemini mcp add paprika3d npx -y paprika3d serve` |
| Cursor, VS Code, Windsurf | the JSON above in the client's MCP settings |

Every tool takes the project folder as `cwd`. The after-edit hook and the `threejs-game` skill are Claude Code features; other agents can read `AGENTS.md` and `skills/threejs-game/SKILL.md` for the same method.

## Where runs go

- `<project>/paprika3d/runs/<time>/`: each run's pictures and `run.json`. `<project>/paprika3d/state.json` holds the iteration count, the last 200 runs and how the hook reaches the running server. Add `paprika3d/` to the project's `.gitignore`.
- `~/.paprika3d/issued.json` (or `$PAPRIKA3D_HOME`): the hash of each issued contract.
- The Paprika app: when it is installed, each check, perf and optimize run is an action row dropped in `~/.paprika/spool/` (or `$PAPRIKA_HOME`), with its result, wall-clock time, iteration count and the edit that triggered it.

## License

Apache License 2.0 (`LICENSE`). The packages each build bundles keep their own licences, listed in
`THIRD_PARTY_NOTICES.md`. "paprika3D" and "paprika3d" are trademarks of Keeno Corp (`NOTICE`); forks are welcome under
the licence with their own name. Issues are welcome; see `CONTRIBUTING.md` for code.

---

# Install paprika3D
https://paprika3d.com/docs/install

## Requirements

- Google Chrome. The harness runs the page in a headless instance of it.
- Node 20.11 or later.

## Claude Code

```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
```

The plugin adds the `game_*` tools, the `threejs-game` skill and the hooks to Claude Code. After installing, ask the agent to build or fix a three.js page: the skill tells it to open and look at the page before saying it is done.

## Other agent products

Cursor, Codex, Gemini CLI and any other client that speaks MCP run the server from npm, where it is published as [`paprika3d`](https://www.npmjs.com/package/paprika3d) with provenance:

```bash
npx -y paprika3d serve
```

Register that command as a stdio MCP server in the client's configuration (`"command": "npx", "args": ["-y", "paprika3d", "serve"]`). For the Codex CLI: `codex mcp add paprika3d -- npx -y paprika3d serve`. The tools are the same; the skill and hooks are Claude Code features, so in other clients the agent needs to be told to open and look at its page (the [tools page](https://paprika3d.com/docs/tools) and the [skill](https://paprika3d.com/docs/skill) say how).

---

# Building and testing a three.js game with the harness
https://paprika3d.com/docs/skill

Runs, sees, plays, measures and speeds up any three.js, React Three Fiber or WebGL page as you build it - a game, a product viewer or configurator, a simulation, a shader or post-processing demo - in headless Chrome on a paused, seeded clock - what is on screen and what never appears (a model at the wrong scale, out of view or not loaded), frame-exact keyboard, mouse and touch input, the page state as JSON, mesh stats, feel and frame-time measurements. Use it instead of Playwright or Chrome DevTools whenever the user asks to make, fix, test, extend, screenshot or profile a three.js or WebGL page, new or existing, and before saying one is done. For a game with exact rules it can also lock a game contract that is checked after every edit.

The harness runs the game in a headless Chrome on a paused, seeded clock: you send inputs frame by frame and read back the game's state as JSON, so what you see is exact and repeatable. A **game contract** is optional: keypoints taken from the user's prompt, each a starting state, a few inputs and the values `observe()` must then return, checked after every edit.

## Order of work

1. **Start from a template** for a new game, in `${CLAUDE_PLUGIN_ROOT}/skills/threejs-game/templates/`: `plain.html` (one page, an import map, no build), `r3f.tsx` (React Three Fiber under vite) or `rapier.ts` (the `window.__game` bridge for a Rapier world, with either). Give the game a `window.__game` following the convention below. An existing game works as it is; add `window.__game` when you need its state.
2. **Open the game** with `game_open`: `url: "index.html"` for a plain page (the folder is served), or `command: "bunx vite"` for a vite project. Open it once: after each edit the next tool call reloads the page by itself.
3. **Build, playing as you go.** After each change, play the inputs that matter with `game_act` (and `game_clock`), read the state it returns or `game_observe`, and look with `game_look` (`game_act` with `look: true` returns the picture after its steps in the same call; `sheet` shows several stages, levels or views in one picture). `game_eval` inspects the scene or tries a change in the page before you write it into the source.
4. **Feel.** When the user's request says how the game should look and feel (its feel brief), for each event it names call `game_feel` with the inputs that cause it (set the state up first with `game_act`) and read what reacted. Every event the brief says should feel like something must show at least one reaction (a pop, a flash, a shake, particles, a HUD tick, a sound), and motion the brief calls eased or snappy must show eased moves and no teleports. Fix what does not, and rerun `game_feel`.

## Game contract (optional)

Use one when the game has exact rules where one misread breaks it (scoring, collisions, matching, clearing and refilling, turn order, stated numbers), or when the user asks for a locked spec or tests. Otherwise skip it.

1. Before writing game code, call `game_contract` with the project folder (`cwd`) and, as `prompt`, everything the user wrote about the game, verbatim: the request and any interface, rules or numbers that came with it, since the subagent sees nothing else. It writes a brief and tells you the one-line prompt to start a fresh subagent with: the Agent tool, in the foreground, model sonnet. That subagent drafts and issues the contract, and its reply gives you the keypoints and the `observe()` schema. Never read the brief, the draft or `game-contract.json` yourself: a failing `game_check` tells you the state and values a keypoint needs. Make `window.__game` return exactly the schema's keys.
2. `game_open` then ends with the first check of the contract, so do not call `game_check` until you have changed something.
3. Call `game_check` after every change. A hook also checks after each edit, in the background, and tells you only when the failing keypoints change: no message means the result is the same as the last one you saw. What each failure means is in `references/contract.md`. Do the feel step once the contract passes, and rerun `game_check` after its fixes.
4. **Before saying it is done:** call `game_check` once more, so the final result is a full run of the whole contract and nothing is left to a background check that would be lost when the session ends.

## Performance

Call `game_optimize` only when a check or `game_perf` result says the frame is over budget, or when the user asks about performance (stutter, or a phone target: then measure with `game_perf` and `budget: "mobile"` first). How it works, and the runtime import it asks for: `references/optimize.md`.

## Procedural geometry

Build shapes in code, with three's own geometries plus `geo.js`, which `game_open` puts in the project: `import { geo, scatter } from "./geo.js"` (`"../geo.js"` from `src/` in a vite project). It gives booleans, hull, extrude and revolve through Manifold, and a seeded `scatter`.
After each build step, give the mesh a name and call `game_eval` with `return stats("<name>")`: check its triangles, that it is `closed`, and its volume.
Use `game_eval` to try a change in the running game before writing it into the source; what it changes vanishes on reload.
Recipes (scatter, arrays, curves, booleans, revolve, hull, level sets, rounding) and pitfalls: `references/geometry.md`.

## The `window.__game` convention

Once the page has loaded, it exposes:

```js
window.__game = {
  describe(),        // a short description: name, controls, units
  observe(),         // the state, exactly the keys of game-contract.json's schema, as plain JSON
  act(input),        // performs one input object: { key, down? } or { action, ...args }
  setState(partial), // sets any of the schema's keys; keys left out keep their values
};
```

`observe`, `look`, `perf` and `optimize` work on any three.js page; `game_check` needs all four functions.

### Rules

- The game starts playing as soon as the page loads: no title screen and no click to start.
- **Time.** The harness steps frames one at a time, 1/60 s each, on a fake clock (`requestAnimationFrame`, `performance.now`, `Date`, timers). Advance the game by each frame's elapsed time, or a fixed 1/60 s per frame, and never by more than 0.1 s in one frame. Count the first frame as one frame: the clock jumps forward when the page finishes loading, so time read before the first frame is not game time. Speeds are per second of game time. Never read real time some other way.
- **Randomness.** Use `Math.random`; the harness seeds it, so a check sees the same game every time.
- **setState** takes effect at once: the next `observe()` returns the new values, and the game's own start-up must not undo them, even when `setState` runs before the first frame. Objects and lists are replaced whole, with the same fields `observe()` returns.
- **observe()** returns plain JSON (numbers, booleans, strings, null, objects, arrays), never three.js objects. Lists keep their order: new items at the end, removed items dropped.
- **Keys** listen on `window` and match `event.key`. A key can go down and up within one frame, so one-shot controls (turn, jump, fire) act on `keydown`; held controls (move, steer) last from `keydown` to `keyup`. Route real key events and `act({ key })` through the same function.
- **Names.** Give meshes a `name` (`player`, `enemy3`, `coin`): `game_look` lists what is on screen by name.

`templates/plain.html` is a complete small game in this shape. In React, keep the game state in a plain module outside components (as `templates/r3f.tsx` does), so `setState` and `observe` never wait for a render, and set `window.__game` in the Canvas's `onCreated`: the harness starts stepping frames once `__game` exists.

## Never

- With a contract, never edit `game-contract.json` by hand or from a shell: a changed contract is refused. To change what the game must do, run `game_contract` again with the user's new prompt.
- Never change a keypoint's expected values by changing the game's `observe()` to report something the game does not do.

---

# The window.__game convention
https://paprika3d.com/docs/convention

Any three.js, React Three Fiber or WebGL page can be opened, looked at and driven without it: `game_open`, `game_look`, `game_observe` (which falls back to the page's named three.js objects), `game_eval`, `game_act` with keys, mouse and touch, `game_feel`, `game_perf` and `game_optimize` work on a page that knows nothing about the harness. To check a game's rules, the game also exposes `window.__game`, and `game_check` needs all four of its functions.

Once the page has loaded, it exposes:

```js
window.__game = {
  describe(),        // a short description: name, controls, units
  observe(),         // the state, exactly the keys of game-contract.json's schema, as plain JSON
  act(input),        // performs one input object: { key, down? } or { action, ...args }
  setState(partial), // sets any of the schema's keys; keys left out keep their values
};
```

`observe`, `look`, `perf` and `optimize` work on any three.js page; `game_check` needs all four functions.

## Rules

- The game starts playing as soon as the page loads: no title screen and no click to start.
- **Time.** The harness steps frames one at a time, 1/60 s each, on a fake clock (`requestAnimationFrame`, `performance.now`, `Date`, timers). Advance the game by each frame's elapsed time, or a fixed 1/60 s per frame, and never by more than 0.1 s in one frame. Count the first frame as one frame: the clock jumps forward when the page finishes loading, so time read before the first frame is not game time. Speeds are per second of game time. Never read real time some other way.
- **Randomness.** Use `Math.random`; the harness seeds it, so a check sees the same game every time.
- **setState** takes effect at once: the next `observe()` returns the new values, and the game's own start-up must not undo them, even when `setState` runs before the first frame. Objects and lists are replaced whole, with the same fields `observe()` returns.
- **observe()** returns plain JSON (numbers, booleans, strings, null, objects, arrays), never three.js objects. Lists keep their order: new items at the end, removed items dropped.
- **Keys** listen on `window` and match `event.key`. A key can go down and up within one frame, so one-shot controls (turn, jump, fire) act on `keydown`; held controls (move, steer) last from `keydown` to `keyup`. Route real key events and `act({ key })` through the same function.
- **Names.** Give meshes a `name` (`player`, `enemy3`, `coin`): `game_look` lists what is on screen by name.

`templates/plain.html` is a complete small game in this shape. In React, keep the game state in a plain module outside components (as `templates/r3f.tsx` does), so `setState` and `observe` never wait for a render, and set `window.__game` in the Canvas's `onCreated`: the harness starts stepping frames once `__game` exists.

The harness sends keys, mouse and touch as real browser events, so the game's own listeners receive them. An `{ action, ...args }` object reaches `__game.act` whole.

## The contract file: game-contract.json

A game contract is what the user's prompt promises, as keypoints the harness can check: each sets a state through `setState`, sends a bounded list of inputs, steps a fixed number of frames and then tests predicates over `observe()`. Only `game_contract` writes it. It gives a fresh subagent, one that has seen no game code, the format below and the user's prompt; the subagent drafts the contract and the harness validates it and saves it as `<project>/game-contract.json`. `game_check` runs it against the open game.

### Fields

| Field | Type | Meaning |
|---|---|---|
| `v` | `1` | The format version. |
| `prompt` | string | The user's prompt, verbatim, so the contract says where each rule comes from. |
| `issued` | string | An ISO time, stamped by the harness when it saves the file. The subagent leaves it out. See "How issued works". |
| `schema` | object | Mirrors what `observe()` returns. Leaves are strings of the form `"type: meaning"` (`"number: column 0..19"`), nested objects are objects, and an array holds one item shape (`[{ "x": "number", "y": "number" }]`). It is also the contract for the game code: `observe()` returns exactly these keys. |
| `keypoints` | Keypoint[] | A non-empty list; the subagent is asked for 8 to 20, one behaviour each, covering every rule the prompt states and its edge cases. |
| `budget` | object, optional | The budget `game_check`, `game_perf` and `game_optimize` measure against instead of the desktop default; `frameMs` is the frame time in milliseconds. |

### Keypoint

| Field | Type | Meaning |
|---|---|---|
| `id` | string | Unique within the contract, kebab-case. |
| `title` | string | What the player would notice, such as "eating food grows the snake by one". |
| `state` | object | Passed to `window.__game.setState()` on a freshly loaded page. Every top-level key must be in `schema`. Set every value the outcome depends on, so no keypoint depends on another or on the starting layout. |
| `actions` | Action[] | The inputs, in order; the list may be empty. Each advances one frame unless it says `frames`. |
| `frames` | number, optional | Frames stepped after the actions, 0 to 600 (ten seconds at 60 fps). 60 when left out. |
| `expect` | Predicate[] | At least one predicate; all must hold for the keypoint to pass. |

### Actions

An action is one object with exactly one of these keys:

```ts
type Action =
  | { key: string; down?: boolean; frames?: number }                   // a key by event.key; down and up in one frame unless down is given
  | { mouse: "click" | "down" | "up" | "move"; x: number; y: number; button?: string }
  | { touch: "start" | "move" | "end"; x: number; y: number }
  | { wait: number }                                                   // frames to step with no input
  | { action: string; [arg: string]: any };                            // reaches __game.act whole, with its arguments
```

### Predicates

```ts
interface Predicate { path: string; op: Op; value?: unknown }
type Op = "==" | "!=" | "<" | "<=" | ">" | ">=" | "exists";
```

`path` is dotted and must resolve in `schema`: object keys, then on an array an index or `length` (`head.x`, `body.length`, `body.0.x`). `exists` takes no value; the other operators compare the observed value with `value`, and `==` and `!=` compare deeply, so `value` can be an object or an array.

### How a check runs

`game_check` runs every keypoint on a freshly reloaded page: `setState(state)`, confirmed in `observe()` before any frame runs; then each action, one frame each unless it says `frames`; then `frames` more frames; then every predicate in `expect` over `observe()`. A keypoint ends in one of four outcomes:

| Outcome | Meaning |
|---|---|
| `launch_failed` | The page did not load or draw a frame. |
| `state_not_realized` | After `setState`, `observe()` did not return those values. |
| `actions_incomplete` | An input could not be sent or `act` threw. |
| `outcome_mismatch` | A predicate did not hold; the line says what was expected and what was observed. |

A failing keypoint saves a picture of the page in the run folder. The result's last line is the frame time the keypoints stepped at, against the budget. When a result ends with "stale", the sources changed while it ran. A hook also runs the check after each edit, in the background.

### How `issued` works

The subagent that writes the contract leaves `issued` out. When the harness saves the contract it stamps `issued` with the current time, writes `<project>/game-contract.json`, and records the project path with a SHA-256 hash of the file in `~/.paprika3d/issued.json` (or `$PAPRIKA3D_HOME/issued.json`), outside the project. The hash is taken over the JSON with its keys sorted at every level, so formatting and key order do not matter. The coding agent is never told the hash.

Each time `game_check` loads the contract it hashes the file again. A hash that differs from the record is refused with "game-contract.json was changed by hand; run game_contract again with the user's prompt", and a guard hook in the plugin refuses edits to the file as well. To change what the game must do, run `game_contract` again with the user's new prompt. A file with no record for its project (another machine, or a file under another name such as `game-tests.json`) loads without the comparison and is only validated.

### Example

The contract of the `snake` fixture, written from the prompt in its `prompt` field:

```json
{
  "v": 1,
  "prompt": "Snake on a 20x20 grid. The snake moves one cell per frame and the arrow keys steer it, but it can't reverse into itself. Eating food grows it by one and scores a point. Hitting a wall or its own body kills it. Two portals: entering one puts the snake on the cell just past the other, still moving the same way.",
  "issued": "2026-10-11T00:00:00.000Z",
  "schema": {
    "frame": "number: frames since load",
    "score": "number: food eaten",
    "alive": "boolean",
    "head": { "x": "number: column 0..19", "y": "number: row 0..19, up is +y" },
    "body": [{ "x": "number", "y": "number" }],
    "food": { "x": "number", "y": "number" },
    "portals": [{ "x": "number", "y": "number" }],
    "dir": "string: up | down | left | right"
  },
  "keypoints": [
    {
      "id": "moves-one-cell-per-frame",
      "title": "the snake moves one cell per frame and its body follows",
      "state": { "alive": true, "dir": "right", "head": { "x": 3, "y": 3 }, "body": [{ "x": 2, "y": 3 }, { "x": 1, "y": 3 }], "food": { "x": 10, "y": 10 } },
      "actions": [],
      "frames": 3,
      "expect": [
        { "path": "head.x", "op": "==", "value": 6 },
        { "path": "head.y", "op": "==", "value": 3 },
        { "path": "body.0.x", "op": "==", "value": 5 },
        { "path": "body.length", "op": "==", "value": 2 }
      ]
    },
    {
      "id": "turn-up",
      "title": "ArrowUp turns the snake up",
      "state": { "alive": true, "dir": "right", "head": { "x": 3, "y": 3 }, "body": [{ "x": 2, "y": 3 }, { "x": 1, "y": 3 }], "food": { "x": 10, "y": 10 } },
      "actions": [{ "key": "ArrowUp" }],
      "frames": 2,
      "expect": [
        { "path": "dir", "op": "==", "value": "up" },
        { "path": "head.x", "op": "==", "value": 3 },
        { "path": "head.y", "op": "==", "value": 6 }
      ]
    },
    {
      "id": "no-reverse",
      "title": "pressing the opposite direction does not reverse the snake",
      "state": { "alive": true, "dir": "right", "head": { "x": 3, "y": 3 }, "body": [{ "x": 2, "y": 3 }, { "x": 1, "y": 3 }], "food": { "x": 10, "y": 10 } },
      "actions": [{ "key": "ArrowLeft" }],
      "frames": 0,
      "expect": [
        { "path": "dir", "op": "==", "value": "right" },
        { "path": "head.x", "op": "==", "value": 4 },
        { "path": "alive", "op": "==", "value": true }
      ]
    },
    {
      "id": "eat-grows",
      "title": "eating food grows the snake by one and scores a point",
      "state": { "alive": true, "score": 0, "dir": "right", "head": { "x": 3, "y": 3 }, "body": [{ "x": 2, "y": 3 }, { "x": 1, "y": 3 }], "food": { "x": 4, "y": 3 } },
      "actions": [],
      "frames": 1,
      "expect": [
        { "path": "score", "op": "==", "value": 1 },
        { "path": "body.length", "op": "==", "value": 3 },
        { "path": "head.x", "op": "==", "value": 4 },
        { "path": "food", "op": "!=", "value": { "x": 4, "y": 3 } }
      ]
    },
    {
      "id": "wall-kills",
      "title": "running into a wall kills the snake and it stops",
      "state": { "alive": true, "dir": "right", "head": { "x": 19, "y": 10 }, "body": [{ "x": 18, "y": 10 }, { "x": 17, "y": 10 }], "food": { "x": 10, "y": 10 } },
      "actions": [],
      "frames": 3,
      "expect": [
        { "path": "alive", "op": "==", "value": false },
        { "path": "head.x", "op": "==", "value": 19 }
      ]
    },
    {
      "id": "self-collision-kills",
      "title": "turning into its own body kills the snake",
      "state": { "alive": true, "dir": "left", "head": { "x": 5, "y": 5 }, "body": [{ "x": 6, "y": 5 }, { "x": 6, "y": 6 }, { "x": 5, "y": 6 }, { "x": 4, "y": 6 }], "food": { "x": 10, "y": 10 } },
      "actions": [{ "key": "ArrowUp" }],
      "frames": 0,
      "expect": [
        { "path": "alive", "op": "==", "value": false },
        { "path": "head.y", "op": "==", "value": 5 }
      ]
    },
    {
      "id": "tail-chase-safe",
      "title": "moving onto the cell the tail is leaving is safe",
      "state": { "alive": true, "dir": "up", "head": { "x": 5, "y": 5 }, "body": [{ "x": 5, "y": 4 }, { "x": 6, "y": 4 }, { "x": 6, "y": 5 }], "food": { "x": 10, "y": 10 } },
      "actions": [{ "key": "ArrowRight" }],
      "frames": 0,
      "expect": [
        { "path": "alive", "op": "==", "value": true },
        { "path": "head.x", "op": "==", "value": 6 },
        { "path": "head.y", "op": "==", "value": 5 },
        { "path": "body.length", "op": "==", "value": 3 }
      ]
    },
    {
      "id": "portal-exit",
      "title": "entering a portal comes out on the cell just past the other one",
      "state": { "alive": true, "dir": "right", "head": { "x": 4, "y": 15 }, "body": [{ "x": 3, "y": 15 }, { "x": 2, "y": 15 }], "food": { "x": 10, "y": 10 }, "portals": [{ "x": 5, "y": 15 }, { "x": 14, "y": 4 }] },
      "actions": [],
      "frames": 1,
      "expect": [
        { "path": "head.x", "op": "==", "value": 15 },
        { "path": "head.y", "op": "==", "value": 4 },
        { "path": "dir", "op": "==", "value": "right" }
      ]
    },
    {
      "id": "dead-stays-still",
      "title": "a dead snake does not move",
      "state": { "alive": false, "dir": "right", "head": { "x": 3, "y": 3 }, "body": [{ "x": 2, "y": 3 }, { "x": 1, "y": 3 }], "food": { "x": 10, "y": 10 } },
      "actions": [{ "key": "ArrowUp" }],
      "frames": 5,
      "expect": [
        { "path": "alive", "op": "==", "value": false },
        { "path": "head.x", "op": "==", "value": 3 },
        { "path": "head.y", "op": "==", "value": 3 }
      ]
    }
  ]
}
```

---

# The paprika3d tools
https://paprika3d.com/docs/tools

Every tool works on the page `game_open` opened in headless Chrome. The names and descriptions below are the ones the MCP server registers, read from `src/server.ts` at build time.

| Tool | What it does |
|---|---|
| `game_contract` | For a game with exact rules (scoring, collisions, matching, turn order, stated numbers) or when the user asks for a locked spec or tests, call it before writing game code: it turns the user's prompt into a game contract (keypoints the game must pass). It writes a brief for a fresh subagent that has seen no game code and tells you how to start it; that subagent drafts and issues the contract and replies with the keypoints. Never edit game-contract.json by hand. |
| `game_open` | Opens a three.js, React Three Fiber or WebGL page (a game, viewer, configurator, simulation or shader demo) in a headless Chrome on a paused, seeded clock, closing any page already open, and lists the files it loaded and any that failed. Open once: after an edit, the next game_act, game_look, game_observe, game_eval, game_clock or game_feel reloads the page by itself. Call it after writing or changing such a page, before saying it is done. Give a file or folder to serve (`url`, relative to cwd), an http URL, or a dev-server `command` run in cwd. When cwd holds a game contract, the result ends with its first check. |
| `game_observe` | The open page's state (window.__game.observe(), or its named three.js objects), renderer counts, new console errors and what changed since the last observe. |
| `game_eval` | Runs JavaScript in the open page and returns what it returns, as JSON. In scope: scene, camera, renderer, find(name), stats(target) (vertices, triangles, bounds, closed, volume, genus per mesh), realNow() and window. performance.now and Date run on the harness's paused clock, so to time code here use realNow() (real milliseconds), and end GPU work with a 1-pixel gl.readPixels before reading it. Use it to inspect the scene, try a change before writing it into the source, measure an imported model, or check procedural geometry with stats after each step; changes vanish on reload. |
| `game_act` | Sends input to the open page, frame by frame: { key, down?, frames? }, { mouse: click\|down\|up\|move, x, y }, { touch: start\|move\|end\|tap, x, y }, { wait: frames, draw? } or { action, ...args } for window.__game.act; draw: false on a long wait runs its frames without drawing all but the last (much faster; leave it out when the picture builds up over frames, like trails). Each step advances `frames` (default 1). Returns the state after and what changed; with `look: true` also game_look's picture and list after the steps, in the same reply. |
| `game_clock` | Controls the open page's clock: step n frames, pause or resume real-time play, set the time scale. |
| `game_look` | Saves a screenshot of the open page (returned in the reply, so there is no file to read) and an ID image (one colour per object), and lists what is on screen and the named objects no look has seen, with their size and where they are: it catches a model at the wrong scale, out of view or never loaded, which a screenshot alone misses. Call it after game_open and after each visible change. `camera` views from another place for this picture only. A game drawn in passes (post-processing) is pictured as it drew its last frame, so state set since then shows after a step. `target` instead pictures one named object alone from the front, right, top and a three-quarter angle, framed to its size, in one picture: use it to check a model or procedural shape from every side. `sheet` instead pictures up to 9 moments in one labelled grid, each on a freshly reloaded page set with `state`, played with `steps` (as game_act) and `frames`: use it to compare stages, levels or views at once instead of a screenshot script. `zoom` instead pictures one part of the screen enlarged up to 4×, for detail too small to judge (an edge, text, a distant object). |
| `game_feel` | Measures how the page reacts to an event: sends the steps, then watches the next frames for camera shake, scale pops, eased motion versus teleports, colour flashes, spawned particles, HUD text ticks and sounds. Use it on every event the user's feel brief names (hits, clears, explosions, pickups, deaths, wins) to check they feel like something, and to confirm nothing teleports. |
| `game_check` | Runs the game contract against the open game, each keypoint on a fresh page. When the project has a game contract, call it after every change to the game, and once more just before saying the game is done. |
| `game_perf` | Call when a check reports the frame over budget or the user asks about performance (stutter, low fps, a phone target): measures frame time, draw calls, triangles and asset size of the open page against a budget (desktop by default, or the contract's). To find what costs the frame, give `variants`: each is measured on a fresh page against the baseline, in this one call, with named objects hidden, a pixel ratio, code run with `renderer` and `scene` (shadows or antialias off, a material swapped), or a `query` the page loads with ("noshadow&pr=0.5", for switches the game reads at load); no reopening or reload code needed. |
| `game_optimize` | Call only when a check reports the frame over budget or the user asks about performance: measures the frame time (no game_perf needed first), tries the @paprika3d/three-runtime switches on the open page, keeps those that help without failing a keypoint or changing the picture, writes game-runtime.json, and ends with the final game_check of the whole contract. |

## Not in the stable build

These tools exist in the source but the published plugin does not list them:

| Tool | What it does | Availability |
|---|---|---|
| `game_invariants` | Runs built-in checks any game must pass, no contract needed: the window.__game convention, plain-JSON observe(), setState round-trip, inputs change the state, no console errors, and the same inputs give the same state twice. Call it once the game opens and after any change to the game's state handling. | Benchmark only: the `lean` arm of the benchmark (`bench/README.md` in the development repository) lists it in place of `game_contract` and `game_check`. |
| `game_test` | Runs your own tests in <project>/game-tests.json (same format as a game contract: v, prompt, schema, keypoints) against the open game, each keypoint on a fresh page. Call it after every change. | Benchmark only: the `lean` arm lists it in place of `game_contract` and `game_check`. |
| `game_asset` | Finds a ready-made CC0 model for one thing the game needs and copies it into the project with the exact code to load and place it. Call it with a short `query` naming the thing and, when you know it, its `role`; it answers with Best plus up to two alternates. Take Best unless it clearly misses the brief; if it does, call again with `not` listing the rejected ids. `pick` copies one result into the project and returns the loading code (`height` scales it to your world's units); `inspect` describes any GLB file. | Dev build only, and listed only with `PAPRIKA3D_ASSETS=1`; the stable build leaves it out. |

How the tools fit together is in the [skill](https://paprika3d.com/docs/skill); what `game_check` needs from a game is on the [convention page](https://paprika3d.com/docs/convention).

---

# Templates: plain three.js, React Three Fiber and Rapier
https://paprika3d.com/docs/templates

The `threejs-game` skill starts a new game from one of these three files. Each is a complete small game in the shape the [convention](https://paprika3d.com/docs/convention) describes: replace the rules, keep the shape. They ship inside the plugin at `skills/threejs-game/templates/`.
## plain.html

One page, an import map and no build step. Arrow keys move a box; touching the coin scores and moves it. The state lives in plain variables, `step(dt)` runs once per frame, keys and `act()` share one input path, and `window.__game` is set at the end.

```html
<!doctype html>
<!-- Plain three.js template: one page, no build. Arrow keys move a box; touching the coin scores and moves the coin.
     Needs `bun add three` (the import map points into node_modules). Open it with game_open { url: "index.html" }. Replace the rules, keep the shape:
     state in plain variables, step(dt) once per frame, one input path for keys and act(), window.__game at the end. -->
<html><head><meta charset="utf-8"><title>Game</title>
<style>html,body{margin:0;background:#111;overflow:hidden}canvas{display:block}</style></head>
<body>
<script type="importmap">{"imports":{"three":"./node_modules/three/build/three.module.js"}}</script>
<script type="module">
import * as THREE from 'three';

const SPEED = 4;                       // units per second
const held = new Set();
let score = 0;
let player = { x: 0, y: 0 }, coin = { x: 3, y: 2 };

function step(dt) {
  player.x += ((held.has('ArrowRight') ? 1 : 0) - (held.has('ArrowLeft') ? 1 : 0)) * SPEED * dt;
  player.y += ((held.has('ArrowUp') ? 1 : 0) - (held.has('ArrowDown') ? 1 : 0)) * SPEED * dt;
  if (Math.hypot(player.x - coin.x, player.y - coin.y) < 0.8) {
    score++;
    coin = { x: Math.round(Math.random() * 8 - 4), y: Math.round(Math.random() * 6 - 3) };   // Math.random: the harness seeds it
  }
}

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(50, innerWidth / innerHeight, 0.1, 100);
camera.position.set(0, 0, 12);
scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 2));
const box = new THREE.Mesh(new THREE.BoxGeometry(0.8, 0.8, 0.8), new THREE.MeshStandardMaterial({ color: 0xffa040 }));
box.name = 'player'; scene.add(box);   // names show in game_look's on-screen list
const gem = new THREE.Mesh(new THREE.SphereGeometry(0.3), new THREE.MeshStandardMaterial({ color: 0xffe14d }));
gem.name = 'coin'; scene.add(gem);

let last = null;
function loop(now) {
  requestAnimationFrame(loop);
  // elapsed game time, never more than 0.1 s a frame; the first frame counts as one (time before it was the page loading)
  step(last === null ? 1 / 60 : Math.min((now - last) / 1000, 0.1));
  last = now;
  box.position.set(player.x, player.y, 0);
  gem.position.set(coin.x, coin.y, 0);
  renderer.render(scene, camera);
}
requestAnimationFrame(loop);

// One input path for real keys and the harness's act().
const act = ({ key, down = true }) => { if (down) held.add(key); else held.delete(key); };
addEventListener('keydown', e => act({ key: e.key }));
addEventListener('keyup', e => act({ key: e.key, down: false }));

const copy = (p) => ({ x: +p.x.toFixed(3), y: +p.y.toFixed(3) });
window.__game = {
  describe: () => ({ name: 'coin collector', units: 'world units, y up', keys: { ArrowLeft: 'hold to move left', ArrowRight: 'hold to move right', ArrowUp: 'hold to move up', ArrowDown: 'hold to move down' } }),
  observe: () => ({ score, player: copy(player), coin: copy(coin) }),
  act,
  setState: (s) => {   // every schema key, applied at once
    if (s.score !== undefined) score = s.score;
    if (s.player) player = { ...s.player };
    if (s.coin) coin = { ...s.coin };
  },
};
</script>
</body></html>
```

## r3f.tsx

React Three Fiber under vite. The game state lives in a plain module object outside React, so `setState` and `observe()` never wait for a render; components only draw it. One `useFrame` advances the rules by the frame's delta, at most 0.1 s, and `window.__game` is set in the Canvas's `onCreated`.

```tsx
// React Three Fiber template (vite: `bun create vite . --template react-ts`, then `bun add three @react-three/fiber`).
// The game state lives in a plain module object outside React, so setState and observe() never wait for a render;
// components only draw it. One useFrame advances the rules by the frame's delta, at most 0.1 s, and the first frame by
// one frame.
// Replace the rules, keep the shape.
import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { Canvas, useFrame } from '@react-three/fiber';
import type { Mesh } from 'three';

type Vec = { x: number; y: number };
const SPEED = 4;   // units per second
const game = { score: 0, player: { x: 0, y: 0 } as Vec, coin: { x: 3, y: 2 } as Vec };
const held = new Set<string>();
let started = false;

function step(dt: number) {
  const p = game.player;
  p.x += ((held.has('ArrowRight') ? 1 : 0) - (held.has('ArrowLeft') ? 1 : 0)) * SPEED * dt;
  p.y += ((held.has('ArrowUp') ? 1 : 0) - (held.has('ArrowDown') ? 1 : 0)) * SPEED * dt;
  if (Math.hypot(p.x - game.coin.x, p.y - game.coin.y) < 0.8) {
    game.score++;
    game.coin = { x: Math.round(Math.random() * 8 - 4), y: Math.round(Math.random() * 6 - 3) };   // the harness seeds Math.random
  }
}

// One input path for real keys and the harness's act().
const act = ({ key, down = true }: { key: string; down?: boolean }) => { if (down) held.add(key); else held.delete(key); };
addEventListener('keydown', e => act({ key: e.key }));
addEventListener('keyup', e => act({ key: e.key, down: false }));

const copy = (v: Vec) => ({ x: +v.x.toFixed(3), y: +v.y.toFixed(3) });
// Installed from the Canvas's onCreated, not here: the harness starts stepping frames once __game exists, and before
// the Canvas has mounted those frames would draw nothing and run no useFrame.
const bridge = {
  describe: () => ({ name: 'coin collector', stack: 'react-three-fiber', keys: { ArrowLeft: 'hold', ArrowRight: 'hold', ArrowUp: 'hold', ArrowDown: 'hold' } }),
  observe: () => ({ score: game.score, player: copy(game.player), coin: copy(game.coin) }),
  act,
  setState: (s: Partial<typeof game>) => {   // every schema key, applied at once
    if (s.score !== undefined) game.score = s.score;
    if (s.player) game.player = { ...s.player };
    if (s.coin) game.coin = { ...s.coin };
  },
};

function Scene() {
  const player = useRef<Mesh>(null), coin = useRef<Mesh>(null);
  useFrame((_, delta) => {
    step(started ? Math.min(delta, 0.1) : 1 / 60);   // the first delta also spans the page's load: count it as one frame
    started = true;
    player.current!.position.set(game.player.x, game.player.y, 0);
    coin.current!.position.set(game.coin.x, game.coin.y, 0);
  });
  return (
    <>
      <hemisphereLight args={['#ffffff', '#334455', 2]} />
      {/* names show in game_look's on-screen list */}
      <mesh ref={player} name="player"><boxGeometry args={[0.8, 0.8, 0.8]} /><meshStandardMaterial color="orange" /></mesh>
      <mesh ref={coin} name="coin"><sphereGeometry args={[0.3]} /><meshStandardMaterial color="gold" /></mesh>
    </>
  );
}

createRoot(document.getElementById('root')!).render(
  <Canvas camera={{ position: [0, 0, 12], fov: 50 }} onCreated={() => { (window as any).__game = bridge; }}><Scene /></Canvas>,
);
```

## rapier.ts

The `window.__game` bridge for a game whose bodies live in a Rapier world, with `@react-three/rapier` or plain `@dimforge/rapier3d-compat`. `observe()` reads positions from the bodies, rounded so a check's exact values are stable; `setState` teleports a body and stops it unless the state gives its velocity.

```ts
// Rapier template: the window.__game bridge for a game whose bodies live in a Rapier world, with
// @react-three/rapier (`installGame(useRapier().world, ...)` in an effect) or plain @dimforge/rapier3d-compat.
// observe() reads positions from the bodies, rounded so a check's exact values are stable; setState teleports a body
// and stops it unless the state gives its velocity, so a keypoint starts at rest by default. Keep the physics step fixed at 1/60 s (@react-three/rapier's default
// timeStep) so stepped frames are exact. Replace the rules, keep the shape.
import type { RigidBody, World } from '@dimforge/rapier3d-compat';

type Vec = { x: number; y: number; z: number };
const SPEED = 4, JUMP = 7;   // units per second
const held = new Set<string>();
let jump = false, score = 0;
const round = (v: Vec) => ({ x: +v.x.toFixed(2), y: +v.y.toFixed(2), z: +v.z.toFixed(2) });

/** One input path for real keys and the harness's act(); Space jumps once per press. */
export function act({ key, down = true }: { key: string; down?: boolean }) {
  const k = key === ' ' ? 'Space' : key;
  if (k === 'Space' && down && !held.has(k)) jump = true;
  if (down) held.add(k); else held.delete(k);
}

/** Call once per physics step, before the world steps: held keys set the player's velocity. */
export function tick(player: RigidBody) {
  const vx = ((held.has('ArrowRight') ? 1 : 0) - (held.has('ArrowLeft') ? 1 : 0)) * SPEED;
  player.setLinvel({ x: vx, y: jump ? JUMP : player.linvel().y, z: 0 }, true);
  jump = false;
}

/** Installs window.__game and the key listeners for the named bodies; returns the cleanup. */
export function installGame(world: World, bodies: { player: RigidBody }) {
  const down = (e: KeyboardEvent) => act({ key: e.key });
  const up = (e: KeyboardEvent) => act({ key: e.key, down: false });
  addEventListener('keydown', down);
  addEventListener('keyup', up);
  (window as any).__game = {
    describe: () => ({ name: 'platformer', stack: 'rapier', units: 'metres, y up', keys: { ArrowLeft: 'hold', ArrowRight: 'hold', Space: 'jump' } }),
    observe: () => ({ score, bodies: world.bodies.len(), player: round(bodies.player.translation()), velocity: round(bodies.player.linvel()) }),
    act,
    setState: (s: { score?: number; player?: Vec; velocity?: Vec }) => {   // every schema key but bodies (a count), applied at once
      if (s.score !== undefined) score = s.score;
      if (s.player) bodies.player.setTranslation(s.player, true);
      if (s.player || s.velocity) bodies.player.setLinvel(s.velocity ?? { x: 0, y: 0, z: 0 }, true);
    },
  };
  return () => { removeEventListener('keydown', down); removeEventListener('keyup', up); delete (window as any).__game; };
}
```

---

# The game contract
https://paprika3d.com/docs/references/contract

`game-contract.json` holds the user's prompt, the `observe()` schema and 8 to 20 keypoints. Each keypoint:

```json
{ "id": "eat-grows", "title": "eating food grows the snake by one",
  "state": { "head": { "x": 3, "y": 3 }, "food": { "x": 4, "y": 3 } },
  "actions": [{ "key": "ArrowUp" }],
  "frames": 1,
  "expect": [{ "path": "score", "op": "==", "value": 1 }, { "path": "body.length", "op": ">=", "value": 3 }] }
```

`game_check` runs every keypoint on a freshly reloaded page: `setState(state)`, confirmed in `observe()` before any frame runs; then each action (one frame each unless it says `frames`); then `frames` more frames (60 when left out); then every `expect` over `observe()`. Paths are dotted: `head.x`, `body.length`, `body.0.x`.

## What a failure means

| Outcome | Meaning | Usual fix |
|---|---|---|
| `launch_failed` | The page did not load or draw a frame | Read the error; `game_observe` shows console errors |
| `state_not_realized` | After `setState`, `observe()` did not return those values | `setState` must apply every schema key at once, and start-up code must not overwrite it |
| `actions_incomplete` | An input could not be sent or `act` threw | Handle that key or action in `act` |
| `outcome_mismatch` | An `expect` did not hold; the line says what was expected and got | Fix the game logic, not `observe()` |

A failing keypoint saves a picture of the page in the run folder.

## Rules

- Only `game_contract` writes `game-contract.json`. Its hash is kept outside the project, and a contract changed by hand is refused with "changed by hand; run game_contract again".
- The contract describes what the user asked for. When the user changes the request, run `game_contract` again with the new prompt (a fresh subagent writes it again).
- When a check result ends with "stale", the sources changed while it ran: check again.

---

# Procedural geometry: three.js plus geo.js
https://paprika3d.com/docs/references/geometry

`game_open` puts `geo.js` in the project root. It holds Manifold (exact booleans, hull, extrude, revolve, level sets, smoothing) with three.js helpers, and a seeded `scatter`. Never read or edit it.

```js
import * as THREE from "three";
import { geo, scatter } from "./geo.js";        // "../geo.js" from src/ in a vite project
const { Manifold, CrossSection, toManifold, toGeometry, boolean } = await geo();   // once, before building
```

- `boolean(op, a, ...b)`: `"union"`, `"difference"` (a minus the rest) or `"intersection"` of closed three.js geometries; returns a new geometry.
- `toManifold(geometry)` and `toGeometry(manifold, { sharpAngle })` convert between the two; work in Manifold when a shape needs several steps.
- `scatter(target, geometry, material, count, { seed, scale: [min, max], align })` returns an InstancedMesh in `target`'s local space, so add it to `target`.
- Manifold is Z-up and its angles are degrees: `.rotate([-90, 0, 0])` turns its Z into three's Y.

After each step, name the mesh and check it with `game_eval`: `return stats("wall")` gives triangles, `closed`, volume and genus (a hole through the part adds 1). Try a step in `game_eval` first when unsure, then write it into the source. Once the numbers are right, `game_look` with `target: "wall"` shows it alone from four sides in one picture, which catches a shape that only looks right from the game's camera.

## Scatter on a surface

```js
const ground = new THREE.Mesh(new THREE.PlaneGeometry(20, 20).rotateX(-Math.PI / 2), groundMat);
const cone = new THREE.ConeGeometry(0.4, 1.5).translate(0, 0.75, 0);   // base at the origin, so it stands on the surface
const trees = scatter(ground, cone, treeMat, 80, { seed: 1, scale: [0.7, 1.3], align: false });   // align: false keeps trees upright
trees.name = "trees"; ground.add(trees);
```

## Parametric array

One InstancedMesh draws every copy in one call; a loop of `Mesh`es sharing one geometry and material is fine for a few.

```js
const N = 12, posts = new THREE.InstancedMesh(new THREE.BoxGeometry(0.2, 1, 0.2), postMat, N), m = new THREE.Matrix4();
for (let i = 0; i < N; i++) {
  const a = (i / N) * Math.PI * 2;
  posts.setMatrixAt(i, m.makeRotationY(-a).setPosition(Math.cos(a) * 5, 0.5, Math.sin(a) * 5));
}
posts.instanceMatrix.needsUpdate = true;
```

## Curve to mesh

```js
const path = new THREE.CatmullRomCurve3([new THREE.Vector3(-4, 0, 0), new THREE.Vector3(0, 2, 2), new THREE.Vector3(4, 0, 0)]);
const pipe = new THREE.TubeGeometry(path, 64, 0.2, 12, false);           // round section; its ends are open
const profile = new THREE.Shape().moveTo(-0.3, -0.1).lineTo(0.3, -0.1).lineTo(0.3, 0.1).lineTo(-0.3, 0.1);
const rail = new THREE.ExtrudeGeometry(profile, { steps: 64, extrudePath: path, bevelEnabled: false });   // any section, capped
```

## Boolean carve

Make cutters overshoot the faces they cut through; a cut flush with a face leaves a sliver.

```js
const wallGeo = boolean("difference",
  new THREE.BoxGeometry(4, 3, 0.4),
  new THREE.BoxGeometry(1, 2.1, 1).translate(-1, -0.55, 0),                    // door, open at the bottom
  new THREE.CylinderGeometry(0.4, 0.4, 1, 24).rotateX(Math.PI / 2).translate(1, 0.5, 0));   // round window: genus 1
const wall = new THREE.Mesh(wallGeo, wallMat); wall.name = "wall";
```

## Lathe or revolve

Start and end the profile on the axis (x = 0), or the shape is open at the poles.

```js
const pts = [[0, 0], [0.5, 0], [0.6, 0.2], [0.3, 0.9], [0.35, 1.2], [0, 1.2]];
const vase = new THREE.LatheGeometry(pts.map(([x, y]) => new THREE.Vector2(x, y)), 32);   // three.js

const section = CrossSection.ofPolygons([pts]), spun = section.revolve(32), upright = spun.rotate([-90, 0, 0]);   // Manifold, for booleans next
const vase2 = toGeometry(upright);
section.delete(); spun.delete(); upright.delete();
```

## Three-lane pebble scatter

Three lanes over one surface, each with its own seed and scale range, so large, medium and small stones mix without one repeating pattern.

```js
const pebble = new THREE.IcosahedronGeometry(1, 1).scale(1, 0.55, 1);
for (const [lane, count, scale, seed] of [["large", 12, [0.25, 0.60], 11], ["medium", 40, [0.25, 0.45], 12], ["small", 120, [0.10, 0.35], 13]]) {
  const stones = scatter(ground, pebble, stoneMat, count, { seed, scale, align: true });
  stones.name = `pebbles-${lane}`; ground.add(stones);
}
```

## Hull and level sets

```js
const hull = Manifold.hull([[0, 0, 0], [1.2, 0.1, 0.2], [0.2, 1, 0.3], [0.5, 0.3, 1], [0.9, 0.8, 0.7], [-0.2, 0.4, 0.6]]);
const rock = toGeometry(hull, { sharpAngle: 0 }); hull.delete();          // faceted rock

// A signed-distance function, positive inside: two spheres blended (smooth min), inside the bounds' box.
const k = 0.4, d = (p, c, r) => Math.hypot(p[0] - c[0], p[1] - c[1], p[2] - c[2]) - r;
const sdf = p => { const a = d(p, [-0.6, 0, 0], 0.7), b = d(p, [0.6, 0, 0], 0.5), h = Math.max(k - Math.abs(a - b), 0) / k;
  return -(Math.min(a, b) - h * h * k / 4); };
const blob = Manifold.levelSet(sdf, { min: [-1.5, -1, -1], max: [1.5, 1, 1] }, 0.08);
const blobGeo = toGeometry(blob); blob.delete();
```

## Rounding a shape

`smoothOut(180)` curves every edge and `refine(n)` splits each edge into n, moving the new vertices onto that curve. The surface passes through the old vertices and bulges out between them, so it suits a low-poly shape turning into a pebble or blob; check its size with `stats`. Flat faces of three or more triangles stay flat, so it will not round a box's edges: hull spheres at the corners instead.

```js
const facets = Manifold.hull([[0, 0, 0], [1, 0.1, 0.2], [0.2, 0.6, 0.3], [0.5, 0.2, 0.9], [0.8, 0.5, 0.6]]);
const smooth = facets.smoothOut(180), fine = smooth.refine(6);
const pebbleGeo = toGeometry(fine);
facets.delete(); smooth.delete(); fine.delete();

const r = 0.15, ball = Manifold.sphere(r, 16), corners = [];   // a 2 x 1 x 1 box with edges rounded to r
for (const x of [-1, 1]) for (const y of [-0.5, 0.5]) for (const z of [-0.5, 0.5]) corners.push(ball.translate([x - Math.sign(x) * r, y - Math.sign(y) * r, z - Math.sign(z) * r]));
const rounded = Manifold.hull(corners), boxGeo = toGeometry(rounded);
for (const c of [ball, rounded, ...corners]) c.delete();
```

## Pitfalls

- three's primitives split vertices at every face edge and UV seam; `toManifold` and `boolean` weld them, so a `BoxGeometry` counts as closed. An open shape (`PlaneGeometry`, a `TubeGeometry` with open ends) throws "the mesh is not closed".
- Every Manifold and CrossSection lives in wasm memory: call `.delete()` on each one you make, including every step of a chain (`a.smoothOut(180).refine(6)` leaks the middle one). `boolean` and `toGeometry` free what they make; a Manifold that `toManifold` returns is yours to delete.
- `boolean("difference", ...)` throws "difference removed nothing; does the cutter overlap?" when the cutter misses: move the cutter, do not catch it.
- `toGeometry` makes smooth normals but keeps edges sharper than 30 degrees hard; pass `{ sharpAngle: 0 }` for facets or `180` to smooth everything.
- Trust `volume` and `genus` only when `stats` says `closed`; an open mesh's volume means nothing.
- Pass `scatter` a `seed` (and keep other build randomness seeded) so the layout is the same on every load.
- Changes made in `game_eval` vanish on reload: write what works into the source.

---

# Performance: game_perf, game_optimize and the runtime layer
https://paprika3d.com/docs/references/optimize

## game_perf

Measures the open game uncapped in headless Chrome: median and p95 frame time, draw calls, triangles and the size of the project's assets, against a budget. `desktop` (the default) is 16.7 ms a frame, 5 MB of assets, 200,000 triangles, 2048 px textures and a pixel ratio of at most 2. The contract's `budget`, or a `budget` argument, overrides it.

## game_optimize

Tries each switch of `@paprika3d/three-runtime` on the open game, one at a time, on top of the ones already kept:

| Switch | What it does | Kept when |
|---|---|---|
| `resolution` | Lowers the pixel ratio while frames run over budget, raises it back when there is time | it breaks no keypoint and is not slower |
| `defaults` | Caps the pixel ratio at 2, compiles shaders up front, stops redrawing shadow maps while no caster moves | same |
| `instancing` | Draws many still meshes that share a geometry and material as one instanced mesh | it is measurably faster, or 20% fewer draw calls |
| `lod` | Simpler versions of meshes over 10,000 triangles when they are far away | measurably faster |
| `dispose` | Frees the GPU memory of objects removed from the scene and never disposed | it breaks no keypoint and is not slower |

A switch that fails a keypoint, breaks the page or changes the picture when it must not is reverted, with the reason. The kept switches go to `game-runtime.json` in the project (and in `public/` when there is one, since vite copies only `public/`). The game's single `install()` call reads that file, so the shipped game runs with the same switches.

`resolution` and `lod` may change the picture; a kept one that did is marked `lookChanged`, with before and after pictures to compare.

The report also lists image and `.glb` files whose textures are over the budget's size.

## Adding the runtime layer

When the game does not import the runtime yet, `game_optimize` puts the built runtime in the project root as `three-runtime.js` and says so. Import it (`import { install } from "./three-runtime.js"`, or `"../three-runtime.js"` from `src/`) and call `install()` at the top of the entry file, before the renderer is made. Never read, copy or edit that file: it is a 110 KB minified bundle the harness keeps current. It does nothing until `game_optimize` has chosen switches. Then reopen the game with `game_open` and call `game_optimize` again.

The layer must be imported by the game itself (only the game's own copy of three can be patched):

```js
import { install } from './three-runtime.js';   // game_optimize puts it in the project root; never read it
install();                                     // before the renderer is made
```

In a page with an import map, `three` must be mapped, since the runtime imports it. Under vite, the project's `three` package is used. A renderer made before `install()` must be passed: `install({ renderer })`. Mark an object, geometry, material or texture with `userData.keep = true` to keep `dispose` away from it (a pooled object kept outside the scene).

---

# Guides
https://paprika3d.com/docs/guides

Each guide takes one task an agent meets while building a three.js page and shows how to do it with the paprika3d tools. Guides are written by an agent and say so at their foot, with the date; every code sample ran in the harness before it was published.

- [Screenshot a three.js scene headlessly from a coding agent](https://paprika3d.com/docs/guides/screenshot-threejs-scene-headless): How a coding agent takes a screenshot of a three.js or WebGL canvas in headless Chrome, gets the list of objects on screen with it, and pictures one object from four sides, using the paprika3d plugin's game_open and game_look.
- [Test keyboard input in a three.js game, frame by frame](https://paprika3d.com/docs/guides/test-threejs-game-keyboard-input): How a coding agent presses keys in a three.js game on exact frames of a paused clock and reads the game's state back as JSON, so the same inputs give the same result on every run, using the paprika3d plugin's game_act and game_observe.
- [Find out why a three.js model is not visible](https://paprika3d.com/docs/guides/threejs-model-not-visible): A three.js object that never shows up is usually at the wrong scale, behind the camera, or never loaded. How a coding agent finds which, with the paprika3d plugin's game_look, game_eval and game_open replies.

---

# Screenshot a three.js scene headlessly from a coding agent
https://paprika3d.com/docs/guides/screenshot-threejs-scene-headless

How a coding agent takes a screenshot of a three.js or WebGL canvas in headless Chrome, gets the list of objects on screen with it, and pictures one object from four sides, using the paprika3d plugin's game_open and game_look.

## The problem

A coding agent that writes a three.js page wants to see what it drew before it reports the work as done. The page is a single `<canvas>`, so the agent needs a browser that runs WebGL with no window, a way to wait until the scene has rendered, and a picture it can open. A raw picture also leaves questions open: which of the objects in the scene are in it, and how large each one is.

This guide uses paprika3d, a Claude Code plugin that opens three.js, React Three Fiber and WebGL pages in its own headless Chrome. Its `game_look` tool saves a screenshot, saves an ID image with one colour per object, and lists the named objects on screen with their share of the image and their pixel box.

## Install

paprika3D needs Google Chrome and Node 20.11 or later.

```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
```

Install three.js into the project folder, since the page below loads it through an import map:

```bash
npm install three
```

## The page

Any three.js page works as it is. The one change that pays off is a `name` on each mesh, because `game_look` reports objects by name. This page draws a floor, a crate and a spinning torus knot:

```html
<!-- verify -->
<!doctype html>
<html><head><meta charset="utf-8"><title>Viewer</title>
<style>html,body{margin:0;overflow:hidden}canvas{display:block}</style></head>
<body>
<script type="importmap">{"imports":{"three":"./node_modules/three/build/three.module.js"}}</script>
<script type="module">
import * as THREE from 'three';

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x20232a);
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
camera.position.set(4, 3, 6);
camera.lookAt(0, 0.5, 0);
scene.add(new THREE.HemisphereLight(0xffffff, 0x444455, 1.5));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(3, 5, 2);
scene.add(sun);

// Name every mesh: the harness reports what is on screen by name.
const floor = new THREE.Mesh(new THREE.PlaneGeometry(10, 10), new THREE.MeshStandardMaterial({ color: 0x556070 }));
floor.name = 'floor';
floor.rotation.x = -Math.PI / 2;
scene.add(floor);

const crate = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0xc08040 }));
crate.name = 'crate';
crate.position.set(-1.2, 0.5, 0);
scene.add(crate);

const knot = new THREE.Mesh(new THREE.TorusKnotGeometry(0.5, 0.18, 128, 16), new THREE.MeshStandardMaterial({ color: 0x40a0e0 }));
knot.name = 'knot';
knot.position.set(1.2, 0.9, 0);
scene.add(knot);

renderer.setAnimationLoop((time) => {
  knot.rotation.y = time / 1000;   // performance time: the harness fakes it, so every run draws the same frame
  renderer.render(scene, camera);
});
</script>
</body></html>
```

Save it as `index.html` in the project folder.

## The tool calls, in order

These are the calls an agent makes, each followed by the reply paprika3d gave when this page was run through it on 2026-10-14. Run folder paths are shortened to `<project>`.

**1. Open the page.** `game_open` serves the folder, loads the page in headless Chrome and pauses its clock at frame 0. The `entities` list is every named object in the scene.

```text
game_open {"url": "index.html", "cwd": "<project>"}

Opened http://127.0.0.1:59037/index.html, paused at frame 0.
{"three":"186","scenes":1,"entities":["floor","crate","knot"],"hasConvention":false}
Procedural geometry: import { geo, scatter } from "./geo.js" (see the skill's geometry reference).
Next: game_look to see it, then game_act for each interaction the request names.

Run folder: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z
```

**2. Take the screenshot.** `game_look` with no arguments pictures the page as the game's own camera sees it.

```text
game_look {}

Picture: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-1.png
ID image: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-1-ids.png
On screen (3):
floor 51.7% [0, 279, 1279, 799]
knot 4.1% [653, 257, 895, 492]
crate 2.2% [435, 299, 605, 459]
Never visible: none
```

The picture is a PNG at the page's viewport, 1280 px by 800 px. Each line under `On screen` is an object's name, the share of the image it covers, and its box in pixels as left, top, right, bottom.

**3. Picture one object from every side.** With `target`, `game_look` draws that object alone from the front, the right, the top and a three-quarter angle, framed to its size, in one picture. It also gives the object's size and centre in world units.

```text
game_look {"target": "knot"}

Picture: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-2-views.png (front, right, top, three-quarter)
knot: size 1.884 × 1.768 × 1.355, centre [1.124, 0.9, 0.026]
```

**4. Look from another camera.** `camera` moves the camera that draws the scene for this one picture and puts it back afterwards. This is a top-down view:

```text
game_look {"camera": {"position": [0, 8, 0.01], "lookAt": [0, 0, 0]}}

Picture: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-3.png
ID image: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-3-ids.png
On screen (3):
floor 89.9% [36, 0, 1243, 799]
knot 2.4% [682, 319, 910, 471]
crate 2.0% [405, 331, 555, 468]
Never visible: none
```

**5. Move time forward, then look again.** The clock stays paused until something steps it, so an animation is pictured at an exact frame. `game_clock` steps it:

```text
game_clock {"step": 60}

Clock at 61.017 s, frame 61.

game_look {}

Picture: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-4.png
ID image: <project>/paprika3d/runs/2026-10-14T07-47-59-715Z/look-4-ids.png
On screen (3):
floor 52.3% [0, 279, 1279, 799]
knot 3.1% [675, 252, 878, 482]
crate 2.2% [435, 299, 605, 459]
Never visible: none
```

The knot has turned, so its box and share changed; the crate did not move, and its line is the same.

## What to read in the reply

- `On screen (N)`: if an object the page should draw is missing from this list, it drew no pixel.
- `Never visible`: named objects that no look has seen yet, with their size and whether they are behind the camera or in view. An object in view that draws no pixel is usually far too small for the scene, hidden behind something, or not drawn at all. The guide on finding an invisible three.js model covers this line.
- `Picture`: open the PNG to judge colour, lighting and composition, which the list does not describe.
- `Errors so far` and `Failed to load` lines in the `game_open` reply: a page with console errors or a model that returned 404 shows them there.

## Pitfalls

- **Unnamed meshes** are listed by their type (`Mesh`), which tells the agent little. Give each mesh a `name`.
- **Time.** The page runs on a fake clock that steps 1/60 s per frame. An animation driven by `requestAnimationFrame` time or `performance.now` is reproducible; one driven by a separate real-time source is not.
- **A page that never renders.** `game_open` waits for a three.js renderer or `window.__game`; after 10 s with neither, it returns an error with the page's console errors.
- **Pictures go in the project.** Runs are written under `paprika3d/` in the project folder; add that folder to `.gitignore`.

## Without paprika3d

A headless browser script can take the same picture. With Puppeteer or Playwright, open the page, wait for the first frames to render, and call `page.screenshot()`. Two things to know when doing it by hand:

- Reading the canvas back with `canvas.toDataURL()` after the frame has been presented returns a blank image unless the renderer was made with `preserveDrawingBuffer: true`, or the read happens right after `renderer.render()` in the same task.
- Headless Chrome needs WebGL enabled. On a machine with no GPU, such as many CI runners, it falls back to the SwiftShader software renderer, which recent Chrome versions turn on with flags such as `--use-angle=swiftshader` and `--enable-unsafe-swiftshader`.

A script like this gives the pixels. Listing which objects are in the picture, or picturing one object from four sides, takes extra code in the page that reads the scene graph.

Written by the paprika3d agent on 2026-10-14, reviewed weekly. Every code sample on this page ran in the harness before publishing.

---

# Test keyboard input in a three.js game, frame by frame
https://paprika3d.com/docs/guides/test-threejs-game-keyboard-input

How a coding agent presses keys in a three.js game on exact frames of a paused clock and reads the game's state back as JSON, so the same inputs give the same result on every run, using the paprika3d plugin's game_act and game_observe.

## The problem

A three.js game reads the keyboard, steps its state once per animation frame, and draws the result. To test that holding ArrowRight moves the player, or that a jump cannot be repeated in mid-air, a test has to send key events on known frames and then read the state. Two things get in the way. Animation frames follow the display's refresh rate and the machine's load, so a test that presses a key for "half a second" moves the player a different distance on each run. And the state lives in the page's JavaScript, behind a canvas, so a screenshot shows where the player is drawn without saying what its position or velocity is.

This guide uses paprika3d, a Claude Code plugin that runs the game in headless Chrome on a paused clock. Its `game_act` tool sends keys, mouse, touch or game actions for a given number of frames, each frame 1/60 s of game time, and replies with the game's state after them.

## Install

paprika3D needs Google Chrome and Node 20.11 or later.

```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
npm install three
```

## The game

Keys work on any page, since paprika3d sends them as real browser events. To get the state back as JSON, the game exposes `window.__game` with `describe()`, `observe()`, `act(input)` and `setState(partial)`, as described on the convention page. Three habits make the game testable:

- State lives in plain variables, apart from the meshes that draw it.
- Real key events and `act({ key, down })` go through the same function.
- Each frame advances the game by its elapsed time, capped at 0.1 s, so the paused clock decides how far the game moves.

This page moves a ball with the arrow keys and jumps on Space:

```html
<!-- verify -->
<!doctype html>
<html><head><meta charset="utf-8"><title>Jumper</title>
<style>html,body{margin:0;overflow:hidden}canvas{display:block}</style></head>
<body>
<script type="importmap">{"imports":{"three":"./node_modules/three/build/three.module.js"}}</script>
<script type="module">
import * as THREE from 'three';

// Game state lives in plain variables, apart from the meshes that draw it.
const SPEED = 3, JUMP = 6, GRAVITY = 18;   // units per second, units per second, units per second squared
const held = new Set();
let x = 0, y = 0, vy = 0, jumps = 0;

function step(dt) {
  x += ((held.has('ArrowRight') ? 1 : 0) - (held.has('ArrowLeft') ? 1 : 0)) * SPEED * dt;
  vy -= GRAVITY * dt;
  y = Math.max(0, y + vy * dt);
  if (y === 0) vy = Math.max(0, vy);
}

// One input path for real keys and for the test harness.
function act({ key, down = true }) {
  if (key === ' ' && down && y === 0) { vy = JUMP; jumps++; }   // one-shot: acts on keydown
  if (down) held.add(key); else held.delete(key);
}
addEventListener('keydown', e => act({ key: e.key }));
addEventListener('keyup', e => act({ key: e.key, down: false }));

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x182030);
const camera = new THREE.PerspectiveCamera(50, innerWidth / innerHeight, 0.1, 100);
camera.position.set(0, 2, 9);
scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 2));
const ground = new THREE.Mesh(new THREE.BoxGeometry(12, 0.2, 2), new THREE.MeshStandardMaterial({ color: 0x4a6a4a }));
ground.name = 'ground';
ground.position.y = -0.6;
scene.add(ground);
const player = new THREE.Mesh(new THREE.SphereGeometry(0.5, 32, 16), new THREE.MeshStandardMaterial({ color: 0xff8030 }));
player.name = 'player';
scene.add(player);

let last = null;
renderer.setAnimationLoop((now) => {
  step(last === null ? 1 / 60 : Math.min((now - last) / 1000, 0.1));   // never more than 0.1 s a frame
  last = now;
  player.position.set(x, y, 0);
  renderer.render(scene, camera);
});

const round = (n) => +n.toFixed(3);
window.__game = {
  describe: () => ({ name: 'jumper', units: 'world units, y up', keys: { ArrowRight: 'hold to move right', ArrowLeft: 'hold to move left', ' ': 'jump' } }),
  observe: () => ({ x: round(x), y: round(y), vy: round(vy), jumps }),
  act,
  setState: (s) => { ({ x = x, y = y, vy = vy, jumps = jumps } = s); },
};
</script>
</body></html>
```

## The tool calls, in order

Each call is followed by the reply paprika3d gave for this page on 2026-10-14. Run folder paths are shortened to `<project>`.

**1. Open the game.** With `window.__game` present, the reply carries the game's own `describe()`.

```text
game_open {"url": "index.html", "cwd": "<project>"}

Opened http://127.0.0.1:61887/index.html, paused at frame 0.
{"name":"jumper","units":"world units, y up","keys":{"ArrowRight":"hold to move right","ArrowLeft":"hold to move left"," ":"jump"},"hasConvention":true}
Procedural geometry: import { geo, scatter } from "./geo.js" (see the skill's geometry reference).
Next: game_look to see it, then game_act for each interaction the request names.

Run folder: <project>/paprika3d/runs/2026-10-14T07-52-41-459Z
```

**2. Read the starting state.** `game_observe` returns `observe()` plus a `harness` block: the frame, renderer counts, console errors since the last observe, and what changed.

```text
game_observe {}

{"x":0,"y":0,"vy":0,"jumps":0,"harness":{"frame":0,"renderer":{"calls":0,"triangles":0,"textures":0,"geometries":0,"programs":0},"scene":{"objects":3,"meshes":2,"lights":1,"cameras":0},"errors":[],"changed":null}}
```

**3. Hold a key for a set number of frames.** Each step advances `frames` frames (default 1). Holding ArrowRight for 30 frames is half a second of game time, at 3 units per second:

```text
game_act {"steps": [{"key": "ArrowRight", "frames": 30}, {"key": "ArrowRight", "down": false}]}

{"after":{"x":1.5,"y":0,"vy":0,"jumps":0},"changed":{"x":1.5}}
```

The player moved 1.5 units, as the speed says it should.

**4. Jump, and stop at the top.** A key goes down on one frame and up on the next; `wait` steps frames with no input. With a jump speed of 6 and gravity of 18, the ball stops rising a third of a second after the jump, which is where these steps end:

```text
game_act {"steps": [{"key": " "}, {"key": " ", "down": false}, {"wait": 18}]}

{"after":{"x":1.5,"y":0.95,"vy":0,"jumps":1},"changed":{"y":0.95,"jumps":1}}
```

`vy` is 0 at the top, and `jumps` counted one jump.

**5. Test a rule: no jump in mid-air.** Press Space again at the top of the jump and let the ball fall:

```text
game_act {"steps": [{"key": " "}, {"key": " ", "down": false}, {"wait": 40}]}

{"after":{"x":1.5,"y":0,"vy":0,"jumps":1},"changed":{"y":0}}
```

`jumps` is still 1: the second press was ignored, and the ball landed.

**6. Look at it.** `game_look` confirms the player is drawn where the state says.

```text
game_look {}

Picture: <project>/paprika3d/runs/2026-10-14T07-52-41-459Z/look-1.png
ID image: <project>/paprika3d/runs/2026-10-14T07-52-41-459Z/look-1-ids.png
On screen (2):
ground 8.7% [0, 614, 1279, 689]
player 0.7% [735, 542, 831, 639]
Never visible: none
```

**7. Run it again.** Reopening the page and sending the same steps gives the same state on the same frame:

```text
game_open {"url": "index.html", "cwd": "<project>"}
game_act {"steps": [{"key": "ArrowRight", "frames": 30}, {"key": "ArrowRight", "down": false}]}

{"after":{"x":1.5,"y":0,"vy":0,"jumps":0},"changed":{"x":1.5}}

game_act {"steps": [{"key": " "}, {"key": " ", "down": false}, {"wait": 18}]}

{"after":{"x":1.5,"y":0.95,"vy":0,"jumps":1},"changed":{"y":0.95,"jumps":1}}

game_observe {}

{"x":1.5,"y":0.95,"vy":0,"jumps":1,"harness":{"frame":51,"renderer":{"calls":2,"triangles":972,"textures":1,"geometries":2,"programs":1},"scene":{"objects":3,"meshes":2,"lights":1,"cameras":0},"errors":[],"changed":null}}
```

## What to read in the reply

- `after`: the state when the last step's frames are done. Compare it with what the request says the input should do.
- `changed`: the keys whose values moved. A key press that changes nothing is a dead control.
- `harness.errors` in `game_observe`: console errors since the last observe. A game that throws on an input shows it here.
- `harness.frame`: the frame count, to confirm how much game time the steps covered.

## Pitfalls

- **One-shot controls act on keydown.** A key can go down and up within one frame, so a jump or a shot that waits for a held key across frames may never fire.
- **Release held keys.** A key sent with no `down: false` step stays held for the following calls.
- **Never read real time.** A game that moves by `Date.now()` deltas read outside the animation frame, or by a fixed amount per frame with no cap, gives different results at a different frame rate. The clock paprika3d installs fakes `requestAnimationFrame`, `performance.now`, `Date` and timers.
- **Randomness.** Use `Math.random`; paprika3d seeds it, so the same steps see the same game.
- **For exact rules, lock a contract.** For a game whose rules can be written down (scoring, collisions, turn order), `game_contract` turns the user's prompt into keypoints and `game_check` runs them after each change.

## Without paprika3d

A browser test can drive the same game. With Playwright or Puppeteer, `page.keyboard.down('ArrowRight')` and `page.keyboard.up('ArrowRight')` send real key events, and `page.evaluate(() => window.__game.observe())` reads the state. To make the result repeatable, the test also needs control of time: Playwright's `page.clock` API can install a fake clock and advance it, or the game can expose a `step(dt)` function the test calls directly with a fixed 1/60 s. For logic alone, keeping the rules in a module with no three.js imports lets a unit test runner such as Vitest call `step` and `act` with no browser at all.

Written by the paprika3d agent on 2026-10-14, reviewed weekly. Every code sample on this page ran in the harness before publishing.

---

# Find out why a three.js model is not visible
https://paprika3d.com/docs/guides/threejs-model-not-visible

A three.js object that never shows up is usually at the wrong scale, behind the camera, or never loaded. How a coding agent finds which, with the paprika3d plugin's game_look, game_eval and game_open replies.

## The problem

The page loads, there is no error, and the model is not there. In three.js this has a short list of usual causes:

- **Scale.** A model exported in centimetres or millimetres, or scaled twice, is far too small for the scene. It is drawn, but it covers a pixel or two.
- **Framing.** The object is behind the camera, outside its view, or beyond its far plane.
- **Loading.** The file returned 404, the loader is missing a decoder (a Draco-compressed glTF needs a `DRACOLoader`), or the load callback never added the result to the scene.
- **Drawing.** The material is transparent, the object is hidden behind another one, or `visible` is false.

Checking these by hand means logging bounding boxes, moving the camera, and reading the network tab. This guide shows how a coding agent gets the answer from tool replies, using paprika3d, a Claude Code plugin that opens three.js pages in its own headless Chrome and reports, after each look, the named objects that drew no pixel.

## Install

paprika3D needs Google Chrome and Node 20.11 or later.

```bash
claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d
npm install three
```

## A page with two of the mistakes

The car below is scaled down twice, as a model exported in centimetres often is, and the lamp sits behind the camera. Every mesh has a `name`, since the replies refer to objects by name.

```html
<!-- verify -->
<!doctype html>
<html><head><meta charset="utf-8"><title>Parking lot</title>
<style>html,body{margin:0;overflow:hidden}canvas{display:block}</style></head>
<body>
<script type="importmap">{"imports":{"three":"./node_modules/three/build/three.module.js"}}</script>
<script type="module">
import * as THREE from 'three';

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x9fc6e8);
const camera = new THREE.PerspectiveCamera(50, innerWidth / innerHeight, 0.1, 200);
camera.position.set(0, 4, 10);
camera.lookAt(0, 0, 0);
scene.add(new THREE.HemisphereLight(0xffffff, 0x445544, 2));

const ground = new THREE.Mesh(new THREE.PlaneGeometry(20, 20), new THREE.MeshStandardMaterial({ color: 0x6b8f5e }));
ground.name = 'ground';
ground.rotation.x = -Math.PI / 2;
scene.add(ground);

// Two common mistakes, one per object.
const car = new THREE.Mesh(new THREE.BoxGeometry(4, 1.4, 2), new THREE.MeshStandardMaterial({ color: 0xd04040 }));
car.name = 'car';
car.scale.setScalar(0.01);          // a model exported in centimetres, scaled down twice
car.position.set(0, 0.7, 0);
scene.add(car);

const lamp = new THREE.Mesh(new THREE.CylinderGeometry(0.15, 0.15, 3), new THREE.MeshStandardMaterial({ color: 0x333333 }));
lamp.name = 'lamp';
lamp.position.set(0, 1.5, 14);      // placed at +z, behind a camera that looks toward -z
scene.add(lamp);

renderer.setAnimationLoop(() => renderer.render(scene, camera));
</script>
</body></html>
```

## The tool calls, in order

Each call is followed by the reply paprika3d gave for this page on 2026-10-14. Run folder paths are shortened to `<project>`.

**1. Open it.** The `entities` list confirms that all three objects are in the scene graph, so this is not a loading problem.

```text
game_open {"url": "index.html", "cwd": "<project>"}

Opened http://127.0.0.1:61064/index.html, paused at frame 0.
{"three":"186","scenes":1,"entities":["ground","car","lamp"],"hasConvention":false}
Procedural geometry: import { geo, scatter } from "./geo.js" (see the skill's geometry reference).
Next: game_look to see it, then game_act for each interaction the request names.

Run folder: <project>/paprika3d/runs/2026-10-14T07-50-50-163Z
```

**2. Look.** `game_look` saves a screenshot and lists what drew pixels and what did not.

```text
game_look {}

Picture: <project>/paprika3d/runs/2026-10-14T07-50-50-163Z/look-1.png
ID image: <project>/paprika3d/runs/2026-10-14T07-50-50-163Z/look-1-ids.png
On screen (2):
ground 68.0% [0, 241, 1279, 799]
car 0.0% [638, 346, 641, 347]
Never visible: lamp (3 units, behind the camera)
```

Two answers are already here. The car is on screen at 0.0% of the image, in a box 3 pixels wide: it is drawn, at a size nobody would notice in the picture. The lamp drew nothing, and the reply says why: it is behind the camera. Its size, 3 units, rules out a scale problem for it.

**3. Measure the small one.** `game_eval` runs JavaScript in the page with `scene`, `camera`, `renderer`, `find(name)` and `stats(target)` in scope. `stats` gives each mesh's triangles, whether it is closed, and its world size:

```text
game_eval {"code": "return stats(\"car\")"}

total  1 meshes  24 v  12 tri
car  24 v  12 tri  closed  vol 0  genus 0  size 0.04×0.014×0.02  [position, normal, uv]
```

The car is 0.04 units long on a ground 20 units wide. Its scale is the cause:

```text
game_eval {"code": "const c = find(\"car\"); return { scale: c.scale.toArray(), world: c.getWorldPosition(c.position.clone()).toArray(), camera: camera.position.toArray() }"}

{"scale":[0.01,0.01,0.01],"world":[0,0.7,0],"camera":[0,4,10]}
```

**4. Try the fix in the page, then look again.** A change made through `game_eval` lasts until the page reloads, so the agent can test a fix before it edits the source:

```text
game_eval {"code": "find(\"car\").scale.setScalar(1); find(\"lamp\").position.z = -4; return \"tried\""}

tried

game_look {}

Picture: <project>/paprika3d/runs/2026-10-14T07-50-50-163Z/look-2.png
ID image: <project>/paprika3d/runs/2026-10-14T07-50-50-163Z/look-2-ids.png
On screen (3):
ground 62.4% [0, 241, 1279, 799]
car 5.5% [456, 272, 823, 431]
lamp 0.3% [630, 125, 649, 271]
Never visible: none
```

Both objects are on screen now. The agent writes the same two changes into `index.html` (remove the `setScalar(0.01)` line, move the lamp to `z = -4`) and reopens the page with `game_open` to confirm.

## When the model never loaded

A missing file shows up in the `game_open` reply. This page loads `models/car.glb` with `GLTFLoader`, and the file is not there:

```js
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
new GLTFLoader().load('models/car.glb', (gltf) => { gltf.scene.name = 'car'; scene.add(gltf.scene); });
```

```text
game_open {"url": "index.html", "cwd": "<project>"}

Opened http://127.0.0.1:61282/index.html, paused at frame 0.
{"three":"186","scenes":1,"entities":[],"hasConvention":false}
Procedural geometry: import { geo, scatter } from "./geo.js" (see the skill's geometry reference).
Errors so far:
Failed to load resource: the server responded with a status of 404 (Not Found)
HttpError: fetch for "http://127.0.0.1:61282/models/car.glb" responded with 404: Not Found
Failed to load: car.glb (404)
Next: game_look to see it, then game_act for each interaction the request names.
```

The `Failed to load` line names the file and its status, and `entities` is empty because nothing was added to the scene. A Draco-compressed model loaded without a `DRACOLoader` logs `THREE.GLTFLoader: No DRACOLoader instance provided.` as a console error, which appears in the same `Errors so far` block, or in the `errors` list of the next `game_observe` if it arrives after the page opened.

## What to read in the replies

- `game_open`: `entities` (what is in the scene graph), `Errors so far`, `Loaded` and `Failed to load`.
- `game_look`, `On screen`: a share of 0.0% with a box a few pixels wide means the object is drawn far too small.
- `game_look`, `Never visible`: each named object that drew no pixel, its largest dimension in world units, and where it is. `behind the camera` is a framing problem. `in view` with a small size is a scale problem. `in view` with a normal size means it is hidden behind something, transparent, or not drawn.
- `game_eval` with `stats`: the world size of each mesh, to compare against the scene.

## Pitfalls

- **Name the model.** A glTF scene's meshes keep the names from the file; give the root you add a `name` too, so the replies point at it.
- **Compare sizes, not just positions.** A model at the right position and the wrong scale looks like a missing model in a screenshot. The size in the reply is in world units, the same units as the camera position.
- **Edits through game_eval vanish on reload.** Write the fix into the source, then open the page again.

## Without paprika3d

The same checks work by hand in the browser console, once the scene is reachable (for example `window.scene = scene` in the page):

- `new THREE.Box3().setFromObject(obj).getSize(new THREE.Vector3())` gives the object's world size.
- To test framing, build a `THREE.Frustum` from `camera.projectionMatrix` multiplied by `camera.matrixWorldInverse` and call `frustum.intersectsObject(mesh)`. A point in front of the camera has a negative z in camera space: `obj.getWorldPosition(v).applyMatrix4(camera.matrixWorldInverse).z < 0`.
- The browser's network panel shows a model or texture that returned 404.
- `THREE.BoxHelper` or `THREE.AxesHelper` added to the scene makes a small or distant object easier to spot in the picture.

Written by the paprika3d agent on 2026-10-14, reviewed weekly. Every code sample on this page ran in the harness before publishing.

---

# About
https://paprika3d.com/docs/about

paprika3D is maintained by Keeno ([github.com/paprika3d](https://github.com/paprika3d)).
<!-- TODO(human): add the maintainer's real name -->

The code of the plugin and MCP server is at [github.com/paprika3d/paprika3d](https://github.com/paprika3d/paprika3d). That repository holds the stable builds; each tagged release publishes one. The code is under the Apache License 2.0, copyright Keeno Corp; the starter templates are MIT. "paprika3D" is a trademark of Keeno Corp.

Some pages on this site are written by an agent. Every such page says so in a line at its foot, with the date it was written and the date it was last reviewed, and every code sample on such a page ran in the harness before it was published. Pages without that line are rendered from the files in the repository: the README, the skill and its references, and the source of the tools.

To report a problem with the harness or with this site, or to ask a question, open an issue at [github.com/paprika3d/paprika3d/issues](https://github.com/paprika3d/paprika3d/issues).