@origingame/create-game 0.1.1 → 0.3.0

package/template-2d/src/main.ts

@@ -0,0 +1,460 @@
+// The 2D starter's 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.
+//
+// A courier runs and jumps the rooftops of one level: a hand-written
+// tilemap (assets/maps/level.ogt) whose roofs collide and whose ledges are
+// one-way on their own collider layer, an og.PlatformerController moved by
+// the arrows, WASD, Space or a pad, the courier's flipbook clips chosen by
+// what the controller did, coins to take, a pit that costs a life, a goal
+// at the far end, a camera that follows, and the UI kit's platformer HUD.
+// Everything the starter shows is in og-game §8 (sprites, flipbooks,
+// tilemaps), §13 (the controller) and og-feel §12 (its tunables).
+//
+// Beside the spawn a lamp keeper stands on a ramp: a 2D skeletal rig
+// (assets/rigs/keeper.ogt, og.Skeleton2D) whose cape is a weighted mesh the
+// idle clip deforms, whose feet two-bone IK planted on the slope
+// (og.IkTarget2D, the Plant system), and whose lantern lights the sprite
+// layers through og.Lighting2D (og-game §8; og-anim's 2D skeletons). Sent
+// along the ramp (`keeper:<x>`), it plays its walk clip there, each foot
+// planted while it carries the keeper and lifted while it swings, and
+// breathes again when it arrives (the Walk and Plant systems).
+//
+// 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, u32, SHAPE_BOX } from "@origingame/engine";
+import type { FlipbookInfo, Result, Rig2DInfo, TileObject, World } from "@origingame/engine";
+
+/** The courier's clips, in the sheet's file order (og-game §8): `start` checks them. */
+const CLIP = { idle: 0, run: 1, jump: 2, fall: 3 } as const;
+/** The camera's height in world units: 14 cells of 16 px, the 16bit-pixel look's 224-pixel frame. */
+const VIEW_H = 14;
+/** The ledges' collider layer (the map's `colliderLayers 2`), one-way for the courier. */
+const LEDGES = 2;
+/** The courier's box (og.Collider): its feet are its position. */
+const BOX = { w: 0.9, h: 1.9 } as const;
+/** Below this the courier fell into the pit. */
+const FALL_Y = -3;
+const LIVES = 3;
+/** The keeper's ramp: a plank from (x0, y0) on the roof rising at `slope` (tan 12°) to x1. */
+const RAMP = { x0: 4.5, y0: 2, x1: 7.6, slope: 0.21256, sinHalf: 0.104528, cosHalf: 0.994522 } as const;
+/** The ramp's top at x. */
+const rampY = (x: number): number => RAMP.y0 + RAMP.slope * (x - RAMP.x0);
+/** The keeper's ankles and its root above the ramp (its legs reach 1.1 from a hip 1.1 up: a slight bend), the lantern from its feet, in world units. */
+const ANKLE = 0.12;
+const LIFT = 0.08;
+const LANTERN = { x: 0.25, y: 1.0 } as const;
+/** The keeper's gait: the walk clip's 0.8 s cycle carries it a stride of 0.4 m (a step per foot), each foot lifted at most `lift` mid-swing. */
+const WALK = { speed: 0.5, stride: 0.4, lift: 0.08 } as const;
+
+/** The courier. */
+export const Hero = defineComponent("Hero", { spawnX: f32(0, { unit: "m" }), spawnY: f32(0, { unit: "m" }) });
+
+/** A coin of the map's `coin` objects; taken once. */
+export const Coin = defineComponent("Coin", { taken: bool() });
+
+/** One of the keeper's feet: its IK target stays on the ramp `dx` ahead of the keeper (behind when negative), `lag` of a gait cycle after the front foot. */
+export const Plant = defineComponent("Plant", { dx: f32(0, { unit: "m" }), lag: f32(0, { min: 0, max: 1 }) });
+
+/** A voice: the sound bit (Sound) it plays when Game.sfx asks for it. */
+export const Voice = defineComponent("Voice", { bit: u32() });
+
+const Sound = { Jump: 1, Coin: 2 } as const;
+
+/** The run: what the HUD shows and the systems share. */
+export const Game = defineResource("Game", {
+  coins: u32(),
+  total: u32(),
+  lives: u32(LIVES),
+  won: bool(),
+  /** The last life was lost: Pickups starts the level again. */
+  restart: bool(),
+  goalX: f32(0, { unit: "m" }),
+  heroX: f32(0, { unit: "m" }),
+  heroY: f32(0, { unit: "m" }),
+  /** Sounds asked for this tick (Sound bits), played by Voices. */
+  sfx: u32(),
+  /** The pause menu is open: the courier and time hold. */
+  paused: bool(),
+  /** The HUD's touch controls this tick (a phone): the run and the held jump. */
+  touchX: f32(0, { min: -1, max: 1 }),
+  touchJump: bool(),
+  /** The keeper's breaths: og.Skeleton2DEvent "inhale" (the idle clip's event at 0). */
+  inhales: u32(),
+  /** The keeper's footfalls: og.Skeleton2DEvent "step" (the walk clip's, one per foot). */
+  steps: u32(),
+});
+
+/** Where the keeper walks (`keeper:<x>`), how far it has walked since it set off (its gait's phase), and its clips. */
+export const KeeperWalk = defineResource("KeeperWalk", {
+  goal: f32(6, { unit: "m" }),
+  walked: f32(0, { unit: "m" }),
+  walking: bool(),
+  /** -1 facing left (towards the spawn), 1 right. */
+  facing: f32(-1),
+  idle: u32(),
+  walk: u32(),
+});
+
+function must<T>(r: Result<T>): T {
+  if (!r.ok) throw new Error(r.reason);
+  return r.value;
+}
+
+/**
+ * Input to the controller, on the press's tick (og-feel §1): the run, the
+ * held jump (released early, the jump is lower), Down to drop through a
+ * ledge. The jump's sound starts on the press while the controller can
+ * jump (og-feel §12). A fall into the pit costs a life and puts the
+ * courier back at the spawn; the last life starts the level again.
+ */
+export const Control = defineSystem(
+  "Control",
+  { reads: [Hero, og.Input, og.Gamepad], writes: [Game, og.PlatformerController, og.Transform], after: ["Hud"] },
+  (q, _time, world) => {
+    const g = must(world.resource(Game));
+    const input = must(world.resource(og.Input));
+    const pad = must(world.resource(og.Gamepad));
+    const stick = pad.axis("leftX", 0);
+    const run = Math.max(-1, Math.min(1, input.axis("ArrowLeft", "ArrowRight") + input.axis("KeyA", "KeyD") + (Math.abs(stick) > 0.25 ? stick : 0) + g.touchX));
+    const jump = input.down("Space") || input.down("ArrowUp") || input.down("KeyW") || pad.down("a", 0) || g.touchJump;
+    const pressed = input.pressed("Space") || input.pressed("ArrowUp") || input.pressed("KeyW") || pad.pressed("a", 0);
+    const down = input.down("ArrowDown") || input.down("KeyS") || pad.down("down", 0);
+    for (const a of q.archetypes()) {
+      const hero = a.column(Hero);
+      const pc = a.column(og.PlatformerController);
+      const p = a.column(og.Transform).position;
+      for (let i = 0; i < a.count; i++) {
+        const playing = !g.won && !g.paused;
+        pc.moveX[i] = playing ? run : 0;
+        pc.jump[i] = playing && jump ? 1 : 0;
+        pc.down[i] = playing && down ? 1 : 0;
+        if (playing && pressed && (pc.grounded[i] === 1 || pc.coyote[i]! > 0)) g.sfx |= Sound.Jump;
+        if (p[i * 3 + 1]! < FALL_Y) {
+          g.lives -= 1;
+          // The last life: Pickups puts every coin back.
+          if (g.lives === 0) g.restart = true;
+          p[i * 3] = hero.spawnX[i]!;
+          p[i * 3 + 1] = hero.spawnY[i]!;
+          pc.velocity[i * 3] = pc.velocity[i * 3 + 1] = 0;
+        }
+        g.heroX = p[i * 3]!;
+        g.heroY = p[i * 3 + 1]!;
+      }
+    }
+  },
+);
+
+/** A coin the courier's box touches is taken; reaching the goal clears the level; the last life lost puts every coin back. */
+export const Pickups = defineSystem("Pickups", { writes: [Game, Coin, og.Sprite], reads: [og.Transform], after: ["Control"] }, (q, _time, world) => {
+  const g = must(world.resource(Game));
+  const restart = g.restart;
+  if (restart) {
+    // The last life was lost: every coin back, the lives full.
+    g.restart = false;
+    g.coins = 0;
+    g.lives = LIVES;
+  }
+  for (const a of q.archetypes()) {
+    const coin = a.column(Coin);
+    const sprite = a.column(og.Sprite);
+    const p = a.column(og.Transform).position;
+    for (let i = 0; i < a.count; i++) {
+      if (restart) {
+        coin.taken[i] = 0;
+        sprite.visible[i] = 1;
+      }
+      if (coin.taken[i] === 1) continue;
+      const dx = Math.abs(p[i * 3]! - g.heroX);
+      const dy = p[i * 3 + 1]! - g.heroY;
+      if (dx < BOX.w / 2 + 0.35 && dy > -0.35 && dy < BOX.h + 0.35) {
+        coin.taken[i] = 1;
+        sprite.visible[i] = 0;
+        g.coins += 1;
+        g.sfx |= Sound.Coin;
+      }
+    }
+  }
+  if (!g.won && g.heroX >= g.goalX) {
+    g.won = true;
+    g.sfx |= Sound.Coin;
+  }
+});
+
+/** The courier's clip from what its controller did, and its facing. */
+export const Animate = defineSystem("Animate", { reads: [Hero, og.PlatformerController], writes: [og.Flipbook, og.Sprite], after: ["Control"] }, (q) => {
+  for (const a of q.archetypes()) {
+    const pc = a.column(og.PlatformerController);
+    const fb = a.column(og.Flipbook);
+    const sprite = a.column(og.Sprite);
+    for (let i = 0; i < a.count; i++) {
+      const vx = pc.velocity[i * 3]!;
+      const vy = pc.velocity[i * 3 + 1]!;
+      const clip = pc.grounded[i] !== 1 ? (vy > 0 ? CLIP.jump : CLIP.fall) : Math.abs(vx) > 0.2 ? CLIP.run : CLIP.idle;
+      if (fb.clip[i] !== clip) fb.clip[i] = clip;
+      sprite.flipX[i] = pc.facing[i]! < 0 ? 1 : 0;
+    }
+  }
+});
+
+/**
+ * Walks the keeper towards KeeperWalk.goal along the ramp at the gait's
+ * speed (by scaled time, as the clip plays: paused, both hold), facing the
+ * way it goes, with the walk clip; on arrival it faces the spawn again with
+ * the idle clip (which starts over, breathing in).
+ */
+export const Walk = defineSystem("Walk", { writes: [KeeperWalk, og.Skeleton2D, og.Transform], after: ["Control"] }, (_q, time, world) => {
+  const keeper = world.find("keeper");
+  if (keeper === null) return;
+  const w = must(world.resource(KeeperWalk));
+  const x = must(world.get(keeper, og.Transform)).position.x;
+  const left = w.goal - x;
+  if (left === 0 && !w.walking) return;
+  const step = WALK.speed * time.scaledDt;
+  const arrived = Math.abs(left) <= step;
+  const nx = arrived ? w.goal : x + Math.sign(left) * step;
+  w.walked = arrived ? 0 : (w.walking ? w.walked : 0) + Math.abs(nx - x);
+  w.walking = !arrived;
+  w.facing = arrived ? -1 : Math.sign(left);
+  must(world.set(keeper, og.Transform, { position: { x: nx, y: rampY(nx) + LIFT, z: 0 } }));
+  const s = must(world.get(keeper, og.Skeleton2D));
+  const clip = arrived ? w.idle : w.walk;
+  const flipX = w.facing < 0;
+  // Only what changed: a new clip starts at 0 (the idle clip's breath, the walk's first step).
+  if (s.clip !== clip || s.flipX !== flipX) must(world.set(keeper, og.Skeleton2D, { clip, flipX }));
+});
+
+/**
+ * Puts the keeper's feet on the ramp (og.IkTarget2D: the legs' two-bone IK
+ * reaches each target, the knees bend as the hip bobs). Standing, each foot
+ * is `dx` from the keeper; walking, the front foot's gait phase is the
+ * distance walked over the stride and the back foot's half a cycle later:
+ * for half a cycle a foot stays where it is on the plank while the keeper
+ * passes over it, for the other half it swings a stride forward, lifted on
+ * a parabola. Keeps the lantern's light at its hand, and counts the
+ * clips' breaths and footfalls.
+ */
+export const Plant2D = defineSystem("Plant", { reads: [Plant, KeeperWalk, og.Skeleton2DEvent], writes: [Game, og.IkTarget2D, og.Transform], after: ["Walk"] }, (q, _time, world) => {
+  const keeper = world.find("keeper");
+  if (keeper === null) return;
+  const at = must(world.get(keeper, og.Transform)).position;
+  const w = must(world.resource(KeeperWalk));
+  for (const a of q.archetypes()) {
+    const plant = a.column(Plant);
+    const target = a.column(og.IkTarget2D).target;
+    for (let i = 0; i < a.count; i++) {
+      let ahead = plant.dx[i]!;
+      let lift = 0;
+      if (w.walking) {
+        const phase = w.walked / WALK.stride + plant.lag[i]!;
+        const p = phase - Math.floor(phase);
+        if (p < 0.5) {
+          // Planted: it slides back under the keeper as fast as the keeper walks.
+          ahead += WALK.stride * (0.25 - p);
+        } else {
+          const s = (p - 0.5) * 2;
+          ahead += WALK.stride * (s - 0.5) * 0.5;
+          lift = WALK.lift * 4 * s * (1 - s);
+        }
+      }
+      const x = at.x + w.facing * ahead;
+      target[i * 2] = x;
+      target[i * 2 + 1] = rampY(x) + ANKLE + lift;
+    }
+  }
+  const lantern = world.find("lantern");
+  if (lantern !== null) must(world.set(lantern, og.Transform, { position: { x: at.x - w.facing * LANTERN.x, y: at.y + LANTERN.y, z: 0 } }));
+  const g = must(world.resource(Game));
+  for (const e of world.events(og.Skeleton2DEvent)) {
+    if (e.name === "inhale") g.inhales += 1;
+    else if (e.name === "step") g.steps += 1;
+  }
+});
+
+/** Plays each sound asked for once: a voice still playing is stopped this tick and played again the next. */
+export const Voices = defineSystem("Voices", { reads: [Voice], writes: [Game, og.AudioSource], after: ["Pickups"] }, (q, _time, world) => {
+  const g = must(world.resource(Game));
+  if (g.sfx === 0) return;
+  let left = g.sfx;
+  for (const a of q.archetypes()) {
+    const voice = a.column(Voice);
+    const source = a.column(og.AudioSource);
+    for (let i = 0; i < a.count; i++) {
+      const bit = voice.bit[i]!;
+      if ((g.sfx & bit) === 0) continue;
+      if (source.playing[i]) source.playing[i] = 0;
+      else {
+        source.playing[i] = 1;
+        left &= ~bit;
+      }
+    }
+  }
+  g.sfx = left;
+});
+
+/**
+ * The UI kit's platformer HUD (og-ui §6): lives, coins, the level's name,
+ * the pause button and, on a phone, the touch controls (taken by Control
+ * this tick: Hud runs first). Pause (the button, Escape or the pad's Start)
+ * opens the kit's pause menu and holds time until Resume.
+ */
+export const Hud = defineSystem("Hud", { writes: [Game] }, (_q, _time, world) => {
+  const g = must(world.resource(Game));
+  const hud = og.ui.platformerHud("Hud", {
+    lives: g.lives,
+    maxLives: LIVES,
+    coins: g.coins,
+    score: g.coins * 100,
+    level: og.i18n.t(world, g.won ? "hud.clear" : "hud.level"),
+    timeLeft: null,
+    // A d-pad and Jump where the pointer is a finger (og-ui §5).
+    touch: og.ui.frameViewport().coarsePointer,
+  });
+  g.touchX = g.paused ? 0 : hud.moveX;
+  g.touchJump = !g.paused && hud.held.includes("jump");
+  const menu = og.ui.pauseMenu("Pause", { open: g.paused, items: [{ id: "resume", label: og.i18n.t(world, "pause.resume") }] });
+  if (g.paused && menu.selected === "resume") {
+    g.paused = false;
+    must(og.time.setScale(world, 1));
+  } else if (!g.paused && hud.paused) {
+    g.paused = true;
+    must(og.time.setScale(world, 0));
+  }
+});
+
+/**
+ * The lamp keeper: a plank ramp, the rig on it facing the spawn, a foot
+ * target per leg, and its lantern's light; og.Lighting2D lights layers 1
+ * and 2 (the keeper, the courier, the coins), the city stays as drawn.
+ */
+function spawnKeeper(world: World, rig: Rig2DInfo): void {
+  const idle = og.anim.clip(rig, "idle");
+  const walk = og.anim.clip(rig, "walk");
+  if (idle < 0 || walk < 0) throw new Error("rigs/keeper.ogt needs clips idle and walk");
+  const mid = (RAMP.x0 + RAMP.x1) / 2;
+  const plank = must(world.spawn({ name: "ramp", position: { x: mid, y: rampY(mid) - 0.2, z: 0 }, quaternion: { x: 0, y: 0, z: RAMP.sinHalf, w: RAMP.cosHalf } }));
+  // The plank is a region of the keeper's texture (pixels 24..64 x 32..40 of 64 x 64).
+  must(world.insert(plank, og.Sprite, { texture: rig.texture, width: RAMP.x1 - RAMP.x0, height: 0.4, uvMin: { x: 0.375, y: 0.5 }, uvMax: { x: 1, y: 0.625 }, layer: 1 }));
+  const x = 6;
+  const keeper = must(world.spawn({ name: "keeper", position: { x, y: rampY(x) + LIFT, z: 0 } }));
+  must(world.insert(keeper, og.Skeleton2D, { rig: rig.rig, clip: idle, flipX: true, layer: 1 }));
+  const w = must(world.resource(KeeperWalk));
+  Object.assign(w, { goal: x, walked: 0, walking: false, facing: -1, idle, walk });
+  // Facing left, the front foot is the left one; the back foot steps half a cycle later.
+  for (const [name, ahead, lag] of [["leg-f", 0.15, 0], ["leg-b", -0.15, 0.5]] as const) {
+    const constraint = rig.constraints.indexOf(name);
+    if (constraint < 0) throw new Error(`rigs/keeper.ogt has no ik ${name}`);
+    const fx = x - ahead;
+    const foot = must(world.spawn({ name: `keeper-${name}` }));
+    must(world.insert(foot, og.IkTarget2D, { skeleton: keeper, constraint, target: { x: fx, y: rampY(fx) + ANKLE }, tolerance: 0.02 }));
+    must(world.insert(foot, Plant, { dx: ahead, lag }));
+  }
+  const light = must(world.spawn({ name: "lantern", position: { x: x + LANTERN.x, y: rampY(x) + LIFT + LANTERN.y, z: 0 } }));
+  must(world.insert(light, og.Light2D, { color: { r: 1, g: 0.72, b: 0.35 }, intensity: 1.6, radius: 4, castShadows: false }));
+  const lighting = must(world.resource(og.Lighting2D));
+  lighting.enabled = true;
+  lighting.ambient = { r: 0.62, g: 0.64, b: 0.78 };
+  lighting.minLayer = 1;
+  lighting.maxLayer = 2;
+}
+
+function checkClips(info: FlipbookInfo): void {
+  for (const [name, index] of Object.entries(CLIP)) {
+    const at = og.anim.clip(info, name);
+    if (at !== index) throw new Error(`sprites/courier.ogt: clip ${name} is ${at}, the code expects ${index}`);
+  }
+}
+
+/** A map object's point in world units: the map's top-left corner is at (0, height). */
+function at(o: TileObject, height: number): { x: number; y: number } {
+  return { x: o.position.x, y: height + o.position.y };
+}
+
+export default og.game({
+  // The art direction as data (assets/looks/origin-game-2d.ogt; og-taste §12).
+  look: "looks/origin-game-2d.ogt",
+  tick: 60,
+  seed: 1,
+  resources: [Game, KeeperWalk],
+  systems: [Hud, Control, Pickups, Animate, Walk, Plant2D, Voices],
+  start(world) {
+    const map = must(og.load.tilemap(world, "maps/level.ogt"));
+    const courier = must(og.load.flipbook(world, "sprites/courier.ogt"));
+    checkClips(courier);
+    const coin = must(og.load.flipbook(world, "sprites/coin.ogt"));
+    spawnKeeper(world, must(og.load.rig2d(world, "rigs/keeper.ogt")));
+    const height = map.height * map.tileHeight;
+
+    const camera = must(world.resource(og.Camera));
+    camera.orthographic = true;
+    camera.height = VIEW_H;
+    camera.position = { x: 8, y: height / 2, z: 50 };
+    camera.background = { r: 0.0042, g: 0.0048, b: 0.018 };
+
+    // The map draws from its top-left corner and gives its collision layers static colliders.
+    const level = must(world.spawn({ name: "level", position: { x: 0, y: height, z: 0 } }));
+    must(world.insert(level, og.Tilemap, { map: map.map, layer: -10 }));
+
+    const g = must(world.resource(Game));
+    for (const o of map.objects) {
+      const p = at(o, height);
+      if (o.kind === "spawn") {
+        const hero = must(world.spawn({ name: "hero", position: { x: p.x, y: p.y, z: 0 } }));
+        must(world.insert(hero, Hero, { spawnX: p.x, spawnY: p.y }));
+        must(world.insert(hero, og.Sprite, { texture: courier.texture, width: 2, height: 2.5, anchor: { x: 0.5, y: 0 }, layer: 2 }));
+        must(world.insert(hero, og.Flipbook, { sheet: courier.sheet, clip: CLIP.idle }));
+        must(world.insert(hero, og.Collider, { shape: SHAPE_BOX, size: { x: BOX.w, y: BOX.h, z: 1 }, offset: { x: 0, y: BOX.h / 2, z: 0 } }));
+        // og-feel §12's platformer tunables; the ledges' layer is one-way.
+        must(world.insert(hero, og.PlatformerController, { maxSpeed: 8, jumpHeight: 3.6, timeToApex: 0.4, oneWayLayers: LEDGES, wallJumps: false }));
+        must(world.insert(hero, og.Follow2D, { offset: { x: 0, y: 1.5 }, deadZone: { x: 1, y: 0.8 }, smoothTime: 0.12, lookAhead: 0.2, lookAheadMax: { x: 2, y: 1 } }));
+      } else if (o.kind === "coin") {
+        const e = must(world.spawn({ name: o.name, position: { x: p.x, y: p.y, z: 0 } }));
+        must(world.insert(e, Coin));
+        must(world.insert(e, og.Sprite, { texture: coin.texture, width: 0.7, height: 0.7, layer: 1 }));
+        must(world.insert(e, og.Flipbook, { sheet: coin.sheet, clip: 0 }));
+        g.total += 1;
+      } else if (o.kind === "goal") {
+        g.goalX = p.x;
+      }
+    }
+
+    for (const [path, bit] of [["audio/jump.wav", Sound.Jump], ["audio/coin.wav", Sound.Coin]] as const) {
+      const sound = og.load.sound(world, path);
+      if (!sound.ok) continue;
+      const v = must(world.spawn({ name: `voice-${bit}` }));
+      must(world.insert(v, Voice, { bit }));
+      must(world.insert(v, og.AudioSource, { sound: sound.value, playing: false, volume: 0.5 }));
+    }
+
+    // Every string the HUD shows (og-i18n §1), and its font.
+    must(og.i18n.load(world, "strings/en.ogt"));
+    const font = og.load.font(world, "fonts/ui.ttf");
+    if (font.ok) og.ui.configure(world, { font: font.value });
+  },
+  commands: {
+    /** `warp:<x>:<y>`: put the courier's feet there. */
+    warp: (world, args) => {
+      const hero = world.find("hero");
+      const x = Number(args[0]);
+      const y = Number(args[1]);
+      if (hero === null || !Number.isFinite(x) || !Number.isFinite(y)) throw new Error("write warp:<x>:<y>");
+      must(world.set(hero, og.Transform, { position: { x, y, z: 0 } }));
+    },
+    /** `keeper:<x>`: send the keeper walking along the ramp to x (the Walk system moves it; its feet step on the plank). */
+    keeper: (world, args) => {
+      const x = Math.max(RAMP.x0 + 0.4, Math.min(RAMP.x1 - 0.4, Number(args[0])));
+      if (world.find("keeper") === null || !Number.isFinite(x)) throw new Error("write keeper:<x>");
+      must(world.resource(KeeperWalk)).goal = x;
+    },
+  },
+  commandHelp: {
+    warp: { usage: "<x>:<y>", doc: "Put the courier's feet at a world point." },
+    keeper: { usage: "<x>", doc: "Send the lamp keeper walking along its ramp to x." },
+  },
+  facts: (world) => {
+    const g = world.resource(Game);
+    if (!g.ok) return {};
+    return { coins: g.value.coins, total: g.value.total, lives: g.value.lives, won: g.value.won, inhales: g.value.inhales, steps: g.value.steps, x: g.value.heroX, y: g.value.heroY };
+  },
+});

