@ludra/cli 0.7.0 → 0.8.0

package/templates/platformer/scripts/hud.ts

@@ -0,0 +1,111 @@
+import type { DrawContext, Script } from "@ludra/core";
+
+const FONT = "Fredoka, system-ui, sans-serif";
+
+/** Text with a soft dark outline, so it reads over the sky and the ground alike. */
+function label(g: DrawContext["g"], text: string, x: number, y: number, size: number, color = "#fff7e6", weight = 600): void {
+  g.font = `${weight} ${size}px ${FONT}`;
+  g.lineJoin = "round";
+  g.lineWidth = size * 0.22;
+  g.strokeStyle = "rgba(14, 18, 40, 0.85)";
+  g.strokeText(text, x, y);
+  g.fillStyle = color;
+  g.fillText(text, x, y);
+}
+
+function star(g: DrawContext["g"], x: number, y: number, r: number): void {
+  g.beginPath();
+  for (let i = 0; i < 10; i++) {
+    const angle = -Math.PI / 2 + (i * Math.PI) / 5;
+    const radius = i % 2 === 0 ? r : r * 0.45;
+    g.lineTo(x + Math.cos(angle) * radius, y + Math.sin(angle) * radius);
+  }
+  g.closePath();
+  g.fillStyle = "#ffd166";
+  g.shadowColor = "#ffb347";
+  g.shadowBlur = 10;
+  g.fill();
+  g.shadowBlur = 0;
+}
+
+function heart(g: DrawContext["g"], x: number, y: number, size: number, full: boolean): void {
+  g.beginPath();
+  g.moveTo(x, y + size * 0.3);
+  g.bezierCurveTo(x, y - size * 0.2, x - size, y - size * 0.2, x - size, y + size * 0.3);
+  g.bezierCurveTo(x - size, y + size * 0.75, x, y + size, x, y + size * 1.2);
+  g.bezierCurveTo(x, y + size, x + size, y + size * 0.75, x + size, y + size * 0.3);
+  g.bezierCurveTo(x + size, y - size * 0.2, x, y - size * 0.2, x, y + size * 0.3);
+  g.fillStyle = full ? "#ff5d73" : "rgba(255, 255, 255, 0.18)";
+  g.fill();
+}
+
+/**
+ * The interface: hearts for lives, points (coins and stomps), a title card for the level
+ * (params.title, params.level) and the end screens. A won level with a next
+ * scene says so; the last one celebrates the whole run.
+ */
+export default {
+  drawUI({ g, world, view, time, recent, params }) {
+    // Lives: a heart pops when one is lost.
+    const hurt = recent("die", 0.4).at(-1);
+    const maxLives = Math.max(world.lives ?? 0, params.lives as number);
+    for (let i = 0; i < maxLives; i++) {
+      const full = i < (world.lives ?? 0);
+      const pop = !full && hurt && i === world.lives ? 1 + 0.6 * (1 - (time - hurt.time) / 0.4) : 1;
+      heart(g, 34 + i * 30, 22, 9 * pop, full);
+    }
+
+    // Points, with a hop whenever some are earned.
+    const got = [...recent("collect", 0.3), ...recent("stomp", 0.3)].sort((a, b) => a.time - b.time).at(-1);
+    const bounce = got ? Math.sin(((time - got.time) / 0.3) * Math.PI) * 6 : 0;
+    star(g, 35, 61 - bounce, 11);
+    g.textAlign = "left";
+    label(g, `${world.score}`, 54, 68 - bounce * 0.5, 22);
+
+    // Title card.
+    if (time < 2.6 && !world.won) {
+      g.globalAlpha = Math.min(1, (2.6 - time) / 0.8);
+      g.textAlign = "center";
+      label(g, `Level ${params.level}`, view.width / 2, view.height / 2 - 46, 20, "#ffd166");
+      label(g, String(params.title), view.width / 2, view.height / 2, 52, "#fff7e6", 700);
+      g.globalAlpha = 1;
+    }
+
+    // A checkpoint caught: a short note under the hearts.
+    const saved = recent("checkpoint", 1.6).at(-1);
+    if (saved) {
+      g.globalAlpha = Math.min(1, (1.6 - (time - saved.time)) / 0.5);
+      g.textAlign = "left";
+      label(g, "Checkpoint!", 24, 100, 16, "#ffd166");
+      g.globalAlpha = 1;
+    }
+
+    g.textAlign = "right";
+    label(g, "M sound  ·  R restart", view.width - 20, view.height - 16, 12, "rgba(255, 247, 230, 0.55)", 500);
+
+    const end = recent(world.won ? "win" : "gameover", 1e9).at(-1);
+    if (world.won || world.lost) {
+      const since = end ? time - end.time : 0;
+      g.fillStyle = `rgba(10, 12, 30, ${Math.min(0.6, since)})`;
+      g.fillRect(0, 0, view.width, view.height);
+      g.globalAlpha = Math.min(1, since * 2);
+      g.textAlign = "center";
+      // Each line rises into place.
+      const rise = Math.max(0, 1 - since * 2.5) * 20;
+      if (world.lost) {
+        label(g, "Game over", view.width / 2, view.height / 2 - 6 + rise, 56, "#ff8fa0", 700);
+        label(g, `${world.score} point${world.score === 1 ? "" : "s"} this run`, view.width / 2, view.height / 2 + 34 + rise, 20);
+        label(g, "Press R to start over", view.width / 2, view.height / 2 + 68 + rise, 15, "rgba(255, 247, 230, 0.7)", 500);
+      } else if (world.exit !== undefined) {
+        label(g, "Level clear!", view.width / 2, view.height / 2 - 6 + rise, 56, "#7cf29c", 700);
+        label(g, "On to the next one…", view.width / 2, view.height / 2 + 34 + rise, 20);
+      } else {
+        label(g, "You made it home!", view.width / 2, view.height / 2 - 6 + rise, 56, "#7cf29c", 700);
+        const falls = world.deaths === 0 ? "without a single fall" : `with ${world.deaths} fall${world.deaths === 1 ? "" : "s"}`;
+        label(g, `${world.score} points, ${falls}`, view.width / 2, view.height / 2 + 34 + rise, 20);
+        label(g, "Press R to play this level again", view.width / 2, view.height / 2 + 68 + rise, 15, "rgba(255, 247, 230, 0.7)", 500);
+      }
+      g.globalAlpha = 1;
+    }
+  },
+} satisfies Script;

