picopilot 0.1.1 → 0.1.3

package/dist/engine/scaffold/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAehC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAiLjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,YAAY,EAAE,CAO9C"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAehC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAmNjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,YAAY,EAAE,CAO9C"}

package/dist/engine/scaffold/scaffold.js

@@ -103,10 +103,12 @@ One change = one pass through this loop. Do NOT skip the last step:
 2. \`picopilot tokens\` to watch the 8192-token budget.
 3. \`picopilot verify\` (the static gate: tokens + integrity). GREEN means
    well-formed, it does NOT mean the cart runs or plays.
-4. **SEE it run.** Add a temporary probe to \`main.lua\` and \`picopilot run\`, then
-   LOOK at the screenshot PNG. Remove the probe after. Or use
-   \`picopilot playtest run\` to drive input and screenshot live gameplay with no
-   cart edit. Probe recipe:
+4. **SEE it PLAY, not just render.** A single screenshot proves a frame draws; it
+   does NOT prove the game behaves. So DRIVE it and watch it change over time:
+   \`picopilot playtest run\` feeds input and captures live gameplay with no cart
+   edit, or add the temporary \`run\` probe below to grab specific frames. Capture
+   a sequence and compare frames so you can see MOTION and STATE CHANGE, not one
+   still. Probe recipe:
 
    \`\`\`lua
    -- TEMPORARY: screenshot a couple of frames, then signal done so run exits.
@@ -115,11 +117,32 @@ One change = one pass through this loop. Do NOT skip the last step:
    if t==45 then printh("__PICOPILOT_DONE__") end
    \`\`\`
 
-**Definition of done: you have looked at a screenshot of the running cart and it
-renders what you intended.** A green \`verify\` is NOT done. A \`picopilot run\`
-that ends in \`exitReason: timeout\` with NO screenshot is NOT proof it works, it
-just means the cart never self-quit; you still have not seen it. Never declare a
-game finished on static checks or a bare timeout alone.
+**Definition of done: you have driven YOUR game's core loop and confirmed its
+state actually behaves, not just that it renders.** Screenshots hide logic bugs
+(state that should change on an event but does not, or does not reset when it
+should). So do NOT check a fixed checklist: enumerate the state transitions YOUR
+specific game defines (whatever its own actions, events, and restart do), then
+drive each one and confirm the before/after state is what you intended, before
+AND after a full round or restart. If reading state off the screen is hard, add
+a temporary \`printh\` to dump the values and confirm them directly.
+
+Two checks that catch the bugs models ship most:
+
+- **Every DISTINCT outcome, in the right direction.** When the game has more than
+  one kind of interaction (different objects, hazards, or actions), drive EACH
+  kind separately and confirm its effect has the intended SIGN, a reward raises
+  what it should, a penalty lowers what it should. Do not verify one happy path
+  and assume the rest; the classic bug is two different interactions wired to the
+  same or opposite-signed effect (a hazard that adds score instead of costing a
+  life).
+- **Is it actually a GAME (can the player lose)?** After driving it, run the
+  design self-checks against what you SAW, not just the design on paper: can the
+  player genuinely fail (is there real pressure, or did you never come close to
+  losing, meaning it is too easy)? does it escalate? is it fair (no unavoidable
+  loss)? If you drove a full round and nothing threatened you, tune it before
+  calling it done. (The \`game-design-reference\` skill carries these self-checks.)
+
+A green \`verify\`, a bare \`timeout\`, or a nice-looking title is NOT done.
 
 ## Handing the finished cart to the user
 
@@ -201,6 +224,17 @@ in \`picopilot.json\`), so you never silently destroy map data you cannot see.
 - **Cart data:** \`cartdata(id)\`, \`dget(i)\`, \`dset(i,v)\`.
 - **Debug:** \`printh(str)\` (to host stdout, \`picopilot run\` captures it), \`stat(n)\`.
 
+**Do NOT guess an API name.** If a function is not in this list and you are not
+SURE it exists, look it up before writing the call, do not invent one. The
+common crashes: random is \`rnd(x)\` (a float in \`[0,x)\`; integer \`flr(rnd(n))\`),
+NOT \`rand\`/\`ranf\`/\`random\`; there is NO built-in collision (write an AABB
+overlap yourself); \`spr\` is \`spr(n,x,y,[w,h],[fx],[fy])\` with NO color/rotate
+arg; persistence is \`cartdata\`+\`dset\`/\`dget\`, not \`poke4\`; bare \`flr\`/\`abs\`/\`min\`
+(no \`math.\`); \`add\`/\`del\`/\`deli\` (no \`table.insert\`). The \`picopilot-code\` skill
+ships a full \`reference/pico8-api.md\` (exact signatures + a wrong-name table);
+read it when unsure. A nil-call crash costs a whole playtest round; the lookup
+does not.
+
 ## Gotchas that silently break carts (these differ from normal Lua/math)
 
 These compile and run but behave WRONG. They are the traps models hit most:

package/dist/engine/scaffold/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;GASG;AAEH,0FAA0F;AAC1F,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,MAAM;IACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CACtB,sDAAsD,YAAY,aAAa,CAC/E,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,gBAAgB,IAAI,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO;IACtB,OAAO;;;;;;;;;;;;;CAaP,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa;IAC5B,OAAO,iBAAiB,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+KP,CAAC;AACF,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC5B,OAAO;QACN,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAC;QACpC,EAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EAAC;QACtC,EAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAC;QACxC,EAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,EAAC;KAClD,CAAC;AACH,CAAC"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;GASG;AAEH,0FAA0F;AAC1F,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,MAAM;IACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CACtB,sDAAsD,YAAY,aAAa,CAC/E,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,gBAAgB,IAAI,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO;IACtB,OAAO;;;;;;;;;;;;;CAaP,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa;IAC5B,OAAO,iBAAiB,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiNP,CAAC;AACF,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC5B,OAAO;QACN,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAC;QACpC,EAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EAAC;QACtC,EAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAC;QACxC,EAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,EAAC;KAClD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picopilot",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "An agent-first toolchain for PICO-8 game development, built on the incur CLI framework.",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/commands/init.test.ts

@@ -126,6 +126,33 @@ describe('picopilot init: AGENTS.md carries the curated PICO-8 reference', () =>
 		expect(agents).toContain('__PICOPILOT_DONE__');
 		// A bare timeout is explicitly NOT proof it works.
 		expect(agents.toLowerCase()).toContain('timeout');
+		// Done means BEHAVIOUR verified, not just a rendered frame: drive the core
+		// loop and confirm state transitions (the bugs a screenshot hides).
+		const lower = agents.toLowerCase();
+		expect(lower).toContain('state');
+		expect(lower).toMatch(/behave|behaviour|behavior/);
+		// GENERIC, not a fixed mechanic checklist: it must tell the agent to
+		// enumerate ITS OWN game's transitions, so it neither assumes mechanics the
+		// game lacks nor checks only a canned list and misses the rest.
+		expect(lower).toContain('enumerate');
+		expect(lower).toMatch(/your (specific )?game/);
+		expect(lower).toContain('do not check a fixed checklist');
+		// Two named checks: distinct-outcome correctness (sign of the effect) and
+		// is-it-a-game / can-the-player-lose (the too-easy check), both generic.
+		expect(lower).toContain('distinct');
+		expect(lower).toMatch(/sign|direction/);
+		expect(lower).toMatch(/can the player lose|player.*(lose|fail)/);
+		expect(lower).toContain('too easy');
+	});
+
+	it('warns against guessing the API and points at the shipped pico8-api reference', () => {
+		const lower = agents.toLowerCase();
+		expect(lower).toContain('do not guess');
+		expect(agents).toContain('reference/pico8-api.md');
+		// Names the exact traps from the observed run: rnd-not-rand, no collision.
+		expect(agents).toContain('rnd(x)');
+		expect(agents).toContain('rand');
+		expect(agents.toLowerCase()).toContain('no built-in collision');
 	});
 
 	it('hands the finished cart off via `pico8 -run`, NOT `serve`', () => {

package/src/engine/scaffold/scaffold.ts

@@ -112,10 +112,12 @@ One change = one pass through this loop. Do NOT skip the last step:
 2. \`picopilot tokens\` to watch the 8192-token budget.
 3. \`picopilot verify\` (the static gate: tokens + integrity). GREEN means
    well-formed, it does NOT mean the cart runs or plays.
-4. **SEE it run.** Add a temporary probe to \`main.lua\` and \`picopilot run\`, then
-   LOOK at the screenshot PNG. Remove the probe after. Or use
-   \`picopilot playtest run\` to drive input and screenshot live gameplay with no
-   cart edit. Probe recipe:
+4. **SEE it PLAY, not just render.** A single screenshot proves a frame draws; it
+   does NOT prove the game behaves. So DRIVE it and watch it change over time:
+   \`picopilot playtest run\` feeds input and captures live gameplay with no cart
+   edit, or add the temporary \`run\` probe below to grab specific frames. Capture
+   a sequence and compare frames so you can see MOTION and STATE CHANGE, not one
+   still. Probe recipe:
 
    \`\`\`lua
    -- TEMPORARY: screenshot a couple of frames, then signal done so run exits.
@@ -124,11 +126,32 @@ One change = one pass through this loop. Do NOT skip the last step:
    if t==45 then printh("__PICOPILOT_DONE__") end
    \`\`\`
 
-**Definition of done: you have looked at a screenshot of the running cart and it
-renders what you intended.** A green \`verify\` is NOT done. A \`picopilot run\`
-that ends in \`exitReason: timeout\` with NO screenshot is NOT proof it works, it
-just means the cart never self-quit; you still have not seen it. Never declare a
-game finished on static checks or a bare timeout alone.
+**Definition of done: you have driven YOUR game's core loop and confirmed its
+state actually behaves, not just that it renders.** Screenshots hide logic bugs
+(state that should change on an event but does not, or does not reset when it
+should). So do NOT check a fixed checklist: enumerate the state transitions YOUR
+specific game defines (whatever its own actions, events, and restart do), then
+drive each one and confirm the before/after state is what you intended, before
+AND after a full round or restart. If reading state off the screen is hard, add
+a temporary \`printh\` to dump the values and confirm them directly.
+
+Two checks that catch the bugs models ship most:
+
+- **Every DISTINCT outcome, in the right direction.** When the game has more than
+  one kind of interaction (different objects, hazards, or actions), drive EACH
+  kind separately and confirm its effect has the intended SIGN, a reward raises
+  what it should, a penalty lowers what it should. Do not verify one happy path
+  and assume the rest; the classic bug is two different interactions wired to the
+  same or opposite-signed effect (a hazard that adds score instead of costing a
+  life).
+- **Is it actually a GAME (can the player lose)?** After driving it, run the
+  design self-checks against what you SAW, not just the design on paper: can the
+  player genuinely fail (is there real pressure, or did you never come close to
+  losing, meaning it is too easy)? does it escalate? is it fair (no unavoidable
+  loss)? If you drove a full round and nothing threatened you, tune it before
+  calling it done. (The \`game-design-reference\` skill carries these self-checks.)
+
+A green \`verify\`, a bare \`timeout\`, or a nice-looking title is NOT done.
 
 ## Handing the finished cart to the user
 
@@ -210,6 +233,17 @@ in \`picopilot.json\`), so you never silently destroy map data you cannot see.
 - **Cart data:** \`cartdata(id)\`, \`dget(i)\`, \`dset(i,v)\`.
 - **Debug:** \`printh(str)\` (to host stdout, \`picopilot run\` captures it), \`stat(n)\`.
 
+**Do NOT guess an API name.** If a function is not in this list and you are not
+SURE it exists, look it up before writing the call, do not invent one. The
+common crashes: random is \`rnd(x)\` (a float in \`[0,x)\`; integer \`flr(rnd(n))\`),
+NOT \`rand\`/\`ranf\`/\`random\`; there is NO built-in collision (write an AABB
+overlap yourself); \`spr\` is \`spr(n,x,y,[w,h],[fx],[fy])\` with NO color/rotate
+arg; persistence is \`cartdata\`+\`dset\`/\`dget\`, not \`poke4\`; bare \`flr\`/\`abs\`/\`min\`
+(no \`math.\`); \`add\`/\`del\`/\`deli\` (no \`table.insert\`). The \`picopilot-code\` skill
+ships a full \`reference/pico8-api.md\` (exact signatures + a wrong-name table);
+read it when unsure. A nil-call crash costs a whole playtest round; the lookup
+does not.
+
 ## Gotchas that silently break carts (these differ from normal Lua/math)
 
 These compile and run but behave WRONG. They are the traps models hit most:

package/src/engine/skills/skills.test.ts

@@ -21,6 +21,11 @@ function readSkill(name: string): string {
 	return readFileSync(join(skillsSourceDir(), name, 'SKILL.md'), 'utf8');
 }
 
+/** Reads a skill RESOURCE file (a non-SKILL.md sibling, e.g. a reference doc). */
+function readRef(skill: string, rel: string): string {
+	return readFileSync(join(skillsSourceDir(), skill, rel), 'utf8');
+}
+
 describe('picopilot skills: generation output (the authored discipline skills)', () => {
 	it('ships exactly the named authored skills, each with valid frontmatter', () => {
 		expect([...SKILL_NAMES].sort()).toEqual(
@@ -130,6 +135,22 @@ describe('picopilot skills: generation output (the authored discipline skills)',
 		expect(md).toContain('+=');
 	});
 
+	it('picopilot-code POINTS AT the pico8-api reference (do-not-guess), and the reference names the traps', () => {
+		const md = readSkill('picopilot-code');
+		// The SKILL.md pointer: an on-demand "do not guess, read the API" pointer.
+		expect(md).toContain('reference/pico8-api.md');
+		expect(md.toLowerCase()).toMatch(/do not guess|don't guess/);
+		// The reference resource itself: exact signatures + the wrong-name table that
+		// covers the exact mistakes a weak model made (rnd-not-rand, no collision,
+		// spr arg count).
+		const api = readRef('picopilot-code', 'reference/pico8-api.md');
+		expect(api).toContain('rnd(x)');
+		expect(api).toContain('rand');
+		expect(api).toContain('rectcol');
+		expect(api).toContain('spr(n,x,y,[w,h]');
+		expect(api.toLowerCase()).toContain('do not exist');
+	});
+
 	it('picopilot-art carries the render→look→set→render loop AND the non-multimodal fallback', () => {
 		const md = readSkill('picopilot-art');
 		// The art loop.
@@ -314,6 +335,7 @@ describe('picopilot skills: isolated --install-skills (the load-bearing shared-w
 		expect(existsSync(join(codeSkill, 'SKILL.md'))).toBe(true);
 		for (const res of [
 			'reference/README.md',
+			'reference/pico8-api.md',
 			'reference/platformer.md',
 			'reference/puzzle-grid.md',
 			'reference/twin-stick-arcade.md',

package/src/skills/picopilot-code/SKILL.md

@@ -49,6 +49,19 @@ run. A green verify is well-formed, not proven-to-run, so it points you at
 `picopilot run`. With shrinko absent, verify is `gate-incapable` (never green),
 because it cannot check token bloat, the failure this loop exists to catch.
 
+## Do NOT guess the API: read `reference/pico8-api.md`
+
+The most expensive weak-model mistake is calling a function that does not exist
+(`rand`, `ranf`, `rectcol`, a `spr` with too many args) and only finding out when
+a playtest round crashes with `attempt to call nil value`. When you are unsure a
+function exists or what its arguments are, READ `reference/pico8-api.md` before
+writing the call: it lists the exact names + signatures of the common API and a
+table of the wrong names LLMs reach for (from mainstream Lua / other engines) and
+their real PICO-8 equivalents. Random is `rnd(x)` (a float in `[0,x)`), not
+`rand`/`ranf`; there is NO built-in collision (write an AABB); `spr` is
+`spr(n,x,y,[w,h],[fx],[fy])` with no color/rotate arg. Checking the reference is
+far cheaper than burning a run on a nil-call crash.
+
 ## PICO-8 gotchas that break carts silently
 
 These are NOT token issues; they are behaviours that differ from mainstream Lua
@@ -94,4 +107,5 @@ from this skill's `reference/` folder (see `reference/README.md` for the index):
 - `reference/rpg-menus-dialog.md`: UI state stack, cursor menus, timed text reveal.
 
 Each carries a minimal idiomatic implementation and a genre-pitfalls checklist.
-Adapt them to your game.
+Adapt them to your game. `reference/pico8-api.md` (the exact API surface) sits in
+the same folder for when you need to look a function up.

package/src/skills/picopilot-code/reference/README.md

@@ -7,7 +7,13 @@ implementations written in idiomatic, token-cheap PICO-8 Lua (see the
 `picopilot-code` SKILL for the token discipline they follow). They teach the
 STRUCTURE and the genre-specific pitfalls; adapt them to your game.
 
-Load the ONE that matches your game:
+First, whenever you are unsure a PICO-8 function exists or what its arguments
+are, read the API surface (do NOT guess a name like `rand`/`rectcol`):
+
+- `pico8-api.md`: EXACT names + signatures for the whole common API, plus a
+  table of wrong names that do NOT exist in PICO-8 and their real equivalents.
+
+Then load the ONE genre file that matches your game:
 
 - `platformer.md`: side-view gravity/jump, per-axis tile collision, camera
   follow.

package/src/skills/picopilot-code/reference/pico8-api.md

@@ -0,0 +1,118 @@
+# PICO-8 API reference (exact names and signatures)
+
+The PICO-8 function surface with EXACT names and argument order. Read this instead of guessing: the #1 way an agent wastes a run is calling a function that does not exist (`rand`, `ranf`, `rectcol`) or passing the wrong arguments, then burning a playtest round on an `attempt to call nil value` crash. If you are unsure a function exists or what its arguments are, look it up HERE first. `[x]` marks an optional argument.
+
+## Do NOT guess: names that do NOT exist in PICO-8
+
+These are the wrong names an LLM reaches for out of habit (mainstream Lua, JS, other engines). Each one crashes or silently misbehaves. Use the RIGHT column.
+
+| You may type (WRONG) | PICO-8 reality |
+|----------------------|----------------|
+| `rand()`, `ranf()`, `random()`, `math.random` | `rnd(x)` returns a float in `[0,x)`; `rnd()` is `[0,1)`. Integer: `flr(rnd(n))`. `rnd(tbl)` picks a random element. |
+| `rand(lo,hi)` (a range) | there is NO range form. Do `lo+rnd(hi-lo)` (float) or `lo+flr(rnd(hi-lo))` (int). |
+| `rectcol`, `collide`, `intersect`, `overlap` | NO built-in collision. Write your own AABB (see below). |
+| `math.floor`, `math.abs`, `math.min`, `math.max`, `math.sqrt` | bare `flr`, `abs`, `min`, `max`, `sqrt` (no `math.` table). |
+| `table.insert`, `table.remove` | `add(t,v)`, `del(t,v)` (by value), `deli(t,i)` (by index). |
+| `string.sub`, `s:sub(..)`, `#s` for chars | `sub(s,i,j)` (1-based, inclusive both ends). |
+| `print(x,y,...)` with x,y swapped, or `printf` | `print(str,[x,y,[col]])` (string FIRST). |
+| `pset(x,y,col)` ok, but `pget(x,y,col)` | `pget(x,y)` takes NO color (it READS one). |
+| `2*pi`, `sin(radians)` | `sin`/`cos` take TURNS `0..1`, and `sin` is INVERTED. A full circle is `t:0->1`. Do NOT multiply by pi. |
+| `poke4` for "save a number" | persistence is `cartdata(id)` then `dset(i,v)` / `dget(i)`. (`poke2/poke4` exist but are raw 16/32-bit RAM writes, not a save API.) |
+| `//` (Lua 5.3 int-divide) | `\` is integer divide (`5\2`==2). `/` does NOT truncate. |
+| shadowing builtins as locals: `local type`, `local add`, `local t=...` near `t=time()` | do not name locals after builtins/globals you use (`type`, `add`, `del`, `t`, `x`, `y`, `pal`, `time`, `sub`). It silently breaks calls to them. |
+
+## AABB overlap (there is no built-in collision, write this)
+
+```lua
+function hit(ax,ay,aw,ah, bx,by,bw,bh)
+ return ax<bx+bw and bx<ax+aw and ay<by+bh and by<ay+ah
+end
+```
+
+## Graphics
+
+- `cls([col])` clear screen (to `col`, default 0).
+- `spr(n,x,y,[w,h],[flip_x],[flip_y])` draw sprite `n` at `x,y`. `w,h` are in SPRITES (default 1,1), NOT pixels. There is NO color/rotate/scale arg; that is `sspr`/`pal` territory. Do NOT pass extra args.
+- `sspr(sx,sy,sw,sh,dx,dy,[dw,dh],[flip_x],[flip_y])` stretch a spritesheet rect.
+- `map(cx,cy,sx,sy,cw,ch,[layer])` draw map cels `cx,cy` (size `cw,ch`) at screen `sx,sy`.
+- `pset(x,y,[col])`, `pget(x,y)` (pget reads, no col arg).
+- `sget(x,y)`, `sset(x,y,[col])` read/write a spritesheet pixel.
+- `print(str,[x,y,[col]])` string is the FIRST arg. Returns the x cursor after.
+- `rect(x0,y0,x1,y1,[col])`, `rectfill(x0,y0,x1,y1,[col])` (two CORNERS, not x,y,w,h).
+- `circ(x,y,r,[col])`, `circfill(x,y,r,[col])`.
+- `oval(x0,y0,x1,y1,[col])`, `ovalfill(...)` (bounding-box corners).
+- `line(x0,y0,x1,y1,[col])`.
+- `pal([c0,c1,[p]])` remap color `c0`->`c1` (p=0 draw, 1 screen). No-arg `pal()` RESETS.
+- `palt([col,t])` set color `col` transparent (`t` true/false). No-arg resets (0 transparent).
+- `camera([x,y])` offset all later draws. No-arg resets.
+- `clip([x,y,w,h])` clip rect. No-arg resets.
+- `color([col])` set the default pen color.
+- `fillp([pat])` set the fill pattern for shape fns.
+- `flip()` present the frame (rarely needed; `_draw` flips for you).
+- `cursor([x,y,[col]])`, `fget`/`fset` (flags, under Map).
+
+## Map and sprite flags
+
+- `mget(x,y)` read the map cel (sprite index) at tile `x,y`.
+- `mset(x,y,v)` write a map cel.
+- `fget(n,[f])` get sprite `n` flags (all as a bitfield, or bit `f`).
+- `fset(n,[f],v)` set sprite flags.
+
+## Input
+
+- `btn([i,[p]])` is button `i` HELD? (i=0..5 = left,right,up,down,O,X; p=player 0..7). No-arg returns a bitfield.
+- `btnp([i,[p]])` was button `i` just PRESSED this frame (with auto-repeat)?
+- Button ids: 0 left, 1 right, 2 up, 3 down, 4 O (z/c/n), 5 X (x/v/m).
+
+## Audio
+
+- `sfx(n,[channel,[offset,[length]]])` play sfx `n`. `n=-1` stops. `channel=-1` any, `-2` stop on the channel.
+- `music([n,[fade_ms,[channel_mask]]])` play music pattern `n`. `n=-1` stops.
+
+## Math (all bare, no `math.` table)
+
+- `flr(x)` floor (round toward -inf). `ceil(x)` = `-flr(-x)`.
+- `abs`, `min(a,b)`, `max(a,b)`, `mid(a,b,c)` (the middle value = idiomatic CLAMP), `sgn(x)`.
+- `sqrt(x)`, `rnd([x])` (float `[0,x)`; `rnd(tbl)` picks an element), `srand(x)` (seed).
+- `sin(t)`, `cos(t)` take TURNS `0..1`; `sin` is INVERTED (screen +y down). `atan2(dx,dy)` returns a turn `0..1`.
+- `%` modulo, `\` integer divide, `&` `|` `^^` `~` `<<` `>>` bitops (Lua-5.3-style ops are NOT all present; use these).
+
+## Tables and iteration (1-BASED)
+
+- `add(t,v,[i])` append (or insert at `i`), returns `v`.
+- `del(t,v)` remove the first element EQUAL to `v` (by value).
+- `deli(t,[i])` remove the element at INDEX `i` (default last), returns it.
+- `count(t,[v])` length (or count of `v`). `#t` also works for a contiguous array.
+- `all(t)` iterator for `for x in all(t) do`. `foreach(t,fn)` call `fn(v)` per element.
+- `pairs(t)`, `ipairs(t)`, `next(t)`. `unpack(t)`, `pack(...)`.
+- Deleting the CURRENT item is safe in `foreach` and in a DESCENDING `for i=#t,1,-1`; an ASCENDING `for i=1,#t` ERRORS once the list shrinks.
+
+## Strings
+
+- `sub(s,i,[j])` substring, 1-based, INCLUSIVE both ends (`sub("abc",2,3)`=="bc").
+- `#s` length, `..` concat, `tostr(x,[hex])`, `tonum(s)`, `chr(n)`, `ord(s,[i])`.
+- `split(s,[sep,[convert]])` -> a 1-based array (great for cheap data tables). NO Lua `string` stdlib (`string.format`, `gsub`, etc. do NOT exist).
+
+## Memory (raw RAM; wrong addresses corrupt gfx/sound/state)
+
+- `peek(addr)`, `poke(addr,v)` one byte. `peek2/poke2` 16-bit, `peek4/poke4` 32-bit (fixed-point).
+- `memcpy(dst,src,len)`, `memset(dst,val,len)`, `reload(...)`, `cstore(...)`.
+- Only poke DOCUMENTED addresses (see the memory map in `AGENTS.md`). Prefer the draw functions above over poking the screen.
+
+## Cart data (persistent save)
+
+- `cartdata(id)` register a 64-slot save block (call ONCE in `_init`; `id` is a unique string).
+- `dget(i)` read slot `i` (0..63), `dset(i,v)` write it. This is how you save a high score, NOT `poke4`.
+
+## System / debug
+
+- `time()` / `t()` seconds since start (a fixed-point float). Do NOT name a local `time`.
+- `stat(n)` system info (`stat(6)` is the `-p`/playtest input string; others: memory, fps, etc.).
+- `printh(str,[filename])` print to the HOST stdout (picopilot `run`/`playtest` capture this) -> your main debug channel.
+- `menuitem(...)`, `extcmd(cmd)` (`extcmd("screen")` screenshots, used by the run probe), `stop()`, `assert(cond,[msg])`, `trace()`.
+
+## The execution loop
+
+- `_init()` once at start. `_update()` at 30fps (or `_update60()` at 60fps, not both). `_draw()` once per visible frame. Mutate state ONLY in `_update`; `_draw` can be skipped under load.
+
+For the behaviours that differ from mainstream Lua/math (turns-not-radians, integer divide, 1-based tables, persistent draw state, the `and/or` ternary trap), see the gotchas in `AGENTS.md`. This file is WHAT EXISTS; that is HOW IT BEHAVES.