@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/src/world.ts

@@ -0,0 +1,91 @@
+// The world `npx @funpixel/tools world forge` writes (design/world/world.json and its room files),
+// read with no engine: rooms, tiles, heights, props, places and each room's light. Nothing imports
+// it until the game has a world; drawing it is the game's own (yours to change or drop). In Vite:
+//
+//   import { loadWorld, room, eachTile, heightAt, place, lightOf } from './world';
+//   const world = loadWorld(import.meta.glob('../design/world/**/*.json', { eager: true, import: 'default' }));
+//   const here = room(world!, world!.critical_path[0]);
+//   // Pixi: eachTile(here, (x, y, kind) => { if (kind === 'solid') wall(x * TILE, y * TILE); });
+//   // Three: for (const i of here.instances) spawn(i.kind, i.pos, i.rot, i.scale);
+//   //        ground vertex y = heightAt(here, x, z, world!.cell); start at place(here, 'arrival'); fog from lightOf(world!, here)
+//
+// A name that is not there degrades with a warning naming the ones that are: a typo never throws in
+// the load path, and never quietly drops the player at (0, 0).
+
+export type TileKind = 'solid' | 'floor' | 'hazard' | 'arrival' | 'goal' | 'pickup' | 'door';
+const TILES: Record<string, TileKind> = { '#': 'solid', '.': 'floor', '^': 'hazard', S: 'arrival', G: 'goal', '*': 'pickup', D: 'door' };
+
+export interface WorldInstance { id: string; kind: string; role: string; pos: number[]; rot: number; scale: number; solid: boolean }
+export interface WorldDoor { id: string; to: string; at: [number, number]; kind: string }
+export interface WorldPlace { name: string; at: number[]; label?: string }
+export interface Light { sky?: string; fog?: { color: string; near: number; far: number }; light?: { color: string; intensity: number }; ambient?: number }
+export interface WorldRoom {
+  id: string; chapter: string; role: string; shape: string; size: [number, number];
+  tiles?: string[]; heights?: number[][]; doors: WorldDoor[]; places: WorldPlace[]; instances: WorldInstance[]; atmosphere: Light;
+}
+export interface World {
+  kind: '2d' | '3d'; seed: number; cell: number; atmosphere: Light; movement?: { step: number };
+  chapters: Array<{ id: string; name: string; rooms: string[]; landmark?: string }>;
+  rooms: WorldRoom[]; edges: Array<{ id: string; from: string; to: string; kind: string }>; critical_path: string[];
+}
+
+/** The world from a map of path → parsed JSON (Vite's import.meta.glob, or your own fetches); null when there is none. */
+export function loadWorld(files: Record<string, unknown>): World | null {
+  const find = (rel: string) => Object.entries(files).find(([k]) => k === rel || k.endsWith(`/${rel}`))?.[1] as any;
+  const w = find('world/world.json') ?? find('world.json');
+  if (!w || !Array.isArray(w.rooms)) return null;
+  const rooms = w.rooms.map((r: any) => ({
+    ...r,
+    tiles: r.tiles ?? (r.file ? find(`world/${r.file}`)?.tiles : undefined),
+    heights: typeof r.heights === 'string' ? find(`world/${r.heights}`)?.heights : r.heights,
+  }));
+  return { ...w, rooms };
+}
+
+const warnMissing = (what: string, name: string, known: string[]) => console.warn(`[world] no ${what} "${name}"; there is ${known.join(', ') || 'none'}`);
+
+/** A room by id; a missing id warns and gives the first room. */
+export function room(world: World, id: string): WorldRoom {
+  const r = world.rooms.find((x) => x.id === id);
+  if (!r) warnMissing('room', id, world.rooms.map((x) => x.id));
+  return r ?? world.rooms[0];
+}
+
+/** What stands at a tile (2D); outside the room is solid. */
+export function tileAt(r: WorldRoom, x: number, y: number): TileKind {
+  return TILES[r.tiles?.[y]?.[x] ?? '#'] ?? 'floor';
+}
+
+export function eachTile(r: WorldRoom, fn: (x: number, y: number, kind: TileKind) => void): void {
+  r.tiles?.forEach((row, y) => { for (let x = 0; x < row.length; x++) fn(x, y, TILES[row[x]] ?? 'floor'); });
+}
+
+/** Ground height (3D) at world x, z in metres, smooth between cell centres. */
+export function heightAt(r: WorldRoom, x: number, z: number, cell = 2): number {
+  const h = r.heights;
+  if (!h?.length) return 0;
+  const cx = Math.max(0, Math.min(h[0].length - 1, x / cell - 0.5)), cz = Math.max(0, Math.min(h.length - 1, z / cell - 0.5));
+  const x0 = Math.floor(cx), z0 = Math.floor(cz), x1 = Math.min(x0 + 1, h[0].length - 1), z1 = Math.min(z0 + 1, h.length - 1);
+  const tx = cx - x0, tz = cz - z0;
+  const a = h[z0][x0] + (h[z0][x1] - h[z0][x0]) * tx, b = h[z1][x0] + (h[z1][x1] - h[z1][x0]) * tx;
+  return a + (b - a) * tz;
+}
+
+/** A named spot (arrival, goal, reward, vista, landmark); a missing one warns and gives the arrival. */
+export function place(r: WorldRoom, name: string): number[] {
+  const p = r.places.find((x) => x.name === name);
+  if (!p) warnMissing(`place in ${r.id}`, name, r.places.map((x) => x.name));
+  return (p ?? r.places.find((x) => x.name === 'arrival') ?? r.places[0])?.at ?? [0, 0, 0];
+}
+
+/** The room's light: the world's default with the room's own changes over it. */
+export function lightOf(world: World, r: WorldRoom): Light {
+  const a = world.atmosphere, o = r.atmosphere ?? {};
+  return { ...a, ...o, ...(a.fog || o.fog ? { fog: { ...a.fog!, ...o.fog } } : {}), ...(a.light || o.light ? { light: { ...a.light!, ...o.light } } : {}) };
+}
+
+/** Where a door leads, or null when it leads nowhere. */
+export function through(world: World, r: WorldRoom, doorId: string): WorldRoom | null {
+  const d = r.doors.find((x) => x.id === doorId);
+  return d ? world.rooms.find((x) => x.id === d.to) ?? null : null;
+}

