@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/three-world/src/screens.css

@@ -0,0 +1,45 @@
+/* The screens around the round (screens.tsx), presented as a game: the title over the living world, the
+   rest as banners over the world softened behind them. */
+/* Cards keep to the safe band (frame.ts --band-*), and a card taller than a sideways phone scrolls inside it rather than under the home bar. */
+.screen { position: fixed; inset: 0; display: grid; place-items: safe center; overflow-y: auto; animation: fade 0.25s ease-out; padding: max(24px, var(--band-top, env(safe-area-inset-top))) var(--band-right, max(16px, env(safe-area-inset-right))) max(24px, var(--band-bottom, env(safe-area-inset-bottom))) var(--band-left, max(16px, env(safe-area-inset-left))); }
+/* Softened, not dimmed: the world stays visible and warm behind a banner. */
+.veil { background: radial-gradient(ellipse at center, rgba(27, 35, 80, 0.15), rgba(27, 35, 80, 0.55)); backdrop-filter: blur(5px); -webkit-backdrop-filter: blur(5px); }
+.banner { display: grid; gap: 0; justify-items: center; width: min(440px, calc(100vw - 32px)); animation: pop 0.35s cubic-bezier(0.2, 1.6, 0.4, 1); }
+.banner-word {
+  margin: 0 0 -14px; position: relative; z-index: 1; font-family: var(--font-display); font-weight: 400;
+  font-size: clamp(44px, 12vw, 84px); line-height: 1; letter-spacing: 0.01em; color: var(--primary);
+  -webkit-text-stroke: 2px #3a1a12; paint-order: stroke fill;
+  text-shadow: 0 4px 0 #a4532c, 0 8px 0 rgba(30, 10, 8, 0.6), 0 0 30px rgba(255, 200, 110, 0.5); transform: rotate(-2deg);
+}
+.banner-body { box-sizing: border-box; width: 100%; display: grid; gap: 12px; justify-items: center; padding: 30px 26px 22px; text-align: center; }
+.ending.lost .banner-word { color: var(--accent); }
+.tally { margin: 0; font-family: var(--font-display); line-height: 1; }
+.tally-n { font-size: 72px; color: var(--primary); text-shadow: 0 4px 0 #a4532c; }
+.tally-of { font-size: 30px; opacity: 0.8; margin-left: 8px; }
+.best { margin: -4px 0 4px; opacity: 0.8; text-transform: uppercase; letter-spacing: 0.1em; font-size: 14px; }
+/* The title is the world: no dimmer, the camera orbits behind, a vignette only at the edges for the type. */
+.title-screen {
+  background: radial-gradient(ellipse at 50% 40%, transparent 55%, rgba(14, 12, 38, 0.55) 100%);
+  grid-template-rows: auto 1fr auto; padding-top: max(56px, env(safe-area-inset-top)); padding-bottom: max(40px, env(safe-area-inset-bottom));
+}
+.title-band { display: grid; gap: 14px; justify-items: center; text-align: center; }
+.wordmark {
+  margin: 0; font-family: var(--font-display); font-weight: 400; font-size: clamp(54px, 15vw, 128px); line-height: 0.92;
+  color: #fff6e8; letter-spacing: 0.01em; -webkit-text-stroke: 3px #3a1a12; paint-order: stroke fill;
+  text-shadow: 0 5px 0 #a4532c, 0 10px 0 rgba(30, 10, 8, 0.55), 0 0 40px rgba(255, 190, 110, 0.55);
+  animation: float 4s ease-in-out infinite; max-width: 12ch;
+}
+img.wordmark { width: min(84vw, 620px); height: auto; font-size: 0; -webkit-text-stroke: 0; }
+.tagline { margin: 0; max-width: 30ch; font-size: clamp(16px, 4.2vw, 21px); text-shadow: 0 2px 4px rgba(14, 12, 38, 0.8); }
+.thumb-zone { grid-row: 3; display: grid; gap: 16px; justify-items: center; }
+@media (orientation: landscape) and (max-height: 500px) {
+  .title-screen { grid-template-rows: 1fr; grid-template-columns: 1fr auto; padding-top: max(18px, env(safe-area-inset-top)); padding-left: max(48px, env(safe-area-inset-left)); padding-right: max(48px, env(safe-area-inset-right)); }
+  .title-band { grid-column: 1; align-self: center; justify-self: start; justify-items: start; text-align: left; }
+  .wordmark { font-size: clamp(44px, 15vh, 92px); }
+  .thumb-zone { grid-row: 1; grid-column: 2; align-self: end; justify-self: end; justify-items: end; }
+  .banner-word { font-size: clamp(40px, 13vh, 72px); }
+  .banner-body { padding: 22px 22px 16px; gap: 8px; }
+}
+.row { display: flex; gap: 12px; }
+.step { margin: 0; display: flex; gap: 12px; align-items: center; text-align: left; line-height: 1.35; }
+@keyframes float { 50% { transform: translateY(-6px) rotate(-1deg); } }

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

@@ -0,0 +1,96 @@
+// Every screen around the round, presented as a game, not a web page: the title is the world itself (the
+// camera orbits the square behind it, no dimmer), the name in big display type with depth, one line of
+// promise, a big lit start in the thumb zone (data-fpx-start, so `verify --front-door` presses it); pause
+// blurs the world behind a banner; the endings stamp their word in and count the score. Each is a declared
+// view (expose.ts). The motes drifting over the title live in the world (world.ts), not the page.
+// The words are the game's: replace them, keep the set. Styles: screens.css.
+
+import type { ComponentChildren } from 'preact';
+import { applyMute } from './sound';
+import { Icon } from './icons';
+import { GOAL, ROUND_SECONDS } from './rules';
+import { go, show, useStore } from './store';
+import { Splash } from './splash';
+
+/** The wordmark as art from the style frame (e.g. '/ui/wordmark.png' in public/), or null: the name in --font-display. */
+export const WORDMARK: string | null = null;
+/** The title's one line: the promise, in the game's words. */
+export const TAGLINE = `Find all ${GOAL} lights before the clock runs out.`;
+
+function Wordmark({ title }: { title: string }) {
+  return WORDMARK ? <img class="wordmark" src={WORDMARK} alt={title} /> : <h1 class="wordmark" data-text={title}>{title}</h1>;
+}
+
+function Banner({ heading, kind = '', children }: { heading: string; kind?: string; children?: ComponentChildren }) {
+  return (
+    <div class={`screen veil ${kind}`}>
+      <div class="banner">
+        <h1 class="banner-word">{heading}</h1>
+        <div class="banner-body plate">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+function Toggles() {
+  const s = useStore();
+  return (
+    <div class="row">
+      <button class="icon plate" data-fpx-touch="KeyM" aria-label={s.muted ? 'sound off' : 'sound on'}><Icon name={s.muted ? 'soundOff' : 'soundOn'} /></button>
+      <button class="icon plate" aria-label="how to play" onClick={() => go('howto')}><Icon name="help" /></button>
+      <button class="icon plate" aria-label="settings" onClick={() => go('settings')}><Icon name="settings" /></button>
+    </div>
+  );
+}
+
+export function Screens({ title }: { title: string }) {
+  const s = useStore();
+  switch (s.screen) {
+    case 'playing': return null;
+    case 'splash': return <Splash title={title} />;
+    case 'paused': return (
+      <Banner heading="Paused" kind="pause">
+        <button class="primary big" onClick={() => go('playing')}><Icon name="play" /> Resume</button>
+        <Toggles />
+        <button class="quiet" onClick={() => go('title')}>Quit to title</button>
+      </Banner>
+    );
+    case 'howto': return (
+      <Banner heading="How to play">
+        <p class="step"><Icon name="gem" size={30} /> Find {GOAL} lights in {ROUND_SECONDS} seconds. Some wait up on the stones.</p>
+        <p class="step"><Icon name="jump" size={30} /> Jump: Space, or the big button. Hold it to jump higher.</p>
+        <p class="step"><Icon name="dash" size={30} /> Dash: Shift, or the small button.</p>
+        <p class="step"><Icon name="up" size={30} /> A red ring glows under you: run out of it, or jump as it flares.</p>
+        <p class="step"><Icon name="right" size={30} /> Move: arrows or WASD; on a phone, put a thumb down on the left.</p>
+        <button class="primary big" onClick={() => go(s.back)}>Back</button>
+      </Banner>
+    );
+    case 'settings': return (
+      <Banner heading="Settings">
+        <button onClick={() => { show({ muted: !s.muted }); applyMute(); }}>Sound: {s.muted ? 'off' : 'on'}</button>
+        <button onClick={() => show({ motion: !s.motion })}>Screen shake and flashes: {s.motion ? 'on' : 'off'}</button>
+        <button class="primary big" onClick={() => go(s.back)}>Back</button>
+      </Banner>
+    );
+    case 'won': case 'lost': return (
+      <Banner heading={s.screen === 'won' ? 'All found!' : s.lostTo === 'spike' ? 'Burned' : "Time's up"} kind={`ending ${s.screen}`}>
+        <p class="tally"><span class="tally-n">{s.score}</span><span class="tally-of">/ {GOAL}</span></p>
+        <p class="best">Best {s.best}</p>
+        <button class="primary big" data-fpx-start onClick={() => go('playing')}><Icon name="play" /> Play again</button>
+        <button class="quiet" onClick={() => go('title')}>Title</button>
+      </Banner>
+    );
+    default: return (
+      <div class="screen title-screen">
+        <header class="title-band">
+          <Wordmark title={title} />
+          <p class="tagline">{TAGLINE}</p>
+        </header>
+        <footer class="thumb-zone">
+          <button class="primary start" data-fpx-start onClick={() => go('playing')}><Icon name="play" size={30} /> Play</button>
+          <Toggles />
+        </footer>
+      </div>
+    );
+  }
+}

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

@@ -0,0 +1,25 @@
+// The game's own tests, run in the page by verify (window.__FPX_SELFTEST__): the rules alone, a sharp
+// bot for balance, the world's reach, and the juice table. The same rules are tested under Node too
+// (test/rules.test.ts, `npm test`).
+
+import { FLARE_FIRST, FLARE_LATE, FLARE_TELL, GOAL, MOVE, newRun, phase, ROUND_SECONDS, tick } from './rules';
+import { botRound } from './bot';
+import { feelTest, scaleTest } from './feel';
+
+const still = { x: 0, z: 0 };
+
+export const selfTests = [
+  { name: 'a round starts with the clock full and every pickup out', run: () => { const r = newRun(1); return r.timeLeft === ROUND_SECONDS && r.pickups.length === GOAL; } },
+  { name: `every pickup is within one jump of its floor (${MOVE.jumpHeight} m)`, run: () => [1, 2, 3, 4, 5].every((s) => newRun(s).pickups.every((p) => p.y - 0.6 <= MOVE.jumpHeight - 0.2)) },
+  { name: 'the same seed lays out and replays the same round', run: () => {
+    const a = newRun(7), b = newRun(7);
+    for (let i = 0; i < 30; i++) { tick(a, { x: 1, z: 0.3 }, 1 / 30); tick(b, { x: 1, z: 0.3 }, 1 / 30); }
+    return JSON.stringify(a) === JSON.stringify(b);
+  } },
+  { name: `a flare glows ${FLARE_TELL} s under the hero before it burns`, run: () => { const r = newRun(2); return tick(r, still, FLARE_FIRST + 1 / 60).outcome === null && phase(r) === 'tell' && tick(r, still, FLARE_TELL - 0.05).outcome === null && tick(r, still, 0.05 + FLARE_LATE + 0.02).outcome === 'lost'; } },
+  { name: 'a jump late in the glow clears the burn', run: () => { const r = newRun(2); tick(r, still, FLARE_FIRST + FLARE_TELL - 0.1); return tick(r, { ...still, jump: true }, 0.6).outcome === null; } },
+  { name: `a sharp player collects ${GOAL} and wins`, run: () => botRound(newRun(3), 0.12) === 'won' },
+  { name: 'a player who never moves loses', run: () => botRound(newRun(3), null) === 'lost' },
+  feelTest,
+  scaleTest,
+];

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

@@ -0,0 +1,99 @@
+// One round at a time: the rules, the screens, input, the juice table, sound and the hooks verify reads
+// (expose.ts). game.ts only draws `session.run`, tells the session where the camera faces (`yaw`) and calls
+// update() every frame. Input is camera-relative: up on the stick is away from the camera.
+
+import { nearestPickup, newRun, phase, tick, type Ev, type Input, type Outcome } from './rules';
+import { bestInput } from './bot';
+import { go, onScreen, show, store } from './store';
+import { bindInput, hold, moveVector, nudge, pollGamepad, type Verb } from './input';
+import { juice, stepJuice } from './juice';
+import { answer } from './feel';
+import { exposeRound } from './expose';
+import { exposeHooks } from './fpx-hooks';
+import { applyMute, loadSounds, unlockAudio } from './sound';
+
+/** Seconds a lost round holds on the hit before its card: short, so a retry is under a second away. */
+export const DEATH_BEAT = 0.6;
+/** The round, the death beat left, the game's clock (`funtools feel` measures on it), the camera's yaw,
+ *  and presses waiting for the next tick. */
+export const session = { run: newRun(), beat: 0, t: 0, yaw: 0, presses: { jump: false, dash: false } };
+export const inControl = (): boolean => store.screen === 'playing' && session.beat === 0;
+
+function end(outcome: Outcome): void {
+  if (!outcome || !inControl()) return;
+  const r = session.run, burned = outcome === 'lost' && r.timeLeft > 0;
+  answer(outcome === 'won' ? 'won' : burned ? 'hit' : 'lost', r.x, r.y, r.z);
+  show(outcome === 'won' ? { wins: store.wins + 1 } : { losses: store.losses + 1, lostTo: burned ? 'spike' : 'time' });
+  if (outcome === 'won') go('won'); else session.beat = DEATH_BEAT;
+}
+
+function endBeat(): void {
+  if (session.beat === 0) return;
+  session.beat = 0;
+  go('lost');
+}
+
+function press(verb: Verb): void {
+  unlockAudio();
+  if (store.screen === 'splash') { go('title'); return; } // any press skips the splash (splash.tsx)
+  if (verb === 'mute') { show({ muted: !store.muted }); applyMute(); return; }
+  if (session.beat > 0) return;
+  if ((verb === 'jump' || verb === 'dash') && inControl()) session.presses[verb] = true;
+  else if (verb === 'pause' && (store.screen === 'playing' || store.screen === 'paused')) go(store.screen === 'playing' ? 'paused' : 'playing');
+  else if ((verb === 'confirm' || verb === 'jump') && store.screen !== 'playing' && store.screen !== 'howto' && store.screen !== 'settings') go('playing');
+}
+
+onScreen((next, prev) => {
+  if (next === 'playing' && prev !== 'paused') {
+    Object.assign(session, { run: newRun(), beat: 0 });
+    show({ score: 0, timeLeft: session.run.timeLeft });
+  }
+  if (next === 'won' || next === 'lost') show({ best: Math.max(store.best, session.run.score) });
+});
+
+/** The stick and keys turned by the camera's yaw: screen up is away from the camera. */
+export function worldInput(): Input {
+  const m = moveVector(), s = Math.sin(session.yaw), c = Math.cos(session.yaw);
+  return { x: m.x * c - m.y * s, z: -m.x * s - m.y * c, held: hold.jump };
+}
+
+const EVENT_ROW: Record<Ev['type'], string> = { jump: 'jump', land: 'land', pickup: 'pickup', tell: 'tell', dash: 'dash', bump: 'bump' };
+
+/** Run the round forward with this input; the round ends through the rule, never around it. */
+function advance(dt: number, input: Input = worldInput()): void {
+  const { events, outcome } = tick(session.run, { ...input, jump: input.jump || session.presses.jump, dash: input.dash || session.presses.dash }, dt);
+  session.presses = { jump: false, dash: false };
+  for (const e of events) if (e.type !== 'land' || (e.power ?? 0) > 2) answer(EVENT_ROW[e.type], e.x, e.y, e.z, e.power);
+  if (events.some((e) => e.type === 'pickup')) show({ score: session.run.score });
+  if (Math.ceil(session.run.timeLeft) !== Math.ceil(store.timeLeft)) show({ timeLeft: session.run.timeLeft });
+  const near = nearestPickup(session.run), goal = near === null ? null : Math.round(near); if (goal !== store.goal) show({ goal });
+  end(outcome);
+}
+
+/** Advance one frame: the gamepad and the juice always; the beat, then the round, except in hitstop. */
+export function update(dt: number): void {
+  pollGamepad(press);
+  stepJuice(dt);
+  session.t += dt; nudge.left = Math.max(0, nudge.left - dt);
+  if (store.screen !== 'playing') return;
+  if (session.beat > 0) { session.beat -= dt; if (session.beat <= 0) endBeat(); return; }
+  if (juice.freeze > 0) { juice.freeze -= dt; return; }
+  advance(dt);
+}
+
+/** A sharp player through the real rules until the round ends (the win view, the winRound check). */
+function playToEnd(): void {
+  for (let i = 0; i < 20000 && inControl(); i++) advance(1 / 30, bestInput(session.run));
+}
+/** Walk toward the nearest pickup until one is collected (the collect check). */
+function collectOne(): void {
+  const was = session.run.score;
+  for (let i = 0; i < 900 && inControl() && session.run.score === was; i++) advance(1 / 30, bestInput(session.run));
+}
+
+export function startSession(): void {
+  bindInput(press);
+  for (const ev of ['pointerup', 'keydown', 'touchend']) addEventListener(ev, unlockAudio);
+  exposeRound({ session, inControl, press, advance: (dt) => advance(dt), playToEnd, collectOne, endBeat, phase: () => phase(session.run) });
+  void loadSounds(['pickup', 'jump', 'land', 'dash', 'bump', 'tell', 'win', 'lose'], 'theme').then((any) => { if (any) exposeHooks({ audio: true }); });
+}

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

@@ -0,0 +1,59 @@
+// The shots: the camera plan as data (the GDD's `## Shots` table, one row per moment). A shot is a named
+// framing: how far behind and above the look point the eye sits, the lens, the look point's height, the
+// yaw, and how it moves (follow the hero, or orbit a point). The rig (camera-rig.ts) frames whatever shot
+// is current; `shoot(name, seconds)` blends to another one (an eased move, never a cut unless 0 s).
+//
+// The title shot IS the play world (the Silt bar S1: the title is a live frame of the game, never a still):
+// it orbits the square the round is played on, so Play is a camera move into the game, not a new screen.
+// A story beat is a shot too (J2: acted in the engine, not a caption over the play): `shoot('reveal', 1.2)`
+// when the beat starts, `shoot('play', 0.8)` when it ends, and `funtools hook` sees the shot change.
+//
+// `funtools score --target` reads these numbers through `__FPX_CAMERA__` and prints its moves against them
+// ("SHOTS.play.height 4.4 → 6.1, fov 50 → 41"): tune a shot here, never by hand in the rig.
+
+export interface Shot {
+  /** follow: behind the hero along the rig's yaw; orbit: circles `look` slowly (the title). */
+  move: 'follow' | 'orbit';
+  /** Metres behind (horizontal) and above the look point; the vertical lens in degrees. */
+  distance: number; height: number; fov: number;
+  /** follow: the look point's height over the hero; orbit: the point it circles (x, y, z). */
+  lookHeight: number; look?: [number, number, number];
+  /** Radians: follow — the yaw it looks along (0 = toward −z); orbit — radians a second. */
+  yaw: number; speed?: number;
+}
+
+export const SHOTS = {
+  /** The title, in the play world: a slow orbit over the square. */
+  title: { move: 'orbit', distance: 21, height: 7.5, fov: 50, lookHeight: 1.5, look: [0, 1.5, 0], yaw: 0, speed: 0.07 },
+  /** Play: the third-person follow the stick is tuned for. */
+  play: { move: 'follow', distance: 9.5, height: 4.4, fov: 50, lookHeight: 1.4, yaw: 0 },
+  /** A beat: pulled back and up, so the whole square and what just changed read in one frame. */
+  reveal: { move: 'follow', distance: 15, height: 9, fov: 45, lookHeight: 1, yaw: 0.35 },
+} satisfies Record<string, Shot>;
+
+export type ShotName = keyof typeof SHOTS;
+
+/** The shot in use and the blend into it. */
+export const shots = { current: 'title' as ShotName, from: null as null | { pos: [number, number, number]; look: [number, number, number]; fov: number }, t: 1, seconds: 0 };
+
+/** Move to a named shot over `seconds` (0 = a cut). The rig captures where it is now as the blend's start. */
+export function shoot(name: ShotName, seconds = 0.9): void {
+  if (shots.current === name && shots.t >= 1) return;
+  shots.current = name;
+  shots.t = seconds > 0 ? 0 : 1;
+  shots.seconds = seconds;
+  shots.from = null; // filled by the rig on its next frame
+}
+
+/** Smoothstep: the blend eases in and out, so a move never jolts. */
+export const ease = (t: number) => t * t * (3 - 2 * t);
+
+/** The camera as data (`__FPX_CAMERA__`): the shot in use and its numbers, where the eye is and what it looks at. */
+export function cameraReport(rig: { camera: { position: { toArray(): number[] }; aspect: number }; aim: { toArray(): number[] }; lens: number }, exposure: number | null): Record<string, unknown> {
+  const name = shots.current, s: Shot = SHOTS[name];
+  return {
+    kind: '3d', source: `src/shots.ts SHOTS.${name}`, shot: name, blending: shots.t < 1, names: Object.keys(SHOTS),
+    shotParams: { distance: s.distance, height: s.height, fov: s.fov, lookHeight: s.lookHeight, yaw: s.yaw },
+    position: rig.camera.position.toArray(), target: rig.aim.toArray(), fov: rig.lens, aspect: rig.camera.aspect, exposure,
+  };
+}

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

@@ -0,0 +1,48 @@
+// A procedural sky, free and in one draw call: the dome shades from the horizon (the fog's colour, so
+// the world's edge melts into it) to the top colour, a sun or moon disc with a glow sits where the key
+// light comes from (lit and shadowed the same way), a soft band of cloud drifts, and stars come out
+// when the sky is dark. Every value is a uniform, so a new place re-colours it with no recompile.
+// A painted or generated skybox is an option you pay for (skill funpixel-3d,
+// references/skyboxes.md): this is the default, and the fallback when the picture fails to load.
+
+import * as THREE from 'three';
+
+const vertex = 'varying vec3 p; void main(){ p = normalize(position); gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }';
+const fragment = /* glsl */ `
+uniform vec3 top; uniform vec3 horizon; uniform vec3 sunDir; uniform vec3 sunColor; uniform float sunSize; uniform float clouds; uniform float stars; uniform float time;
+varying vec3 p;
+float hash(vec3 q){ return fract(sin(dot(q, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }
+float noise(vec2 x){ vec2 i = floor(x), f = fract(x); f = f * f * (3.0 - 2.0 * f);
+  float a = hash(vec3(i, 0.0)), b = hash(vec3(i + vec2(1, 0), 0.0)), c = hash(vec3(i + vec2(0, 1), 0.0)), d = hash(vec3(i + vec2(1, 1), 0.0));
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y); }
+void main(){
+  float h = clamp(p.y, 0.0, 1.0);
+  vec3 col = mix(horizon, top, pow(clamp(h * 1.6, 0.0, 1.0), 0.6));
+  float d = max(dot(p, normalize(sunDir)), 0.0);
+  col += sunColor * (smoothstep(1.0 - sunSize, 1.0 - sunSize * 0.6, d) * 1.2 + pow(d, 24.0) * 0.35);
+  vec2 uv = p.xz / (p.y + 0.25) * 1.6 + vec2(time * 0.01, 0.0);
+  float c = smoothstep(0.55, 0.85, noise(uv) * 0.65 + noise(uv * 2.7) * 0.35) * smoothstep(0.02, 0.25, h) * clouds;
+  col = mix(col, mix(horizon, vec3(1.0), 0.35), c * 0.5);
+  float s = step(0.9975, hash(floor(p * 300.0))) * smoothstep(0.1, 0.5, h) * stars * (1.0 - c);
+  gl_FragColor = vec4(col + s, 1.0);
+}`;
+
+export interface Sky { mesh: THREE.Mesh; set(o: { top: THREE.Color; horizon: THREE.Color; sunDir: [number, number, number]; sunColor: string; dark: boolean }): void; tick(t: number): void }
+
+export function makeSky(scene: THREE.Scene): Sky {
+  const u = {
+    top: { value: new THREE.Color() }, horizon: { value: new THREE.Color() }, sunDir: { value: new THREE.Vector3(0, 1, 0) },
+    sunColor: { value: new THREE.Color() }, sunSize: { value: 0.004 }, clouds: { value: 0.6 }, stars: { value: 0 }, time: { value: 0 },
+  };
+  const mesh = new THREE.Mesh(new THREE.SphereGeometry(400, 32, 16), new THREE.ShaderMaterial({ side: THREE.BackSide, depthWrite: false, fog: false, uniforms: u, vertexShader: vertex, fragmentShader: fragment }));
+  mesh.name = 'sky'; mesh.renderOrder = -1; mesh.frustumCulled = false; scene.add(mesh);
+  return {
+    mesh,
+    set(o) {
+      u.top.value.copy(o.top); u.horizon.value.copy(o.horizon); u.sunDir.value.set(...o.sunDir);
+      u.sunColor.value.set(o.sunColor); u.stars.value = o.dark ? 1 : 0; u.sunSize.value = o.dark ? 0.0025 : 0.004; u.clouds.value = o.dark ? 0.35 : 0.6;
+      scene.background = o.horizon.clone();
+    },
+    tick(t) { u.time.value = t; },
+  };
+}

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

@@ -0,0 +1,83 @@
+// The place on stage: sky, light, post, ground and dressing for one place of places.json, sized by the
+// quality tier. enter(place) re-colours the sky, moves every light, swaps the grade, lays the ground in
+// the place's surface and palette, and dresses it by its kit (the road and the solids kept clear, the
+// landmark at the road's end, spot pools on the landmark and the lanterns). game.ts calls enter() when a
+// round starts, tick() and render() every frame. facts() is state.world: what `funtools places` and
+// `boxes` read (the place, its light, its density against its target, what the dressing costs).
+
+import * as THREE from 'three';
+import data from './places.json';
+import { look } from './look';
+import { PALETTE } from './palette';
+import { budget } from './budget';
+import { makeSky, type Sky } from './sky';
+import { LightRig } from './light';
+import { Post } from './post';
+import { ground } from './world';
+import { dress, wind } from './dressing';
+import { budgetOf, densityOf, scatter, type Placed } from './dressing-math';
+import { lightOf, passes, placeFor, ringOf, roadOf, type Place } from './places';
+import { keyDirection, PRESET_NAMES, TIERS, type LightBlock, type Tier } from './light-math';
+import type { Box, Post as Pillar } from './layout';
+
+export const PLACES: Place[] = (data as unknown as { places: Place[] }).places;
+const gameLight = (typeof look.light === 'object' ? look.light : {}) as unknown as LightBlock;
+
+export class Stage {
+  readonly tier: Tier = budget.tier();
+  readonly sky: Sky;
+  readonly rig: LightRig;
+  readonly post: Post;
+  private set = new THREE.Group();
+  place: Place | null = null;
+  private placed: Placed[] = [];
+  private cost = { calls: 0, triangles: 0 };
+  ready = false;
+
+  constructor(private scene: THREE.Scene, renderer: THREE.WebGLRenderer, camera: THREE.Camera, host: HTMLElement) {
+    this.sky = makeSky(scene); this.rig = new LightRig(scene, renderer, this.tier); this.post = new Post(renderer, scene, camera, host, this.tier);
+    this.set.name = 'set'; scene.add(this.set);
+  }
+
+  /** Round N's place (or a named one), dressed around this round's solids. */
+  async enter(round: number | string, boxes: Box[], posts: Pillar[], seed = 1): Promise<void> {
+    const p = typeof round === 'string' ? PLACES.find((x) => x.id === round) ?? PLACES[0] : placeFor(PLACES, round);
+    this.place = p; this.ready = false;
+    const tone = (k: string, fallback: THREE.Color) => (p.palette[k] ? new THREE.Color(p.palette[k]) : fallback.clone());
+    Object.assign(PALETTE, { skyTop: tone('sky-top', PALETTE.skyTop), horizon: tone('sky-horizon', PALETTE.horizon), ground: tone('ground', PALETTE.ground), ground2: tone('ground-2', PALETTE.ground2), stone: tone('stone', PALETTE.stone) });
+    const l = lightOf(p, gameLight);
+    this.sky.set({ top: PALETTE.skyTop, horizon: PALETTE.horizon, sunDir: keyDirection(l), sunColor: l.key, dark: l.preset === 'moonlit-spot' || l.ambient < 0.6 });
+    this.rig.apply(l, PALETTE.horizon); this.post.apply(l);
+    const next = new THREE.Group();
+    ground(next, 1, p.surface); // the terrain is the place's (seed 1, as dressing-math grounds on); the scatter varies by round
+    const keepouts = [{ x: 0, z: 0, r: 1.5 }, ...boxes.map((b) => ({ x: b.x, z: b.z, r: Math.hypot(b.hw, b.hd) + 0.3 })), ...posts.map((q) => ({ x: q.x, z: q.z, r: q.r + 0.3 }))];
+    const road = roadOf(p), share = TIERS[this.tier].dressing, max = TIERS[this.tier].maxInstances;
+    const [lx, lz] = p.landmark.at;
+    keepouts.push({ x: lx, z: lz, r: p.landmark.scale * 1.2 });
+    this.placed = passes(p).flatMap(({ kit, ring }, i) => scatter(kit, ring, { seed: seed * 31 + i, roads: [road], keepouts, share, max }));
+    const landmark: Placed = { slot: -1, role: 'landmark', kind: p.landmark.kind, x: lx, y: 0, z: lz, scale: p.landmark.scale, turn: 0 };
+    const tris = await dress(next, [...this.placed, landmark], { ground: PALETTE.ground, ground2: PALETTE.ground2, stone: PALETTE.stone, accent: tone('accent', PALETTE.pickup), glow: tone('glow', PALETTE.key) });
+    if (this.place !== p) return; // a newer enter() won
+    this.scene.remove(this.set); this.set = next; this.set.name = 'set'; this.scene.add(next);
+    this.cost = budgetOf([...this.placed, landmark], tris);
+    // Pools of light where the eye should go: the platforms nearest the play, then the landmark, then the lanterns.
+    const near = [...boxes].sort((a, b) => Math.hypot(a.x, a.z) - Math.hypot(b.x, b.z)).slice(0, 2).map((b) => ({ x: b.x, y: b.top, z: b.z }));
+    const lamps = this.placed.filter((q) => q.kind === 'lantern').sort((a, b) => Math.hypot(a.x, a.z) - Math.hypot(b.x, b.z)).map((q) => ({ x: q.x, y: q.y, z: q.z }));
+    this.rig.aimSpots([...near, { x: lx, y: p.landmark.scale * 1.5, z: lz }, ...lamps]);
+    this.ready = true;
+  }
+
+  tick(t: number, x: number, z: number): void { this.sky.tick(t); wind.value = t; this.rig.follow(x, z); }
+  render(): void { this.post.render(); }
+  setSize(w: number, h: number): void { this.post.setSize(w, h); }
+
+  facts(): Record<string, unknown> {
+    const p = this.place, d = densityOf(this.placed, ringOf(), p ? [roadOf(p)] : []);
+    return {
+      places: PLACES.map((q) => q.id), presets: PRESET_NAMES, place: p?.id ?? null, name: p?.name ?? null, ready: this.ready, tier: this.tier,
+      light: this.rig.facts(), post: this.post.facts(),
+      dressing: { ...d, target: p ? Math.round(p.density * TIERS[this.tier].dressing) : null, planned: p?.density ?? null, calls: this.cost.calls, triangles: this.cost.triangles, area: Math.round(Math.PI * ringOf().outer ** 2) },
+      roads: p ? [roadOf(p)] : [],
+    };
+  }
+}

package/templates/three-world/src/styles.css

@@ -0,0 +1,95 @@
+@import './screens.css';
+@import './hud-kit.css';
+/* One palette for the world and the UI: palette.ts reads the world tokens (sky, ground, stone, hero, key
+   light) into the 3D scene, so restyling here restyles both. These are the starter's dusk; the design's
+   replaces them (smoke warns while the scaffold palette ships in funpixel.json). */
+:root {
+  --bg: #1b2350; --ink: #fff6e8; --primary: #ffd36e; --accent: #ff9a5c; --harm: #ff5a4f;
+  --sky-top: #1b2350; --sky-horizon: #f0a073; --ground: #4a4436; --ground-2: #6e6a48; --stone: #9b8a78;
+  --hero: #f4efe4; --hero-accent: #e2553f; --key-light: #ffe2c0;
+}
+/* The UI roles (assets/style.json's `ui` block): every plate, button, icon and face reads these. The
+   starter's material is warm lacquer with a lit edge and a display face with weight, so the first build
+   reads as a game; make them the world's own (skill funpixel-art, references/ui.md). */
+:root {
+  --plate: linear-gradient(180deg, rgba(92, 46, 30, 0.88), rgba(52, 24, 22, 0.9));
+  --plate-edge: rgba(255, 211, 110, 0.55); --plate-ink: var(--ink);
+  --plate-radius: 16px; --plate-shadow: 0 4px 0 rgba(30, 10, 8, 0.55), 0 10px 24px rgba(10, 6, 20, 0.35); --ui-stroke: 2px;
+  --icon-line: #3a1a12; --icon-fill: var(--primary); --icon-stroke: 2.4; --button-ink: #3a1a12;
+  --font-display: 'Lilita One', 'Trebuchet MS', sans-serif; --font-body: 'Nunito', 'Trebuchet MS', sans-serif;
+  --panel: var(--plate);
+}
+html, body {
+  margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden;
+  overscroll-behavior: none; -webkit-user-select: none; user-select: none;
+  -webkit-touch-callout: none; -webkit-tap-highlight-color: transparent;
+  background: var(--bg); color: var(--ink); font-family: var(--font-body); font-weight: 700;
+}
+.plate {
+  background: var(--plate); color: var(--plate-ink); border: var(--ui-stroke) solid var(--plate-edge);
+  border-radius: var(--plate-radius); box-shadow: var(--plate-shadow);
+}
+#app, .stage { position: fixed; inset: 0; }
+.stage { touch-action: none; }
+.stage::after { /* a hurt shows at the edges (juice.vignette sets --vignette), never as a full-screen flash */ content: ''; position: absolute; inset: 0; pointer-events: none; box-shadow: inset 0 0 16vmin 3vmin var(--harm); opacity: var(--vignette, 0); }
+canvas { display: block; width: 100%; height: 100%; }
+button {
+  font: inherit; font-weight: 800; color: var(--ink); cursor: pointer; letter-spacing: 0.01em;
+  min-width: 48px; min-height: 48px; padding: 0 22px; border-radius: 14px;
+  background: var(--plate); border: var(--ui-stroke) solid var(--plate-edge); box-shadow: var(--plate-shadow);
+  display: inline-flex; gap: 10px; align-items: center; justify-content: center;
+  touch-action: manipulation; transition: transform 0.1s ease-out, filter 0.12s, box-shadow 0.1s;
+}
+button:hover { filter: brightness(1.1); transform: translateY(-2px); }
+button:active { transform: translateY(3px); box-shadow: 0 1px 0 rgba(30, 10, 8, 0.55); }
+/* The lit button: a raised, glowing slab, not a form control. */
+button.primary {
+  font-family: var(--font-display); font-weight: 400; font-size: 1.2em; color: var(--button-ink); border: 0;
+  background: linear-gradient(180deg, #fff1b8 0%, var(--primary) 45%, var(--accent) 100%);
+  box-shadow: 0 5px 0 #a4532c, 0 0 0 3px rgba(255, 246, 232, 0.9), 0 10px 30px rgba(255, 190, 100, 0.45);
+  text-shadow: 0 1px 0 rgba(255, 255, 255, 0.6);
+}
+button.primary:active { box-shadow: 0 1px 0 #a4532c, 0 0 0 3px rgba(255, 246, 232, 0.9); }
+button.primary .ico-fill { fill: #3a1a12; } button.primary .ico-line { stroke: transparent; }
+button.big { min-height: 58px; min-width: min(240px, 66vw); }
+button.quiet { background: none; border: 0; box-shadow: none; opacity: 0.85; text-decoration: underline; text-underline-offset: 4px; }
+button.icon { padding: 0; width: 52px; height: 52px; border-radius: 50%; }
+button.start { min-width: min(300px, 74vw); min-height: 68px; font-size: 1.6em; animation: glow 2.4s ease-in-out infinite; }
+/* Edge pieces keep to the safe band (frame.ts: --band-*; the fallbacks are for a game that drops it). */
+.hud {
+  position: fixed; left: var(--band-left, max(16px, env(safe-area-inset-left))); right: var(--band-right, max(16px, env(safe-area-inset-right)));
+  top: var(--band-top, max(12px, env(safe-area-inset-top))); display: flex; gap: 12px; align-items: center;
+  font-size: clamp(17px, 4.4vmin, 26px); pointer-events: none;
+}
+.hud-row { position: relative; display: inline-flex; gap: 8px; align-items: center; padding: 5px 14px 5px 8px; }
+.hud-label { font-size: max(12px, 0.55em); font-weight: 800; opacity: 0.8; text-transform: uppercase; letter-spacing: 0.08em; }
+.hud-value { font-family: var(--font-display); font-variant-numeric: tabular-nums; }
+.hud-time.urgent { animation: urgent 0.5s ease-in-out infinite alternate; }
+.hud-buttons { margin-left: auto; display: flex; gap: 10px; pointer-events: auto; }
+.pop { position: absolute; left: 100%; top: 0; margin-left: 6px; font-family: var(--font-display); color: var(--primary); animation: rise 0.7s ease-out forwards; }
+/* The thumbs' controls (controls.tsx): the stick zone is the left half under the HUD; the actions sit in the right thumb's arc. Touch only (platform.ts inputMode: last input wins). */
+html:not([data-input="touch"]) .touch-only { display: none !important; }
+.stick-zone { position: fixed; inset: 0; touch-action: none; } /* the whole play: a thumb down anywhere off a button moves */
+.stick { position: fixed; left: max(110px, 20vw); top: calc(100% - max(130px, 24vh)); width: 120px; height: 120px; margin: -60px 0 0 -60px; border-radius: 50%;
+  border: 3px solid rgba(255, 246, 232, 0.35); background: radial-gradient(circle, rgba(255, 246, 232, 0.12), rgba(255, 246, 232, 0.02)); display: none; pointer-events: none; }
+.stick.live { display: block; } /* born under the thumb, gone when it lifts: nothing sits on the play at rest */
+.stick-knob { position: absolute; left: 30px; top: 30px; width: 60px; height: 60px; border-radius: 50%; background: var(--plate); border: 3px solid var(--plate-edge); box-shadow: var(--plate-shadow); }
+.actions { position: fixed; right: max(20px, var(--band-right, max(20px, env(safe-area-inset-right)))); bottom: max(24px, var(--band-bottom, max(24px, env(safe-area-inset-bottom)))); display: grid; grid-template-columns: auto auto; gap: 14px; align-items: end; }
+.act { padding: 0; border-radius: 50%; }
+.act-jump { width: 88px; height: 88px; } .act-dash { width: 66px; height: 66px; margin-bottom: 40px; }
+@media (orientation: portrait) and (max-width: 500px) {
+  .hud { gap: 8px; }
+  .hud-label { display: none; } /* the icon names the number where the width is short (aria-label keeps the word) */
+  .hud-buttons { gap: 8px; } button.icon { width: 46px; height: 46px; min-width: 46px; min-height: 46px; }
+}
+
+@keyframes pop { from { transform: scale(0.6) rotate(-4deg); opacity: 0; } }
+@keyframes fade { from { opacity: 0; } }
+@keyframes rise { from { transform: translateY(0) scale(1.4); opacity: 1; } to { transform: translateY(-30px) scale(1); opacity: 0; } }
+@keyframes glow { 50% { box-shadow: 0 5px 0 #a4532c, 0 0 0 3px rgba(255, 246, 232, 0.9), 0 10px 44px rgba(255, 210, 120, 0.8); transform: translateY(-2px); } }
+@keyframes urgent { to { color: var(--harm); transform: scale(1.06); } }
+.ico { flex-shrink: 0; }
+.ico-fill { fill: var(--icon-fill); }
+.ico-line { fill: none; stroke: var(--icon-line); stroke-width: var(--icon-stroke); stroke-linecap: round; stroke-linejoin: round; }
+@media (prefers-reduced-motion: reduce) { .banner, .screen, .wordmark, .pop, button.start, [class*='kit-'] { animation: none; } }
+.load-failed { position: fixed; inset: auto 16px 40%; margin: auto; max-width: 320px; padding: 20px; text-align: center; z-index: 50; }

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

@@ -0,0 +1,55 @@
+// Ground surfaces made in code, free: each kind is a small tiling detail texture drawn once on a canvas
+// (grass blades, sand ripples, cobbles, flagstones, snow, moss) multiplied over the ground's vertex
+// colours, with a roughness to match. The detail breaks the flat colour on big triangles that `boxes`
+// reports as unfinished, at one texture (≤ 256², mipmapped) and no extra draw call. A painted or
+// generated tile is an option you pay for (skill funpixel-3d, references/textures.md); it
+// replaces `map` and keeps everything else.
+
+import * as THREE from 'three';
+import { random } from './layout';
+
+export type Surface = 'grass' | 'sand' | 'cobble' | 'flagstone' | 'snow' | 'moss';
+export const SURFACES: Surface[] = ['grass', 'sand', 'cobble', 'flagstone', 'snow', 'moss'];
+const ROUGH: Record<Surface, number> = { grass: 0.95, sand: 0.9, cobble: 0.8, flagstone: 0.75, snow: 0.6, moss: 0.95 };
+/** Metres one tile covers: hand-sized detail near the camera, never a pattern you can count. */
+export const TILE_M: Record<Surface, number> = { grass: 2, sand: 3, cobble: 1.5, flagstone: 2.5, snow: 4, moss: 2 };
+
+const cache = new Map<Surface, THREE.CanvasTexture>();
+/** The detail texture of a surface: greys around white, so the vertex colours keep the palette. */
+export function detailTexture(kind: Surface, size = 256): THREE.CanvasTexture {
+  const hit = cache.get(kind);
+  if (hit) return hit;
+  const c = document.createElement('canvas'); c.width = c.height = size;
+  const g = c.getContext('2d')!, s = { seed: kind.length * 7919 };
+  g.fillStyle = '#e8e8e8'; g.fillRect(0, 0, size, size);
+  const shade = (v: number, a = 1) => `rgba(${v}, ${v}, ${v}, ${a})`;
+  if (kind === 'grass' || kind === 'moss') {
+    for (let i = 0; i < (kind === 'grass' ? 1400 : 900); i++) {
+      const x = random(s) * size, y = random(s) * size, l = 3 + random(s) * (kind === 'grass' ? 7 : 3);
+      g.strokeStyle = shade(170 + random(s) * 85, 0.8); g.lineWidth = 1 + random(s);
+      g.beginPath(); g.moveTo(x, y); g.lineTo(x + (random(s) - 0.5) * 3, y - l); g.stroke();
+    }
+  } else if (kind === 'sand' || kind === 'snow') {
+    for (let y = 0; y < size; y += 6) { g.strokeStyle = shade(kind === 'sand' ? 205 : 225, 0.6); g.beginPath(); for (let x = 0; x <= size; x += 8) g.lineTo(x, y + Math.sin((x / size) * Math.PI * 4 + y) * 2); g.stroke(); }
+    for (let i = 0; i < 2000; i++) { g.fillStyle = shade(190 + random(s) * 65, 0.7); g.fillRect(random(s) * size, random(s) * size, 1, 1); }
+  } else {
+    const n = kind === 'cobble' ? 8 : 4, step = size / n;
+    for (let r = 0; r < n; r++) for (let q = 0; q < n; q++) {
+      const off = kind === 'cobble' && r % 2 ? step / 2 : 0, x = q * step + off, y = r * step;
+      g.fillStyle = shade(175 + random(s) * 70); g.strokeStyle = shade(110);
+      g.lineWidth = kind === 'cobble' ? 3 : 2;
+      g.beginPath(); g.roundRect(x + 2, y + 2, step - 4, step - 4, kind === 'cobble' ? step * 0.35 : 3); g.fill(); g.stroke();
+    }
+  }
+  const t = new THREE.CanvasTexture(c);
+  t.wrapS = t.wrapT = THREE.RepeatWrapping; t.colorSpace = THREE.SRGBColorSpace; t.anisotropy = 4;
+  cache.set(kind, t);
+  return t;
+}
+
+/** A ground material of a kind over vertex colours; `span` metres of world is the mesh's UV unit 1. */
+export function surfaceMaterial(kind: Surface, span = 1): THREE.MeshStandardMaterial {
+  const map = detailTexture(kind).clone(); map.needsUpdate = true;
+  map.repeat.set(span / TILE_M[kind], span / TILE_M[kind]);
+  return new THREE.MeshStandardMaterial({ vertexColors: true, map, roughness: ROUGH[kind] });
+}