@funpixel/tools 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,82 @@
+// 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 each serve one measure `funtools feel` takes (skill funpixel-game-feel, references/
+// measure.md): hero (a jump's height in bodies, grounded, the state its look shows), threats (tell to
+// burn), control and dead (the death beat), actors (each node's state), t (the game clock), juice (what
+// the renderer applies now). `render` is the frame budget (budget.ts) and `art` the models still drawn
+// as placeholders (models.ts): both ride along so a check or a look can name them.
+// Repeatable frames (HOOKS.md): rounds are seeded from __FPX_SEED__ (rules.ts) and each view CUTS to its
+// named shot (shots.ts), so a capture shows the shot settled, never a blend that depends on what came
+// before; `funtools capture` holds the clock and records the shot it saw.
+
+import { BODY, type Phase, 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 { nudge, type Verb } from './input';
+import { budget } from './budget';
+import { placeholders } from './models';
+import { shoot } from './shots';
+import { world } from './places';
+import places from './places.json';
+
+interface Round {
+  session: { run: Run; beat: number; t: number; yaw: number };
+  inControl: () => boolean;
+  press: (verb: Verb) => void;
+  advance: (dt: number) => void;
+  playToEnd: () => void;
+  collectOne: () => void;
+  endBeat: () => void;
+  phase: () => Phase;
+}
+
+/** 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' | 'dash' | 'jump' | 'fall' | 'run' | 'idle' {
+  const r = s.run;
+  return s.beat > 0 ? 'dead' : r.dashT > 0 ? 'dash' : !r.grounded ? (r.vy > 0 ? 'jump' : 'fall') : Math.hypot(r.vx, r.vz) > 0.5 ? 'run' : 'idle';
+}
+
+export function exposeRound(r: Round): void {
+  const { session: s } = r;
+  const lose = () => { if (store.screen !== 'playing') go('playing'); r.advance(s.run.timeLeft); };
+  /** Hold a camera-relative direction for a moment of game time, as a thumb on the stick would. */
+  const walk = (x: number, y: number) => () => { Object.assign(nudge, { x, y, left: 0.25 }); };
+  /** Enter a view on its named shot, cut (0 s), so the frame does not depend on the camera's last move. */
+  const on = (shot: 'title' | 'play', enter: () => void) => () => { enter(); shoot(shot, 0); };
+  exposeHooks({
+    state: () => ({
+      t: s.t, screen: store.screen, x: s.run.x, y: s.run.y, z: s.run.z, score: s.run.score, jumps: s.run.jumps, seed: s.run.seed,
+      wins: store.wins, losses: store.losses, timeLeft: s.run.timeLeft, control: r.inControl(), dead: s.beat > 0, juice: juiceLevel(),
+      hero: { x: s.run.x, y: s.run.y, z: s.run.z, body: BODY, unit: 'm', grounded: s.run.grounded, state: heroState(s), speed: Math.hypot(s.run.vx, s.run.vz) },
+      threats: [{ id: 'flare', phase: r.phase() }],
+      // Keyed by the scene node's name: game.ts names them 'player' and 'hazard'.
+      actors: { player: heroState(s), hazard: r.phase() },
+      render: budget.facts(), art: { placeholders: [...placeholders] }, world: JSON.parse(JSON.stringify(world.facts())),
+      // The objective and its distance (the Silt bar S2; `funtools hook` reads them at the first control).
+      objective: { title: 'Gather the gems', distance: store.goal }, goalDistance: store.goal,
+    }),
+    verbs: {
+      moveLeft: walk(-1, 0), moveRight: walk(1, 0), moveAway: walk(0, 1), moveToward: walk(0, -1),
+      jump: () => r.press('jump'), dash: () => r.press('dash'), pause: () => r.press('pause'),
+      collect: () => { if (store.screen !== 'playing') go('playing'); r.collectOne(); },
+      winRound: () => { if (store.screen !== 'playing') go('playing'); r.playToEnd(); },
+      loseRound: lose,
+    },
+    views: {
+      title: { enter: on('title', () => go('title')) }, ...(hasSplash ? { splash: { enter: enterSplash } } : {}),
+      howto: { enter: on('title', () => go('howto')) },
+      settings: { enter: on('title', () => go('settings')) },
+      playing: { motion: true, enter: on('play', () => go('playing')) },
+      paused: { enter: on('play', () => { go('playing'); go('paused'); }) },
+      won: { enter: on('play', () => { go('playing'); r.playToEnd(); }) },
+      lost: { enter: on('play', () => { lose(); r.endBeat(); }) },
+      // One play view per place (places.json), so `funtools places` and `boxes` set every place side by side.
+      ...Object.fromEntries(places.places.map((p) => [`place-${p.id}`, { motion: true, enter: on('play', () => { world.request = p.id; go('title'); go('playing'); }) }])),
+    },
+    keys: ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Space', 'ShiftLeft', 'Escape', 'KeyM'],
+    selftests: selfTests,
+  });
+}

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