package/templates/common/test/feel.json

@@ -0,0 +1,36 @@
+{
+  "name": "feel",
+  "viewport": "desktop",
+  "seed": 1,
+  "steps": [
+    "until screen=title 3000",
+    "press Space",
+    "until screen=playing 3000",
+    "press ArrowRight 2",
+    "wait 400",
+    "press ArrowUp",
+    "wait 700",
+    "press ArrowUp 12",
+    "wait 600",
+    "until control=false 9000",
+    "until screen=lost 3000",
+    "retry press Space",
+    "wait 500"
+  ],
+  "expect": {
+    "hop height": "0.8 body",
+    "time in the air": "0.5 s",
+    "apex hang": "0.16 s",
+    "invulnerable window": "0.35 s",
+    "hop cooldown": "0.1 s",
+    "spike tell": "0.6 s",
+    "death beat": "0.5 s",
+    "restart": "under 2 s",
+    "coyote time (late hop)": "0.1 s",
+    "hop buffer (early press)": "0.1 s"
+  },
+  "sweeps": {
+    "coyote": { "steps": ["until screen=title 3000", "press Space", "until screen=playing 3000"], "anchor": "threats.0.phase=strike", "press": "ArrowUp", "success": "hero.grounded=false", "within": 200 },
+    "buffer": { "steps": ["until screen=title 3000", "press Space", "until screen=playing 3000", "wait 300"], "cue": "ArrowUp", "anchor": "hero.grounded=true", "press": "ArrowUp", "success": "hero.grounded=false", "within": 300 }
+  }
+}

package/templates/common/test/platform.test.ts

@@ -0,0 +1,42 @@
+// The page boots where storage is blocked, and progress survives a reload: outcomes a player meets in a
+// sandboxed frame, private browsing or a full disk (one of the owner's games' platform test, in small).
+// save.ts is engine-free so this runs under Node beside the rules.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+const g = globalThis as unknown as Record<string, unknown>;
+/** A storage whose every access throws, as a sandboxed frame or blocked site data gives. */
+const denyStorage = () => Object.defineProperty(globalThis, 'localStorage', { configurable: true, get() { throw new Error('SecurityError: access denied'); } });
+/** A working in-memory storage, shared by every load of save.ts in this test (a "reload"). */
+function fakeStorage(): Map<string, string> {
+  const m = new Map<string, string>();
+  const s = { getItem: (k: string) => m.get(k) ?? null, setItem: (k: string, v: string) => { m.set(k, String(v)); }, removeItem: (k: string) => { m.delete(k); } };
+  Object.defineProperty(globalThis, 'localStorage', { configurable: true, value: s, writable: true });
+  return m;
+}
+
+test('the page boots where storage throws: progress starts at its defaults and saving never throws', async () => {
+  denyStorage();
+  const { progress, storage } = await import('../src/save.ts?denied');
+  assert.equal(progress.data.best, 0);
+  progress.update({ best: 9 });
+  assert.equal(progress.flush().ok, true, 'the session keeps its copy');
+  storage.setItem('k', 'v');
+  assert.equal(storage.getItem('k'), 'v');
+  delete g.localStorage;
+});
+
+test('progress survives a reload, and a corrupt save falls back to the defaults', async () => {
+  const m = fakeStorage();
+  const first = await import('../src/save.ts?first');
+  first.progress.update({ best: 42, reached: 3 });
+  first.progress.flush();
+  const again = await import('../src/save.ts?reload');
+  assert.equal(again.progress.data.best, 42);
+  assert.equal(again.progress.data.reached, 3);
+  m.set('progress', '{not json');
+  const broken = await import('../src/save.ts?corrupt');
+  assert.equal(broken.progress.data.best, 0);
+  delete g.localStorage;
+});

