@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/paper-io/PaperIoRules.ts

@@ -0,0 +1,315 @@
+// Paper IO's rules, with no React or engine: the board (who owns each cell, whose trail is on it), the
+// players, the AI, head-on blocking, moving, laying trail and the flood-fill capture. Ported step for
+// step from the original version's UI-thread physics (games/paper-io/PaperIoPhysics.ts), with the same
+// random draws in the same order, so a seeded run plays out identically.
+import { type Grid, PLAYER_COUNT, POINTS_PER_CELL, START_TERRITORY } from './PaperIoConstants';
+
+export type Vec = { dx: number; dy: number };
+export const DIRECTIONS = {
+  UP: { dx: 0, dy: -1 },
+  DOWN: { dx: 0, dy: 1 },
+  LEFT: { dx: -1, dy: 0 },
+  RIGHT: { dx: 1, dy: 0 }
+} as const;
+export type DirCode = keyof typeof DIRECTIONS;
+
+export type Player = {
+  id: number; // 1-based owner id in the grids
+  index: number; // 0 = you, 1 = the AI
+  isBot: boolean;
+  alive: boolean;
+  col: number;
+  row: number;
+  dir: Vec;
+  pendingDir: Vec;
+  trail: number[]; // the trail's cells, in order
+  homeCol: number;
+  homeRow: number;
+  botState: 'expand' | 'return';
+  botStepsOut: number;
+  botTurned: boolean;
+};
+
+export type Board = Grid & { total: number; owners: number[]; trails: number[]; players: Player[]; counts: number[] };
+
+export type Stats = { score: number; territoryPct: number; aiPct: number; rank: number; alivePlayers: number };
+
+const shuffle = <T>(arr: T[]): T[] => {
+  const a = arr.slice();
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const tmp = a[i]!;
+    a[i] = a[j]!;
+    a[j] = tmp;
+  }
+  return a;
+};
+
+export const countTerritory = (b: Board, id: number) => {
+  let n = 0;
+  for (let i = 0; i < b.total; i++) if (b.owners[i] === id) n++;
+  return n;
+};
+
+/** A fresh board: you near the bottom middle, the AI near the top middle, each on a 3 x 3 patch. */
+export function newBoard(g: Grid): Board {
+  const { cols, rows, cell } = g;
+  const total = cols * rows;
+  const owners: number[] = new Array(total).fill(0);
+  const players: Player[] = [];
+  const s = START_TERRITORY;
+  const m = s + 1;
+  const inset = Math.max(m, Math.round(250 / cell));
+  const midCol = Math.floor(cols / 2);
+  for (let i = 0; i < PLAYER_COUNT; i++) {
+    const spawn = i === 0 ? { col: midCol, row: rows - 1 - inset } : { col: midCol, row: inset };
+    const id = i + 1;
+    for (let r = spawn.row - s; r <= spawn.row + s; r++)
+      for (let c = spawn.col - s; c <= spawn.col + s; c++) if (c >= 0 && c < cols && r >= 0 && r < rows) owners[r * cols + c] = id;
+    players.push({
+      id,
+      index: i,
+      isBot: i !== 0,
+      alive: true,
+      col: spawn.col,
+      row: spawn.row,
+      dir: DIRECTIONS.RIGHT,
+      pendingDir: DIRECTIONS.RIGHT,
+      trail: [],
+      homeCol: spawn.col,
+      homeRow: spawn.row,
+      botState: 'expand',
+      botStepsOut: 0,
+      botTurned: false
+    });
+  }
+  const b: Board = { ...g, total, owners, trails: new Array(total).fill(0), players, counts: [] };
+  b.counts = players.map((p) => countTerritory(b, p.id));
+  return b;
+}
+
+export function stats(b: Board): Stats {
+  const you = b.counts[0] ?? 0;
+  const ai = b.counts[1] ?? 0;
+  let rank = 1;
+  for (const p of b.players) if (p.id !== 1 && (b.counts[p.id - 1] ?? 0) > you) rank++;
+  return {
+    score: you * POINTS_PER_CELL,
+    territoryPct: Math.round((you / b.total) * 1000) / 10,
+    aiPct: Math.round((ai / b.total) * 1000) / 10,
+    rank,
+    alivePlayers: b.players.filter((p) => p.alive).length
+  };
+}
+
+/** A swipe's turn for you: queued for the next step (no turning straight back). Whether it changed. */
+export function turn(b: Board, code: DirCode): boolean {
+  const p = b.players[0];
+  if (!p || !p.alive) return false;
+  const next = DIRECTIONS[code];
+  if (next.dx === -p.dir.dx && next.dy === -p.dir.dy) return false;
+  if (next.dx !== p.pendingDir.dx || next.dy !== p.pendingDir.dy) {
+    p.pendingDir = next;
+    return true;
+  }
+  return false;
+}
+
+// ── The AI ────────────────────────────────────────────────────────────
+
+const resolvedDir = (p: Player): Vec => (p.pendingDir.dx !== -p.dir.dx || p.pendingDir.dy !== -p.dir.dy ? p.pendingDir : p.dir);
+
+function pickSafeDir(b: Board, p: Player, options: Vec[]): Vec | null {
+  for (const d of options) {
+    if (d.dx === -p.dir.dx && d.dy === -p.dir.dy) continue;
+    const nc = p.col + d.dx;
+    const nr = p.row + d.dy;
+    if (nc < 0 || nc >= b.cols || nr < 0 || nr >= b.rows) continue;
+    if (b.trails[nr * b.cols + nc] === p.id) continue;
+    return d;
+  }
+  return null;
+}
+
+function roomInDir(b: Board, p: Player, d: Vec): number {
+  let n = 0;
+  let c = p.col;
+  let r = p.row;
+  while (n < b.cols + b.rows) {
+    c += d.dx;
+    r += d.dy;
+    if (c < 0 || c >= b.cols || r < 0 || r >= b.rows) break;
+    n++;
+  }
+  return n;
+}
+
+function pickOutwardDir(b: Board, p: Player): Vec | null {
+  const options = shuffle<Vec>([DIRECTIONS.UP, DIRECTIONS.DOWN, DIRECTIONS.LEFT, DIRECTIONS.RIGHT]);
+  options.sort((x, y) => roomInDir(b, p, y) - roomInDir(b, p, x));
+  return pickSafeDir(b, p, options);
+}
+
+/** The AI: strike out a long leg, sweep a second one at right angles, then head home to bank it. */
+function decideBot(b: Board, p: Player) {
+  if (p.trail.length === 0) {
+    p.botState = 'expand';
+    p.botTurned = false;
+    p.botStepsOut = 12 + Math.floor(Math.random() * 10);
+    p.pendingDir = pickOutwardDir(b, p) ?? p.dir;
+  } else if (p.botState === 'expand') {
+    p.botStepsOut--;
+    if (p.trail.length > 90) {
+      p.botState = 'return';
+    } else if (p.botStepsOut <= 0) {
+      if (!p.botTurned) {
+        const perp: Vec[] = p.dir.dx !== 0 ? [DIRECTIONS.UP, DIRECTIONS.DOWN] : [DIRECTIONS.LEFT, DIRECTIONS.RIGHT];
+        perp.sort((x, y) => roomInDir(b, p, y) - roomInDir(b, p, x));
+        const safe = pickSafeDir(b, p, perp);
+        if (safe) {
+          p.pendingDir = safe;
+          p.botTurned = true;
+          p.botStepsOut = 10 + Math.floor(Math.random() * 10);
+        } else {
+          p.botState = 'return';
+        }
+      } else {
+        p.botState = 'return';
+      }
+    }
+  }
+  if (p.botState === 'return') {
+    const dCol = p.homeCol - p.col;
+    const dRow = p.homeRow - p.row;
+    const prefer: Vec[] = [];
+    if (Math.abs(dCol) >= Math.abs(dRow)) {
+      if (dCol !== 0) prefer.push(dCol > 0 ? DIRECTIONS.RIGHT : DIRECTIONS.LEFT);
+      if (dRow !== 0) prefer.push(dRow > 0 ? DIRECTIONS.DOWN : DIRECTIONS.UP);
+    } else {
+      if (dRow !== 0) prefer.push(dRow > 0 ? DIRECTIONS.DOWN : DIRECTIONS.UP);
+      if (dCol !== 0) prefer.push(dCol > 0 ? DIRECTIONS.RIGHT : DIRECTIONS.LEFT);
+    }
+    prefer.push(p.dir);
+    const safe = pickSafeDir(b, p, prefer);
+    if (safe) p.pendingDir = safe;
+  }
+  // Never keep a direction off the board or into its own trail
+  const nc = p.col + p.pendingDir.dx;
+  const nr = p.row + p.pendingDir.dy;
+  if (nc < 0 || nc >= b.cols || nr < 0 || nr >= b.rows || b.trails[nr * b.cols + nc] === p.id) {
+    const safe = pickSafeDir(b, p, shuffle<Vec>([DIRECTIONS.UP, DIRECTIONS.DOWN, DIRECTIONS.LEFT, DIRECTIONS.RIGHT]));
+    if (safe) p.pendingDir = safe;
+  }
+}
+
+// ── Moving and capturing ──────────────────────────────────────────────
+
+/** Banks a trail: it becomes land, and so does everything it encloses (not reachable from the edge). */
+function capture(b: Board, p: Player) {
+  const { cols, rows, total, owners, trails } = b;
+  const id = p.id;
+  for (const idx of p.trail) {
+    owners[idx] = id;
+    trails[idx] = 0;
+  }
+  p.trail = [];
+  const reachable = new Uint8Array(total);
+  const queue: number[] = [];
+  const enqueue = (c: number, r: number) => {
+    if (c < 0 || c >= cols || r < 0 || r >= rows) return;
+    const idx = r * cols + c;
+    if (reachable[idx] || owners[idx] === id) return;
+    reachable[idx] = 1;
+    queue.push(idx);
+  };
+  for (let c = 0; c < cols; c++) {
+    enqueue(c, 0);
+    enqueue(c, rows - 1);
+  }
+  for (let r = 0; r < rows; r++) {
+    enqueue(0, r);
+    enqueue(cols - 1, r);
+  }
+  while (queue.length > 0) {
+    const idx = queue.pop()!;
+    const c = idx % cols;
+    const r = (idx - c) / cols;
+    enqueue(c - 1, r);
+    enqueue(c + 1, r);
+    enqueue(c, r - 1);
+    enqueue(c, r + 1);
+  }
+  for (let idx = 0; idx < total; idx++) if (!reachable[idx] && owners[idx] !== id) owners[idx] = id;
+}
+
+const NONE = 0;
+const TRAIL = 1;
+const CAPTURE = 2;
+
+function move(b: Board, p: Player): number {
+  if (p.pendingDir.dx !== -p.dir.dx || p.pendingDir.dy !== -p.dir.dy) p.dir = p.pendingDir;
+  const nc = p.col + p.dir.dx;
+  const nr = p.row + p.dir.dy;
+  if (nc < 0 || nc >= b.cols || nr < 0 || nr >= b.rows) return NONE; // bumps the wall: stays put
+  const idx = nr * b.cols + nc;
+  p.col = nc;
+  p.row = nr;
+  const closesOwnLoop = b.trails[idx] === p.id;
+  if (b.owners[idx] === p.id || closesOwnLoop) {
+    if (p.trail.length > 0) {
+      capture(b, p);
+      return CAPTURE;
+    }
+  } else if (b.trails[idx] === 0) {
+    b.trails[idx] = p.id;
+    p.trail.push(idx);
+    return TRAIL;
+  }
+  return NONE;
+}
+
+/** What one step changed: land (and who captured), trails, and whether the board is full. */
+export type StepResult = { trailCells: number[]; territory: boolean; trails: boolean; captured: boolean[]; full: boolean; won: boolean };
+
+/** One grid step: the AI decides, head-on moves are blocked, everyone moves a cell. */
+export function step(b: Board): StepResult {
+  const { players } = b;
+  for (const p of players) if (p.alive && p.isBot) decideBot(b, p);
+  const targets: number[] = players.map((p) => {
+    if (!p.alive) return -1;
+    const d = resolvedDir(p);
+    const nc = p.col + d.dx;
+    const nr = p.row + d.dy;
+    return nc >= 0 && nc < b.cols && nr >= 0 && nr < b.rows ? nr * b.cols + nc : -1;
+  });
+  const out: StepResult = { trailCells: [], territory: false, trails: false, captured: players.map(() => false), full: false, won: false };
+  for (let i = 0; i < players.length; i++) {
+    const p = players[i]!;
+    if (!p.alive) continue;
+    const target = targets[i]!;
+    // Two heads about to step onto the same cell: both stay put (facing where they meant to go)
+    if (target >= 0 && targets.some((t, j) => j !== i && t === target)) {
+      p.dir = resolvedDir(p);
+      continue;
+    }
+    const r = move(b, p);
+    if (r === TRAIL) {
+      out.trails = true;
+      out.trailCells.push(p.row * b.cols + p.col);
+    } else if (r === CAPTURE) {
+      out.territory = true;
+      out.trails = true;
+      out.captured[i] = true;
+    }
+  }
+  if (out.territory) {
+    b.counts = players.map((p) => countTerritory(b, p.id));
+    const you = b.counts[0] ?? 0;
+    const ai = b.counts[1] ?? 0;
+    if (you + ai >= b.total) {
+      out.full = true;
+      out.won = you > ai;
+    }
+  }
+  return out;
+}

