@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/spec/common/src/levels.ts

@@ -0,0 +1,68 @@
+// The level list is the chapters and rooms of design/spec/rooms.json (chapters.ts): what each room is called, its
+// par, and where the player got to, kept through the SDK's SaveManager so a reload resumes at the checkpoint (the
+// room and wave the player was on). A won round moves the checkpoint to the room's next wave, or after its last wave
+// clears the room and moves through its exit; the next Play enters that room with its own numbers (tune.ts).
+// `funtools reach` and `check` read LEVELS as before, and the room map (room-map.tsx) reads progress(). Written by
+// `funtools spec init` (the big tier); yours to change.
+
+import { SaveManager } from '@funpixel/sdk/save';
+import { storage } from './save';
+import { onScreen } from './store';
+import { cleared, enter, fresh, progressMap, ROOMS, waveWon, type Progress } from './chapters';
+
+export interface Level {
+  id: string;
+  name: string;
+  /** Seconds a good run takes (the room's par). */
+  par?: number;
+  /** The level's data for reach (design/levels/<id>.json); optional. */
+  file?: string;
+}
+
+export const LEVELS: Level[] = ROOMS.map((r) => ({ id: r.id, name: r.name, par: r.par }));
+
+/** Where the player got to, saved apart from the round's best: the checkpoint, the rooms done, the best time in each. */
+export const rooms = new SaveManager<Progress>({ key: 'rooms', version: 1, defaults: fresh() }, storage);
+if (typeof rooms.data.wave !== 'number') rooms.update({ wave: 0 });
+const indexOf = (id: string) => ROOMS.findIndex((r) => r.id === id);
+const checkpoint = () => Math.max(0, indexOf(rooms.data.at));
+
+export const isDone = (id: string): boolean => rooms.data.done.includes(id);
+/** A room opens once it is the checkpoint or was cleared before (replayable). */
+export const isOpen = (i: number): boolean => i === checkpoint() || isDone(ROOMS[i]?.id ?? '');
+
+/** The room being played (an index into LEVELS); choosing one enters it, so the next round plays its numbers. */
+export let current = checkpoint();
+export function choose(i: number): void {
+  current = Math.max(0, Math.min(i, LEVELS.length - 1));
+  enter(ROOMS[current].id);
+}
+
+/** Mark a room cleared in `seconds` (every wave) and move the checkpoint on; saved at once. */
+export function complete(id: string, seconds = 0): void {
+  if (indexOf(id) < 0) return;
+  rooms.update(cleared(rooms.data, id, seconds));
+  rooms.flush();
+}
+
+/** The map of progress (chapters, rooms done / here / locked, best against par). */
+export const progress = () => progressMap(rooms.data);
+
+choose(current);
+
+/** The wave being played in the current room (0-based; chapters.ts wavesOf says how many it has). */
+export const wave = (): number => (rooms.data.at === ROOMS[current].id ? rooms.data.wave : 0);
+
+// Seconds of play in the room (pauses left out, every wave and retry in), and the checkpoint moved when a round is won.
+let since = 0, played = 0, playedIn = '';
+onScreen((next, prev) => {
+  const now = typeof performance === 'undefined' ? Date.now() : performance.now();
+  if (prev === 'playing') played += (now - since) / 1000;
+  if (next === 'playing') { if (playedIn !== ROOMS[current].id) { played = 0; playedIn = ROOMS[current].id; } since = now; }
+  if (next === 'won') {
+    const r = waveWon(rooms.data, ROOMS[current].id, played);
+    rooms.update(r.progress);
+    rooms.flush();
+    if (r.cleared) choose(checkpoint());
+  }
+});

package/templates/spec/common/src/probe-rooms.ts