@@ -0,0 +1,79 @@
+// The juice table as data: what every event the player causes or suffers gets. It is the design note's
+// `## Juice` table (skill funpixel-game-feel) in code: change a row there and here together. A self-test
+// fails an event with no visual or no sound decision (a cue name, or SILENCE), and a big moment (a win, a
+// loss, a hit) that answers no bigger than a small one (a pickup, a jump). The numbers are TUNE in juice.ts.
+
+import { addTrauma, burst, flash, hitstop, punch, vignette, squash, TUNE } from './juice';
+import { duck, play } from './sound';
+import { show, store } from './store';
+
+export const SILENCE = 'silence';
+
+export interface Feel {
+  visual: string;
+  /** The sound file's name under public/assets/sfx/ (silent until it exists), or SILENCE. */
+  sfx: string;
+  burst?: number;
+  /** Sparks rise (true) or dust spreads low (false). */
+  up?: boolean;
+  /** + squash, − stretch; a landing scales it by how hard it landed. */
+  squash?: number;
+  flash?: number;
+  hitstop?: number;
+  trauma?: number;
+  vignette?: boolean;
+  /** The camera's field of view kicks out (a dash, a win). */
+  punch?: number;
+  pop?: string;
+  duck?: boolean;
+  moment?: 'small' | 'big';
+}
+
+export const FEEL: Record<string, Feel> = {
+  pickup: { visual: '16 sparks rise from it, the hero squashes, +1 by the count', sfx: 'pickup', burst: 16, squash: 0.2, pop: '+1', moment: 'small' },
+  jump: { visual: 'the hero stretches tall, a puff of dust at the feet', sfx: 'jump', squash: -0.25, burst: 6, up: false, moment: 'small' },
+  land: { visual: 'the hero squashes by how hard it landed, dust rings out', sfx: 'land', squash: 0.35, burst: 10, up: false, moment: 'small' },
+  dash: { visual: 'the view kicks wider, a streak of dust, a small shake', sfx: 'dash', punch: 1, burst: 8, up: false, trauma: 0.12, moment: 'small' },
+  bump: { visual: 'a short flash and shake against the wall', sfx: 'bump', flash: 3, hitstop: 2, trauma: 0.2, moment: 'small' },
+  tell: { visual: 'a ring glows on the ground under the hero for the whole tell', sfx: 'tell' },
+  hit: { visual: 'the flare bursts, the hero topples for the death beat, a flash, a heavy shake', sfx: 'lose', burst: 30, flash: 6, trauma: 0.5, vignette: true, duck: true, moment: 'big' },
+  won: { visual: '60 sparks, the view kicks wide, a shake', sfx: 'win', burst: 60, punch: 1.5, trauma: 0.3, duck: true, moment: 'big' },
+  lost: { visual: 'a flash, an edge vignette, a heavy shake', sfx: 'lose', flash: 6, hitstop: 8, trauma: 0.45, vignette: true, duck: true, moment: 'big' },
+};
+
+let popId = 0;
+
+/** Play one event's row at a world position; `power` scales a landing's squash (m/s of impact). */
+export function answer(event: keyof typeof FEEL, x = 0, y = 0, z = 0, power?: number): void {
+  const f = FEEL[event];
+  if (f.burst) burst(x, y + (f.up === false ? 0.05 : 0.5), z, f.burst, f.up !== false);
+  if (f.squash) squash(power === undefined ? f.squash : f.squash * Math.min(1, power / TUNE.hardLanding));
+  if (f.flash) flash(f.flash);
+  if (f.hitstop) hitstop(f.hitstop);
+  if (f.trauma) addTrauma(f.trauma);
+  if (f.vignette) vignette();
+  if (f.punch) punch(f.punch);
+  if (f.duck) duck();
+  if (f.sfx !== SILENCE) play(f.sfx);
+  if (f.pop) {
+    const pop = { id: ++popId, text: f.pop };
+    show({ pops: [...store.pops, pop].slice(-4) });
+    setTimeout(() => show({ pops: store.pops.filter((p) => p.id !== pop.id) }), 700);
+  }
+}
+
+export const weight = (f: Feel): number =>
+  (f.burst ?? 0) + 40 * (f.trauma ?? 0) + 2 * (f.flash ?? 0) + (f.hitstop ?? 0) + 20 * Math.abs(f.squash ?? 0) + 8 * (f.punch ?? 0) + (f.vignette ? 10 : 0);
+
+export const feelTest = {
+  name: 'every juice row has a visual and a sound decision',
+  run: () => Object.values(FEEL).every((f) => f.visual.length > 0 && f.sfx.length > 0),
+};
+
+export const scaleTest = {
+  name: 'every big moment answers bigger than every small one',
+  run: () => {
+    const rows = Object.values(FEEL), small = rows.filter((f) => f.moment === 'small').map(weight);
+    return rows.filter((f) => f.moment === 'big').every((f) => weight(f) > Math.max(0, ...small));
+  },
+};

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

