@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/three-world/src/light-math.ts

@@ -0,0 +1,78 @@
+// The light as data, engine-free (the tests and funtools read it): a mood preset (values, never prose)
+// that look.json's "light" block and each place's "light" adjust, and the quality tier that sizes the
+// cost. A frame's light is key (the sun or moon: colour, strength, where it sits), fill (the sky's
+// bounce from the other side), rim (behind, so the silhouette reads), the hemisphere (sky above,
+// ground bounce below; never black: a black floor is unreadable, not moody), fog in the horizon's
+// colour, spots (pools of light on the landmarks: the moonlit-spot look), exposure, and the grade
+// (saturation, contrast, a tint, a vignette) and bloom. `funtools score --target` names its moves in
+// these keys (`look set light.exposure=0.8`). Skill funpixel-3d, references/light-and-places.md.
+
+export interface Light {
+  exposure: number;
+  key: string; keyIntensity: number; keyElevation: number; keyAzimuth: number;
+  fill: string; fillIntensity: number; rim: string; rimIntensity: number;
+  sky: string; bounce: string; ambient: number;
+  fogNear: number; fogFar: number; shadow: 'soft' | 'hard' | 'off';
+  spots: number; spot: string; spotIntensity: number;
+  saturation: number; contrast: number; tint: string; tintAmount: number; vignette: number;
+  bloom: number; bloomThreshold: number;
+}
+export type LightBlock = Partial<Light> & { preset?: string };
+
+const base: Light = {
+  exposure: 1, key: '#fff2dc', keyIntensity: 2.4, keyElevation: 45, keyAzimuth: 35, fill: '#9fb6e0', fillIntensity: 0.4,
+  rim: '#c8d8ff', rimIntensity: 0.6, sky: '#b8c8e8', bounce: '#5a5040', ambient: 1.2, fogNear: 22, fogFar: 70, shadow: 'soft',
+  spots: 0, spot: '#ffd9a0', spotIntensity: 30, saturation: 1, contrast: 1, tint: '#ffffff', tintAmount: 0, vignette: 0.15, bloom: 0.3, bloomThreshold: 0.85,
+};
+/** The moods. Each is a whole light; a block names one and changes a few keys. */
+export const PRESETS: Record<string, Light> = {
+  dusk: { ...base, exposure: 1.05, key: '#ffc58f', keyIntensity: 2.6, keyElevation: 16, fill: '#6f7fc8', fillIntensity: 0.35, rim: '#ff9a6a', rimIntensity: 0.9, sky: '#c9a6c8', bounce: '#5a4636', ambient: 1, saturation: 1.1, contrast: 1.05, tint: '#ff9a5c', tintAmount: 0.06, vignette: 0.3, bloom: 0.5, bloomThreshold: 0.8 },
+  'moonlit-spot': { ...base, exposure: 0.95, key: '#a8b8e8', keyIntensity: 0.8, keyElevation: 55, keyAzimuth: -30, fill: '#3a4570', fillIntensity: 0.3, rim: '#8fa8ff', rimIntensity: 1.1, sky: '#4a5a8a', bounce: '#2a2632', ambient: 0.7, fogNear: 10, fogFar: 42, shadow: 'hard', spots: 3, spot: '#ffc870', spotIntensity: 80, saturation: 0.95, contrast: 1.15, tint: '#4060b0', tintAmount: 0.05, vignette: 0.55, bloom: 0.8, bloomThreshold: 0.7 },
+  overcast: { ...base, exposure: 1.1, key: '#e8eef2', keyIntensity: 0.9, keyElevation: 70, fill: '#c8d4dc', fillIntensity: 0.6, rimIntensity: 0.2, sky: '#d0d8e0', bounce: '#6a6c64', ambient: 1.8, fogNear: 14, fogFar: 58, saturation: 0.82, contrast: 0.95, tint: '#a0b4c0', tintAmount: 0.05, vignette: 0.12, bloom: 0, bloomThreshold: 1 },
+  studio: { ...base, key: '#ffffff', keyIntensity: 2.2, fill: '#ffffff', fillIntensity: 0.8, rim: '#ffffff', rimIntensity: 1.2, sky: '#e8e8ec', bounce: '#80807a', ambient: 0.9, fogNear: 60, fogFar: 200, vignette: 0.08, bloom: 0.2 },
+  noon: { ...base, key: '#fff4e0', keyIntensity: 3, keyElevation: 72, fill: '#9ec4ff', rimIntensity: 0.3, ambient: 1.4, fogNear: 30, fogFar: 90, shadow: 'hard', saturation: 1.1, contrast: 1.05, vignette: 0.12, bloom: 0.25 },
+  dawn: { ...base, key: '#ffd0c8', keyIntensity: 1.8, keyElevation: 10, keyAzimuth: -60, fill: '#8fb0e0', fillIntensity: 0.5, rim: '#ffe0a0', sky: '#e8c0c8', bounce: '#504650', ambient: 1.1, fogNear: 12, fogFar: 55, saturation: 0.95, tint: '#ff9fb0', tintAmount: 0.06, vignette: 0.22, bloom: 0.45 },
+};
+export const PRESET_NAMES = Object.keys(PRESETS);
+export const LIGHT_KEYS = Object.keys(base) as Array<keyof Light>;
+
+/** The light for a place: its preset (or the game's), the game's adjustments unless the place picked another mood, then the place's own. */
+export function resolveLight(game: LightBlock = {}, place: LightBlock = {}): Light & { preset: string } {
+  const preset = [place.preset, game.preset, 'dusk'].find((p): p is string => !!p && p in PRESETS) as string;
+  const own = (b: LightBlock) => Object.fromEntries(Object.entries(b).filter(([k, v]) => k !== 'preset' && k in base && typeof v === typeof (base as any)[k]));
+  const gameAdjusts = !place.preset || place.preset === (game.preset ?? 'dusk');
+  return { ...PRESETS[preset], ...(gameAdjusts ? own(game) : {}), ...own(place), preset };
+}
+
+export type Tier = 'phone' | 'desktop' | 'high';
+/** What `pickLevel` (@funpixel/sdk/device, past 0.6.0) decides from, and the same rule and storage key, so a quality menu set there works here. */
+export interface TierSignals { phone?: boolean; saveData?: boolean; deviceMemory?: number; gpuTier?: 'low' | 'mid' | 'high'; userSetting?: string | null }
+export function tierOf(s: TierSignals): Tier {
+  if (s.userSetting === 'phone' || s.userSetting === 'desktop' || s.userSetting === 'high') return s.userSetting;
+  if (s.phone || s.saveData || (s.deviceMemory !== undefined && s.deviceMemory <= 4) || s.gpuTier === 'low') return 'phone';
+  return s.gpuTier === 'high' && (s.deviceMemory === undefined || s.deviceMemory >= 8) ? 'high' : 'desktop';
+}
+export const QUALITY_KEY = 'funpixel.quality';
+
+/** What each tier may spend on light and dressing: a mid phone at 60 fps holds one shadow map, no bloom pass, half the small props. */
+export const TIERS: Record<Tier, { shadowMap: number; softShadows: boolean; spots: number; bloom: boolean; dressing: number; maxInstances: number }> = {
+  phone: { shadowMap: 1024, softShadows: false, spots: 1, bloom: false, dressing: 0.5, maxInstances: 6000 },
+  desktop: { shadowMap: 2048, softShadows: true, spots: 3, bloom: true, dressing: 1, maxInstances: 16000 },
+  high: { shadowMap: 2048, softShadows: true, spots: 4, bloom: true, dressing: 1, maxInstances: 24000 },
+};
+
+/** Where the key light sits (a unit vector) from its elevation and azimuth in degrees: the sky's sun or moon is drawn there too. */
+export function keyDirection(l: Pick<Light, 'keyElevation' | 'keyAzimuth'>): [number, number, number] {
+  const e = (l.keyElevation * Math.PI) / 180, a = (l.keyAzimuth * Math.PI) / 180;
+  return [Math.cos(e) * Math.sin(a), Math.sin(e), Math.cos(e) * Math.cos(a)];
+}
+
+
+/** A GPU class from the WebGL renderer string, by the SDK's rule (`gpuTier` in @funpixel/sdk/device). */
+export function gpuClass(r: string | null | undefined): 'low' | 'mid' | 'high' | undefined {
+  const s = (r ?? '').toLowerCase();
+  if (!s) return undefined;
+  if (/swiftshader|llvmpipe|softpipe|software|basic render/.test(s) || /mali|adreno|powervr|apple gpu|videocore|tegra/.test(s)) return 'low';
+  if (/geforce|nvidia|rtx|quadro|radeon( rx| pro)|apple m\d/.test(s)) return 'high';
+  return /intel|iris|uhd|radeon/.test(s) ? 'mid' : undefined;
+}

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

