@funpixel/tools 0.0.0-stage → 0.1.0

package/templates/spec/common/test/rooms.ts

@@ -0,0 +1,53 @@
+// Every room of design/spec/rooms.json played in order by the probe players over 5 seeds (src/probe-rooms.ts over
+// the kit's cohort()), printed as JSON for `npx @funpixel/tools rooms`: does a careful player at a human rate clear
+// every room, how long does each take against its par, and where do the naive and the novice players fall back? A
+// lost round retries the room from its door. This file and test/probes.ts play the same round: when you rewrite the
+// rules, rewrite the round below in the same step. Run: node --import ./test/resolve.mjs test/rooms.ts
+
+import { bestStep, GOAL, hop, inReach, move, newRun, phase, tick, type Run } from '../src/rules.ts';
+import { cohort, type Ev, type Policy, type ProbeGame } from '../src/probe-kit.ts';
+import { humanRate } from '../src/probe-human.ts';
+import { campaign, inCampaign } from '../src/probe-rooms.ts';
+import { parTotal, ROOMS } from '../src/chapters.ts';
+
+type Press = 1 | -1 | 0 | 2;
+const spiked = new WeakSet<Run>();
+const round: 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 (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,
+  broken: (run) => (Number.isFinite(run.x) ? null : 'position is not a number'),
+};
+
+/** Straight at the nearest gem that is there, cracks or not. */
+const toGem = (run: Run): Press => {
+  let best = Infinity;
+  for (let i = 0; i < run.gems.length; 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;
+};
+const every = (react: number, choose: (run: Run, rnd: () => number) => Press) => (seed: number) => {
+  let wait = 0, s = seed;
+  const rnd = () => ((s = (s * 1103515245 + 12345) >>> 0) / 4294967296);
+  return (run: Run): Press => ((wait -= 0.05) > 0 ? 0 : ((wait = react), choose(run, rnd)));
+};
+const sharp: Policy<Run, Press> = { name: 'skilled', role: 'skilled', says: 'nearest gem, stepping off every crack', make: () => (run) => bestStep(run) };
+const players: Policy<Run, Press>[] = [
+  { 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: '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))) },
+  sharp,
+  // The careful player the pars are for: the sharp line at a thumb's rate (12 decisions a second, 200 ms to react).
+  humanRate(sharp, round.dt, { rest: 0 }),
+];
+
+const game = campaign(round), seeds = [1, 2, 3, 4, 5], limit = Math.max(600, parTotal() * 4);
+console.log(JSON.stringify({
+  probes: 1,
+  rooms: ROOMS.map((r) => ({ id: r.id, name: r.name, par: r.par })),
+  cohorts: players.map((p) => cohort(game, inCampaign(p), seeds, limit)),
+}));

package/templates/spec/three-world/test/rooms.ts

@@ -0,0 +1,54 @@
+// Every room of design/spec/rooms.json played in order by the probe players over 5 seeds (src/probe-rooms.ts over
+// the kit's cohort()), printed as JSON for `npx @funpixel/tools rooms`: does a careful player at a human rate clear
+// every room, how long does each take against its par, and where do the naive and the novice players fall back? A
+// lost round retries the room from its door. This file and test/probes.ts play the same round: when you rewrite the
+// rules, rewrite the round below in the same step. Run: node --import ./test/resolve.mjs test/rooms.ts
+
+import { GOAL, newRun, tick, type Input, type Run } from '../src/rules.ts';
+import { bestInput } from '../src/bot.ts';
+import { cohort, type Ev, type Policy, type ProbeGame } from '../src/probe-kit.ts';
+import { humanRate } from '../src/probe-human.ts';
+import { campaign, inCampaign } from '../src/probe-rooms.ts';
+import { parTotal, ROOMS } from '../src/chapters.ts';
+
+const burned = new WeakSet<Run>(), DT = 1 / 30;
+const round: ProbeGame<Run, Input> = {
+  newRun, dt: DT,
+  step(run, input) {
+    const { events, outcome } = tick(run, input, DT);
+    const ev: Ev[] = events.map((e) => ({ type: e.type }));
+    if (outcome === 'lost' && run.timeLeft > 0) { burned.add(run); ev.push({ type: 'burned' }); }
+    return ev;
+  },
+  outcome: (run) => (run.score >= GOAL ? 'won' : run.timeLeft <= 0 || burned.has(run) ? 'lost' : null),
+  progress: (run) => run.score,
+  broken: (run) => (![run.x, run.y, run.z].every(Number.isFinite) ? 'position is not a number' : run.y < -0.01 ? 'under the ground' : null),
+};
+
+/** Straight at the nearest pickup on the ground, never jumping, flares or not. */
+const naiveLine = (run: Run): Input => {
+  const p = run.pickups.filter((q) => !q.taken).sort((a, b) => Math.hypot(a.x - run.x, a.z - run.z) - Math.hypot(b.x - run.x, b.z - run.z))[0];
+  if (!p) return { x: 0, z: 0 };
+  const d = Math.hypot(p.x - run.x, p.z - run.z) || 1;
+  return { x: (p.x - run.x) / d, z: (p.z - run.z) / d };
+};
+const every = (react: number, choose: (run: Run, rnd: () => number) => Input) => (seed: number) => {
+  let wait = 0, last: Input = { x: 0, z: 0 }, s = seed;
+  const rnd = () => ((s = (s * 1103515245 + 12345) >>> 0) / 4294967296);
+  return (run: Run): Input => { if ((wait -= DT) > 0) return { ...last, jump: false, dash: false }; wait = react; return (last = choose(run, rnd)); };
+};
+const sharp: Policy<Run, Input> = { name: 'skilled', role: 'skilled', says: 'nearest pickup by route, out of every ring, jumps for the high ones', make: () => (run) => bestInput(run) };
+const players: Policy<Run, Input>[] = [
+  { name: 'naive', role: 'naive', says: 'runs straight at the nearest pickup every 0.3 s, never jumps, flares or not', make: every(0.3, naiveLine) },
+  { name: 'novice', role: 'novice', says: 'nearest pickup every 0.5 s, one decision in five aimed wrong', make: every(0.5, (run, rnd) => { const i = bestInput(run); return rnd() < 0.2 ? { x: -i.z, z: i.x } : i; }) },
+  sharp,
+  // The careful player the pars are for: the sharp line at a thumb's rate (12 decisions a second, 200 ms to react).
+  humanRate(sharp, round.dt, { rest: { x: 0, z: 0 }, hold: true }),
+];
+
+const game = campaign(round), seeds = [1, 2, 3, 4, 5], limit = Math.max(600, parTotal() * 4);
+console.log(JSON.stringify({
+  probes: 1,
+  rooms: ROOMS.map((r) => ({ id: r.id, name: r.name, par: r.par })),
+  cohorts: players.map((p) => cohort(game, inCampaign(p), seeds, limit)),
+}));

package/templates/three/src/character.ts

@@ -0,0 +1,65 @@
+// A library character (or any rigged GLB with named clips) that plays its clips by name.
+// `npx @funpixel/tools character get robot-3d` puts model.glb and clips.json in
+// public/assets/characters/robot-3d/; then:
+//
+//   const bot = await loadModelCharacter('assets/characters/robot-3d');
+//   scene.add(bot.root);
+//   bot.play(gaitClip(gait, speedShare));          // idle / walk / run by speed (characters.ts)
+//   bot.rate(clipRate(gait, speed, bot.groundSpeed('walk')));  // feet keep up, no skating
+//   bot.play('attack', () => bot.play('idle'));    // a one-shot, then back
+//   bot.update(dt);                                 // every frame
+//
+// Clips are in place: move `root` yourself. Every 3D library character has the same clip
+// names on the same humanoid rig: idle walk run jump attack hit death wave nod hop flinch
+// celebrate.
+
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { gaitSpec, LOOPS, type Gait } from './characters';
+
+interface ClipFacts { name: string; loop?: boolean; ground_speed_mps?: number }
+
+export interface ModelCharacter {
+  root: THREE.Object3D;
+  clips: string[];
+  play(name: string, onDone?: () => void): void;
+  /** Speed the playing clip up or down (clipRate keeps it inside the gait's range). */
+  rate(r: number): void;
+  /** A travel clip's ground speed in m/s from clips.json, or 0 when it has none. */
+  groundSpeed(name: string): number;
+  update(dt: number): void;
+}
+
+export async function loadModelCharacter(dir: string, gait: Gait = gaitSpec('character')): Promise<ModelCharacter> {
+  const gltf = await new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).loadAsync(`${dir}/model.glb`);
+  const facts: ClipFacts[] = await fetch(`${dir}/clips.json`).then((r) => (r.ok ? r.json() : { clips: [] })).then((j) => j.clips ?? []).catch(() => []);
+  const mixer = new THREE.AnimationMixer(gltf.scene);
+  const actions = new Map<string, THREE.AnimationAction>(gltf.animations.map((c) => [c.name, mixer.clipAction(c)] as const));
+  let current: THREE.AnimationAction | null = null;
+  let done: (() => void) | undefined;
+  mixer.addEventListener('finished', (e) => {
+    if (e.action === current && done) { const f = done; done = undefined; f(); }
+  });
+  const play = (name: string, onDone?: () => void) => {
+    const next = actions.get(name);
+    if (!next || next === current) return;
+    const loop = facts.find((f) => f.name === name)?.loop ?? LOOPS.has(name);
+    next.reset();
+    next.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
+    next.clampWhenFinished = !loop;
+    next.play();
+    if (current) current.crossFadeTo(next, gait.fade, false);
+    current = next;
+    done = onDone;
+  };
+  play(actions.has('idle') ? 'idle' : gltf.animations[0]?.name ?? '');
+  return {
+    root: gltf.scene,
+    clips: [...actions.keys()],
+    play,
+    rate(r) { if (current) current.timeScale = r; },
+    groundSpeed(name) { return facts.find((f) => f.name === name)?.ground_speed_mps ?? 0; },
+    update(dt) { mixer.update(dt); },
+  };
+}

package/templates/three/src/game.ts

@@ -0,0 +1,99 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.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 } from './assets';
+import { Living, ROLE } from './living';
+import { heroPose } from './pose';
+import { heroState } from './expose';
+
+// The renderer: it draws session.run, and decides nothing. One slot = one
+// world unit; the camera is fixed, so moving right moves right on screen.
+const FOV = 50;
+const slotX = (x: number) => x - (SLOTS - 1) / 2;
+
+/** One unit tall, feet at 0, from the conventional .glb — or the placeholder while there is none. */
+async function art(name: string, placeholder: () => THREE.Object3D): Promise<() => THREE.Object3D> {
+  const url = await findAsset('models', name);
+  const model = url ? await new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).loadAsync(url).catch((e) => {
+    // A Draco-compressed model also needs DRACOLoader and its decoders in public/ (skill funpixel-3d).
+    console.warn(`${url} did not load; drawing the placeholder`, e);
+    return null;
+  }) : null;
+  return () => {
+    if (!model) return new THREE.Group().add(placeholder());
+    const m = model.scene.clone(true);
+    const size = new THREE.Box3().setFromObject(m).getSize(new THREE.Vector3());
+    m.scale.setScalar(1 / Math.max(size.x, size.y, size.z, 1e-6));
+    return new THREE.Group().add(m);
+  };
+}
+
+export async function startGame(host: HTMLElement): Promise<void> {
+  const renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5));
+  host.appendChild(renderer.domElement);
+  const scene = new THREE.Scene();
+  // Every colour here is the scaffold's placeholder palette (styles.css): the design's replaces it.
+  scene.background = new THREE.Color('#101018');
+  // GLBs render flat grey without an environment map.
+  scene.environment = new THREE.PMREMGenerator(renderer).fromScene(new RoomEnvironment()).texture;
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 1.5));
+  const camera = new THREE.PerspectiveCamera(FOV, innerWidth / innerHeight, 0.1, 100);
+  scene.add(new THREE.Mesh(new THREE.BoxGeometry(SLOTS + 1, 0.2, 3).translate(0, -0.1, 0), new THREE.MeshStandardMaterial({ color: 0x2a2a3a })));
+
+  const makeGem = await art('gem', () => new THREE.Mesh(new THREE.OctahedronGeometry(0.28), new THREE.MeshStandardMaterial({ color: 0xf6ad55, emissive: 0x7a4a10 })));
+  const makePlayer = await art('player', () => new THREE.Mesh(new THREE.BoxGeometry(0.8, 0.8, 0.8).translate(0, 0.4, 0), new THREE.MeshStandardMaterial({ color: 0x4fd1c5 })));
+  const gems = Array.from({ length: SLOTS }, makeGem), player = makePlayer();
+  player.name = 'player';
+  // The spike: a crack that glows through the tell, a blade through the strike: one look per phase.
+  const crack = new THREE.Mesh(new THREE.CircleGeometry(0.35, 20).rotateX(-Math.PI / 2), new THREE.MeshBasicMaterial({ color: 0xff5a5f }));
+  const blade = new THREE.Mesh(new THREE.ConeGeometry(0.18, 1, 12).translate(0, 0.5, 0), new THREE.MeshStandardMaterial({ color: 0xe2e8f0 }));
+  const hazard = new THREE.Group().add(crack, blade);
+  [hazard.name, crack.name, blade.name] = ['hazard', 'crack', 'blade'];
+  const sparks = new THREE.Points(new THREE.BufferGeometry(), new THREE.PointsMaterial({ color: 0xf6ad55, size: 0.12 }));
+  scene.add(player, ...gems, hazard, sparks);
+
+  // The instrumentation the probe projects a subject through (skill funpixel-verify).
+  Object.assign(window, { __THREEJS_SCENE__: scene, __THREEJS_RENDERER__: renderer, camera, THREE }); // the renderer: what `funtools profile` reads
+
+  // Resize once, through the SDK (it fires once now, then on every change);
+  // pull the camera back until the whole track fits the width.
+  let eye = new THREE.Vector3(0, 4, 10);
+  setupGameResize((width, height) => {
+    camera.aspect = width / height;
+    const fit = (SLOTS / 2 + 1) / (Math.tan(THREE.MathUtils.degToRad(FOV / 2)) * camera.aspect);
+    eye = new THREE.Vector3(0, Math.max(4, fit * 0.4), Math.max(10, fit));
+    camera.updateProjectionMatrix();
+    renderer.setSize(width, height);
+  });
+
+  startSession(host);
+  const clock = new THREE.Clock(), life = new Living('player', ROLE.hero); // the demo hero breathes between events (optional)
+  renderer.setAnimationLoop(() => {
+    const dt = Math.min(clock.getDelta(), 0.1); update(dt);
+    const run = session.run, t = clock.elapsedTime;
+    gems.forEach((g, i) => {
+      g.visible = run.gems[i] === 0;
+      g.position.set(slotX(i), 0.45 + Math.sin(t * 3 + i) * 0.08, 0);
+      g.rotation.y = t * 1.5;
+    });
+    const ph = phase(run);
+    [hazard.visible, crack.visible, blade.visible] = [ph !== 'rest', ph === 'tell', ph === 'strike'];
+    if (run.spike) hazard.position.set(slotX(run.spike.slot), 0.01, 0);
+    hazard.scale.setScalar(ph === 'tell' ? 1 + 0.2 * Math.sin(t * 24) : 1);
+    const sq = squashScale(), pose = life.update(dt), hp = heroPose(heroState(session), run);
+    player.position.set(slotX(run.x), hp.lift, 0);
+    player.scale.set(sq.x * pose.scaleX * hp.sx, sq.y * pose.scaleY * hp.sy, sq.x * pose.scaleX * hp.sx);
+    player.rotation.z = hp.turn;
+    // The hit flash: the player's materials glow white for a few frames.
+    player.traverse((o) => ((o as THREE.Mesh).material as THREE.MeshStandardMaterial | undefined)?.emissive?.setScalar(juice.flash));
+    host.style.setProperty('--vignette', juice.vignette.toFixed(3)); // the edge vignette (styles.css .stage::after), never a full-screen flash
+    sparks.geometry.setFromPoints(juice.particles.map((p) => new THREE.Vector3(slotX(p.x), p.y + 0.4, 0)));
+    const off = shakeOffset(); camera.position.set(eye.x + off.x, eye.y + off.y, eye.z);
+    camera.lookAt(0, 0.5, 0); renderer.render(scene, camera);
+  });
+}

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

