@ludra/cli 0.5.0 → 0.8.0

package/templates/breakout/scripts/backdrop.ts

@@ -0,0 +1,101 @@
+import type { Script } from "@ludra/core";
+
+/** A stable pseudo-random number per index, so the stars don't jump between frames. */
+function hash(n: number): number {
+  const x = Math.sin(n * 127.1 + 311.7) * 43758.5453;
+  return x - Math.floor(x);
+}
+
+/**
+ * The synthwave sky behind the game: stars, a striped sun on the horizon and a
+ * neon grid rolling toward the player. Presentation only.
+ */
+export default {
+  draw({ g, world, time }) {
+    const w = world.width;
+    const h = world.height;
+    const horizon = h * 0.64;
+
+    const sky = g.createLinearGradient(0, 0, 0, horizon);
+    sky.addColorStop(0, "#05001a");
+    sky.addColorStop(0.7, "#1b0045");
+    sky.addColorStop(1, "#4a0063");
+    g.fillStyle = sky;
+    g.fillRect(0, 0, w, horizon);
+
+    for (let i = 0; i < 110; i++) {
+      const size = i % 13 === 0 ? 2 : 1;
+      g.globalAlpha = 0.25 + 0.65 * Math.abs(Math.sin(time * (0.6 + hash(i) * 1.6) + i));
+      g.fillStyle = i % 5 === 0 ? "#ff9de2" : "#d6ecff";
+      g.fillRect(hash(i * 2 + 1) * w, hash(i * 3 + 7) * horizon * 0.9, size, size);
+    }
+    g.globalAlpha = 1;
+
+    // The sun: a warm glow, then a disc cut by bands that drift down like a VHS sunset.
+    const glow = g.createRadialGradient(w / 2, horizon, 20, w / 2, horizon, 330);
+    glow.addColorStop(0, "rgba(255, 60, 140, 0.55)");
+    glow.addColorStop(1, "rgba(255, 60, 140, 0)");
+    g.globalCompositeOperation = "lighter";
+    g.fillStyle = glow;
+    g.fillRect(0, 0, w, horizon);
+    g.globalCompositeOperation = "source-over";
+
+    const radius = 120;
+    const sun = g.createLinearGradient(0, horizon - radius, 0, horizon);
+    sun.addColorStop(0, "#ffe66d");
+    sun.addColorStop(0.55, "#ff7a3d");
+    sun.addColorStop(1, "#ff2a6d");
+    g.save();
+    g.beginPath();
+    g.arc(w / 2, horizon, radius, Math.PI, 0);
+    g.clip();
+    g.globalAlpha = 0.85;
+    g.fillStyle = sun;
+    g.fillRect(w / 2 - radius, horizon - radius, radius * 2, radius);
+    g.globalAlpha = 1;
+    g.fillStyle = sky;
+    for (let i = 0; i < 7; i++) {
+      const t = (i + ((time * 0.35) % 1)) / 7;
+      g.fillRect(w / 2 - radius, horizon - radius * 0.55 + t * radius * 0.55, radius * 2, 1 + t * 7);
+    }
+    g.restore();
+
+    // The floor grid.
+    const floor = g.createLinearGradient(0, horizon, 0, h);
+    floor.addColorStop(0, "#14002e");
+    floor.addColorStop(1, "#020008");
+    g.fillStyle = floor;
+    g.fillRect(0, horizon, w, h - horizon);
+
+    g.strokeStyle = "#ff2a6d";
+    g.shadowColor = "#ff2a6d";
+    g.shadowBlur = 10;
+    g.lineWidth = 1.5;
+    const rows = 12;
+    for (let i = 0; i < rows; i++) {
+      const t = (i + ((time * 0.8) % 1)) / rows;
+      const y = horizon + (h - horizon) * t * t;
+      g.globalAlpha = 0.15 + t * 0.75;
+      g.beginPath();
+      g.moveTo(0, y);
+      g.lineTo(w, y);
+      g.stroke();
+    }
+    g.globalAlpha = 0.55;
+    for (let j = -12; j <= 12; j++) {
+      g.beginPath();
+      g.moveTo(w / 2 + j * 10, horizon);
+      g.lineTo(w / 2 + j * 150, h);
+      g.stroke();
+    }
+
+    // The horizon line itself, bright.
+    g.globalAlpha = 1;
+    g.strokeStyle = "#ff8fd8";
+    g.shadowBlur = 18;
+    g.beginPath();
+    g.moveTo(0, horizon);
+    g.lineTo(w, horizon);
+    g.stroke();
+  },
+} satisfies Script;

