@funpixel/tools 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,43 @@
+// A sharp player through the real rules, engine-free: runs out of a glowing flare (jumping late in the
+// glow when it cannot clear it), else to the nearest pickup, jumping up to the ones on platforms and over
+// whatever stops it. The self-tests, the win view and test/probes.ts all play with it.
+
+import { FLARE_LATE, FLARE_R, FLARE_TELL, MOVE, tick, type Input, type Outcome, type Run } from './rules';
+
+const nearest = (run: Run) => {
+  let best = null as Run['pickups'][number] | null, cost = Infinity;
+  for (const p of run.pickups) {
+    if (p.taken || (run.flare && Math.hypot(p.x - run.flare.x, p.z - run.flare.z) < FLARE_R + 1)) continue; // never into a lit ring
+    const c = Math.hypot(p.x - run.x, p.z - run.z) + 3 * Math.max(0, p.y - run.y - 1);
+    if (c < cost) { cost = c; best = p; }
+  }
+  return best;
+};
+
+/** What a sharp player presses now. */
+export function bestInput(run: Run): Input {
+  const f = run.flare;
+  if (f && Math.hypot(run.x - f.x, run.z - f.z) < FLARE_R + MOVE.radius) {
+    // Run out when there is time to; jump late in the glow only when there is not (never up into a ring lit on a platform).
+    const dx = run.x - f.x || 0.01, dz = run.z - f.z, d = Math.hypot(dx, dz), escape = (FLARE_R + MOVE.radius - d) / MOVE.run < FLARE_TELL + FLARE_LATE - f.t - 0.1;
+    return { x: dx / d, z: dz / d, jump: run.grounded && !escape && f.y <= run.y + 0.2 && f.t > FLARE_TELL - 0.12 };
+  }
+  const p = nearest(run);
+  if (!p) return { x: 0, z: 0 };
+  const dx = p.x - run.x, dz = p.z - run.z, d = Math.hypot(dx, dz) || 1;
+  const up = p.y - 0.6 > run.y + 0.1 && d < 2.6, stuck = run.grounded && Math.hypot(run.vx, run.vz) < 1 && d > 1.5;
+  const nearFlare = !!f && Math.hypot(run.x - f.x, run.z - f.z) < FLARE_R + 2.5;
+  return { x: dx / d, z: dz / d, jump: run.grounded && !nearFlare && (up || stuck) };
+}
+
+/** Play a round through the rules: the sharp player deciding every `react` seconds, or never (null). */
+export function botRound(run: Run, react: number | null, limit = 600): Outcome {
+  let input: Input = { x: 0, z: 0 }, wait = 0;
+  for (let t = 0; t < limit; t += 1 / 30) {
+    if (react !== null && (wait -= 1 / 30) <= 0) { input = bestInput(run); wait = react; }
+    const { outcome } = tick(run, input, 1 / 30);
+    input = { ...input, jump: false };
+    if (outcome) return outcome;
+  }
+  return null;
+}

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

@@ -0,0 +1,73 @@
+// The performance budget, as data the game keeps and the probe reads (state.render): a mid phone holds 60
+// fps when a frame stays under ~120 draw calls and ~300k triangles at a pixel ratio of at most 1.5. The
+// pixel ratio steps down by itself when frames run long (and the shadows go first), and back up when there
+// is room. `funtools profile` and `look --hud` read the same facts. Raise a number only after measuring.
+// The quality tier follows the GPU, never the pointer: a desktop window in
+// touch emulation reports a coarse pointer and would get the phone's budget. The touch LAYOUT still follows
+// the pointer (controls.tsx). The GPU's name rides in state.render too: a frame time means nothing without
+// it (headless Chrome draws on SwiftShader, no GPU).
+
+import type * as THREE from 'three';
+import { gpuClass, QUALITY_KEY, tierOf, type Tier } from './light-math';
+
+export const BUDGET = {
+  /** Draw calls and triangles a frame may cost; a frame over either is logged once. */
+  calls: 120, triangles: 300_000,
+  /** The pixel ratio's ceiling on a phone-class GPU (phones report 3; 1.5 looks sharp and costs a quarter of 3), on a desktop GPU, and the floor. */
+  maxRatio: 1.5, desktopRatio: 2, minRatio: 0.75,
+  /** The frame time (ms) that counts as long, how many seconds of long frames step down, and the step. */
+  slowMs: 20, slowFor: 1.5, step: 0.25,
+} as const;
+
+/** GPU families that mean a phone or a tablet (iOS, and Safari on a Mac, say only "Apple GPU": there the pointer is fine). */
+const MOBILE_GPU = /adreno|mali|powervr|apple gpu|immortalis|xclipse|videocore|tegra|sgx/i;
+/** A phone-class device (pure: the tests call it): a fine pointer never is; a coarse one is unless its GPU is a desktop's. */
+export const phoneClass = (gpu: string | null, coarse: boolean): boolean => coarse && !(gpu && !MOBILE_GPU.test(gpu));
+
+/** Costs a slow phone sheds before the shadows and the pixel ratio (post.ts adds bloom): each returns true when it shed something. */
+export const shedders: Array<() => boolean> = [];
+
+let renderer: THREE.WebGLRenderer | null = null, ratio: number = BUDGET.maxRatio, cap: number = BUDGET.maxRatio, gpu: string | null = null;
+let slow = 0, fast = 0, fps = 60, warned = false;
+
+export const budget = {
+  /** Take the renderer: cap its pixel ratio and let info count across render calls. */
+  attach(r: THREE.WebGLRenderer): void {
+    renderer = r;
+    try { const gl = r.getContext(), ext = gl.getExtension('WEBGL_debug_renderer_info'); gpu = String(gl.getParameter(ext ? ext.UNMASKED_RENDERER_WEBGL : gl.RENDERER)); } catch { gpu = null; }
+    const coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+    cap = phoneClass(gpu, coarse) ? BUDGET.maxRatio : BUDGET.desktopRatio; ratio = Math.min(devicePixelRatio || 1, cap);
+    r.setPixelRatio(ratio); r.info.autoReset = false;
+  },
+  /** Once a frame, before rendering: zero the counters (a probe reading between frames sees the last whole frame). */
+  begin(): void { renderer?.info.reset(); },
+  /** Once a frame, after rendering: read the cost and adapt the pixel ratio. */
+  frame(dt: number): void {
+    if (!renderer) return;
+    const ms = dt * 1000, info = renderer.info.render;
+    fps += (1 / Math.max(dt, 1e-3) - fps) * 0.05;
+    if (!warned && (info.calls > BUDGET.calls || info.triangles > BUDGET.triangles)) {
+      warned = true;
+      console.warn(`budget: ${info.calls} draw calls / ${info.triangles} triangles (budget ${BUDGET.calls} / ${BUDGET.triangles}); merge or instance (budget.ts)`);
+    }
+    slow = ms > BUDGET.slowMs ? slow + dt : 0;
+    fast = ms < BUDGET.slowMs * 0.6 ? fast + dt : 0;
+    if (slow > BUDGET.slowFor && ratio > BUDGET.minRatio) {
+      if (shedders.some((shed) => shed())) { /* bloom went first */ } else if (renderer.shadowMap.enabled) renderer.shadowMap.enabled = false; else ratio = Math.max(BUDGET.minRatio, ratio - BUDGET.step);
+      renderer.setPixelRatio(ratio); slow = 0;
+    } else if (fast > 5 && ratio < Math.min(devicePixelRatio || 1, cap)) {
+      ratio = Math.min(cap, ratio + BUDGET.step); renderer.setPixelRatio(ratio); fast = 0;
+    }
+    this.last = { calls: info.calls, triangles: info.triangles };
+  },
+  last: { calls: 0, triangles: 0 },
+  /** The quality tier the light, post and dressing are sized by: the player's setting, else the GPU and the device (light-math tierOf). */
+  tier(): Tier {
+    // ?quality=phone|desktop|high (a bench run, a capture) wins, then the player's setting.
+    let userSetting: string | null = typeof location === 'object' ? new URLSearchParams(location.search).get('quality') : null;
+    try { userSetting ??= localStorage.getItem(QUALITY_KEY); } catch { /* private mode */ }
+    const nav = navigator as Navigator & { deviceMemory?: number; connection?: { saveData?: boolean } };
+    return tierOf({ phone: cap === BUDGET.maxRatio, saveData: nav.connection?.saveData === true, deviceMemory: nav.deviceMemory, gpuTier: gpuClass(gpu), userSetting });
+  },
+  facts: () => ({ calls: budget.last.calls, triangles: budget.last.triangles, pixelRatio: ratio, fps: Math.round(fps), shadows: !!renderer?.shadowMap.enabled, gpu, tier: cap === BUDGET.maxRatio ? 'phone' : 'desktop' }),
+};