package/templates/common/test/probes.ts

@@ -0,0 +1,72 @@
+// The rules played by five policies over 100 seeds each (src/probe-kit.ts), printed as JSON for
+// `npx @funpixel/tools sim`, which reads it: standing still must not win, a naive player should not
+// do as well as a sharp one unless the design says so, doing what the game teaches should pay.
+// Rewrite the policies with your rules: each sees only what a player could see. Run: node test/probes.ts
+// This file and src/rules.ts are one piece: when you rewrite the rules, rewrite this in the same
+// step (it plays the demo until then), and set the seconds per run past the length the game means
+// to have — sim reads play length from the sharp bot (15 min and an ending, the design doc's
+// play-length line; name the ending in ended(run)). With levels, add level(run) to the game below: sim splits clear rate, loss
+// rate and time per level for each player and warns on a flat level, a wall and a run nothing loses.
+//
+// Optional, when the game has them: a staged moment (the seed and time that give the best REAL
+// signature moment; the moment view's enter() replays it with replayTo) and a music timeline
+// (the game's own musicMix(run) sampled while a bot plays; `follow` names the layer and the
+// on-screen number it should rise with).
+
+import { bestStep, GOAL, hop, inReach, move, newRun, phase, SLOTS, TELL_SECONDS, tick, type Run } from '../src/rules.ts';
+import { cohort, stageMoment, type Ev, type Policy, type ProbeGame } from '../src/probe-kit.ts';
+import { humanRate } from '../src/probe-human.ts';
+
+/** A step (±1), a hop (2) or nothing (0). A run a spike ended is kept in `spiked`. */
+type Press = 1 | -1 | 0 | 2;
+const spiked = new WeakSet<Run>();
+const game: ProbeGame<Run, Press> = {
+  newRun, dt: 0.05,
+  step(run, p) {
+    const ev: Ev[] = [];
+    if (p === 2) { if (hop(run)) ev.push({ type: 'hop' }); }
+    else if (p) { const m = move(run, p); if (m.picked !== null) ev.push({ type: 'pickup' }); if (m.bumped) ev.push({ type: 'bump' }); }
+    if (tick(run, 0.05) === 'lost' && run.timeLeft > 0) { spiked.add(run); ev.push({ type: 'spiked' }); }
+    return ev;
+  },
+  outcome: (run) => (run.score >= GOAL ? 'won' : run.timeLeft <= 0 || spiked.has(run) ? 'lost' : null),
+  progress: (run) => run.score,
+  firstSuccess: (run) => run.score >= 5,
+  broken: (run) => (Number.isFinite(run.x) ? null : 'position is not a number'),
+};
+
+/** Straight at the nearest gem that is there, cracks or not: the naive line. */
+const toGem = (run: Run): Press => {
+  let best = Infinity;
+  for (let i = 0; i < SLOTS; i++) if (run.gems[i] === 0 && i !== run.x && Math.abs(i - run.x) < Math.abs(best)) best = i - run.x;
+  return best === Infinity ? 0 : best > 0 ? 1 : -1;
+};
+/** The crack is under the player and the strike is near: a hop now clears it. */
+const hopTime = (run: Run) => phase(run) === 'tell' && inReach(run) && run.spike!.t >= TELL_SECONDS - 0.2;
+
+/** Press `choose(run)` once every `react` seconds, as a hand would; `reflex` presses between (a hop). */
+const every = (react: number, choose: (run: Run, rnd: () => number) => Press, reflex?: (run: Run) => Press) => (seed: number) => {
+  let wait = 0, s = seed;
+  const rnd = () => ((s = (s * 1103515245 + 12345) >>> 0) / 4294967296);
+  return (run: Run): Press => reflex?.(run) || ((wait -= 0.05) > 0 ? 0 : ((wait = react), choose(run, rnd)));
+};
+
+const policies: Policy<Run, Press>[] = [
+  { name: 'idle', role: 'idle', says: 'never presses', make: () => () => 0 },
+  { name: 'naive', role: 'naive', says: 'steers straight at the nearest gem, a press every 0.35 s, cracks or not', make: every(0.35, toGem) },
+  { name: 'taught', role: 'taught', says: 'what the how-to says: walk, turn at the wall, hop the spike late in its glow, a press every 0.18 s', make: every(0.18, (run) => (run.x <= 0 ? 1 : run.x >= SLOTS - 1 ? -1 : run.facing), (run) => (hopTime(run) ? 2 : 0)) },
+  { name: 'skilled', role: 'skilled', says: 'nearest gem, stepping off every crack, a press every 0.12 s', make: every(0.12, bestStep) },
+  { name: 'novice', role: 'novice', says: 'nearest gem every 0.6 s, one press in five the wrong way; hops when it sees the crack under it', make: every(0.6, (run, rnd) => (phase(run) === 'tell' && inReach(run) ? 2 : rnd() < 0.2 ? (-toGem(run) as Press) : toGem(run))) },
+];
+
+const best = policies.find((p) => p.role === 'skilled')!;
+// The sharp line again at a thumb's rate (12 decisions a second, 200 ms to react): a level only the bot clears is a wall.
+policies.push(humanRate({ ...best, make: () => (run) => bestStep(run) }, game.dt, { rest: 0 }));
+
+const seeds = Array.from({ length: 100 }, (_, i) => i + 1);
+console.log(JSON.stringify({
+  probes: 1,
+  cohorts: policies.map((p) => cohort(game, p, seeds, 60)),
+  moments: [{ name: 'streak', says: 'gems picked in 2 s', candidates: stageMoment(game, best, { seeds: seeds.slice(0, 20), at: [2, 4, 6], window: 2, score: (e) => (e.type === 'pickup' ? 1 : 0) }) }],
+  timelines: [],
+}));