package/templates/breakout/scripts/ball.ts

@@ -0,0 +1,89 @@
+import type { Script } from "@ludra/core";
+
+interface Params {
+  /** Ball speed in px/s, kept constant. */
+  speed: number;
+  /** Seconds the ball rests on the paddle before launching. */
+  launchDelay: number;
+  /** Id of the paddle. */
+  paddle: string;
+}
+
+/**
+ * Rests on the paddle, launches, and keeps a constant speed (bounce: 1 does
+ * the reflecting). Falling past the bottom costs a life: the paddle "dies"
+ * (a die event, or game over on the last ball) and the ball goes back onto it.
+ */
+export default {
+  start({ self, world, params }) {
+    self.state.stuck = true;
+    self.state.launchAt = world.time + (params.launchDelay as number);
+  },
+  update({ self, world, params }) {
+    const { speed, launchDelay, paddle: paddleId } = params as unknown as Params;
+    const paddle = world.get(paddleId);
+    if (!paddle) return;
+
+    if (self.state.stuck) {
+      self.x = paddle.x;
+      self.y = paddle.y - paddle.height / 2 - self.height / 2 - 1;
+      self.vx = 0;
+      self.vy = 0;
+      if (world.time >= (self.state.launchAt as number)) {
+        self.state.stuck = false;
+        self.vx = speed * 0.5;
+        self.vy = -speed * 0.866;
+        world.emit("launch");
+      }
+      return;
+    }
+
+    if (self.y > world.height + 30) {
+      world.kill(paddle);
+      self.state.stuck = true;
+      self.state.launchAt = world.time + launchDelay;
+      return;
+    }
+
+    // Never travel almost horizontally (it would take forever to come back), and keep the speed constant.
+    const minVertical = speed * 0.35;
+    if (Math.abs(self.vy) < minVertical) self.vy = (self.vy < 0 ? -1 : 1) * minVertical;
+    const current = Math.hypot(self.vx, self.vy);
+    if (current > 0) {
+      self.vx = (self.vx / current) * speed;
+      self.vy = (self.vy / current) * speed;
+    }
+  },
+  /** A white-hot core in a golden halo, trailing a comet tail. */
+  draw({ g, self, local }) {
+    const trail = (local.trail ??= []) as Array<{ x: number; y: number }>;
+    const last = trail.at(-1);
+    // The ball jumped back onto the paddle: don't draw a streak across the screen.
+    if (last && Math.hypot(self.x - last.x, self.y - last.y) > 60) trail.length = 0;
+    trail.push({ x: self.x, y: self.y });
+    if (trail.length > 16) trail.shift();
+
+    g.globalCompositeOperation = "lighter";
+    trail.forEach((p, i) => {
+      const t = (i + 1) / trail.length;
+      g.fillStyle = `rgba(255, ${150 + t * 80}, 40, ${t * 0.3})`;
+      g.beginPath();
+      g.arc(p.x, p.y, 7 * t, 0, Math.PI * 2);
+      g.fill();
+    });
+
+    const halo = g.createRadialGradient(self.x, self.y, 2, self.x, self.y, 30);
+    halo.addColorStop(0, "rgba(255, 214, 10, 0.7)");
+    halo.addColorStop(1, "rgba(255, 120, 10, 0)");
+    g.fillStyle = halo;
+    g.fillRect(self.x - 30, self.y - 30, 60, 60);
+
+    g.globalCompositeOperation = "source-over";
+    g.shadowColor = "#ffd60a";
+    g.shadowBlur = 18;
+    g.fillStyle = "#fffbe6";
+    g.beginPath();
+    g.arc(self.x, self.y, self.width / 2, 0, Math.PI * 2);
+    g.fill();
+  },
+} satisfies Script;

package/templates/breakout/scripts/brick.ts

