@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/src/levels.ts

@@ -0,0 +1,43 @@
+// The level list, as data, for a game that has more than one level, chapter or stage: what each is
+// called, what it takes to open, and where the player got to (kept in the save, so a reload returns
+// there). A level select reads it, `funtools reach` reads each level's `file` (a tile grid or a 3D level
+// spec), and `funtools check` warns when the GDD plans several levels and the game keeps no list. The
+// starter's round is one level; add yours here. A won round completes the level being played. Yours to
+// change or drop.
+
+import { progress } from './save';
+import { onScreen } from './store';
+
+export interface Level {
+  id: string;
+  name: string;
+  /** Seconds a good run takes (a par for stars); optional. */
+  par?: number;
+  /** The level's data for reach (design/levels/<id>.json); optional. */
+  file?: string;
+}
+
+// One level a line between the fp:union lines: lanes building levels at once each add their own line, and
+// `funtools lanes sync` keeps every lane's line (a lane may change only the lines inside the block).
+export const LEVELS: Level[] = [
+  // fp:union levels
+  { id: 'round-1', name: 'The first round', par: 30 },
+  // fp:union end
+];
+
+/** A level opens once every one before it is done (index ≤ the furthest reached). */
+export const isOpen = (i: number): boolean => i <= (Number(progress.data.reached) || 0);
+export const isDone = (id: string): boolean => (progress.data.done as string[]).includes(id);
+
+/** Mark a level done and open the next; saved at once. */
+export function complete(id: string): void {
+  const i = LEVELS.findIndex((l) => l.id === id);
+  if (i < 0) return;
+  const done = isDone(id) ? (progress.data.done as string[]) : [...(progress.data.done as string[]), id];
+  progress.update({ done, reached: Math.max(Number(progress.data.reached) || 0, Math.min(i + 1, LEVELS.length - 1)) });
+}
+
+/** The level being played (an index into LEVELS); a level select sets it before Play. */
+export let current = 0;
+export const choose = (i: number): void => { current = Math.max(0, Math.min(i, LEVELS.length - 1)); };
+onScreen((next) => { if (next === 'won') complete(LEVELS[current].id); });

package/templates/common/src/living.ts

@@ -0,0 +1,91 @@
+// The living layer: optional motion between events for actors whose role moves (the design
+// note's ## Actors Motion column; `scene --motion` judges each actor by it). Breathe at rest, a step bob, tilt and lean
+// tied to speed, a facing flip, a blink, and a squash on land or hit HELD at its peak for a few
+// frames so a capture can see it. Each actor's motion is data with tuned ranges: a value outside
+// one throws, naming the field, so no one ships sine soup. Engine-free: the renderer applies the
+// pose (scale, rotation, y offset in body heights, flip, blink) to its sprite or mesh.
+
+/** Each dial, its tuned range and default (research 16: breathe 3% at 0.5 Hz, bob 8%, squash ≥ 20%). */
+export const RANGES = {
+  breathe: [0, 0.06, 0.03], breatheHz: [0.2, 1.2, 0.5],
+  bob: [0, 0.12, 0.08], tilt: [0, 12, 8], lean: [0, 15, 8], stepHz: [1, 6, 3],
+  squash: [0.2, 0.45, 0.25], holdFrames: [3, 6, 4], blinkEvery: [1.5, 6, 3], blinkMs: [60, 160, 100],
+} as const;
+export type Motion = { -readonly [K in keyof typeof RANGES]: number };
+
+/** A full spec from a partial one; throws `living: <actor>.<field> …` on anything out of range. */
+export function motion(actor: string, spec: Partial<Motion> = {}): Motion {
+  const out = {} as Motion;
+  for (const [k, [lo, hi, def]] of Object.entries(RANGES) as Array<[keyof Motion, readonly [number, number, number]]>) {
+    const v = spec[k] ?? def;
+    if (!Number.isFinite(v) || v < lo || v > hi) throw new Error(`living: ${actor}.${k} is ${v}; it must be ${lo}–${hi}`);
+    out[k] = v;
+  }
+  return out;
+}
+
+/** The roles' starting points: a hero breathes and leans, an enemy bobs harder, a pickup glints. */
+export const ROLE: Record<'hero' | 'enemy' | 'pickup', Partial<Motion>> = {
+  hero: {},
+  enemy: { bob: 0.1, tilt: 10, breathe: 0.04 },
+  pickup: { breathe: 0.06, breatheHz: 1, lean: 0, tilt: 0 },
+};
+
+export interface Pose { scaleX: number; scaleY: number; rotation: number; offsetY: number; blink: boolean; flip: boolean }
+
+const FRAME = 1 / 60;
+
+export class Living {
+  readonly m: Motion;
+  private t: number;
+  private step = 0;
+  private squashLeft = 0;
+  private squashAmount = 0;
+  private spring = 0;
+  private nextBlink: number;
+  private blinkLeft = 0;
+  private facing = 1;
+
+  constructor(actor: string, spec: Partial<Motion> = {}) {
+    this.m = motion(actor, spec);
+    // A phase of its own, from the name, so a crowd never breathes in step.
+    let h = 0;
+    for (const c of actor) h = (h * 31 + c.charCodeAt(0)) % 997;
+    this.t = h / 97;
+    this.nextBlink = this.m.blinkEvery * (0.5 + (h % 10) / 10);
+  }
+
+  /** Landing or being hit: squash by `amount` (default the spec's), held, then a spring back. */
+  squash(amount = this.m.squash): void {
+    this.squashAmount = Math.max(RANGES.squash[0], Math.min(RANGES.squash[1], amount));
+    this.squashLeft = this.m.holdFrames * FRAME;
+  }
+
+  /** One frame. `speed` is the share of top speed (−1…1, its sign the heading); returns the pose. */
+  update(dt: number, speed = 0): Pose {
+    const m = this.m, s = Math.max(-1, Math.min(1, speed)), moving = Math.abs(s) > 0.05;
+    this.t += dt;
+    if (moving) { this.step += dt * m.stepHz * Math.abs(s) * Math.PI; this.facing = Math.sign(s); }
+    const stepWave = Math.sin(this.step);
+    const breathe = moving ? 0 : m.breathe * Math.sin(this.t * m.breatheHz * Math.PI * 2);
+    let sx = 1 - breathe * 0.5, sy = 1 + breathe;
+    if (this.squashLeft > 0) {
+      this.squashLeft -= dt;
+      this.spring = this.squashAmount; // the peak, held so a capture sees it
+    } else {
+      this.spring = Math.abs(this.spring) < 0.002 ? 0 : this.spring * Math.exp(-13 * dt) * Math.cos(20 * dt);
+    }
+    sx *= 1 + this.spring;
+    sy *= 1 - this.spring * 0.8;
+    this.blinkLeft -= dt;
+    if ((this.nextBlink -= dt) <= 0) { this.blinkLeft = m.blinkMs / 1000; this.nextBlink = m.blinkEvery * (0.7 + Math.random() * 0.6); }
+    const rad = Math.PI / 180;
+    return {
+      scaleX: sx, scaleY: sy,
+      rotation: (moving ? m.lean * s + m.tilt * stepWave * Math.abs(s) : 0) * rad,
+      offsetY: moving ? -m.bob * Math.abs(stepWave) * Math.abs(s) : 0,
+      blink: this.blinkLeft > 0,
+      flip: this.facing < 0,
+    };
+  }
+}