@@ -0,0 +1,99 @@
+// The renderer: it draws session.run and decides nothing. The place on stage (stage.ts: sky, light, post, dressing), the camera (camera-rig.ts),
+// the models with their placeholders (models.ts) and the budget (budget.ts) are each their own file; this
+// one wires them to the round every frame. A new round lays out a new world (layout.ts), rebuilt here.
+
+import * as THREE from 'three';
+import { setupGameResize } from '@funpixel/sdk';
+import { floorAt } from './layout';
+import { FLARE_R, phase } from './rules';
+import { session, startSession, update } from './session';
+import { juice, squashScale } from './juice';
+import { onScreen, store } from './store';
+import { Living, ROLE } from './living';
+import { heroState } from './expose';
+import { heroPose } from './pose';
+import { budget } from './budget';
+import { CameraRig } from './camera-rig';
+import { cameraReport, shoot } from './shots';
+import { makeRenderer, motes, solids } from './world';
+import { Stage } from './stage';
+import { world } from './places';
+import { heroPlaceholder, model, pickupPlaceholder, useRenderer } from './models';
+import { PALETTE } from './palette';
+
+const glowTexture = () => {
+  const c = document.createElement('canvas'); c.width = c.height = 64;
+  const g = c.getContext('2d')!, r = g.createRadialGradient(32, 32, 0, 32, 32, 32);
+  r.addColorStop(0, 'rgba(255,255,255,1)'); r.addColorStop(0.4, 'rgba(255,255,255,0.5)'); r.addColorStop(1, 'rgba(255,255,255,0)');
+  g.fillStyle = r; g.fillRect(0, 0, 64, 64);
+  return new THREE.CanvasTexture(c);
+};
+
+export async function startGame(host: HTMLElement): Promise<void> {
+  const renderer = makeRenderer(host), scene = new THREE.Scene(), rig = new CameraRig(), camera = rig.camera;
+  const stage = new Stage(scene, renderer, camera, host); useRenderer(renderer);
+  world.facts = () => stage.facts();
+  onScreen((next) => { if (next === 'won') world.round++; }); // a won round travels on: the next round is the next place
+  const drift = motes(scene, glowTexture());
+  const makeHero = await model('hero', 1, heroPlaceholder), makePickup = await model('pickup', 0.7, pickupPlaceholder);
+  const hero = new THREE.Group().add(makeHero()); hero.name = 'player';
+  const blob = new THREE.Mesh(new THREE.CircleGeometry(0.42, 24).rotateX(-Math.PI / 2), new THREE.MeshBasicMaterial({ color: 0x000000, transparent: true, opacity: 0.35, depthWrite: false }));
+  // The flare: a ring on the ground through the tell, a column of light through the burn.
+  const ring = new THREE.Mesh(new THREE.RingGeometry(FLARE_R - 0.18, FLARE_R, 40).rotateX(-Math.PI / 2), new THREE.MeshBasicMaterial({ color: PALETTE.harm, transparent: true, depthWrite: false }));
+  const column = new THREE.Mesh(new THREE.CylinderGeometry(FLARE_R, FLARE_R * 0.8, 2.2, 28, 1, true), new THREE.MeshBasicMaterial({ color: PALETTE.harm, transparent: true, opacity: 0.6, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, depthWrite: false }));
+  column.position.y = 1.1;
+  const hazard = new THREE.Group().add(ring, column); [hazard.name, ring.name, column.name] = ['hazard', 'ring', 'column'];
+  const sparks = new THREE.Points(new THREE.BufferGeometry(), new THREE.PointsMaterial({ map: glowTexture(), color: PALETTE.pickup, size: 0.35, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending }));
+  scene.add(hero, blob, hazard, sparks);
+
+  // The world of the round in play: platforms, pillars and pickups from its layout, rebuilt for each new round.
+  let built: typeof session.run | null = null, level = new THREE.Group(), gems: THREE.Object3D[] = [];
+  const build = () => {
+    scene.remove(level); level = new THREE.Group(); built = session.run;
+    // Each round plays the next place (or the one a place-<id> view asked for): light, ground and dressing first, so the solids take its stone.
+    void stage.enter(world.request ?? world.round, built.boxes, built.posts, built.seed); world.request = null;
+    for (const o of solids(level, built.boxes, built.posts)) o.name ||= 'solid';
+    gems = built.pickups.map((p, i) => { const g = makePickup(); g.position.set(p.x, p.y, p.z); g.name = `pickup-${i}`; level.add(g); return g; });
+    scene.add(level);
+  };
+
+  // The instrumentation the probe projects a subject through (skill funpixel-verify), and what `funtools profile` reads.
+  Object.assign(window, { __THREEJS_SCENE__: scene, __THREEJS_RENDERER__: renderer, __THREEJS_CAMERA__: camera, camera, THREE, __FPX_CAMERA__: () => cameraReport(rig, renderer.toneMappingExposure) });
+  setupGameResize((width, height) => { camera.aspect = width / height; camera.updateProjectionMatrix(); renderer.setSize(width, height); stage.setSize(width, height); });
+  startSession(); build();
+  // Warm-up: compile every material's shader before the first frame, so play never hitches on one.
+  await renderer.compileAsync(scene, camera).catch(() => {});
+  const clock = new THREE.Clock(), life = new Living('player', ROLE.hero), lean = { x: 0 }, PLAY_SCREENS = new Set<string>(['playing', 'paused', 'won', 'lost']);
+  let lastScreen = '';
+  renderer.setAnimationLoop(() => {
+    const dt = Math.min(clock.getDelta(), 0.1); update(dt);
+    const run = session.run, t = clock.elapsedTime, state = heroState(session);
+    if (built !== run) build();
+    drift(t);
+    // The camera plan (shots.ts): only a change of screen picks the shot, so a beat's own (shoot('reveal')) holds.
+    if (store.screen !== lastScreen) { const inPlay = PLAY_SCREENS.has(store.screen); if (inPlay !== PLAY_SCREENS.has(lastScreen)) shoot(inPlay ? 'play' : 'title', 1.1); lastScreen = store.screen; }
+    rig.update(dt, run, run.boxes, run.posts);
+    session.yaw = rig.yaw;
+    run.pickups.forEach((p, i) => { gems[i].visible = !p.taken; gems[i].position.y = p.y + Math.sin(t * 2.5 + i) * 0.12; gems[i].rotation.y = t * 1.6 + i; });
+    // The hero: facing its heading, leaning into speed, squashed on a landing, toppled in the death beat.
+    const sq = squashScale(), pose = life.update(dt), kp = heroPose(state, run);
+    hero.position.set(run.x, run.y, run.z);
+    hero.rotation.set(0, run.heading, 0);
+    lean.x += (kp.lean - lean.x) * Math.min(1, dt * 10);
+    hero.children[0].rotation.set(kp.topple || lean.x, 0, 0);
+    hero.scale.set(sq.x * pose.scaleX * kp.sx, sq.y * pose.scaleY * kp.sy, sq.x * pose.scaleX * kp.sx);
+    hero.traverse((o) => ((o as THREE.Mesh).material as THREE.MeshStandardMaterial | undefined)?.emissive?.setScalar(juice.flash * 0.6));
+    const floor = floorAt(run.boxes, run.x, run.z, run.y, 0.3, 0.17);
+    blob.position.set(run.x, floor + 0.02, run.z);
+    blob.scale.setScalar(Math.max(0.4, 1 - (run.y - floor) * 0.25));
+    const ph = phase(run);
+    hazard.visible = ph !== 'rest';
+    if (run.flare) hazard.position.set(run.flare.x, run.flare.y + 0.03, run.flare.z);
+    (ring.material as THREE.MeshBasicMaterial).opacity = ph === 'tell' ? 0.45 + 0.45 * Math.sin(t * 22) ** 2 : 0.9;
+    ring.scale.setScalar(ph === 'tell' ? 0.85 + 0.15 * (run.flare?.t ?? 0) : 1); column.visible = ph === 'burn';
+    sparks.geometry.setFromPoints(juice.particles.map((p) => new THREE.Vector3(p.x, p.y, p.z)));
+    host.style.setProperty('--vignette', juice.vignette.toFixed(3)); // the edge vignette (styles.css .stage::after), never a full-screen flash
+    stage.tick(t, run.x, run.z); // the place's light (its key and shadow box follow the hero), sky and dressing
+    budget.begin(); stage.render(); budget.frame(dt);
+  });
+}

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