@@ -0,0 +1,77 @@
+// The light rig, driven by data (light-math.ts): a hemisphere (sky and ground bounce), one key that
+// casts the frame's only shadow map (its box follows the hero, sized by the tier), a fill from the
+// other side, a rim from behind, a few spot pools on the landmarks (the moonlit-spot look: the art
+// lit, the room in shadow), fog in the horizon colour, tone mapping and exposure. `apply(light)` moves
+// every value at once (a new place, a new mood) without making a light, so no shader recompiles.
+// The grade and bloom are post.ts. Values: src/look.json "light", each place's "light" (places.json).
+
+import * as THREE from 'three';
+import { keyDirection, TIERS, type Light, type Tier } from './light-math';
+
+const MAX_SPOTS = 4;
+
+export class LightRig {
+  readonly hemi = new THREE.HemisphereLight();
+  readonly key = new THREE.DirectionalLight();
+  readonly fill = new THREE.DirectionalLight();
+  readonly rim = new THREE.DirectionalLight();
+  readonly spots: THREE.SpotLight[] = [];
+  private dir = new THREE.Vector3(0, 1, 0);
+  light: Light | null = null;
+
+  constructor(private scene: THREE.Scene, private renderer: THREE.WebGLRenderer, readonly tier: Tier) {
+    const t = TIERS[tier];
+    renderer.toneMapping = THREE.ACESFilmicToneMapping; renderer.outputColorSpace = THREE.SRGBColorSpace;
+    renderer.shadowMap.enabled = true; renderer.shadowMap.type = t.softShadows ? THREE.PCFSoftShadowMap : THREE.PCFShadowMap;
+    this.key.castShadow = true; this.key.shadow.mapSize.set(t.shadowMap, t.shadowMap);
+    this.key.shadow.bias = -0.0006; this.key.shadow.normalBias = 0.02;
+    Object.assign(this.key.shadow.camera, { left: -14, right: 14, top: 14, bottom: -14, near: 1, far: 60 });
+    scene.add(this.hemi, this.key, this.key.target, this.fill, this.fill.target, this.rim, this.rim.target);
+    // The pools are made once, as many as the tier allows, and dimmed to 0 when a place has fewer:
+    // a light count that changes recompiles every lit material (a hitch on a phone).
+    for (let i = 0; i < Math.min(MAX_SPOTS, t.spots); i++) {
+      const s = new THREE.SpotLight('#ffffff', 0, 18, 0.55, 0.5, 1.4); s.castShadow = false;
+      this.spots.push(s); scene.add(s, s.target);
+    }
+    scene.fog = new THREE.Fog('#000000', 20, 70);
+  }
+
+  /** Set every light from one resolved light; `horizon` is the sky's horizon colour (the fog's colour). */
+  apply(l: Light, horizon: THREE.Color): void {
+    this.light = l;
+    this.renderer.toneMappingExposure = l.exposure;
+    this.hemi.color.set(l.sky); this.hemi.groundColor.set(l.bounce); this.hemi.intensity = l.ambient;
+    this.key.color.set(l.key); this.key.intensity = l.keyIntensity; this.key.castShadow = l.shadow !== 'off';
+    this.key.shadow.radius = l.shadow === 'hard' ? 1 : 4;
+    this.dir.set(...keyDirection(l));
+    this.fill.color.set(l.fill); this.fill.intensity = l.fillIntensity;
+    this.rim.color.set(l.rim); this.rim.intensity = l.rimIntensity;
+    const fog = this.scene.fog as THREE.Fog;
+    fog.color.copy(horizon); fog.near = l.fogNear; fog.far = l.fogFar;
+    this.spots.forEach((s, i) => { s.color.set(l.spot); s.intensity = i < l.spots ? l.spotIntensity : 0; });
+  }
+
+  /** Pools of light on these points (the landmarks, the art): a spot above each, aimed down. */
+  aimSpots(points: Array<{ x: number; y: number; z: number }>): void {
+    this.spots.forEach((s, i) => {
+      const p = points[i];
+      if (!p) { s.intensity = 0; return; }
+      s.position.set(p.x + 0.6, p.y + 6, p.z + 0.6); s.target.position.set(p.x, p.y, p.z);
+      if (this.light && i < this.light.spots) s.intensity = this.light.spotIntensity;
+    });
+  }
+
+  /** Keep the key's shadow box over the hero, fill and rim placed against it. Each frame. */
+  follow(x: number, z: number): void {
+    const d = this.dir;
+    this.key.position.set(x + d.x * 24, Math.max(4, d.y * 24), z + d.z * 24); this.key.target.position.set(x, 0, z);
+    this.fill.position.set(x - d.x * 20, 10, z - d.z * 20); this.fill.target.position.set(x, 0, z);
+    this.rim.position.set(x - d.z * 16, 6, z + d.x * 16 - 12); this.rim.target.position.set(x, 1, z);
+  }
+
+  /** What the state shows (state.world.light) and `funtools places` compares between places. */
+  facts(): Record<string, unknown> {
+    const l = this.light;
+    return l ? { preset: (l as Light & { preset?: string }).preset ?? null, exposure: l.exposure, key: l.key, keyIntensity: l.keyIntensity, ambient: l.ambient, fog: [l.fogNear, l.fogFar], spots: Math.min(l.spots, this.spots.length), shadow: this.key.castShadow && this.renderer.shadowMap.enabled, tier: this.tier } : {};
+  }
+}