@@ -0,0 +1,51 @@
+import type { Script } from "@ludra/core";
+
+/** Mixes a #rrggbb color toward white (amount > 0) or black (amount < 0). */
+function shade(hex: string, amount: number): string {
+  const n = parseInt(hex.slice(1), 16);
+  const mix = (c: number) => Math.round(amount > 0 ? c + (255 - c) * amount : c * (1 + amount));
+  return `rgb(${mix(n >> 16)}, ${mix((n >> 8) & 255)}, ${mix(n & 255)})`;
+}
+
+/** Breaks when the ball hits it and adds params.points to the score. Glows in params.color. */
+export default {
+  touch({ self, world, params }, other) {
+    if (other.id !== params.ball) return;
+    world.score += params.points as number;
+    world.emit("brick", { points: params.points, color: params.color });
+    world.destroy(self);
+  },
+  draw({ g, self, params, time }) {
+    const color = params.color as string;
+    const x = self.x - self.width / 2;
+    const y = self.y - self.height / 2;
+    const pulse = 0.7 + 0.3 * Math.sin(time * 3 + self.x * 0.03);
+
+    const body = g.createLinearGradient(0, y, 0, y + self.height);
+    body.addColorStop(0, shade(color, 0.45));
+    body.addColorStop(0.45, color);
+    body.addColorStop(1, shade(color, -0.45));
+    g.shadowColor = color;
+    g.shadowBlur = 22 * pulse;
+    g.fillStyle = body;
+    g.beginPath();
+    g.roundRect(x, y, self.width, self.height, 7);
+    g.fill();
+
+    g.shadowBlur = 0;
+    g.strokeStyle = "rgba(255, 255, 255, 0.65)";
+    g.lineWidth = 2;
+    g.beginPath();
+    g.moveTo(x + 10, y + 5);
+    g.lineTo(x + self.width - 10, y + 5);
+    g.stroke();
+
+    // One pip per point, so the rows read as worth more.
+    g.fillStyle = "rgba(255, 255, 255, 0.85)";
+    for (let i = 0; i < (params.points as number); i++) {
+      g.beginPath();
+      g.arc(x + self.width - 14 - i * 9, y + self.height - 9, 2.5, 0, Math.PI * 2);
+      g.fill();
+    }
+  },
+} satisfies Script;

package/templates/breakout/scripts/paddle.ts

@@ -0,0 +1,53 @@
+import type { Script } from "@ludra/core";
+
+/**
+ * Aims the ball by where it hits the paddle: the center sends it straight up,
+ * the edges send it off at a steep angle, which is what makes breakout skillful.
+ */
+export default {
+  touch({ self, world, params }, other) {
+    if (other.id !== params.ball) return;
+    const offset = Math.max(-1, Math.min(1, (other.x - self.x) / (self.width / 2)));
+    const speed = Math.hypot(other.vx, other.vy) || 1;
+    other.vx = offset * speed * 0.8;
+    other.vy = -Math.sqrt(speed * speed - other.vx * other.vx);
+    world.emit("paddle-hit");
+  },
+  draw({ g, self, time, recent }) {
+    const hit = recent("paddle-hit", 0.3).at(-1);
+    const flash = hit ? 1 - (time - hit.time) / 0.3 : 0;
+    const x = self.x - self.width / 2;
+    const y = self.y - self.height / 2;
+
+    // Light spilling onto the floor under the paddle.
+    const spill = g.createRadialGradient(self.x, self.y + 14, 4, self.x, self.y + 14, 90);
+    spill.addColorStop(0, `rgba(0, 240, 255, ${0.35 + flash * 0.4})`);
+    spill.addColorStop(1, "rgba(0, 240, 255, 0)");
+    g.globalCompositeOperation = "lighter";
+    g.fillStyle = spill;
+    g.fillRect(self.x - 100, self.y - 20, 200, 60);
+    g.globalCompositeOperation = "source-over";
+
+    const body = g.createLinearGradient(0, y, 0, y + self.height);
+    body.addColorStop(0, "#e6ffff");
+    body.addColorStop(0.4, "#2ee6ff");
+    body.addColorStop(1, "#006c9e");
+    g.shadowColor = flash > 0 ? "#ffffff" : "#00f0ff";
+    g.shadowBlur = 24 + flash * 30;
+    g.fillStyle = body;
+    g.beginPath();
+    g.roundRect(x, y, self.width, self.height, self.height / 2);
+    g.fill();
+
+    // Magenta emitters at both ends, breathing.
+    g.shadowColor = "#ff2a6d";
+    g.shadowBlur = 14;
+    g.fillStyle = "#ff5c9d";
+    const breathe = 3.5 + Math.sin(time * 5) * 0.8;
+    for (const ex of [x + 10, x + self.width - 10]) {
+      g.beginPath();
+      g.arc(ex, self.y, breathe, 0, Math.PI * 2);
+      g.fill();
+    }
+  },
+} satisfies Script;