@@ -0,0 +1,44 @@
+// The HUD while playing, as data: each readout is a row (an icon, a label a newcomer can read, the value)
+// on the shared plate, along the top edge inside the safe areas, so the 3D play keeps the middle and the
+// thumbs keep the bottom (controls.tsx). Change the rows, not the markup. A row with `count` counts up and
+// pulses; the time row turns urgent in its last seconds (hud-kit.tsx: Counter, Pips, Bar, all optional).
+
+import { GOAL } from './rules';
+import { Icon, type IconName } from './icons';
+import { Counter, Toasts } from './hud-kit';
+import { useStore, type store } from './store';
+import { Controls } from './controls';
+
+type State = typeof store;
+
+/** What the HUD shows. Every number carries a label: an unlabelled number reads as noise. */
+export const HUD: Array<{ id: string; icon: IconName; label: string; value: (s: State) => string; count?: (s: State) => number; urgent?: (s: State) => boolean }> = [
+  // The objective and its distance, on screen from the first control: "Gems 3 / 16 · 12 m" (rules.ts nearestPickup).
+  { id: 'score', icon: 'gem', label: 'Gems', value: (s) => ` / ${GOAL}${s.goal !== null ? ` · ${s.goal} m` : ''}`, count: (s) => s.score },
+  { id: 'time', icon: 'clock', label: 'Time', value: (s) => `${Math.ceil(s.timeLeft)}s`, urgent: (s) => s.timeLeft <= 10 },
+];
+
+export function Hud() {
+  const s = useStore();
+  if (s.screen !== 'playing') return null;
+  return (
+    <>
+      <div class="hud">
+        {HUD.map((r) => (
+          <span class={`hud-row plate hud-${r.id}${r.urgent?.(s) ? ' urgent' : ''}`} key={r.id} aria-label={r.label}>
+            <Icon name={r.icon} size={22} />
+            <span class="hud-label">{r.label}</span>
+            <span class="hud-value">{r.count && <Counter value={r.count(s)} />}{r.value(s)}</span>
+            {r.id === 'score' && s.pops.map((p) => <span class="pop" key={p.id}>{p.text}</span>)}
+          </span>
+        ))}
+        <span class="hud-buttons">
+          <button class="icon plate" data-fpx-touch="KeyM" aria-label={s.muted ? 'sound off' : 'sound on'}><Icon name={s.muted ? 'soundOff' : 'soundOn'} /></button>
+          <button class="icon plate" data-fpx-touch="Escape" aria-label="pause"><Icon name="pause" /></button>
+        </span>
+      </div>
+      <Toasts />
+      <Controls />
+    </>
+  );
+}

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