package/templates/three-world/src/look.json

@@ -0,0 +1,30 @@
+{
+  "bg": "#1b2350",
+  "ink": "#fff6e8",
+  "primary": "#ffd36e",
+  "accent": "#ff9a5c",
+  "harm": "#ff5a4f",
+  "button-ink": "#3a1a12",
+  "sky-top": "#1b2350",
+  "sky-horizon": "#f0a073",
+  "ground": "#4a4436",
+  "ground-2": "#6e6a48",
+  "stone": "#9b8a78",
+  "hero": "#f4efe4",
+  "hero-accent": "#e2553f",
+  "key-light": "#ffe2c0",
+  "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": "#fff6e8",
+  "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": "#ffd36e",
+  "icon-stroke": 2.4,
+  "font-display": "'Lilita One', 'Trebuchet MS', sans-serif",
+  "font-body": "'Nunito', 'Trebuchet MS', sans-serif",
+  "light": {
+    "preset": "dusk"
+  }
+}

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

@@ -0,0 +1,38 @@
+// The faces the UI is set in, bundled with the game (no font request at play time): the display face for
+// the wordmark, banners and numbers, the body face for the rest. Swap them in package.json and here, and
+// keep funpixel.json's metadata.fonts naming them so verify checks they load.
+import '@fontsource/lilita-one/400.css';
+import '@fontsource/nunito/700.css';
+import '@fontsource/nunito/800.css';
+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 (
+    <>
+      {/* The 3D world is the whole play; the HUD and the thumbs float over it (data-fpx-play: look measures it). */}
+      <div ref={stage} class="stage" data-fpx-play />
+      <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/three-world/src/models.ts

@@ -0,0 +1,62 @@
+// Models: a .glb at the conventional path replaces its placeholder with no code (public/assets/models/
+// <name>.glb; skill funpixel-3d). The placeholder rule: every placeholder is a DESIGNED shape in the
+// palette (a figure with a face and a direction, a lit crystal), never a magenta box or an error cube, so a
+// first build reads as a game; and each one is named in state.art.placeholders until its model lands, so a
+// placeholder never ships unseen. A model that fails to load logs why and keeps its placeholder.
+
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { findAsset } from './assets';
+import { PALETTE } from './palette';
+
+/** The models still drawn as placeholders (state.art.placeholders). */
+export const placeholders = new Set<string>();
+const std = (color: THREE.Color, o: Partial<THREE.MeshStandardMaterialParameters> = {}) => new THREE.MeshStandardMaterial({ color, roughness: 0.8, ...o });
+
+// Platform GLBs are Draco (static) or meshopt (rigged) with KTX2 textures: all three decoders. Since three r180
+// the Draco and Basis loaders default to decoders bundled from the package (`new URL(…, import.meta.url)`), so
+// vite ships them same-origin with no path to set; a hand-set path that 404s answers with index.html and hangs.
+export const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).setDRACOLoader(new DRACOLoader());
+/** KTX2 needs the renderer to pick a format: game.ts calls this once the renderer exists, before any model loads. */
+export const useRenderer = (r: THREE.WebGLRenderer): void => { loader.setKTX2Loader(new KTX2Loader().detectSupport(r)); };
+
+/** A model `height` metres tall standing on y = 0, from its .glb when there is one, else `placeholder()`. */
+export async function model(name: string, height: number, placeholder: () => THREE.Object3D): Promise<() => THREE.Object3D> {
+  const url = await findAsset('models', name);
+  const gltf = url ? await loader.loadAsync(url).catch((e) => { console.warn(`${url} did not load; drawing the placeholder`, e); return null; }) : null;
+  if (!gltf) placeholders.add(name);
+  return () => {
+    if (!gltf) return placeholder();
+    const m = gltf.scene.clone(true), box = new THREE.Box3().setFromObject(m), size = box.getSize(new THREE.Vector3());
+    m.scale.setScalar(height / Math.max(size.y, 1e-6));
+    m.position.y = -box.min.y * m.scale.y;
+    // A skinned mesh's bounds are its bind pose: an animated limb leaves them and the mesh vanishes at the frame's
+    // edge. One hero is cheap to never cull; a crowd gets real bounds instead.
+    m.traverse((o) => { if ((o as THREE.Mesh).isMesh) o.castShadow = true; if ((o as THREE.SkinnedMesh).isSkinnedMesh) o.frustumCulled = false; });
+    return new THREE.Group().add(m);
+  };
+}
+
+/** The hero's placeholder: a rounded body, a head, eyes and a scarf, so its facing and its squash read. */
+export function heroPlaceholder(): THREE.Object3D {
+  const g = new THREE.Group(), skin = std(PALETTE.hero), accent = std(PALETTE.heroAccent), dark = std(new THREE.Color('#1c1a24'), { roughness: 0.3 });
+  const body = new THREE.Mesh(new THREE.CapsuleGeometry(0.3, 0.35, 6, 14), skin); body.position.y = 0.48;
+  const head = new THREE.Mesh(new THREE.SphereGeometry(0.24, 20, 14), skin); head.position.y = 0.92;
+  const scarf = new THREE.Mesh(new THREE.TorusGeometry(0.22, 0.07, 8, 20), accent); scarf.rotation.x = Math.PI / 2; scarf.position.y = 0.74;
+  const tail = new THREE.Mesh(new THREE.BoxGeometry(0.12, 0.05, 0.36), accent); tail.position.set(0.1, 0.72, -0.28); tail.rotation.x = 0.5;
+  for (const side of [-1, 1]) { const eye = new THREE.Mesh(new THREE.SphereGeometry(0.045, 10, 8), dark); eye.position.set(0.09 * side, 0.95, 0.21); g.add(eye); }
+  g.add(body, head, scarf, tail);
+  g.traverse((o) => { o.castShadow = true; });
+  return g;
+}
+
+/** A pickup's placeholder: a glowing crystal on a soft halo. */
+export function pickupPlaceholder(): THREE.Object3D {
+  const gem = new THREE.Mesh(new THREE.OctahedronGeometry(0.3), std(PALETTE.pickup, { emissive: PALETTE.pickup, emissiveIntensity: 0.9, roughness: 0.3, flatShading: true }));
+  const halo = new THREE.Mesh(new THREE.TorusGeometry(0.42, 0.03, 6, 28), new THREE.MeshBasicMaterial({ color: PALETTE.pickup, transparent: true, opacity: 0.55 }));
+  halo.rotation.x = Math.PI / 2; halo.position.y = -0.35;
+  return new THREE.Group().add(gem, halo);
+}

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

