@origingame/create-game 0.3.0 → 0.5.0

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

@@ -16,9 +16,11 @@
 // 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).
+// along the ramp (`keeper:<x>`), it turns to face the way (a paper turn
+// over a few ticks), plays its walk clip there, each foot planted while it
+// carries the keeper and lifted while it swings, lets both feet land when
+// it arrives, turns back and breathes again (the Walk and Plant systems).
+// No foot ever moves faster than the gait's own swing.
 //
 // 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.
@@ -47,6 +49,16 @@ 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 fastest a foot moves (m/s): the gait's swing at its start, a stride
+ * forward in half a cycle (twice the walking speed) while it rises up the
+ * slope and off it (the lift's parabola, 4 lift over the swing's length,
+ * at its steepest). A foot sent elsewhere (setting off, stopping, a turn)
+ * steps there no faster.
+ */
+const FOOT_SPEED = Math.hypot(2 * WALK.speed, 2 * WALK.speed * RAMP.slope + (8 * WALK.lift * WALK.speed) / WALK.stride);
+/** A turn's ticks: the rig narrows to its edge and opens the other way (og.Transform's scale x, never 0). */
+const TURN_TICKS = 12;
 
 /** The courier. */
 export const Hero = defineComponent("Hero", { spawnX: f32(0, { unit: "m" }), spawnY: f32(0, { unit: "m" }) });
@@ -54,8 +66,17 @@ export const Hero = defineComponent("Hero", { spawnX: f32(0, { unit: "m" }), spa
 /** 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 }) });
+/**
+ * One of the keeper's feet: its IK target stands on the ramp `dx` ahead of
+ * the keeper (behind when negative), `lag` of a gait cycle after the front
+ * foot; `x`, `y` is where the foot is.
+ */
+export const Plant = defineComponent("Plant", {
+  dx: f32(0, { unit: "m" }),
+  lag: f32(0, { min: 0, max: 1 }),
+  x: f32(0, { unit: "m" }),
+  y: f32(0, { unit: "m" }),
+});
 
 /** A voice: the sound bit (Sound) it plays when Game.sfx asks for it. */
 export const Voice = defineComponent("Voice", { bit: u32() });
@@ -86,13 +107,20 @@ export const Game = defineResource("Game", {
   steps: u32(),
 });
 
-/** Where the keeper walks (`keeper:<x>`), how far it has walked since it set off (its gait's phase), and its clips. */
+/** Where the keeper walks (`keeper:<x>`), how far it has walked since it set off (its gait's phase), its turn and stop, 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),
+  /** Ticks of a turn done (0: not turning). */
+  turning: u32(),
+  /** og.Transform's scale x: 1, or through a turn from 1 towards -1. */
+  squash: f32(1),
+  /** Arrived, the feet stepping to stand (Plant sets `landed` when both are down). */
+  settling: bool(),
+  landed: bool(true),
   idle: u32(),
   walk: u32(),
 });
