@origingame/engine 0.0.0-stage → 0.1.0

package/knowledge/scaffold/template/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/knowledge/scaffold/template/assets/looks/origin-game.ogt

@@ -0,0 +1,12 @@
+type look
+version 1
+---
+# The game's look (og-taste §12): the frame's art direction as data, named
+# by GameDesc.look in src/main.ts and applied before start runs. It starts
+# from the catalogue's faceted-low-poly preset (flat facets on every lit
+# material, a soft vignette, AgX tone mapping); a block written below wins
+# over the preset field by field, and `extends` takes any catalogue slug
+# (packages/knowledge/looks/catalogue.json). `npm create @origingame/game`
+# writes the game's own look from its premise, or from --look <slug>.
+name "Origin Game"
+extends "faceted-low-poly"

package/knowledge/scaffold/template/assets/nav/yard.ogt

@@ -0,0 +1,27 @@
+type navmesh
+version 1
+---
+# The yard's navmesh, baked by `og cook` (og.nav.load("nav/yard.ogt")): the
+# ground and the wall `start` builds in src/main.ts, voxelised for an agent
+# 0.4 m wide and 1.8 m tall. A `scene` or `model` entry bakes glTF geometry
+# instead of boxes.
+agent {
+  radius 0.4
+  height 1.8
+  climb 0.4
+  slope 45
+}
+cellSize 0.25
+tileSize 32
+bounds {
+  min -12 -1 -12
+  max 12 3 12
+}
+box {
+  center 0 -0.1 0
+  size 30 0.2 30
+}
+box {
+  center -3 1 -2
+  size 0.6 2 6
+}

package/knowledge/scaffold/template/assets/scenes/main.ogt

@@ -0,0 +1,34 @@
+type scene
+version 1
+---
+name "Main"
+entity "ground" {
+  Transform {
+    position 0 0 0
+    quaternion 0 0 0 1
+    scale 1 1 1
+  }
+}
+entity "dropship" {
+  model "models/dropship.glb"
+  Transform {
+    position 0 1.5 0
+    quaternion 0 0 0 1
+    scale 1 1 1
+  }
+}
+entity "trickster" {
+  model "models/walker.glb"
+  Transform {
+    position 2 0 0
+    quaternion 0 0.7071068 0 0.7071068
+    scale 1 1 1
+  }
+  entity "marker" {
+    Transform {
+      position 0 2.2 0
+      quaternion 0 0 0 1
+      scale 0.25 0.25 0.25
+    }
+  }
+}

package/knowledge/scaffold/template/assets/strings/en.ogt

@@ -0,0 +1,14 @@
+type strings
+version 1
+---
+# The template's strings (og.i18n, og-i18n §1): every word the menu shows
+# is a key here, never a literal in a system. This is the base table, in
+# the game's source language; a locale is its own file beside it
+# (`zh-CN.ogt`, with the same keys and its `fonts` line), loaded in `start`.
+locale "en"
+base true
+string "menu.title" "Origin Engine"
+string "menu.prompt" "Press Start to begin"
+string "menu.spinning" "Spinning  {speed} rad/s"
+string "menu.start" "Start"
+string "menu.started" "Started"

package/knowledge/scaffold/template/assets/textures/stone_n.png.ogt

@@ -0,0 +1,7 @@
+type import
+version 1
+---
+# A tangent-space normal map: UASTC, linear (colour textures default to ETC1S, sRGB).
+texture {
+  kind normal
+}

package/knowledge/scaffold/template/gitattributes

@@ -0,0 +1,22 @@
+# Media to Git LFS, as the platform's other scaffolds route them; text stays
+# diffable (.ogt scenes and settings are line-based text by design).
+*.glb filter=lfs diff=lfs merge=lfs -text
+*.gltf filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.ktx2 filter=lfs diff=lfs merge=lfs -text
+*.hdr filter=lfs diff=lfs merge=lfs -text
+*.exr filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+*.ogt text eol=lf
+*.ts text eol=lf

package/knowledge/scaffold/template/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "origin-game",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "og dev .",
+    "start": "og run .",
+    "build": "og build .",
+    "publish-build": "og build . --publish",
+    "cook": "og cook .",
+    "check": "og check .",
+    "test": "og test ."
+  },
+  "dependencies": {
+    "@origingame/engine": "0.1.0"
+  }
+}

package/knowledge/scaffold/template/project.ogt