@@ -0,0 +1,21 @@
+// The world's colours come from the same tokens as the UI (styles.css :root), so one edit restyles the
+// sky, the fog, the ground and the screens together. Each is read once at start; the fog is always the
+// sky's horizon colour, so the far edge of the world melts into the sky instead of ending in a line.
+
+import * as THREE from 'three';
+
+const css = typeof getComputedStyle === 'function' ? getComputedStyle(document.documentElement) : null;
+const token = (name: string, fallback: string) => new THREE.Color((css?.getPropertyValue(name).trim() || fallback));
+
+export const PALETTE = {
+  skyTop: token('--sky-top', '#1b2350'),
+  horizon: token('--sky-horizon', '#f0a073'),
+  ground: token('--ground', '#3d4a3a'),
+  ground2: token('--ground-2', '#5e6c45'),
+  stone: token('--stone', '#9b8a78'),
+  hero: token('--hero', '#f4efe4'),
+  heroAccent: token('--hero-accent', '#e2553f'),
+  pickup: token('--primary', '#ffd36e'),
+  harm: token('--harm', '#ff5a4f'),
+  key: token('--key-light', '#ffe2c0'),
+};

package/templates/three-world/src/places.json

@@ -0,0 +1,50 @@
+{
+  "$comment": "The places as data (the GDD's ## Places rows): each its own light (a mood preset and a few changed keys, light-math.ts), palette, ground surface, dressing kit with a density target (things per 100 m², what funtools boxes measures), a landmark and the road kept clear to it. Round N plays place N mod the count. Skill funpixel-3d, references/light-and-places.md.",
+  "places": [
+    {
+      "id": "square", "name": "The Square at dusk",
+      "light": { "preset": "dusk" },
+      "palette": { "sky-top": "#1b2350", "sky-horizon": "#f0a073", "ground": "#4f5a34", "ground-2": "#7c8a44", "stone": "#9b8a78", "accent": "#ffd36e", "glow": "#ffcf7a" },
+      "surface": "grass", "density": 150,
+      "kit": [
+        { "role": "ground", "kind": "tuft", "density": 120, "scale": [0.7, 1.4], "clump": 0.7, "patch": 4, "roadside": 0.4 },
+        { "role": "ground", "kind": "flower", "density": 30, "scale": [0.8, 1.3], "clump": 0.85, "patch": 2.5, "roadside": 0.6 },
+        { "role": "mid", "kind": "rock", "density": 1.2, "scale": [0.6, 1.8], "clump": 0.5, "patch": 6 },
+        { "role": "mid", "kind": "bush", "density": 2, "scale": [0.7, 1.5], "clump": 0.6, "patch": 5, "roadside": 0.5 },
+        { "role": "mid", "kind": "tree", "density": 0.8, "scale": [1, 2.2], "clump": 0.6, "patch": 9 },
+        { "role": "life", "kind": "lantern", "count": 10, "scale": [1, 1.2], "roadside": 1 }
+      ],
+      "landmark": { "kind": "column", "at": [0, -34], "scale": 2.6 },
+      "road": { "to": [0, -34], "width": 2.6 }
+    },
+    {
+      "id": "grove", "name": "The Grey Grove",
+      "light": { "preset": "overcast" },
+      "palette": { "sky-top": "#6f7f86", "sky-horizon": "#c9d2d0", "ground": "#3e4a3a", "ground-2": "#5f7a52", "stone": "#7c8580", "accent": "#d8e6a0", "glow": "#e8f0c8" },
+      "surface": "moss", "density": 115,
+      "kit": [
+        { "role": "ground", "kind": "tuft", "density": 90, "scale": [0.8, 1.6], "clump": 0.8, "patch": 5, "roadside": 0.3 },
+        { "role": "ground", "kind": "reeds", "density": 18, "scale": [0.8, 1.5], "clump": 0.9, "patch": 3 },
+        { "role": "mid", "kind": "bush", "density": 4, "scale": [0.8, 1.8], "clump": 0.7, "patch": 6, "roadside": 0.4 },
+        { "role": "mid", "kind": "tree", "density": 2.4, "scale": [1.2, 2.6], "clump": 0.7, "patch": 10 },
+        { "role": "mid", "kind": "rock", "density": 1.5, "scale": [0.6, 2], "clump": 0.4, "patch": 6 }
+      ],
+      "landmark": { "kind": "tree", "at": [-6, -32], "scale": 5 },
+      "road": { "to": [-6, -32], "width": 2.2 }
+    },
+    {
+      "id": "court", "name": "The Moon Court",
+      "light": { "preset": "moonlit-spot" },
+      "palette": { "sky-top": "#070b1c", "sky-horizon": "#26305a", "ground": "#3a3a48", "ground-2": "#4c4a5a", "stone": "#b8b0a0", "accent": "#9db4d6", "glow": "#ffc870" },
+      "surface": "flagstone", "density": 40,
+      "kit": [
+        { "role": "ground", "kind": "tuft", "density": 40, "scale": [0.6, 1.1], "clump": 0.9, "patch": 2, "roadside": 0.8 },
+        { "role": "mid", "kind": "column", "density": 0.6, "scale": [0.8, 1.3], "clump": 0.3, "patch": 8 },
+        { "role": "mid", "kind": "rock", "density": 1, "scale": [0.5, 1.4], "clump": 0.6, "patch": 4 },
+        { "role": "life", "kind": "lantern", "count": 6, "scale": [1, 1.3], "roadside": 1 }
+      ],
+      "landmark": { "kind": "column", "at": [4, -30], "scale": 3.2 },
+      "road": { "to": [4, -30], "width": 3 }
+    }
+  ]
+}

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