@@ -0,0 +1,22 @@
+// Three's side of the world-space HUD (markers.ts): where an object is on
+// screen. Pin with `pin(enemy, bar)`, then after each render call
+// `drawMarkers(projector(camera), renderer.domElement)`. `lift` raises the
+// marker above the object's origin (a bar over a head).
+
+import * as THREE from 'three';
+import type { Project } from './markers';
+
+const at = new THREE.Vector3();
+const eye = new THREE.Vector3();
+
+export function projector(camera: THREE.Camera, lift = 1.2): Project<THREE.Object3D> {
+  return (target) => {
+    target.getWorldPosition(at);
+    at.y += lift;
+    camera.getWorldPosition(eye);
+    const distance = at.distanceTo(eye);
+    at.project(camera);
+    // Behind a perspective camera the projected depth passes 1.
+    return { x: at.x, y: at.y, front: at.z < 1, distance };
+  };
+}

package/templates/three-world/src/bot.ts

@@ -0,0 +1,43 @@
+// A sharp player through the real rules, engine-free: runs out of a glowing flare (jumping late in the
+// glow when it cannot clear it), else to the nearest pickup, jumping up to the ones on platforms and over
+// whatever stops it. The self-tests, the win view and test/probes.ts all play with it.
+
+import { FLARE_LATE, FLARE_R, FLARE_TELL, MOVE, tick, type Input, type Outcome, type Run } from './rules';
+
+const nearest = (run: Run) => {
+  let best = null as Run['pickups'][number] | null, cost = Infinity;
+  for (const p of run.pickups) {
+    if (p.taken || (run.flare && Math.hypot(p.x - run.flare.x, p.z - run.flare.z) < FLARE_R + 1)) continue; // never into a lit ring
+    const c = Math.hypot(p.x - run.x, p.z - run.z) + 3 * Math.max(0, p.y - run.y - 1);
+    if (c < cost) { cost = c; best = p; }
+  }
+  return best;
+};
+
+/** What a sharp player presses now. */
+export function bestInput(run: Run): Input {
+  const f = run.flare;
+  if (f && Math.hypot(run.x - f.x, run.z - f.z) < FLARE_R + MOVE.radius) {
+    // Run out when there is time to; jump late in the glow only when there is not (never up into a ring lit on a platform).
+    const dx = run.x - f.x || 0.01, dz = run.z - f.z, d = Math.hypot(dx, dz), escape = (FLARE_R + MOVE.radius - d) / MOVE.run < FLARE_TELL + FLARE_LATE - f.t - 0.1;
+    return { x: dx / d, z: dz / d, jump: run.grounded && !escape && f.y <= run.y + 0.2 && f.t > FLARE_TELL - 0.12 };
+  }
+  const p = nearest(run);
+  if (!p) return { x: 0, z: 0 };
+  const dx = p.x - run.x, dz = p.z - run.z, d = Math.hypot(dx, dz) || 1;
+  const up = p.y - 0.6 > run.y + 0.1 && d < 2.6, stuck = run.grounded && Math.hypot(run.vx, run.vz) < 1 && d > 1.5;
+  const nearFlare = !!f && Math.hypot(run.x - f.x, run.z - f.z) < FLARE_R + 2.5;
+  return { x: dx / d, z: dz / d, jump: run.grounded && !nearFlare && (up || stuck) };
+}
+
+/** Play a round through the rules: the sharp player deciding every `react` seconds, or never (null). */
+export function botRound(run: Run, react: number | null, limit = 600): Outcome {
+  let input: Input = { x: 0, z: 0 }, wait = 0;
+  for (let t = 0; t < limit; t += 1 / 30) {
+    if (react !== null && (wait -= 1 / 30) <= 0) { input = bestInput(run); wait = react; }
+    const { outcome } = tick(run, input, 1 / 30);
+    input = { ...input, jump: false };
+    if (outcome) return outcome;
+  }
+  return null;
+}

