@origingame/create-game 0.2.0 → 0.4.0

package/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/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/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/template/package.json

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

package/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.4.0"
 entry "src/main.ts"
 # 2d (orthographic camera, sprites, 2D physics) or 3d.
 profile "3d"

package/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/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/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/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/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/template-2d/LICENSES.md

@@ -9,6 +9,7 @@ its `tools/make-assets.py`), and the rest is written by hand.
 | `assets/sprites/courier.png`, `assets/sprites/coin.png` and their `.ogt` | CC0 1.0 | self-made: the runner archetype's courier and coin |
 | `assets/tiles/city.png` | CC0 1.0 | self-made: the runner archetype's city tileset |
 | `assets/tiles/city.ogt`, `assets/maps/level.ogt` | CC0 1.0 | self-made, written by hand |
+| `assets/rigs/keeper.png`, `assets/rigs/keeper.ogt` | CC0 1.0 | self-made: the lamp keeper's parts drawn with ImageMagick primitives, its rig written by hand |
 | `assets/audio/jump.wav`, `assets/audio/coin.wav` | CC0 1.0 | self-made: the runner archetype's synthesised tones |
 | `assets/fonts/ui.ttf` | SIL Open Font License 1.1 (`assets/fonts/OFL.txt`) | Noto Sans SC Regular, subset to Latin-1 by the runner archetype from the project template's `assets/fonts/NotoSansSC-Regular-subset.ttf` |
 | `assets/looks/*.ogt`, `assets/strings/*.ogt`, every other `.ogt` | CC0 1.0 | self-made, written by hand |

package/template-2d/README.md

@@ -5,11 +5,14 @@ a premise that says 2D, platformer, side-scroller, metroidvania or pixel
 art): the smallest whole 2D Origin Engine project. A courier runs and jumps
 the rooftops of one level, takes coins, jumps up through one-way ledges and
 lands on them, loses a life in the pit and clears the level at the far
-wall; Escape (or the HUD's Pause) opens the pause menu.
+wall; Escape (or the HUD's Pause) opens the pause menu. Beside the spawn a
+lamp keeper, a 2D skeletal rig, breathes on a ramp with its feet planted
+and walks along it when sent (`keeper:<x>`): it turns over a few ticks,
+steps along the plank, lets both feet land and turns back.
 
 ```sh
 og run .     # headless with the probe; og dev . reloads on save
-og test .    # tests/smoke.og.ts
+og test .    # tests/smoke.og.ts, tests/keeper.og.ts
 og build .   # the play page
 ```
 
@@ -20,6 +23,7 @@ og build .   # the play page
 | The project in the 2D profile: an orthographic camera, sprites, 2D physics | `project.ogt`, `start` in `src/main.ts` | og-game §2, §8 |
 | A hand-written tilemap over a tileset: a parallax skyline, roofs that collide, ledges on their own collider layer (`colliderLayers 2`) that the controller makes one-way | `assets/maps/level.ogt`, `assets/tiles/city.ogt` | og-game §8 (the grammar) |
 | A flipbook sheet, its clips numbered in file order and checked against the code | `assets/sprites/courier.ogt`, `CLIP`, `checkClips` | og-game §8 |
+| A 2D skeletal rig: bones, slots, region attachments, a weighted-mesh cape the idle clip deforms, two-bone IK legs planted on a slope (og.IkTarget2D) and stepping along it under a walk clip with Bézier keys (turning over 12 ticks, no foot faster than the gait's swing, settling before idle), its clip events (breaths, footfalls) read as og.Skeleton2DEvent, its lantern an og.Light2D under og.Lighting2D (layers 1 and 2) | `assets/rigs/keeper.ogt`, `spawnKeeper`, `Walk`, `Plant`, `tests/keeper.og.ts` | og-game §8 |
 | og.PlatformerController: run, jump (held for the full height), coyote time, the jump buffer, one-way ledges, Down to drop | `Control`, the hero in `start` | og-game §13; og-feel §12 |
 | The map's objects: the spawn, the coins, the goal | `start`, `Pickups` | og-game §8 |
 | Input on the press's tick: keys, a pad, the HUD's touch controls on a phone | `Control`, `Hud` | og-feel §1; og-ui §5 |