@@ -0,0 +1,25 @@
+type project
+version 1
+---
+# The project manifest (docs/design.md §2.5): `og run`, `og build`, `og cook`,
+# `og dev` and `og test` read it. `npm create @origingame/game` fills in the
+# name and id.
+name "Origin Game"
+id "origin-game"
+# The engine this game is written against (design §9: upgrades are explicit).
+engine "0.1.0"
+entry "src/main.ts"
+# 2d (orthographic camera, sprites, 2D physics) or 3d.
+profile "3d"
+tick 60
+seed 1
+scenes {
+  main "scenes/main.ogt"
+}
+scene main
+publish {
+  # `og build --publish` keeps only the player-facing probe members
+  # (hello, tick, state, pick, entity, input, capture).
+  probe player
+  out "dist"
+}

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

@@ -0,0 +1,246 @@
+// The game entry: its default export is og.game(...). `og run .` runs it
+// headless with the probe; `og dev .` reloads it on every save; `og build .`
+// bundles it for the play page.
+//
+// This is the hello of docs/design.md §3.2 (Health, Velocity, Move) grown
+// into a scene: scenes/main.ogt (cooked from assets/scenes/main.ogt) spawns
+// the ground, the dropship and the trickster before the first tick; `start`
+// gives the ground its mesh and collider, drops a crate above it, puts the
+// camera, the UI font and the string table (assets/strings/en.ogt) in
+// place. The Start button of the menu panel (or S or Enter) starts the
+// trickster spinning and lets the crate fall.
+//
+// A guard walks the yard: a state machine in assets/ai/guard.ogt (og.ai)
+// patrols its post on the navmesh baked from assets/nav/yard.ogt (og.nav),
+// sees the trickster only inside its view cone and not through the wall,
+// raises the alarm and chases it, then searches and goes back.
+//
+// The frame's look is data: GameDesc.look names a file under assets/looks/
+// that extends a preset of the style catalogue, applied before start runs.
+
+import { og, defineComponent, defineResource, defineSystem, bool, f32, Vector3, SHAPE_BOX } from "@origingame/engine";
+import type { World } from "@origingame/engine";
+
+export const Health = defineComponent("Health", {
+  hp: f32(100, { min: 0, max: 1000, tunable: true, label: "Health" }),
+  max: f32(100),
+});
+
+export const Velocity = defineComponent("Velocity", { v: Vector3() });
+
+/** Turns an entity about +Y; 0 until the player starts. */
+export const Spin = defineComponent("Spin", {
+  speed: f32(0, { min: -10, max: 10, step: 0.1, unit: "rad", tunable: true, label: "Spin speed" }),
+  target: f32(1.5, { min: -10, max: 10, tunable: true, label: "Spin when started" }),
+});
+
+/** Whether the player has pressed Start. */
+export const Run = defineResource("Run", { started: bool(), chimed: bool() });
+
+/** The guard's alarms, raised by its machine's `alarm` command. */
+export const Alarm = defineComponent("Alarm", { raised: f32(0) });
+
+export const Move = defineSystem("Move", { reads: [Velocity], writes: [og.Transform] }, (q, time) => {
+  for (const a of q.archetypes()) {
+    const p = a.column(og.Transform).position;
+    const v = a.column(Velocity).v;
+    for (let i = 0; i < a.count; i++) {
+      p[i * 3] += v[i * 3] * time.dt;
+      p[i * 3 + 1] += v[i * 3 + 1] * time.dt;
+      p[i * 3 + 2] += v[i * 3 + 2] * time.dt;
+    }
+  }
+});
+
+/**
+ * The menu panel: the title, the trickster's state and the Start button.
+ * A click on Start (or S or Enter) starts the run; the button then reads
+ * "Started" and stays inert.
+ */
+export const Menu = defineSystem("Menu", { reads: [Spin, og.Input], writes: [Run] }, (q, _time, world) => {
+  const run = world.resource(Run);
+  const input = world.resource(og.Input);
+  if (!run.ok || !input.ok) return;
+  let speed = 0;
+  for (const a of q.archetypes()) if (a.count > 0) speed = a.column(Spin).speed[0]!;
+  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" } });
+    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;
+  }));
+});
+
+/** Once started, every Spin turns at its target speed. */
+export const StartSpin = defineSystem("StartSpin", { reads: [Run], writes: [Spin], after: ["Menu"] }, (q, _time, world) => {
+  const run = world.resource(Run);
+  if (!run.ok || !run.value.started) return;
+  for (const a of q.archetypes()) {
+    const s = a.column(Spin);
+    for (let k = 0; k < a.count; k++) if (s.speed[k] === 0) s.speed[k] = s.target[k]!;
+  }
+});
+
+/** Once started, held bodies (gravityScale 0) fall. */
+export const Drop = defineSystem("Drop", { reads: [Run], writes: [og.RigidBody], after: ["Menu"] }, (q, _time, world) => {
+  const run = world.resource(Run);
+  if (!run.ok || !run.value.started) return;
+  for (const a of q.archetypes()) {
+    const g = a.column(og.RigidBody).gravityScale;
+    for (let k = 0; k < a.count; k++) if (g[k] === 0) g[k] = 1;
+  }
+});
+
+/** Once started, the crate's blip plays once (an AudioSource inserted held, released here). */
+export const Chime = defineSystem("Chime", { writes: [Run, og.AudioSource], after: ["Menu"] }, (q, _time, world) => {
+  const run = world.resource(Run);
+  if (!run.ok || !run.value.started || run.value.chimed) return;
+  run.value.chimed = true;
+  for (const a of q.archetypes()) a.column(og.AudioSource).playing.fill(1);
+});
+
+/** Rotates by Spin.speed about +Y: q' = q * (axis-angle about Y). */
+export const Rotate = defineSystem("Rotate", { reads: [Spin], writes: [og.Transform], after: ["StartSpin"] }, (q, time) => {
+  for (const a of q.archetypes()) {
+    const r = a.column(og.Transform).quaternion;
+    const s = a.column(Spin).speed;
+    for (let i = 0; i < a.count; i++) {
+      const half = (s[i] * time.dt) / 2;
+      // Small-angle rotation, renormalised: deterministic arithmetic only.
+      const sy = half - (half * half * half) / 6;
+      const cw = 1 - (half * half) / 2;
+      const x = r[i * 4], y = r[i * 4 + 1], z = r[i * 4 + 2], w = r[i * 4 + 3];
+      const nx = x * cw - z * sy, ny = y * cw + w * sy, nz = z * cw + x * sy, nw = w * cw - y * sy;
+      const n = Math.sqrt(nx * nx + ny * ny + nz * nz + nw * nw);
+      r[i * 4] = nx / n;
+      r[i * 4 + 1] = ny / n;
+      r[i * 4 + 2] = nz / n;
+      r[i * 4 + 3] = nw / n;
+    }
+  }
+});
+
+function spawnWave(world: World, count: number): void {
+  const ship = og.load.gltf(world, "models/dropship.glb");
+  if (!ship.ok) throw new Error(ship.reason);
+  for (let i = 0; i < count; i++) {
+    const e = world.instantiate(ship.value, { name: `wave-${world.tick}-${i}`, position: { x: -4 + i * 1.5, y: 4, z: -3 } });
+    if (!e.ok) throw new Error(e.reason);
+    world.insert(e.value, Velocity, { v: { x: 0, y: -0.5, z: 0 } });
+  }
+}
+
+function must<T>(r: { ok: true; value: T } | { ok: false; reason: string }): T {
+  if (!r.ok) throw new Error(r.reason);
+  return r.value;
+}
+
+export default og.game({
+  tick: 60,
+  seed: 1,
+  scenes: { main: "scenes/main.ogt" },
+  // The art direction as data (og-taste §12): applied after the scene
+  // spawns and before start, which may still change any of it.
+  look: "looks/origin-game.ogt",
+  resources: [Run],
+  systems: [Move, Menu, StartSpin, Drop, Chime, Rotate],
+  // MSAA keeps world-space sprites and text sharp; TAA would blur them across
+  // frames. The UI draws over the finished frame either way.
+  render: { antialias: "msaa4" },
+  start(world) {
+    // The camera looks down -Z at the scene from in front.
+    const camera = must(world.resource(og.Camera));
+    camera.position = { x: 0.4, y: 1.8, z: 8 };
+    camera.quaternion = { x: 0, y: 0, z: 0, w: 1 };
+    must(world.resource(og.RenderSettings)).sky = true;
+
+    // The ground: a 30 m slab whose top is y = 0, drawn and collided with.
+    const ground = world.find("ground");
+    if (ground !== null) {
+      const slab = must(og.render.boxGeometry(world, { width: 30, height: 0.2, depth: 30 }));
+      const stone = must(og.render.standardMaterial(world, { color: { r: 0.18, g: 0.2, b: 0.24 }, roughness: 0.95 }));
+      world.set(ground, og.Transform, { position: { x: 0, y: -0.1, z: 0 } });
+      world.insert(ground, og.Mesh, { geometry: slab, material: stone, receiveShadow: true });
+      world.insert(ground, og.Collider, { shape: SHAPE_BOX, size: { x: 30, y: 0.2, z: 30 } });
+    }
+
+    // The crate: a dynamic body held in the air (gravityScale 0) until Start.
+    const cube = must(og.render.boxGeometry(world, {}));
+    const amber = must(og.render.standardMaterial(world, { color: { r: 0.9, g: 0.55, b: 0.08 }, roughness: 0.6 }));
+    const crate = must(world.spawn({ name: "crate", position: { x: -2.4, y: 4, z: 0.5 } }));
+    world.insert(crate, og.Mesh, { geometry: cube, material: amber, castShadow: true, receiveShadow: true });
+    world.insert(crate, og.RigidBody, { gravityScale: 0 });
+    world.insert(crate, og.Collider, { shape: SHAPE_BOX });
+    const blip = og.load.sound(world, "audio/blip.wav");
+    if (blip.ok) world.insert(crate, og.AudioSource, { sound: blip.value, playing: false, spatial: true });
+
+    const trickster = world.find("trickster");
+    if (trickster !== null) {
+      world.insert(trickster, Spin);
+      world.insert(trickster, Health);
+      // What the guard looks for: team 1, looked at 1 m above its feet.
+      world.insert(trickster, og.Perceivable, { team: 1, eyeHeight: 1 });
+    }
+
+    // The wall the navmesh was baked around (assets/nav/yard.ogt): drawn, and solid to the guard's sight.
+    const wall = must(world.spawn({ name: "wall", position: { x: -3, y: 1, z: -2 } }));
+    const slabGeo = must(og.render.boxGeometry(world, { width: 0.6, height: 2, depth: 6 }));
+    const plaster = must(og.render.standardMaterial(world, { color: { r: 0.55, g: 0.52, b: 0.48 }, roughness: 0.9 }));
+    world.insert(wall, og.Mesh, { geometry: slabGeo, material: plaster, castShadow: true, receiveShadow: true });
+    world.insert(wall, og.Collider, { shape: SHAPE_BOX, size: { x: 0.6, y: 2, z: 6 } });
+
+    // The guard: the walker model, moved by og.nav on the baked navmesh and run by og.ai's machine.
+    const yard = must(og.nav.load(world, "nav/yard.ogt"));
+    const mind = must(og.ai.load(world, "ai/guard.ogt"));
+    const walker = must(og.load.gltf(world, "models/walker.glb"));
+    const guard = must(world.instantiate(walker, { name: "guard", position: { x: -6, y: 0, z: -3 } }));
+    // Facing east (+X), towards the wall: its view cone is 120° around the way it faces until it moves.
+    world.set(guard, og.Transform, { quaternion: { x: 0, y: Math.SQRT1_2, z: 0, w: Math.SQRT1_2 } });
+    world.insert(guard, og.NavAgent, { nav: yard.mesh, speed: 1.5, acceleration: 12, radius: 0.4, faceMovement: true, turnSpeed: 8 });
+    world.insert(guard, og.AiAgent, { behaviour: mind.behaviour });
+    world.insert(guard, og.Perception, { sight: 9, fov: 120, eyeHeight: 1.6, team: 2 });
+    world.insert(guard, Alarm);
+    // Every string the menu shows (og-i18n §1): load each locale's table here.
+    must(og.i18n.load(world, "strings/en.ogt"));
+    const font = og.load.font(world, "fonts/NotoSansSC-Regular-subset.ttf");
+    // A press answers with a sound as well as its look (og-taste §6): the `click` preset, synthesised by og cook.
+    const click = og.load.sound(world, "audio/click.ogt");
+    og.ui.configure(world, { ...(font.ok ? { font: font.value } : {}), ...(click.ok ? { sounds: { press: click.value } } : {}) });
+  },
+  commands: {
+    spawn_wave: (world, args) => spawnWave(world, Number(args[0] ?? 3)),
+    // The guard's machine raises it on entering `alert`; og.ai passes the guard's handle first.
+    alarm: (world, args) => {
+      const guard = Number(args[0]) as never;
+      const a = must(world.get(guard, Alarm));
+      must(world.set(guard, Alarm, { raised: a.raised + 1 }) as never);
+    },
+    /** `lure:<x>:<z>`: moves the trickster on the ground. */
+    lure: (world, args) => {
+      const t = world.find("trickster");
+      if (t === null) throw new Error("no trickster");
+      must(world.set(t, og.Transform, { position: { x: Number(args[0]), y: 0, z: Number(args[1]) } }) as never);
+    },
+  },
+  commandHelp: {
+    spawn_wave: { usage: "[count]", doc: "Drop that many dropships (3 by default)." },
+    alarm: { usage: "<guard>", doc: "The guard's state machine raises it on entering alert; og.ai passes the guard's handle." },
+    lure: { usage: "<x>:<z>", doc: "Move the trickster on the ground." },
+  },
+  facts: (world) => {
+    const run = world.resource(Run);
+    const trickster = world.find("trickster");
+    const spin = trickster === null ? null : world.get(trickster, Spin);
+    const crate = world.find("crate");
+    const at = crate === null ? null : world.get(crate, og.Transform);
+    const guard = world.find("guard");
+    const mind = guard === null ? null : (og.ai.describe(world, guard) as { state: string } | null);
+    return {
+      started: run.ok && run.value.started,
+      guard: mind?.state ?? null,
+      spin: spin?.ok ? spin.value.speed : null,
+      crateY: at?.ok ? at.value.position.y : null,
+    };
+  },
+});