package/templates/three-world/src/budget.ts

@@ -0,0 +1,73 @@
+// The performance budget, as data the game keeps and the probe reads (state.render): a mid phone holds 60
+// fps when a frame stays under ~120 draw calls and ~300k triangles at a pixel ratio of at most 1.5. The
+// pixel ratio steps down by itself when frames run long (and the shadows go first), and back up when there
+// is room. `funtools profile` and `look --hud` read the same facts. Raise a number only after measuring.
+// The quality tier follows the GPU, never the pointer (Held Note, src/view/device.ts): a desktop window in
+// touch emulation reports a coarse pointer and would get the phone's budget. The touch LAYOUT still follows
+// the pointer (controls.tsx). The GPU's name rides in state.render too: a frame time means nothing without
+// it (headless Chrome draws on SwiftShader, no GPU).
+
+import type * as THREE from 'three';
+import { gpuClass, QUALITY_KEY, tierOf, type Tier } from './light-math';
+
+export const BUDGET = {
+  /** Draw calls and triangles a frame may cost; a frame over either is logged once. */
+  calls: 120, triangles: 300_000,
+  /** The pixel ratio's ceiling on a phone-class GPU (phones report 3; 1.5 looks sharp and costs a quarter of 3), on a desktop GPU, and the floor. */
+  maxRatio: 1.5, desktopRatio: 2, minRatio: 0.75,
+  /** The frame time (ms) that counts as long, how many seconds of long frames step down, and the step. */
+  slowMs: 20, slowFor: 1.5, step: 0.25,
+} as const;
+
+/** GPU families that mean a phone or a tablet (iOS, and Safari on a Mac, say only "Apple GPU": there the pointer is fine). */
+const MOBILE_GPU = /adreno|mali|powervr|apple gpu|immortalis|xclipse|videocore|tegra|sgx/i;
+/** A phone-class device (pure: the tests call it): a fine pointer never is; a coarse one is unless its GPU is a desktop's. */
+export const phoneClass = (gpu: string | null, coarse: boolean): boolean => coarse && !(gpu && !MOBILE_GPU.test(gpu));
+
+/** Costs a slow phone sheds before the shadows and the pixel ratio (post.ts adds bloom): each returns true when it shed something. */
+export const shedders: Array<() => boolean> = [];
+
+let renderer: THREE.WebGLRenderer | null = null, ratio: number = BUDGET.maxRatio, cap: number = BUDGET.maxRatio, gpu: string | null = null;
+let slow = 0, fast = 0, fps = 60, warned = false;
+
+export const budget = {
+  /** Take the renderer: cap its pixel ratio and let info count across render calls. */
+  attach(r: THREE.WebGLRenderer): void {
+    renderer = r;
+    try { const gl = r.getContext(), ext = gl.getExtension('WEBGL_debug_renderer_info'); gpu = String(gl.getParameter(ext ? ext.UNMASKED_RENDERER_WEBGL : gl.RENDERER)); } catch { gpu = null; }
+    const coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+    cap = phoneClass(gpu, coarse) ? BUDGET.maxRatio : BUDGET.desktopRatio; ratio = Math.min(devicePixelRatio || 1, cap);
+    r.setPixelRatio(ratio); r.info.autoReset = false;
+  },
+  /** Once a frame, before rendering: zero the counters (a probe reading between frames sees the last whole frame). */
+  begin(): void { renderer?.info.reset(); },
+  /** Once a frame, after rendering: read the cost and adapt the pixel ratio. */
+  frame(dt: number): void {
+    if (!renderer) return;
+    const ms = dt * 1000, info = renderer.info.render;
+    fps += (1 / Math.max(dt, 1e-3) - fps) * 0.05;
+    if (!warned && (info.calls > BUDGET.calls || info.triangles > BUDGET.triangles)) {
+      warned = true;
+      console.warn(`budget: ${info.calls} draw calls / ${info.triangles} triangles (budget ${BUDGET.calls} / ${BUDGET.triangles}); merge or instance (budget.ts)`);
+    }
+    slow = ms > BUDGET.slowMs ? slow + dt : 0;
+    fast = ms < BUDGET.slowMs * 0.6 ? fast + dt : 0;
+    if (slow > BUDGET.slowFor && ratio > BUDGET.minRatio) {
+      if (shedders.some((shed) => shed())) { /* bloom went first */ } else if (renderer.shadowMap.enabled) renderer.shadowMap.enabled = false; else ratio = Math.max(BUDGET.minRatio, ratio - BUDGET.step);
+      renderer.setPixelRatio(ratio); slow = 0;
+    } else if (fast > 5 && ratio < Math.min(devicePixelRatio || 1, cap)) {
+      ratio = Math.min(cap, ratio + BUDGET.step); renderer.setPixelRatio(ratio); fast = 0;
+    }
+    this.last = { calls: info.calls, triangles: info.triangles };
+  },
+  last: { calls: 0, triangles: 0 },
+  /** The quality tier the light, post and dressing are sized by: the player's setting, else the GPU and the device (light-math tierOf). */
+  tier(): Tier {
+    // ?quality=phone|desktop|high (a bench run, a capture) wins, then the player's setting.
+    let userSetting: string | null = typeof location === 'object' ? new URLSearchParams(location.search).get('quality') : null;
+    try { userSetting ??= localStorage.getItem(QUALITY_KEY); } catch { /* private mode */ }
+    const nav = navigator as Navigator & { deviceMemory?: number; connection?: { saveData?: boolean } };
+    return tierOf({ phone: cap === BUDGET.maxRatio, saveData: nav.connection?.saveData === true, deviceMemory: nav.deviceMemory, gpuTier: gpuClass(gpu), userSetting });
+  },
+  facts: () => ({ calls: budget.last.calls, triangles: budget.last.triangles, pixelRatio: ratio, fps: Math.round(fps), shadows: !!renderer?.shadowMap.enabled, gpu, tier: cap === BUDGET.maxRatio ? 'phone' : 'desktop' }),
+};

