@origingame/engine 0.2.0 → 0.3.0

package/knowledge/scaffold/template/assets/timelines/intro.ogt

@@ -0,0 +1,101 @@
+type timeline
+version 1
+---
+name "Intro"
+duration 10
+# The camera's rail: a slow arc in front of the yard, from the left to the right.
+path "flyby" {
+  kind catmullRom
+  point -5 3.2 9
+  point -1.5 2.4 7.5
+  point 2 2 7
+  point 5 2.8 8.5
+}
+track camera {
+  rail "flyby"
+  key 0 {
+    at 0
+    target 0 1 0
+    fov 50
+  }
+  key 9.5 {
+    at 1
+    target 1.5 1 0
+    fov 42
+    ease cubicInOut
+  }
+}
+track transform "trickster" {
+  key 2 {
+    position 2 0 0
+  }
+  key 5 {
+    position 0.5 0 1.5
+    ease cubicInOut
+  }
+}
+track animation "trickster" {
+  key 0 {
+    clip "idle"
+    loop true
+  }
+  key 2 {
+    clip "walk"
+    loop true
+    blendIn 0.3
+  }
+  key 5 {
+    clip "wave"
+    blendIn 0.25
+  }
+}
+track caption {
+  captions "narration.srt"
+  style lg
+  anchor bottom
+}
+track audio {
+  key 1 {
+    sound "audio/blip.wav"
+    volume 0.6
+  }
+  key 5 {
+    sound "audio/click.ogt"
+  }
+}
+track music {
+  key 6 {
+    sound "audio/sting.ogt"
+    volume 0.7
+    fadeIn 0.3
+    fadeOut 1
+    end 9.5
+    loop true
+  }
+}
+track event {
+  key 5.5 {
+    do "spawn_wave:2"
+    retroactive true
+  }
+}
+track transition {
+  key 0 {
+    kind fade
+    mode in
+    duration 1
+  }
+  key 9 {
+    kind fade
+    mode out
+    duration 1
+  }
+}
+track marker {
+  key 2 {
+    name "walk"
+  }
+  key 5.5 {
+    name "drop"
+  }
+}

package/knowledge/scaffold/template/assets/timelines/narration.srt

@@ -0,0 +1,11 @@
+1
+00:00:00,800 --> 00:00:02,800
+The yard, before the drop.
+
+2
+00:00:03,000 --> 00:00:05,200
+The trickster walks out to meet it.
+
+3
+00:00:06,400 --> 00:00:08,800
+Here they come.

package/knowledge/scaffold/template/host.d.ts

@@ -0,0 +1,46 @@
+// The host this project's playtest helpers (tests/*.ts) touch under bun:
+// `node:` modules, `process`, `Buffer`, `TextEncoder`, `import.meta.url`.
+// Declared here because the project type-checks with `types: []` (no
+// @types/node, no bun-types): `og check` reads them through tsconfig.json's
+// include. Game code (src/) uses none of them.
+
+declare module "node:fs" {
+  export function existsSync(path: string): boolean;
+  export function readFileSync(path: string): Uint8Array;
+  export function readFileSync(path: string, encoding: string): string;
+  export function writeFileSync(path: string, data: string | Uint8Array): void;
+  export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
+  export function copyFileSync(from: string, to: string): void;
+}
+
+declare module "node:path" {
+  export function dirname(path: string): string;
+  export function join(...parts: string[]): string;
+  export function resolve(...parts: string[]): string;
+}
+
+declare module "node:url" {
+  export function fileURLToPath(url: string | URL): string;
+}
+
+declare module "node:zlib" {
+  export function inflateSync(data: Uint8Array): Uint8Array;
+  export function deflateSync(data: Uint8Array, options?: { level?: number }): Uint8Array;
+}
+
+declare const process: {
+  readonly env: Record<string, string | undefined>;
+  cwd(): string;
+  readonly stdout: { write(text: string): boolean };
+};
+declare const Buffer: { concat(chunks: readonly Uint8Array[]): Uint8Array };
+declare class TextEncoder {
+  encode(text: string): Uint8Array;
+}
+declare class URL {
+  constructor(url: string, base?: string | URL);
+  readonly href: string;
+}
+interface ImportMeta {
+  readonly url: string;
+}

package/knowledge/scaffold/template/package.json

@@ -13,6 +13,6 @@
     "test": "og test ."
   },
   "dependencies": {
-    "@origingame/engine": "0.2.0"
+    "@origingame/engine": "0.3.0"
   }
 }

package/knowledge/scaffold/template/project.ogt

@@ -7,7 +7,7 @@ version 1
 name "Origin Game"
 id "origin-game"
 # The engine this game is written against (design §9: upgrades are explicit).
-engine "0.2.0"
+engine "0.3.0"
 entry "src/main.ts"
 # 2d (orthographic camera, sprites, 2D physics) or 3d.
 profile "3d"

package/knowledge/scaffold/template/src/main.ts