package/templates/common/test/rules.test.ts

@@ -0,0 +1,88 @@
+// The rules under Node: `npm test` (Node 22.18+ runs TypeScript as is). Kept
+// outside src/, so the platform's build never type-checks it. Name a
+// test after the rule it proves, and grow this file with the rules: the team's
+// best games carry hundreds.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { botRound, GOAL, HOP_BUFFER, HOP_COOLDOWN, HOP_LATE, HOP_SAFE, HOP_SECONDS, hop, move, newRun, phase, ROUND_SECONDS, SLOTS, SPIKE_FIRST, TELL_SECONDS, tick } from '../src/rules.ts';
+
+test('a press moves half a slot, and the wall stops it', () => {
+  const r = newRun(1);
+  move(r, 1);
+  assert.equal(r.x, Math.floor(SLOTS / 2) + 0.5);
+  for (let i = 0; i < SLOTS * 2; i++) move(r, 1);
+  assert.equal(move(r, 1).bumped, true);
+});
+
+test('a gem scores once, then comes back after a moment', () => {
+  const r = newRun(1);
+  move(r, 1);
+  assert.equal(move(r, 1).picked, Math.floor(SLOTS / 2) + 1);
+  move(r, -1);
+  assert.equal(move(r, 1).picked, null, 'not back yet');
+  tick(r, 1);
+  move(r, -1);
+  assert.notEqual(move(r, 1).picked, null, 'back after a second');
+});
+
+test(`collecting ${GOAL} wins, dodging the spikes; the clock running out loses`, () => {
+  assert.equal(botRound(newRun(5), 0.25), 'won');
+  const r = newRun(5);
+  r.nextSpike = Infinity;
+  assert.equal(tick(r, ROUND_SECONDS), 'lost');
+  assert.equal(r.timeLeft, 0);
+});
+
+test(`a spike's crack glows ${TELL_SECONDS} s before it strikes; standing on it loses, a slot away is clear`, () => {
+  const r = newRun(2);
+  assert.equal(tick(r, SPIKE_FIRST), null);
+  assert.equal(phase(r), 'tell');
+  assert.equal(tick(r, TELL_SECONDS - 0.1), null, 'the warning is not the hit');
+  assert.equal(tick(r, 0.1 + HOP_LATE), 'lost');
+  const away = newRun(2);
+  tick(away, SPIKE_FIRST);
+  move(away, 1); move(away, 1);
+  assert.equal(tick(away, 1), null);
+});
+
+test(`the hop: ${HOP_SECONDS} s in the air, safe for ${HOP_SAFE} s, ready again ${HOP_COOLDOWN} s after landing`, () => {
+  const r = newRun(3);
+  tick(r, SPIKE_FIRST + TELL_SECONDS - 0.15);
+  assert.ok(hop(r), 'a hop late in the tell');
+  assert.equal(hop(r), false, 'not twice in the air');
+  assert.equal(tick(r, HOP_SECONDS), null, 'it clears the strike');
+  assert.equal(hop(r), false, 'resting: the press is kept');
+  tick(r, HOP_COOLDOWN);
+  assert.ok(r.hop >= 0, 'and takes off the moment the hop is ready');
+  const early = newRun(3);
+  tick(early, SPIKE_FIRST);
+  hop(early);
+  assert.equal(tick(early, TELL_SECONDS + 0.1), 'lost', 'a hop taken at the first glow lands in the strike: the committed landing is open');
+});
+
+test(`forgiveness: a press ${HOP_BUFFER} s before landing hops when ready; a spike hits ${HOP_LATE} s after it stands`, () => {
+  const r = newRun(3);
+  hop(r);
+  tick(r, HOP_SECONDS - HOP_BUFFER);
+  assert.equal(hop(r), false, 'still in the air');
+  tick(r, HOP_BUFFER + HOP_COOLDOWN);
+  assert.ok(r.hop >= 0, 'the early press took off when the hop was ready');
+  const early = newRun(3);
+  hop(early);
+  tick(early, HOP_SECONDS - HOP_BUFFER - 0.05);
+  hop(early);
+  tick(early, 0.1 + HOP_COOLDOWN);
+  assert.equal(early.hop, -1, 'a press before the buffer is dropped');
+  const late = newRun(3);
+  assert.equal(tick(late, SPIKE_FIRST + TELL_SECONDS + HOP_LATE - 0.05), null, 'the spike stands, not yet a hit');
+  assert.ok(hop(late));
+  assert.equal(tick(late, 0.5), null, 'a hop that late still clears it');
+  assert.equal(tick(newRun(3), SPIKE_FIRST + TELL_SECONDS + HOP_LATE), 'lost', 'later than that is a hit');
+});
+
+test('the same seed replays the same round', () => {
+  const a = newRun(9), b = newRun(9);
+  for (let i = 0; i < 12; i++) { move(a, 1); move(b, 1); tick(a, 0.7); tick(b, 0.7); }
+  assert.deepEqual(a, b);
+});