package/templates/three-world/src/camera-rig.ts

@@ -0,0 +1,99 @@
+// The camera rig: a third-person follow that frames where the hero is GOING (look-ahead on its velocity),
+// stays out of walls (a ray from the hero to the eye against every platform and pillar; it pulls in fast
+// and eases back out slowly, so it never clips and never pumps), keeps its yaw steady so the stick means
+// the same thing all round (the hits' rule for touch: a camera that turns by itself turns the controls),
+// and frames whatever shot is current (shots.ts: the title's orbit over the square, play's follow, a
+// beat's reveal), blending between them. The framing numbers are SHOTS; the follow's handling is RIG;
+// `__FPX_CAMERA__` reports both so `funtools score` names the line to edit. Skill funpixel-game-spine, camera.md.
+
+import * as THREE from 'three';
+import type { Box, Post } from './layout';
+import { juice, shakeOffset } from './juice';
+import { ease, SHOTS, shots, type Shot } from './shots';
+
+export const RIG = {
+  /** Seconds of velocity framed ahead, and follow rates (per second; higher is tighter). */
+  lookAhead: 0.35, follow: 7, aheadFollow: 3,
+  /** Clearance from walls (m), how fast it pulls in and eases back out, and the nearest it comes. */
+  clearance: 0.4, pullIn: 20, easeOut: 2.5, nearest: 2.2,
+} as const;
+
+const v = new THREE.Vector3(), dir = new THREE.Vector3(), box = new THREE.Box3(), ray = new THREE.Ray(), hit = new THREE.Vector3();
+
+/** How far along the ray from `from` (unit `d`) to `len` metres the first solid is, or `len`. */
+function firstHit(from: THREE.Vector3, d: THREE.Vector3, len: number, boxes: Box[], posts: Post[]): number {
+  let best = len;
+  ray.set(from, d);
+  for (const b of boxes) {
+    // The eye rises from the look point, so a solid no taller than that point cannot block it (a low crate
+    // beside the hero once pinned the camera to the hero's back: Tidemarket, 1 Oct).
+    if (d.y > 0 && b.top <= from.y) continue;
+    box.min.set(b.x - b.hw - 0.2, -1, b.z - b.hd - 0.2); box.max.set(b.x + b.hw + 0.2, b.top, b.z + b.hd + 0.2);
+    if (ray.intersectBox(box, hit)) best = Math.min(best, hit.distanceTo(from));
+  }
+  for (const p of posts) {
+    const ox = from.x - p.x, oz = from.z - p.z, a = d.x * d.x + d.z * d.z, bq = 2 * (ox * d.x + oz * d.z), c = ox * ox + oz * oz - (p.r + 0.25) ** 2, disc = bq * bq - 4 * a * c;
+    if (a < 1e-6 || disc < 0) continue;
+    const t = (-bq - Math.sqrt(disc)) / (2 * a);
+    if (t > 0 && t < best && from.y + d.y * t < p.h + 0.3) best = t;
+  }
+  return best;
+}
+
+const lerp3 = (a: [number, number, number], b: THREE.Vector3, t: number) => v.set(a[0] + (b.x - a[0]) * t, a[1] + (b.y - a[1]) * t, a[2] + (b.z - a[2]) * t);
+
+export class CameraRig {
+  readonly camera = new THREE.PerspectiveCamera(SHOTS.play.fov, 1, 0.1, 500);
+  private look = new THREE.Vector3(0, SHOTS.play.lookHeight, 0);
+  private ahead = new THREE.Vector3();
+  private reach: number = Math.hypot(SHOTS.play.distance, SHOTS.play.height);
+  private angle = 0;
+  private eye = new THREE.Vector3();
+  readonly aim = new THREE.Vector3(); // what the eye looks at (cameraReport, shots.ts)
+  /** The yaw the stick is read along: the current follow shot's. */
+  yaw: number = SHOTS.play.yaw;
+  lens: number = SHOTS.play.fov; // the lens before juice, for the report
+
+  /** Frame the current shot (follow the hero clear of the solids, or orbit), blending from the last one. */
+  update(dt: number, hero: { x: number; y: number; z: number; vx: number; vz: number }, boxes: Box[], posts: Post[]): void {
+    const k = (rate: number) => 1 - Math.exp(-rate * dt);
+    const shot: Shot = SHOTS[shots.current];
+    if (shots.from === null && shots.t < 1) shots.from = { pos: this.camera.position.toArray() as [number, number, number], look: this.look.toArray() as [number, number, number], fov: this.camera.fov };
+    if (shot.move === 'orbit') {
+      this.angle += dt * (shot.speed ?? 0.07);
+      const c = shot.look ?? [0, shot.lookHeight, 0];
+      this.aim.set(c[0], c[1], c[2]);
+      this.eye.set(c[0] + Math.sin(this.angle) * shot.distance, c[1] + shot.height, c[2] + Math.cos(this.angle) * shot.distance);
+      this.reach = Math.hypot(SHOTS.play.distance, SHOTS.play.height);
+      this.look.copy(this.aim);
+    } else {
+      this.yaw = shot.yaw;
+      this.ahead.lerp(v.set(hero.vx, 0, hero.vz).multiplyScalar(RIG.lookAhead), k(RIG.aheadFollow));
+      this.look.lerp(v.set(hero.x, hero.y + shot.lookHeight, hero.z).add(this.ahead), k(RIG.follow));
+      // Upright phones see less to the sides: pull back and look a little flatter so the world still reads.
+      const tall = Math.max(0, 1 - this.camera.aspect), dist = shot.distance * (1 + tall * 0.5), high = shot.height * (1 + tall * 0.2);
+      const full = Math.hypot(dist, high);
+      dir.set(Math.sin(this.yaw) * dist, high, Math.cos(this.yaw) * dist).normalize();
+      const free = Math.max(RIG.nearest, firstHit(v.set(hero.x, hero.y + shot.lookHeight, hero.z), dir, full, boxes, posts) - RIG.clearance);
+      this.reach += (free - this.reach) * k(free < this.reach ? RIG.pullIn : RIG.easeOut);
+      this.eye.copy(this.look).addScaledVector(dir, this.reach);
+      this.eye.y = Math.max(0.6, this.eye.y);
+      this.aim.copy(this.look);
+    }
+    // The blend: from where the last shot left the camera to this one, eased.
+    let lens: number = shot.fov;
+    if (shots.t < 1 && shots.from) {
+      shots.t = Math.min(1, shots.t + dt / Math.max(0.05, shots.seconds));
+      const e = ease(shots.t);
+      this.eye.copy(lerp3(shots.from.pos, this.eye, e));
+      this.aim.copy(lerp3(shots.from.look, this.aim, e));
+      lens = shots.from.fov + (shot.fov - shots.from.fov) * e;
+    }
+    const off = shakeOffset();
+    this.camera.position.copy(this.eye); this.camera.lookAt(this.aim);
+    this.camera.position.x += off.x; this.camera.position.y += off.y;
+    this.lens = lens;
+    const fov = lens + juice.fov;
+    if (Math.abs(this.camera.fov - fov) > 0.01) { this.camera.fov = fov; this.camera.updateProjectionMatrix(); }
+  }
+}

