@origingame/engine 0.4.0 → 0.5.0

package/knowledge/looks/catalogue.json

@@ -37,6 +37,10 @@
         "preset": "templates/looks/expressionist-painting.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.paintRadius",
           "Stylise.paintCanvas",
@@ -88,6 +92,10 @@
         "preset": "templates/looks/bold-comic-illustration.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.toon",
           "PostEffects.outline",
@@ -137,6 +145,10 @@
         "preset": "templates/looks/watercolor-wash.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.paintEdgeDarkening",
           "Stylise.paintBleed",
@@ -186,6 +198,9 @@
         "preset": "templates/looks/pixel-3d-hybrid.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "PostEffects.depthOfField",
           "PostEffects.ao",
@@ -237,6 +252,9 @@
         "preset": "templates/looks/faceted-low-poly.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.flatShading",
           "Fog",
@@ -276,8 +294,8 @@
         "Animation holds poses for 2 or more ticks (stepped, not interpolated)."
       ],
       "premise": {
-        "genre": "adventure, platformer, comedy",
-        "mood": "warm, odd, handmade",
+        "genre": "adventure, platformer, comedy, party games",
+        "mood": "warm, odd, playful, handmade",
         "era": "stop-motion film",
         "audience": "all ages, art-house"
       },
@@ -285,6 +303,9 @@
         "preset": "templates/looks/sculpted-clay.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.roughness",
           "StandardMaterialDesc.sheen",
@@ -336,6 +357,9 @@
         "preset": "templates/looks/8bit-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.palette",
@@ -386,6 +410,9 @@
         "preset": "templates/looks/voxel-worlds.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.flatShading",
           "PostEffects.ao",
@@ -434,6 +461,9 @@
         "preset": "templates/looks/illuminated-manuscript.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.paintCanvas",
           "Stylise.ink",
@@ -485,6 +515,9 @@
         "preset": "templates/looks/rubber-hose-animation.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "PostEffects.filmGrain",
           "PostEffects.vignette",
@@ -536,6 +569,9 @@
         "preset": "templates/looks/pencil-hatching.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "Stylise.hatching",
           "Stylise.hatchingLevels",
@@ -585,6 +621,9 @@
         "preset": "templates/looks/gothic-contour.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Fog",
           "PostEffects.glow",
@@ -637,6 +676,10 @@
         "preset": "templates/looks/lush-painted-worlds.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.paintRadius",
           "Stylise.paintCanvas",
@@ -688,6 +731,10 @@
         "preset": "templates/looks/decorative-storybook.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.ink",
           "Stylise.paintCanvas",
@@ -738,6 +785,9 @@
         "preset": "templates/looks/classical-painting-collage.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "sprites with transforms",
           "PostEffects.vignette",
@@ -788,6 +838,9 @@
         "preset": "templates/looks/detailed-doodle.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.ink",
           "unlit materials",
@@ -838,6 +891,10 @@
         "preset": "templates/looks/black-figure-pottery.ogt",
         "presetReady": true,
         "support": "content",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.palette",
           "Stylise.posterize",
@@ -888,6 +945,9 @@
         "preset": "templates/looks/heavy-ink-shadows.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "Stylise.posterize",
           "Stylise.hatching",
@@ -937,6 +997,9 @@
         "preset": "templates/looks/monochrome-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.palette",
@@ -986,6 +1049,9 @@
         "preset": "templates/looks/16bit-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.pixelSnap",
@@ -1035,6 +1101,9 @@
         "preset": "templates/looks/detailed-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.pixelSnap",
@@ -1085,6 +1154,9 @@
         "preset": "templates/looks/luminous-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Lighting2D",
@@ -1135,6 +1207,9 @@
         "preset": "templates/looks/topdown-tile-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "tilemap layers",
           "Sprite.sortY",
@@ -1184,6 +1259,9 @@
         "preset": "templates/looks/low-resolution-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.vertexSnap",