@@ -0,0 +1,56 @@
+// The places, as places.json lists them (stage.ts imports the file; this part is engine-free and the tests run it): each place's
+// light resolved against the game's look.json "light", its kit split into what dresses the play
+// (ground cover and life, never on the road or a solid) and what dresses beyond it (mid props, trees,
+// the landmark), its road from the play to the landmark, and its density target. Round N plays place
+// N mod the count; the views place-<id> enter one directly (expose.ts), so `funtools places` can set
+// every place side by side. Grow the list here, from the GDD's ## Places rows.
+
+import { ARENA } from './layout';
+import { resolveLight, type LightBlock } from './light-math';
+import type { Kit, Ring, Road, Slot } from './dressing-math';
+
+export interface Place {
+  id: string; name: string; light: LightBlock; palette: Record<string, string>; surface: string;
+  /** Things per 100 m² the place is dressed to: what `funtools boxes` measures against. */
+  density: number; kit: Slot[];
+  landmark: { kind: string; at: [number, number]; scale: number };
+  road: { to: [number, number]; width: number };
+  /** The place's target picture, when the plan has one (`funtools places` sets it beside the view). */
+  target?: string;
+}
+
+/** How far past the play the dressing reaches (m): inside the fog, so the world never ends in a line. */
+export const REACH = 30;
+
+export const placeFor = (list: Place[], round: number): Place => list[((round % list.length) + list.length) % list.length];
+
+/** The two dressing passes of a place: the play (small things only) and beyond its edge. */
+export function passes(p: Place): Array<{ kit: Kit; ring: Ring }> {
+  const play = p.kit.filter((s) => s.role === 'ground' || s.role === 'life'), far = p.kit.filter((s) => s.role === 'mid');
+  return [
+    { kit: { slots: play }, ring: { x: 0, z: 0, inner: 0, outer: ARENA + REACH } },
+    { kit: { slots: far }, ring: { x: 0, z: 0, inner: ARENA + 2, outer: ARENA + REACH } },
+  ];
+}
+export const roadOf = (p: Place): Road => ({ pts: [[0, 0], p.road.to], width: p.road.width });
+/** The ring a place's density is measured over (the whole dressed disc). */
+export const ringOf = (): Ring => ({ x: 0, z: 0, inner: 0, outer: ARENA + REACH });
+
+/** The place's light against the game's look block. */
+export const lightOf = (p: Place, game: LightBlock | undefined) => resolveLight(game ?? {}, p.light);
+
+/** Problems in the list, as words (a selftest and `funtools places` read them): a place with no id, a duplicate, an unknown preset. */
+export function placeProblems(list: Place[], presets: string[]): string[] {
+  const out: string[] = [], seen = new Set<string>();
+  for (const p of list) {
+    if (!p.id) out.push('a place without an id');
+    else if (seen.has(p.id)) out.push(`two places are called ${p.id}`);
+    seen.add(p.id);
+    if (p.light?.preset && !presets.includes(p.light.preset)) out.push(`${p.id}: light preset ${p.light.preset} is not one of ${presets.join(', ')}`);
+    if (!(p.density > 0)) out.push(`${p.id}: no density target`);
+  }
+  return out;
+}
+
+/** The bridge between the stage and the hooks: the place a view asked for, and the stage's facts (state.world). */
+export const world = { request: null as string | null, round: 0, facts: (): Record<string, unknown> => ({}) };

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

