@origingame/engine 0.2.0 → 0.4.0

package/knowledge/scaffold/template/tests/frames.ts

@@ -0,0 +1,134 @@
+// The reference-frame check: decode the PNGs a run wrote and compare them
+// with references/<tier>/ under og-tests' tolerance (a channel off by more
+// than 32/255 is an outlier; fail above 0.5 % outliers or an RGB RMSE above
+// 0.01). A tier without its own references compares with `metal` and says
+// so. `OG_FX_CAPTURE=1 og test .` records this tier's references instead.
+// (Copied from templates/fx-showcase/tests/frames.ts, so the template stands alone.)
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inflateSync } from "node:zlib";
+import type { PlaytestChecks, PlaytestRun } from "@origingame/engine/playtest";
+
+export interface Image {
+  width: number;
+  height: number;
+  /** RGBA8 rows. */
+  rgba: Uint8Array;
+}
+
+/** An 8-bit RGB or RGBA, non-interlaced PNG, unfiltered. */
+export function decodePng(bytes: Uint8Array): Image {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let at = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 4;
+  const idat: Uint8Array[] = [];
+  while (at < bytes.length) {
+    const len = view.getUint32(at);
+    const type = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+    const data = bytes.subarray(at + 8, at + 8 + len);
+    if (type === "IHDR") {
+      width = view.getUint32(at + 8);
+      height = view.getUint32(at + 12);
+      const depth = data[8]!;
+      const color = data[9]!;
+      if (depth !== 8 || (color !== 6 && color !== 2) || data[12] !== 0) throw new Error(`unsupported PNG (depth ${depth}, colour ${color}, interlace ${data[12]})`);
+      channels = color === 6 ? 4 : 3;
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    at += 12 + len;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const out = new Uint8Array(width * height * 4);
+  const prev = new Uint8Array(stride);
+  const cur = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]!;
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    for (let i = 0; i < stride; i++) {
+      const a = i >= channels ? cur[i - channels]! : 0;
+      const b = prev[i]!;
+      const c = i >= channels ? prev[i - channels]! : 0;
+      let v = line[i]!;
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      cur[i] = v & 255;
+    }
+    for (let x = 0; x < width; x++) {
+      for (let k = 0; k < 4; k++) out[(y * width + x) * 4 + k] = k < channels ? cur[x * channels + k]! : 255;
+    }
+    prev.set(cur);
+  }
+  return { width, height, rgba: out };
+}
+
+/** og-tests' rule: outlier fraction and RGB RMSE between two equal-size frames. */
+export function difference(a: Image, b: Image): { outliers: number; rmse: number } {
+  if (a.width !== b.width || a.height !== b.height) return { outliers: 1, rmse: 1 };
+  let outliers = 0;
+  let sum = 0;
+  const n = a.width * a.height;
+  for (let p = 0; p < n; p++) {
+    let out = false;
+    for (let k = 0; k < 3; k++) {
+      const d = Math.abs(a.rgba[p * 4 + k]! - b.rgba[p * 4 + k]!);
+      if (d > 32) out = true;
+      const f = d / 255;
+      sum += f * f;
+    }
+    if (out) outliers++;
+  }
+  return { outliers: outliers / n, rmse: Math.sqrt(sum / (n * 3)) };
+}
+
+/** The playtest's output directory (the bundled playtest runs from it). */
+export function outDir(): string {
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+/** The project's references/, from its og-out/test/<name>/. */
+export function referencesDir(): string {
+  return resolve(outDir(), "..", "..", "..", "references");
+}
+
+/** Compares each screenshot with its reference (`<prefix><file>`), or records it. */
+export function checkFrames(run: PlaytestRun, t: PlaytestChecks, files: readonly string[], prefix: string): void {
+  // Read only where there is a renderer: without one (tier `none`) each frame is
+  // reported "no renderer, frame unchecked" and every other check still runs.
+  t.frame(files, () => {
+    const refs = referencesDir();
+    t.ok(existsSync(refs) || process.env.OG_FX_CAPTURE !== undefined, `the references directory exists at ${refs}`);
+    const own = join(refs, run.tier);
+    const capture = process.env.OG_FX_CAPTURE !== undefined;
+    for (const f of files) {
+      const actual = join(outDir(), f);
+      // Each file on its own: this tier's reference where it has one, metal's otherwise.
+      const mine = join(own, prefix + f);
+      const ref = capture || existsSync(mine) ? mine : join(refs, "metal", prefix + f);
+      if (ref !== mine) process.stdout.write(`  note: no ${run.tier} reference for ${prefix}${f}; comparing with metal\n`);
+      if (capture) {
+        mkdirSync(own, { recursive: true });
+        copyFileSync(actual, ref);
+        t.ok(true, `recorded ${ref}`);
+        continue;
+      }
+      if (!existsSync(ref)) {
+        t.ok(false, `${ref} is missing: record it with OG_FX_CAPTURE=1 og test .`);
+        continue;
+      }
+      const d = difference(decodePng(readFileSync(actual)), decodePng(readFileSync(ref)));
+      process.stdout.write(`  ${f}: ${(d.outliers * 100).toFixed(3)} % outliers, RMSE ${d.rmse.toFixed(5)} against ${ref}\n`);
+      t.ok(d.outliers <= 0.005 && d.rmse <= 0.01, `${f} matches ${prefix}${f}: ${(d.outliers * 100).toFixed(3)} % outliers (≤ 0.5 %), RMSE ${d.rmse.toFixed(5)} (≤ 0.01)`);
+    }
+  });
+}

package/knowledge/scaffold/template/tests/intro.og.ts

@@ -0,0 +1,65 @@
+// The intro cutscene (assets/timelines/intro.ogt) played from the command
+// channel: `timeline:play:intro` makes the entity `timeline-intro`, and the
+// timeline drives the camera along the "flyby" rail, walks the trickster
+// with its clips, shows the narration from narration.srt, plays two sounds,
+// runs `spawn_wave:2` at 5.5 s and fades in and out. At 4 s and 8 s the
+// caption on screen is the .srt's cue for that time and the frames are
+// compared with references/<tier>/intro-4.png and intro-8.png
+// (tests/frames.ts; `OG_FX_CAPTURE=1 og test .` records them). After the end
+// the camera is the game's again.
+import { playtest } from "@origingame/engine/playtest";
+import { checkFrames } from "./frames.ts";
+
+interface EntityDump {
+  components: Record<string, Record<string, number | boolean | string | number[]>>;
+}
+
+interface UiDump {
+  elements: Array<{ id: string; text: string; x: number; y: number; width: number; height: number }>;
+}
+
+const FILES = ["intro-4.png", "intro-8.png"] as const;
+
+export default playtest({
+  name: "the intro plays its rail camera, captions, clips, event and fades from timeline:play:intro",
+  size: "1280x720",
+  commands: [
+    "0:timeline:play:intro",
+    "4:screenshot:intro-4.png",
+    "4:dump_ui:ui-4.json",
+    "4:dump_entity:timeline-intro:timeline-4.json",
+    "4:dump_entity:trickster:trickster-4.json",
+    "8:screenshot:intro-8.png",
+    "8:dump_ui:ui-8.json",
+    "8:dump_world:world-8.json",
+    "10.5:dump_entity:timeline-intro:timeline-end.json",
+    "10.5:dump_ui:ui-end.json",
+    "10.6:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    t.ok(run.quit, "the script reached quit");
+    const caption = (file: string) =>
+      run.json<UiDump>(file).elements.find((e) => e.id.startsWith("timeline-caption-") && e.id.endsWith("-text"));
+    const at4 = caption("ui-4.json");
+    t.equal(at4?.text, "The trickster walks out to meet it.", "at 4 s the caption is the .srt's second cue");
+    t.ok(at4 !== undefined && at4.y > 600, `the caption sits at the bottom (y ${at4?.y})`);
+    t.equal(caption("ui-8.json")?.text, "Here they come.", "at 8 s the caption is the third cue");
+    const tl = run.json<EntityDump>("timeline-4.json").components["og.Timeline"]!;
+    t.equal(tl["playing"], true, "the timeline plays at 4 s");
+    t.near(Number(tl["time"]), 4, 0.02, "its time is the run's (it started at tick 0)");
+    // The transform track walks the trickster from (2 0 0) at 2 s to (0.5 0 1.5) at 5 s.
+    const p = run.json<EntityDump>("trickster-4.json").components["og.Transform"]!["position"] as number[];
+    t.ok(p[0]! < 2 && p[0]! > 0.5 && p[2]! > 0 && p[2]! < 1.5, `the trickster is on its way at 4 s (${p.join(", ")})`);
+    const world = run.json<{ entities: number }>("world-8.json");
+    t.ok(world.entities >= 10, `the event key at 5.5 s ran spawn_wave:2 (${world.entities} entities)`);
+    const end = run.json<EntityDump>("timeline-end.json").components["og.Timeline"]!;
+    t.equal(end["playing"], false, "the timeline ended");
+    t.equal(Number(end["time"]), 10, "at its duration");
+    t.equal(caption("ui-end.json"), undefined, "no caption after the end");
+    t.frame(FILES, () => {
+      for (const f of FILES) t.equal(run.png(f).width, 1280, `${f} is 1280 wide`);
+    });
+    checkFrames(run, t, FILES, "");
+  },
+});

package/knowledge/scaffold/template/tests/smoke.og.ts

@@ -1,43 +1,37 @@
 // The template's playtest, run by `og test` through `og run --headless
 // --commands`: a tap on the menu's Start button (found by its UI id, no key
 // fallback) starts the trickster spinning and drops the crate onto the
-// ground; the frame, the dumps and the UI tree are written.
+// ground. Every check is an `expect:` step evaluated in the run at its tick
+// (docs/design.md §3.4): a failed one fails the run with the tick and what
+// it observed, and a frame one without a renderer is reported unchecked.
+// The frame, the scene described as data, the dumps and the UI tree are
+// written beside them.
 import { playtest } from "@origingame/engine/playtest";
 
-interface EntityDump {
-  components: Record<string, Record<string, number | boolean | string | number[]>>;
-}
-
-interface UiDump {
-  elements: Array<{ id: string; parent: string; text: string; x: number; y: number; width: number; height: number }>;
-}
-
 export default playtest({
-  name: "A tap on Start spins the trickster and drops the crate; the run writes its frame, dumps and UI tree",
-  commands:
-    "0.5:touch_move_to:Start;0.6:touch_start;0.7:touch_end;" +
-    "2.0:screenshot:smoke.png;2.1:dump_entity:trickster:trickster.json;2.15:dump_entity:crate:crate.json;" +
-    "2.2:dump_world:world.json;2.3:dump_ui:ui.json;2.5:quit",
-  check(run, t) {
-    t.ok(run.quit, "the script reached quit");
-    // Frames are read inside t.frame: without a renderer (og test in a sandbox
-    // with no GPU) the frame is reported unchecked and every other check runs.
-    t.frame("smoke.png", () => {
-      const frame = run.png("smoke.png");
-      t.ok(frame.width > 0 && frame.height > 0, `a ${frame.width}x${frame.height} frame was captured`);
-    });
-    const world = run.json<{ entities: number; systems: Array<{ name: string; matched: number | null }> }>("world.json");
-    t.ok(world.entities >= 5, `the scene spawned with the crate (${world.entities} entities)`);
-    t.ok(world.systems.some((s) => s.name === "Rotate" && s.matched === 1), "Rotate matches the trickster");
-    const ui = run.json<UiDump>("ui.json");
-    const start = ui.elements.find((e) => e.id === "Start");
-    t.ok(start !== undefined && start.width > 0 && start.height > 0, "the UI tree has the Start button with bounds");
-    t.ok(start?.text === "Started", `the button reads "${start?.text}" after the tap`);
-    const trickster = run.json<EntityDump>("trickster.json");
-    const spin = trickster.components["Spin"]!;
-    t.ok(Number(spin["speed"]) > 0, `the trickster spins (${spin["speed"]} rad/s)`);
-    const crate = run.json<EntityDump>("crate.json");
-    const y = (crate.components["og.Transform"]!["position"] as number[])[1]!;
-    t.ok(y > 0.4 && y < 0.6, `the crate fell from 4 m and rests on the ground (y ${y.toFixed(3)})`);
-  },
+  name: "A tap on Start spins the trickster and drops the crate; the run writes its frame, description, dumps and UI tree",
+  commands: [
+    "0.5:touch_move_to:Start",
+    "0.6:touch_start",
+    "0.7:touch_end",
+    // The tap was one press; the run started; the button says so.
+    "0.8:expect:event:og.PointerDown:1",
+    "0.8:expect:state:started==true",
+    "0.9:expect:ui:text:=Started",
+    // The trickster spins; the crate fell from 4 m and rests on the ground.
+    "2.0:expect:state:spin>0",
+    "2.0:expect:entity:crate:within:-3,0.4,-1,1,0.6,2",
+    "2.0:expect:event:og.CollisionStarted",
+    // The frame (1280x720): the sky at the top, the crate and the trickster where they stand.
+    "2.0:screenshot:smoke.png",
+    "2.0:expect:region:560,16,64,24:color:#9da5b1:24",
+    "2.0:expect:entity:crate:within:380,360,280,240",
+    "2.0:expect:entity:trickster:within:640,300,240,280",
+    "2.1:describe:describe.json",
+    "2.1:dump_entity:trickster:trickster.json",
+    "2.15:dump_entity:crate:crate.json",
+    "2.2:dump_world:world.json",
+    "2.3:dump_ui:ui.json",
+    "2.5:quit",
+  ].join(";"),
 });

package/knowledge/scaffold/template/tsconfig.json

@@ -13,5 +13,5 @@
     "allowImportingTsExtensions": true,
     "noEmit": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "host.d.ts"]
 }