package/template-2d/tests/keeper.og.ts

@@ -0,0 +1,93 @@
+// The lamp keeper's playtest (og-game §8, 2D skeletons): the rig plays its
+// idle clip (its event counted as breaths) with both legs' IK targets on
+// the ramp and reached; `keeper:7` sends it walking up the ramp with its
+// walk clip, facing the way it goes, one foot planted on the plank while
+// the other swings above it; it arrives, faces the spawn and breathes again
+// with both feet planted, higher.
+import { playtest } from "@origingame/engine/playtest";
+
+interface Got<T> {
+  value: T;
+}
+
+type Fields = Record<string, number | boolean | string | number[]>;
+
+interface EntityDump {
+  components: Record<string, Fields>;
+}
+
+/** The ramp's top at x (src/main.ts's RAMP), plus the ankle's height. */
+const ankleY = (x: number): number => 2 + 0.21256 * (x - 4.5) + 0.12;
+/** The plank's ends and the highest a swinging foot lifts (src/main.ts's RAMP and WALK). */
+const PLANK = { x0: 4.5, x1: 7.6 } as const;
+const LIFT = 0.08;
+/** The rig's clips, in file order. */
+const IDLE = 0;
+const WALK = 1;
+
+export default playtest({
+  name: "The lamp keeper breathes on its ramp with both feet planted, walks up the slope stepping on the plank, and stands planted again",
+  commands:
+    "1.0:screenshot:keeper.png;1.01:dump_entity:keeper:keeper.json;1.02:dump_entity:keeper-leg-f:front.json;1.03:dump_entity:keeper-leg-b:back.json;" +
+    "2.1:get:Game:game.json;2.2:keeper:7;" +
+    "2.6:screenshot:walk.png;2.61:dump_entity:keeper:walk.json;2.62:dump_entity:keeper-leg-f:walk-front.json;2.63:dump_entity:keeper-leg-b:walk-back.json;" +
+    "2.9:dump_entity:keeper:walk-later.json;2.91:dump_entity:keeper-leg-f:walk-front-later.json;2.92:dump_entity:keeper-leg-b:walk-back-later.json;" +
+    "4.6:dump_entity:keeper:keeper-up.json;4.61:dump_entity:keeper-leg-f:front-up.json;4.62:dump_entity:keeper-leg-b:back-up.json;4.7:get:Game:game-end.json;4.8:quit",
+  check(run, t) {
+    t.ok(run.quit, "the script reached quit");
+    for (const png of ["keeper.png", "walk.png"]) {
+      t.frame(png, () => {
+        const frame = run.png(png);
+        t.ok(frame.width > 0 && frame.height > 0, `a ${frame.width}x${frame.height} frame was captured`);
+      });
+    }
+    const skeleton = (file: string) => run.json<EntityDump>(file).components["og.Skeleton2D"]!;
+    const at = (file: string) => (run.json<EntityDump>(file).components["og.Transform"]!["position"] as number[])[0]!;
+    const foot = (file: string) => run.json<EntityDump>(file).components["og.IkTarget2D"]!;
+
+    // Standing: the idle clip, both feet on the ramp under the keeper.
+    const idle = skeleton("keeper.json");
+    t.ok(idle["clip"] === IDLE && (idle["time"] as number) > 0.9 && (idle["time"] as number) < 1.1, `the idle clip plays (clip ${idle["clip"]}, time ${idle["time"]})`);
+    for (const [file, label, dx, x0] of [["front.json", "front", -0.15, 6], ["back.json", "back", 0.15, 6], ["front-up.json", "front after the walk", -0.15, 7], ["back-up.json", "back after the walk", 0.15, 7]] as const) {
+      const ik = foot(file);
+      const target = ik["target"] as number[];
+      const x = x0 + dx;
+      t.ok(Math.abs(target[0]! - x) < 1e-4 && Math.abs(target[1]! - ankleY(x)) < 1e-4, `the ${label} foot's target is on the ramp (${target.join(", ")})`);
+      t.ok(ik["reached"] === true, `the ${label} foot reached it (error ${ik["error"]})`);
+    }
+
+    // Walking: the walk clip, facing up the ramp, the keeper between where it was and where it goes.
+    let planted = 0;
+    for (const [keeper, front, back] of [["walk.json", "walk-front.json", "walk-back.json"], ["walk-later.json", "walk-front-later.json", "walk-back-later.json"]] as const) {
+      const s = skeleton(keeper);
+      const x = at(keeper);
+      t.ok(s["clip"] === WALK && s["flipX"] === false, `walking, the keeper plays its walk clip facing right (clip ${s["clip"]}, flipX ${s["flipX"]})`);
+      t.ok(x > 6 && x < 7, `walking, it is part of the way along the ramp (x ${x})`);
+      for (const [file, label] of [[front, "front"], [back, "back"]] as const) {
+        const ik = foot(file);
+        const [fx, fy] = ik["target"] as [number, number];
+        const lift = fy - ankleY(fx);
+        t.ok(fx > PLANK.x0 && fx < PLANK.x1 && lift > -1e-4 && lift <= LIFT + 1e-4, `walking, the ${label} foot is on the plank or above it (x ${fx}, ${lift.toFixed(4)} up)`);
+        t.ok(ik["reached"] === true, `walking, the ${label} foot reached its target (error ${ik["error"]})`);
+        if (Math.abs(lift) < 1e-4) planted += 1;
+      }
+    }
+    t.ok(planted >= 2, `while it walks a foot stays planted on the plank (${planted} of 4 targets on it)`);
+    // The back foot carried the keeper from 2.6 s to 2.9 s: it did not move.
+    const before = foot("walk-back.json")["target"] as number[];
+    const later = foot("walk-back-later.json")["target"] as number[];
+    t.ok(Math.abs(before[0]! - later[0]!) < 1e-4 && Math.abs(before[1]! - later[1]!) < 1e-4, `the planted foot stays put while the keeper passes over it (${before.join(", ")} then ${later.join(", ")})`);
+
+    // Arrived: idle again, facing the spawn, at x 7.
+    const up = skeleton("keeper-up.json");
+    t.ok(up["clip"] === IDLE && up["flipX"] === true && Math.abs(at("keeper-up.json") - 7) < 1e-4, `it arrived at 7 and breathes facing the spawn (clip ${up["clip"]}, x ${at("keeper-up.json")})`);
+
+    // A loop of 2 s from tick 0 to 2.1 s passed its event at 0 and at 2; the walk
+    // (2 s at 0.5 m/s, a step every 0.4 s) stepped 5 times, and the idle clip
+    // started over on arrival with a breath.
+    const game = run.json<Got<{ inhales: number }>>("game.json").value;
+    t.ok(game.inhales === 2, `og.Skeleton2DEvent counted two breaths before the walk (${game.inhales})`);
+    const end = run.json<Got<{ inhales: number; steps: number }>>("game-end.json").value;
+    t.ok(end.steps === 5 && end.inhales === 3, `the walk clip's events counted 5 steps, then a third breath (${end.steps}, ${end.inhales})`);
+  },
+});