package/templates/three-world/src/camera-rig.ts

@@ -0,0 +1,99 @@
+// The camera rig: a third-person follow that frames where the hero is GOING (look-ahead on its velocity),
+// stays out of walls (a ray from the hero to the eye against every platform and pillar; it pulls in fast
+// and eases back out slowly, so it never clips and never pumps), keeps its yaw steady so the stick means
+// the same thing all round (the hits' rule for touch: a camera that turns by itself turns the controls),
+// and frames whatever shot is current (shots.ts: the title's orbit over the square, play's follow, a
+// beat's reveal), blending between them. The framing numbers are SHOTS; the follow's handling is RIG;
+// `__FPX_CAMERA__` reports both so `funtools score` names the line to edit. Skill funpixel-game-spine, camera.md.
+
+import * as THREE from 'three';
+import type { Box, Post } from './layout';
+import { juice, shakeOffset } from './juice';
+import { ease, SHOTS, shots, type Shot } from './shots';
+
+export const RIG = {
+  /** Seconds of velocity framed ahead, and follow rates (per second; higher is tighter). */
+  lookAhead: 0.35, follow: 7, aheadFollow: 3,
+  /** Clearance from walls (m), how fast it pulls in and eases back out, and the nearest it comes. */
+  clearance: 0.4, pullIn: 20, easeOut: 2.5, nearest: 2.2,
+} as const;
+
+const v = new THREE.Vector3(), dir = new THREE.Vector3(), box = new THREE.Box3(), ray = new THREE.Ray(), hit = new THREE.Vector3();
+
+/** How far along the ray from `from` (unit `d`) to `len` metres the first solid is, or `len`. */
+function firstHit(from: THREE.Vector3, d: THREE.Vector3, len: number, boxes: Box[], posts: Post[]): number {
+  let best = len;
+  ray.set(from, d);
+  for (const b of boxes) {
+    // The eye rises from the look point, so a solid no taller than that point cannot block it (a low crate
+    // beside the hero once pinned the camera to the hero's back: Tidemarket, 1 Oct).
+    if (d.y > 0 && b.top <= from.y) continue;
+    box.min.set(b.x - b.hw - 0.2, -1, b.z - b.hd - 0.2); box.max.set(b.x + b.hw + 0.2, b.top, b.z + b.hd + 0.2);
+    if (ray.intersectBox(box, hit)) best = Math.min(best, hit.distanceTo(from));
+  }
+  for (const p of posts) {
+    const ox = from.x - p.x, oz = from.z - p.z, a = d.x * d.x + d.z * d.z, bq = 2 * (ox * d.x + oz * d.z), c = ox * ox + oz * oz - (p.r + 0.25) ** 2, disc = bq * bq - 4 * a * c;
+    if (a < 1e-6 || disc < 0) continue;
+    const t = (-bq - Math.sqrt(disc)) / (2 * a);
+    if (t > 0 && t < best && from.y + d.y * t < p.h + 0.3) best = t;
+  }
+  return best;
+}
+
+const lerp3 = (a: [number, number, number], b: THREE.Vector3, t: number) => v.set(a[0] + (b.x - a[0]) * t, a[1] + (b.y - a[1]) * t, a[2] + (b.z - a[2]) * t);
+
+export class CameraRig {
+  readonly camera = new THREE.PerspectiveCamera(SHOTS.play.fov, 1, 0.1, 500);
+  private look = new THREE.Vector3(0, SHOTS.play.lookHeight, 0);
+  private ahead = new THREE.Vector3();
+  private reach: number = Math.hypot(SHOTS.play.distance, SHOTS.play.height);
+  private angle = 0;
+  private eye = new THREE.Vector3();
+  readonly aim = new THREE.Vector3(); // what the eye looks at (cameraReport, shots.ts)
+  /** The yaw the stick is read along: the current follow shot's. */
+  yaw: number = SHOTS.play.yaw;
+  lens: number = SHOTS.play.fov; // the lens before juice, for the report
+
+  /** Frame the current shot (follow the hero clear of the solids, or orbit), blending from the last one. */
+  update(dt: number, hero: { x: number; y: number; z: number; vx: number; vz: number }, boxes: Box[], posts: Post[]): void {
+    const k = (rate: number) => 1 - Math.exp(-rate * dt);
+    const shot: Shot = SHOTS[shots.current];
+    if (shots.from === null && shots.t < 1) shots.from = { pos: this.camera.position.toArray() as [number, number, number], look: this.look.toArray() as [number, number, number], fov: this.camera.fov };
+    if (shot.move === 'orbit') {
+      this.angle += dt * (shot.speed ?? 0.07);
+      const c = shot.look ?? [0, shot.lookHeight, 0];
+      this.aim.set(c[0], c[1], c[2]);
+      this.eye.set(c[0] + Math.sin(this.angle) * shot.distance, c[1] + shot.height, c[2] + Math.cos(this.angle) * shot.distance);
+      this.reach = Math.hypot(SHOTS.play.distance, SHOTS.play.height);
+      this.look.copy(this.aim);
+    } else {
+      this.yaw = shot.yaw;
+      this.ahead.lerp(v.set(hero.vx, 0, hero.vz).multiplyScalar(RIG.lookAhead), k(RIG.aheadFollow));
+      this.look.lerp(v.set(hero.x, hero.y + shot.lookHeight, hero.z).add(this.ahead), k(RIG.follow));
+      // Upright phones see less to the sides: pull back and look a little flatter so the world still reads.
+      const tall = Math.max(0, 1 - this.camera.aspect), dist = shot.distance * (1 + tall * 0.5), high = shot.height * (1 + tall * 0.2);
+      const full = Math.hypot(dist, high);
+      dir.set(Math.sin(this.yaw) * dist, high, Math.cos(this.yaw) * dist).normalize();
+      const free = Math.max(RIG.nearest, firstHit(v.set(hero.x, hero.y + shot.lookHeight, hero.z), dir, full, boxes, posts) - RIG.clearance);
+      this.reach += (free - this.reach) * k(free < this.reach ? RIG.pullIn : RIG.easeOut);
+      this.eye.copy(this.look).addScaledVector(dir, this.reach);
+      this.eye.y = Math.max(0.6, this.eye.y);
+      this.aim.copy(this.look);
+    }
+    // The blend: from where the last shot left the camera to this one, eased.
+    let lens: number = shot.fov;
+    if (shots.t < 1 && shots.from) {
+      shots.t = Math.min(1, shots.t + dt / Math.max(0.05, shots.seconds));
+      const e = ease(shots.t);
+      this.eye.copy(lerp3(shots.from.pos, this.eye, e));
+      this.aim.copy(lerp3(shots.from.look, this.aim, e));
+      lens = shots.from.fov + (shot.fov - shots.from.fov) * e;
+    }
+    const off = shakeOffset();
+    this.camera.position.copy(this.eye); this.camera.lookAt(this.aim);
+    this.camera.position.x += off.x; this.camera.position.y += off.y;
+    this.lens = lens;
+    const fov = lens + juice.fov;
+    if (Math.abs(this.camera.fov - fov) > 0.01) { this.camera.fov = fov; this.camera.updateProjectionMatrix(); }
+  }
+}

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