@@ -0,0 +1,36 @@
+// The starter's icon family: chunky, rounded, filled shapes with a thick line, sized for a thumb and read
+// at a glance over a 3D scene. A starting family, not this game's: redraw them in the game's own style
+// (its stroke, corners and a motif of its world) with the same names, so no call site changes (skill
+// funpixel-mobile-ui, references/restyle-ui.md). Inline SVG, never emoji. Two tones from styles.css's
+// tokens: the fill in --icon-fill, the line in --icon-line, the stroke --icon-stroke.
+
+type Glyph = { line: string; fill?: string };
+
+export const ICONS = {
+  left: { line: 'M14.5 6.5 9 12l5.5 5.5', fill: 'M16 4.5 7.5 12l8.5 7.5c1 .9 2.3.2 2.3-1.1V5.6c0-1.3-1.3-2-2.3-1.1z' },
+  right: { line: 'M9.5 6.5 15 12l-5.5 5.5', fill: 'M8 4.5 16.5 12 8 19.5c-1 .9-2.3.2-2.3-1.1V5.6c0-1.3 1.3-2 2.3-1.1z' },
+  up: { line: 'M6.5 14.5 12 9l5.5 5.5', fill: 'M4.5 16 12 7.5l7.5 8.5c.9 1 .2 2.3-1.1 2.3H5.6c-1.3 0-2-1.3-1.1-2.3z' },
+  pause: { line: 'M9 7.5v9M15 7.5v9', fill: 'M6.5 4.5h3.8a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1H6.5a1 1 0 0 1-1-1v-13a1 1 0 0 1 1-1zm7.2 0h3.8a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-3.8a1 1 0 0 1-1-1v-13a1 1 0 0 1 1-1z' },
+  play: { line: 'M9.5 8.2v7.6l6-3.8z', fill: 'M7.2 4.6c0-1 1.1-1.6 1.9-1.1l11 7.4c.8.5.8 1.7 0 2.2l-11 7.4c-.8.5-1.9-.1-1.9-1.1z' },
+  soundOn: { line: 'M16 9.2c1.6 1.4 1.6 4.2 0 5.6M18.6 6.8c3 2.8 3 7.6 0 10.4', fill: 'M3.5 9.2c0-.7.5-1.2 1.2-1.2h2.8l4.6-3.7c.8-.6 1.9-.1 1.9.9v13.6c0 1-1.1 1.5-1.9.9L7.5 16H4.7c-.7 0-1.2-.5-1.2-1.2z' },
+  soundOff: { line: 'M16 9.5l4.5 5M20.5 9.5l-4.5 5', fill: 'M3.5 9.2c0-.7.5-1.2 1.2-1.2h2.8l4.6-3.7c.8-.6 1.9-.1 1.9.9v13.6c0 1-1.1 1.5-1.9.9L7.5 16H4.7c-.7 0-1.2-.5-1.2-1.2z' },
+  help: { line: 'M10 9.6c.2-1.3 1.1-2 2.2-2 1.3 0 2.2.9 2.2 2 0 1.6-2.3 1.8-2.3 3.6M12.1 16.4v.1', fill: 'M12 2.8c5.1 0 9.2 4.1 9.2 9.2s-4.1 9.2-9.2 9.2S2.8 17.1 2.8 12 6.9 2.8 12 2.8z' },
+  settings: { line: 'M12 9.6a2.4 2.4 0 1 0 0 4.8 2.4 2.4 0 0 0 0-4.8z', fill: 'M10.6 2.8h2.8l.6 2.4 1.8.8 2.2-1.3 2 2-1.3 2.2.8 1.8 2.4.6v2.8l-2.4.6-.8 1.8 1.3 2.2-2 2-2.2-1.3-1.8.8-.6 2.4h-2.8l-.6-2.4-1.8-.8-2.2 1.3-2-2 1.3-2.2-.8-1.8-2.4-.6v-2.8l2.4-.6.8-1.8-1.3-2.2 2-2 2.2 1.3 1.8-.8z' },
+  gem: { line: 'M5 9.5h14M9.5 4.8 12 9.5l2.5-4.7M12 9.5v10', fill: 'M7.6 4.2h8.8l4.4 5.4-8.8 10.8L3.2 9.6z' },
+  heart: { line: 'M8.5 8.6c-.9 0-1.6.7-1.7 1.6', fill: 'M12 20.4s-8.4-5-8.4-10.6c0-2.8 2.1-4.9 4.7-4.9 1.6 0 2.9.8 3.7 2 .8-1.2 2.1-2 3.7-2 2.6 0 4.7 2.1 4.7 4.9 0 5.6-8.4 10.6-8.4 10.6z' },
+  clock: { line: 'M12 7.6V12l3.2 2', fill: 'M12 2.8c5.1 0 9.2 4.1 9.2 9.2s-4.1 9.2-9.2 9.2S2.8 17.1 2.8 12 6.9 2.8 12 2.8z' },
+  jump: { line: 'M12 17.5V8.2M8.2 11.6 12 7.8l3.8 3.8', fill: 'M5 19.2c0-.7.5-1.2 1.2-1.2h11.6c.7 0 1.2.5 1.2 1.2s-.5 1.2-1.2 1.2H6.2c-.7 0-1.2-.5-1.2-1.2z' },
+  dash: { line: 'M4.5 9h5M3.5 12h6M4.5 15h5', fill: 'M11 5.4c0-.9 1-1.4 1.8-.9l8 5.9c.7.6.7 1.6 0 2.2l-8 5.9c-.8.5-1.8 0-1.8-.9z' },
+} satisfies Record<string, Glyph>;
+
+export type IconName = keyof typeof ICONS;
+
+export const Icon = ({ name, size = 24 }: { name: IconName; size?: number }) => {
+  const g: Glyph = ICONS[name];
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} aria-hidden="true" class="ico">
+      {g.fill && <path class="ico-fill" d={g.fill} />}
+      <path class="ico-line" d={g.line} />
+    </svg>
+  );
+};

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