package/templates/three-world/src/controls.tsx

@@ -0,0 +1,49 @@
+// Phone controls: a floating stick (put a thumb down anywhere in the left zone and the stick is born under
+// it; drag to move, release to stop) and the action buttons in the right thumb's arc (jump big, dash
+// smaller), all inside the safe areas. Shown for touch only (`.touch-only`, platform.ts: last input wins, so
+// a finger shows them and a key or a mouse hides them); keys and a gamepad do the same on a desk.
+// The stick zone carries data-fpx-gesture (the moves), the buttons data-fpx-touch (their keys), so verify's
+// phone checks see every key reached by a thumb. Sizes and reach: skill funpixel-mobile-ui.
+
+import { useState } from 'preact/hooks';
+import { Icon } from './icons';
+import { stick } from './input';
+import { useStore } from './store';
+
+/** The stick's travel (CSS px from the base to full speed) and the dead zone (a share of it). */
+export const STICK = { radius: 56, dead: 0.12 };
+
+export function Controls() {
+  const s = useStore();
+  const [base, setBase] = useState<{ x: number; y: number; id: number } | null>(null);
+  const [knob, setKnob] = useState({ x: 0, y: 0 });
+  if (s.screen !== 'playing') return null;
+  const move = (e: PointerEvent, b = base) => {
+    if (!b || e.pointerId !== b.id) return;
+    let dx = e.clientX - b.x, dy = e.clientY - b.y;
+    const len = Math.hypot(dx, dy), max = STICK.radius;
+    if (len > max) { dx *= max / len; dy *= max / len; }
+    setKnob({ x: dx, y: dy });
+    const m = Math.min(1, len / max);
+    Object.assign(stick, m < STICK.dead ? { x: 0, y: 0 } : { x: (dx / max), y: -(dy / max) }, { active: true });
+  };
+  const end = (e: PointerEvent) => {
+    if (!base || e.pointerId !== base.id) return;
+    setBase(null); setKnob({ x: 0, y: 0 }); Object.assign(stick, { x: 0, y: 0, active: false });
+  };
+  return (
+    <>
+      <div class="stick-zone touch-only" data-fpx-gesture="ArrowLeft ArrowRight ArrowUp ArrowDown"
+        onPointerDown={(e) => { const b = { x: e.clientX, y: e.clientY, id: e.pointerId }; (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId); setBase(b); move(e, b); }}
+        onPointerMove={(e) => move(e)} onPointerUp={end} onPointerCancel={end}>
+        <div class={`stick ${base ? 'live' : ''}`} style={base ? { left: `${base.x}px`, top: `${base.y}px` } : undefined}>
+          <div class="stick-knob" style={{ transform: `translate(${knob.x}px, ${knob.y}px)` }} />
+        </div>
+      </div>
+      <div class="actions touch-only">
+        <button class="act act-dash" data-fpx-touch="ShiftLeft" aria-label="dash"><Icon name="dash" size={30} /></button>
+        <button class="act act-jump" data-fpx-touch="Space" aria-label="jump"><Icon name="jump" size={40} /></button>
+      </div>
+    </>
+  );
+}