package/templates/breakout/scripts/rules.ts

@@ -0,0 +1,147 @@
+import type { DrawContext, Script } from "@ludra/core";
+
+const FONT = "Orbitron, system-ui, sans-serif";
+
+/** Text with a neon glow: a blurred colored pass, then a crisp light core. */
+function neonText(g: DrawContext["g"], text: string, x: number, y: number, size: number, color: string, weight = 900): void {
+  g.font = `${weight} ${size}px ${FONT}`;
+  g.shadowColor = color;
+  g.shadowBlur = size * 0.6;
+  g.fillStyle = color;
+  g.fillText(text, x, y);
+  g.shadowBlur = size * 0.15;
+  g.fillStyle = "#ffffff";
+  g.globalAlpha *= 0.85;
+  g.fillText(text, x, y);
+  g.globalAlpha /= 0.85;
+}
+
+/**
+ * The level is won when no bricks are left (entities whose id starts with
+ * params.prefix). Also draws the brick-break feedback and the whole interface.
+ */
+export default {
+  start({ self, world, params }) {
+    self.state.total = world.all("script").filter((e) => e.id.startsWith(params.prefix as string)).length;
+  },
+  update({ self, world, params }) {
+    const left = world.all("script").filter((e) => e.id.startsWith(params.prefix as string)).length;
+    self.state.bricksLeft = left;
+    if (left === 0) world.win();
+  },
+
+  /** Shockwaves, colored shards and "+3" popups where bricks break. */
+  draw({ g, time, recent, burst, local }) {
+    for (const hit of recent("brick", 0.9)) {
+      const { points, color } = hit.data as { points: number; color: string };
+      // Burst once per break: the hook runs every rendered frame.
+      if (hit.time > ((local.lastBurst as number) ?? -1)) {
+        burst(hit.x, hit.y, { count: 26, color, speed: 240, life: 0.6, size: 3, gravity: 500, spread: 360 });
+        local.lastBurst = hit.time;
+      }
+      const age = (time - hit.time) / 0.9;
+      g.globalCompositeOperation = "lighter";
+      g.strokeStyle = color;
+      g.shadowColor = color;
+      g.shadowBlur = 20;
+      g.lineWidth = 4 * (1 - age);
+      g.globalAlpha = 1 - age;
+      g.beginPath();
+      g.ellipse(hit.x, hit.y, 20 + age * 90, 10 + age * 40, 0, 0, Math.PI * 2);
+      g.stroke();
+      g.textAlign = "center";
+      neonText(g, `+${points}`, hit.x, hit.y - 10 - age * 50, 22, color);
+      g.globalAlpha = 1;
+    }
+  },
+
+  drawUI({ g, self, world, view, time, recent }) {
+    const total = (self.state.total as number) ?? 0;
+    const left = (self.state.bricksLeft as number) ?? total;
+
+    // A red flash from the edges when the ball is lost.
+    const lost = recent("die", 0.7).at(-1);
+    if (lost) {
+      const strength = 1 - (time - lost.time) / 0.7;
+      const edge = g.createRadialGradient(view.width / 2, view.height / 2, view.height * 0.3, view.width / 2, view.height / 2, view.width * 0.7);
+      edge.addColorStop(0, "rgba(255, 0, 60, 0)");
+      edge.addColorStop(1, `rgba(255, 0, 60, ${0.6 * strength})`);
+      g.fillStyle = edge;
+      g.fillRect(0, 0, view.width, view.height);
+    }
+
+    g.textAlign = "left";
+    g.font = `700 11px ${FONT}`;
+    g.fillStyle = "rgba(255, 180, 230, 0.75)";
+    g.fillText("SCORE", 36, 44);
+    neonText(g, String(world.score).padStart(3, "0"), 36, 74, 28, "#ff2a6d");
+
+    // Bricks left as a segmented meter.
+    g.textAlign = "right";
+    g.font = `700 11px ${FONT}`;
+    g.fillStyle = "rgba(180, 250, 255, 0.75)";
+    g.fillText(`BRICKS ${left}/${total}`, view.width - 36, 44);
+    const segments = Math.max(1, total);
+    const meterWidth = 168;
+    for (let i = 0; i < segments; i++) {
+      const on = i < left;
+      g.fillStyle = on ? "#00f0ff" : "rgba(0, 240, 255, 0.15)";
+      g.shadowColor = "#00f0ff";
+      g.shadowBlur = on ? 10 : 0;
+      g.fillRect(view.width - 36 - meterWidth + (i * meterWidth) / segments, 54, meterWidth / segments - 2, 10);
+    }
+    g.shadowBlur = 0;
+
+    // Balls left, as glowing dots under the meter.
+    for (let i = 0; i < (world.lives ?? 0); i++) {
+      g.fillStyle = "#ffd60a";
+      g.shadowColor = "#ffd60a";
+      g.shadowBlur = 10;
+      g.beginPath();
+      g.arc(view.width - 42 - i * 18, 84, 5, 0, Math.PI * 2);
+      g.fill();
+    }
+    g.shadowBlur = 0;
+
+    g.textAlign = "center";
+    if (time < 2.5 && !world.won) {
+      g.globalAlpha = Math.min(1, 2.5 - time) * (0.6 + 0.4 * Math.sin(time * 6));
+      neonText(g, "◄  ►   MOVE", view.width / 2, view.height - 70, 16, "#00f0ff", 700);
+      g.globalAlpha = 1;
+    }
+    g.font = `700 10px ${FONT}`;
+    g.fillStyle = "rgba(255, 255, 255, 0.35)";
+    g.fillText("M SOUND  ·  R RESTART", view.width / 2, view.height - 14);
+
+    if (world.won) {
+      const win = recent("win", 1e9).at(-1);
+      const since = win ? time - win.time : 0;
+      g.fillStyle = `rgba(5, 0, 20, ${Math.min(0.7, since * 1.4)})`;
+      g.fillRect(0, 0, view.width, view.height);
+      // A neon sign flickering on.
+      const flicker = since < 0.6 && Math.sin(since * 70) > 0.2 ? 0.25 : 1;
+      g.globalAlpha = Math.min(1, since * 2) * flicker;
+      neonText(g, "WALL CLEARED", view.width / 2, view.height / 2 - 6, 64, "#ff2a6d");
+      g.globalAlpha = Math.min(1, Math.max(0, since * 2 - 0.6));
+      neonText(g, `SCORE ${world.score}   ·   ${(win?.time ?? time).toFixed(1)}s`, view.width / 2, view.height / 2 + 44, 20, "#00f0ff", 700);
+      g.font = `700 12px ${FONT}`;
+      g.fillStyle = "rgba(255, 255, 255, 0.6)";
+      g.fillText("PRESS R TO PLAY AGAIN", view.width / 2, view.height / 2 + 84);
+      g.globalAlpha = 1;
+    }
+
+    if (world.lost) {
+      const over = recent("gameover", 1e9).at(-1);
+      const since = over ? time - over.time : 0;
+      g.fillStyle = `rgba(20, 0, 10, ${Math.min(0.75, since * 1.5)})`;
+      g.fillRect(0, 0, view.width, view.height);
+      g.globalAlpha = Math.min(1, since * 2);
+      neonText(g, "GAME OVER", view.width / 2, view.height / 2 - 6, 64, "#ff2a6d");
+      neonText(g, `${left} BRICK${left === 1 ? "" : "S"} TO GO   ·   SCORE ${world.score}`, view.width / 2, view.height / 2 + 44, 20, "#00f0ff", 700);
+      g.font = `700 12px ${FONT}`;
+      g.fillStyle = "rgba(255, 255, 255, 0.6)";
+      g.fillText("PRESS R TO TRY AGAIN", view.width / 2, view.height / 2 + 84);
+      g.globalAlpha = 1;
+    }
+  },
+} satisfies Script;