package/template-2d/tests/smoke.og.ts

@@ -0,0 +1,60 @@
+// The starter's playtest, run by `og test` through `og run --headless
+// --commands`: the courier runs right over two coins, jumps up through the
+// one-way ledge above it and lands on top, Escape opens the pause menu and
+// holds time, Escape again resumes, and a fall into the pit costs a life
+// and puts the courier back at the spawn.
+import { playtest } from "@origingame/engine/playtest";
+
+interface Got<T> {
+  value: T;
+}
+
+interface Game {
+  coins: number;
+  lives: number;
+  paused: boolean;
+  heroX: number;
+  heroY: number;
+}
+
+interface EntityDump {
+  components: Record<string, Record<string, number | boolean | string | number[]>>;
+}
+
+interface UiDump {
+  elements: Array<{ id: string; text: string; width: number; height: number }>;
+}
+
+export default playtest({
+  name: "The courier runs over two coins, jumps up through a one-way ledge onto it, pauses and resumes, and the pit costs a life",
+  commands:
+    "0.5:key_down:ArrowRight;2.0:key_up:ArrowRight;" +
+    "2.3:key_down:Space;2.9:key_up:Space;" +
+    "3.5:screenshot:ledge.png;3.55:dump_entity:hero:hero.json;3.6:get:Game:ledge.json;3.65:dump_ui:ui.json;" +
+    "3.7:key_down:Escape;3.75:key_up:Escape;4.2:get:Game:paused.json;" +
+    "4.3:key_down:Escape;4.35:key_up:Escape;4.5:get:Game:resumed.json;" +
+    "4.6:warp:21:-1;5.0:get:Game:fell.json;5.1:quit",
+  check(run, t) {
+    t.ok(run.quit, "the script reached quit");
+    t.frame("ledge.png", () => {
+      const frame = run.png("ledge.png");
+      t.ok(frame.width > 0 && frame.height > 0, `a ${frame.width}x${frame.height} frame was captured`);
+    });
+    const ledge = run.json<Got<Game>>("ledge.json").value;
+    t.ok(ledge.coins === 2, `the run took the two coins on the roof (${ledge.coins})`);
+    // The ledge (cells 11-15 of row 9) has its top at y 5: the courier passed up through it and stands on it.
+    t.ok(ledge.heroX > 11 && ledge.heroX < 16, `the courier is under the ledge's span (x ${ledge.heroX.toFixed(2)})`);
+    t.ok(Math.abs(ledge.heroY - 5) < 0.05, `and stands on the one-way ledge (y ${ledge.heroY.toFixed(3)})`);
+    const hero = run.json<EntityDump>("hero.json");
+    t.ok(hero.components["og.PlatformerController"]!["grounded"] === true, "the controller is grounded on the ledge");
+    const ui = run.json<UiDump>("ui.json");
+    const count = ui.elements.find((e) => e.id === "Count");
+    t.ok(count !== undefined && count.text === "2", `the platformer HUD counts the coins ("${count?.text}")`);
+    const paused = run.json<Got<Game>>("paused.json").value;
+    t.ok(paused.paused, "Escape opened the pause menu");
+    t.ok(!run.json<Got<Game>>("resumed.json").value.paused, "Escape again resumed");
+    const fell = run.json<Got<Game>>("fell.json").value;
+    t.ok(fell.lives === 2, `the pit cost a life (${fell.lives} left)`);
+    t.ok(Math.abs(fell.heroX - 2.5) < 0.5 && fell.heroY < 2.5, `the courier is back at the spawn (${fell.heroX.toFixed(2)}, ${fell.heroY.toFixed(2)})`);
+  },
+});

package/template-2d/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"]
+}