@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-world-and-story/references/world-kit.md

@@ -0,0 +1,154 @@
+# A world from a kit: scatter, landmarks, the route
+
+Working code, checked in a scratch scaffold on pixi.js 8.21 and three 0.170 (captured and profiled
+at 844×390). Take what helps; change the numbers to the place.
+
+## The kit
+
+Six to twelve pieces in one style carry a whole area. Ways to get them:
+
+| Piece | Tool | Note |
+|---|---|---|
+| 2D props (rock, bush, lamp, crate, fence) | `generate_sprite`, one call per piece with the same style words | a style lock keeps them one family (skill `funpixel-art`) |
+| A state variant (lamp lit/unlit, bridge broken/mended) | `edit_image` on the accepted sprite | the same drawing changed, so the swap reads as the world changing |
+| Ground and paths | `generate_image` texture or strip (`funtools gen texture`) | seamless tiles under the scatter; the scatter hides the grid |
+| Characters that move | `generate_spritesheet` | idle and walk from one base |
+| 3D props | code-built (below), `generate_3d_model`, or `find_material` type `model` (Poly Haven, CC0) | instance anything placed more than a few times |
+| Sky | `generate_skybox`, or a Poly Haven HDRI via `get_material` | the sky sets the time of day and the palette |
+| A set with a plan | `build_level` (skill `funpixel-3d`) | interiors, a village square, anything with doors |
+
+## Scatter by rule
+
+Seeded dart-throwing with spacing: denser at the edges, sparse in the open, a clear route and a
+ring around each landmark, jittered scale, flip and tint. Engine-free.
+
+```ts
+// Dress a place from a kit: seeded, spaced, denser at the edges, the path kept clear.
+// Engine-free: it returns placements; Pixi or Three draws them.
+
+export interface Piece { name: string; radius: number; weight: number; zones?: Zone[] }
+export type Zone = 'edge' | 'field' | 'path-side' | 'landmark';
+export interface Placement { piece: string; x: number; y: number; scale: number; flip: boolean; tint: number; zone: Zone }
+export interface Area {
+  w: number; h: number;
+  /** The walkable route as points; pieces keep `clear` away from it, `path-side` pieces hug it. */
+  path: Array<[number, number]>; clear: number;
+  /** Landmarks already placed (a tower, a tree): scatter leaves a ring around each. */
+  landmarks: Array<{ x: number; y: number; r: number }>;
+}
+
+export function rng(seed: number) {
+  return () => { seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t ^= t + Math.imul(t ^ (t >>> 7), 61 | t); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+
+const distToPath = (x: number, y: number, path: Area['path']) => {
+  let best = Infinity;
+  for (let i = 1; i < path.length; i++) {
+    const [ax, ay] = path[i - 1], [bx, by] = path[i], dx = bx - ax, dy = by - ay;
+    const k = Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / (dx * dx + dy * dy || 1)));
+    best = Math.min(best, Math.hypot(x - ax - k * dx, y - ay - k * dy));
+  }
+  return best;
+};
+
+/** Where a point sits: near an edge, beside the path, or in the open field. */
+function zoneOf(x: number, y: number, a: Area): Zone | null {
+  const d = distToPath(x, y, a.path);
+  if (d < a.clear) return null;                                  // the route stays readable
+  if (a.landmarks.some((l) => Math.hypot(x - l.x, y - l.y) < l.r)) return null; // landmarks breathe
+  if (d < a.clear * 1.8) return 'path-side';
+  const edge = Math.min(x, y, a.w - x, a.h - y);
+  return edge < Math.min(a.w, a.h) * 0.14 ? 'edge' : 'field';
+}
+
+/** Dart-throwing with spacing: `tries` candidates, each kept only if no neighbour is closer than the sum of radii. */
+export function scatter(kit: Piece[], a: Area, seed: number, tries = 1500, density: Record<Zone, number> = { edge: 1, 'path-side': 0.6, field: 0.25, landmark: 0 }): Placement[] {
+  const r = rng(seed), out: Placement[] = [], total = kit.reduce((s, p) => s + p.weight, 0);
+  for (let i = 0; i < tries; i++) {
+    const x = r() * a.w, y = r() * a.h, zone = zoneOf(x, y, a);
+    if (!zone || r() > density[zone]) continue;
+    let pick = r() * total, piece = kit[0];
+    for (const p of kit) { pick -= p.weight; if (pick <= 0) { piece = p; break; } }
+    if (piece.zones && !piece.zones.includes(zone)) continue;
+    const scale = 0.8 + r() * 0.45;
+    if (out.some((o) => Math.hypot(o.x - x, o.y - y) < (kit.find((k) => k.name === o.piece)!.radius * o.scale + piece.radius * scale) * 0.9)) continue;
+    const warm = Math.round(235 + r() * 20);                     // a small tint jitter breaks the copy-paste look
+    out.push({ piece: piece.name, x, y, scale, flip: r() < 0.5, tint: (warm << 16) | (Math.round(240 + r() * 15) << 8) | 235, zone });
+  }
+  return out.sort((p, q) => p.y - q.y);                          // back to front for a 2D side or top view
+}
+```
+
+Pixi: draw the placements back to front (they come sorted by y), with the flip and tint.
+
+```ts
+for (const p of scatter(KIT, { w, h, path, clear: 30, landmarks: [tower] }, 42)) {
+  const s = new Sprite({ texture: kitTextures[p.piece], anchor: { x: 0.5, y: 1 } });
+  s.position.set(p.x, p.y); s.scale.set(p.flip ? -p.scale : p.scale, p.scale); s.tint = p.tint;
+  world.addChild(s);
+}
+```
+
+Measured in the lab: about 280 pieces on an 844×390 view drew in 3 draw calls (Pixi batches
+sprites and graphics that share a texture), JS work under 0.5 ms a frame. Put every kit piece on
+one atlas (`npx @funpixel/tools optimize pack-atlas`) so they keep batching.
+
+Three: one `InstancedMesh` per piece kind, so a few hundred props cost a few draw calls.
+
+```ts
+/** Scatter on the XZ plane (area units = metres), one draw call per piece kind. */
+export function dressGround(scene: THREE.Scene, size: number, path: Array<[number, number]>, landmark: THREE.Vector3, seed: number) {
+  const toArea = (x: number, z: number): [number, number] => [x + size / 2, z + size / 2];
+  const placed = scatter(KIT, { w: size, h: size, path: path.map(([x, z]) => toArea(x, z)), clear: 1.6, landmarks: [{ x: landmark.x + size / 2, y: landmark.z + size / 2, r: 4 }] }, seed, 4000);
+  const m = new THREE.Matrix4(), q = new THREE.Quaternion();
+  for (const piece of KIT) {
+    const mine = placed.filter((p) => p.piece === piece.name);
+    const [geo, mat] = GEO[piece.name];
+    const mesh = new THREE.InstancedMesh(geo, mat, mine.length);
+    mesh.name = 'kit-' + piece.name;
+    mine.forEach((p, i) => {
+      q.setFromAxisAngle(new THREE.Vector3(0, 1, 0), (p.x * 13.7) % (Math.PI * 2));
+      mesh.setMatrixAt(i, m.compose(new THREE.Vector3(p.x - size / 2, 0, p.y - size / 2), q, new THREE.Vector3(p.scale, p.scale, p.scale)));
+      mesh.setColorAt(i, new THREE.Color(p.tint));
+    });
+    scene.add(mesh);
+  }
+  return placed.length;
+}
+```
+
+Measured in the lab: 621 instances across the kit and trees, 16 draw calls, 17,640 triangles.
+
+## Landmarks and the route
+
+- One landmark tall enough to see from most of the map, with its own silhouette and light (a
+  tower, a great tree). Place it first; the scatter leaves room around it.
+- The route is the brightest, least cluttered band. In 2D a path texture or a stroked spline
+  (`Graphics.stroke({ width, cap: 'round', join: 'round' })`); in 3D a lighter ground strip.
+- Two or three districts, each with one colour and one material: the orchard is warm and round,
+  the quarry grey and angular. A player should know where they are from one frame.
+- Depth in 2D: two or three parallax layers (far hills move at 0.2–0.4 of the camera, near props
+  at 1.0), the far ones lighter and bluer; in 3D, fog in the sky's colour (skill `funpixel-art`).
+
+## Contact and life
+
+- A soft shadow under anything standing on the ground (a blurred dark ellipse in 2D; a blob
+  texture or a shadow map in 3D) glues it to the place.
+- Small ambient motion sells a place: grass sway (a sine on rotation with a per-piece phase),
+  drifting particles (pollen, fireflies, dust), water shimmer, smoke. Keep it low contrast so the
+  player and threats stay the clearest things on screen. Respect `prefers-reduced-motion`.
+- Wildlife that reacts (birds that lift off as you pass) is cheap and reads as a living world.
+
+## A minimap, cheaply
+
+A round mask over a small render of the world's layout: in 2D, draw the route and landmarks into a
+`Graphics` in a corner at 1/20 scale with the player as an arrow; in 3D, a top-down orthographic
+camera into a small `WebGLRenderTarget` shown on a plane, or a 2D canvas that draws the same
+positions. Keep it off the thumbs' zones (skill `funpixel-mobile-ui`).
+
+## Checking a place
+
+- Capture the play view at phone size and ask: can I see the landmark, the route and the goal?
+- `npx @funpixel/tools look --read` for whether the player and threats stand out from the ground.
+- `npx @funpixel/tools profile --views playing` before and after dressing; the draw calls and
+  object count say what the kit costs.

