@funpixel/tools 0.0.0-stage → 0.1.0

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 (The Last Good Robot: 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 (Saltwake's Dusk Cup, 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 (Saltwake's
+ * Dusk Cup, 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;
+      };
+    },
+  };
+}

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

@@ -0,0 +1,99 @@
+// probe-kit.ts — the rules played by simple policies over many seeds, engine-free: does standing still win? does a
+// naive steer-to-target bot do as well as a sharp one (no skill ceiling)? does the taught line pay? how long does a good
+// run last, and does it reach an ending? which seed stages the best REAL moment? test/probes.ts wires the game in; `npx @funpixel/tools sim` reads it.
+
+export type Outcome = 'won' | 'lost' | null; export interface Ev { type: string } export type Role = 'idle' | 'naive' | 'taught' | 'skilled' | 'novice' | 'middle';
+
+/** The game as the probes see it: its own rules, advanced a fixed step at a time. */
+export interface ProbeGame<R, I> {
+  newRun(seed: number): R;
+  /** One fixed step of `dt` seconds with the policy's input; events are data ({ type }). */
+  step(run: R, input: I): readonly Ev[]; dt: number;
+  outcome(run: R): Outcome;
+  /** How far the run got (waves cleared, score, level): higher is further. */
+  progress(run: R): number;
+  /** The first success a newcomer must reach (the novice floor), when the game names one. */
+  firstSuccess?(run: R): boolean;
+  /** What must never happen (NaN, off the map, inside a wall): its name, else null. */
+  broken?(run: R): string | null;
+  /** level: the level, stage or wave the run is on (1, 2 …; sim splits play length by it). ended: the ending (the last content, an end screen; a win counts): the run stops there, timed apart from losses. */
+  level?(run: R): number; ended?(run: R): boolean;
+}
+
+/** A player: `make(seed)` returns its press each step from what it can see; `human`: probe-human.ts; `foresight`: what it knows
+ *  a person cannot (clones the run, simulates ahead: never counted as human); role `middle` does SOME of what is taught. */
+export interface Policy<R, I> { name: string; role: Role; says: string; make(seed: number): (run: R) => I; human?: { hz: number; reactMs: number }; foresight?: string }
+export interface Cohort {
+  policy: string; role: Role; says: string; seeds: number; seconds: number; won: number; lost: number; open: number;
+  progress: { mean: number; min: number; max: number }; meanSeconds: number;
+  /** Seeds that reached game.firstSuccess (null: none named); events: mean count per run by type; ended/endedAt: seeds that reached the ending (or won; never a loss), and when. */
+  firstSuccess: number | null; events: Record<string, number>; ended: number; endedAt: number | null;
+  /** broken: absent with no broken() check, null when never broken. spread: run length across seeds. levels (with
+   *  game.level): seeds that reached, cleared (went on or won there) and lost each level, when and how long there. */
+  broken?: { what: string; seed: number; at: number } | null; lostSeeds: number[]; spread: { min: number; median: number; max: number };
+  levels?: Array<{ level: number; reached: number; meanAt: number; cleared: number; lost: number; meanSeconds: number }>; human?: Policy<unknown, unknown>['human']; foresight?: string;
+}
+const r2 = (n: number) => Math.round(n * 100) / 100;
+/** Play one policy from each seed until the run ends or `seconds` pass. */
+export function cohort<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seeds: number[], seconds: number): Cohort {
+  const prog: number[] = [], events: Record<string, number> = {}, lostSeeds: number[] = [], times: number[] = [];
+  const per = new Map<number, { at: number[]; spent: number[]; cleared: number; lost: number }>();
+  const at = (lv: number) => per.get(lv) ?? (per.set(lv, { at: [], spent: [], cleared: 0, lost: 0 }), per.get(lv)!);
+  let won = 0, lost = 0, time = 0, first = 0, broken: Cohort['broken'] = null; const ends: number[] = [];
+  for (const seed of seeds) {
+    const run = game.newRun(seed), input = p.make(seed);
+    let t = 0, reached = false, lv = game.level?.(run), since = 0;
+    if (lv !== undefined) at(lv).at.push(0);
+    while (t < seconds && !game.outcome(run) && !game.ended?.(run)) {
+      for (const e of game.step(run, input(run))) events[e.type] = (events[e.type] ?? 0) + 1;
+      t += game.dt; reached ||= game.firstSuccess?.(run) ?? false;
+      const b: string | null | undefined = broken ? null : game.broken?.(run);
+      if (b) broken = { what: b, seed, at: r2(t) };
+      const now = game.level?.(run);
+      if (now !== lv) {
+        if (lv !== undefined) { at(lv).spent.push(t - since); at(lv).cleared += now !== undefined && now > lv ? 1 : 0; }
+        if (now !== undefined) at(now).at.push(t); lv = now; since = t;
+      }
+    }
+    const o = game.outcome(run); if (o === 'won' || (o !== 'lost' && game.ended?.(run))) ends.push(t);
+    if (lv !== undefined) { at(lv).spent.push(t - since); if (o === 'won') at(lv).cleared++; else if (o === 'lost') at(lv).lost++; }
+    if (o === 'won') won++; else if (o === 'lost') { lost++; lostSeeds.push(seed); }
+    first += reached ? 1 : 0; prog.push(game.progress(run)); time += t; times.push(t);
+  }
+  const n = seeds.length || 1; times.sort((a, b) => a - b);
+  const mean = (xs: number[]) => (xs.length ? r2(xs.reduce((a, b) => a + b, 0) / xs.length) : 0), levels = [...per].sort((a, b) => a[0] - b[0]).map(([level, l]) => ({ level, reached: l.at.length, meanAt: mean(l.at), cleared: l.cleared, lost: l.lost, meanSeconds: mean(l.spent) }));
+  return {
+    policy: p.name, role: p.role, says: p.says, seeds: seeds.length, seconds, won, lost, open: seeds.length - won - lost,
+    progress: { mean: r2(prog.reduce((a, b) => a + b, 0) / n), min: Math.min(...prog), max: Math.max(...prog) },
+    meanSeconds: r2(time / n), firstSuccess: game.firstSuccess ? first : null, ended: ends.length, endedAt: ends.length ? mean(ends) : null,
+    events: Object.fromEntries(Object.entries(events).map(([k, v]) => [k, r2(v / n)])), lostSeeds: lostSeeds.slice(0, 12),
+    spread: { min: r2(times[0] ?? 0), median: r2(times[times.length >> 1] ?? 0), max: r2(times[times.length - 1] ?? 0) },
+    ...(game.level ? { levels } : {}), ...(game.broken ? { broken } : {}), ...(p.human ? { human: p.human } : {}), ...(p.foresight ? { foresight: p.foresight } : {}),
+  };
+}
+
+function advance<R, I>(game: ProbeGame<R, I>, run: R, input: (run: R) => I, seconds: number): Ev[] {
+  const out: Ev[] = []; for (let t = 0; t < seconds && !game.outcome(run); t += game.dt) out.push(...game.step(run, input(run))); return out;
+}
+/** The run a policy reaches from `seed` after `seconds`: a moment view's enter() replays the staged moment with it. */
+export function replayTo<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seed: number, seconds: number): R {
+  const run = game.newRun(seed); advance(game, run, p.make(seed), seconds); return run;
+}
+/** Search seeds × start times for the best REAL signature moment: `score` rates each event in the window after. */
+export function stageMoment<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, o: { seeds: number[]; at: number[]; window: number; score: (e: Ev) => number }) {
+  const found: Array<{ seed: number; at: number; score: number }> = [];
+  for (const seed of o.seeds) for (const at of o.at) {
+    const run = game.newRun(seed), input = p.make(seed); advance(game, run, input, at);
+    found.push({ seed, at, score: r2(advance(game, run, input, o.window).reduce((s, e) => s + o.score(e), 0)) });
+  }
+  return found.sort((a, b) => b.score - a.score || a.seed - b.seed || a.at - b.at).slice(0, 5);
+}
+/** Sample the run every `every` s while a policy plays: e.g. the game's own musicMix(run) beside what is on screen. */
+export function timeline<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seed: number, seconds: number, every: number, sample: (run: R, since: Ev[]) => Record<string, number>) {
+  const run = game.newRun(seed), input = p.make(seed), rows: Array<Record<string, number>> = []; let since: Ev[] = [];
+  for (let t = 0, next = 0; t < seconds && !game.outcome(run); t += game.dt) {
+    since.push(...game.step(run, input(run)));
+    if (t >= next) { rows.push({ t: r2(t), ...sample(run, since) }); since = []; next += every; }
+  }
+  return rows;
+}