@@ -0,0 +1,22 @@
+// What a renderer draws beyond position: the hero's key pose for each of its states, engine-free, so
+// `funtools feel` sees one look per state (research 18: the hits draw each state; Dead Cells' rule, the
+// fewest keys that read). Applied on top of the juice's squash and the living layer's breath. A rigged
+// model plays clips by the same states instead (character.ts: gaitClip).
+
+import type { Run } from './rules';
+
+export interface HeroPose {
+  /** Forward lean in radians (into speed), a topple (the death beat), and a stretch on top of the squash. */
+  lean: number; topple: number; sx: number; sy: number;
+}
+
+/** Leaning into a run, stretched rising, a little squashed falling, toppled when dead. */
+export function heroPose(state: string, run: Run): HeroPose {
+  const speed = Math.hypot(run.vx, run.vz);
+  if (state === 'dead') return { lean: 0, topple: -Math.PI / 2, sx: 1, sy: 1 };
+  if (state === 'jump') return { lean: 0.1, topple: 0, sx: 0.9, sy: 1.12 };
+  if (state === 'fall') return { lean: 0.05, topple: 0, sx: 1.04, sy: 0.97 };
+  if (state === 'dash') return { lean: 0.35, topple: 0, sx: 0.92, sy: 1.04 };
+  if (state === 'run') return { lean: Math.min(0.25, speed * 0.035), topple: 0, sx: 1, sy: 1 };
+  return { lean: 0, topple: 0, sx: 1, sy: 1 };
+}

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

@@ -0,0 +1,47 @@
+// The post stack, sized by the tier. Every tier gets the grade (saturation, contrast, tint, vignette:
+// common grade.ts, a CSS layer the compositor applies, so a phone pays nothing for it). Desktop and
+// high add bloom on what is brighter than the threshold (the lanterns, the pickups, the sun), at half
+// resolution, before tone mapping (OutputPass, last). A phone that runs long sheds bloom first, before
+// shadows and the pixel ratio (budget.ts). Values: the resolved light (light-math.ts).
+
+import * as THREE from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
+import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js';
+import { applyGrade, gradeOf } from './grade';
+import { TIERS, type Light, type Tier } from './light-math';
+import { shedders } from './budget';
+
+export class Post {
+  private composer: EffectComposer | null = null;
+  private bloom: UnrealBloomPass | null = null;
+
+  constructor(private renderer: THREE.WebGLRenderer, private scene: THREE.Scene, private camera: THREE.Camera, private host: HTMLElement, tier: Tier) {
+    if (!TIERS[tier].bloom) return;
+    const size = renderer.getSize(new THREE.Vector2());
+    this.composer = new EffectComposer(renderer);
+    this.composer.addPass(new RenderPass(scene, camera));
+    this.bloom = new UnrealBloomPass(new THREE.Vector2(size.x / 2, size.y / 2), 0.5, 0.4, 0.85);
+    this.composer.addPass(this.bloom);
+    this.composer.addPass(new OutputPass());
+    shedders.push(() => { if (!this.bloom?.enabled) return false; this.bloom.enabled = false; return true; });
+  }
+
+  /** Apply a light's grade and bloom (a new place, a new mood). */
+  apply(l: Light): void {
+    applyGrade(this.host, gradeOf(l as unknown as Record<string, unknown>));
+    if (this.bloom) { this.bloom.strength = l.bloom; this.bloom.threshold = l.bloomThreshold; this.bloom.enabled = l.bloom > 0; }
+  }
+
+  setSize(w: number, h: number): void {
+    this.composer?.setSize(w, h); this.composer?.setPixelRatio(this.renderer.getPixelRatio());
+    this.bloom?.resolution.set(w / 2, h / 2);
+  }
+
+  render(): void {
+    if (this.composer && this.bloom?.enabled) this.composer.render(); else this.renderer.render(this.scene, this.camera);
+  }
+
+  facts(): Record<string, unknown> { return { bloom: !!this.bloom?.enabled, grade: this.host.dataset.fpxGrade ? JSON.parse(this.host.dataset.fpxGrade) : null }; }
+}

package/templates/three-world/src/rest-math.ts