package/templates/common/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "skillListingBudgetFraction": 0.03
+}

package/templates/common/.harnessignore

@@ -0,0 +1,28 @@
+# Private files that must never ship with the game (funtools stage / publish). Rules are rooted with
+# a leading slash so each one matches only the path it names. Everything not matched is uploaded, and
+# the platform installs dependencies and builds the upload, so package.json, the lockfile,
+# tsconfig.json, vite.config.ts, index.html, funpixel.json, src/ and public/ stay.
+/AGENTS.md
+/CLAUDE.md
+/.agents/
+/.claude/
+/.funtools/
+/verify.json
+/design/
+/dist-playable/
+# Local tooling and generation inputs: scripts, tools, the asset manifest, raw provider originals and
+# the costs ledger (assets gen). What ships is the processed copy under public/.
+/scripts/
+/tools/
+/assets/
+/reference/
+# Notes, tests and test config: README.md stays, every other note is the team's.
+*.md
+!/README.md
+/test/
+/vitest.config.ts
+# Secrets, if one is ever dropped here.
+.env
+.env.*
+# src/splash-funpixel/ (the "Made with Funpixel" card) ships only when funpixel.json says
+# "splash": "funpixel"; funtools applies that itself, whatever this file says.

package/templates/common/AGENTS.md