package/templates/three-world/src/cutout-atlas.ts

@@ -0,0 +1,26 @@
+// An atlas built in the page from separate cut-outs (`funtools cut` writes one PNG per figure), for
+// cutouts.ts: one texture, so every figure in it draws in the same single draw call.
+
+import * as THREE from 'three';
+
+/**
+ * An atlas built in the page from separate cut-outs (`funtools cut` writes one PNG per figure): each
+ * picture fitted into a square cell, its foot on the cell's bottom edge, centred. `fill` is the share of
+ * the cell each picture fills (width, height), to size an instance to the figure's true height.
+ */
+export async function atlasFrom(urls: string[], cell = 256): Promise<{ texture: THREE.CanvasTexture; cols: number; rows: number; fill: Array<{ w: number; h: number }> }> {
+  const imgs = await Promise.all(urls.map((u) => new Promise<HTMLImageElement>((ok, fail) => { const im = new Image(); im.onload = () => ok(im); im.onerror = () => fail(new Error(`atlasFrom: ${u} did not load`)); im.src = u; })));
+  const cols = Math.max(1, Math.ceil(Math.sqrt(imgs.length))), rows = Math.max(1, Math.ceil(imgs.length / cols));
+  const canvas = document.createElement('canvas');
+  canvas.width = cols * cell; canvas.height = rows * cell;
+  const g = canvas.getContext('2d')!;
+  const fill = imgs.map((im, i) => {
+    const s = Math.min(cell / im.width, cell / im.height), w = im.width * s, h = im.height * s;
+    g.drawImage(im, (i % cols) * cell + (cell - w) / 2, Math.floor(i / cols) * cell + cell - h, w, h);
+    return { w: w / cell, h: h / cell };
+  });
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.anisotropy = 4;
+  return { texture, cols, rows, fill };
+}