@@ -0,0 +1,49 @@
+// Phone controls: a floating stick (put a thumb down anywhere in the left zone and the stick is born under
+// it; drag to move, release to stop) and the action buttons in the right thumb's arc (jump big, dash
+// smaller), all inside the safe areas. Shown for touch only (`.touch-only`, platform.ts: last input wins, so
+// a finger shows them and a key or a mouse hides them); keys and a gamepad do the same on a desk.
+// The stick zone carries data-fpx-gesture (the moves), the buttons data-fpx-touch (their keys), so verify's
+// phone checks see every key reached by a thumb. Sizes and reach: skill funpixel-mobile-ui.
+
+import { useState } from 'preact/hooks';
+import { Icon } from './icons';
+import { stick } from './input';
+import { useStore } from './store';
+
+/** The stick's travel (CSS px from the base to full speed) and the dead zone (a share of it). */
+export const STICK = { radius: 56, dead: 0.12 };
+
+export function Controls() {
+  const s = useStore();
+  const [base, setBase] = useState<{ x: number; y: number; id: number } | null>(null);
+  const [knob, setKnob] = useState({ x: 0, y: 0 });
+  if (s.screen !== 'playing') return null;
+  const move = (e: PointerEvent, b = base) => {
+    if (!b || e.pointerId !== b.id) return;
+    let dx = e.clientX - b.x, dy = e.clientY - b.y;
+    const len = Math.hypot(dx, dy), max = STICK.radius;
+    if (len > max) { dx *= max / len; dy *= max / len; }
+    setKnob({ x: dx, y: dy });
+    const m = Math.min(1, len / max);
+    Object.assign(stick, m < STICK.dead ? { x: 0, y: 0 } : { x: (dx / max), y: -(dy / max) }, { active: true });
+  };
+  const end = (e: PointerEvent) => {
+    if (!base || e.pointerId !== base.id) return;
+    setBase(null); setKnob({ x: 0, y: 0 }); Object.assign(stick, { x: 0, y: 0, active: false });
+  };
+  return (
+    <>
+      <div class="stick-zone touch-only" data-fpx-gesture="ArrowLeft ArrowRight ArrowUp ArrowDown"
+        onPointerDown={(e) => { const b = { x: e.clientX, y: e.clientY, id: e.pointerId }; (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId); setBase(b); move(e, b); }}
+        onPointerMove={(e) => move(e)} onPointerUp={end} onPointerCancel={end}>
+        <div class={`stick ${base ? 'live' : ''}`} style={base ? { left: `${base.x}px`, top: `${base.y}px` } : undefined}>
+          <div class="stick-knob" style={{ transform: `translate(${knob.x}px, ${knob.y}px)` }} />
+        </div>
+      </div>
+      <div class="actions touch-only">
+        <button class="act act-dash" data-fpx-touch="ShiftLeft" aria-label="dash"><Icon name="dash" size={30} /></button>
+        <button class="act act-jump" data-fpx-touch="Space" aria-label="jump"><Icon name="jump" size={40} /></button>
+      </div>
+    </>
+  );
+}