package/templates/platformer/scripts/lantern.ts

@@ -0,0 +1,35 @@
+import type { Script } from "@ludra/core";
+
+/**
+ * Lights the checkpoint's lantern once the player has touched it: a flickering
+ * flame and warm light on the grass, so players can see where they'll respawn.
+ */
+export default {
+  draw({ g, self, time, recent }) {
+    const lit = recent("checkpoint", 1e9).find((e) => (e.data as { checkpoint: string }).checkpoint === self.id);
+    // The lantern hangs at the top left of the post.
+    const x = self.x - 6;
+    const y = self.y - self.height / 2 + 19;
+    if (!lit) return;
+
+    const since = time - lit.time;
+    const flicker = 1 + Math.sin(time * 13) * 0.06 + Math.sin(time * 7.7) * 0.05;
+    // A burst of light when it first catches, settling into a steady glow.
+    const flare = Math.max(0, 1 - since * 1.5);
+    const radius = (70 + flare * 60) * flicker;
+    g.globalCompositeOperation = "lighter";
+    const light = g.createRadialGradient(x, y, 2, x, y, radius);
+    light.addColorStop(0, `rgba(255, 200, 110, ${0.55 + flare * 0.3})`);
+    light.addColorStop(1, "rgba(255, 160, 60, 0)");
+    g.fillStyle = light;
+    g.fillRect(x - radius, y - radius, radius * 2, radius * 2);
+
+    g.globalCompositeOperation = "source-over";
+    g.fillStyle = "#ffd166";
+    g.shadowColor = "#ffb347";
+    g.shadowBlur = 14;
+    g.beginPath();
+    g.ellipse(x, y + 1, 2.5 * flicker, 4 * flicker, 0, 0, Math.PI * 2);
+    g.fill();
+  },
+} satisfies Script;