@@ -0,0 +1,73 @@
+// Input: a move direction (held keys, the touch stick, the gamepad's left stick, all the same vector) and
+// verbs, one name per action, reached from the keyboard, the on-screen buttons and a gamepad alike, so a
+// phone reaches every action a keyboard does and a check can drive any of them. The stick is screen-space
+// (x right, y up = away from the camera); session.ts turns it by the camera's yaw into the world.
+
+export type Verb = 'jump' | 'dash' | 'pause' | 'confirm' | 'mute';
+
+/** KeyboardEvent.code → a direction held. */
+export const MOVE_KEYS: Record<string, [number, number]> = {
+  ArrowLeft: [-1, 0], KeyA: [-1, 0], ArrowRight: [1, 0], KeyD: [1, 0],
+  ArrowUp: [0, 1], KeyW: [0, 1], ArrowDown: [0, -1], KeyS: [0, -1],
+};
+/** KeyboardEvent.code → verb. Each verb's first code is declared in __FPX_KEYS__; on a phone the buttons carry them. */
+export const KEYS: Record<string, Verb> = {
+  Space: 'jump', KeyJ: 'jump', ShiftLeft: 'dash', KeyK: 'dash',
+  Escape: 'pause', KeyP: 'pause', Enter: 'confirm', KeyM: 'mute',
+};
+
+/** Standard-mapping gamepad: A jumps, X or B dashes, Start pauses; the left stick moves. */
+const PAD_BUTTONS: Record<number, Verb> = { 0: 'jump', 2: 'dash', 1: 'dash', 9: 'pause' };
+const held = new Set<string>(), padHeld = new Set<Verb>();
+/** The touch stick's vector (controls.tsx writes it) and the gamepad's, each length ≤ 1. */
+export const stick = { x: 0, y: 0, active: false }; const pad = { x: 0, y: 0 };
+/** The jump is held (a held jump rises higher; a release cuts it). */
+export const hold = { jump: false };
+/** A verb's own nudge (checks and journeys): a direction held for a moment of game time. */
+export const nudge = { x: 0, y: 0, left: 0 };
+
+/** The direction asked for now, screen-space, length ≤ 1. */
+export function moveVector(): { x: number; y: number } {
+  let x = stick.x + pad.x, y = stick.y + pad.y;
+  for (const code of held) { const d = MOVE_KEYS[code]; if (d) { x += d[0]; y += d[1]; } }
+  if (nudge.left > 0) { x += nudge.x; y += nudge.y; }
+  const len = Math.hypot(x, y);
+  return len > 1 ? { x: x / len, y: y / len } : { x, y };
+}
+
+export function bindInput(press: (verb: Verb) => void): void {
+  addEventListener('keydown', (e) => {
+    if (MOVE_KEYS[e.code]) { held.add(e.code); e.preventDefault(); return; }
+    const verb = KEYS[e.code];
+    if (!verb) return;
+    if (verb !== 'pause') e.preventDefault();
+    if (verb === 'jump') hold.jump = true;
+    if (!e.repeat) press(verb);
+  });
+  addEventListener('keyup', (e) => { held.delete(e.code); if (KEYS[e.code] === 'jump') hold.jump = false; });
+  // The on-screen buttons and the HUD's icons: data-fpx-touch="<code>" presses that code's verb.
+  document.addEventListener('pointerdown', (e) => {
+    const el = (e.target as Element | null)?.closest?.('[data-fpx-touch]');
+    const verb = el ? KEYS[el.getAttribute('data-fpx-touch') ?? ''] : undefined;
+    if (!verb) return;
+    e.preventDefault();
+    if (verb === 'jump') hold.jump = true;
+    press(verb);
+  });
+  addEventListener('pointerup', () => { if (!held.has('Space')) hold.jump = false; });
+  addEventListener('blur', () => { held.clear(); hold.jump = false; Object.assign(stick, { x: 0, y: 0, active: false }); });
+}
+
+/** Poll the first gamepad once a frame: the left stick moves (dead zone 0.2), a button presses once per push. */
+export function pollGamepad(press: (verb: Verb) => void): void {
+  const gp = typeof navigator.getGamepads === 'function' ? navigator.getGamepads()[0] : null;
+  if (!gp) { pad.x = pad.y = 0; return; }
+  const ax = gp.axes[0] ?? 0, ay = gp.axes[1] ?? 0, len = Math.hypot(ax, ay);
+  [pad.x, pad.y] = len < 0.2 ? [0, 0] : [ax, -ay];
+  const down = new Set<Verb>();
+  for (const [i, verb] of Object.entries(PAD_BUTTONS)) if (gp.buttons[Number(i)]?.pressed) down.add(verb);
+  hold.jump = hold.jump || down.has('jump');
+  for (const v of down) if (!padHeld.has(v)) press(v);
+  padHeld.clear();
+  for (const v of down) padHeld.add(v);
+}

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