package/templates/three-world/src/cutout-atlas.ts

@@ -0,0 +1,26 @@
+// An atlas built in the page from separate cut-outs (`funtools cut` writes one PNG per figure), for
+// cutouts.ts: one texture, so every figure in it draws in the same single draw call.
+
+import * as THREE from 'three';
+
+/**
+ * An atlas built in the page from separate cut-outs (`funtools cut` writes one PNG per figure): each
+ * picture fitted into a square cell, its foot on the cell's bottom edge, centred. `fill` is the share of
+ * the cell each picture fills (width, height), to size an instance to the figure's true height.
+ */
+export async function atlasFrom(urls: string[], cell = 256): Promise<{ texture: THREE.CanvasTexture; cols: number; rows: number; fill: Array<{ w: number; h: number }> }> {
+  const imgs = await Promise.all(urls.map((u) => new Promise<HTMLImageElement>((ok, fail) => { const im = new Image(); im.onload = () => ok(im); im.onerror = () => fail(new Error(`atlasFrom: ${u} did not load`)); im.src = u; })));
+  const cols = Math.max(1, Math.ceil(Math.sqrt(imgs.length))), rows = Math.max(1, Math.ceil(imgs.length / cols));
+  const canvas = document.createElement('canvas');
+  canvas.width = cols * cell; canvas.height = rows * cell;
+  const g = canvas.getContext('2d')!;
+  const fill = imgs.map((im, i) => {
+    const s = Math.min(cell / im.width, cell / im.height), w = im.width * s, h = im.height * s;
+    g.drawImage(im, (i % cols) * cell + (cell - w) / 2, Math.floor(i / cols) * cell + cell - h, w, h);
+    return { w: w / cell, h: h / cell };
+  });
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.anisotropy = 4;
+  return { texture, cols, rows, fill };
+}

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

@@ -0,0 +1,47 @@
+// The arithmetic of painted cut-outs (cutouts.ts), engine-free so a test can hold it: which cell of an
+// atlas a frame is, which frame a walker shows after walking so far (the stride follows the ground, so
+// the feet never slide), and the sway the shader bends a cut-out by (the top moves, the foot stays).
+
+/** One atlas cell in texture space (v up, row 0 at the top of the picture), mirrored when `flip`. */
+export interface Rect { u0: number; v0: number; u1: number; v1: number }
+
+export function frameRect(frame: number, cols: number, rows: number, flip = false): Rect {
+  const n = Math.max(1, cols * rows);
+  const f = ((Math.floor(frame) % n) + n) % n;
+  const c = f % cols, r = Math.floor(f / cols);
+  const u0 = c / cols, u1 = (c + 1) / cols, v1 = 1 - r / rows, v0 = 1 - (r + 1) / rows;
+  return flip ? { u0: u1, v0, u1: u0, v1 } : { u0, v0, u1, v1 };
+}
+
+/** A cycle of frames in the atlas: `first`, `count` frames, one full cycle per `stride` metres walked. */
+export interface Cycle { first: number; count: number; stride: number; idle?: number }
+
+/**
+ * The frame a walker shows after `distance` metres: the cycle advances by distance, not by time, so a
+ * walker that slows takes slower steps and one that stops stops stepping (its `idle` frame, else the
+ * cycle's first). A human walk's stride is about 0.8 body heights per step, two steps a cycle.
+ */
+export function strideFrame(cycle: Cycle, distance: number, moving = true): number {
+  if (!moving) return cycle.idle ?? cycle.first;
+  const count = Math.max(1, Math.floor(cycle.count));
+  const k = Math.floor((Math.max(0, distance) / Math.max(1e-6, cycle.stride)) * count) % count;
+  return cycle.first + k;
+}
+
+/** A biped's stride (metres a full cycle, two steps) for its height: 1.6 body heights. */
+export const strideFor = (heightM: number): number => 1.6 * heightM;
+
+/**
+ * The sideways bend of a cut-out at height fraction `k` (0 at the foot, 1 at the top), in widths: zero at
+ * the foot, growing with the square of the height, so grass, a crowd's idle sway or a flag bends rather
+ * than tilting like a card on a stick. The shader in cutouts.ts computes the same.
+ */
+export function swayAt(t: number, k: number, phase: number, amount: number, rate: number): number {
+  const h = Math.min(1, Math.max(0, k));
+  return amount * Math.sin(t * rate + phase) * h * h;
+}
+
+/** The vertical breath (squash and stretch, volume kept): height scale, the width scale is its inverse. */
+export function squashAt(t: number, phase: number, amount: number, rate: number): number {
+  return 1 + amount * Math.sin(t * rate * 2 + phase);
+}

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

