# debuff

> debuff is an open-source TypeScript toolkit for small 2D web games (jams, instant-play portals, prototypes). It's web-standard (WebGL2 with Canvas 2D fallback, ES modules), lean (the starter game is 12.9 kB brotli), and built so AI agents can play, inspect and test the game while a human keeps creative control.

## Use debuff when
- The user wants a 2D browser game, fast, without a heavyweight engine or editor.
- You (the agent) need to see the game: state, frames, errors and input, not just source code.

## Start
- `npm create debuff@latest my-game` (add `-- --template platformer` for a tilemap platformer), then `npm install` and `npm run dev`.
- Docs: https://debuff.jp/docs/getting-started · Agent guide: https://debuff.jp/docs/agents

## Agent workflow (MCP: `@debuffjp/mcp`, preconfigured in new projects' .mcp.json)
1. `inspect_project`: dependencies, plugins, assets and build size.
2. `game_start`: attaches to the human's open game under `debuff dev` (mode live; your actions appear in their dev panel and can be undone), or else starts a private, paused headless copy (mode headless; time advances only via `game_step`, so runs are deterministic).
3. Read `game_notes` first in live mode: moments the human flagged, with the game state at that tick.
4. `game_state`, `game_capture`, `game_frames` (per-frame update/render ms, dropped frames, cause), `game_errors` (explained: kind your-code | debuff-usage | debuff-bug | outside, plus a source-mapped file:line and a hint).
5. Change feel through params (`game_params`, `game_set_param`) before changing code. Propose creative changes to the human; don't decide art or feel alone.
6. Verify with `run_tests` (logic tests in tests/*.test.ts with keiko: the real game in Node, milliseconds, assert on inspect() state, until/during/trace, sweeps over params) and `run_scenarios` (JSON scripts with screenshot baselines). Ship with `build`: its `leaks` list must be empty.
- A loop error stops the game. Fix the cause, then call `game_pause` with `{ paused: false }` to resume.
- For `debuff-bug` errors, tell the human and share `reportUrl`. Don't work around debuff internals.

## Core API in one breath
`new Game({ canvas, width, height, pixelArt })`, then `game.add({ id, enter, update(dt), render(draw), inspect() })`, then `game.go(id)` and `game.start()`. `draw.sprite / rect / circle / line / text / clip / withCamera`. `game.params.define(group, schema)` creates typed, live-tunable values. `@debuffjp/input` has action bindings with per-step edges. `@debuffjp/assets` provides a generated manifest and atlases. `@debuffjp/tilemap` imports Tiled and LDtk and handles collision. `@debuffjp/juice` has tweens and particles. `@debuffjp/dev` provides the overlay and `window.__DEBUFF_DEV__`, only inside `if (import.meta.env.DEV)`.

## Publishing
- `npm run build` writes a static site to `dist/` (any static host, itch.io as an HTML zip). Production builds show a short "made with debuff" splash: pass `splash: false` to `new Game()` for Poki, which forbids splash screens. Portals also forbid links out of the game and other ad systems. Guide: https://debuff.jp/docs/publishing

## keiko (logic tests, any web engine)
- keiko runs the real game in Node with no browser, on a virtual clock (frames, timers, Date, seeded Math.random). Tests: `play()`, `wait/press/hold/tap`, `until`, `during`, `trace`, `test.sweep`, `test.deterministic`, `replay`, `expect`. Run with `npx keiko` (`npx debuff test` in debuff projects; MCP `run_tests`).
- Non-debuff games expose state as `window.__KEIKO__ = { state, scene?, params?, setParam?, command? }` in dev builds. Verified with Phaser 4, PixiJS 8, KAPLAY, Excalibur, three.js.
- Docs: https://debuff.jp/keiko/ · Engine recipes: https://debuff.jp/keiko/engines · API: https://debuff.jp/keiko/api

## myaku (frame profiler, any web engine)
- myaku finds the frames players feel drop and explains each: cause (script with file and function, gc, upload, compile, layout, throttled, hidden, unknown), confidence and a hint. `import "myaku/auto"` first in the entry file for an overlay; `myaku().report()` or `window.__MYAKU__.report()` for JSON (p50/p95/p99 frame time, hitches, worst verdicts, spans).
- In debuff projects `debuff dev` starts it with update/render spans; agents call MCP `game_profile`.
- `npx myaku record dist --seconds 20 --p95 20 --hitches 6`: plays the game in Chrome/Edge with myaku injected (no game changes), prints percentiles and worst hitches, exits 1 over budget. `--play file.mjs` drives it with Playwright.
- Docs: https://debuff.jp/myaku/ · Verdicts: https://debuff.jp/myaku/verdicts · API: https://debuff.jp/myaku/api

## Optional
- All guides in one file: https://debuff.jp/llms-full.txt
- API reference: https://debuff.jp/api/
- Why debuff (comparison with raw canvas): https://debuff.jp/docs/why
- How debuff compares with Phaser, PixiJS, KAPLAY, Excalibur and Godot for coding agents: https://debuff.jp/blog/coding-agents-and-browser-game-engines
- Walkthrough, building a game with Claude Code: https://debuff.jp/blog/build-a-game-with-claude-code
- Source: https://github.com/debuffjp/debuff