@@ -0,0 +1,135 @@
+<!-- funpixel-gdk:brief -->
+# Game development with the Funpixel toolkit
+
+Start with the creator's goal. An asset repair stays an asset repair; a new game gets the path
+below. The creator and host agent own scope, style and workflow. Recipes here and in the
+skills are defaults, not boundaries: keep locked choices, explore open ones, find another way when
+no recipe fits.
+
+Assets work in any engine; build, preview and publish target browser games (Pixi 8 or Three.js,
+Preact, the SDK).
+
+## The shelf
+
+Skills hold what great looks like, with numbers; each loads in one call (Skill tool or `SKILL.md`):
+- starting, planning or reshaping a game, the GDD: `funpixel-gdd`; code, the SDK, multiplayer:
+  `funpixel-game-spine`; rules, levels, balance, depth and replay: `funpixel-game-logic`
+- the look, 2D art, light and effects: `funpixel-art`; 3D models, the bench and levels: `funpixel-3d`
+- feel and payoffs: `funpixel-game-feel`; a place with a story: `funpixel-world-and-story`; sound
+  and music: `funpixel-audio`; phone HUD, touch: `funpixel-mobile-ui`
+- proving it plays, the panel and blind player: `funpixel-verify`; dev log: `funpixel-feedback`;
+  publish, trailer, store shots, playable ads: `funpixel-publish`; a store: `funpixel-store`;
+  Unity: `funpixel-unity-game`
+
+The session start names the few this game needs. Local hooks advise (`funpixel.json` `gdk.gate`:
+`"block"` or `"off"`; `FUNPIXEL_GDK_GATE`); no setting changes publishing's own checks.
+
+## The path
+
+For a complete game, the path our best games took: you are the person's copilot, not an autopilot.
+A plan made with them is a contract, target frames show what done looks like, and every round
+closes the gap between the two. The locked plan
+is the job; how you build it is yours. Why, tool and signal per step:
+`funpixel-gdd/references/the-path.md`.
+
+Start each session from `npx @funpixel/tools flow`: the owner's notes first (they outrank an
+agent's claim), then the one next step. After every step, a short status in the chat with a
+capture of the build: the owner watches and steers.
+
+1. **Brief back, one screen, one question.** A short brief (title, kind, verb, world, length,
+   failing, look, platforms), your calls in a line each, then one question: is it right? Decide
+   the rest and say it: their ask outranks a standing request.
+2. **First look, then a first playable.** The key art and the hero's reference sheet, shown in
+   the chat for the owner to steer. Then a playable built from them with real assets (the hero,
+   the place in the key art's light, title, music, the verb's sounds), sized by the game (short:
+   about 1 minute; long: 3 to 5), judged against the key art. They play: potential, or not.
+3. **Plan the whole game around it** (skill `funpixel-gdd`): the genre's best, pillars, story,
+   levels and maps, fun and wow moments, screens and HUD, a numbers contract with named tests,
+   the rest of the first look (target frames), the asset list with its price.
+4. **Lock** (`flow ask`): the owner's "looks good, let's build" (price shown; not a cap). It
+   stands until they say otherwise; a new direction is a new GDD version locked again; a
+   departure goes in "Where the build moved", with why.
+5. **Sim first** (`sim`, `test`), then **build with the assets as they land** in `public/assets/`,
+   each judged under the game's light. The slice: one verb, a win and a loss, progress, keys and
+   touch, `check` exits 0.
+6. **Each round, the look-dev loop**: capture at the target moments, set each beside its target
+   (`compare --target`), fix the biggest difference, then play it (`play`, `playtest`). Repeat
+   until each beat is close. Matching the targets is the job, never a style choice: only the owner
+   relaxes a target.
+7. **Extend** chapter by chapter (each to its targets, then the owner's yes); fold a new
+   request into the pillars first.
+8. **Finish when the person plays it and says yes.** Green means stop. When verify passes and the
+   goal is met, stop editing. No renames, restyles or polish nobody asked for; they break what
+   worked and hide which change did what.
+Hand back what plays now (keys and touch), what is out on purpose, the next two or three steps,
+and every stand-in. File the dev log with `report_feedback` before you finish.
+
+## A funtools scaffold
+
+A folder `funtools init` made is a finished frame around a demo round (`init --bare`: none). Replace
+the demo with your game (`rules.ts`, `session.ts`, `game.ts`, `feel.ts`, `hud.tsx`, `screens.tsx`,
+`look.json`, a check per mechanic in `funpixel.json`); keep the frame, host integration and checks.
+
+## Silent failures
+
+- dt is in seconds and clamped: `dt = Math.min(dt, 0.1)`. A background tab hands you one huge
+  frame and everything tunnels. Pixi: `ticker.deltaMS / 1000`, never `deltaTime`.
+- Resize with `setupGameResize((w, h) => …)` from `@funpixel/sdk`, never a `resize` listener or
+  `resizeTo: window`: those miss iframe resizes. It fires once at the call, so create the renderer
+  first.
+- Audio: one `new AudioEngine({ iosPatch: false })` from `@funpixel/sdk/audio`; connect every
+  source to `audio.master` and call `audio.unlock()` from the first click, pointerup or keydown.
+  `iosPatch: false` lets the iPhone ringer switch mute the game; pass `true`
+  only when sound is the game (rhythm, music). Keep an existing game's choice.
+- Pointer handlers use `addEventListener`. Assigning `onpointerdown = …` twice kills the first
+  control without an error.
+- Three: GLBs need `DRACOLoader`, `KTX2Loader` and the meshopt decoder with same-origin decoder
+  paths, an environment map (they render flat grey without one), and `mixer.update(dt)` every frame.
+- Pixi: every display object gets a `.label`; `window.__PIXI_APP__ = app` after `app.init()`.
+- Room codes, share codes and seeds carry `data-funpixel-selectable` (else they cannot be copied).
+- `@funpixel/sdk` is pinned exactly (`"0.7.0"`). Import the root only for `setupGameResize`;
+  everything else from a subpath. Multiplayer is `Room.autoJoin(getGameKey(), …)`, never a raw
+  WebSocket (skill `funpixel-game-spine`).
+- A performance fix changes how a frame is made (pooling, atlases, instancing), never what it shows.
+- Assets arrive as expiring URLs: `npx @funpixel/tools job <id> --wait --out public/assets/<file>`;
+  never base64 in code.
+- Hosts may refuse chains, loops, `sed -i`, heredocs and outside paths: use the edit tool, one
+  command per call (`doctor --host`); keep captures in `design/shots/`.
+
+## Red flags: thoughts before broken games
+
+- "It compiles, so it works." Verify it; a runtime crash builds green.
+- "I'll cast it to make the error go away." Look the name up (skill `funpixel-game-spine`); `as any` and
+  `?.` compile code that does nothing.
+- "The class exists, so the feature exists." Trace it from boot, the loop or an input handler, and
+  give it a check.
+- "The shapes will do for now." They won't: make the planned asset. A shape is only a fallback
+  until it lands; name every one still in the game at hand-back.
+- "The Play button surely works." Press it (skill `funpixel-verify`, front door).
+
+## Spending
+
+Scope, time and spend are the creator's: never shrink an agreed game to save them. The locked plan
+is the go-ahead for its assets: make them (pass `confirm_cost`); before each paid call say the
+route and its cost in one line. No budget unless the owner sets a cap. Out of credits is a pause: say so;
+they top up and you go on. Long jobs return an id: collect
+with `get_job`. Never end a session (headless `-p` too) while a background job, subagent
+or recording runs: a session that ends does not come back. Do the work in the session.
+
+## Hosted and local
+
+The Funpixel MCP does the paid and hosted work; `funtools` runs locally and free. When the MCP is
+not connected, use the local column and say which steps you could not do.
+
+| Job | MCP tool | Local (`npx @funpixel/tools …`) |
+|---|---|---|
+| New game | `create_game`, only with no local files (`init` mints the id) | `init` |
+| Build and preview | `build`, `preview` | `npm run build`, `dev` |
+| Check it plays | `probe`, `screenshot` (`click` presses Play) | `verify`, `verify --watch`, `verify --front-door` |
+| Look at a state | `capture_view`, `audit_screens`, `inspect_scene` | `capture` (`--all`: every view), `audit-screens`, `scene` |
+| Critic panel, blind player | `review`, `play` | `playtest`: `critic`, `player` agent seats |
+| Images, sprites, sheets | `generate_image`, `generate_sprite`, `edit_image`, `generate_spritesheet` | `gen image\|sprite\|edit\|sheet`, `assets gen` |
+| Sound and music | `generate_sound`, `generate_music` | `gen sound`, `gen music` |
+| 3D models | `generate_3d_model`, then the bench tools (skill `funpixel-3d`) | `gen model3d`, `model …` (`--local` on your Blender) |
+| Publish | `publish_game` | `publish` (needs `funtools login`) |
+| Dev log and feedback | `report_feedback` | lines in `.funtools/devlog.jsonl` |

package/templates/common/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/common/assets/assets.example.json

@@ -0,0 +1,9 @@
+{
+  "about": "Optional. Copy to assets/assets.json to make assets from text with `npx @funpixel/tools assets gen` (dry run first: --dry-run). Each subject is composed with assets/style.json. The names match the files src/assets.ts looks for, so a made sprite or sound is used with no code. Hand-made or one-off assets never need to be listed here.",
+  "items": [
+    { "name": "player", "kind": "sprite", "subject": "the player character, whole, facing right", "role": { "h": 96 }, "draws": 2 },
+    { "name": "gem", "kind": "sprite", "subject": "a small cut gem that glints", "role": { "h": 48 } },
+    { "name": "pickup", "kind": "sound", "subject": "a bright short chime for collecting a gem", "params": { "duration_seconds": 0.5 } },
+    { "name": "theme", "kind": "music", "subject": "a light looping theme for the game's world", "params": { "instrumental": true } }
+  ]
+}

package/templates/common/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>{{name}}</title>
+    <link rel="stylesheet" href="./src/styles.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>

package/templates/common/src/art/files.mjs

@@ -0,0 +1,27 @@
+// node src/art/files.mjs — the first step of `npm run build` (Node, not the game: nothing imports it).
+//
+// Writes src/art/files.json: every file under public/assets/ ("sfx/pickup.mp3"), so the built game asks only
+// for the asset files that are there (src/assets.ts findAsset) and a fresh game, drawing its placeholders,
+// logs no 404 per missing sound or sprite. The dev server is asked directly, so a file dropped in while it
+// runs is used at once. Written only when the list changes. No dependencies. It lives in src/ so an export
+// or an upload keeps it with the build that runs it.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const dir = join(root, 'public', 'assets');
+const out = join(root, 'src', 'art', 'files.json');
+
+const walk = (d) => readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+  e.name.startsWith('.') ? [] : e.isDirectory() ? walk(join(d, e.name)) : e.isFile() ? [relative(dir, join(d, e.name)).split(sep).join('/')] : []);
+
+const files = existsSync(dir) ? walk(dir).sort() : [];
+const text = JSON.stringify({ about: 'Every file under public/assets/, written by src/art/files.mjs at the start of npm run build: the built game asks only for these.', files }, null, 2) + '\n';
+let was = '';
+try { was = readFileSync(out, 'utf8'); } catch { /* the first build */ }
+if (was !== text) {
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, text);
+}