@@ -0,0 +1,99 @@
+// Many painted cut-outs for one draw call. One THREE.Sprite per cut-out is a draw call each (one
+// game's build reached 164 against a budget of 150); here every cut-out sharing an atlas is ONE
+// InstancedMesh. Each instance has its place, height, tint, atlas frame and mirror, and a sway and
+// squash the vertex shader bends it by (the foot stays planted, the top moves: animation, not a card
+// bobbing on a stick). They turn round the vertical axis to the camera and cut their edge by alphaTest,
+// so nothing is sorted. walk() steps a frame cycle by DISTANCE walked (cutout-math.ts), so feet keep
+// pace with the ground. Cut-outs cast no shadow (a blob decal under each reads better).
+//   const atlas = await atlasFrom(['art/crab-1.png', …]);   // cutout-atlas.ts; or a grid sheet as it is
+//   const crabs = cutouts(scene, atlas.texture, { cols: atlas.cols, rows: atlas.rows });
+//   const i = crabs.add({ x, y: groundAt(x, z), z, h: 0.6, sway: 0.04, squash: 0.03, rate: 3 });
+//   crabs.set(i, { x, z, y: groundAt(x, z), flip: vx < 0 });            // each frame
+//   crabs.walk(i, { first: 0, count: 4, stride: 0.5 }, travelled, speed > 0.05); crabs.update(dt);
+
+import * as THREE from 'three';
+import { strideFrame, type Cycle } from './cutout-math';
+export { atlasFrom } from './cutout-atlas';
+
+export interface CutoutSpec {
+  /** Foot position; h = world height of the cell (width h × aspect unless w is given). */
+  x: number; y: number; z: number; h: number; w?: number;
+  frame?: number; flip?: boolean; tint?: THREE.ColorRepresentation; visible?: boolean;
+  /** Bend at the top in widths (0.03–0.08 a breath or grass, 0.15 a flag); squash a share of the height
+   *  (0.02–0.05 a breath, 0.1 a hop); rate in radians a second (the squash runs at twice it). */
+  sway?: number; squash?: number; rate?: number; phase?: number;
+}
+
+export interface Cutouts {
+  mesh: THREE.InstancedMesh;
+  readonly count: number;
+  add(s: CutoutSpec): number;
+  set(i: number, patch: Partial<CutoutSpec>): void;
+  /** Step instance `i` through `cycle` by the distance it has walked; `moving` false shows the idle frame. */
+  walk(i: number, cycle: Cycle, distance: number, moving?: boolean): void;
+  get(i: number): CutoutSpec;
+  update(dt: number): void;
+}
+
+export interface CutoutOpts { cols: number; rows: number; max?: number; alphaTest?: number; aspect?: number }
+
+export function cutouts(scene: THREE.Object3D, atlas: THREE.Texture, opts: CutoutOpts): Cutouts {
+  const max = opts.max ?? 256, aspect = opts.aspect ?? 1;
+  atlas.colorSpace = THREE.SRGBColorSpace;
+  const geo = new THREE.PlaneGeometry(1, 1).translate(0, 0.5, 0); // the foot at y = 0, the top at y = 1
+  const frames = new THREE.InstancedBufferAttribute(new Float32Array(max * 2), 2); // frame, flip
+  const sways = new THREE.InstancedBufferAttribute(new Float32Array(max * 4), 4); // phase, sway, rate, squash
+  geo.setAttribute('aFrame', frames); geo.setAttribute('aSway', sways);
+  const uniforms = { uTime: { value: 0 }, uGrid: { value: new THREE.Vector2(opts.cols, opts.rows) } };
+  const mat = new THREE.MeshBasicMaterial({ map: atlas, alphaTest: opts.alphaTest ?? 0.5, side: THREE.DoubleSide });
+  mat.onBeforeCompile = (shader) => {
+    Object.assign(shader.uniforms, uniforms);
+    shader.vertexShader = 'attribute vec2 aFrame;\nattribute vec4 aSway;\nuniform float uTime;\nuniform vec2 uGrid;\n' + shader.vertexShader
+      .replace('#include <uv_vertex>', `#include <uv_vertex>
+#ifdef USE_MAP
+  float fCol = mod(aFrame.x, uGrid.x), fRow = floor(aFrame.x / uGrid.x);
+  float fu = aFrame.y > 0.5 ? 1.0 - uv.x : uv.x;
+  vMapUv = vec2((fCol + fu) / uGrid.x, 1.0 - (fRow + 1.0 - uv.y) / uGrid.y);
+#endif`)
+      .replace('#include <project_vertex>', `
+  vec3 iPos = (modelMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xyz;
+  float sx = length(instanceMatrix[0].xyz), sy = length(instanceMatrix[1].xyz);
+  vec3 camR = vec3(viewMatrix[0][0], 0.0, viewMatrix[2][0]);
+  camR = length(camR) > 1e-4 ? normalize(camR) : vec3(1.0, 0.0, 0.0);
+  float k = clamp(transformed.y, 0.0, 1.0);
+  float sq = 1.0 + aSway.w * sin(uTime * aSway.z * 2.0 + aSway.x);
+  float bend = aSway.y * sin(uTime * aSway.z + aSway.x) * k * k;
+  vec3 wp = iPos + camR * ((transformed.x / sq + bend) * sx) + vec3(0.0, transformed.y * sy * sq, 0.0);
+  vec4 mvPosition = viewMatrix * vec4(wp, 1.0);
+  gl_Position = projectionMatrix * mvPosition;`);
+  };
+  const mesh = new THREE.InstancedMesh(geo, mat, max);
+  // Instances spread over the world (the shader places them): no culling by the mesh's own bounds.
+  Object.assign(mesh, { count: 0, frustumCulled: false, castShadow: false, name: 'cutouts' });
+  scene.add(mesh);
+  const specs: CutoutSpec[] = [];
+  const m4 = new THREE.Matrix4(), col = new THREE.Color(), pos = new THREE.Vector3(), scl = new THREE.Vector3(), q = new THREE.Quaternion();
+  const write = (i: number) => {
+    const s = specs[i], shown = s.visible !== false;
+    m4.compose(pos.set(s.x, s.y, s.z), q, scl.set(shown ? s.w ?? s.h * aspect : 0, shown ? s.h : 0, 1));
+    mesh.setMatrixAt(i, m4); mesh.setColorAt(i, col.set(s.tint ?? 0xffffff));
+    frames.setXY(i, s.frame ?? 0, s.flip ? 1 : 0);
+    sways.setXYZW(i, s.phase ?? i * 1.618, s.sway ?? 0, s.rate ?? 2, s.squash ?? 0);
+    mesh.instanceMatrix.needsUpdate = true; frames.needsUpdate = true; sways.needsUpdate = true;
+    if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+  };
+  return {
+    mesh, get count() { return specs.length; },
+    add(s) {
+      if (specs.length >= max) throw new Error(`cutouts: ${max} instances in use (raise opts.max)`);
+      specs.push({ ...s }); mesh.count = specs.length; write(specs.length - 1);
+      return specs.length - 1;
+    },
+    set(i, patch) { Object.assign(specs[i], patch); write(i); },
+    walk(i, cycle, distance, moving = true) {
+      const f = strideFrame(cycle, distance, moving);
+      if (specs[i].frame !== f) { specs[i].frame = f; frames.setX(i, f); frames.needsUpdate = true; }
+    },
+    get(i) { return specs[i]; }, update(dt) { uniforms.uTime.value += dt; },
+  };
+}

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