package/templates/platformer/shaders/glow.frag

@@ -0,0 +1,29 @@
+// A storybook night: soft bloom so the moon, coins and lanterns glow, a gentle
+// blue-shadow / warm-highlight grade, and a vignette.
+// The engine declares u_image, u_resolution, u_time and v_uv, plus every
+// uniform listed under "postfx.uniforms" in the scene.
+
+void main() {
+  vec2 pixel = 1.0 / u_resolution;
+  vec3 color = texture2D(u_image, v_uv).rgb;
+
+  // Gaussian-weighted taps: far taps count less, so thin bright text doesn't leave a dotted grid.
+  vec3 glow = vec3(0.0);
+  float total = 0.0;
+  for (int i = -5; i <= 5; i++) {
+    for (int j = -5; j <= 5; j++) {
+      float weight = exp(-float(i * i + j * j) / 12.0);
+      glow += max(texture2D(u_image, v_uv + vec2(float(i), float(j)) * pixel * 2.0).rgb - 0.55, 0.0) * weight;
+      total += weight;
+    }
+  }
+  color += glow / total * bloom;
+
+  float luma = dot(color, vec3(0.299, 0.587, 0.114));
+  color = mix(color * vec3(0.92, 0.97, 1.1), color * vec3(1.06, 1.0, 0.9), smoothstep(0.25, 0.85, luma) * warmth);
+
+  vec2 centered = v_uv - 0.5;
+  color *= 1.0 - vignette * dot(centered, centered) * 1.4;
+
+  gl_FragColor = vec4(color, 1.0);
+}

package/templates/platformer/tests/gameplay.test.json

@@ -3,34 +3,72 @@
     {
       "name": "player rests on the ground",
       "duration": "1s",
-      "assert": ["player.grounded == true", "player.y == 482", "deaths == 0"]
+      "assert": [
+        "player.grounded == true",
+        "player.y == 482",
+        "deaths == 0"
+      ]
     },
     {
       "name": "player runs right",
       "inputs": "right:1s",
-      "assert": ["player.x > 300 at 1s", "player.grounded == true at 1s"]
+      "assert": [
+        "player.x > 300 at 1s",
+        "player.grounded == true at 1s"
+      ]
     },
     {
       "name": "jumping leaves the ground and lands again",
       "inputs": "wait:0.2s, jump:0.4s",
-      "assert": ["events.jump == 1", "player.y < 400 at 0.5s", "player.grounded == true at end"]
+      "assert": [
+        "events.jump == 1",
+        "player.y < 400 at 0.5s",
+        "player.grounded == true at end"
+      ]
     },
     {
       "name": "spikes kill the player, who respawns at the start",
       "inputs": "right:1.85s",
       "duration": "2s",
-      "assert": ["deaths == 1", "events.die == 1", "player.x < 200"]
+      "assert": [
+        "deaths == 1",
+        "events.die == 1",
+        "player.x < 200",
+        "lives == 2"
+      ]
     },
     {
       "name": "the lift carries the player over the pit",
       "inputs": "right:0.3s, right+jump:0.45s, right:0.85s, right+jump:0.45s, right:0.35s, right+jump:0.45s, right:0.18s",
       "duration": "4s",
-      "assert": ["coin-2.exists == false", "player.grounded == true", "player.x > 860", "deaths == 0"]
+      "assert": [
+        "coin-2.exists == false",
+        "player.grounded == true",
+        "player.x > 860",
+        "deaths == 0"
+      ]
     },
     {
-      "name": "the level can be completed without dying",
+      "name": "Night Meadow can be completed without dying",
       "inputs": "right:0.3s, right+jump:0.45s, right:0.85s, right+jump:0.45s, right:0.35s, right+jump:0.45s, right:0.18s, wait:1.0s, right+jump:0.45s, right:0.3s, wait:0.6s, right+jump:0.45s, right:0.1s, wait:0.6s, right:0.7s, right+jump:0.45s, right:0.2s, right+jump:0.45s, right:1.5s",
-      "assert": ["won == true", "deaths == 0", "score == 4", "events.stomp == 1", "slime.exists == false"]
+      "assert": [
+        "won == true",
+        "deaths == 0",
+        "score == 4",
+        "events.stomp == 1",
+        "slime.exists == false",
+        "events.checkpoint == 1"
+      ]
+    },
+    {
+      "name": "three falls end the game",
+      "inputs": "right:7s",
+      "assert": [
+        "deaths == 3",
+        "lives == 0",
+        "lost == true",
+        "events.gameover == 1"
+      ]
     }
   ]
 }