package/templates/breakout/scripts/wall.ts

@@ -0,0 +1,21 @@
+import type { Script } from "@ludra/core";
+
+/** A dark wall with a neon tube along it. */
+export default {
+  draw({ g, self, time }) {
+    const x = self.x - self.width / 2;
+    const y = self.y - self.height / 2;
+    g.fillStyle = "#0a0020";
+    g.fillRect(x, y, self.width, self.height);
+
+    g.strokeStyle = "#00f0ff";
+    g.shadowColor = "#00f0ff";
+    g.shadowBlur = 16 + Math.sin(time * 2) * 4;
+    g.lineWidth = 3;
+    g.strokeRect(x + 4, y + 4, self.width - 8, self.height - 8);
+    g.shadowBlur = 0;
+    g.strokeStyle = "rgba(220, 255, 255, 0.8)";
+    g.lineWidth = 1;
+    g.strokeRect(x + 4, y + 4, self.width - 8, self.height - 8);
+  },
+} satisfies Script;

package/templates/breakout/shaders/neon.frag

@@ -0,0 +1,42 @@
+// Neon CRT: bloom on bright pixels, chromatic aberration toward the edges,
+// scanlines, a slight tube curve 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.
+
+vec3 sampleAt(vec2 uv) {
+  return texture2D(u_image, uv).rgb;
+}
+
+void main() {
+  vec2 centered = v_uv - 0.5;
+  vec2 uv = 0.5 + centered * (1.0 + curve * dot(centered, centered));
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
+    gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0);
+    return;
+  }
+
+  vec2 pixel = 1.0 / u_resolution;
+  vec2 shift = centered * aberration * pixel * 6.0;
+  vec3 color = vec3(sampleAt(uv + shift).r, sampleAt(uv).g, sampleAt(uv - shift).b);
+
+  // Bloom: a Gaussian-weighted average of the bright parts around this pixel.
+  // 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(sampleAt(uv + vec2(float(i), float(j)) * pixel * 2.0) - 0.5, 0.0) * weight;
+      total += weight;
+    }
+  }
+  color += glow / total * bloom;
+
+  float line = 0.5 + 0.5 * sin(gl_FragCoord.y * 3.14159);
+  color *= 1.0 - scanlines * line * 0.35;
+  color *= 1.0 - vignette * dot(centered, centered) * 1.8;
+  // A barely visible flicker, like a tube.
+  color *= 0.985 + 0.015 * sin(u_time * 50.0);
+
+  gl_FragColor = vec4(color, 1.0);
+}

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