@@ -0,0 +1,98 @@
+// The dressing pass as rules, engine-free (the tests and the selftests run it): a place's kit names its
+// slots (ground cover, mid props, landmarks, life), each with a density per 100 m², a scale range and
+// how much it clumps; scatter() throws them over the place seeded, keeping the road and the solids
+// clear, grounding each on the terrain, clustering instead of even noise (real ground cover grows in
+// patches), thicker beside the road than out in the field. densityOf() is the number `boxes` checks
+// against the place's target, budgetOf() the triangles and draw calls it costs (one per kind: instanced).
+// Skill funpixel-3d, references/light-and-places.md "Dressing".
+
+import { ARENA, random } from './layout';
+
+export type SlotRole = 'ground' | 'mid' | 'landmark' | 'life';
+export interface Slot {
+  role: SlotRole; kind: string;
+  /** Instances per 100 m² of the place (a landmark: a count, see `count`). */
+  density?: number; count?: number;
+  scale: [number, number];
+  /** 0 = even, 1 = all in patches; patches are `patch` metres across. */
+  clump?: number; patch?: number;
+  /** 0 = anywhere, 1 = hugging the road's sides. */
+  roadside?: number;
+}
+export interface Kit { slots: Slot[] }
+/** The ring a place dresses: from `inner` to `outer` metres round (x, z). */
+export interface Ring { x: number; z: number; inner: number; outer: number }
+export interface Road { pts: Array<[number, number]>; width: number }
+export interface Keepout { x: number; z: number; r: number }
+export interface Placed { slot: number; role: SlotRole; kind: string; x: number; y: number; z: number; scale: number; turn: number }
+
+/** The terrain's height: flat over the play, rising past its edge (the ground mesh and every prop use this one function). */
+export function heightAt(x: number, z: number, seed = 1): number {
+  const d = Math.hypot(x, z);
+  if (d <= ARENA + 2) return 0;
+  // Low frequencies only: the ground mesh's ~2 m cells must follow it, or props float over the facets.
+  const t = 0.5 + 0.5 * Math.sin(x * 0.17 + seed) * Math.cos(z * 0.15 - seed);
+  return Math.min(6, (d - ARENA - 2) ** 1.6 * 0.08) * (0.7 + 0.3 * t);
+}
+
+/** Where a thing stands: the lowest ground under its footprint (a slope buries the uphill edge a little, never floats the downhill one). */
+export const footing = (x: number, z: number, r: number, seed = 1): number => Math.min(heightAt(x, z, seed), ...[0, 1, 2, 3].map((i) => heightAt(x + Math.cos(i * 1.571) * r, z + Math.sin(i * 1.571) * r, seed))) - 0.03;
+
+/** Distance from a point to a road's centre line. */
+export function roadDistance(road: Road, x: number, z: number): number {
+  let best = Infinity;
+  for (let i = 1; i < road.pts.length; i++) {
+    const [ax, az] = road.pts[i - 1], [bx, bz] = road.pts[i], dx = bx - ax, dz = bz - az, l = dx * dx + dz * dz || 1;
+    const t = Math.max(0, Math.min(1, ((x - ax) * dx + (z - az) * dz) / l));
+    best = Math.min(best, Math.hypot(x - ax - t * dx, z - az - t * dz));
+  }
+  return best;
+}
+
+export const ringArea = (r: Ring): number => Math.PI * (r.outer ** 2 - r.inner ** 2);
+
+export interface ScatterOpts { seed: number; roads?: Road[]; keepouts?: Keepout[]; /** The tier's share (light-math TIERS.dressing). */ share?: number; max?: number }
+
+export function scatter(kit: Kit, ring: Ring, o: ScatterOpts): Placed[] {
+  const s = { seed: o.seed ^ 0x2c1b3c6d }, roads = o.roads ?? [], keep = o.keepouts ?? [], out: Placed[] = [], area = ringArea(ring);
+  const free = (x: number, z: number, pad: number) => roads.every((r) => roadDistance(r, x, z) > r.width / 2 + pad) && keep.every((k) => Math.hypot(x - k.x, z - k.z) > k.r + pad);
+  const inRing = (x: number, z: number) => { const d = Math.hypot(x - ring.x, z - ring.z); return d >= ring.inner && d <= ring.outer; };
+  const anywhere = (): [number, number] => { const a = random(s) * Math.PI * 2, d = Math.sqrt(ring.inner ** 2 + random(s) * (ring.outer ** 2 - ring.inner ** 2)); return [ring.x + Math.sin(a) * d, ring.z + Math.cos(a) * d]; };
+  kit.slots.forEach((slot, si) => {
+    const share = slot.role === 'landmark' ? 1 : o.share ?? 1;
+    const want = Math.round((slot.count ?? ((slot.density ?? 0) * area) / 100) * share);
+    const patch = slot.patch ?? 3, clump = slot.clump ?? 0, side = slot.roadside ?? 0;
+    const centres = Array.from({ length: Math.max(1, Math.round(want / 12)) }, anywhere);
+    let made = 0;
+    for (let tries = 0; made < want && tries < want * 12 && out.length < (o.max ?? Infinity); tries++) {
+      let x: number, z: number;
+      if (random(s) < clump) {
+        const [cx, cz] = centres[Math.floor(random(s) * centres.length)], a = random(s) * Math.PI * 2, r = patch * Math.sqrt(-2 * Math.log(1 - random(s) * 0.98)) * 0.5;
+        x = cx + Math.sin(a) * r; z = cz + Math.cos(a) * r;
+      } else [x, z] = anywhere();
+      const sc = slot.scale[0] + random(s) * (slot.scale[1] - slot.scale[0]);
+      if (!inRing(x, z) || !free(x, z, sc * 0.4)) continue;
+      // Roadside: keep a point with a chance that falls off with its distance from the nearest road edge.
+      if (side > 0 && roads.length) { const d = Math.min(...roads.map((r) => roadDistance(r, x, z) - r.width / 2)); if (random(s) > (1 - side) + side * Math.exp(-d / 3)) continue; }
+      out.push({ slot: si, role: slot.role, kind: slot.kind, x, y: footing(x, z, sc * 0.4), z, scale: sc, turn: random(s) * Math.PI * 2 });
+      made++;
+    }
+  });
+  return out;
+}
+
+export interface Density { things: number; per100: number; byRole: Record<string, number>; onRoad: number }
+/** Things per 100 m² of the ring, by role, and how many stand on a road (should be 0: the road stays clear). */
+export function densityOf(placed: Placed[], ring: Ring, roads: Road[] = []): Density {
+  const area = ringArea(ring), byRole: Record<string, number> = {};
+  for (const p of placed) byRole[p.role] = (byRole[p.role] ?? 0) + 1;
+  for (const k of Object.keys(byRole)) byRole[k] = Math.round((byRole[k] / area) * 1000) / 10;
+  const onRoad = placed.filter((p) => roads.some((r) => roadDistance(r, p.x, p.z) < r.width / 2)).length;
+  return { things: placed.length, per100: Math.round((placed.length / area) * 1000) / 10, byRole, onRoad };
+}
+
+/** What a dressing costs a frame: one draw call per kind (instanced), triangles = instances × the kind's. */
+export function budgetOf(placed: Placed[], trianglesOf: Record<string, number>): { calls: number; triangles: number } {
+  const kinds = new Set(placed.map((p) => p.kind));
+  return { calls: kinds.size, triangles: placed.reduce((n, p) => n + (trianglesOf[p.kind] ?? 0), 0) };
+}

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