package/templates/common/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "noEmit": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}

package/templates/common/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+export default defineConfig({
+  esbuild: { jsx: 'automatic', jsxImportSource: 'preact' },
+  server: { host: true, port: 5173, cors: true },
+  build: { target: 'esnext', outDir: 'dist' },
+});

package/templates/pixi/src/character.ts

@@ -0,0 +1,63 @@
+// A library character (or any generate_spritesheet sheet) as one AnimatedSprite that
+// plays its cycles by name. `npx @funpixel/tools character get fox-2d` puts the files in
+// public/assets/characters/fox-2d/; then:
+//
+//   const fox = await loadSheetCharacter('assets/characters/fox-2d');
+//   stage.addChild(fox.sprite);
+//   fox.play(gaitClip(gait, speedShare));   // idle / walk / run by speed (characters.ts)
+//   fox.play('attack', () => fox.play('idle'));  // a one-shot, then back
+//   fox.face(dx);                            // flip to the heading
+//
+// Every frame's anchor is the feet, so swapping cycles never jumps. blink is a one-frame
+// cycle: `fox.blink()` on living.ts's schedule shows it for ~100 ms.
+
+import * as PIXI from 'pixi.js';
+
+interface CycleMeta { fps: number; loop: boolean }
+
+export interface SheetCharacter {
+  sprite: PIXI.AnimatedSprite;
+  /** The cycles this sheet has: every library character has idle, walk, run, hit, death, blink. */
+  cycles: string[];
+  play(name: string, onDone?: () => void): void;
+  face(dx: number): void;
+  blink(ms?: number): void;
+}
+
+export async function loadSheetCharacter(dir: string): Promise<SheetCharacter> {
+  const sheet = await PIXI.Assets.load<PIXI.Spritesheet>(`${dir}/sheet.json`);
+  const meta = ((sheet.data.meta as unknown as { funpixel?: { animations?: Record<string, CycleMeta> } }).funpixel?.animations) ?? {};
+  const cycles = Object.keys(sheet.animations);
+  const first = cycles.includes('idle') ? 'idle' : cycles[0];
+  const sprite = new PIXI.AnimatedSprite(sheet.animations[first]);
+  sprite.anchor.copyFrom(sheet.animations[first][0].defaultAnchor ?? { x: 0.5, y: 1 });
+  let current = '';
+  const play = (name: string, onDone?: () => void) => {
+    const frames = sheet.animations[name];
+    if (!frames || name === current) return;
+    current = name;
+    const m = meta[name] ?? { fps: 10, loop: name === 'idle' || name === 'walk' || name === 'run' };
+    sprite.textures = frames;
+    sprite.animationSpeed = m.fps / 60;
+    sprite.loop = m.loop;
+    sprite.onComplete = onDone ? () => { current = ''; onDone(); } : undefined;
+    sprite.gotoAndPlay(0);
+  };
+  play(first);
+  return {
+    sprite,
+    cycles,
+    play,
+    face(dx) {
+      if (dx !== 0) sprite.scale.x = Math.abs(sprite.scale.x) * Math.sign(dx);
+    },
+    blink(ms = 100) {
+      const eyes = sheet.animations.blink?.[0];
+      if (!eyes || current !== 'idle') return;
+      const was = sprite.currentFrame;
+      sprite.stop();
+      sprite.texture = eyes;
+      setTimeout(() => { if (current === 'idle') sprite.gotoAndPlay(was); }, ms);
+    },
+  };
+}