@@ -201,30 +229,62 @@ export const Animate = defineSystem("Animate", { reads: [Hero, og.PlatformerCont
 /**
  * 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).
+ * way it goes, with the walk clip. Facing the other way first, it turns
+ * over TURN_TICKS (og.Transform's scale x eased from 1 to -1, never 0, then
+ * flipX), its feet stepping across with it. On arrival it holds the walk
+ * pose until Plant has both feet down, turns to face the spawn, and once
+ * they are down again breathes 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 }));
+  const place = (nx: number) => must(world.set(keeper, og.Transform, { position: { x: nx, y: rampY(nx) + LIFT, z: 0 }, scale: { x: w.squash, y: 1, z: 1 } }));
+  if (w.turning > 0 || (time.scaledDt > 0 && w.turning === 0 && wantsTurn(w, x))) {
+    // A turn: the rig narrows to its edge and opens facing the other way.
+    if (time.scaledDt === 0) return;
+    w.turning += 1;
+    if (w.turning < TURN_TICKS) {
+      w.squash = Math.cos((Math.PI * (w.turning - 0.5)) / (TURN_TICKS - 0.5));
+    } else {
+      w.turning = 0;
+      w.squash = 1;
+      w.facing = -w.facing;
+      must(world.set(keeper, og.Skeleton2D, { flipX: w.facing < 0 }));
+    }
+    place(x);
+    return;
+  }
+  const left = w.goal - x;
+  if (left !== 0) {
+    const step = WALK.speed * time.scaledDt;
+    const arrived = Math.abs(left) <= step;
+    const nx = arrived ? w.goal : x + Math.sign(left) * step;
+    w.walked = (w.walking ? w.walked : 0) + Math.abs(nx - x);
+    w.walking = !arrived;
+    w.settling = arrived;
+    w.landed = false;
+    place(nx);
+    // Walking plays the walk clip from its first step; arrived, it holds its pose while the feet land.
+    if (s.clip !== w.walk) must(world.set(keeper, og.Skeleton2D, { clip: w.walk, speed: 1 }));
+    else if (arrived) must(world.set(keeper, og.Skeleton2D, { speed: 0 }));
+    return;
+  }
+  if (w.settling && w.landed) w.settling = false;
+  // Standing, both feet down and facing the spawn: breathe.
+  if (!w.settling && w.landed && w.facing < 0 && s.clip !== w.idle) must(world.set(keeper, og.Skeleton2D, { clip: w.idle, speed: 1 }));
 });
 
+/** Whether the keeper must turn before it goes on: towards its goal, or back to the spawn once it stands with both feet down. */
+function wantsTurn(w: { goal: number; facing: number; settling: boolean; walking: boolean }, x: number): boolean {
+  const left = w.goal - x;
+  if (left !== 0) return Math.sign(left) !== w.facing && !w.walking;
+  return !w.settling && w.facing > 0;
+}
+
 /**
  * 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
@@ -232,14 +292,19 @@ export const Walk = defineSystem("Walk", { writes: [KeeperWalk, og.Skeleton2D, o
  * 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.
+ * a parabola. A foot steps to where it should be at most FOOT_SPEED fast,
+ * lifted while it is still on its way, so turning, setting off and
+ * stopping are steps, not jumps (each leg hangs from its own hip: the
+ * front foot crosses to the other side in a turn). 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) => {
+export const Plant2D = defineSystem("Plant", { reads: [og.Skeleton2DEvent], writes: [Game, KeeperWalk, Plant, 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));
+  const reach = FOOT_SPEED * time.scaledDt;
+  let down = true;
   for (const a of q.archetypes()) {
     const plant = a.column(Plant);
     const target = a.column(og.IkTarget2D).target;
@@ -258,13 +323,22 @@ export const Plant2D = defineSystem("Plant", { reads: [Plant, KeeperWalk, og.Ske
           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;
+      // Turning, each foot follows its hip as the rig narrows and opens the other way.
+      const wx = at.x + w.facing * w.squash * ahead;
+      const [x, y] = toward(plant.x[i]!, plant.y[i]!, wx, rampY(wx) + ANKLE + lift, reach);
+      // Still on its way: lifted with how far it has left (a step's height at half a stride), as fast as it may rise.
+      const rest = Math.abs(wx - x);
+      const [fx, fy] = rest > 1e-6 ? toward(plant.x[i]!, plant.y[i]!, x, Math.max(y, rampY(x) + ANKLE + WALK.lift * Math.min(1, rest / (WALK.stride / 2))), reach) : [x, y];
+      plant.x[i] = fx;
+      plant.y[i] = fy;
+      target[i * 2] = fx;
+      target[i * 2 + 1] = fy;
+      if (Math.hypot(wx - fx, rampY(wx) + ANKLE + lift - fy) > 1e-5 || lift > 0) down = false;
     }
   }
+  w.landed = down;
   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 } }));
+  if (lantern !== null) must(world.set(lantern, og.Transform, { position: { x: at.x - w.facing * w.squash * 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;
@@ -272,6 +346,13 @@ export const Plant2D = defineSystem("Plant", { reads: [Plant, KeeperWalk, og.Ske
   }
 });
 
+/** (x, y) moved towards (tx, ty) by at most `reach`. */
+function toward(x: number, y: number, tx: number, ty: number, reach: number): [number, number] {
+  const d = Math.hypot(tx - x, ty - y);
+  if (d <= reach) return [tx, ty];
+  return [x + ((tx - x) * reach) / d, y + ((ty - y) * reach) / d];
+}
+
 /** 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));
@@ -340,7 +421,7 @@ function spawnKeeper(world: World, rig: Rig2DInfo): void {
   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 });
+  Object.assign(w, { goal: x, walked: 0, walking: false, facing: -1, turning: 0, squash: 1, settling: false, landed: true, 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);
@@ -348,7 +429,7 @@ function spawnKeeper(world: World, rig: Rig2DInfo): void {
     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 }));
+    must(world.insert(foot, Plant, { dx: ahead, lag, x: fx, y: rampY(fx) + ANKLE }));
   }
   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 }));

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

@@ -3,7 +3,10 @@
 // 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.
+// with both feet planted, higher. Every tick from the command to the end
+// is dumped: the turns take several ticks, and no foot ever moves further
+// in a tick than the gait's own swing does, setting off and stopping
+// included; the idle clip comes back only once both feet are down.
 import { playtest } from "@origingame/engine/playtest";
 
 interface Got<T> {
@@ -24,15 +27,38 @@ const LIFT = 0.08;
 /** The rig's clips, in file order. */
 const IDLE = 0;
 const WALK = 1;
+/**
+ * The most a foot moves in a 60 Hz tick: the gait's swing at its start,
+ * worked out by hand from src/main.ts's WALK and RAMP. Forward twice the
+ * walking speed, 1 m/s; up the 0.21256 slope at that, plus the lift's
+ * parabola at its steepest, 4 x 0.08 m over the swing's half cycle of
+ * 0.4 s (2.5 per second of its parameter), 0.8 m/s: 1.01256 m/s. Together
+ * 1.42316 m/s, 0.023719 m a tick.
+ */
+const STRIDE_STEP = 0.023719;
+/** The ticks dumped every tick: from just before `keeper:7` (2.2 s) to the end (5 s). */
+const FIRST = 130;
+const LAST = 300;
+const perTick = Array.from({ length: LAST - FIRST + 1 }, (_, i) => {
+  const k = FIRST + i;
+  const at = (j: number) => (k / 60 + 0.002 * j).toFixed(4);
+  return `${at(1)}:dump_entity:keeper:k${k}.json;${at(2)}:dump_entity:keeper-leg-f:f${k}.json;${at(3)}:dump_entity:keeper-leg-b:b${k}.json`;
+}).join(";");
 
 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",
+  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.85:screenshot:walk.png;2.851:dump_entity:keeper:walk.json;2.852:dump_entity:keeper-leg-f:walk-front.json;2.853:dump_entity:keeper-leg-b:walk-back.json",
+    "3.15:dump_entity:keeper:walk-later.json;3.151:dump_entity:keeper-leg-f:walk-front-later.json;3.152:dump_entity:keeper-leg-b:walk-back-later.json",
+    perTick,
+    "5.1:dump_entity:keeper:keeper-up.json;5.11:dump_entity:keeper-leg-f:front-up.json;5.12:dump_entity:keeper-leg-b:back-up.json;5.2:get:Game:game-end.json;5.3:quit",
+  ]
+    .join(";")
+    .split(";")
+    .sort((a, b) => Number(a.split(":")[0]) - Number(b.split(":")[0]))
+    .join(";"),
   check(run, t) {
     t.ok(run.quit, "the script reached quit");
     for (const png of ["keeper.png", "walk.png"]) {
@@ -73,7 +99,7 @@ export default playtest({
       }
     }
     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.
+    // The back foot carried the keeper from 2.85 s to 3.15 s (the walk starts after the turn): 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(", ")})`);
@@ -82,6 +108,65 @@ export default playtest({
     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")})`);
 
+    // Tick by tick: the keeper's scale x, facing, clip and place, and each foot's target.
+    const ticks = Array.from({ length: LAST - FIRST + 1 }, (_, i) => {
+      const k = FIRST + i;
+      const keeper = run.json<EntityDump>(`k${k}.json`).components;
+      const s = keeper["og.Skeleton2D"]!;
+      return {
+        k,
+        x: (keeper["og.Transform"]!["position"] as number[])[0]!,
+        squash: (keeper["og.Transform"]!["scale"] as number[])[0]!,
+        flipX: s["flipX"] === true,
+        clip: s["clip"] as number,
+        feet: [`f${k}.json`, `b${k}.json`].map((f) => foot(f)["target"] as number[]),
+      };
+    });
+    // No foot moves further in a tick than the gait's swing: setting off, walking, stopping and both turns.
+    let worst = 0;
+    let worstAt = 0;
+    for (let i = 1; i < ticks.length; i++) {
+      for (const f of [0, 1]) {
+        const [a, b] = [ticks[i - 1]!.feet[f]!, ticks[i]!.feet[f]!];
+        const d = Math.hypot(b[0]! - a[0]!, b[1]! - a[1]!);
+        if (d > worst) [worst, worstAt] = [d, ticks[i]!.k];
+      }
+    }
+    t.ok(worst <= STRIDE_STEP + 1e-6, `no foot moves more than a gait tick's ${STRIDE_STEP} m in one tick (at most ${worst.toFixed(6)} m, tick ${worstAt})`);
+    // The walk itself moves the swinging foot nearly that far, so the bound is the gait's, not a loose one.
+    t.ok(worst > STRIDE_STEP * 0.9, `the walk's swing reaches the bound (${worst.toFixed(6)} m)`);
+    // Each turn: several ticks of a narrowed rig (never edge-on), standing still, between one facing and the other.
+    const turns: { from: number; to: number; ticks: number; still: boolean; steady: boolean }[] = [];
+    for (let i = 1; i < ticks.length; i++) {
+      if (ticks[i]!.flipX === ticks[i - 1]!.flipX) continue;
+      let j = i - 1;
+      while (j > 0 && ticks[j]!.squash !== 1) j--;
+      const span = ticks.slice(j, i + 1);
+      turns.push({
+        from: ticks[j]!.k,
+        to: ticks[i]!.k,
+        ticks: i - j - 1,
+        still: span.every((u) => Math.abs(u.x - span[0]!.x) < 1e-6),
+        steady: span.every((u, n) => u.squash !== 0 && (n === 0 || Math.abs(u.squash * (u.flipX ? -1 : 1) - span[n - 1]!.squash * (span[n - 1]!.flipX ? -1 : 1)) <= 0.5)),
+      });
+    }
+    t.ok(turns.length === 2, `the keeper turned twice: setting off and on arrival (${turns.length})`);
+    for (const u of turns) {
+      t.ok(u.ticks >= 4 && u.still && u.steady, `a turn (ticks ${u.from} to ${u.to}) narrows the rig over ${u.ticks} ticks in place, never edge-on or by half its width at once`);
+    }
+    // The stop: the idle clip returns only with both feet down on the ramp, where they stand.
+    const back = ticks.findIndex((u, i) => i > 0 && u.clip === IDLE && ticks[i - 1]!.clip !== IDLE);
+    t.ok(back > 0, `the idle clip came back (tick ${ticks[back]?.k})`);
+    if (back > 0) {
+      const u = ticks[back]!;
+      for (const [f, dx] of [[0, -0.15], [1, 0.15]] as const) {
+        const [fx, fy] = u.feet[f]!;
+        t.ok(Math.abs(fx! - (u.x + dx)) < 1e-4 && Math.abs(fy! - ankleY(fx!)) < 1e-4, `when idle returns, foot ${f} is down where it stands (${fx}, ${fy})`);
+      }
+      const arrived = ticks.findIndex((v) => Math.abs(v.x - 7) < 1e-6);
+      t.ok(arrived > 0 && back - arrived > 1, `between arriving (tick ${ticks[arrived]?.k}) and breathing (tick ${u.k}) the feet land and the keeper turns`);
+    }
+
     // 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.