@@ -0,0 +1,84 @@
+// The dressing drawn: one InstancedMesh per kind (10k grass tufts are one draw call), each instance
+// grounded where dressing-math put it. A kind's look is the game's own model when one is at
+// public/assets/models/<kind>.glb (its largest mesh, instanced), else a designed shape in the place's
+// palette (a tuft, a flower, a rock, a bush, a tree, a lantern, a broken column, reeds). Ground cover
+// and life sway in the wind in the vertex shader (the foot planted), so the world breathes at no CPU
+// cost. Every mesh is named dress-<role>-<kind> with userData.dressing, which the dressing probe
+// (`funtools boxes`) counts per area. Cut-outs (cutouts.ts) are the painted alternative.
+
+import * as THREE from 'three';
+import { findAsset } from './assets';
+import { loader } from './models';
+import { heightAt, type Placed } from './dressing-math';
+import { cornersOf, restOn } from './rest-math';
+
+export interface Tones { ground: THREE.Color; ground2: THREE.Color; stone: THREE.Color; accent: THREE.Color; glow: THREE.Color }
+type Shape = { geo: THREE.BufferGeometry; color: (t: Tones) => THREE.Color; sway: number; emissive?: boolean };
+const cone = (r: number, h: number, n = 6, y = 0) => new THREE.ConeGeometry(r, h, n).translate(0, y + h / 2, 0);
+const merge = (...g: THREE.BufferGeometry[]) => { const out = g.map((x) => x.toNonIndexed()); const pos = out.flatMap((x) => [...(x.attributes.position.array as Float32Array)]); const geo = new THREE.BufferGeometry(); geo.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3)); geo.computeVertexNormals(); return geo; };
+/** Normals straight up: a blade lights like the ground it grows from, never as a dark card seen from behind. */
+const upright = (g: THREE.BufferGeometry) => { const n = g.attributes.normal as THREE.BufferAttribute; for (let i = 0; i < n.count; i++) n.setXYZ(i, 0, 1, 0); return g; };
+const blades = () => upright(merge(...[0, 1, 2].map((i) => new THREE.PlaneGeometry(0.16, 0.5).translate(0, 0.25, 0).rotateY((i * Math.PI) / 3))));
+const SHAPES: Record<string, () => Shape> = {
+  tuft: () => ({ geo: blades(), color: (t) => t.ground2.clone().lerp(new THREE.Color('#ffffff'), 0.08), sway: 0.12 }),
+  reeds: () => ({ geo: upright(merge(...[0, 1, 2, 3].map((i) => new THREE.PlaneGeometry(0.06, 1.1).translate(0.08 * i - 0.12, 0.55, 0).rotateY(i)))), color: (t) => t.ground2.clone().multiplyScalar(1.15), sway: 0.18 }),
+  flower: () => ({ geo: merge(new THREE.CylinderGeometry(0.012, 0.012, 0.3, 3).translate(0, 0.15, 0), new THREE.IcosahedronGeometry(0.06, 0).translate(0, 0.32, 0)), color: (t) => t.accent.clone(), sway: 0.1 }),
+  rock: () => ({ geo: new THREE.DodecahedronGeometry(0.5).scale(1, 0.6, 0.9).translate(0, 0.2, 0), color: (t) => t.stone.clone().multiplyScalar(0.85), sway: 0 }),
+  bush: () => ({ geo: merge(new THREE.IcosahedronGeometry(0.55, 1).translate(0, 0.45, 0), new THREE.IcosahedronGeometry(0.4, 1).translate(0.4, 0.35, 0.1)), color: (t) => t.ground2.clone().multiplyScalar(0.8), sway: 0.04 }),
+  tree: () => ({ geo: merge(new THREE.CylinderGeometry(0.12, 0.16, 1.2, 6).translate(0, 0.6, 0), cone(0.9, 2.2, 7, 1), cone(0.65, 1.6, 7, 2.2)), color: (t) => t.ground2.clone().multiplyScalar(0.7), sway: 0.03 }),
+  lantern: () => ({ geo: merge(new THREE.CylinderGeometry(0.05, 0.06, 1.8, 6).translate(0, 0.9, 0), new THREE.OctahedronGeometry(0.16).translate(0, 1.9, 0)), color: (t) => t.glow.clone(), sway: 0, emissive: true }),
+  column: () => ({ geo: merge(new THREE.CylinderGeometry(0.45, 0.5, 3.4, 10).translate(0, 1.7, 0), new THREE.BoxGeometry(1.2, 0.3, 1.2).translate(0, 3.5, 0)), color: (t) => t.stone.clone(), sway: 0 }),
+};
+export const KINDS = Object.keys(SHAPES);
+
+/** Wind: one clock for every swaying kind (the foot stays put; the top moves by its height). */
+export const wind = { value: 0 };
+function sway(mat: THREE.MeshStandardMaterial, amount: number): void {
+  if (!amount) return;
+  mat.onBeforeCompile = (sh) => {
+    sh.uniforms.uWind = wind;
+    sh.vertexShader = `uniform float uWind;\n${sh.vertexShader}`.replace('#include <begin_vertex>', `#include <begin_vertex>
+      vec4 w = instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0); float bend = ${amount.toFixed(3)} * position.y;
+      transformed.x += sin(uWind * 1.7 + w.x * 0.4 + w.z * 0.3) * bend; transformed.z += cos(uWind * 1.3 + w.z * 0.5) * bend * 0.6;`);
+  };
+}
+
+const owned = new Map<string, Promise<{ geo: THREE.BufferGeometry; mat: THREE.Material } | null>>();
+const ownModel = (kind: string) => owned.get(kind) ?? owned.set(kind, loadOwn(kind)).get(kind)!;
+async function loadOwn(kind: string): Promise<{ geo: THREE.BufferGeometry; mat: THREE.Material } | null> {
+  const url = await findAsset('models', kind);
+  const g = url ? await loader.loadAsync(url).catch(() => null) : null;
+  let best: THREE.Mesh | null = null;
+  g?.scene.traverse((o) => { const m = o as THREE.Mesh; if (m.isMesh && (!best || m.geometry.attributes.position.count > best.geometry.attributes.position.count)) best = m; });
+  return best ? { geo: (best as THREE.Mesh).geometry, mat: (best as THREE.Mesh).material as THREE.Material } : null;
+}
+
+/** Draw the placed things into `group`, one InstancedMesh per kind. Returns the triangles each kind costs. */
+export async function dress(group: THREE.Group, placed: Placed[], tones: Tones): Promise<Record<string, number>> {
+  const byKind = new Map<string, Placed[]>(), tris: Record<string, number> = {};
+  for (const p of placed) (byKind.get(p.kind) ?? byKind.set(p.kind, []).get(p.kind)!).push(p);
+  const m = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0), c = new THREE.Color();
+  for (const [kind, list] of byKind) {
+    const own = await ownModel(kind), shape = (SHAPES[kind] ?? SHAPES.rock)();
+    const mat = own?.mat ?? new THREE.MeshStandardMaterial({ color: '#ffffff', roughness: 0.9, flatShading: kind === 'rock', side: shape.sway > 0.08 ? THREE.DoubleSide : THREE.FrontSide, ...(shape.emissive ? { emissive: shape.color(tones), emissiveIntensity: 1.4 } : {}) });
+    if (!own) sway(mat as THREE.MeshStandardMaterial, shape.sway);
+    const geo = own?.geo ?? shape.geo, mesh = new THREE.InstancedMesh(geo, mat, list.length);
+    // Each one rests on the ground under its whole footprint (its own bounds, turned and scaled: a tree's is its canopy),
+    // read at the corners and the centre the way the world read reads it (rest-math.ts).
+    if (!geo.boundingBox) geo.computeBoundingBox();
+    const bb = geo.boundingBox!, foot: [number, number, number, number] = [bb.min.x, bb.max.x, bb.min.z, bb.max.z];
+    list.forEach((p, i) => {
+      const corners = cornersOf(foot, p.x, p.z, p.turn, p.scale);
+      const mid = [corners.reduce((t, c) => t + c[0], 0) / 4, corners.reduce((t, c) => t + c[1], 0) / 4];
+      // restOn gives where its lowest point goes; the instance's origin sits that far above it (a rock's dips below 0).
+      p.y = restOn([mid, ...corners].map(([x, z]) => heightAt(x, z)), (bb.max.y - bb.min.y) * p.scale) - bb.min.y * p.scale + 0.02;
+      mesh.setMatrixAt(i, m.compose(new THREE.Vector3(p.x, p.y - 0.02, p.z), q.setFromAxisAngle(up, p.turn), new THREE.Vector3(p.scale, p.scale, p.scale)));
+      if (!own) mesh.setColorAt(i, c.copy(shape.color(tones)).offsetHSL(0, 0, ((i * 2654435761) % 100) / 1000 - 0.05));
+    });
+    mesh.name = `dress-${list[0].role}-${kind}`; mesh.userData = { dressing: true, role: list[0].role, kind };
+    mesh.castShadow = list[0].role === 'landmark' || list[0].role === 'mid'; mesh.receiveShadow = true;
+    mesh.computeBoundingSphere(); group.add(mesh);
+    tris[kind] = (geo.index ? geo.index.count : geo.attributes.position.count) / 3;
+  }
+  return tris;
+}