debuff

Build for production and return the size report (raw, gzip, brotli per file). `leaks` lists dev-only code found in the output; it must be empty. `saves` compares the game's saves with saves.json: an error means players would lose saved progress. Don't accept save changes yourself; tell the human (they run `debuff build --accept-saves`).

Check the project's setup in one pass: Node, debuff package versions, node_modules, debuff.config.ts, assets, saves.json, agent files and the browser. Every check has an id, ok, a message and a fix; ok is false only when a required check failed. Call it when another tool fails on setup. live: true also starts the dev server and waits for the game's dev hooks (about 5 to 15 s).

Play the game headlessly with random but plausible input (movement keys held, action keys tapped) to find runtime errors, stuck states and back-and-forth loops. Each finding includes the explained error (kind, source-mapped file:line, hint) and `repro`: a scenario file that replays it exactly. Pass that file to run_scenarios to reproduce, then again after fixing to verify. The same seed gives the same inputs.

Screenshot of the current frame as a PNG image. With `path`, also saves it to that file in the project. social: true letterboxes it into 1200×675 (16:9), the size X and Bluesky show for post images and link cards; save those under .debuff/captures/ and `debuff ship press` adds them to the press kit.

Video clips of the live game for devlogs, store pages and press kits. action start keeps a rolling recording of the last 15 s; save writes what it has (between about 7 and 15 s) to .debuff/captures/<name>.mp4 (WebM in browsers that can't record MP4) and keeps recording; stop ends it. Play or drive the game with game_input between start and save. Live mode only: clips record real time. The human posts; never post anywhere yourself.

Run a command the game registered with devTools({ commands }) (warp to a level, grant an item, select a cell), like a scenario's { command, args } step; recorded in replays. Prefer it over computing screen coordinates for game_input. An unknown name lists the registered ones. Returns the command's result and the new state.

Runtime errors since the game started, explained: kind (your-code, debuff-usage, debuff-bug, outside), where (source file:line, source-mapped), a hint, the loop phase and tick, and a repeat count. A loop error stops the game; fix it, then game_pause false to resume. For debuff-bug, tell the human and share reportUrl rather than working around it. Type errors aren't runtime errors: use typecheck.

Recent frames, oldest first: intervalMs (what the player feels), updateMs, renderMs, steps (>1 means catching up), quads, drawCalls and longTaskMs (browser-reported main-thread stalls). Use it to explain stutter; in headless mode times reflect stepping, not real play. summary: true returns percentiles and the 3 slowest frames instead of every frame.

Keyboard, pointer, wheel or touch input. press/release take a KeyboardEvent.code (e.g. Space, ArrowLeft, KeyZ), or PointerRight / PointerMiddle for mouse buttons. tap/pointer_down/pointer_move take logical x, y; tap and pointer_down also take kind (mouse, touch or pen). wheel takes dy (and dx) in CSS pixels. touch_down/touch_move take id, x, y (touch_down also kind: touch or pen); touch_up takes id. Input takes effect on the next game_step.

Moments the human flagged in the overlay (live mode): their words, the tick, the scene's inspect() state then, and the frames leading up to it.

Every tunable param group: schema (type, default, min, max, units, description) and current values.

Pause or resume a live game (headless games are always paused). game_step also pauses first.

Why the game stutters, from myaku: frame-time percentiles (p50/p95/p99), hitches per minute, and the worst hitches explained. Each has a cause (script, gc, upload, compile, layout, throttled, hidden, unknown), a confidence, the script and function to look at when known, and a hint. Spans show time in debuff's update and render. Prefer this over game_frames to explain stutter; measure in live mode, since headless stepping doesn't reflect real play.

Everything played since the game loaded (keys, pointer, param changes) up to `toTick` (default: now), saved as a scenario in .debuff/replays/ that replays it exactly. Use a note's `tick` to reproduce what the human saw when they flagged it, then run_scenarios with the returned file. `warnings` lists anything a replay can't reproduce (for example slow motion).

Live mode only. Take the human's game back (or forward, within the known session) to `tick`: the page reloads, replays the session's inputs to that tick and stays paused, so the state is exactly what it was then. Use a note's `tick` to look at the moment the human flagged. The page needs a second to reload; then use game_state or game_capture.

Set a tunable param live. Values are validated against the param's type and range. Changes last until game_start or a reload.

Connect to the game. auto (default): attach to the human's live game if `debuff dev` has it open in a browser, else start a private headless copy, paused. Returns the mode, state and how many notes the human has flagged. Replaces any running session. A headless copy holds a browser (about ten Chromium processes) until game_stop, so call that when you are done; it also closes after 15 idle minutes.

Current scene, tick, time, logical width and height, renderer, frame stats, the scene's inspect() data and plugin inspect data. reducedMotion true means the game may freeze or tone down its animations (reducedMotionForced: game_start forced it).

Advance the simulation by fixed steps (60 per second by default) and return the new state.

Headless: close the browser and dev server. Live: resume the human's game and disconnect.

Summary of the project: dependencies, plugins and their contributions, assets, last build size.

Run the asset pipeline: every asset id, type, size and importer, plus generated files, warnings and possibly unused ids.

Report tooling friction in debuff, keiko, myaku, spryte or debuff.jp to the public board at papercuts.debuff.jp: a slow or flaky tool, a missing API, confusing docs. Call it on your own, without being asked, whenever a debuff tool cost you time, once you are unstuck; then tell the human in one line. It checks for duplicates first: when it returns action "similar", call again with hit set to the matching id (that adds your minutes to it) or with force: true if none is the same problem. Write the title as the symptom. Never include secrets, file contents or personal data: open entries are public.

Run scenarios/*.json (or the given files) in a headless browser. Returns per-step results, runtime errors, captures and final state. Pass `files` while iterating; a full run starts a browser, so run it once when the work is done.

Run the logic tests in tests/**/*.test.ts (keiko): the real game in Node, no browser, in milliseconds. Each failure has its message, the source line, and the game's tick, scene and state when it failed. While iterating pass `files` or `filter` to run only what your change touches, and run everything once when the work is done. Write a test for each mechanic you add.

Type-check the project with its own tsc (no emit, no browser needed). Returns diagnostics: file (relative to the root), line, column, TypeScript code and message. Run it after editing code; vite doesn't type-check, so the game can run with type errors.