@@ -0,0 +1,91 @@
+// Juice: the numbers the renderer applies every frame, in metres. Every feel default is tunable in one
+// place, TUNE below: shake is trauma² × a maximum, capped and decaying; flashes last a few frames;
+// particles are capped and the oldest go first; hitstop freezes the sim's bodies, never input, the HUD
+// or the particles; squash and stretch are the body's (a landing squashes by how hard it landed).
+// The motion setting (store.motion; off under prefers-reduced-motion until the player turns it on) is
+// the off switch for shake, the camera's punch and full-screen flashes; the local response a row declares
+// stays, so every action still answers. What each event gets is the table in feel.ts; `funtools feel`
+// reads juiceLevel() (state.juice) to time each key event's answer and to check a win answers bigger.
+
+import { store } from './store';
+
+export interface Particle { x: number; y: number; z: number; vx: number; vy: number; vz: number; life: number; warm: boolean }
+
+const FRAME = 1 / 60;
+
+/** The feel defaults, one place to tune them (skill funpixel-game-feel). */
+export const TUNE = {
+  /** Shake: trauma is capped at traumaCap; the camera moves trauma² × shakeMax (m); trauma lost per second. */
+  traumaCap: 0.6, shakeMax: 0.5, traumaDecay: 1.8,
+  /** Squash springs back at this rate per second; a flash fades at this rate. A landing at `hardLanding` m/s squashes fully. */
+  squashDecay: 4, flashDecay: 15, hardLanding: 12,
+  /** The edge vignette's strength and fade per second: a hurt shows at the screen's edges, never as a full-screen flash. */
+  vignette: 0.6, vignetteDecay: 4,
+  /** The camera's field of view kick on a dash or a win (degrees), and how fast it settles. */
+  fovPunch: 6, fovDecay: 5,
+  /** Particles: at most this many alive, their speed (m/s), gravity (m/s²) and life lost per second. */
+  maxParticles: 220, particleSpeed: 3.2, particleGravity: 7, particleFade: 1.6,
+} as const;
+
+export const ease = {
+  outCubic: (t: number) => 1 - (1 - t) ** 3,
+  outBack: (t: number) => 1 + 2.7 * (t - 1) ** 3 + 1.7 * (t - 1) ** 2,
+  inOutSine: (t: number) => -(Math.cos(Math.PI * t) - 1) / 2,
+};
+
+export const juice = {
+  /** + squashes (wide and flat), − stretches (tall and thin). */
+  squash: 0,
+  flash: 0,
+  vignette: 0,
+  trauma: 0,
+  fov: 0,
+  /** Seconds the sim's bodies stay frozen (hitstop). */
+  freeze: 0,
+  particles: [] as Particle[],
+};
+
+export const squash = (amount = 0.3): void => { juice.squash = amount; };
+export const flash = (frames = 4): void => { juice.flash = Math.max(juice.flash, frames * FRAME * TUNE.flashDecay); };
+export const hitstop = (frames: number): void => { juice.freeze = Math.max(juice.freeze, frames * FRAME); };
+export const addTrauma = (t: number): void => { juice.trauma = Math.min(TUNE.traumaCap, juice.trauma + t); };
+export const vignette = (): void => { if (store.motion) juice.vignette = TUNE.vignette; };
+export const punch = (scale = 1): void => { if (store.motion) juice.fov = TUNE.fovPunch * scale; };
+
+/** A burst at a point: `up` sends it up like sparks; without, it spreads low like dust. */
+export function burst(x: number, y: number, z: number, count = 12, up = true): void {
+  const n = store.motion ? count : Math.ceil(count / 2);
+  for (let i = 0; i < n; i++) {
+    const a = (i / n) * Math.PI * 2 + Math.random() * 0.4, s = TUNE.particleSpeed * (0.5 + Math.random() * 0.8);
+    juice.particles.push({ x, y, z, vx: Math.cos(a) * s, vy: up ? s * (0.6 + Math.random()) : 0.6, vz: Math.sin(a) * s, life: 1, warm: up });
+  }
+  juice.particles.splice(0, Math.max(0, juice.particles.length - TUNE.maxParticles));
+}
+
+export function stepJuice(dt: number): void {
+  juice.squash -= Math.sign(juice.squash) * Math.min(Math.abs(juice.squash), dt * TUNE.squashDecay);
+  juice.flash = Math.max(0, juice.flash - dt * TUNE.flashDecay);
+  juice.vignette = Math.max(0, juice.vignette - dt * TUNE.vignetteDecay);
+  juice.trauma = Math.max(0, juice.trauma - dt * TUNE.traumaDecay);
+  juice.fov = Math.max(0, juice.fov - dt * TUNE.fovDecay * Math.max(1, juice.fov));
+  for (const p of juice.particles) {
+    p.x += p.vx * dt; p.y = Math.max(0.02, p.y + p.vy * dt); p.z += p.vz * dt;
+    p.vy -= TUNE.particleGravity * dt; p.life -= dt * TUNE.particleFade;
+  }
+  juice.particles = juice.particles.filter((p) => p.life > 0);
+}
+
+/** The body's scale this frame: wide and flat on a squash, tall and thin on a stretch, volume kept. */
+export const squashScale = () => ({ x: 1 + juice.squash * 0.8, y: 1 - juice.squash });
+
+/** The camera's offset this frame, in metres; zero with motion off. */
+export function shakeOffset(): { x: number; y: number } {
+  const a = store.motion ? juice.trauma * juice.trauma * TUNE.shakeMax : 0, t = performance.now() / 1000;
+  return { x: a * Math.sin(t * 47.3), y: a * Math.sin(t * 61.7 + 1.3) };
+}
+
+/** What the renderer applies right now (state.juice): `funtools feel` times each key event's answer by it. */
+export const juiceLevel = () => ({
+  trauma: juice.trauma, flash: juice.flash, squash: Math.abs(juice.squash), vignette: juice.vignette,
+  freeze: juice.freeze, particles: juice.particles.length, fov: juice.fov,
+});

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

