@origingame/engine 0.3.0 → 0.5.0

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,10 +92,13 @@ 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);
+  problems.push(...ogtShape(skillTexts(files)));
   scaffold(roots, rules, manifest.overlay, files, byPath, problems);
   return problems;
 }
@@ -91,7 +107,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 +181,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 +311,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 +329,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 +430,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 +472,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)) {
@@ -398,7 +518,7 @@ interface Style {
   descriptor: string;
   checks: string[];
   premise: Record<string, string>;
-  look: { preset: string; presetReady: boolean; support: string; primitives: string[]; missing: string[] };
+  look: { preset: string; presetReady: boolean; support: string; profiles: string[]; primitives: string[]; missing: string[] };
   ui: string;
   palette: { size: string; rules: string };
   assets: Record<string, string>;
@@ -407,6 +527,8 @@ 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;
+/** What `look.profiles` may name: the project profiles a style draws for (create's premise match never offers a style outside the game's). */
+export const PROFILES = ["2d", "3d"] as const;
 /** The placeholders the art-bible template may use. */
 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"];
@@ -418,7 +540,7 @@ const ASSET_SPECS = ["logicalResolution", "spriteScale", "faceBudget", "outlineP
  * bible direction), its preset path `templates/looks/<slug>.ogt` (a
  * `type look` file when presetReady), its support honest (`missing` names
  * the primitives a style that is not `full` lacks, and is empty for one
- * that is), every `Resource.field` it names a member of the generated API,
+ * that is), the profiles it draws for (`look.profiles`, 2d and/or 3d), every `Resource.field` it names a member of the generated API,
  * og-taste naming every slug, and no text phrased as an imitation.
  */
 function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]): void {
@@ -472,6 +594,10 @@ function looks(roots: Roots, files: readonly PayloadFile[], problems: string[]):
     }
     if (look.preset !== `templates/looks/${s.slug}.ogt`) problems.push(`${id}: look.preset is ${look.preset}, expected templates/looks/${s.slug}.ogt`);
     if (!(SUPPORT as readonly string[]).includes(look.support)) problems.push(`${id}: look.support ${look.support} is none of ${SUPPORT.join(", ")}`);
+    const profiles = Array.isArray(look.profiles) ? look.profiles : [];
+    if (profiles.length === 0 || new Set(profiles).size !== profiles.length || !profiles.every((p) => (PROFILES as readonly string[]).includes(p))) {
+      problems.push(`${id}: look.profiles must name the profiles the style draws for, one or both of ${PROFILES.join(", ")} (create matches a premise only among the game's)`);
+    }
     const missing = look.missing ?? [];
     if (look.support === "full" && missing.length > 0) problems.push(`${id}: support full, yet it names missing primitives`);
     if (look.support !== "full" && !missing.some(text)) problems.push(`${id}: support ${look.support} must name what is missing (the primitive or the authored art)`);
