@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/src/feel.ts

@@ -0,0 +1,78 @@
+// 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 for an event the design
+// keeps quiet), so a new event cannot ship unanswered, and fails a big moment
+// (a win, a loss, a hit) that gets no more than a small one (a point, a hop).
+// The numbers each effect uses (shake, decay, particles, easing) are TUNE in juice.ts.
+
+import { addTrauma, burst, flash, hitstop, vignette, squash } from './juice';
+import { duck, play } from './sound';
+import { show, store } from './store';
+
+/** A juice row's sound decision when the design keeps the event quiet. */
+export const SILENCE = 'silence';
+
+export interface Feel {
+  /** What the eye gets, in words, as the note has it. */
+  visual: string;
+  /** The sound file's name under public/assets/sfx/ (silent until it exists), or SILENCE. */
+  sfx: string;
+  burst?: number;
+  squash?: number;
+  flash?: number;
+  hitstop?: number;
+  trauma?: number;
+  vignette?: boolean;
+  pop?: string;
+  duck?: boolean;
+  /** How big the moment is: a big one (a win, a loss, a hit) must answer bigger than every small one. */
+  moment?: 'small' | 'big';
+}
+
+export const FEEL: Record<string, Feel> = {
+  pickup: { visual: '12 sparks, a squash, +1 by the score', sfx: 'pickup', burst: 12, squash: 0.35, pop: '+1', moment: 'small' },
+  bump: { visual: 'a 4-frame flash, a small shake', sfx: 'bump', flash: 4, hitstop: 3, trauma: 0.2, moment: 'small' },
+  hop: { visual: 'the hero stretches tall in the air (game.ts), a squash on take-off', sfx: 'hop', squash: 0.2, moment: 'small' },
+  tell: { visual: 'a red crack glows under the slot for the whole tell', sfx: 'crack' },
+  hit: { visual: 'the spike stands, the hero topples for the death beat, a flash, a heavy shake', sfx: 'lose', flash: 6, trauma: 0.45, vignette: true, duck: true, moment: 'big' },
+  won: { visual: '40 sparks, a shake', sfx: 'win', burst: 40, 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 track position. */
+export function answer(event: keyof typeof FEEL, x = 0, y = 0.4): void {
+  const f = FEEL[event];
+  if (f.burst) burst(x, y, f.burst);
+  if (f.squash) squash(f.squash);
+  if (f.flash) flash(f.flash);
+  if (f.hitstop) hitstop(f.hitstop);
+  if (f.trauma) addTrauma(f.trauma);
+  if (f.vignette) vignette();
+  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);
+  }
+}
+
+/** How much a row answers with, in one number: particles, shake, flashes, hitstop and squash together. */
+export const weight = (f: Feel): number =>
+  (f.burst ?? 0) + 40 * (f.trauma ?? 0) + 2 * (f.flash ?? 0) + (f.hitstop ?? 0) + 20 * (f.squash ?? 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/common/src/fpx-hooks.ts

@@ -0,0 +1,46 @@
+// fpx-hooks.ts — how a game tells Funpixel's verify what to read and what to
+// press. Without these, verify can only say "not observed". The contract is
+// HOOKS.md in the Funpixel docs; this file is all of it.
+//
+//   import { exposeHooks } from './fpx-hooks';
+//   exposeHooks({ state: () => ({ score, lives, x: player.x }) });
+//   exposeHooks({ verbs: { jump: () => player.jump() }, keys: ['Space'] });
+//
+// Call it once the game is running, and again whenever you add something:
+// each call sets only what it is given.
+
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+type Solved = { solvable: boolean; moves: number };
+
+export interface FpxHooks {
+  /** A fresh snapshot each call: the fields checks read (numbers where they compare). */
+  state?: () => Record<string, Json>;
+  /** Named actions that run the SAME code a real key or tap runs. */
+  verbs?: Record<string, () => void>;
+  /** The game's screens. `motion: true` marks gameplay, which verify enters first; `moment: true`
+   *  marks the signature payoff, which `capture` plays as a burst (its enter() drives the rules there). */
+  views?: Record<string, { enter: () => void; motion?: boolean; moment?: boolean }>;
+  /** KeyboardEvent codes the game listens for; on a phone each needs a swipe on the play (data-fpx-gesture) or a control. */
+  keys?: string[];
+  /** The game makes sound: verify fails it if it plays none. */
+  audio?: boolean;
+  /** The game's own tests; each returns true when it holds. */
+  selftests?: Array<{ name: string; run: () => boolean | Promise<boolean> }>;
+  /** Levels and a solver: verify fails an unsolvable level and reports the difficulty curve. */
+  levels?: { count: number; solve: (index: number) => Solved | Promise<Solved> };
+}
+
+const GLOBALS: Record<keyof FpxHooks, string> = {
+  state: '__FPX_STATE__', verbs: '__FPX_VERBS__', views: '__FPX_VIEWS__', keys: '__FPX_KEYS__',
+  audio: '__FPX_AUDIO__', selftests: '__FPX_SELFTEST__', levels: '__FPX_LEVELS__',
+};
+
+export function exposeHooks(hooks: FpxHooks): void {
+  const w = window as unknown as Record<string, unknown>;
+  for (const [name, value] of Object.entries(hooks) as Array<[keyof FpxHooks, unknown]>) {
+    if (value === undefined || !GLOBALS[name]) continue;
+    if (name === 'keys') w[GLOBALS.keys] = Object.fromEntries((value as string[]).map((code) => [code, 1]));
+    else if (name === 'audio') w[GLOBALS.audio] = value ? { declared: true } : undefined;
+    else w[GLOBALS[name]] = value;
+  }
+}

package/templates/common/src/frame.ts

@@ -0,0 +1,63 @@
+// The safe HUD band, as code the HUD, the pad and the message lane read (not a rule repeated in each
+// stylesheet). The band is how far every edge piece keeps in from each side: the phone's own safe-area
+// insets (the notch, the status bar, the home bar), never less than the floors a phone needs even where
+// the browser reports 0 (a sideways iPhone's notch side, the status bar on an upright one). It is
+// published as CSS variables (--band-top/right/bottom/left) and as window.__FPX_FRAME__ { band, play }
+// for the game (keep world markers out of the band) and for checks; it is measured again on every resize
+// and rotation. Yours to change or drop: `funtools check` measures the outcome, not this file (pieces
+// under the notch, the HUD's cover of the play; `check --phone`).
+
+export interface Insets { top: number; right: number; bottom: number; left: number }
+export interface Rect { x: number; y: number; w: number; h: number }
+
+/** The least each edge keeps, by how the screen is held. A phone is a screen whose short side is 500 px or less. */
+export const FLOORS: Record<'desk' | 'phone-landscape' | 'phone-portrait', Insets> = {
+  desk: { top: 12, right: 16, bottom: 16, left: 16 },
+  'phone-landscape': { top: 12, right: 48, bottom: 24, left: 48 },
+  'phone-portrait': { top: 48, right: 16, bottom: 36, left: 16 },
+};
+
+export const frame = {
+  band: { ...FLOORS.desk } as Insets,
+  /** The viewport inside the band: where play can show without a HUD piece over it. */
+  play: { x: 0, y: 0, w: 0, h: 0 } as Rect,
+  held: 'desk' as keyof typeof FLOORS,
+};
+
+const listeners = new Set<(f: typeof frame) => void>();
+/** Called now and on every change of the band (a rotation, a resize). */
+export function onBand(cb: (f: typeof frame) => void): () => void {
+  listeners.add(cb);
+  cb(frame);
+  return () => { listeners.delete(cb); };
+}
+
+/** The safe-area insets the browser reports (0 outside a notched phone or without viewport-fit=cover). */
+function safeArea(): Insets {
+  const probe = document.createElement('div');
+  probe.style.cssText = 'position:fixed;visibility:hidden;pointer-events:none;padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left)';
+  document.body.appendChild(probe);
+  const cs = getComputedStyle(probe);
+  const px = (v: string) => parseFloat(v) || 0;
+  const out = { top: px(cs.paddingTop), right: px(cs.paddingRight), bottom: px(cs.paddingBottom), left: px(cs.paddingLeft) };
+  probe.remove();
+  return out;
+}
+
+export function measure(): void {
+  const w = innerWidth, h = innerHeight;
+  frame.held = Math.min(w, h) > 500 ? 'desk' : w > h ? 'phone-landscape' : 'phone-portrait';
+  const floor = FLOORS[frame.held], safe = safeArea();
+  frame.band = { top: Math.max(floor.top, safe.top), right: Math.max(floor.right, safe.right), bottom: Math.max(floor.bottom, safe.bottom), left: Math.max(floor.left, safe.left) };
+  frame.play = { x: frame.band.left, y: frame.band.top, w: Math.max(0, w - frame.band.left - frame.band.right), h: Math.max(0, h - frame.band.top - frame.band.bottom) };
+  const root = document.documentElement.style;
+  for (const side of ['top', 'right', 'bottom', 'left'] as const) root.setProperty(`--band-${side}`, `${frame.band[side]}px`);
+  for (const l of listeners) l(frame);
+}
+
+if (typeof document !== 'undefined' && document.body) {
+  measure();
+  addEventListener('resize', measure);
+  addEventListener('orientationchange', () => setTimeout(measure, 120));
+  Object.assign(window, { __FPX_FRAME__: frame });
+}

package/templates/common/src/grade.ts

@@ -0,0 +1,47 @@
+// The colour grade over the play, for Pixi and Three alike: saturation and contrast as a CSS filter on
+// the stage, a tint and a vignette as one overlay above the canvas and below the HUD (the HUD keeps its
+// own colours, so its contrast checks still hold). The compositor applies it, so it costs no draw call
+// and no render target on a phone, and every capture of the page shows it. Values come from
+// src/look.json's "light" block (saturation, contrast, tint, tintAmount, vignette); the 3D starter
+// resolves them from its mood preset and each place first (light-math.ts). A neutral grade removes
+// itself. Skill funpixel-vfx, references/three.md "Grade"; yours to change or drop.
+
+export interface Grade { saturation: number; contrast: number; tint: string; tintAmount: number; vignette: number }
+export const NEUTRAL: Grade = { saturation: 1, contrast: 1, tint: '#ffffff', tintAmount: 0, vignette: 0 };
+
+const num = (v: unknown, lo: number, hi: number, d: number) => (typeof v === 'number' && Number.isFinite(v) ? Math.min(hi, Math.max(lo, v)) : d);
+/** The grade from a look block (anything else is ignored), clamped to values that still read. */
+export function gradeOf(block: Record<string, unknown> | undefined): Grade {
+  const b = block ?? {};
+  return {
+    saturation: num(b.saturation, 0, 2, 1), contrast: num(b.contrast, 0.5, 1.6, 1),
+    tint: typeof b.tint === 'string' && /^#[0-9a-f]{6}$/i.test(b.tint) ? b.tint : '#ffffff', tintAmount: num(b.tintAmount, 0, 0.4, 0), vignette: num(b.vignette, 0, 0.9, 0),
+  };
+}
+
+/** The CSS for a grade (pure: the tests read it): the stage's filter and the overlay's background. */
+export function gradeCss(g: Grade): { filter: string; overlay: string } {
+  const filter = g.saturation === 1 && g.contrast === 1 ? '' : `saturate(${g.saturation.toFixed(2)}) contrast(${g.contrast.toFixed(2)})`;
+  const hex = g.tint.slice(1), rgb = [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16)).join(', ');
+  const layers = [
+    g.vignette > 0 ? `radial-gradient(ellipse at 50% 45%, rgba(0, 0, 0, 0) 45%, rgba(0, 0, 0, ${g.vignette.toFixed(2)}) 100%)` : '',
+    g.tintAmount > 0 ? `linear-gradient(rgba(${rgb}, ${g.tintAmount.toFixed(2)}), rgba(${rgb}, ${g.tintAmount.toFixed(2)}))` : '',
+  ].filter(Boolean);
+  return { filter, overlay: layers.join(', ') };
+}
+
+/** Apply a grade to the stage element; call again to change it (a new place, a new mood). */
+export function applyGrade(stage: HTMLElement, g: Grade): void {
+  const css = gradeCss(g);
+  stage.style.filter = css.filter;
+  stage.dataset.fpxGrade = JSON.stringify(g);
+  let el = stage.querySelector<HTMLElement>(':scope > .grade');
+  if (!css.overlay) { el?.remove(); return; }
+  if (!el) {
+    el = document.createElement('div'); el.className = 'grade'; el.setAttribute('aria-hidden', 'true');
+    Object.assign(el.style, { position: 'absolute', inset: '0', pointerEvents: 'none', mixBlendMode: 'normal' });
+    stage.appendChild(el);
+  }
+  el.style.background = css.overlay;
+}
+