@@ -0,0 +1,63 @@
+// probe-rooms.ts — the whole campaign as one probe game, for test/rooms.ts: the round's own ProbeGame played room
+// after room through chapters.ts, each room under its own numbers (its `tune`), wave after wave. A lost round retries
+// its wave from the checkpoint with a fresh seed; past `retries` losses in one room the run is lost there. level(run)
+// is the room's place in the list, so the kit's cohort() times every room and counts who cleared it (funtools rooms).
+
+import { enter, ROOMS, wavesOf, type Room } from './chapters';
+import type { Ev, Policy, ProbeGame } from './probe-kit.ts';
+
+export interface Campaign<R> {
+  /** The room being played (an index into the list), its wave, the round in it, and the campaign's own seed. */
+  i: number; wave: number; run: R; seed: number;
+  /** Seconds played, and when the current room was entered. */
+  t: number; since: number;
+  /** Per room: seconds to clear it (retries included) and rounds lost there. */
+  times: number[]; retries: number[];
+  done: boolean; failed: boolean;
+}
+
+/** The campaign over `rooms` (default: every room in rooms.json, in order). */
+export function campaign<R, I>(round: ProbeGame<R, I>, o: { rooms?: Room[]; retries?: number } = {}): ProbeGame<Campaign<R>, I> {
+  const list = o.rooms ?? ROOMS, cap = o.retries ?? 8;
+  const index = (id: string) => list.findIndex((r) => r.id === id);
+  const play = (c: Campaign<R>) => { c.run = round.newRun((c.seed * 7919 + c.i * 131 + c.wave * 29 + c.retries[c.i] * 17) | 0); };
+  const start = (c: Campaign<R>, i: number) => { enter(list[i].id); c.i = i; c.wave = 0; c.since = c.t; play(c); };
+  return {
+    dt: round.dt,
+    newRun(seed) {
+      const c = { i: 0, wave: 0, run: null as unknown as R, seed, t: 0, since: 0, times: list.map(() => 0), retries: list.map(() => 0), done: false, failed: false };
+      start(c, 0);
+      return c;
+    },
+    step(c, input) {
+      const ev: Ev[] = [...round.step(c.run, input)];
+      c.t += round.dt;
+      const o = round.outcome(c.run);
+      if (o === 'won' && c.wave + 1 < wavesOf(list[c.i])) { c.wave++; ev.push({ type: 'wave' }); play(c); }
+      else if (o === 'won') {
+        c.times[c.i] = c.t - c.since;
+        const next = index(list[c.i].exit);
+        ev.push({ type: 'room' });
+        if (next < 0) c.done = true;
+        else start(c, next);
+      } else if (o === 'lost') {
+        ev.push({ type: 'retry' });
+        if (++c.retries[c.i] > cap) c.failed = true;
+        else play(c);
+      }
+      return ev;
+    },
+    outcome: (c) => (c.done ? 'won' : c.failed ? 'lost' : null),
+    progress: (c) => c.i + (c.done ? 1 : 0),
+    firstSuccess: (c) => c.i > 0 || c.done,
+    level: (c) => c.i + 1,
+    ended: (c) => c.done,
+    ...(round.broken ? { broken: (c: Campaign<R>) => round.broken!(c.run) } : {}),
+  };
+}
+
+/** A round's player, playing the campaign: it sees the round being played, nothing else. */
+export function inCampaign<R, I>(p: Policy<R, I>): Policy<Campaign<R>, I> {
+  return { ...p, make: (seed) => { const f = p.make(seed); return (c) => f(c.run); } } as Policy<Campaign<R>, I>;
+}
+

package/templates/spec/common/src/room-map.tsx

@@ -0,0 +1,30 @@
+// The map of progress: every chapter's rooms as a row, the one the player resumes at marked (with its wave), each
+// cleared room with its best time against its par. It reads levels.ts (the save), so it is current on every render of
+// the endings (screens.tsx shows it under the score). Marked data-fpx-map for checks. The look is yours (styles.css
+// .room-map).
+
+import { current, LEVELS, progress } from './levels';
+
+const mmss = (s: number) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+
+export function RoomMap() {
+  const chapters = progress();
+  const playing = LEVELS[current]?.id;
+  return (
+    <div class="room-map" data-fpx-map style="display:grid;gap:6px;margin:8px 0;text-align:left;font-size:0.85em">
+      {chapters.map((c) => (
+        <div key={c.id}>
+          <strong>{c.name}</strong>
+          <ol style="display:flex;gap:6px;list-style:none;padding:0;margin:4px 0;flex-wrap:wrap">
+            {c.rooms.map((r) => (
+              <li key={r.id} class={`room ${r.state}`} data-room={r.id} data-state={r.state}
+                style={`padding:2px 8px;border-radius:999px;border:1px solid currentColor;opacity:${r.state === 'locked' ? 0.45 : 1};font-weight:${r.id === playing ? 700 : 400}`}>
+                {r.name}{r.state === 'here' && r.waves > 1 ? ` · wave ${r.wave + 1} of ${r.waves}` : ''}{r.best !== null ? ` · ${mmss(r.best)} / ${mmss(r.par)}` : ''}
+              </li>
+            ))}
+          </ol>
+        </div>
+      ))}
+    </div>
+  );
+}