@@ -571,7 +697,7 @@ export const GRAMMARS: readonly Grammar[] = [
     source: "crates/og-anim/src/graph.rs",
     region: [/pub fn from_document/, /\/\/\/ The slot of a parameter/],
     reads: readKeys,
-    names: { param: 1, clip: 1, blend1d: 2, blend2d: 3, child: 1, state: 2, entry: 1, transition: 2, when: 1, weight: 1 },
+    names: { param: 1, clip: 1, blend1d: 2, blend2d: 3, child: 1, state: 2, entry: 1, transition: 2, when: 1, weight: 1, sync: 1 },
   },
   { type: "navmesh", source: "crates/og-cook/src/cook/e6.rs", region: [/pub\(super\) fn cook_navmesh/, /og_nav::bake::bake\(/], reads: readKeys, home: "og-ai" },
   {
@@ -723,14 +849,70 @@ export function grammarDrift(skills: ReadonlyMap<string, string>, read: (path: s
   return problems;
 }
 
-function grammar(roots: Roots, files: readonly PayloadFile[], problems: string[]): void {
-  const repo = join(roots.pkg, "..", "..");
-  if (!existsSync(join(repo, "crates"))) return; // the published package: the parsers are not beside it
+/** Each skill's SKILL.md text, by skill name. */
+function skillTexts(files: readonly PayloadFile[]): Map<string, string> {
   const skills = new Map<string, string>();
   for (const f of files) {
     const m = /^game\/skills\/([^/]+)\/SKILL\.md$/.exec(f.path);
     if (m && isText(f.bytes)) skills.set(m[1]!, decoder.decode(f.bytes));
   }
+  return skills;
+}
+
+/**
+ * Every `.ogt` example a skill writes in a code block (```text or a bare
+ * fence, as a whole file or a fragment) holds to og-core's parser
+ * (crates/og-core/src/ogt.rs `parse`) line by line, so an author who copies
+ * it cooks: a `{` ends its key's line, a `}` stands alone on its own, the
+ * blocks close, and a file that opens with `type` has `version` and `---`
+ * next. A block with no brace and no `type` line is not checked (shell,
+ * prose). Strings and `#` comments are read as the parser reads them.
+ */
+export function ogtShape(skills: ReadonlyMap<string, string>): string[] {
+  const problems: string[] = [];
+  for (const [skill, md] of skills) {
+    for (const m of md.matchAll(/^( *)```([\w-]*)\n([\s\S]*?)^ *```/gm)) {
+      if (m[2] !== "text" && m[2] !== "") continue;
+      const indent = m[1]!.length;
+      const lines = m[3]!.split("\n").map((l) => l.slice(Math.min(indent, l.length - l.trimStart().length)));
+      const words = lines.map((l) => {
+        const out: string[] = [];
+        for (const t of l.matchAll(/"(?:[^"\\]|\\.)*"|\S+/g)) {
+          if (t[0].startsWith("#")) break;
+          out.push(t[0]);
+        }
+        return out;
+      });
+      const typed = words.find((w) => w.length > 0)?.[0] === "type";
+      if (!typed && !words.some((w) => w.includes("{") || w.includes("}"))) continue;
+      const first = md.slice(0, m.index).split("\n").length + 1;
+      const at = (i: number) => `skills/${skill}/SKILL.md:${first + i}`;
+      if (typed) {
+        const head = words.map((w, i) => [w, i] as const).filter(([w]) => w.length > 0).slice(0, 3);
+        if (head[1]?.[0][0] !== "version" || head[2]?.[0].join(" ") !== "---") problems.push(`${at(head[0]![1])}: an .ogt example opens with \`type\` but not \`version <n>\` and \`---\` after it; the parser refuses a file without its header`);
+      }
+      let depth = 0;
+      words.forEach((w, i) => {
+        const open = w.indexOf("{");
+        if (open >= 0 && open !== w.length - 1) problems.push(`${at(i)}: \`${lines[i]!.trim()}\` opens a block mid-line; the .ogt parser refuses it ('{' must end its line): put each line of the block on its own`);
+        if (w.includes("}") && w.length !== 1) problems.push(`${at(i)}: \`${lines[i]!.trim()}\` closes a block beside other words; the .ogt parser refuses it ('}' must be alone on its line)`);
+        if (open >= 0) depth++;
+        if (w.includes("}")) depth--;
+        if (depth < 0) {
+          problems.push(`${at(i)}: an unmatched '}'`);
+          depth = 0;
+        }
+      });
+      if (depth > 0) problems.push(`${at(lines.length - 1)}: an .ogt example leaves ${depth} block(s) open`);
+    }
+  }
+  return problems;
+}
+
+function grammar(roots: Roots, files: readonly PayloadFile[], problems: string[]): void {
+  const repo = join(roots.pkg, "..", "..");
+  if (!existsSync(join(repo, "crates"))) return; // the published package: the parsers are not beside it
+  const skills = skillTexts(files);
   problems.push(...grammarDrift(skills, (p) => (existsSync(join(repo, p)) ? readFileSync(join(repo, p), "utf8") : undefined)));
 }
 

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

@@ -1,6 +1,6 @@
 ---
 name: og-audio
-description: Sound on Origin Engine — one-shot voices for game events, the procedural sound presets og cook synthesises (coin, jump, hit, click and more), UI sounds, the four buses and their effects (filters, reverb send, compressor or limiter, ducking), music with stems, bar-aligned starts, crossfades and stingers on og.Music's clock, spatial sources with occlusion and distance dulling, voice priority and the cap, and proving it all headless with listen and og run --audio. Use when a game is silent, when adding any sound or music, or when the mix is muddy, clipping or wrong.
+description: Sound on Origin Engine — one-shot voices for game events, the procedural sound presets og cook synthesises (coin, jump, hit, click and more), UI sounds, the four buses and their effects (filters, reverb send, compressor or limiter, ducking), music with stems, bar-aligned starts, crossfades and stingers on og.Music's clock, spatial sources with occlusion, distance dulling, Doppler, cones and HRTF for headphones, voice priority and the cap, and proving it all headless with listen and og run --audio. Use when a game is silent, when adding any sound or music, or when the mix is muddy, clipping or wrong.
 ---
 
 Audio on Origin Engine is world state: an entity with `og.AudioSource`
@@ -34,9 +34,11 @@ given and taken, pickups, a door, a death, a win and a loss, every UI press.
 
 - One voice entity per sound, spawned in `start` with `playing: false`, and
   a `Voices` system that plays each requested one: systems set bits of a
-  game resource (`Sounds.sfx |= Sound.Jump`), Voices sets `playing` on the
-  matching voice (a voice already playing is stopped this tick and
-  restarted the next). Every archetype in `templates/archetypes` does
+  game resource (`Sounds.sfx |= Sound.Jump`), Voices sets `retrigger: true`
+  on the matching voice (it starts again from the top in that tick,
+  playing or not, and the engine clears it; archetypes written before
+  `retrigger` set `playing`, stopping a playing voice one tick and
+  starting it the next). Every archetype in `templates/archetypes` does
   this; copy a `Voices`.
 - Vary repeated sounds: `pitch` 0.92–1.08 from the world's `og.Rng` for
   footsteps, hits and coins, so a stream of them does not machine-gun.
@@ -58,14 +60,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
@@ -173,10 +175,34 @@ at 1.0 is a mix bug, not loudness.
   the listener is. It follows the listener's world transform, so put the
   og.AudioListener where the ears are (the camera, or the player); a zone
   on a child of a moving room moves with it.
+- Motion is heard: a spatial source or listener that moves shifts the
+  pitch (Doppler, from tick velocities down `og.Parent`, so a car on a
+  rig or a listener on a moving camera just works). `dopplerFactor` 1 is
+  physical; 0.3–0.6 on a racing game's engines keeps a fly-by readable;
+  0 on a source that must keep its pitch (a voice line, a musical
+  instrument in the world) or on the `og.AudioListener` to turn it off
+  everywhere. A warp or respawn (a jump faster than sound in one tick)
+  shifts nothing. `og.Audio.speedOfSound` (343.3) is the scale.
+- Directional sources: `coneInnerAngle`, `coneOuterAngle` (full angles,
+  degrees, about the entity's +Z, as three.js's `setDirectionalCone`)
+  and `coneOuterGain`: a loudspeaker or an NPC talking forward `90`,
+  `240`, `0.3`; a siren on a vehicle `120`, `300`, `0.5`. Rotate the
+  entity to aim it; the default 360/360 is omnidirectional.
+- Headphones: `og.AudioListener.panningModel: "hrtf"` places spatial
+  sources by interaural delay and head shadow (a spherical-head model),
+  clearer left and right than the stereo panner, without front/back or
+  height cues; offer it as a setting ("Headphones"), keep `equalpower`
+  for speakers (the default). Non-spatial sources keep their `pan`.
 - `og.Audio.maxVoices` (32) caps voices; past it the lowest `priority`,
   then the quietest, then the oldest is culled (`SOUND_CULLED`). Give the
   player's own sounds and the music a high priority (200+), ambient props a
-  low one.
+  low one. Ambient loops and music stems that should keep their place
+  when culled get `virtualize: true`: past the cap they go silent with
+  their playhead running and come back where they would be, not from the
+  top (`og.AudioPlayback.virtual` says which).
+- `og.Audio.resampler` is `sinc` (clean highs at any pitch); `linear` is
+  the older, cheaper mix, kept for a game that compares its exact output
+  (a WAV hash in a test). Unpitched 48 kHz sounds play the same either way.
 
 ## 7. Prove it
 

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

@@ -14,7 +14,7 @@ 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 UI skin, as
+warning, and every refusal named the line and the fix (a copied UI style, 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
@@ -53,8 +53,9 @@ a number and a sound (taste 98, feel 79).
    `get:<Resource>[.<field>]` or `get:<entity>[.<Component>[.<field>]]`
    (logs the value as game code sees it, og.Time whole and a light og.DayNight
    drives as it is drawn, and writes `get-<tick>.json`, then
-   `get-<tick>-2.json`, ... for more on one tick; a world dump lists
-   resources by name only, so `get:` is how to read one),
+   `get-<tick>-2.json`, ... for more on one tick; `get:Game:game.json`
+   names the file; a world dump lists resources by name only, so `get:`
+   is how to read one),
    `set:<entity>.<Component>.<field>=<value>` or
    `set:<Resource>.<field>=<value>` (`set:og.Camera.trauma=0.5`,
    `set:Game.coins=10`, `set:og.Stylise.ink=false`: a number, `true` or
@@ -98,7 +99,46 @@ each its argument form and one sentence in `GameDesc.commandHelp`
 (`{ spawn_wave: { usage: "<count>", doc: "Spawns a wave now." } }`)
 so `help` explains it (it lists `spawn_wave:<count>`: the name, then the
 usage). An entry naming no action is logged when the game
-starts.
+starts. A step's arguments are its colon-delimited fields after the
+action, never shell words: `0.5:records:12:34.5` hands the handler
+`args[0]` `"12"` and `args[1]` `"34.5"`, and its usage is written the same
+way, `usage: "<berries>:<seconds>"` (a space stays inside its field:
+`records:12 34.5` is one argument). A game may not take a core action's
+name; og-game §3 lists them, with `open_pause` beside the engine's `pause`.
+
+**File names.** Every output of one script has its own file. An unnamed
+output takes the action and the tick (`get-000030.json`), and a second on
+the same tick is suffixed quietly (`get-000030-2.json`). A named one that
+an earlier step of the script already wrote, at any time (a copy-pasted
+`0.5:get:Game:met.json`), is written as `met-2.json`, then `met-3.json`,
+never over the first, and logs a WARN naming both steps ("'met.json' was
+already written by the 0.5s get step, so this one is 'met-2.json'"). The
+WARN is in `run.warnings`, so a playtest that asserts a clean run
+(`t.equal(run.warnings.length, 0, ...)`) fails on the clash, and
+`run.json("met.json")` reads the first step's: give each named step its
+own file.
+
+**Values in the JSON.** A dump and a `get` answer write a vector as an
+array in lane order (`Vector3` `[x, y, z]`, `Quaternion` `[x, y, z, w]`,
+`Color` `[r, g, b]`), where the API's values are objects
+(`{ x, y, z }`); `set:` takes the lanes comma-separated, without spaces
+(`set:box.og.Transform.position=4,5,6`). Read a dump by index:
+
+```ts
+// 0.3:get:box.og.Transform:t.json writes {"kind":"get","target":"box.og.Transform","tick":18,"value":{"position":[1,2.5,-3],...}}
+const [x, y, z] = run.json<{ value: { position: [number, number, number] } }>("t.json").value.position;
+t.near(y, 2.5, 1e-4, "the box stands on the ledge");
+```
+
+An `f32` field is IEEE-754 single precision. Game code reads it as the
+f32's exact value promoted to a JavaScript number, so `2.7` written to an
+f32 reads back as `2.700000047683716`, and what game code sends carries
+that number as JSON (the facts, an og.platform payload, so
+`dump_platform`); `get` and the dumps print the f32's shortest form,
+`2.7`. Compare numbers with a tolerance in a test (`t.near(a, b, 1e-4,
+...)`), round only to display one (`toFixed(1)` on the label), and keep a
+value that must round-trip exactly (a payload a test compares with `===`)
+in an `f64` field.
 
 ## 2. Live sessions: the probe and hot reload
 
@@ -169,6 +209,15 @@ same store, for a relaunch (og-platform-sdk §4).
 - Determinism is checkable: two runs with the same seed and script give the
   same world hash in `dump_world`. When they do not, find the wall-clock
   read or the unseeded randomness before anything else.
+- A model built as code (og-model) is judged on numbers and one sheet,
+  not on a frame read by eye: `view:<entity>:front|back|side|top`,
+  `view:<entity>:orbit:<degrees>` and `turntable:<entity>:<n>` frame it
+  from fixed cameras, and `og compare <reference.png> <render.png>`
+  prints the silhouette IoU and the ΔE00 per mask region and writes the
+  reference beside the render as one sheet PNG (`--mask`, `--align`,
+  `--json`). Two runs give the same numbers and the same sheet bytes, so
+  quote them with the command. og-model §3 has the commands and how to
+  read them, og-model §4 the gate each pass must meet.
 - Report what ran and what did not. A build that compiled is not a game
   that plays.
 
@@ -196,7 +245,7 @@ every screen that matters.
 | taste | UI sounds | a press that changed the UI and started a voice on the ui bus within 8 ticks | every press | og-taste §6, og-audio §3 |
 | taste | Locale keys | `og cook`'s warnings | none | og-i18n §1 |
 | feel | Input latency | ticks from the tick an input lands to the first thing seen or heard to change (a named entity accelerating or changing clip, the UI, a sound, a tween, a floating text, shake, hit stop, a particle burst); a press answered on its release counts from the release | 0–1 ticks | og-feel §1 |
-| feel | Hit feedback | each damage moment (a fact named `hp`, `health`, `lives`… falling, or `hits`, `damage`, `kills`… rising): hit stop, shake, floating text and a sound within 8 ticks | three of the four | og-feel §3, §4, §7, og-audio §1 |
+| feel | Hit feedback | each damage moment (a fact named `hp`, `health`, `lives`… falling, or `hits`, `damage`, `kills`… rising): hit stop, shake, floating text and a sound within 8 ticks | three of the four, per moment (a moment with three owes no fourth: a bump that holds, shakes and sounds is not asked for a number) | og-feel §3, §4, §7, og-audio §1 |
 | feel | Idle frames | ticks after the first ten where nothing moves or animates, no UI moves, no sound starts or plays, no tween, text or particle runs | at most 10 % | og-feel §9, og-taste §5 |
 | 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 |
@@ -237,14 +286,24 @@ run it again after the fix: the report is the evidence.
 `og build .` bundles `src/` to `dist/game.js`, cooks, and copies the engine
 runtime and wasm next to it. `og build . --publish` produces the published
 form: the probe keeps only its player-facing members (hello, tick, state,
-pick, entity, input, capture) and the command channel is gone.
+pick, entity, input, capture) and the command channel is gone. A `2d`
+project publishes the 2D module, which has no 3D world
+(`RenderCapabilities.world3d` false): the build refuses scenes holding
+`Terrain`, `TerrainScatter`, `Water`, `WaterSurface` or `Fluid3D`, naming
+each by scene file and line (og-game §2).
 What ships is still checked by script, through what it keeps: real input
 on the published page and the probe's `tick`, `state` and `capture`. A
 playtest written in input steps (`key_down`, `type`, `touch_move_to` an
 id, `move_to_text`, `touch_start`) and `screenshot` steps runs there as it
 runs under `og test`, each frame compared with the same references; a
 game command (warp, give) has no channel there and is refused, so keep
-the steps a published check needs free of them. The engine runs this on
+the steps a published check needs free of them. The page shows the
+Player's Back over the canvas's top-left corner (12, 12, 40 by 40 CSS px
+on a desktop page; og-ui §5), which anchored HUD groups keep out of, so
+a playtest the page is held to gives its native run the same cover with
+`setup: "cover:12,12,40,40"` (`PlaytestDesc.setup`: command steps run
+once after `start`, before the first tick, never part of the page's
+script) and its frames lay out as the page's. The engine runs this on
 the published build of its own games (its `tests/web/published.ts`: the
 boot, the title, a press, a typed name and a frame against the metal
 reference, with a clean console).

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

@@ -218,16 +218,32 @@ export const Move = defineSystem("Move", { reads: [Velocity], writes: [og.Transf
   module variable or as numbers of code points.
   A `str` holds 1 to 4,096 bytes: a larger capacity typechecks and is
   refused when the game starts (`a string field holds 1 to 4096 bytes`).
-- A field holds one value: a component has no array or list field. A few
-  values are numbered fields (`p0`..`p7`, as og.CameraRail's rail points);
-  a list is an entity per element with its own component, looped over by
-  a query (a ring of skid marks, the laps of a race); a long record (a
-  lap's taped inputs) is text in `str(4096)` chunks, an entity each.
+- A field holds one value, or a fixed-capacity list of one number or
+  handle kind: `list(u32(), 8)`, `list(Asset(), 4)` (1 to 1,024 elements,
+  starting empty, never tunable). Reading it answers a frozen array, a
+  copy: `push`, `splice` and index writes throw, so write it whole
+  (`v.passes = [...v.passes, h]`, `v.passes = []`, `world.set(e, Chain,
+  { passes: [3, 5] })`). One over the capacity is refused with the fix
+  named (`declare the field list(u32(), 9) or larger`), never truncated.
+  Its column is the element's typed array with (capacity + 1) lanes per
+  entity, the count first, zeros past it, so `[]` and `[0]` are different
+  worlds. The probe reads it as a JSON array (`get:`, `dump_entity`),
+  `set:Chain.passes=[3,5]` (or `3,5`, nothing for `[]`) writes it whole, a
+  scene or a look gives it on one line (`passes 3 5`, the key alone for
+  `[]`), and snapshots and the hash carry it; a migrating restore keeps a
+  list that fits a new capacity and empties one that does not.
+  A list holds numbers only: a few vectors are numbered fields
+  (`p0`..`p7`, as og.CameraRail's rail points); a list of things with
+  fields of their own is an entity per element with its own component,
+  looped over by a query (a ring of skid marks, the laps of a race); a
+  long record (a lap's taped inputs) is text in `str(4096)` chunks, an
+  entity each.
 - A handle is a 64-bit number (an `og.load` answer, a texture, a sound,
   a geometry, a material, an entity): keep it in a field of its own kind,
-  `Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()` or
-  `Entity()` (each handle type of the API has its factory), in a
-  component or a resource. A `u32` field refuses one (`4294967298 is not
+  `Asset()`, `Texture()`, `Sound()`, `Font()`, `Style()`, `Look()`,
+  `Geometry()`, `Material()` or `Entity()` (each handle type of the API
+  has its factory, named as the type: a font is a `Font()`, never an
+  `Asset()` cast), in a component or a resource. A `u32` field refuses one (`4294967298 is not
   a u32`).
 - Per-entity calls (`world.get`, `world.set`) are for commands, setup and
   the few named entities a system touches (a camera, a listener, the

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

@@ -135,7 +135,7 @@ is what a sprite wants.
 | Take-off | (0.85, 1.15) | 0.1 s |
 | Hit taken | (1.2, 0.8) | 0.15 s, with a flash |
 | Pickup collected (on the pickup) | (1.4, 1.4) then shrink to 0 | 0.15 s |
-| UI button press (the skin's `press` does it for og.ui) | (0.92, 0.92) | 0.08 s, unscaled |
+| UI button press (the style's `press` does it for og.ui) | (0.92, 0.92) | 0.08 s, unscaled |
 
 Do not squash rigid things (crates, walls, the camera's target in a
 cutscene) or anything more than once per 6 ticks.
@@ -161,7 +161,7 @@ motion and hit stop (UI motion). `og.tween.squash` (§5) and
 | Constant motion, timers, scrolling, colour cycles | `linear` |
 | Most small motion when unsure | `quadOut` (the default) |
 
-Durations: 0.1–0.2 s for feedback, 0.12–0.3 s for UI (the skin's
+Durations: 0.1–0.2 s for feedback, 0.12–0.3 s for UI (the style's
 durations, og-taste §5), 0.2–0.35 s for swaps, 0.4–0.8 s for camera moves,
 reveals and screen transitions (up to 0.7 s). Longer feels sluggish unless
 it is a cutscene or a reward.
@@ -169,7 +169,10 @@ it is a cutscene or a reward.
 ## 7. Floating text
 
 `og.render.floatingText(world, { text, position, ... })` pops a text that
-rises, drifts and fades by itself (world state, deterministic).
+rises, drifts and fades by itself (world state, deterministic). A label
+that stays with a character (a name tag, a player's number) is not
+floating text: it is screen text where the og.Camera resource's
+`worldToScreen` puts the point, og-ui §3 (Text over a world point).
 
 - Damage and score numbers above the hit point, not on the HUD: the eye is
   already there. Pickups: what was gained (`+1`, `key`), short.
@@ -180,6 +183,11 @@ rises, drifts and fades by itself (world state, deterministic).
   biggest number on screen should be the most important.
 - Lifetime 0.6–1.0 s, rise 0.8–1.5 units, spread 0.2–0.4 so stacked hits do
   not overlap. At most 6–8 on screen: sum rapid hits into one number.
+- Not every impact wants a number. An impact is held by three of four
+  signals (hit stop §3, shake §4, floating text, a sound): `og polish`
+  counts them per damage moment and asks for the missing ones only of a
+  moment with fewer than three, so a party game's bump that holds, shakes
+  and sounds owes no floating text.
 
 ## 8. Camera: look-ahead, dead zones, zones, rails