@@ -0,0 +1,73 @@
+// The world's layout from one seed, engine-free: platforms to jump onto, pillars to run around, the
+// pickups (a third of them up on the platforms, so the jump is the way to the score). The renderer
+// draws exactly this list and the rules collide with it, so what you see is what you stand on.
+// Grow the world here: rooms, a route, set pieces (skill funpixel-game-logic, content-at-scale).
+
+/** An axis-aligned platform: centre (x, z), half sizes (hw, hd), top height. */
+export interface Box { x: number; z: number; hw: number; hd: number; top: number }
+/** A round solid (a pillar, a tree trunk): centre and radius. The camera keeps clear of these too. */
+export interface Post { x: number; z: number; r: number; h: number }
+/** A pickup at its centre; `taken` once collected. */
+export interface Pickup { x: number; y: number; z: number; taken: boolean }
+
+/** The square's radius in metres, how many platforms and pillars, and the pickup count. */
+export const ARENA = 15, BOXES = 7, POSTS = 6;
+
+/** The one random source (mulberry32): a number in [0, 1) that advances `s.seed`. */
+export function random(s: { seed: number }): number {
+  s.seed = (s.seed + 0x6d2b79f5) | 0;
+  let t = Math.imul(s.seed ^ (s.seed >>> 15), 1 | s.seed);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+const inBox = (b: Box, x: number, z: number, pad = 0) => Math.abs(x - b.x) <= b.hw + pad && Math.abs(z - b.z) <= b.hd + pad;
+
+/** Platforms, pillars and `count` pickups for a seed; every pickup is reachable with one jump. */
+export function layout(s: { seed: number }, count: number): { boxes: Box[]; posts: Post[]; pickups: Pickup[] } {
+  const boxes: Box[] = [], posts: Post[] = [], pickups: Pickup[] = [];
+  const free = (x: number, z: number, pad: number) => boxes.every((b) => !inBox(b, x, z, pad)) && posts.every((p) => Math.hypot(x - p.x, z - p.z) > p.r + pad);
+  for (let i = 0; boxes.length < BOXES && i < 200; i++) {
+    const a = random(s) * Math.PI * 2, d = 4 + random(s) * (ARENA - 7);
+    const b = { x: Math.sin(a) * d, z: Math.cos(a) * d, hw: 1 + random(s) * 1.2, hd: 1 + random(s) * 1.2, top: 0.6 + Math.round(random(s) * 3) * 0.2 };
+    if (boxes.every((o) => Math.abs(o.x - b.x) > o.hw + b.hw + 2.5 || Math.abs(o.z - b.z) > o.hd + b.hd + 2.5)) boxes.push(b);
+  }
+  for (let i = 0; posts.length < POSTS && i < 200; i++) {
+    const a = random(s) * Math.PI * 2, d = 3.5 + random(s) * (ARENA - 5), x = Math.sin(a) * d, z = Math.cos(a) * d;
+    if (free(x, z, 2.5)) posts.push({ x, z, r: 0.45 + random(s) * 0.3, h: 2.5 + random(s) * 2 });
+  }
+  const high = Math.floor(count / 3);
+  boxes.slice(0, high).forEach((b) => pickups.push({ x: b.x, y: b.top + 0.6, z: b.z, taken: false }));
+  for (let i = 0; pickups.length < count && i < 2000; i++) {
+    const a = random(s) * Math.PI * 2, d = 2.5 + random(s) * (ARENA - 4), x = Math.sin(a) * d, z = Math.cos(a) * d;
+    if (free(x, z, 1.2) && pickups.every((p) => Math.hypot(p.x - x, p.z - z) > 2.5)) pickups.push({ x, y: 0.6, z, taken: false });
+  }
+  return { boxes, posts, pickups };
+}
+
+/** The highest surface under (x, z) the feet can stand on from height y (a step up of `step` is allowed). */
+export function floorAt(boxes: Box[], x: number, z: number, y: number, step: number, foot: number): number {
+  let floor = 0;
+  for (const b of boxes) if (b.top <= y + step && b.top > floor && inBox(b, x, z, foot)) floor = b.top;
+  return floor;
+}
+
+/** Push a body of radius r at height y out of every platform side taller than a step and every post. True when it hit one. */
+export function pushOut(p: { x: number; z: number; vx: number; vz: number }, y: number, r: number, step: number, boxes: Box[], posts: Post[]): boolean {
+  let hit = false;
+  for (const b of boxes) {
+    if (b.top <= y + step || !inBox(b, p.x, p.z, r)) continue;
+    const ox = b.hw + r - Math.abs(p.x - b.x), oz = b.hd + r - Math.abs(p.z - b.z);
+    if (ox < oz) { p.x += Math.sign(p.x - b.x || 1) * ox; p.vx = 0; } else { p.z += Math.sign(p.z - b.z || 1) * oz; p.vz = 0; }
+    hit = true;
+  }
+  for (const q of posts) {
+    const dx = p.x - q.x, dz = p.z - q.z, d = Math.hypot(dx, dz), min = q.r + r;
+    if (d >= min || y > q.h) continue;
+    const nx = d ? dx / d : 1, nz = d ? dz / d : 0, into = p.vx * nx + p.vz * nz;
+    p.x = q.x + nx * min; p.z = q.z + nz * min;
+    if (into < 0) { p.vx -= into * nx; p.vz -= into * nz; } // slide along it, keep the tangent speed
+    hit = true;
+  }
+  return hit;
+}