@@ -0,0 +1,29 @@
+// Where a drawn thing rests on the terrain, engine-free (the tests run it): its footprint's corners as placed and
+// the lowest point that the kit's world read (funtools boxes and walk, the grounding probe) calls standing on the
+// ground. dressing.ts applies it to every instance of the dressing and the landmark. Skill funpixel-3d.
+
+/** Where the lowest point of a drawn thing of height `h` rests once its shape is known, from the ground under its footprint's corners and
+ * centre (as placed: turned and scaled). The kit's world read (funtools boxes and walk, the grounding probe) judges a big
+ * prop by those points: it must touch the ground at one (within max(0.25 m, 3% of h)), go more than max(0.5 m, 35% of h)
+ * into it at fewer than half, and hang more than max(1.5 m, 40% of h) over it at fewer than half of those it stands
+ * over. The lowest point that holds all three, so a slope buries the uphill side a little and floats the downhill side
+ * as little as it can. Grounded at its trunk, a tree's canopy hovered over the downhill side of a slope ("dress-mid-tree
+ * hovers 0.66 m", a fresh game's own world read); grounded at its lowest corner, a wide bush sank into the uphill one. */
+export function restOn(ground: number[], h: number): number {
+  // A quarter inside each line: the world read samples the drawn ground mesh, a few centimetres off this function.
+  const touch = Math.max(0.25, 0.03 * h), sink = 0.75 * Math.max(0.5, 0.35 * h), drop = 0.75 * Math.max(1.5, 0.4 * h);
+  const s = [...ground].sort((a, b) => a - b);
+  for (const at of s) {
+    const y = at - 0.03;
+    const sunk = s.filter((g) => g > y + sink).length;
+    const over = s.filter((g) => g <= y + touch), hung = over.filter((g) => y - g > drop).length;
+    if (sunk * 2 < s.length && !(over.length >= 2 && hung * 2 >= over.length)) return y;
+  }
+  return s[Math.floor(s.length / 2)] - 0.03;
+}
+
+/** The four corners of a footprint `[x0, x1, z0, z1]` (the shape's own bounds at scale 1) placed at (x, z), turned and scaled. */
+export function cornersOf(foot: [number, number, number, number], x: number, z: number, turn: number, scale: number): Array<[number, number]> {
+  const [x0, x1, z0, z1] = foot, c = Math.cos(turn), s = Math.sin(turn);
+  return ([[x0, z0], [x1, z0], [x0, z1], [x1, z1]] as Array<[number, number]>).map(([px, pz]) => [x + (px * c + pz * s) * scale, z + (-px * s + pz * c) * scale]);
+}

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