@@ -66,7 +66,7 @@ export const Menu = defineSystem("Menu", { reads: [Spin, og.Input], writes: [Run
   const started = run.value.started;
   og.ui.column("Hud", { padding: { left: 24, top: 24, right: 24, bottom: 24 } }, () => og.ui.panel("Menu", { padding: { left: 20, top: 16, right: 20, bottom: 16 } }, () => {
     og.ui.label("Title", og.i18n.t(world, "menu.title"), { step: "displaySm" });
-    og.ui.label("Status", started ? og.i18n.t(world, "menu.spinning", { speed: speed.toFixed(1) }) : og.i18n.t(world, "menu.prompt"), { color: { token: started ? "accentInk" : "fgMuted" } });
+    og.ui.label("Status", started ? og.i18n.t(world, "menu.spinning", { speed: speed.toFixed(1) }) : og.i18n.t(world, "menu.prompt"), { color: { token: started ? "highlight" : "inkMuted" } });
     const start = og.ui.button("Start", og.i18n.t(world, started ? "menu.started" : "menu.start"), { variant: "primary", size: "large", disabled: started });
     if (!started && (start.clicked || input.value.pressed("KeyS") || input.value.pressed("Enter"))) run.value.started = true;
   }));

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

@@ -399,7 +399,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 +408,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 +428,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 +437,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 +457,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 +485,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-build/SKILL.md

@@ -14,8 +14,8 @@ needs a browser or a Rust toolchain. The command channel is
 The loop held for two whole games written from this package alone
 (`examples/lantern-vale`, `examples/hollowbell`): `og cook` took 47 and 69
 assets cold in 8.2 s and 3.6 s and under 100 ms after a change, without a
-warning, and every refusal named the line and the fix (a copied skin
-without its CJK `fallback` named the line and og-taste §1;
+warning, and every refusal named the line and the fix (a copied UI skin, as
+styles were then called, without its CJK `fallback` named the line and og-taste §1;
 `PostEffects.vignette is true or false` named the line). Scripted runs gave
 the same frames every time, `store: "keep"` relaunches and two-process
 replays worked the first time they were asked for, and `og polish` scored
@@ -201,7 +201,10 @@ every screen that matters.
 | feel | Sound on input | inputs answered by a sound within 6 ticks | every action | og-audio §1 |
 | feel | Frame time | step + render, p95, on the tier it ran on (`metal` on a Mac, `vulkan` on a GPU); the probe's own screenshots (render, read back, PNG) are not the game's step and are left out. Without a renderer the row says `n/a (no renderer)`, as do contrast, text size and HUD occupancy, which read frames | 8.3 ms (half the frame) | og-game §14 |
 
-The report also lists clipped samples in the mix (og-audio §4). Contrast and
+The report also lists clipped samples in the mix (og-audio §4), and a UI
+style finding (no score) when a shot's `dump_ui` reports `style` empty: the
+UI draws in prototype, the engine's placeholder, not a style of the game's
+own (og-taste §1). Contrast and
 text size read text only: icons and images (their "text" is a picture's
 name), disabled controls and what they hold (WCAG exempts them), the
 slivers a scroll container cuts, what a dialog's or a tutorial's scrim
@@ -218,7 +221,7 @@ so it depends on the glyphs' coverage: thin strokes cover few pixels
 whole, and a regular-weight CJK face at body sizes measures lower than
 Latin in the same colours (a 15 px "设置" 3.1:1 where "Settings" reads
 4.6:1 on one button), as it reads lower to the eye. Darken the ink in the
-skin's palette, give the CJK face a heavier weight or the label a larger
+style's palette, give the CJK face a heavier weight or the label a larger
 step; the measure is not wrong there. Facts are the game's `facts`
 (og-game §3): expose `hp`, `hits` or `kills` there or the hit measures stay
 n/a. A baseline line says how often things change with no input at all;
@@ -226,7 +229,7 @@ when it is high (a runner that always moves), read latency together with
 the frames.
 
 The numbers cannot judge a style. Read the frames before changing anything,
-fix the cause in the skin, the template or the system, never per call, and
+fix the cause in the style, the template or the system, never per call, and
 run it again after the fix: the report is the evidence.
 
 ## 6. Shipping

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

@@ -270,6 +270,17 @@ it is declared.
   probe and the command channel address entities by them.
 - Vector, quaternion, matrix, colour, transform and material vocabulary is
   three.js's (`position`, `quaternion`, `scale`, `metalness`, `roughness`).
+- Math on those values is three.js's methods as pure functions, imported
+  from `@origingame/engine`: `vec3`, `vec2`, `quat`, `mat4`, `box3`,
+  `sphere`, `plane`, `frustum`, `ray`, `color` (`vec3.add(a, b)`,
+  `quat.slerp(a, b, t)`, `mat4.transformPoint(m, p)`,
+  `frustum.fromCamera(...)` then `frustum.intersectsBox(f, box)`,
+  `ray.intersectTriangle(r, a, b, c)` answering a point or null,
+  `color.fromHex(0x14161b)` answering linear RGB). They never change their
+  arguments and answer new plain objects, so there are no classes to
+  construct and a result is written into a column as any other value;
+  they use only arithmetic and `sqrt`, so a system using them stays
+  deterministic. Signatures: `reference/math.md`.
 
 ## 7. Where the API is described