package/templates/pixi/src/game.ts

@@ -0,0 +1,99 @@
+import * as PIXI from 'pixi.js';
+import { setupGameResize } from '@funpixel/sdk';
+import { phase, SLOTS } from './rules';
+import { session, startSession, update } from './session';
+import { juice, shakeOffset, squashScale } from './juice';
+import { findAsset, fitInBox, type Box } from './assets';
+import { Living, ROLE } from './living';
+import { heroPose } from './pose';
+import { heroState } from './expose';
+import { gradeFromLook } from './look';
+
+// The renderer: it draws session.run, and decides nothing. Everything is drawn at a 40 px slot and scaled to the screen's; one slot = `unit` pixels.
+const DESIGN = 40;
+
+/** A sprite fitted into its box (a slot by default; the box, not the picture, sets the size), or the placeholder. */
+async function art(name: string, placeholder: () => PIXI.Graphics, fitTo: Box = { w: DESIGN * 0.9, h: DESIGN * 0.9, anchor: [0.5, 0.5] }): Promise<() => PIXI.Container> {
+  const url = await findAsset('sprites', name);
+  const texture = url ? await PIXI.Assets.load<PIXI.Texture>(url).catch(() => null) : null;
+  return () => {
+    const box = new PIXI.Container();
+    if (!texture) { box.addChild(placeholder()); return box; }
+    const s = new PIXI.Sprite(texture);
+    const fit = fitInBox(texture.width, texture.height, fitTo);
+    s.anchor.set(fit.anchor[0], fit.anchor[1]); s.scale.set(fit.scale);
+    box.addChild(s);
+    return box;
+  };
+}
+
+export async function startGame(host: HTMLElement): Promise<void> {
+  const app = new PIXI.Application();
+  // Every colour here is the scaffold's placeholder palette (styles.css): the design's replaces it.
+  await app.init({ width: innerWidth, height: innerHeight, background: '#101018', antialias: true });
+  host.appendChild(app.canvas);
+  gradeFromLook(host); // look.json "light": saturation, contrast, tint, vignette, one CSS layer below the HUD (grade.ts)
+  (window as any).__PIXI_APP__ = app;
+
+  let unit = DESIGN, left = 0, floor = 0;
+  // Resize once, through the SDK: the window, the host's viewport messages and an iframe that changes size all arrive here (it fires once now).
+  setupGameResize((w, h) => {
+    app.renderer.resize(w, h);
+    unit = Math.min((w * 0.84) / (SLOTS - 1), h * 0.12);
+    left = w / 2 - (unit * (SLOTS - 1)) / 2;
+    floor = h * 0.62;
+  });
+
+  const world = new PIXI.Container();
+  app.stage.addChild(world);
+  const ground = new PIXI.Graphics();
+  const makeGem = await art('gem', () => new PIXI.Graphics().poly([0, -12, 10, 0, 0, 12, -10, 0]).fill(0xf6ad55));
+  const makePlayer = await art('player', () => new PIXI.Graphics().roundRect(-16, -16, 32, 32, 8).fill(0x4fd1c5));
+  const gems = Array.from({ length: SLOTS }, makeGem), player = makePlayer();
+  // The hit flash: one filter on the one body that flashes (filters on the few, never the stage).
+  const flash = new PIXI.ColorMatrixFilter();
+  player.filters = [flash];
+  for (const [i, g] of gems.entries()) g.label = `gem-${i}`;
+  // The spike: a crack that glows through the tell, a blade through the strike: one look per phase.
+  const crack = new PIXI.Graphics({ label: 'crack' }).ellipse(0, 0, 16, 4).fill(0xff5a5f);
+  const blade = new PIXI.Graphics({ label: 'blade' }).poly([-9, 0, 0, -40, 9, 0]).fill(0xe2e8f0);
+  const hazard = new PIXI.Container({ label: 'hazard', children: [crack, blade] });
+  const sparks = new PIXI.Graphics();
+  world.label = 'world'; ground.label = 'ground'; sparks.label = 'sparks'; player.label = 'player';
+  world.addChild(ground, ...gems, hazard, player, sparks);
+
+  // The demo's actors move gently between events (the player breathes and leans, each gem
+  // pulses); keep this only where your actors' roles want it.
+  const life = new Living('player', ROLE.hero), gemLife = gems.map((_, i) => new Living(`gem-${i}`, ROLE.pickup));
+  let lastX = session.run.x;
+  startSession(host);
+  app.ticker.add((ticker) => {
+    const dt = Math.min(ticker.deltaMS / 1000, 0.1);
+    update(dt);
+    const run = session.run, k = unit / DESIGN, t = performance.now() / 1000;
+    const pose = life.update(dt, (run.x - lastX) / dt / 8), hp = heroPose(heroState(session), run);
+    lastX = run.x;
+    ground.clear().rect(left - unit / 2, floor + unit * 0.5, unit * SLOTS, 4).fill(0x2a2a3a);
+    gems.forEach((g, i) => {
+      g.visible = run.gems[i] === 0;
+      const glint = gemLife[i].update(dt);
+      g.position.set(left + i * unit, floor + Math.sin(t * 3 + i) * unit * 0.08);
+      g.scale.set(k * glint.scaleX, k * glint.scaleY);
+    });
+    const ph = phase(run);
+    [hazard.visible, crack.visible, blade.visible] = [ph !== 'rest', ph === 'tell', ph === 'strike'];
+    if (run.spike) hazard.position.set(left + run.spike.slot * unit, floor + unit * 0.5);
+    hazard.scale.set(k * (ph === 'tell' ? 1 + 0.2 * Math.sin(t * 24) : 1));
+    const sq = squashScale();
+    player.position.set(left + run.x * unit, floor + (pose.offsetY - hp.lift) * unit);
+    player.scale.set(k * sq.x * pose.scaleX * hp.sx * (pose.flip ? -1 : 1), k * sq.y * pose.scaleY * hp.sy);
+    player.rotation = pose.rotation + hp.turn;
+    flash.enabled = juice.flash > 0;
+    if (flash.enabled) flash.brightness(1 + juice.flash * 3, false);
+    host.style.setProperty('--vignette', juice.vignette.toFixed(3)); // the edge vignette (styles.css .stage::after), never a full-screen flash
+    sparks.clear();
+    for (const p of juice.particles) sparks.circle(left + p.x * unit, floor - p.y * unit, unit * 0.1 * p.life).fill({ color: 0xf6ad55, alpha: p.life });
+    const off = shakeOffset();
+    world.position.set(off.x * unit, off.y * unit);
+  });
+}