package/knowledge/scripts/mount.ts

@@ -90,7 +90,8 @@ export function mount(roots: Roots, production: string, write: boolean): MountRe
     if (exists && lstatSync(target).isDirectory()) throw new Error(`${f.path}: a directory in the platform tree where the package has a file`);
     const same = exists && Buffer.compare(readFileSync(target), Buffer.from(f.bytes)) === 0;
     const mode = executable(f.source) ? 0o755 : 0o644;
-    const modeSame = exists && (statSync(target).mode & 0o777) === mode;
+    // Windows chmod cannot represent POSIX group/other or executable bits.
+    const modeSame = exists && (process.platform === "win32" || (statSync(target).mode & 0o777) === mode);
     if (same && modeSame) continue;
     changes.push({ kind: exists ? "changed" : "added", path: f.path });
     if (write) {

package/knowledge/scripts/validate.ts

@@ -44,7 +44,20 @@ export function readRules(pkg: string): Rules {
 }
 
 /** The skills this package ships. */
-export const SKILLS = ["og-ai", "og-audio", "og-build", "og-core", "og-feel", "og-game", "og-i18n", "og-platform-sdk", "og-taste", "og-ui"] as const;
+export const SKILLS = ["og-ai", "og-audio", "og-build", "og-core", "og-feel", "og-game", "og-i18n", "og-model", "og-platform-sdk", "og-taste", "og-ui"] as const;
+
+/**
+ * The guides this package ships: hand-written pages in guides/, mounted
+ * beside og-game's SKILL.md (knowledge.json), each named by og-game and
+ * held to the skills' rules (API names, section references, tools).
+ */
+export const GUIDES = ["three-to-og"] as const;
+
+/** Where knowledge.json mounts guides/ in the production tree. */
+export const GUIDE_MOUNT = "game/skills/og-game/guides/";
+
+/** The og-cli source that cites the guides by section, in the engine repository. */
+export const GUIDE_CITERS = ["crates/og-cli/src/migrate.rs"] as const;
 
 /** What a scaffolded project must contain (scaffold/README.md describes each). */
 export const TEMPLATE_FILES = ["project.ogt", "src/main.ts", "package.json", "tsconfig.json", "tests/smoke.og.ts"] as const;
@@ -79,7 +92,9 @@ export function validate(roots: Roots = defaultRoots()): string[] {
   }
 
   skills(rules, files, problems);
+  guideFiles(roots, rules, files, problems);
   coherence(files, problems);
+  skinWord(roots, files, problems);
   apiNames(roots, files, problems);
   looks(roots, files, problems);
   grammar(roots, files, problems);
@@ -91,7 +106,7 @@ function packageJson(roots: Roots, problems: string[]): void {
   const p = JSON.parse(readFileSync(join(roots.pkg, "package.json"), "utf8")) as { name?: string; version?: string; files?: string[]; scripts?: Record<string, string> };
   if (p.name !== "@origingame/engine-knowledge") problems.push(`package.json: name is ${p.name}; the package is @origingame/engine-knowledge (design §9)`);
   if (!/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(p.version ?? "")) problems.push(`package.json: version ${p.version} is not semver`);
-  for (const f of ["wiki", "skills", "looks", "scaffold", "rules", "knowledge.json"]) {
+  for (const f of ["wiki", "skills", "guides", "looks", "scaffold", "rules", "knowledge.json"]) {
     if (!p.files?.some((x) => x === f || x === `${f}/`)) problems.push(`package.json: files does not publish ${f}`);
   }
   if (!p.scripts?.test) problems.push("package.json: no test script, so scripts/check.sh bun-test would skip the package");
@@ -165,6 +180,46 @@ function skills(rules: Rules, files: readonly PayloadFile[], problems: string[])
   for (const s of SKILLS) if (!found.has(s)) problems.push(`skills/${s}/SKILL.md: missing`);
 }
 
+/**
+ * The guides as files: guides/ holds exactly GUIDES, each reaches the
+ * payload at GUIDE_MOUNT, names no tool a Session lacks and no wiki page
+ * the IDL does not generate, and every `three-to-og §N` the og-cli source
+ * cites (GUIDE_CITERS: `og migrate three` points to its sections) is a
+ * numbered section of the guide.
+ */
+function guideFiles(roots: Roots, rules: Rules, files: readonly PayloadFile[], problems: string[]): void {
+  const dir = join(roots.pkg, "guides");
+  const present = existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(".md")).map((n) => n.slice(0, -3)) : [];
+  for (const g of present) if (!(GUIDES as readonly string[]).includes(g)) problems.push(`guides/${g}.md: not in GUIDES (scripts/validate.ts); list it there and name it from og-game, or remove it`);
+  const pages = new Set(files.map((f) => /^game\/skills\/og-game\/reference\/([^/]+)$/.exec(f.path)?.[1]).filter((n): n is string => n !== undefined));
+  const repo = join(roots.pkg, "..", "..");
+  for (const g of GUIDES) {
+    const f = files.find((x) => x.path === `${GUIDE_MOUNT}${g}.md`);
+    if (!f) {
+      problems.push(`guides/${g}.md: missing, or not mounted at ${GUIDE_MOUNT} (knowledge.json mounts guides/ there)`);
+      continue;
+    }
+    if (!isText(f.bytes)) continue;
+    const text = decoder.decode(f.bytes);
+    for (const t of namedTools(text, rules)) problems.push(`guides/${g}.md: names \`${t}\`, which is no tool a Session can be offered; rename it or put it in a code block if it is not a tool`);
+    for (const page of new Set([...text.matchAll(/\breference\/([a-z0-9-]+\.md)\b/g)].map((m) => m[1]!))) {
+      if (!pages.has(page)) problems.push(`guides/${g}.md: names reference/${page}, which the generated wiki does not have (a module's page is reference/<module>.md)`);
+    }
+    const have = new Set([...text.matchAll(/^## (\d+)\. /gm)].map((m) => m[1]!));
+    for (const citer of GUIDE_CITERS) {
+      const path = join(repo, citer);
+      if (!existsSync(join(repo, "crates"))) break; // the published package: the sources are not beside it
+      if (!existsSync(path)) {
+        problems.push(`${citer}: missing; GUIDE_CITERS in scripts/validate.ts names it`);
+        continue;
+      }
+      for (const m of readFileSync(path, "utf8").matchAll(new RegExp(`${g} §(\\d+)`, "g"))) {
+        if (!have.has(m[1]!)) problems.push(`${citer}: cites ${g} §${m[1]}, which guides/${g}.md does not have (its sections: ${[...have].join(", ")})`);
+      }
+    }
+  }
+}
+
 function scaffold(roots: Roots, rules: Rules, overlay: string, files: readonly PayloadFile[], byPath: Map<string, PayloadFile>, problems: string[]): void {
   const prefix = `game-scaffold/${overlay}/`;
   if (rules.scaffold.existingOverlays.includes(overlay)) {
@@ -255,7 +310,15 @@ function coherence(files: readonly PayloadFile[], problems: string[]): void {
     const t = textOf(`game/skills/${s}/SKILL.md`);
     if (t !== undefined) texts.set(s, t);
   }
-  const sections = new Map([...texts].map(([s, t]) => [s, new Set([...t.matchAll(/^## (\d+)\. /gm)].map((m) => m[1]!))]));
+  // The guides (guides/<name>.md, mounted beside og-game's SKILL.md) are
+  // held to the same section references; their owner names each.
+  const guides = new Map<string, string>();
+  for (const g of GUIDES) {
+    const t = textOf(`${GUIDE_MOUNT}${g}.md`);
+    if (t !== undefined) guides.set(g, t);
+  }
+  const numbered = (t: string) => new Set([...t.matchAll(/^## (\d+)\. /gm)].map((m) => m[1]!));
+  const sections = new Map([...texts, ...guides].map(([s, t]) => [s, numbered(t)]));
   for (const [module, skill] of home) {
     const t = texts.get(skill);
     if (t !== undefined && !t.includes(`reference/${module}.md`)) problems.push(`skills/${skill}/SKILL.md: teaches the ${module} module (wiki/index.md) but never names reference/${module}.md`);
@@ -265,22 +328,76 @@ function coherence(files: readonly PayloadFile[], problems: string[]): void {
       const owner = home.get(m);
       if (owner && owner !== skill) problems.push(`skills/${skill}/SKILL.md: names reference/${m}.md, which ${owner} teaches; point to ${owner} instead, so each module is taught in one place`);
     }
-    const prose = t.replace(/^```[\s\S]*?^```/gm, "");
-    for (const m of prose.matchAll(/(og-[a-z]+(?:-[a-z]+)*) §([A-Za-z][\w ]*)/g)) problems.push(`skills/${skill}/SKILL.md: refers to ${m[1]} §${m[2]!.split(" ")[0]} by name; refer to a skill's sections by their numbers (## N.)`);
-    for (const m of prose.matchAll(/§(\d+)/g)) {
-      // The skill this § belongs to: walk back over a list of §s ("og-feel
-      // §9–§11", "og-taste §4, §10") to the word before it.
-      const before = prose.slice(0, m.index).split(/\s+/);
-      let i = before.length - 1;
-      while (i >= 0 && (before[i] === "" || /^\(?§\d+(\.\d+)?[–,;)]*$/.test(before[i]!) || before[i] === "and" || before[i] === "or")) i--;
-      const word = (before[i] ?? "").replace(/^[(`*]+/, "");
-      let target: string | undefined = skill;
-      if (/^og-[a-z]+(?:-[a-z]+)*$/.test(word)) target = word;
-      else if (/\.md\b|\//.test(word) || /^design/.test(word)) target = undefined;
-      if (target === undefined) continue;
-      const have = sections.get(target);
-      if (!have) problems.push(`skills/${skill}/SKILL.md: refers to ${target} §${m[1]}, and there is no skill ${target}`);
-      else if (!have.has(m[1]!)) problems.push(`skills/${skill}/SKILL.md: refers to ${target === skill ? "its own" : target} §${m[1]}, which ${target === skill ? "it does not have" : "does not exist there"} (its sections: ${[...have].join(", ") || "none numbered"})`);
+  }
+  for (const [name, t] of [...texts, ...guides]) {
+    const at = guides.has(name) ? `guides/${name}.md` : `skills/${name}/SKILL.md`;
+    problems.push(...sectionRefs(at, name, t, sections));
+  }
+  // What the guides say of a page, and who names them.
+  const names = (t: string) => new Set([...t.matchAll(/\bguides\/([a-z0-9-]+)\.md\b/g)].map((m) => m[1]!));
+  for (const [name, t] of [...texts, ...guides]) {
+    const at = guides.has(name) ? `guides/${name}.md` : `skills/${name}/SKILL.md`;
+    for (const g of names(t)) if (!(GUIDES as readonly string[]).includes(g)) problems.push(`${at}: names guides/${g}.md, which this package does not ship (its guides: ${GUIDES.join(", ")})`);
+  }
+  for (const g of guides.keys()) {
+    if (!texts.get("og-game")?.includes(`guides/${g}.md`)) problems.push(`skills/og-game/SKILL.md: never names guides/${g}.md, so no agent finds the guide; name it where its subject is taught`);
+  }
+}
+
+/**
+ * Every section reference of one text (`og-feel §4`, or `§4` for its own,
+ * `three-to-og §2` for a guide's) names a numbered `## N.` section that
+ * exists: `at` names the text in the messages, `own` the text itself.
+ */
+export function sectionRefs(at: string, own: string, text: string, sections: ReadonlyMap<string, ReadonlySet<string>>): string[] {
+  const problems: string[] = [];
+  const prose = text.replace(/^```[\s\S]*?^```/gm, "");
+  for (const m of prose.matchAll(/(og(?:-[a-z]+)+|three-to-og) §([A-Za-z][\w ]*)/g)) problems.push(`${at}: refers to ${m[1]} §${m[2]!.split(" ")[0]} by name; refer to a skill's sections by their numbers (## N.)`);
+  for (const m of prose.matchAll(/§(\d+)/g)) {
+    // The text this § belongs to: walk back over a list of §s ("og-feel
+    // §9–§11", "og-taste §4, §10") to the word before it.
+    const before = prose.slice(0, m.index).split(/\s+/);
+    let i = before.length - 1;
+    while (i >= 0 && (before[i] === "" || /^\(?§\d+(\.\d+)?[–,;)]*$/.test(before[i]!) || before[i] === "and" || before[i] === "or")) i--;
+    const word = (before[i] ?? "").replace(/^[(`*]+/, "");
+    let target: string | undefined = own;
+    if (/^og-[a-z]+(?:-[a-z]+)*$/.test(word) || (GUIDES as readonly string[]).includes(word)) target = word;
+    else if (/\.md\b|\//.test(word) || /^design/.test(word)) target = undefined;
+    if (target === undefined) continue;
+    const have = sections.get(target);
+    if (!have) problems.push(`${at}: refers to ${target} §${m[1]}, and there is no skill ${target}`);
+    else if (!have.has(m[1]!)) problems.push(`${at}: refers to ${target === own ? "its own" : target} §${m[1]}, which ${target === own ? "it does not have" : "does not exist there"} (its sections: ${[...have].join(", ") || "none numbered"})`);
+  }
+  return problems;
+}
+
+/**
+ * What a sentence that says "skin" must also name for the word to be one of
+ * its other meanings: a glTF rig's skin (joints, morphs, a model), the
+ * character controllers' collision gap (the `skin` field, off a surface),
+ * a 2D skeleton's skin (a rig2d `skin` block swapping a slot's attachment,
+ * `og.Skeleton2D.skin`, an armature's setup pose), or a surface (a skin
+ * tone, peach skin, a crowd's or a tile set's looks).
+ */
+export const SKIN_ELSEWHERE = /gltf|joint|skelet|morph|\brig\b|bone|mesh|model|clips?\b|anim|`skins?`|slot|attach|armature|\bswap\b|setup pose|surface|\bgap\b|collid|\btones?\b|peach|crowd|tiles/i;
+
+/**
+ * A skill or wiki page never calls a UI style a "skin": og-ui's word is
+ * style (`type style`, `og.load.style`, `UiDesc.style`, `styles/<name>/`).
+ * Each sentence holding `skin` or `skins` must name one of the word's
+ * other meanings (SKIN_ELSEWHERE).
+ */
+function skinWord(roots: Roots, files: readonly PayloadFile[], problems: string[]): void {
+  for (const f of files) {
+    if (!f.path.startsWith("game/skills/") || !f.path.endsWith(".md") || !isText(f.bytes)) continue;
+    const name = relative(roots.pkg, f.source).split("\\").join("/");
+    for (const paragraph of decoder.decode(f.bytes).split(/\n\s*\n/)) {
+      // Sentences, and a table's cells, of the paragraph's joined lines.
+      for (const sentence of paragraph.replace(/\s*\n\s*/g, " ").split(/(?<=[.;!?])\s+|\s\|\s/)) {
+        if (/\bskins?\b/i.test(sentence) && !SKIN_ELSEWHERE.test(sentence)) {
+          problems.push(`${name}: calls a UI style a skin ("${sentence.trim().slice(0, 120)}"); og-ui's word is style (type style, og.load.style, styles/<name>/)`);
+        }
+      }
     }
   }
 }
@@ -312,6 +429,7 @@ export const NOT_FIELDS: Record<string, string> = {
   runs: "PlaytestDesc.runs (packages/engine/src/playtest.ts)",
   then: "PlaytestDesc.then (packages/engine/src/playtest.ts)",
   store: "PlaytestRun.store (packages/engine/src/playtest.ts)",
+  setup: "PlaytestDesc.setup (packages/engine/src/playtest.ts)",
 };
 
 export function readApiNames(engine: string): ApiNames | undefined {
@@ -353,8 +471,9 @@ function apiNames(roots: Roots, files: readonly PayloadFile[], problems: string[
   if (!api) return;
   for (const f of files) {
     const m = /^game\/skills\/([^/]+)\/SKILL\.md$/.exec(f.path);
-    if (!m || !isText(f.bytes)) continue;
-    const at = `skills/${m[1]}/SKILL.md`;
+    const guide = f.path.startsWith(GUIDE_MOUNT) && f.path.endsWith(".md") ? f.path.slice(GUIDE_MOUNT.length) : undefined;
+    if ((!m && !guide) || !isText(f.bytes)) continue;
+    const at = guide ? `guides/${guide}` : `skills/${m![1]}/SKILL.md`;
     const text = decoder.decode(f.bytes);
     const bad = new Set<string>();
     for (const x of text.matchAll(/(?<![\w./@-])og\.([A-Za-z_]\w*)(?:\.([A-Za-z_]\w*))?/g)) {
@@ -399,7 +518,7 @@ interface Style {
   checks: string[];
   premise: Record<string, string>;
   look: { preset: string; presetReady: boolean; support: string; primitives: string[]; missing: string[] };
-  skin: string;
+  ui: string;
   palette: { size: string; rules: string };
   assets: Record<string, string>;
   artBible: { direction: string; avoid: string[] };
@@ -408,7 +527,7 @@ interface Style {
 /** What `look.support` may say: full (every primitive draws), partial or planned (`missing` names what is still to land), content (the look is authored art). */
 export const SUPPORT = ["full", "partial", "planned", "content"] as const;
 /** The placeholders the art-bible template may use. */
-export const BIBLE_FIELDS = ["title", "premise", "camera", "platform", "name", "descriptor", "direction", "palette", "assets", "skin", "avoid", "game", "slug", "checks"] as const;
+export const BIBLE_FIELDS = ["title", "premise", "camera", "platform", "name", "descriptor", "direction", "palette", "assets", "ui", "avoid", "game", "slug", "checks"] as const;
 const PREMISE = ["genre", "mood", "era", "audience"];
 const ASSET_SPECS = ["logicalResolution", "spriteScale", "faceBudget", "outlinePx", "textureDensity"];
 
@@ -428,7 +547,7 @@ function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]):
     problems.push(`${at}: missing; og-taste §12 reads the style catalogue from it`);
     return;
   }
-  let cat: { schemaVersion?: number; categories?: Record<string, string>; skins?: string[]; artBibleTemplate?: string; styles?: Style[] };
+  let cat: { schemaVersion?: number; categories?: Record<string, string>; ui?: string[]; artBibleTemplate?: string; styles?: Style[] };
   try {
     cat = JSON.parse(readFileSync(path, "utf8"));
   } catch (e) {
@@ -437,7 +556,10 @@ function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]):
   }
   if (cat.schemaVersion !== 1) problems.push(`${at}: schemaVersion ${cat.schemaVersion}, expected 1`);
   const categories = Object.keys(cat.categories ?? {});
-  const skins = cat.skins ?? [];
+  const packs = cat.ui ?? [];
+  for (const p of packs) {
+    if (existsSync(join(roots.pkg, "..", "..", "templates")) && !existsSync(join(roots.pkg, "..", "..", "templates", "styles", p, "style.ogt"))) problems.push(`${at}: ui names ${p}, which is not a built-in style (templates/styles/${p}/style.ogt)`);
+  }
   for (const m of (cat.artBibleTemplate ?? "").matchAll(/\{(\w+)\}/g)) {
     if (!(BIBLE_FIELDS as readonly string[]).includes(m[1]!)) problems.push(`${at}: artBibleTemplate uses {${m[1]}}, which is none of ${BIBLE_FIELDS.join(", ")}`);
   }
@@ -454,9 +576,9 @@ function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]):
     if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(s.slug ?? "")) problems.push(`${id}: slug is not lowercase-hyphen`);
     if (seen.has(s.slug)) problems.push(`${id}: a second style with this slug`);
     seen.add(s.slug);
-    for (const k of ["name", "descriptor", "skin"] as const) if (!text(s[k])) problems.push(`${id}: no ${k}`);
+    for (const k of ["name", "descriptor", "ui"] as const) if (!text(s[k])) problems.push(`${id}: no ${k}`);
     if (!categories.includes(s.category)) problems.push(`${id}: category ${s.category} is none of ${categories.join(", ")}`);
-    if (!skins.includes(s.skin)) problems.push(`${id}: skin ${s.skin} is none of the packs (${skins.join(", ")})`);
+    if (!packs.includes(s.ui)) problems.push(`${id}: ui ${s.ui} is none of the built-in styles (${packs.join(", ")})`);
     if (!Array.isArray(s.checks) || s.checks.length !== 3 || !s.checks.every(text)) problems.push(`${id}: needs exactly three checks a critic can judge on a frame`);
     for (const k of PREMISE) if (!text(s.premise?.[k])) problems.push(`${id}: premise has no ${k}`);
     for (const k of ASSET_SPECS) if (!text(s.assets?.[k])) problems.push(`${id}: assets has no ${k}`);
@@ -482,15 +604,21 @@ function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]):
     const preset = join(repo, look.preset);
     if (look.presetReady) {
       if (existsSync(join(repo, "templates")) && !existsSync(preset)) problems.push(`${id}: presetReady, but ${look.preset} does not exist`);
-      else if (existsSync(preset) && !/^type look\s*$/m.test(readFileSync(preset, "utf8"))) problems.push(`${id}: ${look.preset} is not an .ogt of type look`);
+      else if (existsSync(preset)) {
+        const body = readFileSync(preset, "utf8");
+        if (!/^type look\s*$/m.test(body)) problems.push(`${id}: ${look.preset} is not an .ogt of type look`);
+        // The preset dresses the UI in the style the catalogue gives it.
+        const ui = /^ui[ \t]+"([^"]+)"/m.exec(body)?.[1];
+        if (ui !== s.ui) problems.push(`${id}: ${look.preset} has ${ui ? `ui "${ui}"` : "no ui line"}; the catalogue says ui "${s.ui}"`);
+      }
     }
     if (tasteText && !tasteText.includes(`\`${s.slug}\``)) problems.push(`skills/og-taste/SKILL.md: the style catalogue (§12) does not list \`${s.slug}\``);
     else if (tasteText) {
-      // §12's row for the style says what the catalogue says: family, name, support, skin.
+      // §12's row for the style says what the catalogue says: family, name, support, ui style.
       const row = new RegExp(`^\\| \`${s.slug.replace(/[-]/g, "\\-")}\` \\| ([^|]+) \\| ([^|]+) \\| ([^|]+) \\| \`([^\`]+)\` \\|$`, "m").exec(tasteText);
-      const want = [cat.categories?.[s.category] ?? s.category, s.name, look.support, s.skin];
+      const want = [cat.categories?.[s.category] ?? s.category, s.name, look.support, s.ui];
       const have = row?.slice(1, 5).map((x) => x.trim());
-      if (!have) problems.push(`skills/og-taste/SKILL.md: §12's table has no row for \`${s.slug}\` (| slug | family | style | support | skin |)`);
+      if (!have) problems.push(`skills/og-taste/SKILL.md: §12's table has no row for \`${s.slug}\` (| slug | family | style | support | ui |)`);
       else if (have.join("|") !== want.join("|")) problems.push(`skills/og-taste/SKILL.md: §12's row for \`${s.slug}\` reads ${have.join(", ")}; the catalogue says ${want.join(", ")}`);
     }
     const all = JSON.stringify(s);

package/knowledge/skills/og-audio/SKILL.md

@@ -58,14 +58,14 @@ game's style needs it; presets are a floor, not a style.
 ## 3. UI sounds
 
 `og.ui.configure(world, { sounds: { hover, press, open, close, success, error } })`
-(or the skin's `sound` lines) plays them on the `ui` bus: `click` for
+(or the style's `sound` lines) plays them on the `ui` bus: `click` for
 press, `select` for success, `back` for close, `error` for a refused press
 (and for `og.ui.shake({ sound: true })`, og-ui §6). Each starts in the
 tick of its input. `hover` also answers keyboard and gamepad focus moving
 to a control, and `press` a press by Enter, Space or the pad's A, so a
 menu walked with a pad is heard step by step; keep `hover` short and quiet
 (volume ≤ 0.3). `configure` changes only the fields it is given: setting
-the sounds after a skin (or a look that brings one) keeps the skin and its
+the sounds after a style (or a look that brings one) keeps the style and its
 fonts, and `sounds: null` silences them again.
 
 ## 4. Buses and the mix