package/templates/common/src/look.json

@@ -0,0 +1,19 @@
+{
+  "bg": "#101018",
+  "ink": "#f4f1ea",
+  "primary": "#4fd1c5",
+  "accent": "#f6ad55",
+  "harm": "#ff6b6b",
+  "button-ink": "#101018",
+  "plate": "rgba(16, 16, 24, 0.82)",
+  "plate-edge": "transparent",
+  "plate-ink": "#f4f1ea",
+  "plate-radius": "12px",
+  "plate-shadow": "none",
+  "ui-stroke": "2px",
+  "icon-line": "currentColor",
+  "icon-fill": "#f6ad55",
+  "icon-stroke": 2,
+  "font-display": "system-ui, sans-serif",
+  "font-body": "system-ui, sans-serif"
+}

package/templates/common/src/look.ts

@@ -0,0 +1,54 @@
+// The HUD and screen look as one value: src/look.json holds the UI role tokens styles.css reads (bg, ink,
+// plate, plate-ink, accent, font-display …), and this applies it to :root at load, before the first
+// paint. Lenient on load: a token the page cannot use keeps the stylesheet's value and logs ONE line,
+// "[frame] look fallback: …", which `funtools check` reads; a declared face that never loads says so too.
+// Change the look with `npx @funpixel/tools look set plate-ink=#3a2618` (strict: it refuses an unknown
+// token or a bad value, and proposes a readable ink when a pair fails contrast), or edit look.json and run
+// `look report`. Delete look.json and the stylesheet's values stand. Yours to change or drop.
+
+import { applyGrade, gradeOf } from './grade';
+
+const files = import.meta.glob('./look.json', { eager: true, import: 'default' }) as Record<string, Record<string, string | number>>;
+export const look: Record<string, string | number> = files['./look.json'] ?? {};
+
+type Kind = 'colour' | 'paint' | 'length' | 'shadow' | 'number' | 'font';
+const KINDS: Record<string, Kind> = {
+  bg: 'colour', ink: 'colour', primary: 'colour', accent: 'colour', harm: 'colour', 'button-ink': 'colour',
+  plate: 'paint', 'plate-edge': 'colour', 'plate-ink': 'colour', 'plate-radius': 'length', 'plate-shadow': 'shadow',
+  'ui-stroke': 'length', 'icon-line': 'colour', 'icon-fill': 'colour', 'icon-stroke': 'number',
+  'font-display': 'font', 'font-body': 'font',
+  'sky-top': 'colour', 'sky-horizon': 'colour', ground: 'colour', 'ground-2': 'colour', stone: 'colour',
+  hero: 'colour', 'hero-accent': 'colour', 'key-light': 'colour',
+};
+const PROP: Record<Kind, string> = { colour: 'color', paint: 'background', length: 'width', shadow: 'box-shadow', number: 'opacity', font: 'font-family' };
+const GENERIC = /^(system-ui|ui-[a-z-]+|-apple-system|sans-serif|serif|monospace|cursive|fantasy)$/i;
+
+/** One line per value that fell back: what the checks read. */
+export const fallbacks: string[] = [];
+const fallback = (what: string) => { const line = `[frame] look fallback: ${what}`; fallbacks.push(line); console.warn(line); };
+
+export function applyLook(root: HTMLElement = document.documentElement): void {
+  for (const [k, v] of Object.entries(look)) {
+    if (k.startsWith('$')) continue;
+    if (k === 'light' && v && typeof v === 'object') continue; // the world's light block: the 3D starter's light-math.ts and grade.ts read it
+    const kind = KINDS[k];
+    if (!kind && !k.startsWith('x-')) { fallback(`${k}: not a token the stylesheet reads; ignored`); continue; }
+    const ok = kind === 'number' ? typeof v === 'number' && v >= 0 : typeof v === 'string' && v.trim() !== '' && (!kind || /^var\(--[a-z0-9-]+\)$/.test(v.trim()) || CSS.supports(PROP[kind], v));
+    if (!ok) { fallback(`${k}: ${JSON.stringify(v)} is not a ${kind ?? 'value'}; the stylesheet's value renders`); continue; }
+    root.style.setProperty(`--${k}`, String(v));
+  }
+  // A face named in the look that never loads renders as the next one in its stack: say so once.
+  if (document.fonts?.ready) void document.fonts.ready.then(() => {
+    for (const k of ['font-display', 'font-body']) {
+      const stack = typeof look[k] === 'string' ? String(look[k]) : '';
+      const family = stack.split(',')[0]?.trim().replace(/^['"]|['"]$/g, '');
+      if (!family || GENERIC.test(family)) continue;
+      const faces = [...document.fonts].filter((f) => f.family.replace(/^['"]|['"]$/g, '') === family);
+      if (!faces.length) fallback(`${k}: no @font-face declares "${family}"; the next face in the stack renders`);
+      else if (faces.every((f) => f.status === 'error')) fallback(`${k}: "${family}" failed to load; the next face in the stack renders`);
+    }
+  });
+}
+
+/** The grade of the "light" block straight onto the stage (grade.ts; the Pixi starter's one call; neutral without a block). */
+export const gradeFromLook = (stage: HTMLElement): void => applyGrade(stage, gradeOf(typeof look.light === 'object' ? (look.light as unknown as Record<string, unknown>) : undefined));

package/templates/common/src/main.tsx

@@ -0,0 +1,31 @@
+import { render } from 'preact';
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { Hud } from './hud';
+import { Screens } from './screens';
+import { startSplash } from './splash';
+import './platform'; // pause when hidden, storage that never throws, first-tap fullscreen (yours to change)
+import './frame'; // the safe HUD band: --band-* and __FPX_FRAME__ (yours to change)
+import './levels'; // the level list and where the player got to (saved)
+import { applyLook } from './look'; // src/look.json onto :root, before the first paint
+
+function App() {
+  const stage = useRef<HTMLDivElement>(null), [failed, setFailed] = useState(false);
+  useEffect(() => {
+    // The engine is its own chunk, fetched behind the title so the title paints first; a failed fetch (a
+    // dropped phone connection) offers a retry card, never a blank page.
+    const host = stage.current;
+    if (host) import('./game').then((m) => m.startGame(host)).catch((e) => { console.error('the game did not load', e); setFailed(true); });
+  }, []);
+  return (
+    <>
+      <div ref={stage} class="stage" data-fpx-gesture="ArrowLeft ArrowRight ArrowUp" />
+      <Hud />
+      <Screens title={document.title} />
+      {failed && <div class="load-failed plate" role="alert"><p>The game did not load.</p><button class="primary" onClick={() => location.reload()}>Try again</button></div>}
+    </>
+  );
+}
+
+applyLook();
+startSplash();
+render(<App />, document.getElementById('app')!);

package/templates/common/src/markers.ts

@@ -0,0 +1,60 @@
+// World-space HUD, engine-free: DOM markers pinned to things in the scene (a
+// bar over an enemy, a name, an intent icon) that hide when their thing is off
+// screen, waypoints that clamp to the screen edge as an arrow with the
+// distance, and a centre reticle that flashes on a hit. world-hud.ts gives the
+// engine's projection; pin.ts places. Options: use them or delete the files
+// (skill funpixel-mobile-ui, references/hud-genres.md).
+
+import { distanceLabel, place } from './pin';
+
+export interface Marker<T = unknown> { el: HTMLElement; target: T; waypoint: boolean }
+/** The engine's answer for one target: normalised device coordinates, in front of the camera, distance. */
+export type Project<T> = (target: T) => { x: number; y: number; front: boolean; distance: number };
+
+const markers: Marker<any>[] = [];
+
+/** Pin `content` over `target`. A waypoint stays on screen, clamped to the edge, with its distance. */
+export function pin<T>(target: T, content: string | HTMLElement, opts: { waypoint?: boolean; className?: string } = {}): Marker<T> {
+  const el = typeof content === 'string' ? Object.assign(document.createElement('div'), { textContent: content }) : content;
+  el.classList.add('kit-marker');
+  if (opts.className) el.classList.add(opts.className);
+  document.body.appendChild(el);
+  const m = { el, target, waypoint: !!opts.waypoint };
+  markers.push(m);
+  return m;
+}
+
+export function unpin(m: Marker<any>): void {
+  m.el.remove();
+  const i = markers.indexOf(m);
+  if (i >= 0) markers.splice(i, 1);
+}
+
+/** Move every marker; call once a frame after drawing. `margin` keeps the safe area and HUD bands clear. */
+export function drawMarkers<T>(project: Project<T>, canvas: HTMLElement, margin = 48): void {
+  const r = canvas.getBoundingClientRect();
+  for (const m of markers as Marker<T>[]) {
+    const p = project(m.target);
+    const at = place(p, r.width, r.height, margin, m.waypoint);
+    m.el.style.display = at.visible ? '' : 'none';
+    if (!at.visible) continue;
+    // Nearer reads bigger, never under 60%: a far enemy's bar must still be legible.
+    const scale = Math.max(0.6, Math.min(1, 12 / Math.max(p.distance, 1e-6)));
+    m.el.style.transform = `translate(${r.left + at.x}px, ${r.top + at.y}px) translate(-50%, -100%) scale(${m.waypoint ? 1 : scale})`;
+    m.el.classList.toggle('kit-edge', at.onEdge);
+    m.el.style.setProperty('--angle', `${at.angle}rad`);
+    if (m.waypoint) m.el.dataset.distance = distanceLabel(p.distance);
+  }
+}
+
+/** A centre reticle; `hit()` flashes the hit cross, `over(true)` tints it over a target. */
+export function reticle(): { el: HTMLElement; hit(): void; over(on: boolean): void } {
+  const el = document.createElement('div');
+  el.className = 'kit-reticle';
+  document.body.appendChild(el);
+  return {
+    el,
+    hit() { el.classList.remove('kit-hit'); void el.offsetWidth; el.classList.add('kit-hit'); },
+    over(on) { el.classList.toggle('kit-over', on); },
+  };
+}

package/templates/common/src/motion-sample.ts

@@ -0,0 +1,71 @@
+// A gait (motion.ts) played: the stride phase advanced by DISTANCE walked (a planted foot never
+// slides), the pose at that phase, and the rate a rigged clip plays at. Engine-free; the renderer
+// applies the pose. Three.js, a rigged clip:
+//   const { gait: g } = gait('walk');
+//   action.timeScale = clipTimeScale(g, speedMps / heightM).scale;   // feet keep up with the body
+// Three.js or Pixi, parts driven in code:
+//   phase = advance(g, phase, distanceMovedThisFrame / height, dt);
+//   const p = sampleGait(g, phase);  hips.position.y = base + p.y * height;  thighL.rotation.x = …
+
+import { nearestGait, type Gait, type GaitName, type MotionWarning } from './motion';
+
+export interface LegPose { x: number; lift: number; planted: boolean }
+export interface GaitPose {
+  /** Bob and side shift, in body heights; lean, hip and chest turn, arms, in radians. */
+  y: number; x: number; lean: number; hipYaw: number; chestYaw: number; arms: [number, number];
+  /** Each foot fore (+) or aft (−) of the hips in body heights, its lift, and whether it is planted. */
+  legs: LegPose[];
+  /** Flyers: −1 (down) … 1 (up); 0.2 held while gliding. */
+  wing: number;
+  crouch: number;
+}
+
+/** Each leg's offset in the cycle: a biped's alternate; a quadruped's walk lands hind, fore, hind, fore. */
+const LEGS = { biped: [0, 0.5], quadruped: [0, 0.5, 0.25, 0.75], flyer: [] } as const;
+const TAU = Math.PI * 2;
+const ease = (s: number) => 0.5 - 0.5 * Math.cos(Math.PI * s); // never a triangle wave
+const frac = (v: number) => v - Math.floor(v);
+
+/** The next stride phase (0…1): by distance for legs (in body heights), by time for a wing beat. */
+export function advance(g: Gait, phase: number, distanceBh: number, dt: number): number {
+  return frac(phase + (g.kind === 'flyer' ? g.flapHz * dt : Math.abs(distanceBh) / g.stride));
+}
+
+/** The pose at a stride phase. */
+export function sampleGait(g: Gait, phase: number): GaitPose {
+  const ph = frac(phase);
+  if (g.kind === 'flyer') {
+    const flapping = ph < 1 - g.glide;
+    const w = flapping ? Math.cos((TAU * ph) / Math.max(0.2, 1 - g.glide)) : 0.2;
+    return { y: g.bob * -w * 0.5, x: 0, lean: g.lean, hipYaw: 0, chestYaw: 0, arms: [0, 0], legs: [], wing: w, crouch: 0 };
+  }
+  // The limp: the bad leg's stance is shorter, and the body dips deeper while it carries the weight.
+  const bad = g.limpSide === 'left' ? 0 : 1;
+  const legs = LEGS[g.kind].map((o, i): LegPose => {
+    const stance = g.stance * (i % 2 === bad && g.kind === 'biped' ? 1 - g.limp * 0.3 : 1);
+    const lp = frac(ph + o);
+    const reach = (stance * g.stride) / 2;
+    if (lp < stance) return { x: reach - (2 * reach * lp) / stance, lift: 0, planted: true };
+    const s = (lp - stance) / (1 - stance);
+    return { x: -reach + 2 * reach * ease(s), lift: g.footLift * Math.sin(Math.PI * s), planted: false };
+  });
+  const dip = g.kind === 'biped' ? g.limp * g.bob * Math.max(0, Math.sin(TAU * (ph - (bad ? 0.5 : 0)))) : 0;
+  const yaw = g.hipYaw * Math.sin(TAU * ph);
+  const lag = 0.05; // the arms follow the legs a beat late (secondary motion)
+  return {
+    y: -0.5 * g.bob * Math.cos(2 * TAU * ph) - dip - g.crouch,
+    x: g.sway * Math.sin(TAU * ph),
+    lean: g.lean, hipYaw: yaw, chestYaw: -0.6 * yaw,
+    arms: [g.armSwing * Math.sin(TAU * (ph + 0.5 - lag)), g.armSwing * Math.sin(TAU * (ph - lag))],
+    legs, wing: 0, crouch: g.crouch,
+  };
+}
+
+/** A clip's playback rate so the feet keep up, held at 0.6–1.6; past that, a warning names the preset to switch to. */
+export function clipTimeScale(g: Gait, speedBh: number, clipSpeedBh = g.designSpeed): { scale: number; warning?: MotionWarning; switchTo?: GaitName } {
+  const r = Math.abs(speedBh) / Math.max(1e-6, clipSpeedBh);
+  const scale = Math.min(1.6, Math.max(0.6, r));
+  if (r === scale || speedBh === 0) return { scale: speedBh === 0 ? 1 : scale };
+  const switchTo = nearestGait(Math.abs(speedBh), g.kind);
+  return { scale, switchTo, warning: { dial: 'designSpeed', value: clipSpeedBh, range: [0.6 * clipSpeedBh, 1.6 * clipSpeedBh], why: `moving at ${Math.abs(speedBh).toFixed(2)} bh/s: the feet ${r < 0.6 ? 'moonwalk' : 'scramble'}; cross-fade to ${switchTo}` } };
+}

package/templates/common/src/motion.ts

@@ -0,0 +1,92 @@
+// Gaits as data: a preset a game picks (walk, run, sneak, carry, limp, old, child, quadruped, flyer)
+// and a few dials it tunes, each inside the range where a body still reads as a body. Engine-free:
+// motion-sample.ts turns a gait and a stride phase into a pose (bob, sway, lean, hip and chest turn,
+// arm swing, each foot's place and lift, a wing beat); the renderer applies it to parts, bones or a
+// sheet's frame rate. Units are BODY HEIGHTS (bh), so one table serves pixels and metres: a 1.75 m
+// person walking 1.4 m/s moves 0.8 bh/s. A dial out of range is REFUSED while you build (the dev
+// server, or `strict: true`): a number you tuned that silently became another is a lost intent. In a
+// shipped build it is held at the edge and named in `warnings`, so a player never meets a crash
+// (skill funpixel-game-feel, motion.md).
+
+export type GaitKind = 'biped' | 'quadruped' | 'flyer';
+export interface MotionWarning { dial: string; value: number; range?: readonly [number, number]; why: string }
+
+/** Each dial: its range and what happens past it. */
+export const GAIT_DIALS = {
+  designSpeed: [0.2, 4, 'body heights a second the stride was tuned for; feet slide when the body moves much faster or slower'],
+  stride: [0.3, 2.2, 'body heights covered by one full stride (two steps)'],
+  stance: [0.25, 0.75, 'share of the cycle a foot is planted: above 0.5 walks, below 0.5 runs (both feet off the ground)'],
+  bob: [0, 0.06, 'rise and fall, share of height, twice a stride and lowest at contact; more reads as bouncing'],
+  footLift: [0, 0.25, 'how high a swinging foot rises, share of height'],
+  lean: [-0.2, 0.35, 'radians forward into speed or a load (negative leans back under a load held in front)'],
+  armSwing: [0, 0.8, 'radians of shoulder swing opposite the legs; above ~0.8 the hands crest the shoulder and flail'],
+  hipYaw: [0, 0.3, 'radians the hips turn toward the swinging leg; the chest turns back about 60% of it'],
+  sway: [0, 0.04, 'side shift over the planted foot, share of height'],
+  crouch: [0, 0.35, 'hips lowered, share of height; a deep crouch belongs to a slow gait'],
+  limp: [0, 0.6, 'asymmetry: the bad leg plants shorter and the body dips deeper on it'],
+  flapHz: [0, 12, 'wing beats a second (flyers): small birds 8–12, gulls 3–4, big wings 1–2'],
+  glide: [0, 0.8, 'share of each beat cycle held with wings spread (flyers)'],
+} as const;
+export type GaitDial = keyof typeof GAIT_DIALS;
+export type Gait = { kind: GaitKind; limpSide: 'left' | 'right' } & { -readonly [K in GaitDial]: number };
+
+const base = { stance: 0.62, bob: 0.03, footLift: 0.06, lean: 0.03, armSwing: 0.35, hipYaw: 0.12, sway: 0.015, crouch: 0, limp: 0, flapHz: 0, glide: 0 };
+/** The presets: starting points to tune, never finished motion. Numbers from reference walks at 1.75 m. */
+export const GAITS = {
+  walk: { kind: 'biped', designSpeed: 0.8, stride: 0.8, ...base },
+  run: { kind: 'biped', designSpeed: 2.3, stride: 1.6, ...base, stance: 0.38, bob: 0.045, footLift: 0.16, lean: 0.15, armSwing: 0.6, hipYaw: 0.18, sway: 0.01, crouch: 0.04 },
+  sneak: { kind: 'biped', designSpeed: 0.4, stride: 0.6, ...base, stance: 0.72, bob: 0.012, footLift: 0.05, lean: 0.12, armSwing: 0.12, hipYaw: 0.06, sway: 0.01, crouch: 0.25 },
+  carry: { kind: 'biped', designSpeed: 0.6, stride: 0.65, ...base, stance: 0.66, bob: 0.025, footLift: 0.05, lean: 0.1, armSwing: 0.05, hipYaw: 0.08, sway: 0.025 },
+  limp: { kind: 'biped', designSpeed: 0.5, stride: 0.6, ...base, stance: 0.64, bob: 0.035, footLift: 0.05, lean: 0.05, armSwing: 0.25, hipYaw: 0.1, sway: 0.03, limp: 0.4 },
+  old: { kind: 'biped', designSpeed: 0.5, stride: 0.55, ...base, stance: 0.68, bob: 0.015, footLift: 0.035, lean: 0.12, armSwing: 0.18, hipYaw: 0.06, sway: 0.02, crouch: 0.06, limp: 0.05 },
+  child: { kind: 'biped', designSpeed: 1.0, stride: 0.85, ...base, stance: 0.58, bob: 0.045, footLift: 0.09, lean: 0.04, armSwing: 0.5, hipYaw: 0.15, sway: 0.02 },
+  // A four-legged creature: height = shoulder height; legs step in the walk's lateral sequence.
+  quadruped: { kind: 'quadruped', designSpeed: 1.2, stride: 1.0, ...base, stance: 0.6, bob: 0.02, footLift: 0.08, lean: 0, armSwing: 0, hipYaw: 0.06, sway: 0.01 },
+  // A flyer: the cycle is a wing beat, driven by time, not distance.
+  flyer: { kind: 'flyer', designSpeed: 3, stride: 1, ...base, stance: 0.5, bob: 0.03, footLift: 0, lean: 0.1, armSwing: 0, hipYaw: 0, sway: 0.01, flapHz: 6, glide: 0.3 },
+} as const satisfies Record<string, Omit<Gait, 'limpSide'>>;
+export type GaitName = keyof typeof GAITS;
+
+/**
+ * A gait from a preset and the dials a game tunes. Out-of-range dials are held at the edge and named
+ * in `warnings`, along with pairings that read wrong (a deep crouch at speed, a run's stance at a walk's pace).
+ */
+export function gait(preset: GaitName, tune: Partial<Gait> = {}, opts: { strict?: boolean } = {}): { gait: Gait; warnings: MotionWarning[] } {
+  const raw = { limpSide: 'left' as const, ...GAITS[preset], ...tune } as Gait;
+  const warnings = checkGait(raw);
+  // Refuse over clamp while building: the dev server (Vite's import.meta.env.DEV), or asked for.
+  const strict = opts.strict ?? (import.meta as { env?: { DEV?: boolean } }).env?.DEV === true;
+  const out = warnings.filter((w) => w.range);
+  if (strict && out.length) throw new RangeError(`gait "${preset}": ${out.map((w) => `${w.dial} ${w.value} is outside ${w.range![0]}–${w.range![1]} (${GAIT_DIALS[w.dial as GaitDial][2]})`).join('; ')}`);
+  const g = { ...raw };
+  for (const [k, [lo, hi]] of Object.entries(GAIT_DIALS) as Array<[GaitDial, readonly [number, number, string]]>) {
+    const v = Number.isFinite(g[k]) ? g[k] : (GAITS[preset] as Record<GaitDial, number>)[k];
+    g[k] = Math.min(hi, Math.max(lo, v));
+  }
+  return { gait: g, warnings };
+}
+
+/** What reads wrong in a gait, by dial; never throws. */
+export function checkGait(g: Partial<Gait>): MotionWarning[] {
+  const out: MotionWarning[] = [];
+  for (const [k, [lo, hi, why]] of Object.entries(GAIT_DIALS) as Array<[GaitDial, readonly [number, number, string]]>) {
+    const v = g[k];
+    if (v === undefined) continue;
+    if (!Number.isFinite(v) || v < lo || v > hi) out.push({ dial: k, value: v, range: [lo, hi], why: `held at ${Number.isFinite(v) ? (v < lo ? lo : hi) : 'the preset'}: ${why}` });
+  }
+  const speed = g.designSpeed ?? 1, kind = g.kind ?? 'biped';
+  if ((g.crouch ?? 0) > 0.15 && speed > 1) out.push({ dial: 'crouch', value: g.crouch!, why: 'a deep crouch at speed reads as a scuttle: pair it with a designSpeed under 1' });
+  if (kind === 'biped' && (g.stance ?? 0.6) < 0.5 && speed < 1.2) out.push({ dial: 'stance', value: g.stance!, why: 'a run\'s stance at a walk\'s pace reads as jogging on the spot' });
+  if (kind !== 'flyer' && g.stride) {
+    const steps = (2 * speed) / g.stride;
+    if (steps < 1 || steps > 4.5) out.push({ dial: 'stride', value: g.stride, why: `${steps.toFixed(1)} steps a second at designSpeed: people step 1.5–3.5 a second; change the stride, not the clock` });
+  }
+  if (kind === 'flyer' && !(g.flapHz! > 0)) out.push({ dial: 'flapHz', value: g.flapHz ?? 0, why: 'a flyer with no wing beat glides like a stone' });
+  return out;
+}
+
+/** The preset whose designSpeed is nearest a speed in body heights a second (same kind). */
+export function nearestGait(speedBh: number, kind: GaitKind = 'biped'): GaitName {
+  const names = (Object.keys(GAITS) as GaitName[]).filter((n) => GAITS[n].kind === kind);
+  return names.reduce((a, b) => (Math.abs(GAITS[b].designSpeed - speedBh) < Math.abs(GAITS[a].designSpeed - speedBh) ? b : a));
+}

package/templates/common/src/pin.ts

@@ -0,0 +1,32 @@
+// Where a world-space marker goes on screen: a bar over an enemy, a name, a
+// waypoint. The engine turns the thing's position into normalised device
+// coordinates (x, y in -1…1, and whether it is in front of the camera); this
+// places the marker, and when the thing is off screen (or behind) either hides
+// it or clamps it to the screen edge inside the safe margin with the angle an
+// arrow should point. Pure, no engine (test/pin.test.ts); three/src/world-hud.ts
+// and pixi/src/world-hud.ts use it.
+
+export interface Placed { x: number; y: number; visible: boolean; onEdge: boolean; angle: number }
+
+/**
+ * `ndc` from the engine, `w`/`h` the canvas in CSS px, `margin` the inset to keep clear (the safe
+ * area plus the HUD bands). `clamp`: keep an off-screen goal on the edge as an arrow (a waypoint);
+ * otherwise an off-screen thing's marker hides (an enemy bar).
+ */
+export function place(ndc: { x: number; y: number; front: boolean }, w: number, h: number, margin = 24, clamp = false): Placed {
+  // Behind the camera the projection mirrors: flip it so the arrow points the right way.
+  let nx = ndc.front ? ndc.x : -ndc.x, ny = ndc.front ? ndc.y : -ndc.y;
+  const inside = ndc.front && Math.abs(nx) <= 1 && Math.abs(ny) <= 1;
+  const toPx = (u: number, v: number) => ({ x: ((u + 1) / 2) * w, y: ((1 - v) / 2) * h });
+  if (inside) return { ...toPx(nx, ny), visible: true, onEdge: false, angle: 0 };
+  if (!clamp) return { ...toPx(nx, ny), visible: false, onEdge: false, angle: 0 };
+  // Scale the direction until it touches the margin box: the marker sits on the edge toward the goal.
+  if (!ndc.front && nx === 0 && ny === 0) ny = -1;
+  const hx = Math.max(1, w / 2 - margin), hy = Math.max(1, h / 2 - margin);
+  const dx = nx * (w / 2), dy = -ny * (h / 2);
+  const k = Math.min(hx / Math.max(Math.abs(dx), 1e-6), hy / Math.max(Math.abs(dy), 1e-6));
+  return { x: w / 2 + dx * k, y: h / 2 + dy * k, visible: true, onEdge: true, angle: Math.atan2(dy, dx) };
+}
+
+/** Metres (or world units) as the waypoint's label: "12 m", "1.4 km". */
+export const distanceLabel = (d: number): string => (d >= 1000 ? `${(d / 1000).toFixed(1)} km` : `${Math.round(d)} m`);

package/templates/common/src/platform.ts

@@ -0,0 +1,67 @@
+// Platform seams, ready to use and yours to change or drop (none is required): the game pausing and going
+// quiet while its tab is hidden or a host holds it, progress flushed when the page goes (save.ts), fullscreen
+// with the orientation lock on the first tap on a phone, a haptic pulse, and which input the player is using
+// (on-screen controls show only for touch: the owner, 1 Oct, "no need for mobile controls on desktop").
+// The owner's web games carry the same seams (one has platform.ts, save.ts, fullscreen.ts,
+// portal.ts; its platform test boots with storage that throws). What a check reads is the outcome: progress
+// survives a reload, the game pauses when hidden, the page boots where storage is blocked.
+
+import { fullscreen, haptics, orientation } from '@funpixel/sdk/device';
+import { go, store } from './store';
+import { audio } from './sound';
+import { progress } from './save';
+
+/** How the game is held on a phone (funpixel.json metadata.orientation); locked on the first tap where the browser allows it. */
+export const HOLD = '{{orientation}}' as 'portrait' | 'landscape';
+
+const holds = new Set<string>();
+/** Pause and silence the game for a reason (the tab hidden, a host's ad or menu); sound returns when every reason is released. */
+export function hold(reason: string): void {
+  if (!holds.size) {
+    if (store.screen === 'playing') go('paused');
+    void audio.ctx.suspend().catch(() => {});
+  }
+  holds.add(reason);
+}
+/** Release one reason; the game stays paused (the player resumes it), only the sound comes back. */
+export function release(reason: string): void {
+  if (!holds.delete(reason) || holds.size) return;
+  void audio.ctx.resume().catch(() => {});
+}
+export const held = (): boolean => holds.size > 0;
+
+/** A short pulse on phones that have one; off with the motion setting. */
+export const buzz = (ms: number | number[] = 12): void => { if (store.motion) haptics.vibrate(ms); };
+
+/** The input the player is using now: 'touch' shows the on-screen controls (anything marked `.touch-only`),
+ *  'desk' hides them. Last input wins: a finger shows them, a key or a mouse hides them, live. It starts
+ *  from the screen (a coarse pointer, or the Studio's `?funpixel_touch` phone preview). Under a probe
+ *  (navigator.webdriver) the starting mode holds, so a probe pressing keys on a phone frame still sees the
+ *  phone's controls. */
+export let inputMode: 'touch' | 'desk' = 'desk';
+const markInput = (m: 'touch' | 'desk'): void => {
+  inputMode = m;
+  if (document.documentElement.dataset.input !== m) document.documentElement.dataset.input = m;
+};
+
+if (typeof document !== 'undefined') {
+  markInput(typeof matchMedia === 'function' && (matchMedia('(pointer: coarse)').matches || new URLSearchParams(location.search).has('funpixel_touch')) ? 'touch' : 'desk');
+  if (!navigator.webdriver) {
+    addEventListener('pointerdown', (e) => markInput(e.pointerType === 'mouse' ? 'desk' : 'touch'), true);
+    addEventListener('pointermove', (e) => { if (e.pointerType === 'mouse' && inputMode !== 'desk') markInput('desk'); }, true);
+    addEventListener('keydown', () => { if (inputMode !== 'desk') markInput('desk'); }, true);
+  }
+  document.addEventListener('visibilitychange', () => (document.hidden ? hold('hidden') : release('hidden')));
+  addEventListener('pagehide', () => { progress.flush(); });
+  // A host (a portal, the Funpixel player) holds the game through these, e.g. around an ad break.
+  Object.assign(window, { __FPX_HOLD__: { hold, release, held } });
+  // Fullscreen and the orientation lock on the first tap on a touch screen: no browser allows them without a
+  // gesture, and they are asked once (a player who leaves fullscreen is not dragged back). iPhone Safari has neither.
+  if (typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches && !navigator.webdriver) { // not under a probe: fullscreen would resize its viewport
+    const first = () => {
+      removeEventListener('pointerup', first, true);
+      void fullscreen.enter().then(() => (document.fullscreenElement ? orientation.lock(HOLD) : false));
+    };
+    addEventListener('pointerup', first, true);
+  }
+}

package/templates/common/src/pose.ts

@@ -0,0 +1,22 @@
+// What a renderer draws beyond position: the hero's look for each of its states, engine-free, so
+// both engines draw the same poses and `funtools feel` can see one look per state (research 18: our
+// games shipped one drawing per actor; the hits draw each state). A key pose per state is enough —
+// Dead Cells' pose-to-pose rule: the fewest keys that read, frames only around a key.
+
+import { hopHeight, type Run } from './rules';
+
+export interface HeroPose {
+  /** Height above the ground, in slots. */
+  lift: number;
+  /** Scale on top of the living layer's breath and lean. */
+  sx: number; sy: number;
+  /** Turn in radians (a topple). */
+  turn: number;
+}
+
+/** Tall and thin in a hop (Celeste stretches its hero to 0.6 × 1.4 on a jump), toppled in the death beat. */
+export function heroPose(state: string, run: Run): HeroPose {
+  if (state === 'dead') return { lift: 0, sx: 1, sy: 1, turn: (-Math.PI / 2) * run.facing };
+  if (state === 'hop') return { lift: hopHeight(run), sx: 0.8, sy: 1.25, turn: 0 };
+  return { lift: 0, sx: 1, sy: 1, turn: 0 };
+}

package/templates/common/src/probe-human.ts

@@ -0,0 +1,29 @@
+// probe-human.ts — a probe player at a human rate, for test/probes.ts beside the sharp bot: sim reads a level the
+// 60-decisions-a-second bot clears and this one cannot as a wall for people (one race, 30 Sep).
+
+import type { Policy } from './probe-kit.ts';
+
+/**
+ * The same player at a human rate: a fresh decision `hz` times a second (a thumb makes 10–15), each landing `reactMs`
+ * late (~200 ms to see and react). Between decisions the hand rests (`rest`, e.g. no press) or, with `hold`, keeps the
+ * last input (a steer held down). A level the 60-a-second bot clears and this one cannot is a wall for people (one
+ * race, 30 Sep). Wrap a policy that decides each call; one with its own press timer slows further.
+ */
+export function humanRate<R, I>(p: Policy<R, I>, dt: number, o: { rest: I; hold?: boolean; hz?: number; reactMs?: number }): Policy<R, I> {
+  const hz = o.hz ?? 12, reactMs = o.reactMs ?? 200;
+  return {
+    ...p, name: `${p.name}@${hz}hz`, human: { hz, reactMs },
+    says: `${p.says}; at a human rate (${hz} decisions a second, ${reactMs} ms to react)`,
+    make(seed) {
+      const choose = p.make(seed), due: Array<[number, I]> = [];
+      let t = 0, next = 0, held = o.rest;
+      return (run) => {
+        if (t >= next - 1e-9) { due.push([t + reactMs / 1000, choose(run)]); next += 1 / hz; }
+        let fresh = false;
+        while (due.length && due[0][0] <= t + 1e-9) { held = due.shift()![1]; fresh = true; }
+        t += dt;
+        return fresh || o.hold ? held : o.rest;
+      };
+    },
+  };
+}