package/templates/pixi/src/world-hud.ts

@@ -0,0 +1,16 @@
+// Pixi's side of the world-space HUD (markers.ts): where a display object is
+// on screen. Pin with `pin(enemy, bar)`, then each frame call
+// `drawMarkers(projector(app), app.canvas)`. `lift` raises the marker above
+// the object's origin in screen pixels (a bar over a head).
+
+import type { Application, Container } from 'pixi.js';
+import type { Project } from './markers';
+
+export function projector(app: Application, lift = 24): Project<Container> {
+  return (target) => {
+    const p = target.getGlobalPosition();
+    const w = app.screen.width || 1, h = app.screen.height || 1;
+    // A 2D game has no depth: distance 0 keeps markers full size.
+    return { x: (p.x / w) * 2 - 1, y: 1 - ((p.y - lift) / h) * 2, front: true, distance: 0 };
+  };
+}

package/templates/spec/common/src/chapters.ts

@@ -0,0 +1,97 @@
+// chapters.ts — the game's chapters and rooms as data (design/spec/rooms.json), engine-free so the probes and the
+// tests play them: the data checked as it loads, a room entered (its numbers laid over the defaults, tune.ts), played
+// wave by wave (a checkpoint before each: a lost round retries its wave), left by its exit, and the map of where a
+// player got to. The rooms are the content list: one is added in rooms.json with a par (the seconds a good run takes),
+// an exit (the next room's id, or "end") and what it teaches, never in code. `funtools rooms` plays every room with bots; `funtools spec lint` checks the file.
+
+import data from '../design/spec/rooms.json' with { type: 'json' };
+import { override } from './tune';
+
+export interface Room {
+  id: string; name: string;
+  /** Seconds a good first run takes: the pars add up to the game's length (`funtools rooms` measures them). */
+  par: number;
+  /** The room this one opens onto, or END. */
+  exit: string;
+  teaches?: string; beat?: string;
+  /** This room's numbers, laid over tunables.json's defaults while it is played. */
+  tune?: Record<string, number | boolean | string>;
+  /** Rounds won in a row to clear the room (default 1); each starts at a checkpoint, so a loss retries only its wave. */
+  waves?: number;
+  /** The vertical slice: the first room, built and passed before any other room is opened. */
+  slice?: boolean;
+}
+export interface Chapter { id: string; name: string; rooms: Room[] }
+export const END = 'end';
+
+/** The file checked: every room has an id, a name, a par and an exit to a room that exists (or END). */
+export function check(raw: unknown): Chapter[] {
+  const chapters = (raw as { chapters?: unknown } | null)?.chapters;
+  if (!Array.isArray(chapters) || !chapters.length) throw new Error('chapters: design/spec/rooms.json has no chapters');
+  const out: Chapter[] = [], ids = new Set<string>();
+  for (const c of chapters as Array<Record<string, unknown>>) {
+    const rooms = Array.isArray(c.rooms) ? (c.rooms as Array<Record<string, unknown>>) : [];
+    if (!rooms.length) throw new Error(`chapters: chapter ${String(c.id)} has no rooms`);
+    for (const r of rooms) {
+      const at = `room ${String(r.id ?? '?')}`;
+      if (typeof r.id !== 'string' || !r.id) throw new Error('chapters: a room has no id');
+      if (ids.has(r.id)) throw new Error(`chapters: ${at} is listed twice`);
+      if (!(typeof r.par === 'number' && r.par > 0)) throw new Error(`chapters: ${at} has no par (seconds a good run takes)`);
+      if (typeof r.exit !== 'string' || !r.exit) throw new Error(`chapters: ${at} has no exit (the next room's id, or "${END}")`);
+      ids.add(r.id);
+    }
+    out.push({ id: String(c.id), name: String(c.name ?? c.id), rooms: rooms as unknown as Room[] });
+  }
+  for (const r of out.flatMap((c) => c.rooms)) if (r.exit !== END && !ids.has(r.exit)) throw new Error(`chapters: room ${r.id} exits to "${r.exit}", which is not a room`);
+  return out;
+}
+
+export const CHAPTERS = check(data);
+export const ROOMS: Room[] = CHAPTERS.flatMap((c) => c.rooms);
+export function roomOf(id: string): Room {
+  const r = ROOMS.find((x) => x.id === id);
+  if (!r) throw new Error(`chapters: no room "${id}"`);
+  return r;
+}
+export const chapterOf = (id: string): Chapter => CHAPTERS.find((c) => c.rooms.some((r) => r.id === id))!;
+/** The room this one exits to, or null after the last. */
+export const nextRoom = (id: string): Room | null => { const r = roomOf(id); return r.exit === END ? null : roomOf(r.exit); };
+/** The game's length on paper: every room's par, in seconds. */
+export const parTotal = (): number => ROOMS.reduce((s, r) => s + r.par, 0);
+
+/** Enter a room: its numbers go over the defaults, every other number back to its default. */
+export function enter(id: string): Room {
+  const r = roomOf(id);
+  override(r.tune ?? {}, `room ${id}`);
+  return r;
+}
+
+export const wavesOf = (r: Room): number => Math.max(1, Math.floor(r.waves ?? 1));
+
+/** Where a player got to: the room and wave to resume at (the checkpoint), the rooms done, the best seconds in each. */
+export type Progress = { at: string; wave: number; done: string[]; best: Record<string, number> };
+export const fresh = (): Progress => ({ at: ROOMS[0].id, wave: 0, done: [], best: {} });
+
+/** A room cleared in `seconds`: done, its best kept, the checkpoint moved through its exit (it stays at the last room). */
+export function cleared(p: Progress, id: string, seconds: number): Progress {
+  const best = { ...p.best };
+  if (seconds > 0 && !(best[id] <= seconds)) best[id] = Math.round(seconds * 10) / 10;
+  const done = p.done.includes(id) ? p.done : [...p.done, id];
+  return { at: nextRoom(id)?.id ?? id, wave: 0, done, best };
+}
+
+/** A round won in room `id`: the next wave's checkpoint, or the room cleared after its last wave (`seconds` in the room). */
+export function waveWon(p: Progress, id: string, seconds: number): { progress: Progress; cleared: boolean } {
+  const wave = (p.at === id ? p.wave : 0) + 1;
+  if (wave < wavesOf(roomOf(id))) return { progress: { ...p, at: id, wave }, cleared: false };
+  return { progress: cleared(p, id, seconds), cleared: true };
+}
+
+export type RoomState = 'done' | 'here' | 'locked';
+/** The map of progress: each chapter's rooms as done (replayable), here (the checkpoint) or locked, with best and par. */
+export function progressMap(p: Progress): Array<{ id: string; name: string; rooms: Array<{ id: string; name: string; par: number; best: number | null; waves: number; wave: number; state: RoomState }> }> {
+  return CHAPTERS.map((c) => ({
+    id: c.id, name: c.name,
+    rooms: c.rooms.map((r) => ({ id: r.id, name: r.name, par: r.par, best: p.best[r.id] ?? null, waves: wavesOf(r), wave: r.id === p.at ? p.wave : 0, state: r.id === p.at ? 'here' : p.done.includes(r.id) ? 'done' : 'locked' })),
+  }));
+}