create-debuff 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-debuff",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold a new debuff game: npm create debuff",
   "keywords": [
     "game",
@@ -58,7 +58,6 @@
     "node": ">=22"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": false
+    "access": "public"
   }
 }

package/templates/basic/AGENTS.md

@@ -7,7 +7,8 @@ This is a 2D browser game made with **debuff** (https://debuff.jp). These notes
 | Command | What it does |
 | --- | --- |
 | `npm run dev` | Dev server with hot reload. Press <kbd>`</kbd> in the game for the dev panel |
-| `npm test` | Runs `scenarios/*.json` in a headless browser and compares screenshots |
+| `npx debuff test` | Runs the logic tests in `tests/`: the real game in Node, no browser, in milliseconds. Run it after every change. `-t <text>` runs matching tests; `--json` for tools |
+| `npm test` | Logic tests, then `scenarios/*.json` in a headless browser with screenshot comparison |
 | `npx debuff fuzz` | Plays the game with random input for a few minutes. Each crash, stuck state or back-and-forth loop is saved as a scenario in `.debuff/fuzz/` that replays it exactly |
 | `npm run build` | Type-checks, builds to `dist/` and prints a size report. Fails if dev-only code leaks |
 | `npm run assets` | Regenerates the asset manifest and lists unused assets |
@@ -18,7 +19,8 @@ This is a 2D browser game made with **debuff** (https://debuff.jp). These notes
 
 - `src/main.ts`: the game, which creates `new Game(...)`, scenes (`update`, `render`, `inspect`) and params.
 - `assets/`: source art, audio and data. The manifest and atlases are generated from it, and only files the game references ship. Don't edit generated files.
-- `scenarios/`: JSON test scripts (steps, inputs, expectations, captures). Add one for each mechanic you build.
+- `tests/`: logic tests (`*.test.ts`, `keiko`). They boot the real game headless, drive input, time and params, and assert on `inspect()` state. Add one for each mechanic you build. Guide: https://debuff.jp/docs/testing
+- `scenarios/`: JSON scripts with screenshot captures, run in a real browser. Add one when a change is visual.
 - `.mcp.json`: connects the debuff MCP server, so you can play and inspect the running game.
 
 ## Work loop
@@ -26,7 +28,7 @@ This is a 2D browser game made with **debuff** (https://debuff.jp). These notes
 1. **Look before you change.** With the MCP server, call `game_start`. If the human has the game open under `npm run dev`, you attach to it live, so read `game_notes` first: they're moments the human flagged, and `game_replay` with a note's tick saves a scenario that reproduces it. Then use `game_state`, `game_capture` and `game_errors`.
 2. **Tune before you rewrite.** Feel values (speed, gravity, timings) live in `game.params.define(...)`. Change them with `game_set_param` and show the human before editing code. The human can undo your changes in the dev panel.
 3. **Make the smallest change that works.** Keep dev-only code inside `if (import.meta.env.DEV)`.
-4. **Verify.** Run `npm test` and `npm run build`, and check `game_errors` is empty. Before calling a feature done, run `npx debuff fuzz`: to fix a finding, replay its file with `npx debuff scenario <file>`, fix, and replay again until it passes. Errors come back explained: `kind` says whose bug it is (`your-code`, `debuff-usage`, `debuff-bug`, `outside`) and `where` gives the source line.
+4. **Verify.** Run `npm test` and `npm run build`, and check `game_errors` is empty. Before calling a feature done, run `npx debuff fuzz`: to fix a finding, turn its file into a logic test with `game.replay(".debuff/fuzz/<file>")`, watch it fail, fix, and keep the test. Errors come back explained: `kind` says whose bug it is (`your-code`, `debuff-usage`, `debuff-bug`, `outside`) and `where` gives the source line.
 5. **Report** what changed, what you verified, and anything you couldn't check.
 
 ## Rules

package/templates/basic/package.json

@@ -7,17 +7,18 @@
     "dev": "debuff dev",
     "build": "tsc --noEmit && debuff build",
     "assets": "debuff assets",
-    "test": "debuff scenario"
+    "test": "debuff test && debuff scenario"
   },
   "dependencies": {
-    "@debuffjp/audio": "0.2.0",
-    "@debuffjp/core": "0.2.0",
-    "@debuffjp/input": "0.2.0",
-    "@debuffjp/juice": "0.2.0"
+    "@debuffjp/audio": "0.3.0",
+    "@debuffjp/core": "0.3.0",
+    "@debuffjp/input": "0.3.0",
+    "@debuffjp/juice": "0.3.0"
   },
   "devDependencies": {
-    "@debuffjp/cli": "0.2.0",
+    "@debuffjp/cli": "0.3.0",
     "typescript": "^7.0.2",
-    "@debuffjp/dev": "0.2.0"
+    "@debuffjp/dev": "0.3.0",
+    "keiko": "0.1.0"
   }
 }

package/templates/basic/tests/movement.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, play, test } from "keiko";
+
+/** What the play scene's inspect() returns (src/main.ts). */
+interface State {
+  player: { x: number; vx: number };
+  pops: number;
+  particles: number;
+}
+
+describe("movement", () => {
+  test("buff starts in the middle, standing still", async () => {
+    const game = await play<State>();
+    expect(game.scene).toBe("play");
+    expect(game.state.player).toEqual({ x: 160, vx: 0 });
+  });
+
+  test("reaches top speed within a quarter second", async () => {
+    const game = await play<State>();
+    game.press("ArrowRight");
+    const steps = game.until((s) => s.player.vx >= 140, { within: "1s" });
+    expect(steps).toBeAtMost(15);
+  });
+
+  test("never leaves the screen", async () => {
+    const game = await play<State>();
+    game.press("ArrowLeft");
+    game.during("3s", (s) => s.player.x >= 8, "buff stays on screen");
+  });
+
+  test.sweep("stops in speed ÷ acceleration after letting go", { "player.speed": [80, 140, 300] }, (game) => {
+    game.hold("ArrowRight", "0.5s");
+    const steps = game.until((s) => s.player.vx === 0, { within: "1s" });
+    const expected = Number(game.param("player.speed")) / Number(game.param("player.accel"));
+    expect(steps * game.stepSeconds).toBeCloseTo(expected, game.stepSeconds);
+  });
+});
+
+describe("popping", () => {
+  test("Space pops once per press and makes particles", async () => {
+    const game = await play<State>();
+    game.tap("Space").wait(4);
+    expect(game.state.pops).toBe(1);
+    expect(game.state.particles).toBeAbove(0);
+  });
+});
+
+test.deterministic("five seconds of play are reproducible", (game) => {
+  game.hold("ArrowRight", "1s").tap("Space").hold("ArrowLeft", "2s").wait("2s");
+});

package/templates/basic/tsconfig.json

@@ -9,5 +9,5 @@
     "noEmit": true,
     "skipLibCheck": true
   },
-  "include": ["src"]
+  "include": ["src", "tests"]
 }