paprika3D (the three.js toolset for coding agents)

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.

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.

Controls the open page's clock: step n frames, pause or resume real-time play, set the time scale.

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.

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.

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.

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

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.

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.

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.

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.