package/templates/spec/common/src/tune.ts

@@ -0,0 +1,93 @@
+// tune.ts — every number the game plays by, read from design/spec/tunables.json (the big tier's one source of
+// truth; `funtools spec init` writes it from the starter's own numbers). tune('group.name') reads one, typed from
+// the file; group('move') is a live table whose fields follow the file. A key the file does not have throws at once,
+// with its name. A room lays its own numbers over the defaults (override, from chapters.ts); in dev an edit to the
+// file lands without a rebuild (vite's hot update), and onTune(fn) re-reads what a module keeps in its own bindings.
+// `funtools spec lint` checks the file against src/: unknown and unused ids, numbers still typed into the code.
+
+import data from '../design/spec/tunables.json' with { type: 'json' };
+
+type Groups = typeof data.groups;
+type G = keyof Groups & string;
+/** Every id in the file, as 'group.name'. */
+export type Key = { [g in G]: `${g}.${keyof Groups[g] & string}` }[G];
+type Default<E> = E extends { default: infer V } ? V : never;
+type At<K extends string> = K extends `${infer g}.${infer n}` ? (g extends G ? (n extends keyof Groups[g] ? Groups[g][n] : never) : never) : never;
+export type Value<K extends Key> = Default<At<K>>;
+/** A group as a plain table of its defaults' types. */
+export type Table<g extends G> = { -readonly [n in keyof Groups[g]]: Default<Groups[g][n]> };
+export type Overrides = Partial<Record<Key, number | boolean | string>>;
+
+const FILE = 'design/spec/tunables.json';
+let base = new Map<string, unknown>();
+let layer: Record<string, unknown> = {};
+const live = new Map<string, Record<string, unknown>>();
+const listeners = new Set<() => void>();
+
+/** Read the file's groups into the defaults; a malformed file stops the game with what is wrong. */
+function load(raw: unknown): void {
+  const groups = (raw as { groups?: Record<string, Record<string, unknown>> } | null)?.groups;
+  if (!groups || typeof groups !== 'object') throw new Error(`tune: ${FILE} has no "groups" object (funtools spec init writes one)`);
+  const next = new Map<string, unknown>();
+  for (const [g, entries] of Object.entries(groups)) {
+    for (const [n, e] of Object.entries(entries ?? {})) {
+      if (!e || typeof e !== 'object' || !('default' in e)) throw new Error(`tune: ${g}.${n} in ${FILE} has no default`);
+      next.set(`${g}.${n}`, (e as { default: unknown }).default);
+    }
+  }
+  base = next;
+}
+load(data);
+
+/** One number (or switch, or word) by its id. A missing id is a bug: it throws, named. */
+export function tune<K extends Key>(key: K): Value<K> {
+  if (key in layer) return layer[key] as Value<K>;
+  if (!base.has(key)) throw new Error(`tune: no tunable "${key}" in ${FILE}: add it there (default, unit, range, why) or fix the name`);
+  return base.get(key) as Value<K>;
+}
+
+function fill(name: string, table: Record<string, unknown>): void {
+  const pre = `${name}.`;
+  let found = false;
+  for (const k of base.keys()) if (k.startsWith(pre)) { table[k.slice(pre.length)] = tune(k as Key); found = true; }
+  if (!found) throw new Error(`tune: no group "${name}" in ${FILE}`);
+}
+
+/** A whole group as one object that stays current: its fields change in place when the file or a room changes them. */
+export function group<g extends G>(name: g): Table<g> {
+  let table = live.get(name);
+  if (!table) { table = {}; fill(name, table); live.set(name, table); }
+  return table as Table<g>;
+}
+
+function changed(): void {
+  for (const [name, table] of live) fill(name, table);
+  for (const fn of listeners) fn();
+}
+
+/** Run `fn` now and again whenever a number changes (a room entered, the file edited in dev). Returns the unsubscribe. */
+export function onTune(fn: () => void): () => void {
+  listeners.add(fn);
+  fn();
+  return () => { listeners.delete(fn); };
+}
+
+/** Lay a room's numbers over the defaults (an empty set restores them). An id the file does not have throws, naming `from`. */
+export function override(values: Overrides | Record<string, unknown>, from = 'an override'): void {
+  for (const k of Object.keys(values)) if (!base.has(k)) throw new Error(`tune: ${from} sets "${k}", which ${FILE} does not have`);
+  layer = { ...values };
+  changed();
+}
+
+/** The numbers laid over the defaults right now (a room's). */
+export const overrides = (): Record<string, unknown> => ({ ...layer });
+
+// Dev only: the file edited while the game runs lands at once (`tune()` reads it; onTune listeners re-read).
+if (import.meta.hot) {
+  import.meta.hot.accept('../design/spec/tunables.json', (m) => {
+    if (!m) return;
+    load((m as { default?: unknown }).default ?? m);
+    changed();
+    console.info(`[tune] ${FILE} reloaded`);
+  });
+}

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