package/templates/common/src/hud-kit.css

@@ -0,0 +1,29 @@
+/* hud-kit.tsx: counters, pips, bars and the message lane (options; restyle or delete with the file). */
+.kit-count { display: inline-block; font-variant-numeric: tabular-nums; }
+.kit-gain { animation: kit-pulse 0.14s ease-out; color: var(--accent); transition: color 0.3s; }
+.kit-loss { animation: kit-shake 0.2s; color: var(--harm); }
+.kit-pips { display: inline-flex; gap: 2px; }
+.kit-empty { opacity: 0.3; }
+.kit-pop { animation: kit-pip-pop 0.25s ease-out; }
+.kit-crack { animation: kit-shake 0.25s; }
+.kit-bar { position: relative; display: inline-block; width: 7em; height: 0.55em; border-radius: 99px; background: rgba(0, 0, 0, 0.45); overflow: hidden; }
+.kit-bar-fill, .kit-bar-trail { position: absolute; inset: 0 auto 0 0; border-radius: inherit; }
+.kit-bar-fill { background: var(--primary); transition: width 0.08s; }
+.kit-bar-trail { background: var(--ink); opacity: 0.6; transition: width 0.35s 0.4s ease-in; }
+.kit-low .kit-bar-fill { animation: kit-throb 0.9s ease-in-out infinite; }
+.kit-toasts { position: fixed; left: 50%; transform: translateX(-50%); display: grid; gap: 6px; justify-items: center; pointer-events: none; }
+.kit-top { top: calc(var(--band-top, max(12px, env(safe-area-inset-top))) + 3.2em); }
+.kit-bottom { bottom: calc(var(--band-bottom, max(16px, env(safe-area-inset-bottom))) + 96px); }
+.kit-toast { padding: 6px 14px; font-weight: 800; max-width: min(80vw, 28em); text-align: center; animation: kit-pulse 0.18s ease-out; }
+.kit-toast.kit-critical { color: var(--accent); font-size: 1.3em; }
+.kit-times { margin-left: 6px; color: var(--accent); }
+.kit-marker { position: fixed; left: 0; top: 0; pointer-events: none; font-size: 13px; font-weight: 800; white-space: nowrap; }
+.kit-marker[data-distance]::after { content: attr(data-distance); display: block; font-size: 12px; text-align: center; }
+.kit-marker.kit-edge::before { content: ''; display: block; margin: 0 auto 2px; width: 0; border: 7px solid transparent; border-left: 12px solid var(--accent); rotate: var(--angle); }
+.kit-reticle { position: fixed; left: 50%; top: 50%; width: 10px; height: 10px; margin: -5px; border: 2px solid var(--ink); border-radius: 50%; box-shadow: 0 0 0 1px var(--bg); pointer-events: none; }
+.kit-reticle.kit-over { border-color: var(--accent); }
+.kit-reticle.kit-hit::after { content: '×'; position: absolute; inset: -9px; display: grid; place-items: center; color: var(--accent); font-size: 22px; animation: fade 0.15s reverse forwards; }
+@keyframes kit-pulse { 50% { transform: scale(1.15); } }
+@keyframes kit-pip-pop { from { transform: scale(1.4); } }
+@keyframes kit-shake { 25% { transform: translateX(-3px); } 75% { transform: translateX(3px); } }
+@keyframes kit-throb { 50% { opacity: 0.55; } }

