@origingame/engine 0.3.0 → 0.4.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,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)) {

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

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
@@ -169,6 +169,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.
 
@@ -237,14 +246,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,11 +218,26 @@ 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

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.