@@ -0,0 +1,59 @@
+// The big tier's data, as the game loads it: every number from design/spec/tunables.json, every room from
+// design/spec/rooms.json. A room's numbers lay over the defaults and come off again; a wave won moves the checkpoint,
+// the last wave clears the room; a missing id throws by name. Written by `funtools spec init`; grow it with the game.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { group, onTune, override, tune, type Key } from '../src/tune.ts';
+import { CHAPTERS, cleared, enter, fresh, nextRoom, parTotal, progressMap, ROOMS, waveWon, wavesOf } from '../src/chapters.ts';
+
+test('every room has a par, an exit to a room that is there, and numbers the tunables hold', () => {
+  assert.ok(CHAPTERS.length >= 1 && ROOMS.length >= 1);
+  for (const r of ROOMS) {
+    assert.ok(r.par > 0, `${r.id} has a par`);
+    assert.ok(r.exit === 'end' || ROOMS.some((x) => x.id === r.exit), `${r.id} exits to a room`);
+    for (const k of Object.keys(r.tune ?? {})) assert.doesNotThrow(() => tune(k as Key), `${r.id} sets ${k}`);
+  }
+  assert.equal(nextRoom(ROOMS[ROOMS.length - 1].id), null, 'the last room ends the game');
+  assert.equal(parTotal(), ROOMS.reduce((s, r) => s + r.par, 0));
+});
+
+test('a room lays its numbers over the defaults, a group follows, and leaving puts the defaults back', () => {
+  const room = ROOMS.find((r) => Object.keys(r.tune ?? {}).length);
+  if (!room) return;
+  const [key, value] = Object.entries(room.tune!)[0];
+  const [g, name] = key.split('.');
+  const table = group(g as never) as Record<string, unknown>;
+  let heard = 0;
+  const off = onTune(() => { heard++; });
+  enter(room.id);
+  assert.equal(tune(key as Key), value);
+  assert.equal(table[name], value, 'the live table changed in place');
+  override({});
+  assert.notEqual(heard, 0);
+  off();
+  enter(ROOMS[0].id);
+});
+
+test('a missing id throws by name', () => {
+  assert.throws(() => tune('nope.nothing' as Key), /no tunable "nope\.nothing"/);
+  assert.throws(() => override({ 'nope.nothing': 1 }, 'room x'), /room x sets "nope\.nothing"/);
+});
+
+test('waves move the checkpoint; the last wave clears the room and opens its exit; the map follows', () => {
+  const first = ROOMS[0];
+  let p = fresh();
+  for (let w = 1; w < wavesOf(first); w++) {
+    const r = waveWon(p, first.id, 10 * w);
+    assert.equal(r.cleared, false);
+    assert.equal(r.progress.wave, w, 'the next wave is the checkpoint');
+    p = r.progress;
+  }
+  const done = waveWon(p, first.id, 61);
+  assert.equal(done.cleared, true);
+  assert.equal(done.progress.at, nextRoom(first.id)?.id ?? first.id);
+  assert.equal(done.progress.best[first.id], 61);
+  assert.equal(cleared(done.progress, first.id, 70).best[first.id], 61, 'a slower clear keeps the best');
+  const map = progressMap(done.progress).flatMap((c) => c.rooms);
+  assert.equal(map[0].state, ROOMS.length > 1 ? 'done' : 'here');
+});

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

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

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

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

package/templates/three/src/character.ts

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

package/templates/three/src/game.ts

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

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

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