package/templates/common/src/hud-kit.tsx

@@ -0,0 +1,85 @@
+// The HUD's moving parts, as options: a counter that counts to its new value
+// and pulses (a loss snaps down and flashes), pips that pop in and crack out,
+// a bar whose lost part trails, and the toast queue drawn in the band away
+// from the player. Each change the player caused gets an answer the eye can
+// catch while it watches the play. Restyle through styles.css (`.kit-*`), use
+// a piece, or delete the file (skill funpixel-mobile-ui, references/hud-genres.md).
+
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { Icon, type IconName } from './icons';
+import { store } from './store';
+import { expire, onToasts, toasts, zoneFor } from './toasts';
+
+/** The previous value, and a number that changes on every change (a key that restarts a CSS animation). */
+function useChange<T>(value: T): { prev: T; bumps: number } {
+  const last = useRef({ prev: value, now: value, bumps: 0 });
+  if (last.current.now !== value) last.current = { prev: last.current.now, now: value, bumps: last.current.bumps + 1 };
+  return last.current;
+}
+
+/** A number that counts from the shown value to `value` over `ms` (ease-out). */
+export function Counter({ value, ms = 320, format = String }: { value: number; ms?: number; format?: (n: number) => string }) {
+  const [shown, setShown] = useState(value);
+  const from = useRef(value);
+  const { prev, bumps } = useChange(value);
+  useEffect(() => {
+    const start = from.current;
+    if (value <= start || !store.motion) { from.current = value; setShown(value); return; }
+    const t0 = performance.now();
+    let raf = requestAnimationFrame(function tick(t) {
+      const k = Math.min(1, (t - t0) / ms), eased = 1 - (1 - k) ** 3;
+      from.current = Math.round(start + (value - start) * eased);
+      setShown(from.current);
+      if (k < 1) raf = requestAnimationFrame(tick);
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [value]);
+  const kind = bumps === 0 ? '' : value > prev ? 'kit-gain' : 'kit-loss';
+  return <span class={`kit-count ${kind}`} key={bumps}>{format(shown)}</span>;
+}
+
+/** `max` icons, `value` of them filled: a gained pip pops in, a lost one cracks and stays as an outline. */
+export function Pips({ value, max, icon, label }: { value: number; max: number; icon: IconName; label: string }) {
+  const { prev, bumps } = useChange(value);
+  return (
+    <span class="kit-pips" role="img" aria-label={`${label}: ${value} of ${max}`}>
+      {Array.from({ length: max }, (_, i) => {
+        const moved = bumps > 0 && i >= Math.min(prev, value) && i < Math.max(prev, value);
+        const cls = i < value ? (moved ? 'kit-pip kit-pop' : 'kit-pip') : moved ? 'kit-pip kit-empty kit-crack' : 'kit-pip kit-empty';
+        return <span class={cls} key={`${i}-${moved ? bumps : 0}`}><Icon name={icon} size={20} /></span>;
+      })}
+    </span>
+  );
+}
+
+/** A bar; the part just lost stays as a lighter trail for a moment, then drains (CSS transition). */
+export function Bar({ value, max, label }: { value: number; max: number; label: string }) {
+  const share = Math.max(0, Math.min(1, value / Math.max(max, 1e-6)));
+  return (
+    <span class={`kit-bar${share < 0.2 ? ' kit-low' : ''}`} role="meter" aria-label={label} aria-valuenow={value} aria-valuemax={max}>
+      <span class="kit-bar-trail" style={{ width: `${share * 100}%` }} />
+      <span class="kit-bar-fill" style={{ width: `${share * 100}%` }} />
+    </span>
+  );
+}
+
+/** The message lane, one message at a time in the band away from the player (`playerY`: 0 top … 1 bottom).
+ *  data-fpx-ms tells `look --hud` how long each message stays, so it can say whether it can be read. */
+export function Toasts({ playerY }: { playerY?: number | null }) {
+  const [, redraw] = useState(0);
+  useEffect(() => {
+    const off = onToasts(() => redraw((n) => n + 1));
+    let raf = requestAnimationFrame(function tick() { expire(); raf = requestAnimationFrame(tick); });
+    return () => { off(); cancelAnimationFrame(raf); };
+  }, []);
+  if (!toasts.length || store.screen !== 'playing') return null;
+  return (
+    <div class={`kit-toasts kit-${zoneFor(playerY)}`} aria-live="polite">
+      {toasts.map((t) => (
+        <span class={`kit-toast plate${t.critical ? ' kit-critical' : ''}`} key={`${t.id}-${t.bumps}`} data-fpx-ms={t.life}>
+          {t.text}{t.count > 1 && <b class="kit-times">×{t.count}</b>}
+        </span>
+      ))}
+    </div>
+  );
+}

package/templates/common/src/hud.tsx

@@ -0,0 +1,55 @@
+// The HUD while playing, as data: each readout is a row (an icon, a label a
+// newcomer can read, the value). The play takes the moves as a swipe (input.ts);
+// the on-screen buttons are a setting, off by default. Change the rows, not the markup.
+// Every edge is inset by the safe area (styles.css). A row with `count` counts
+// up and pulses (hud-kit.tsx: Counter, Pips, Bar, toasts, all optional).
+
+import { GOAL } from './rules';
+import { Icon, type IconName } from './icons';
+import { Counter, Toasts } from './hud-kit';
+import { useStore, type store } from './store';
+
+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 }> = [
+  { id: 'score', icon: 'gem', label: 'Gems', value: () => `/${GOAL}`, count: (s) => s.score },
+  { id: 'time', icon: 'clock', label: 'Time', value: (s) => `${Math.ceil(s.timeLeft)}s` },
+];
+
+/** The on-screen buttons, for players who cannot swipe (Settings). A pad that repeats the play's swipe costs the
+ *  bottom of a phone screen and reads as a desktop port (skill funpixel-mobile-ui, step 6). */
+export const PAD: Array<{ code: string; icon: IconName; label: string }> = [
+  { code: 'ArrowLeft', icon: 'left', label: 'step left' },
+  { code: 'ArrowUp', icon: 'up', label: 'hop' },
+  { code: 'ArrowRight', icon: 'right', label: 'step right' },
+];
+
+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}`} key={r.id}>
+            <Icon name={r.icon} size={20} />
+            <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" data-fpx-touch="KeyM" aria-label={s.muted ? 'sound off' : 'sound on'}><Icon name={s.muted ? 'soundOff' : 'soundOn'} /></button>
+          <button class="icon" data-fpx-touch="Escape" aria-label="pause"><Icon name="pause" /></button>
+        </span>
+      </div>
+      <Toasts />
+      {s.pad && <div class="pad touch-only">
+        {PAD.map((b) => (
+          <button class="plate" data-fpx-touch={b.code} aria-label={b.label} key={b.code}><Icon name={b.icon} size={32} /></button>
+        ))}
+      </div>}
+    </>
+  );
+}

package/templates/common/src/icons.tsx

@@ -0,0 +1,35 @@
+// PLACEHOLDER GLYPHS: a working set so the first build has icons, not this game's family. Redraw
+// them in the game's own style (its stroke weight, corners and a motif of its world) with the
+// same names, so no call site changes (skill funpixel-mobile-ui, references/restyle-ui.md);
+// `look --hud` names these glyphs while they ship. Inline SVG, never emoji: they take the theme
+// and look the same on every phone. Two tones from the tokens in styles.css: the line in
+// --icon-line (the plate's ink), the fill in --icon-fill (a role colour), stroke --icon-stroke.
+
+type Glyph = { line: string; fill?: string };
+
+export const ICONS = {
+  left: { line: 'M15 5 7 12l8 7z', fill: 'M15 5 7 12l8 7z' },
+  right: { line: 'M9 5l8 7-8 7z', fill: 'M9 5l8 7-8 7z' },
+  up: { line: 'M5 15l7-8 7 8z', fill: 'M5 15l7-8 7 8z' },
+  pause: { line: 'M8.5 5.5v13M15.5 5.5v13' },
+  play: { line: 'M8 5.2v13.6L19 12z', fill: 'M8 5.2v13.6L19 12z' },
+  soundOn: { line: 'M4 9.5h3.5L12 6v12l-4.5-3.5H4zM15.5 9a4.2 4.2 0 0 1 0 6M18 6.8a7.4 7.4 0 0 1 0 10.4', fill: 'M4 9.5h3.5L12 6v12l-4.5-3.5H4z' },
+  soundOff: { line: 'M4 9.5h3.5L12 6v12l-4.5-3.5H4zM15.5 9.5l5 5M20.5 9.5l-5 5', fill: 'M4 9.5h3.5L12 6v12l-4.5-3.5H4z' },
+  help: { line: 'M12 3.5a8.5 8.5 0 1 0 0 17 8.5 8.5 0 0 0 0-17zM9.6 9.4a2.5 2.5 0 1 1 3.4 2.3c-.6.3-1 .8-1 1.5v.6M12 16.6v.2', fill: 'M12 3.5a8.5 8.5 0 1 0 0 17 8.5 8.5 0 0 0 0-17z' },
+  settings: { line: 'M12 8.8a3.2 3.2 0 1 0 0 6.4 3.2 3.2 0 0 0 0-6.4zM12 3v2.4M12 18.6V21M3 12h2.4M18.6 12H21M5.6 5.6l1.7 1.7M16.7 16.7l1.7 1.7M5.6 18.4l1.7-1.7M16.7 7.3l1.7-1.7', fill: 'M12 8.8a3.2 3.2 0 1 0 0 6.4 3.2 3.2 0 0 0 0-6.4z' },
+  gem: { line: 'M12 3.5 19.5 12 12 20.5 4.5 12zM4.5 12h15M12 3.5 9 12l3 8.5 3-8.5z', fill: 'M12 3.5 19.5 12 12 20.5 4.5 12z' },
+  heart: { line: 'M12 20s-7-4.4-8.8-8.6A5 5 0 0 1 12 7a5 5 0 0 1 8.8 4.4C19 15.6 12 20 12 20z', fill: 'M12 20s-7-4.4-8.8-8.6A5 5 0 0 1 12 7a5 5 0 0 1 8.8 4.4C19 15.6 12 20 12 20z' },
+  clock: { line: 'M12 3.5a8.5 8.5 0 1 0 0 17 8.5 8.5 0 0 0 0-17zM12 7.5V12l3 2', fill: 'M12 3.5a8.5 8.5 0 1 0 0 17 8.5 8.5 0 0 0 0-17z' },
+} 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/common/src/input.ts

@@ -0,0 +1,70 @@
+// Input verbs: one name per action, reached from the keyboard, a swipe or tap
+// on the play, a gamepad and (a setting) the on-screen buttons alike, so a
+// phone reaches every action a keyboard does and a check can drive any of them.
+
+export type Verb = 'left' | 'right' | 'hop' | 'pause' | 'confirm' | 'mute';
+
+/** KeyboardEvent.code → verb. Each verb's first code is declared in __FPX_KEYS__; on a phone the play's swipe
+ *  claims the steps and the hop (data-fpx-gesture in main.tsx), the HUD's icons the rest. */
+export const KEYS: Record<string, Verb> = {
+  ArrowLeft: 'left', KeyA: 'left',
+  ArrowRight: 'right', KeyD: 'right',
+  ArrowUp: 'hop', KeyW: 'hop',
+  Escape: 'pause', KeyP: 'pause',
+  Space: 'confirm', Enter: 'confirm', // confirm while playing is a hop too (session.ts)
+  KeyM: 'mute',
+};
+
+/** Standard-mapping gamepad button → verb: d-pad left/right/up, A, Start. */
+const PAD_BUTTONS: Record<number, Verb> = { 14: 'left', 15: 'right', 12: 'hop', 0: 'confirm', 9: 'pause' };
+const held = new Set<string>();
+/** CSS px of travel that makes a swipe; under it the release is a tap. */
+const SWIPE = 24;
+
+export function bindInput(stage: HTMLElement, press: (verb: Verb) => void): void {
+  addEventListener('keydown', (e) => {
+    const verb = KEYS[e.code];
+    if (!verb || e.repeat) return;
+    if (verb !== 'pause') e.preventDefault();
+    press(verb);
+  });
+  // The icon buttons and the on-screen buttons (a setting): 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();
+    press(verb);
+  });
+  // The play itself: a swipe left or right steps (at once, past SWIPE px), a swipe up or a tap hops. The finger
+  // stays on the play, and the screen a pad would take goes to the play (skill funpixel-mobile-ui, step 6).
+  let start: { x: number; y: number; id: number; used: boolean } | null = null;
+  stage.addEventListener('pointerdown', (e) => { start = { x: e.clientX, y: e.clientY, id: e.pointerId, used: false }; });
+  stage.addEventListener('pointermove', (e) => {
+    if (!start || start.used || e.pointerId !== start.id) return;
+    const dx = e.clientX - start.x, dy = e.clientY - start.y;
+    if (Math.max(Math.abs(dx), Math.abs(dy)) < SWIPE) return;
+    start.used = true;
+    if (Math.abs(dx) > Math.abs(dy)) press(dx < 0 ? 'left' : 'right'); else if (dy < 0) press('hop');
+  });
+  stage.addEventListener('pointerup', (e) => {
+    if (start && !start.used && e.pointerId === start.id) press('hop'); // a tap, not a swipe
+    start = null;
+  });
+  stage.addEventListener('pointercancel', () => { start = null; });
+  addEventListener('blur', () => held.clear());
+}
+
+/** Poll the first gamepad once a frame; a button or a stick past halfway presses once per push. */
+export function pollGamepad(press: (verb: Verb) => void): void {
+  const pad = typeof navigator.getGamepads === 'function' ? navigator.getGamepads()[0] : null;
+  if (!pad) return;
+  const down = new Set<string>();
+  for (const [i, verb] of Object.entries(PAD_BUTTONS)) if (pad.buttons[Number(i)]?.pressed) down.add(verb);
+  const x = pad.axes[0] ?? 0;
+  if (x < -0.5) down.add('left');
+  if (x > 0.5) down.add('right');
+  for (const v of down) if (!held.has(v)) press(v as Verb);
+  held.clear();
+  for (const v of down) held.add(v);
+}

package/templates/common/src/juice.ts

@@ -0,0 +1,92 @@
+// Juice: the numbers the renderer applies every frame, in track units (one
+// slot = 1). 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; easing for pops and settles.
+// The motion setting (store.motion; off under prefers-reduced-motion until the
+// player turns it on) is the off switch for shake and the edge vignette; the
+// local response a row declares (the struck body's flash, hitstop, its sound)
+// stays, so every action still answers. What each event gets is the table in
+// feel.ts; `funtools feel` reads juiceLevel() (exposed as state.juice) to time
+// each key event's answer (within ~100 ms) and to check a win answers bigger
+// than a point.
+
+import { store } from './store';
+
+export interface Particle { x: number; y: number; vx: number; vy: number; life: number }
+
+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 (track units); trauma lost per second. */
+  traumaCap: 0.6, shakeMax: 0.6, traumaDecay: 1.8,
+  /** Squash springs back at this rate per second; a flash fades at this rate. */
+  squashDecay: 3, flashDecay: 15,
+  /** 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,
+  /** Particles: at most this many alive, their speed (units/s) and life lost per second. */
+  maxParticles: 160, particleSpeed: 2.5, particleFade: 2,
+} as const;
+
+/** Easing for pops, settles and screen moves: t in 0–1. */
+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 = {
+  squash: 0,
+  /** 0–1: how white the struck body is this frame. */
+  flash: 0,
+  /** 0–1: the edge vignette (the player hurt, a round lost; never the whole screen); off with motion off. */
+  vignette: 0,
+  trauma: 0,
+  /** Seconds the sim's bodies stay frozen (hitstop). */
+  freeze: 0,
+  particles: [] as Particle[],
+};
+
+export const squash = (amount = 0.35): 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 function burst(x: number, y: number, count = 12): void {
+  const n = store.motion ? count : Math.ceil(count / 2);
+  for (let i = 0; i < n; i++) {
+    const a = (i / n) * Math.PI * 2, speed = TUNE.particleSpeed * (0.6 + Math.random() * 0.8);
+    juice.particles.push({ x, y, vx: Math.cos(a) * speed, vy: Math.sin(a) * speed, life: 1 });
+  }
+  juice.particles.splice(0, Math.max(0, juice.particles.length - TUNE.maxParticles));
+}
+
+export function stepJuice(dt: number): void {
+  juice.squash = Math.max(0, 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);
+  for (const p of juice.particles) {
+    p.x += p.vx * dt;
+    p.y += p.vy * dt;
+    p.life -= dt * TUNE.particleFade;
+  }
+  juice.particles = juice.particles.filter((p) => p.life > 0);
+}
+
+/** The player's scale this frame: wide and flat on a squash, springing back. */
+export const squashScale = () => ({ x: 1 + juice.squash, y: 1 - juice.squash * 0.6 });
+
+/** The camera's offset this frame, in track units; 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, for the state (state.juice): `funtools feel` times each key event's answer by it. */
+export const juiceLevel = () => ({
+  trauma: juice.trauma, flash: juice.flash, squash: juice.squash, vignette: juice.vignette,
+  freeze: juice.freeze, particles: juice.particles.length,
+});