package/knowledge/scaffold/template/tests/guard.og.ts

@@ -0,0 +1,67 @@
+// The guard (assets/ai/guard.ogt, a state machine on og.ai; the navmesh
+// cooked from assets/nav/yard.ogt, walked by og.nav). Facing east at its
+// first post, it does not see the trickster behind the wall (in range, in
+// its cone) nor behind it (in range, in the open); in front of it, it does,
+// raises the alarm once and chases; when the trickster slips behind the wall
+// it searches where it last saw it and returns to its patrol 3 s later.
+import { playtest } from "@origingame/engine/playtest";
+
+interface AiDump {
+  behaviour: string;
+  kind: string;
+  state: string;
+  sees: boolean;
+}
+interface EntityDump {
+  components: Record<string, Record<string, unknown>>;
+}
+
+const at = (run: { json<T>(f: string): T }, f: string) => run.json<EntityDump>(f).components["og.Transform"]!["position"] as number[];
+
+export default playtest({
+  name: "the guard patrols, sees inside its cone and not through the wall, chases, searches and returns",
+  commands: [
+    "0.3:lure:0:-3",
+    "0.4:dump_ai:guard:walled.json",
+    "0.4:dump_entity:guard:g0.json",
+    "0.5:lure:-6:-7",
+    "0.7:dump_ai:guard:behind.json",
+    "1.0:lure:-4:-1",
+    "1.1:dump_ai:guard:front.json",
+    "2.2:dump_entity:guard:chasing.json",
+    "2.2:dump_ai:guard:chase.json",
+    "2.3:lure:-1:-4",
+    "2.6:dump_ai:guard:lost.json",
+    "6.0:dump_ai:guard:back.json",
+    "6.0:dump_entity:guard:end.json",
+    "6.1:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const walled = run.json<AiDump>("walled.json");
+    t.equal(walled.behaviour, "guard", "the guard runs assets/ai/guard.ogt");
+    t.equal(walled.kind, "machine", "a state machine");
+    t.equal(walled.state, "patrol", "it patrols");
+    t.equal(walled.sees, false, "the wall hides the trickster 6 m ahead, inside its cone and its 9 m sight");
+    const g0 = at(run, "g0.json");
+    t.ok(Math.abs(g0[1]!) < 0.2, `it stands on the navmesh's surface (y ${g0[1]!.toFixed(3)})`);
+    const behind = run.json<AiDump>("behind.json");
+    t.equal(behind.sees, false, "4 m behind it, in the open, the trickster is outside its 120° cone");
+    t.equal(behind.state, "patrol", "so it keeps patrolling");
+
+    const front = run.json<AiDump>("front.json");
+    t.equal(front.sees, true, "in front of it the trickster is seen");
+    t.equal(front.state, "alert", "and the guard is alert");
+    const chase = run.json<AiDump>("chase.json");
+    t.equal(chase.state, "alert", "still chasing a second later");
+    const c = at(run, "chasing.json");
+    const d = Math.hypot(c[0]! + 4, c[2]! + 1);
+    t.ok(d < 2.0, `it closed in on the trickster (${d.toFixed(2)} m)`);
+
+    const lost = run.json<AiDump>("lost.json");
+    t.equal(lost.sees, false, "behind the wall the trickster is hidden");
+    t.equal(lost.state, "search", "so the guard searches");
+    t.equal(run.json<AiDump>("back.json").state, "patrol", "three seconds later it is back on patrol");
+    t.equal(run.json<EntityDump>("end.json").components["Alarm"]!["raised"], 1, "the alarm was raised once, on entering alert");
+  },
+});

package/knowledge/scaffold/template/tests/smoke.og.ts

@@ -0,0 +1,43 @@
+// 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.
+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)})`);
+  },
+});

package/knowledge/scaffold/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": [],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}