@@ -0,0 +1,31 @@
+{
+  "tests": [
+    {
+      "name": "the ball rests on the paddle, then launches",
+      "duration": "0.5s",
+      "assert": ["ball.vy == 0", "ball.x == 480", "events.launch == 0"]
+    },
+    {
+      "name": "the ball launches upward and breaks a brick",
+      "duration": "1.5s",
+      "assert": ["events.launch == 1", "events.brick >= 1", "score >= 1"]
+    },
+    {
+      "name": "the paddle only moves sideways and stays inside the walls",
+      "inputs": "right+up:2s",
+      "duration": "2s",
+      "assert": ["paddle.y == 500", "paddle.x == 880"]
+    },
+    {
+      "name": "missing the ball costs a life and puts the ball back on the paddle",
+      "duration": "3s",
+      "assert": ["events.die == 1", "lives == 2", "ball.state.stuck == true"]
+    },
+    {
+      "name": "the wall can be cleared without losing a life",
+      "inputs": "wait:87f, right:48f, wait:56f, left:34f, wait:71f, left:29f, wait:73f, left:3f, wait:98f, left:24f, wait:84f, right:23f, wait:92f, right:36f, wait:72f, left:8f, wait:112f, right:17f, left:2f, wait:108f, left:22f, wait:92f, left:22f, wait:86f, left:26f, wait:75f, right:8f, wait:115f, right:17f, wait:141f, right:10f",
+      "duration": "30s",
+      "assert": ["won == true", "deaths == 0", "rules.state.bricksLeft == 0", "score == 42"]
+    }
+  ]
+}

package/templates/platformer/CLAUDE.md

@@ -1,24 +1,27 @@
 # {{name}}
 
-A game built with Ludra, a game engine designed for AI agents.
+A platformer built with Ludra, a game engine designed for AI agents: two levels, Night Meadow and Moonlit Cliffs.
 
 ## Layout
 
 - `ludra.json`: project config (name, entry scene, window size)
-- `scenes/main.scene.json`: the level. Entities are made of components; `effects` adds particles, sound and shake to game events.
+- `scenes/main.scene.json`: level 1 (the entry scene). Its flag's `next` leads to `scenes/level-2.scene.json`. Entities are made of components; `effects` adds particles, sound and shake to game events.
+- `prefabs/`: `coin` and `slime`, reused by both levels. An entity says `"prefab": "slime"` and lists only what differs.
 - `assets/`: SVG art. Spritesheets are frames side by side; tiles repeat.