package/src/games/paper-io/PaperIoScene.ts

@@ -0,0 +1,310 @@
+// Everything Paper IO draws: the board (themed, as the original board), each player's land as raised slabs
+// in their color, trails as thinner translucent strips laid on top, and people carrying their team's
+// flags. Their clothes, faces and articulated walking limbs are cached code-built meshes. Seen from
+// above with an orthographic camera, using point-based layout inside a compact, scaled world.
+//
+// Land uses cached corner meshes for a smooth outline; interior cells and trails share the built-in cube,
+// spawned the first time it's needed: a board starts with 18 land cells, not one per grid cell. Newly
+// captured land rises in white and settles to its owner's color, as the original flash did.
+import { effects, type Entity, extrude, type Model, Path, type Quat, quat, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { cellCentre, COLORS, LAND, type Layout, PERSON, PERSON_COLORS, PLAYER_COLORS, STEP_MS, TRAIL, WORLD_SCALE } from './PaperIoConstants';
+import { personMeshes } from './PaperIoMeshes';
+import type { Board, Vec } from './PaperIoRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('paper-io/PaperIoScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const BOARD_DEPTH = 8;
+const BACKDROP_DEPTH = 30;
+// A head glides one frame-aligned step, so glides chain without a pause (as the original glide)
+const GLIDE = (Math.ceil(STEP_MS / (1000 / 60)) * (1000 / 60)) / 1000;
+const FLASH = 0.48;
+
+const panelMesh = (w: number, h: number, radius: number) =>
+  cached(`pio-panel:${w}x${h}:${radius}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-w / 2, -h / 2, w, h, radius), { depth: BOARD_DEPTH }), { shine: 0.15 })
+  );
+
+/** Round only exposed territory corners, keeping neighbouring cells joined without seams. */
+function landCorners(b: Board, col: number, row: number, owner: number): number {
+  // Keep the screen edges filled: the outline is rounded only against other cells on the board.
+  const matches = (c: number, r: number) => c < 0 || c >= b.cols || r < 0 || r >= b.rows || b.owners[r * b.cols + c] === owner;
+  const top = matches(col, row - 1);
+  const right = matches(col + 1, row);
+  const bottom = matches(col, row + 1);
+  const left = matches(col - 1, row);
+  return (!top && !left ? 1 : 0) | (!top && !right ? 2 : 0) | (!bottom && !right ? 4 : 0) | (!bottom && !left ? 8 : 0);
+}
+
+function landMesh(corners: number): Model | 'cube' {
+  if (!corners) return 'cube';
+  return cached(`pio-land:${corners}`, () => {
+    const radius = (corners & (corners - 1)) === 0 ? 0.95 : 0.48;
+    const [tl, tr, br, bl] = [1, 2, 4, 8].map((bit) => (corners & bit ? radius : 0)) as [number, number, number, number];
+    const path = new Path().moveTo(-0.5 + tl, -0.5).lineTo(0.5 - tr, -0.5);
+    if (tr) path.arcTo(tr, tr, 0, false, true, 0.5, -0.5 + tr);
+    path.lineTo(0.5, 0.5 - br);
+    if (br) path.arcTo(br, br, 0, false, true, 0.5 - br, 0.5);
+    path.lineTo(-0.5 + bl, 0.5);
+    if (bl) path.arcTo(bl, bl, 0, false, true, -0.5, 0.5 - bl);
+    path.lineTo(-0.5, -0.5 + tl);
+    if (tl) path.arcTo(tl, tl, 0, false, true, -0.5 + tl, -0.5);
+    return createShape(extrude(path.close(), { depth: 1 }), { center: false });
+  });
+}
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+interface PersonRig {
+  root: Entity;
+  visual: Entity;
+  legs: readonly [Entity, Entity];
+  arm: Entity;
+  flag: Entity;
+  stride: number;
+  col: number;
+  row: number;
+  walking: boolean;
+}
+export type Scene = {
+  root: Entity;
+  backdrop: Entity;
+  board: Entity;
+  /** Land and trail cells, by cell index (spawned when first needed), and who each shows. */
+  land: (Entity | null)[];
+  landOwner: Int8Array;
+  landCorners: Uint8Array;
+  trail: (Entity | null)[];
+  trailOwner: Int8Array;
+  heads: PersonRig[];
+};
+
+const boardColor = (theme: GameTheme) => toColor(theme.mode === 'classic' ? COLORS.CLASSIC_BOARD : theme.BOARD.SURFACE);
+const landColor = (id: number) => toColor(PLAYER_COLORS[id - 1]?.territory ?? '#888888');
+const trailColor = (id: number) => toColor(PLAYER_COLORS[id - 1]?.trail ?? '#AAAAAA', 0.6);
+const landH = (l: Layout) => l.cell * LAND;
+/** Facing a grid direction (x right, y down): people face along local +x and stand along +z. */
+const facing = (d: Vec): Quat => quat.z(Math.atan2(-d.dy, d.dx));
+
+function spawnHead(world: World, l: Layout, index: number, parent: Entity): PersonRig {
+  const c = PLAYER_COLORS[index]!;
+  const meshes = personMeshes();
+  const root = world.spawn({ mesh: 'none', parent, pickable: false });
+  const visual = world.spawn({ mesh: 'none', parent: root, scale: l.cell * PERSON.SCALE, pickable: false });
+  const skin = toColor(PERSON_COLORS.SKIN[index % PERSON_COLORS.SKIN.length]!);
+  world.spawn({ mesh: meshes.shirt, parent: visual, color: toColor(c.head), pickable: false });
+  world.spawn({ mesh: meshes.skin, parent: visual, color: skin, pickable: false });
+  world.spawn({ mesh: meshes.details, parent: visual, pickable: false });
+  const legs = [-1, 1].map((side) => {
+    const leg = world.spawn({ mesh: 'none', parent: visual, position: [0, side * 0.11, 0.86], pickable: false });
+    world.spawn({ mesh: meshes.leg, parent: leg, pickable: false });
+    return leg;
+  }) as [Entity, Entity];
+  const arm = world.spawn({ mesh: 'none', parent: visual, position: [0, 0.205, 1.37], pickable: false });
+  world.spawn({ mesh: meshes.sleeve, parent: arm, color: toColor(c.head), pickable: false });
+  world.spawn({ mesh: meshes.hand, parent: arm, color: skin, pickable: false });
+  const hoist = world.spawn({ mesh: 'none', parent: visual, position: [0.24, -0.31, 2.4], pickable: false });
+  const flag = world.spawn({
+    mesh: meshes.flags[index % meshes.flags.length]!,
+    parent: hoist,
+    rotation: quat.z(-0.055),
+    color: toColor(c.head),
+    pickable: false
+  });
+  world.animate(flag, { rotation: quat.z(0.055) }, { duration: 0.5 + index * 0.08, repeat: 'forever', yoyo: true, easing: 'easeInOut' });
+  return { root, visual, legs, arm, flag, stride: index, col: -1, row: -1, walking: false };
+}
+
+function rest(world: World, h: PersonRig) {
+  for (const joint of [...h.legs, h.arm]) {
+    world.stopAnimation(joint);
+    world.animate(joint, { rotation: [0, 0, 0, 1] }, { duration: 0.15 });
+  }
+  world.stopAnimation(h.visual);
+  world.set(h.visual, { position: [0, 0, 0] });
+  h.walking = false;
+}
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, b: Board): Scene {
+  const root = world.spawn({ mesh: 'none', scale: WORLD_SCALE, pickable: false });
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  world.set(backdrop, { parent: root });
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const board = world.spawn({
+    mesh: panelMesh(l.gridW, l.gridH, theme.mode === 'classic' ? 0 : 8),
+    parent: root,
+    position: [0, 0, -BOARD_DEPTH / 2],
+    color: boardColor(theme),
+    pickable: false
+  });
+  const s: Scene = {
+    root,
+    backdrop,
+    board,
+    land: new Array(b.total).fill(null),
+    landOwner: new Int8Array(b.total),
+    landCorners: new Uint8Array(b.total),
+    trail: new Array(b.total).fill(null),
+    trailOwner: new Int8Array(b.total),
+    heads: b.players.map((_, i) => spawnHead(world, l, i, root))
+  };
+  syncBoard(world, l, s, b, false);
+  placeHeads(world, l, s, b, false);
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  world.despawn(s.root);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  world.set(s.board, { mesh: panelMesh(l.gridW, l.gridH, theme.mode === 'classic' ? 0 : 8), color: boardColor(theme) });
+}
+
+// ── Keeping up with the board ─────────────────────────────────────────
+
+/** Shows each cell's land and trail as the board has them; newly captured land flashes in if `flash`. */
+export function syncBoard(world: World, l: Layout, s: Scene, b: Board, flash: boolean, dirty?: readonly number[]) {
+  const h = landH(l);
+  const th = l.cell * TRAIL;
+  for (let scan = 0, count = dirty?.length ?? b.total; scan < count; scan++) {
+    const i = dirty ? dirty[scan]! : scan;
+    const owner = b.owners[i]!;
+    const col = i % b.cols;
+    const row = (i - col) / b.cols;
+    const corners = owner ? landCorners(b, col, row, owner) : 0;
+    if (owner !== s.landOwner[i] || corners !== s.landCorners[i]) {
+      const [x, y] = cellCentre(l, col, row);
+      let e = s.land[i];
+      if (owner === 0) {
+        if (e != null) world.despawn(e);
+        s.land[i] = null;
+      } else {
+        const color = landColor(owner);
+        const mesh = landMesh(corners);
+        if (e == null) {
+          e = world.spawn({ mesh, parent: s.root, position: [x, y, h / 2], scale: [l.columnWidth, l.rowDepth, h], color, pickable: false });
+          s.land[i] = e;
+        } else world.set(e, { mesh });
+        if (flash && owner !== s.landOwner[i]) {
+          world.stopAnimation(e);
+          world.set(e, { color: toColor(COLORS.FLASH), position: [x, y, h * 0.75], scale: [l.columnWidth, l.rowDepth, h * 1.5] });
+          world.animate(e, { color, position: [x, y, h / 2], scale: [l.columnWidth, l.rowDepth, h] }, { duration: FLASH, easing: 'easeOut' });
+        } else world.set(e, { color });
+      }
+      s.landOwner[i] = owner;
+      s.landCorners[i] = corners;
+    }
+    const trail = b.trails[i]!;
+    if (trail !== s.trailOwner[i]) {
+      const old = s.trail[i];
+      if (old != null) world.despawn(old);
+      s.trail[i] = null;
+      if (trail !== 0) {
+        const col = i % b.cols;
+        const row = (i - col) / b.cols;
+        const [x, y] = cellCentre(l, col, row);
+        const e = world.spawn({
+          mesh: 'cube',
+          parent: s.root,
+          position: [x, y, h + th / 2],
+          scale: [l.columnWidth * 0.86, l.rowDepth * 0.86, th],
+          color: trailColor(trail),
+          pickable: false
+        });
+        // Laid down with a little pop
+        world.set(e, { scale: [l.columnWidth * 0.4, l.rowDepth * 0.4, th] });
+        world.animate(e, { scale: [l.columnWidth * 0.86, l.rowDepth * 0.86, th] }, { duration: 0.12, easing: 'back' });
+        s.trail[i] = e;
+      }
+      s.trailOwner[i] = trail;
+    }
+  }
+}
+
+/** People glide between cells, turn with their feet, and carry their flags through each step. */
+export function placeHeads(world: World, l: Layout, s: Scene, b: Board, glide: boolean, popped: boolean[] = []) {
+  b.players.forEach((p, i) => {
+    const head = s.heads[i];
+    if (!head) return;
+    const [x, y] = cellCentre(l, p.col, p.row);
+    const z = landH(l) + (b.trails[p.row * b.cols + p.col] ? l.cell * TRAIL : 0) + l.cell * 0.02;
+    const rotation = facing(p.dir);
+    const moved = head.col !== p.col || head.row !== p.row;
+    if (glide) {
+      world.animate(head.root, { position: [x, y, z] }, { duration: GLIDE, easing: 'linear' });
+      world.animate(head.root, { rotation }, { duration: 0.14 });
+      if (moved && p.alive) {
+        const phase = ++head.stride % 2 === 0 ? 1 : -1;
+        head.legs.forEach((leg, legIndex) =>
+          world.animate(leg, { rotation: quat.y(PERSON.STRIDE * phase * (legIndex === 0 ? 1 : -1)) }, { duration: GLIDE, easing: 'easeInOut' })
+        );
+        world.animate(head.arm, { rotation: quat.y(-PERSON.STRIDE * phase * 0.7) }, { duration: GLIDE, easing: 'easeInOut' });
+        world.animate(head.visual, [{ position: [0, 0, l.cell * 0.055], at: 0.5 }, { position: [0, 0, 0] }], {
+          duration: GLIDE,
+          easing: 'easeInOut'
+        });
+        const flags = personMeshes().flags;
+        world.set(head.flag, { mesh: flags[head.stride % flags.length]! });
+        head.walking = true;
+      } else if (head.walking) rest(world, head);
+    } else {
+      world.stopAnimation(head.root);
+      world.set(head.root, { position: [x, y, z], rotation, scale: p.alive ? 1 : 0 });
+    }
+    head.col = p.col;
+    head.row = p.row;
+    if (popped[i]) {
+      // A banked trail: the flag bearer celebrates.
+      world.animate(head.root, [{ scale: 1.22, at: 0.3 }, { scale: 1 }], { duration: 0.35, easing: 'easeOut' });
+      const [cx, cy] = cellCentre(l, p.col, p.row);
+      effects.shatter(world, {
+        position: [cx * WORLD_SCALE, cy * WORLD_SCALE, (z + l.cell) * WORLD_SCALE],
+        count: 14,
+        size: l.cell * 0.3 * WORLD_SCALE,
+        speed: l.cell * 8 * WORLD_SCALE,
+        lifetime: 0.5,
+        gravity: -l.cell * 20 * WORLD_SCALE,
+        colors: [toColor(PLAYER_COLORS[i]!.head), toColor('#FFFFFF')]
+      });
+    }
+  });
+}
+
+/** The round's over: walking stops; the winner and their flag lift in celebration. */
+export function finish(world: World, l: Layout, s: Scene, won: boolean) {
+  s.heads.forEach((h, i) => {
+    rest(world, h);
+    const winner = (i === 0) === won;
+    world.stopAnimation(h.root);
+    if (winner) world.animate(h.root, [{ scale: PERSON.CELEBRATION_SCALE, at: 0.4 }, { scale: 1.3 }], { duration: 0.5, easing: 'easeOut' });
+    else world.animate(h.root, { scale: 0.75 }, { duration: 0.4 });
+  });
+  if (won)
+    effects.confetti(world, {
+      position: [0, 0, l.cell * 3 * WORLD_SCALE],
+      count: 70,
+      size: l.cell * 0.5 * WORLD_SCALE,
+      speed: l.gridW * 1.2 * WORLD_SCALE,
+      lifetime: 1.4,
+      gravity: -l.gridW * 2 * WORLD_SCALE,
+      colors: ['#6BCB77', '#FFD93D', '#FFFFFF', '#4CA85B'].map((c) => toColor(c))
+    });
+}
+
+/** Reusable assets; the game loader advances one builder per frame. */
+export function* warmAssets(): Iterable<() => unknown> {
+  for (let corners = 1; corners < 16; corners++) yield () => landMesh(corners);
+}