package/templates/platformer/tests/level-2.test.json

@@ -0,0 +1,49 @@
+{
+  "tests": [
+    {
+      "name": "level 2 starts from the coin and slime prefabs",
+      "scene": "scenes/level-2.scene.json",
+      "inputs": "right:1s",
+      "assert": [
+        "coin-1.exists == false",
+        "score == 1",
+        "slime-1.x > 380"
+      ]
+    },
+    {
+      "name": "the first slime can be stomped across a wide window",
+      "scene": "scenes/level-2.scene.json",
+      "inputs": "right:1s, wait:0.6s, right+jump:0.45s, right:0.5s",
+      "assert": [
+        "events.stomp == 1",
+        "slime-1.exists == false",
+        "deaths == 0"
+      ]
+    },
+    {
+      "name": "after the lantern, a fall respawns the player there",
+      "scene": "scenes/level-2.scene.json",
+      "inputs": "right:1s, wait:0.73s, right+jump:0.45s, right:0.7s, wait:0.1s, right+jump:0.45s, right:0.3s, wait:0.1s, right:1.8s",
+      "duration": "7s",
+      "assert": [
+        "events.checkpoint == 1",
+        "deaths == 1",
+        "lives == 2",
+        "player.x == 760",
+        "player.grounded == true"
+      ]
+    },
+    {
+      "name": "Moonlit Cliffs can be completed without dying",
+      "scene": "scenes/level-2.scene.json",
+      "inputs": "right:1s, wait:0.73s, right+jump:0.45s, right:0.7s, wait:0.1s, right+jump:0.45s, right:0.3s, wait:0.1s, right+jump:0.45s, right:0.2s, wait:0.1s, right:0.3s, right+jump:0.45s, right:0.5s, wait:1.5s, right+jump:0.45s, right:1.5s",
+      "assert": [
+        "won == true",
+        "deaths == 0",
+        "score == 6",
+        "events.stomp == 2",
+        "events.checkpoint == 1"
+      ]
+    }
+  ]
+}

package/templates/topdown/CLAUDE.md

@@ -17,9 +17,10 @@ A top-down game built with Ludra, a game engine designed for AI agents.
 2. Run `npx @ludra/cli check` after every edit. Each problem names the JSON path and a fix.
 3. Run `npx @ludra/cli play --inputs "right:1s, up:0.5s" --ascii` to see what actually happens. Add `--screenshot 0.5s,end` to save real rendered frames to `screenshots/` and look at them.
 4. Write the behavior you want into `tests/*.test.json` and run `npx @ludra/cli test`.
-5. Run `npx @ludra/cli dev` so a human can play it in the browser.
+5. Run `npx @ludra/cli review` and fix every issue it lists: it catches what makes a game feel unfinished (untested mechanics, silent events, the default HUD, flat looks).
+6. Run `npx @ludra/cli dev` so a human can play it in the browser.
 
-Never call a change done until `ludra check` and `ludra test` both pass.
+Never call a change done until `ludra check`, `ludra test` and `ludra review` are all clean.
 
 ## Rules of thumb
 

package/templates/topdown/package.json

@@ -8,6 +8,6 @@
     "test": "ludra test"
   },
   "devDependencies": {
-    "@ludra/cli": "^0.7.0"
+    "@ludra/cli": "^0.8.0"
   }
 }