package/templates/common/src/assets.ts

@@ -0,0 +1,62 @@
+// Conventional asset paths: drop a file at one of these and the game uses it
+// on the next load, with no code; until then it draws a placeholder.
+//
+//   public/assets/sprites/<name>.png   the player and gem (Pixi)
+//   public/assets/models/<name>.glb    the player and gem (Three)
+//   public/assets/sfx/<name>.mp3       pickup, bump, win, lose (the juice table, feel.ts)
+//   public/assets/music/<name>.mp3     theme, looped from the first input
+//
+// A built game asks only for the files src/art/files.json lists (npm run build writes it).
+//
+// e.g. npx @funpixel/tools gen sprite "a round blue slime" --out public/assets/sprites/player.png
+//
+// A picture is drawn into a BOX, never at its pixel size: a re-made sprite of any size lands where the old one
+// stood. `funtools assets process` records each item's box in src/art/assets.json (declared in the manifest, or
+// its size the first time it lands, kept on every re-make); pass it to fitInBox.
+
+export type Kind = 'sprites' | 'models' | 'sfx' | 'music';
+const EXT: Record<Kind, string> = { sprites: 'png', models: 'glb', sfx: 'mp3', music: 'mp3' };
+const TYPE: Record<Kind, RegExp> = { sprites: /^image\//, models: /gltf|octet-stream/, sfx: /^audio\//, music: /^audio\// };
+
+export const assetPath = (kind: Kind, name: string) => `assets/${kind}/${name}.${EXT[kind]}`;
+
+// What is under public/assets/ as the last `npm run build` saw it (src/art/files.json, written by its first
+// step, src/art/files.mjs): a built game asks only for files that are there, so a fresh game drawing its
+// placeholders logs no 404 per missing sound or sprite. The dev server is asked directly (it answers a missing
+// file with the page, never a 404), so a file dropped in while it runs is used at once. No list (an older game,
+// or run outside Vite): every file is asked for, as before. A file added after the last build: build again.
+const LISTED = (() => {
+  try {
+    // (ts-ignore: Vite's own types name glob and env; the kit's Node tests type-check this file without them.)
+    // @ts-ignore
+    const got = Object.values(import.meta.glob('./art/files.json', { eager: true, import: 'default' }))[0] as { files?: unknown } | undefined;
+    // @ts-ignore
+    const dev: boolean = !!import.meta.env?.DEV;
+    return !dev && Array.isArray(got?.files) ? new Set(got.files as string[]) : null;
+  } catch {
+    return null;
+  }
+})();
+
+/**
+ * The file's URL when a real one is there, else null. Checked by type too: a
+ * dev server answers a missing path with the page itself.
+ */
+export async function findAsset(kind: Kind, name: string): Promise<string | null> {
+  const url = assetPath(kind, name);
+  if (LISTED && !LISTED.has(url.slice('assets/'.length))) return null;
+  try {
+    const r = await fetch(url, { method: 'HEAD' });
+    return r.ok && TYPE[kind].test(r.headers.get('content-type') ?? '') ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The size a picture is drawn at and the point of it on its position (fractions: [0.5, 1] = feet, [0.5, 0.5] = middle). */
+export interface Box { w: number; h: number; anchor: [number, number] }
+
+/** A picture of pw x ph pixels fitted inside its box (contain): the scale to draw it at, and its anchor. */
+export function fitInBox(pw: number, ph: number, box: Box): { scale: number; anchor: [number, number] } {
+  return { scale: Math.min(box.w / Math.max(pw, 1), box.h / Math.max(ph, 1)), anchor: box.anchor };
+}

package/templates/common/src/beat.ts

@@ -0,0 +1,50 @@
+// The music's beat map in the game (written by `npx @funpixel/tools beats`, beside each track as
+// <track>.beats.json): where the beat is now, how far an input landed from the nearest one, when
+// the next bar starts. Engine-free; feed it the music's own clock (sound.ts `musicTime()`), never
+// the frame clock, so a dropped frame or a paused tab cannot drift the game off the music.
+
+export interface BeatMap {
+  bpm: number;
+  period: number;
+  offset: number;
+  detected: boolean;
+  meter: number;
+  downbeat: number;
+  seconds: number;
+  beats?: number[];
+  confidence?: number;
+}
+
+/** The map for a track URL (its .beats.json), or null when there is none or the music has no clear pulse. */
+export async function loadBeats(trackUrl: string): Promise<BeatMap | null> {
+  try {
+    const r = await fetch(trackUrl.replace(/\.[a-z0-9]+(\?.*)?$/i, '.beats.json'));
+    if (!r.ok) return null;
+    const m = (await r.json()) as BeatMap;
+    return m && m.detected && m.period > 0 ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where the music is: the beat (0-based from the first), the bar, the beat inside the bar, and the phase 0–1 to the next. */
+export function beatAt(m: BeatMap, t: number): { beat: number; bar: number; inBar: number; phase: number; downbeat: boolean } {
+  const x = (t - m.offset) / m.period;
+  const beat = Math.floor(x);
+  const fromDown = beat - m.downbeat;
+  const inBar = ((fromDown % m.meter) + m.meter) % m.meter;
+  return { beat, bar: Math.floor(fromDown / m.meter), inBar, phase: x - beat, downbeat: inBar === 0 };
+}
+
+/** The nearest beat to `t` and how far off it was, in ms (negative = early): judge a press with it. */
+export function nearestBeat(m: BeatMap, t: number): { beat: number; offMs: number } {
+  const beat = Math.round((t - m.offset) / m.period);
+  return { beat, offMs: Math.round((t - (m.offset + beat * m.period)) * 1000) };
+}
+
+/** Seconds of music time when the next beat (or with `bar`, the next downbeat) begins after `t`. */
+export function nextBeat(m: BeatMap, t: number, bar = false): number {
+  let k = Math.floor((t - m.offset) / m.period) + 1;
+  if (bar) while (((k - m.downbeat) % m.meter + m.meter) % m.meter !== 0) k++;
+  return m.offset + k * m.period;
+}

package/templates/common/src/characters.ts

@@ -0,0 +1,54 @@
+// Library characters: animated before your game asks. `npx @funpixel/tools character list`
+// shows the shelf; `character get <id>` copies one into public/assets/characters/<id>/
+// (free): a 2D sheet (sheet.json + sheet.png, the feet as every frame's anchor) or a 3D
+// model.glb whose clips play by name. Every 2D character has the same cycle names, and
+// every 3D one the same clip names on the same rig, so this code plays any of them;
+// `character restyle` gives one your look and keeps every motion.
+//
+// This file is engine-free: which clip a moving actor plays, and how fast. Like living.ts,
+// the numbers are data with tuned ranges — a value outside one throws, naming the field.
+// The loaders are the engine's: character.ts beside game.ts.
+
+/** Every library character's clip names. 2D: idle walk run jump attack hit death blink (a
+ *  flyer has no jump; its walk and run are flying). 3D: those less blink, plus wave nod hop
+ *  flinch celebrate. A one-shot (attack, hit, death, jump, emotes) plays once and holds. */
+export const LOOPS = new Set(['idle', 'walk', 'run']);
+
+/** Each dial, its tuned range and default. */
+export const GAIT_RANGES = {
+  walkAt: [0.05, 0.5, 0.12],   // share of top speed where idle turns into walk
+  runAt: [0.35, 0.95, 0.6],    // share of top speed where walk turns into run
+  fade: [0.05, 0.4, 0.2],      // seconds a 3D clip cross-fades into the next
+  // How far a clip's rate may follow the body's speed. Outside it a walk reads as a
+  // moonwalk (too slow) or a scramble (too fast): switch clip instead.
+  minRate: [0.5, 1, 0.75], maxRate: [1, 2, 1.4],
+} as const;
+export type Gait = { -readonly [K in keyof typeof GAIT_RANGES]: number };
+
+/** A full gait from a partial one; throws `characters: <actor>.<field> …` out of range. */
+export function gaitSpec(actor: string, spec: Partial<Gait> = {}): Gait {
+  const out = {} as Gait;
+  for (const [k, [lo, hi, def]] of Object.entries(GAIT_RANGES) as Array<[keyof Gait, readonly [number, number, number]]>) {
+    const v = spec[k] ?? def;
+    if (!Number.isFinite(v) || v < lo || v > hi) throw new Error(`characters: ${actor}.${k} is ${v}; it must be ${lo}–${hi}`);
+    out[k] = v;
+  }
+  if (out.runAt <= out.walkAt) throw new Error(`characters: ${actor}.runAt must be above walkAt`);
+  return out;
+}
+
+/** The clip a body moving at `share` of its top speed (0…1) plays. */
+export function gaitClip(g: Gait, share: number): 'idle' | 'walk' | 'run' {
+  const s = Math.abs(share);
+  return s < g.walkAt ? 'idle' : s < g.runAt ? 'walk' : 'run';
+}
+
+/**
+ * The rate to play a travel clip at so the feet keep up with the body. 3D: `speed` and the
+ * clip's `ground_speed_mps` (character.json / get_character's answer) in metres a second.
+ * 2D: pixels a second against the distance one cycle covers. Held inside the gait's range.
+ */
+export function clipRate(g: Gait, speed: number, clipSpeed: number): number {
+  if (!(clipSpeed > 0)) return 1;
+  return Math.min(g.maxRate, Math.max(g.minRate, Math.abs(speed) / clipSpeed));
+}

package/templates/common/src/expose.ts

@@ -0,0 +1,63 @@
+// The hooks verify, journeys and feel read (HOOKS.md; fpx-hooks.ts is the contract). winRound and
+// loseRound end a round through the rules (a sharp player, the round run out), so checks reach
+// both endings. The state's feel fields are optional, each for one measure `funtools feel` takes
+// (skill funpixel-game-feel, references/measure.md): hero (a jump's height and arc, a dash, the
+// invulnerable window), threats (tell to strike), control and dead (the death beat and the time
+// back to control), actors (each node's look in each of its states), t (the game's clock in seconds,
+// so a window is timed in game time and a stutter cannot lengthen it), juice (what the renderer applies
+// now: feel times each key event's answer — a score, a hit, a win — and checks a win answers bigger
+// than a point). Drop what your game lacks.
+
+import { BODY, hopHeight, phase, safe, type Run } from './rules';
+import { go, store } from './store';
+import { exposeHooks } from './fpx-hooks';
+import { juiceLevel } from './juice';
+import { selfTests } from './selftests';
+import { enterSplash, hasSplash } from './splash';
+import type { Verb } from './input';
+
+interface Round {
+  session: { run: Run; beat: number; stepFor: number; t: number };
+  inControl: () => boolean;
+  press: (verb: Verb) => void;
+  advance: (dt: number) => void;
+  playToEnd: () => void;
+  endBeat: () => void;
+}
+
+/** The hero's state in the game's words: what it is doing, as its look should show. */
+export function heroState(s: Round['session']): 'dead' | 'hop' | 'step' | 'idle' {
+  return s.beat > 0 ? 'dead' : s.run.hop >= 0 ? 'hop' : s.stepFor > 0 ? 'step' : 'idle';
+}
+
+export function exposeRound(r: Round): void {
+  const { session: s } = r;
+  const lose = () => { if (store.screen !== 'playing') go('playing'); r.advance(s.run.timeLeft); };
+  exposeHooks({
+    state: () => ({
+      t: s.t, screen: store.screen, x: s.run.x, score: s.run.score, seed: s.run.seed, wins: store.wins, losses: store.losses,
+      control: r.inControl(), dead: s.beat > 0, juice: juiceLevel(),
+      // In slots, with the body's height, so a hop reads back in body heights.
+      hero: { x: s.run.x, y: hopHeight(s.run), body: BODY, unit: 'slot', grounded: s.run.hop < 0, state: heroState(s), invulnerable: safe(s.run) },
+      threats: [{ id: 'spike', phase: phase(s.run) }],
+      // Keyed by the scene node's label: game.ts labels them 'player' and 'hazard'.
+      actors: { player: heroState(s), hazard: phase(s.run) },
+    }),
+    verbs: {
+      moveLeft: () => r.press('left'), moveRight: () => r.press('right'), hop: () => r.press('hop'), pause: () => r.press('pause'),
+      winRound: () => { if (store.screen !== 'playing') go('playing'); r.playToEnd(); },
+      loseRound: lose,
+    },
+    views: {
+      title: { enter: () => go('title') }, ...(hasSplash ? { splash: { enter: enterSplash } } : {}),
+      howto: { enter: () => go('howto') },
+      settings: { enter: () => go('settings') },
+      playing: { motion: true, enter: () => go('playing') },
+      paused: { enter: () => { go('playing'); go('paused'); } },
+      won: { enter: () => { go('playing'); r.playToEnd(); } },
+      lost: { enter: () => { lose(); r.endBeat(); } },
+    },
+    keys: ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'Escape', 'KeyM'],
+    selftests: selfTests,
+  });
+}