package/templates/three-world/src/cutout-math.ts

@@ -0,0 +1,47 @@
+// The arithmetic of painted cut-outs (cutouts.ts), engine-free so a test can hold it: which cell of an
+// atlas a frame is, which frame a walker shows after walking so far (the stride follows the ground, so
+// the feet never slide), and the sway the shader bends a cut-out by (the top moves, the foot stays).
+
+/** One atlas cell in texture space (v up, row 0 at the top of the picture), mirrored when `flip`. */
+export interface Rect { u0: number; v0: number; u1: number; v1: number }
+
+export function frameRect(frame: number, cols: number, rows: number, flip = false): Rect {
+  const n = Math.max(1, cols * rows);
+  const f = ((Math.floor(frame) % n) + n) % n;
+  const c = f % cols, r = Math.floor(f / cols);
+  const u0 = c / cols, u1 = (c + 1) / cols, v1 = 1 - r / rows, v0 = 1 - (r + 1) / rows;
+  return flip ? { u0: u1, v0, u1: u0, v1 } : { u0, v0, u1, v1 };
+}
+
+/** A cycle of frames in the atlas: `first`, `count` frames, one full cycle per `stride` metres walked. */
+export interface Cycle { first: number; count: number; stride: number; idle?: number }
+
+/**
+ * The frame a walker shows after `distance` metres: the cycle advances by distance, not by time, so a
+ * walker that slows takes slower steps and one that stops stops stepping (its `idle` frame, else the
+ * cycle's first). A human walk's stride is about 0.8 body heights per step, two steps a cycle.
+ */
+export function strideFrame(cycle: Cycle, distance: number, moving = true): number {
+  if (!moving) return cycle.idle ?? cycle.first;
+  const count = Math.max(1, Math.floor(cycle.count));
+  const k = Math.floor((Math.max(0, distance) / Math.max(1e-6, cycle.stride)) * count) % count;
+  return cycle.first + k;
+}
+
+/** A biped's stride (metres a full cycle, two steps) for its height: 1.6 body heights. */
+export const strideFor = (heightM: number): number => 1.6 * heightM;
+
+/**
+ * The sideways bend of a cut-out at height fraction `k` (0 at the foot, 1 at the top), in widths: zero at
+ * the foot, growing with the square of the height, so grass, a crowd's idle sway or a flag bends rather
+ * than tilting like a card on a stick. The shader in cutouts.ts computes the same.
+ */
+export function swayAt(t: number, k: number, phase: number, amount: number, rate: number): number {
+  const h = Math.min(1, Math.max(0, k));
+  return amount * Math.sin(t * rate + phase) * h * h;
+}
+
+/** The vertical breath (squash and stretch, volume kept): height scale, the width scale is its inverse. */
+export function squashAt(t: number, phase: number, amount: number, rate: number): number {
+  return 1 + amount * Math.sin(t * rate * 2 + phase);
+}