@@ -0,0 +1,89 @@
+// The game's rules, engine-free (no Three, no DOM): the renderer draws this state and the self-tests and
+// test/probes.ts play it offline, so a rule is testable without a frame. Grow the game here first. A small
+// 3D round: run and jump around a lit square, collect GOAL pickups before the clock runs out. From
+// FLARE_FIRST s a ring glows under the hero (the tell), then flares along the ground: jump over it or run
+// out of it. Units are metres and seconds; the hero is BODY tall. random() is seeded (__FPX_SEED__ + n).
+
+import { ARENA, floorAt, layout, pushOut, random, type Box, type Pickup, type Post } from './layout';
+
+export const BODY = 1, GOAL = 16, ROUND_SECONDS = 45, PICK_RADIUS = 1;
+/** The character's feel, one table (skill funpixel-game-feel): speeds m/s, rates m/s², times s, heights m.
+ *  Forgiveness as Celeste does it: coyote (a jump just after a ledge still counts) and a buffer (a press
+ *  just before landing fires on landing), 0.1 s each. A released jump cuts the rise (a tap hops low). */
+export const MOVE = {
+  run: 6.5, accel: 42, decel: 32, air: 0.6, turn: 14,
+  jumpHeight: 1.6, apex: 0.36, fallBoost: 1.5, release: 2.5, coyote: 0.1, buffer: 0.1,
+  dash: 15, dashTime: 0.16, dashCool: 0.7, radius: 0.35, step: 0.3,
+} as const;
+const G = (2 * MOVE.jumpHeight) / MOVE.apex ** 2, V0 = (2 * MOVE.jumpHeight) / MOVE.apex;
+/** The flare: glows FLARE_TELL s, burns FLARE_BURN s up to FLARE_HIGH m off its ground within FLARE_R m; a
+ *  hit lands only FLARE_LATE s after it lights, so a jump that late still saves. */
+export const FLARE_TELL = 0.7, FLARE_BURN = 0.25, FLARE_LATE = 0.1, FLARE_R = 1.5, FLARE_HIGH = 0.5, FLARE_FIRST = 8, FLARE_EVERY = 2.5;
+
+export interface Run {
+  x: number; y: number; z: number; vx: number; vy: number; vz: number; heading: number;
+  grounded: boolean; coyote: number; buffer: number; dashT: number; dashCool: number; jumps: number;
+  score: number; timeLeft: number; boxes: Box[]; posts: Post[]; pickups: Pickup[];
+  flare: { x: number; y: number; z: number; t: number } | null; nextFlare: number; seed: number;
+}
+/** What the player asks for this frame: a world direction (length ≤ 1), the jump held, and presses. */
+export interface Input { x: number; z: number; held?: boolean; jump?: boolean; dash?: boolean }
+export interface Ev { type: 'jump' | 'land' | 'pickup' | 'tell' | 'dash' | 'bump'; x: number; y: number; z: number; power?: number }
+export type Outcome = 'won' | 'lost' | null; export type Phase = 'rest' | 'tell' | 'burn';
+
+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 s = { seed }, world = layout(s, GOAL);
+  return { x: 0, y: 0, z: 0, vx: 0, vy: 0, vz: 0, heading: Math.PI, grounded: true, coyote: 0, buffer: 0, dashT: 0, dashCool: 0, jumps: 0,
+    score: 0, timeLeft: ROUND_SECONDS, ...world, flare: null, nextFlare: FLARE_FIRST, seed: s.seed };
+}
+/** Ask for a jump: it fires now when on the ground (or within coyote time), else when it lands within the buffer. */
+export const jump = (run: Run): void => { run.buffer = MOVE.buffer; };
+export function dash(run: Run): boolean { if (run.dashCool > 0) return false; run.dashT = MOVE.dashTime; run.dashCool = MOVE.dashCool; return true; }
+export const phase = (run: Run): Phase => (!run.flare ? 'rest' : run.flare.t < FLARE_TELL ? 'tell' : 'burn');
+export const inReach = (run: Run, x = run.x, z = run.z): boolean => !!run.flare && Math.hypot(x - run.flare.x, z - run.flare.z) < FLARE_R;
+export const burning = (run: Run): boolean => !!run.flare && run.flare.t >= FLARE_TELL + FLARE_LATE && inReach(run) && run.y - run.flare.y < FLARE_HIGH && run.y > run.flare.y - 0.3; // a flare on a platform burns its top, not the ground below
+const turnTo = (a: number, b: number, max: number) => { const d = Math.atan2(Math.sin(b - a), Math.cos(b - a)); return a + Math.max(-max, Math.min(max, d)); };
+
+/** Advance in steps of at most 1/120 s; the events this frame and 'won'/'lost' when the round ends. */
+/** Metres from the hero to the nearest pickup still there (the objective's distance), or null when none is left. */
+export function nearestPickup(run: Run): number | null {
+  let best = Infinity;
+  for (const p of run.pickups) if (!p.taken) best = Math.min(best, Math.hypot(p.x - run.x, p.z - run.z));
+  return Number.isFinite(best) ? best : null;
+}
+
+export function tick(run: Run, input: Input, dt: number): { events: Ev[]; outcome: Outcome } {
+  const events: Ev[] = [], at = (type: Ev['type'], power?: number) => events.push({ type, x: run.x, y: run.y, z: run.z, power });
+  if (input.jump) jump(run);
+  if (input.dash && dash(run)) at('dash');
+  const n = Math.max(1, Math.ceil(dt * 120 - 1e-6)), h = dt / n, len = Math.min(1, Math.hypot(input.x, input.z)), held = input.held ?? true;
+  for (let k = 0; k < n; k++) {
+    run.coyote -= h; run.buffer -= h; run.dashCool -= h; run.dashT -= h;
+    if (len > 0.1) run.heading = turnTo(run.heading, Math.atan2(input.x, input.z), MOVE.turn * h);
+    if (run.dashT > 0) { run.vx = Math.sin(run.heading) * MOVE.dash; run.vz = Math.cos(run.heading) * MOVE.dash; } else {
+      const k2 = len > 0.1 ? 1 / Math.hypot(input.x, input.z) : 0, tx = input.x * k2 * len * MOVE.run, tz = input.z * k2 * len * MOVE.run;
+      const rate = (len > 0.1 ? MOVE.accel : MOVE.decel) * (run.grounded ? 1 : MOVE.air) * h, dx = tx - run.vx, dz = tz - run.vz, d = Math.hypot(dx, dz);
+      if (d <= rate) { run.vx = tx; run.vz = tz; } else { run.vx += (dx / d) * rate; run.vz += (dz / d) * rate; }
+    }
+    if (run.buffer > 0 && (run.grounded || run.coyote > 0)) { run.vy = V0; run.grounded = false; run.coyote = 0; run.buffer = 0; run.jumps++; at('jump'); }
+    run.vy -= G * h * (run.vy < 0 ? MOVE.fallBoost : held ? 1 : MOVE.release);
+    run.x += run.vx * h; run.z += run.vz * h;
+    if (pushOut(run, run.y, MOVE.radius, MOVE.step, run.boxes, run.posts) && Math.hypot(run.vx, run.vz) < 1 && len > 0.5 && run.dashT > 0) at('bump');
+    const r = Math.hypot(run.x, run.z); if (r > ARENA) { run.x *= ARENA / r; run.z *= ARENA / r; }
+    const floor = floorAt(run.boxes, run.x, run.z, run.y, MOVE.step, MOVE.radius * 0.5);
+    run.y += run.vy * h;
+    if (run.y <= floor) { if (!run.grounded) at('land', -run.vy); run.y = floor; run.vy = 0; run.grounded = true; }
+    else if (run.grounded && run.y - floor > MOVE.step) { run.grounded = false; run.coyote = MOVE.coyote; } // walked off a ledge
+    else if (run.grounded) { run.y = floor; run.vy = 0; }
+    for (const p of run.pickups) if (!p.taken && Math.hypot(p.x - run.x, p.z - run.z) < PICK_RADIUS && Math.abs(run.y + BODY / 2 - p.y) < 1) { p.taken = true; run.score++; at('pickup'); }
+    if (run.score >= GOAL) return { events, outcome: 'won' };
+    if (!run.flare && (run.nextFlare -= h) <= 0) { run.flare = { x: run.x, y: run.grounded ? run.y : floorAt(run.boxes, run.x, run.z, run.y, 0, 0), z: run.z, t: 0 }; at('tell'); }
+    else if (run.flare && (run.flare.t += h) >= FLARE_TELL) {
+      if (burning(run)) return { events, outcome: 'lost' };
+      if (run.flare.t >= FLARE_TELL + FLARE_BURN) { run.flare = null; run.nextFlare = FLARE_EVERY + random(run); }
+    }
+    if ((run.timeLeft = run.timeLeft - h <= 1e-6 ? 0 : run.timeLeft - h) === 0) return { events, outcome: 'lost' };
+  }
+  return { events, outcome: null };
+}