@@ -1235,6 +1313,9 @@
         "preset": "templates/looks/coarse-pixel.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d"
+        ],
         "primitives": [
           "Stylise.pixelHeight",
           "Stylise.palette",
@@ -1283,6 +1364,9 @@
         "preset": "templates/looks/anime-cel-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.toon",
           "StandardMaterialDesc.gradientMap",
@@ -1334,6 +1418,9 @@
         "preset": "templates/looks/inked-comic-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "PostEffects.outline",
           "StandardMaterialDesc.toon",
@@ -1385,6 +1472,9 @@
         "preset": "templates/looks/paper-craft.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterialDesc.flatShading",
           "MaterialStyle.flatShading",
@@ -1435,6 +1525,9 @@
         "preset": "templates/looks/miniature-diorama.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "PostEffects.depthOfField",
           "PostEffects.ao",
@@ -1485,6 +1578,9 @@
         "preset": "templates/looks/painterly-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "Stylise.paintRadius",
           "Stylise.paintAnisotropy",
@@ -1535,6 +1631,9 @@
         "preset": "templates/looks/cinematic-realism.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "StandardMaterial (PBR)",
           "Environment",
@@ -1587,6 +1686,9 @@
         "preset": "templates/looks/muted-cinematic-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "PostEffects.godRays",
           "Fog",
@@ -1638,6 +1740,10 @@
         "preset": "templates/looks/layered-silhouette.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "Stylise.depthBands",
           "Fog",
@@ -1687,6 +1793,10 @@
         "preset": "templates/looks/minimal-geometric.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "unlit materials",
           "boxGeometry/sphereGeometry/planeGeometry",
@@ -1736,6 +1846,10 @@
         "preset": "templates/looks/neon-vector.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "RenderSettings.bloom",
           "emissive unlit materials",
@@ -1787,6 +1901,9 @@
         "preset": "templates/looks/monochrome-dither-3d.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "3d"
+        ],
         "primitives": [
           "Stylise.posterize",
           "Stylise.palette",
@@ -1836,6 +1953,10 @@
         "preset": "templates/looks/luminous-layered-painting.ogt",
         "presetReady": true,
         "support": "full",
+        "profiles": [
+          "2d",
+          "3d"
+        ],
         "primitives": [
           "sprite layers",
           "Fog",

package/knowledge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origingame/engine-knowledge",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Origin Engine knowledge for agents: the API wiki generated from api.ogt, the eleven og-* skills, the guides (three-to-og), the style catalogue and the project scaffold description, laid out for the OriginGame platform's knowledge packs. Not published on its own: @origingame/engine carries it as knowledge/ (docs/release.md §2).",
   "license": "MIT",
   "private": true,

package/knowledge/scaffold/origin-engine.json

@@ -4,13 +4,13 @@
   "substrate": "origin-engine-ts",
   "engine": {
     "package": "@origingame/engine",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "repository": "origingame/origin-engine"
   },
   "template": {
     "source": "templates/game",
     "create": "@origingame/create-game",
-    "version": "0.4.0"
+    "version": "0.5.0"
   },
   "probe": {
     "protocol": 5,

package/knowledge/scaffold/template/package.json

@@ -13,6 +13,6 @@
     "test": "og test ."
   },
   "dependencies": {
-    "@origingame/engine": "0.4.0"
+    "@origingame/engine": "0.5.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.4.0"
+engine "0.5.0"
 entry "src/main.ts"
 # 2d (orthographic camera, sprites, 2D physics) or 3d.
 profile "3d"

package/knowledge/scripts/validate.ts

@@ -98,6 +98,7 @@ export function validate(roots: Roots = defaultRoots()): string[] {
   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;
 }
@@ -517,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>;
@@ -526,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"];
@@ -537,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 {
@@ -591,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)`);
@@ -690,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" },
   {
@@ -842,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.
@@ -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