-- `scripts/`: custom game logic in TypeScript (create it when needed). Run `npx @ludra/cli components script` for the API.
-- `tests/*.test.json`: gameplay tests, run headlessly
+- `scripts/`: `backdrop.ts` (the night sky and parallax hills), `lantern.ts` (lights a reached checkpoint), `hud.ts` (hearts, points, title card, end screens). Run `npx @ludra/cli components script` for the API.
+- `shaders/glow.frag`: the finishing shader (bloom, grade, vignette).
+- `tests/*.test.json`: gameplay tests, run headlessly. Tests for level 2 say `"scene": "scenes/level-2.scene.json"`.
 
 ## Loop
 
-1. Edit `scenes/main.scene.json`. Run `npx @ludra/cli components` for every component and field.
+1. Edit `scenes/main.scene.json`. Run `npx @ludra/cli components` for every component and field, and `npx @ludra/cli blocks` for ready-made pieces you can drop in with `npx @ludra/cli add <block> --at x,y`.
 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, jump:0.4s" --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
 
@@ -27,6 +30,8 @@ Never call a change done until `ludra check` and `ludra test` both pass.
 - Collectibles, hazards and goals need `"sensor": true` on their body.
 - Moving platforms and enemies are kinematic bodies with a `patrol`. Players standing on a moving platform are carried.
 - A jump only triggers on a new press, so put a segment without jump between two jump segments.
-- The level is done when a test proves `won == true` with `deaths == 0`.
+- The game has 3 lives (`world.lives`); the lantern is a `checkpoint`, placed where the player already stands before a hard part.
+- A level is done when a test proves `won == true` with `deaths == 0`. Add a level: copy a scene, point the last flag's `next` at it, and give it its own tests.
+- For more than sprites (lighting, glow, your own HUD, fonts, shaders), scripts can have `draw` and `drawUI` hooks with the real Canvas 2D context, and the scene can set `"fonts"` and `"postfx"`. See `npx @ludra/cli components script`.
 - Art and effects never change gameplay. Make it playable first, then dress it. Write new art as SVG in `assets/`.
 - For behavior no component provides (chasing, keys, timers, shooting), write a script and attach it with a `script` component. Use `world.random()`, never `Math.random()`, and test what it does through `self.state` and `world.emit`.

package/templates/platformer/assets/lantern.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="64" viewBox="0 0 24 64">
+  <!-- A checkpoint: a wooden post with an unlit lantern hanging from it. lantern.ts lights it. -->
+  <rect x="10" y="6" width="4" height="58" rx="1.5" fill="#6b4f3a"/>
+  <rect x="10" y="6" width="2" height="58" fill="#80624a"/>
+  <rect x="4" y="6" width="16" height="3" rx="1.5" fill="#5c4332"/>
+  <path d="M6 9 v4" stroke="#cfd8ff" stroke-width="1"/>
+  <rect x="2" y="13" width="8" height="12" rx="2" fill="#2a3150" stroke="#cfd8ff" stroke-width="1.2"/>
+  <rect x="4" y="11" width="4" height="2" rx="1" fill="#cfd8ff"/>
+</svg>

package/templates/platformer/package.json

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

package/templates/platformer/prefabs/coin.prefab.json

@@ -0,0 +1,8 @@
+{
+  "description": "A spinning gold coin worth 1 point. Place it with just a transform.",
+  "components": {
+    "body": { "type": "static", "width": 20, "height": 20, "sensor": true },
+    "sprite": { "shape": "circle", "color": "#ffd166", "image": "assets/coin.svg", "frameWidth": 20, "idle": "0-3", "layer": 1 },
+    "collectible": { "score": 1 }
+  }
+}

package/templates/platformer/prefabs/slime.prefab.json

@@ -0,0 +1,9 @@
+{
+  "description": "A purple slime that walks back and forth; stomp it for a point. Override patrol to change its range and pace.",
+  "components": {
+    "body": { "type": "kinematic", "width": 32, "height": 26, "sensor": true },
+    "sprite": { "color": "#c77dff", "image": "assets/slime.svg", "frameWidth": 32, "idle": "0", "run": "0-1", "fps": 4, "layer": 2 },
+    "patrol": { "axis": "x", "distance": 200, "speed": 70 },
+    "hazard": { "stompable": true, "score": 1 }
+  }
+}