package/templates/common/src/rules.ts

@@ -0,0 +1,99 @@
+// The game's rules, engine-free (no Pixi, Three or DOM): the renderer draws this state and the self-tests
+// grade it offline, so a rule is testable without a frame. Grow the game here first. A track of slots with
+// a gem in each: step onto GOAL gems before the clock runs out. From SPIKE_FIRST on, a crack glows under the
+// player (the tell), then a spike stands there: hop it or step away. random(run) is seeded (__FPX_SEED__ + n).
+
+/** One key press moves STEP (half a slot), so two presses reach the next gem. */ export const SLOTS = 12, ROUND_SECONDS = 60, GOAL = 30, STEP = 0.5;
+/** A picked gem comes back after RESPAWN_SECONDS plus up to RESPAWN_JITTER, from the run's seed. */ export const RESPAWN_SECONDS = 0.3, RESPAWN_JITTER = 0.2;
+/** The hero's height in slots (the drawn body): hop heights are in body heights. */ export const BODY = 0.8;
+/** The hop, the one defensive verb: in the air HOP_SECONDS, HOP_HEIGHT bodies at the top, safe from
+ *  a spike for HOP_SAFE after take-off, then a committed, open landing; ready HOP_COOLDOWN after.
+ *  Forgiveness (Celeste: a 4-frame buffer, 0.1 s coyote time): a press up to HOP_BUFFER before the
+ *  landing hops when ready; a spike hits only HOP_LATE after it stands, so a hop or step that late saves. */
+export const HOP_SECONDS = 0.5, HOP_HEIGHT = 0.8, HOP_SAFE = 0.35, HOP_COOLDOWN = 0.1, HOP_BUFFER = 0.1, HOP_LATE = 0.1;
+/** The spike: the crack glows TELL_SECONDS, the spike stands STRIKE_SECONDS; the first at SPIKE_FIRST s (past
+ *  the arcade idle floor: a player reading the screen is not killed for it), the next SPIKE_EVERY s (plus up to a second) after one ends. */
+export const TELL_SECONDS = 0.6, STRIKE_SECONDS = 0.15, SPIKE_FIRST = 8, SPIKE_EVERY = 2.5;
+export interface Run {
+  /** Position in slots (0 … SLOTS - 1); per slot, seconds until its gem is back (0 = there). */
+  x: number; score: number; timeLeft: number; facing: 1 | -1; gems: number[];
+  /** Seconds since the hop took off (-1 on the ground), until it is ready again, and an early press kept for then. */
+  hop: number; hopCool: number; queued: boolean;
+  /** The spike under way (its slot, seconds since its crack began to glow), and the wait for the next. */
+  spike: { slot: number; t: number } | null; nextSpike: number;
+  seed: number; // the random source's state: newRun(seed) with the same seed replays the same round
+}
+export type Outcome = 'won' | 'lost' | null; export type Phase = 'rest' | 'tell' | 'strike';
+/** The rules' one random source (mulberry32): a number in [0, 1) that advances the run's seed. */
+export function random(run: Run): number {
+  run.seed = (run.seed + 0x6d2b79f5) | 0;
+  let t = Math.imul(run.seed ^ (run.seed >>> 15), 1 | run.seed);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+let runs = 0; /* runs started in this page */ const nextSeed = (fixed = (globalThis as { __FPX_SEED__?: unknown }).__FPX_SEED__): number => (typeof fixed === 'number' ? (fixed + runs++) | 0 : Date.now() | 0);
+export function newRun(seed = nextSeed()): Run {
+  const start = Math.floor(SLOTS / 2);
+  const gems = Array.from({ length: SLOTS }, (_, i) => (i === start ? RESPAWN_SECONDS : 0));
+  return { x: start, score: 0, timeLeft: ROUND_SECONDS, facing: 1, gems, hop: -1, hopCool: 0, queued: false, spike: null, nextSpike: SPIKE_FIRST, seed };
+}
+export function move(run: Run, dir: 1 | -1): { picked: number | null; bumped: boolean; outcome: Outcome } {
+  run.facing = dir;
+  const next = Math.min(SLOTS - 1, Math.max(0, run.x + dir * STEP));
+  if (next === run.x) return { picked: null, bumped: true, outcome: null };
+  run.x = next;
+  const slot = Math.round(run.x);
+  if (Math.abs(run.x - slot) > 1e-9 || run.gems[slot] > 0) return { picked: null, bumped: false, outcome: null };
+  run.gems[slot] = RESPAWN_SECONDS + RESPAWN_JITTER * random(run);
+  run.score += 1;
+  return { picked: slot, bumped: false, outcome: run.score >= GOAL ? 'won' : null };
+}
+
+/** Take off, when on the ground and rested; false when it is not ready, keeping a press made within
+ *  HOP_BUFFER of the landing (or while resting) to take off the moment it is. */
+export function hop(run: Run): boolean {
+  const ready = run.hop < 0 && run.hopCool <= 0;
+  if (ready) run.hop = 0;
+  run.queued = !ready && (run.queued || run.hop < 0 || HOP_SECONDS - run.hop <= HOP_BUFFER + 1e-6);
+  return ready;
+}
+export const hopHeight = (run: Run): number => (run.hop < 0 ? 0 : 4 * HOP_HEIGHT * BODY * (run.hop / HOP_SECONDS) * (1 - run.hop / HOP_SECONDS));
+export const safe = (run: Run): boolean => run.hop >= 0 && run.hop < HOP_SAFE;
+export const phase = (run: Run): Phase => (!run.spike ? 'rest' : run.spike.t < TELL_SECONDS ? 'tell' : 'strike');
+/** Within a spike's reach: half a slot away is still hit, a whole slot is clear. */
+export const inReach = (run: Run, x = run.x): boolean => !!run.spike && Math.abs(x - run.spike.slot) < 0.75;
+
+/** Advance the clock in steps of at most 50 ms; 'lost' when a spike or the clock ends the round this tick. */
+export function tick(run: Run, dt: number): Outcome {
+  const n = Math.max(1, Math.ceil(dt / 0.05 - 1e-6)), h = dt / n, E = 1e-6;
+  for (let k = 0; k < n; k++) {
+    for (let i = 0; i < run.gems.length; i++) run.gems[i] = Math.max(0, run.gems[i] - h);
+    if (run.hop >= 0 && (run.hop += h) >= HOP_SECONDS - E) { run.hop = -1; run.hopCool = HOP_COOLDOWN; } else if (run.hop < 0) run.hopCool = Math.max(0, run.hopCool - h);
+    if (run.queued && run.hop < 0 && run.hopCool <= E) { run.hopCool = 0; hop(run); }
+    if (!run.spike && (run.nextSpike -= h) <= E) run.spike = { slot: Math.round(run.x), t: 0 };
+    else if (run.spike && (run.spike.t += h) >= TELL_SECONDS - E) {
+      if (run.spike.t >= TELL_SECONDS + HOP_LATE - E && inReach(run) && !safe(run)) return 'lost';
+      if (run.spike.t >= TELL_SECONDS + STRIKE_SECONDS - E) { run.spike = null; run.nextSpike = SPIKE_EVERY + random(run); }
+    }
+    const was = run.timeLeft;
+    if ((run.timeLeft = run.timeLeft - h <= E ? 0 : run.timeLeft - h) === 0 && was > 0) return 'lost';
+  }
+  return null;
+}
+/** Which way a sharp player steps now: off a glowing crack, else toward the nearest gem (never into a crack), or 0. */
+export function bestStep(run: Run): 1 | -1 | 0 {
+  if (run.spike && inReach(run)) return run.x > run.spike.slot || (run.x === run.spike.slot && run.x < SLOTS - 1) ? 1 : -1;
+  let best = Infinity;
+  for (let i = 0; i < SLOTS; i++) if (run.gems[i] === 0 && i !== run.x && Math.abs(i - run.x) < Math.abs(best)) best = i - run.x;
+  const dir = best === Infinity ? 0 : best > 0 ? 1 : -1;
+  return dir && !inReach(run, run.x + dir * STEP) ? dir : 0;
+}
+/** Play a round through the rules: a sharp bot pressing every `react` seconds, or never (null). */
+export function botRound(run: Run, react: number | null): Outcome {
+  for (let t = 0; t <= ROUND_SECONDS; t += react ?? 0.1) {
+    const dir = react === null ? 0 : bestStep(run);
+    const outcome = (dir ? move(run, dir).outcome : null) ?? tick(run, react ?? 0.1);
+    if (outcome) return outcome;
+  }
+  return null;
+}