@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-game-feel/references/motion.md

@@ -0,0 +1,134 @@
+# Motion as data: gaits and strikes
+
+A walk, a limp, a pounce and a heavy swing are numbers before they are code. Every starter ships
+three engine-free files that hold them: `src/motion.ts` (gait presets and their dials),
+`src/motion-sample.ts` (the stride driven by distance, the pose at a phase, a clip's rate) and
+`src/strike.ts` (key poses and timed phases). Pick a preset, tune a few dials, and print the
+warnings while you tune. While you build (the dev server, or `strict: true`) a dial past its range
+is refused with the reason the edge exists, so a number you tuned never silently becomes another;
+in a shipped game nothing throws: it is held at the edge and named.
+
+Units are body heights (bh), so the same table serves a 64 px sprite and a 1.75 m person: a person
+walking 1.4 m/s moves 0.8 bh/s.
+
+## Gaits: pick a preset, tune the dials
+
+| Preset | designSpeed (bh/s) | stride (bh) | stance | What reads |
+|---|---|---|---|---|
+| walk | 0.8 | 0.8 | 0.62 | two bobs a stride, arms opposite the legs |
+| run | 2.3 | 1.6 | 0.38 | both feet off the ground, a lean into speed |
+| sneak | 0.4 | 0.6 | 0.72 | hips low (crouch 0.25), arms close, small bob |
+| carry | 0.6 | 0.65 | 0.66 | arms braced (swing 0.05), more side sway |
+| limp | 0.5 | 0.6 | 0.64 | the bad leg plants shorter, the body dips on it |
+| old | 0.5 | 0.55 | 0.68 | short steps, a forward stoop, low foot lift |
+| child | 1.0 | 0.85 | 0.58 | quick, bouncy, big arm swing |
+| quadruped | 1.2 | 1.0 | 0.6 | hind, fore, hind, fore (height = shoulder) |
+| flyer | 3.0 | n/a | n/a | 6 beats a second, 30% of each cycle gliding |
+
+The dials and their ranges (`GAIT_DIALS`): designSpeed 0.2–4, stride 0.3–2.2, stance 0.25–0.75
+(above 0.5 walks, below runs), bob 0–0.06 of height, footLift 0–0.25, lean −0.2–0.35 rad,
+armSwing 0–0.8 rad (past it the hands crest the shoulder and flail), hipYaw 0–0.3 rad (the chest
+turns back 60% of it), sway 0–0.04, crouch 0–0.35, limp 0–0.6, flapHz 0–12, glide 0–0.8.
+
+`checkGait` also names pairings that read wrong: a deep crouch above 1 bh/s (a scuttle), a run's
+stance under a walk's pace (jogging on the spot), a step rate outside 1–4.5 a second (change the
+stride, not the clock), a flyer with no beat (a stone gliding).
+
+Give each person in a crowd one asymmetry (a limp of 0.1, a swagger of hip turn, a stoop) and
+vary designSpeed ±15%: a crowd on one preset marches like a drill team.
+
+## Keep the feet on the ground
+
+A clip or a stride is tuned for one speed. Played at another, the feet slide. Two routes:
+
+```ts
+import { gait } from './motion';
+import { advance, clipTimeScale, sampleGait } from './motion-sample';
+
+const { gait: g, warnings } = gait('walk', { limp: 0.15, designSpeed: 0.75 });
+if (import.meta.env.DEV) for (const w of warnings) console.warn('gait ' + w.dial + ': ' + w.why);
+
+// A rigged clip (three.js AnimationMixer): the rate follows ground speed, held at 0.6–1.6.
+const t = clipTimeScale(g, speedMps / heightM);
+walkAction.timeScale = t.scale;
+if (t.switchTo) crossFadeTo(t.switchTo);        // a run clip, not a walk at 2×
+
+// Parts in code (a cut-out rig or a primitive body): the phase moves by distance walked.
+phase = advance(g, phase, movedThisFrameM / heightM, dt);
+const p = sampleGait(g, phase);
+hips.position.y = hipHeight + p.y * heightM;
+hips.position.x = p.x * heightM;
+hips.rotation.y = p.hipYaw; chest.rotation.y = p.chestYaw; body.rotation.x = p.lean;
+armL.rotation.x = p.arms[0]; armR.rotation.x = p.arms[1];
+p.legs.forEach((leg, i) => { feet[i].position.z = leg.x * heightM; feet[i].position.y = leg.lift * heightM; });
+```
+
+A planted foot moves backward at exactly the body's speed (it stays still on the ground), and a
+swinging foot eases forward on a sine, never a triangle wave. Standing still plays idle, never a
+walk at rate 0. A flyer's phase moves by time (`flapHz`), and `p.wing` runs −1 to 1; tilt the body
+into each turn as well.
+
+### A walk made of pictures
+
+A sheet walk follows the same rule: the frame comes from the phase, and the phase from distance.
+
+```ts
+phase = (phase + movedThisFrameM / (0.8 * heightM)) % 1;   // one cycle per ~0.8 body heights
+body.material.map.offset.x = Math.floor(phase * FRAMES) / FRAMES;
+body.position.y = Math.abs(Math.sin(phase * Math.PI * 2)) * 0.03 * heightM;  // bob at twice the step rate
+```
+
+Use 8–12 frames for the hero (contact, down, passing, up per foot) and 6+ for a background
+walker; fewer pops between poses. Hold the contact frame on a stop rather than snapping to idle
+mid-stride. `walk` reports `HERO WALK POPS` (under 6 frames), `ON A TREADMILL` (walk frames while
+standing) and `ON A TIMER` (frames that keep the clock's pace when the speed changes); contact and
+bob are for your eye on the walk film.
+
+Declare the preset in the actors contract (`gait: "walk"`, `height: 1.7`, HOOKS.md "Actors"), and
+`npx @funpixel/tools life` adds a note when an actor's travel is far from its preset's designSpeed
+(the feet moonwalk or scramble) and names the nearer preset, or when a declared gait slides.
+
+## Strikes: five keys, four phases
+
+`src/strike.ts` holds a strike as guard → wind-up → contact → follow-through → guard, with seconds
+for each phase and an easing each: the wind-up eases out and settles into the pose, the strike
+eases in and accelerates to contact, the follow-through carries past the target, the recovery
+eases home. `bodyLead` starts the hips and chest that long before the arm.
+
+| Preset | anticipation | strike | follow-through | recovery | lead |
+|---|---|---|---|---|---|
+| jab | 0.10 | 0.05 | 0.08 | 0.15 | 0.03 |
+| heavy (overhead) | 0.40 | 0.09 | 0.25 | 0.45 | 0.08 |
+| sweep | 0.22 | 0.08 | 0.20 | 0.30 | 0.06 |
+| kick | 0.18 | 0.07 | 0.12 | 0.28 | 0.05 |
+| lunge (a creature's bite) | 0.30 | 0.06 | 0.10 | 0.40 | 0.04 |
+
+Ranges: anticipation 0.08–0.6 s, strike 0.03–0.15 s (slower reads as a push), follow-through
+0.05–0.4 s, recovery 0.1–0.8 s (the window an opponent punishes), lead 0–0.12 s. `checkStrike`
+names a wind-up under 1.5× the strike (weightless) and an arm over the shoulder on a move that is
+not an overhead (out of control).
+
+```ts
+import { STRIKES, strikeAt } from './strike';
+
+let t = 0;                                       // set to 0 on the press
+function update(dt: number) {
+  const before = t; t += dt;
+  const r = strikeAt(STRIKES.heavy, t, before);
+  if (r.contact) resolveHit();                  // once, on the contact frame, never on the press
+  arm.rotation.x = -r.pose.raise * 1.6;
+  arm.position.z = r.pose.reach * 0.4;
+  chest.rotation.y = r.body.twist * 0.6;        // the body leads the arm
+  hips.position.y = baseY - r.body.crouch * heightM;
+}
+```
+
+`r.impactPhase` is where contact sits in the whole move (0–1); hitstop, the flash and the sound
+belong on that frame ([contact.md](contact.md)). The enemy's tell is its anticipation: tune it
+with `funtools feel`'s tell-to-strike reading, not by feel alone.
+
+## These are starting points
+
+The presets are reference numbers to tune, not finished motion. A game's own character (a weary
+courier, a skittish crab) comes from moving two or three dials away from the preset on purpose and
+saying why in the GDD's `## Actors` Motion column.

package/plugins/kiro/skills/funpixel-game-feel/references/payoffs.md

@@ -0,0 +1,35 @@
+# Response, reward and restraint
+
+Measure the core action before adding decoration. Record the input frame, acknowledgement frame,
+contact frame and peak pose. At 60 Hz, 3–4 frames is roughly 50–67 ms; label a duration in
+milliseconds if the game is not fixed at 60 Hz. An immediate pose and sound confirm a press even
+when the attack needs a longer wind-up. Input buffering survives local hitstop.
+
+When escalation serves the loop, make a payoff ladder in the design note, with distinct rewards where useful. A three-tier chain example:
+
+| Tier | Trigger | Visible answer | Audio | Recovery |
+|---|---|---|---|---|
+| Small | one target | directional kick, 3-frame peak, 6 fragments | dry pop | next input available |
+| Medium | three linked targets | ripples staggered 70 ms, one combined score | rising three-note phrase | readable gaps between ripples |
+| Peak | a rare six-target chain | 4-frame hero pose, expanding ring, score parked above play | short sting, music ducks | threats stay visible |
+
+These are starting values to test, not universal settings. Choose distinct poses or compositions,
+not just the same scale tween with a larger number. Keep hit effects attached to the target and
+show the direction of force. A death has a collapse or exit; the player can follow where it went.
+If a pickup flies to the HUD, its arrival updates or pulses the correct counter once.
+
+Schedule quiet beats between rewards. Music can add a layer at a higher stage and resolve on its
+clear; a repeated attack should not restart the track or replay a sting every frame. Give every
+sim event its declared answer, including failure, recovery and menu actions. At the peak, check
+hero/threat silhouettes, score overlap and phone frame cost before adding another particle.
+
+Prove timing in a short capture sequence with the input and event times alongside it. Stills can
+prove composition; they cannot prove latency, rhythm, music or a satisfying loop. Use the blind
+player's real-input report for control and comprehension, audio observations for sound, and
+clips for motion review when the reviewer can actually watch them. Mark unavailable evidence
+`not observed`. Compare the reduced-motion version too: it keeps readable poses, outlines and
+sound while suppressing camera movement and full-screen flashes.
+
+A frustrating death is a design finding: record the last safe decision, the warning and the
+available escape. Repeated unavoidable first-wave deaths mean change the opening pressure,
+controls or recovery rule. They are not fixed by a louder explosion.

package/plugins/kiro/skills/funpixel-game-feel/references/recipes.md

@@ -0,0 +1,107 @@
+# Feel recipes
+
+Optional patterns for an action game. Choose the feedback the current brief needs; these examples
+do not require sound, shake or flashing in every game. Adjust the event self-test to the declared
+response, including intentional silence. Use timings for player readability, not screenshot scores.
+
+A game `funtools init` made already has all of this: `src/feel.ts` (the table and its self-test),
+`src/juice.ts` (flash, hitstop, capped shake, particles, the motion switch) and `src/sound.ts`
+(buses, mute, ducking). Change their rows and numbers; use these recipes elsewhere.
+
+Engine-free TypeScript; the renderer reads the numbers. Frame counts assume 60 fps and are turned
+into seconds once, so a 120 Hz phone feels the same.
+
+## The table as data, and its self-test
+
+The juice table in the design note and this file say the same thing. The self-test fails the moment
+the sim emits an event nobody designed an answer for.
+
+```ts
+// src/feel.ts
+export type Feel = { visual: string; sfx: string; hitstop?: number; trauma?: number; fullFlash?: boolean };
+export const FEEL: Record<string, Feel> = {
+  lit:   { visual: 'hullFlash', sfx: 'bell_tick' },
+  wreck: { visual: 'spray10', sfx: 'timber_crack', hitstop: 6, trauma: 0.3 },
+  home:  { visual: 'scorePop', sfx: 'harbour_chime' },
+  dawn:  { visual: 'sunrise', sfx: 'dawn_sting' },
+  dark:  { visual: 'lampOut', sfx: 'lamp_die', trauma: 0.45, fullFlash: true },
+};
+
+// wherever the hooks are exposed
+exposeHooks({ selftests: [{
+  name: 'juice: every event has a visual and a sound',
+  run: () => EVENT_KINDS.every((k) => FEEL[k]?.visual && FEEL[k]?.sfx),
+}] });
+```
+
+`EVENT_KINDS` is the list the sim's `step()` can return, exported beside it.
+
+## Hitstop on the bodies, not the loop
+
+```ts
+const FRAME = 1 / 60;
+function hitstop(bodies: { freeze: number }[], frames: number) {
+  for (const b of bodies) b.freeze = Math.max(b.freeze, frames * FRAME);
+}
+// in the fixed step, per body: skip its motion while frozen; input, particles and HUD still run
+if (body.freeze > 0) { body.freeze -= dt; continue; }
+```
+
+## Trauma shake with a cap
+
+```ts
+const shake = { trauma: 0, max: 24, decay: 1.8, scale: 1 }; // scale: the player's setting, 0 under reduced motion
+export const addTrauma = (t: number) => { shake.trauma = Math.min(0.6, shake.trauma + t); };
+export function shakeOffset(dt: number, time: number) {
+  shake.trauma = Math.max(0, shake.trauma - shake.decay * dt);
+  const a = shake.trauma * shake.trauma * shake.max * shake.scale;
+  return { x: a * Math.sin(time * 47.3), y: a * Math.sin(time * 61.7 + 1.3) }; // applied to the camera only
+}
+```
+
+Keep the `addTrauma(` call sites few and named in the note; each is a moment you chose.
+
+## Squash around a base scale
+
+```ts
+sprite.baseScale = 1;                       // set once, at load, from the art's fit
+function squash(s: Squashable, sx: number, sy: number, frames: number) {
+  s.squash = { sx, sy, left: frames * FRAME, total: frames * FRAME };
+}
+// each frame: ease back to 1 and multiply, never assign an absolute scale
+if (s.squash && (s.squash.left -= dt) <= 0) s.squash = undefined;
+const k = s.squash ? easeOutBack(1 - s.squash.left / s.squash.total) : 1;
+s.scale.set(s.baseScale * lerp(s.squash?.sx ?? 1, 1, k), s.baseScale * lerp(s.squash?.sy ?? 1, 1, k));
+```
+
+## Easing and smoothing
+
+```ts
+export const easeOutCubic = (t: number) => 1 - (1 - t) ** 3;
+export const easeOutBack = (t: number) => 1 + 2.7 * (t - 1) ** 3 + 1.7 * (t - 1) ** 2;
+// a follow that feels the same at 30, 60 or 120 fps
+export const follow = (v: number, target: number, sharpness: number, dt: number) =>
+  v + (target - v) * (1 - Math.exp(-sharpness * dt));
+```
+
+## A number that pops where it was earned
+
+```ts
+function popNumber(layer: Container, text: string, x: number, y: number) {
+  const n = pool.take(text);                 // pooled text, tabular digits
+  n.position.set(x, y); n.alpha = 1; n.baseScale = 1.3;
+  tween(n, { y: y - 40, baseScale: 1, alpha: 0 }, 0.6, easeOutCubic, () => pool.give(n));
+}
+```
+
+## Reduced motion
+
+```ts
+const reduce = matchMedia('(prefers-reduced-motion: reduce)');
+export const comfort = { shake: reduce.matches ? 0 : 1, fullFlash: !reduce.matches, particles: reduce.matches ? 0.5 : 1 };
+reduce.addEventListener('change', (e) => Object.assign(comfort, { shake: e.matches ? 0 : 1, fullFlash: !e.matches, particles: e.matches ? 0.5 : 1 }));
+// the settings screen writes the same object and saves it; the player's choice wins over the media query
+```
+
+Hitstop, the struck body's own flash and every sound are never behind `comfort`: they are the
+answer, not the motion.

package/plugins/kiro/skills/funpixel-game-feel/references/unity.md

@@ -0,0 +1,73 @@
+# Game feel: motion, juice and haptics
+
+Feel bugs pass every test. One soccer game's sim (the engine-free rules, stepped at a fixed 60 Hz) was correct, but 1 frame in 8 advanced 0 or 2 sim ticks, so the ball stalled and then jumped all match; the owner called it trembling. This skill gives each moment a measured answer and names the effects that were built, then removed.
+
+## Tools
+
+Not in the kit: the Unity starter, coroutine tweens (a pop, a shake, eases), haptics by strength (iOS taptics through a native plugin, Android vibration effects, off with the player's setting), a frame-owner `GameDriver`, an interpolation blend with a trace flag, a near-miss tracker and the `moment_freq` check. Write those yourself:
+
+- A frame owner: one `MonoBehaviour` that reads input, steps the sim at a fixed rate (`sim.Update(dt)`), sends events to presenters and draws with `Render(alpha)`.
+- Interpolation and its trace: blend the drawn state between the last two ticks, and a dev-only launch flag that writes per-frame tick counts to a `trace.csv`.
+- A near-miss detector in the engine-free core, so bots can count it.
+- Frequency tests: bot batches in an Edit Mode test (`funtools unity run -- -nographics -runTests -testPlatform EditMode -testResults results.xml`, never with `-quit`: the test runner exits by itself), or `dotnet test` on an engine-free core, at 30 and 60 fps.
+
+No game uses DOTween (coroutine tweens do). One game's views branch aims its camera with Cinemachine 6.6 and plays its intro on Timeline; the rest drive the camera in code. Nothing checks sliding feet or loop pops.
+
+## Procedure
+
+1. Render interpolated between the last two fixed sim ticks. Check: 100% of frames with steps other than 1 are blended, and drawn-ball jerk p99 is under a threshold (value not in the report). A teleported or thrown ball blends for 0.18 s.
+2. Tie per-frame effects to sim steps, or scale them by dt (`1 - Math.Pow(0.4, dt*60)`). Check: headless runs at 60 and 120 Hz give the same end-state hash and effect counts per sim second.
+3. Buffer the main action. The soccer game's kick has a 200 ms buffer (`BufferMs`): a press arms it and the foot swings when the ball arrives.
+4. Answer each moment from the table.
+
+   | Moment | Answer | Duration |
+   |---|---|---|
+   | Button press | pop 0.18, light haptic, click | 0.22 s |
+   | Hit or smash | shake 0.08, particles, SFX pitch ±6%, medium or heavy haptic | 0.25 s shake |
+   | Pickup, coins | merged pop-ups, fly-to-counter | within 0.15 s |
+   | Callout | slam in from 1.4×; not replaced within 0.6 s | 0.6–0.8 s |
+   | Near miss | small callout, camera nudge, reaction pose, crowd ooh, haptic | 0.8 s; sound gate 600 ms |
+   | Win | 2 confetti waves, card pop, score counts up | about 1 s |
+   | Lose | "So close!" at 3 or fewer pieces left; no slow-mo | not in the report |
+   | Goal | net bulge, goal shake, the only big callout | no slow-mo |
+
+5. Map haptics by strength: a web vibration of 30 ms or more is heavy, 14 ms or more medium, else light. Throttle to 80–90 ms and merge pulses inside 120 ms into the strongest, so a light tap does not swallow a heavy one.
+6. Keep each tween's true rest scale (key it by Transform); otherwise a second pop records a mid-pop scale as the base.
+7. Draw particles from fixed pools; the pool is the budget. One 2D game: 2 quad batches, 600 particles. The soccer game: 220 sprites, 120 confetti, 14 rings in 6 batched meshes. At most 120 spawns per second, oldest recycled; ambient at most 40 live.
+8. Frequency-test every juice event with bot batches at 30 and 60 fps. The soccer game's targets: own goals at most 0.3 per match, misses and blocks 2–5 per 90 s.
+9. Keep in-match overlays minimal; do not freeze or slow play while the clock runs.
+10. Measure a camera change against the problem it is meant to fix, in frames.
+11. Honour the effects setting: shake is skipped when "Shake & flashes" is off, and the kickoff dolly (about 1/3 closer over the 1.5 s countdown) when screen effects are off.
+12. Animate by role:
+
+   | Role | How | Numbers |
+   |---|---|---|
+   | Hero | code; ports copy the web's procedural rig | pose tweens 0.22–0.4 s |
+   | Rigged cast (one game only) | Animator blend trees | transitions 0.12–0.15 s, exit time 0.9 |
+   | Crowd | vertex-animation textures, GPU instancing | 1,800 units in 18 draws |
+   | UI | coroutine tweens | defaults above |
+
+   Root motion is off everywhere: the sim owns positions.
+13. Show the owner a zoomed close-up on one asset before rolling out a style.
+14. Finish with a person playing on a phone: the soccer game's feel bugs came from the owner's TestFlight play.
+
+## Worked example
+
+A soccer game (a 3D port from three.js):
+
+1. A dev trace flag wrote `trace.csv`: at a 60 Hz sim, 1 frame in 8 (12%) advanced 0 or 2 ticks.
+2. A blend draws every frame between the last two ticks.
+3. A bot batch counted per match: OWN GOAL! 2.1 times (about 30% of goals), goal slow-mo 14 times.
+4. Own-goal detection depended on frame rate: 0.02 per match at 60 fps, 0.25 at 30 fps.
+5. The near-miss tracker's cooldown gives one moment per play; misses and blocks measured 4.2 per 90 s. Slow-mo was removed.
+
+## Common mistakes
+
+- Slow-mo on goals: fired 14 times a match, read as lag, and shipped in every TestFlight build until 1 Oct.
+- A follow camera showed both goals only 18–40% of the time; reverted to a fixed full-pitch view. With the next item, two rounds lost.
+- A camera lift for barks (a 2D game): changed 0 covered frames (2–8 of 165 either way) and added a 25–69 pt view shift; PR #11 was reverted in PR #12.
+- A sticker-border shader: a 2D mock-up style put on dogs, ball and goals before a close-up was shown. It did not transfer to 3D, broke static merging (dozens more draws), cost about 3 builds and was removed: "it was much better before". Four more decorations were reverted the same way in 24 h.
+- A 1.6 s freeze after goals read as "freezy".
+- Effects per render frame: at 120 Hz one game's bobs and sparkles ran twice as fast.
+- Concurrent pop tweens on one Transform: the cash pill grew huge (game not named).
+- "44 of 304 kicks connected" (the soccer game) is cited for this skill; its cause and fix are not in the report.

package/plugins/kiro/skills/funpixel-game-logic/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: funpixel-game-logic
+description: Use when writing a game's rules, levels, scoring, escalation or balance, or when a run is too short, too easy or too thin to replay. Covers seeded engine-free logic with tests, solvable levels, balance bots and depth (endless, a local best). In Unity (rules that run in tests with no scene), follow references/unity.md.
+---
+
+# Game logic outside the renderer
+
+The rules are what players master. Threes spent 14 months on one rule; Brotato publishes its wave
+schedule; Slay the Spire shows every enemy's next move. Rules you can read, tune and play a
+thousand times in a second are where depth comes from. Kept in plain TypeScript (no engine, DOM or
+Preact), seeded and tested, they can be balanced by a bot and ported: two of our web games went
+native in about a day each, and the ports found four bugs the tests had missed (research 12).
+
+## Tools
+
+- `probe` runs the game's `__FPX_SELFTEST__` entries and its `__FPX_LEVELS__` solver on
+  Funpixel's browsers, as `npx @funpixel/tools verify` does locally: a failed invariant or an
+  unsolvable level shows as a FAIL.
+- `check_plan` flags a design note whose escalation is only speed.
+- `npm test` runs the logic's tests (`node --test test/*.test.ts` in a `funtools init` game);
+  `npx @funpixel/tools test` records the run for the Stop hook; `test --node` runs the files with
+  Node alone when npm test cannot start (a bundler missing from PATH).
+- `npx @funpixel/tools sim` plays the rules with five simple players (idle, naive, taught,
+  skilled, novice) and names standing still that wins, a missing skill ceiling and the best
+  staged moment ([references/probes.md](references/probes.md)).
+- `npx @funpixel/tools reach` fills each level kept as data (tiles or the 3D spec) from its spawn
+  with the game's own jump and names every exit, pickup or room nothing reaches, with the gap in
+  the way ([references/levels.md](references/levels.md)).
+- `npx @funpixel/tools smoke` warns when a file in `src/rules.ts`, `src/sim/`, `src/logic/` or
+  `src/rules/` imports an engine, Preact or the DOM, calls `Math.random()`, or decides a hit from
+  display objects' bounds. Each warning names a rule the renderer now owns; moving it into `src/sim/`
+  with a test is the usual answer.
+
+## One shape that works
+
+1. **`src/sim/` imports nothing visual** (no `pixi.js`, `three`, `preact` or `window`). State is plain
+   data; `step(state, input, dt)` advances it and returns events as data
+   (`{ type: 'hit', target, hp }`). The renderer and the audio read state and events and leave the
+   state alone, so a test can drive the sim with no screen.
+2. **One seeded random source, passed in.** A `Math.random()` in the sim means a daily seed stops
+   reproducing its level and a bug cannot be replayed:
+   ```ts
+   export function mulberry32(seed: number) {
+     return () => { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+       t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+   }
+   ```
+   Cosmetic randomness (particles, dust) can use `Math.random()`, since it does not shift gameplay.
+   `__FPX_STATE__()` exposes `seed`.
+3. **Rules as numbered, named constants** (`R1 jump height 3.2 tiles`, `R2 coyote 80 ms`) in
+   `src/sim/rules.ts`, listed in the design note, each proved by a test named after it
+   (`R2: a jump 70 ms after leaving a ledge still fires`). One game's rule ids let traversal tests
+   catch a ledge with 64 px of headroom (research 12); a change then moves the note, the constant and
+   the test together.
+4. **Determinism as a test.** Same seed and inputs, same state hash; a tiebreaker on every sort and a
+   fixed physics step keep it true.
+5. **Tests beside the rules, outside `src`:** `test/*.test.ts`. The platform type-checks only `src`,
+   so test imports stay out of its build.
+
+## Levels
+
+Levels kept as data (a file or seed each) can be re-solved after every edit. Generating backwards
+from a solved state makes boards solvable by construction. A breadth-first solver in
+`__FPX_LEVELS__` lets verify prove every level solvable and chart the curve. Jump reach, safe
+spawns, hard levels on a rhythm: [references/levels.md](references/levels.md). Many levels from
+hand-made anchors plus a seeded recipe the bots check: [references/content-at-scale.md](references/content-at-scale.md).
+
+## Escalation changes what the player does
+
+Faster alone leaves the game the same, only harder to read, and `check_plan` flags a ramp that is
+speed alone. One game's review found its ramp invisible: the area indicator was computed and not
+drawn. A ramp as a list of what changes, new things one at a time, waves with rests, and a ramp the
+player can see: [references/escalation.md](references/escalation.md).
+
+## Depth and replay
+
+A finished level still loses to the genre hit on depth: run length, what happens per minute,
+pressure early, and a reason for run two. [references/depth.md](references/depth.md) has run
+lengths by genre, density targets, score attack, endless, daily seeds and a local best, each as an
+option with its reason; the bots below measure them.
+
+## Balance before art
+
+A headless loop over `src/sim` plays thousands of runs in seconds, where a browser session plays
+one, so tuning from bots, a frozen novice floor, a bot that finishes the level in `npm test` (in
+one game it caught a speed change that starved a route), a blind phone player, a parameter sweep
+and a hunt for what bots never do all come cheap once the rules stand alone. Each, with its reason
+and where it came from: [references/balance.md](references/balance.md); the five probe players and
+`sim`: [references/probes.md](references/probes.md).
+
+## Worked example
+
+A sort puzzle (tap a tube, tap a target, matching colours merge):
+1. `src/sim/tubes.ts`: `type Board = number[][]`, `legalMoves(b)`, `apply(b, m)`, `isSolved(b)`.
+2. `src/sim/generate.ts`: from a solved board of `R3 = 4` colours, 40 random reverse moves from
+   `mulberry32(seed)`, rejecting boards the solver finishes in under `R5 = 6` moves.
+3. `test/tubes.test.ts`: `R1: a move onto a different colour is refused`;
+   `generate(7) twice gives the same board`; `levels 1-50 are solvable and mostly get harder`.
+4. `exposeHooks({ levels: { count: 50, solve } })`: verify solves all 50 and reports a rising curve.
+5. The renderer draws the sim's `Board` and plays a rising pitch per merge.
+
+## Common mistakes
+
+- A `Math.random()` in the sim: the daily seed no longer reproduces the level, and bugs cannot be
+  replayed.
+- Rules read from sprite positions: now the logic cannot be tested.
+- A self-test that assumes the starting state: checks run first and change it.
+- Tuning difficulty by playing it yourself five times; a bot plays thousands.
+- Tests that re-implement the rule they test; asserting the outcome of a scripted input catches more.
+
+Where this comes from: our own games (rule ids, bots, probes, solvable-by-construction; research
+12) and the hits in research 18; procedural and puzzle habits began in our platform's genre notes;
+review and escalation habits partly from Claude Code Game Studios (MIT).

package/plugins/kiro/skills/funpixel-game-logic/references/balance.md

@@ -0,0 +1,88 @@
+# Balance before art
+
+Tuning by feel after the art is in means every change repaints something. With the rules in
+`src/sim/` and no renderer behind them, the numbers can be settled first, by bots, in seconds.
+Each practice below is an option with its reason; pick the ones the game needs and write what you
+chose into the design note.
+
+## Simulate before tuning
+
+A headless loop over `src/sim` plays thousands of runs in seconds, where a browser session plays
+one. Five of your own plays are an anecdote; a thousand bot runs are a distribution, and the worst
+case in it is usually the one a player meets.
+
+## Players beside the sharp bot
+
+A sharp bot tests exploits and mastery. It says little about a newcomer, so keep others beside it:
+
+- **A novice, for onboarding.** It reacts slowly, hesitates and misses, and uses only what a player
+  can see. Freezing its policy and seeds before tuning keeps the floor from moving with the
+  balance. For first-stage survival games, 80 of 100 fixed seeds that both survive and score is
+  the floor this kit's probes use; other genres name their own first success and deadline.
+- **An idle one, a naive one and one that does what the tutorial teaches.** They catch standing
+  still that wins, a missing skill ceiling and a tutorial that teaches a losing line
+  ([probes.md](probes.md) has each one's story and `npx @funpixel/tools sim`, which runs them).
+
+Saving the counts, the policy, the failing seeds and deaths by cause makes the next change
+comparable. Rerunning after each balance change, then on held-out seeds, shows whether the tuning
+fitted the seeds or the game. This floor is a regression check: it predicts no human success rate.
+
+## A bot that finishes the level, as a test
+
+`sim`'s probes describe and warn. A bot that plays the whole level or chapter inside `npm test`,
+and fails the suite when it no longer reaches the end, is the other half: a balance change that
+makes the level unfinishable turns the tests red at once. A `funtools init` game starts with one
+(`rules.test.ts`: `botRound` wins a round on seed 5); a longer game grows it. This is a lesson from
+one game (a 3D horror chapter, September 2026, gathered by its lane), and no
+first-try action game has tested it yet.
+
+Its chapter test (`chapter.test.ts`, "Contract H", named after the GDD's numbers) carried:
+
+- `median_bot_finishes` for each of two routes (seal every weldable door, or fight through) on five
+  seeds. The bot plays through the same intent a thumb produces, with a human reaction budget.
+- `weld_everything_bot_reaches_exit`: the route that welds everything finishes, with both welds.
+- `gas_ge_1_3x_median`: the chapter lays out at least 1.3 times the gas the worst of six bot runs
+  spends, so the shared resource has slack a real player needs.
+- `all_rooms_reach_exit_by_duct`: with every weldable door welded, every walkable cell still
+  reaches the exit, so no choice can soft-lock the chapter.
+- `same_seed_same_inputs_same_events`: a bot's intents replayed on a fresh sim give the same events
+  and state (what lets a run be replayed and filmed: skill `funpixel-game-spine`,
+  `references/replay.md`).
+
+**What it caught.** A mid-build request ("make her faster") raised walk and run from 2.5 / 4.5 to
+2.7 / 4.8 m/s, and it quietly broke the weld route: the bot rushed into extra fights, spent gas on
+them and could not afford the second weld. The finish test failed; the team settled on 2.5 / 4.5.
+Our reading: a faster hero feels like an improvement in the hand, so playing it would not have
+shown the cost (the movement table is in skill `funpixel-game-feel`, `references/contact.md`).
+
+Choices that made it useful, each an option:
+
+- **The failure message is the bot's trace** (`expect(r.done, trace.join(' | '))`), so a red test
+  says where the run stopped and what the bot was after.
+- **The tests keep one plain bot, fixed.** A keen `fighter` style that uses every weapon exists for
+  films only; changing the regression bot's policy moves the bar it checks, the same reason the
+  novice's policy is frozen above.
+- **Routes live with the level data**, with a fallback route (the gas, each objective top to bottom,
+  the exit) for a level that has none.
+
+A bot that finishes proves the level can be finished by that bot. It says nothing about whether a
+person finds the way or enjoys it; that is the blind phone player's job, below.
+
+## A blind phone player, judged apart
+
+A blind phone player tells three things apart: whether it found the goal, whether it could operate
+the controls, and whether it made progress. Expert wins do not cancel that player's confusion or
+deaths, since the expert already knows what the newcomer is missing. When the blind player
+struggles, controls, safe introductions and warning time are usually the cause; cutting every
+enemy's health hides the problem and flattens the game for everyone else.
+
+## Sweep one parameter
+
+Sweeping one parameter and writing the table (cost growth 1.10 against finish time, say) turns a
+guess into a choice: pick from the table, where the curve bends, rather than by feel.
+
+## What bots never do
+
+Bots play the game as written, so they miss a softlock only a human reaches and an offline payout
+that finishes the game overnight. Anything that accrues while the game is closed is worth a cap, or the first return
+visit ends the game.