@ludra/cli 0.5.0 → 0.7.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,90 @@
+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"
+ * 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.emit("ball-lost");
+      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,128 @@
+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("ball-lost", 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;
+
+    if (world.deaths > 0) {
+      g.font = `700 11px ${FONT}`;
+      g.fillStyle = "rgba(255, 120, 140, 0.8)";
+      g.fillText(`BALLS LOST ${world.deaths}`, view.width - 36, 84);
+    }
+
+    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;
+    }
+  },
+} 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.ball-lost == 1", "deaths == 1", "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

@@ -12,7 +12,7 @@ A game built with Ludra, a game engine designed for AI agents.
 
 ## 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`.
@@ -28,5 +28,6 @@ Never call a change done until `ludra check` and `ludra test` both pass.
 - 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`.
+- 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/package.json

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

package/templates/topdown/CLAUDE.md

@@ -0,0 +1,38 @@
+# {{name}}
+
+A top-down game built with Ludra, a game engine designed for AI agents.
+
+## Layout
+
+- `ludra.json`: project config (name, entry scene, window size)
+- `scenes/main.scene.json`: the level, seen from above. Entities are made of components; `effects` adds particles, sound and shake to game events.
+- `assets/`: SVG art. Spritesheets are frames side by side; tiles repeat.
+- `scripts/`: TypeScript. `night.ts` draws the darkness, the lantern, colored lights and fireflies; `portal.ts` the vortex; `hud.ts` the whole interface. Run `npx @ludra/cli components script` for the API.
+- `shaders/dream.frag`: the post-processing shader (bloom, warm/cool grade, vignette).
+- `tests/*.test.json`: gameplay tests, run headlessly
+
+## Loop
+
+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, 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.
+
+Never call a change done until `ludra check` and `ludra test` both pass.
+
+## Rules of thumb
+
+- Coordinates are entity centers in pixels; +y is down. The world has no gravity (`"gravity": 0`).
+- The hero uses `topdown`: arrow keys move it in 8 directions at `speed` px/s. Inputs like `"right+up:0.5s"` move diagonally. A `dynamic` body collides with walls.
+- Walls are `static` bodies. Hazards, collectibles and goals need `"sensor": true`.
+- Enemies are kinematic sensor bodies with a `patrol` (`axis` "x" or "y") and a `hazard`. In top-down games they can't be stomped.
+- A floor is an entity with only a tiled `sprite` (no body) on `layer` -1, sized to the world.
+- The level is done when a test proves `won == true` with `deaths == 0`, and every enemy crossing works across a wide timing window (sweep `wait:` values with `play`).
+- Art and effects never change gameplay. Make it playable first, then dress it. Write new art as SVG in `assets/`.
+
+## Looks
+
+The sprites are SVG; the mood comes from code. `night.ts` lights the scene (keep every hazard lit in its warning color), and the scene loads the Cinzel font and runs `shaders/dream.frag`.
+
+There are no limits on looks. A script's `draw(ctx)` paints with the real Canvas 2D context (`ctx.g`), `drawUI(ctx)` replaces the HUD, `"fonts"` loads Google Fonts, and `"postfx"` runs a GLSL shader over every frame. Run `npx @ludra/cli components script` for the API. Draw hooks only paint: they can't change the game, so tests stay valid. After every visual change, look at real frames with `play --screenshot`.

package/templates/topdown/_gitignore

@@ -0,0 +1,2 @@
+node_modules/
+screenshots/

package/templates/topdown/assets/gem.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="40" height="20" viewBox="0 0 40 20">
+  <!-- Spritesheet: 2 frames of 20x20, a shimmering crystal. -->
+  <g>
+    <path d="M10 1 L18 8 L10 19 L2 8 Z" fill="#4cc9f0"/>
+    <path d="M10 1 L18 8 L10 8 Z" fill="#a5ecff"/>
+    <path d="M2 8 L10 8 L10 19 Z" fill="#2c8fb5"/>
+    <circle cx="7" cy="6" r="1.2" fill="#ffffff"/>
+  </g>
+  <g transform="translate(20 0)">
+    <path d="M10 1 L18 8 L10 19 L2 8 Z" fill="#7fe0ff"/>
+    <path d="M10 1 L18 8 L10 8 Z" fill="#e0faff"/>
+    <path d="M2 8 L10 8 L10 19 Z" fill="#3aa6c8"/>
+    <circle cx="13" cy="5" r="1.4" fill="#ffffff"/>
+    <circle cx="7" cy="12" r="0.8" fill="#ffffff"/>
+  </g>
+</svg>

package/templates/topdown/assets/grass.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40">
+  <!-- Tile: soft grass with a few flowers, the floor of the grove. -->
+  <rect width="40" height="40" fill="#2f5a3a"/>
+  <path d="M4 10 l1 -3 l1 3 M22 6 l1 -3 l1 3 M31 24 l1 -3 l1 3 M9 31 l1 -3 l1 3 M17 19 l1 -3 l1 3" stroke="#3f7a4c" stroke-width="1.2" fill="none"/>
+  <circle cx="28" cy="12" r="1.6" fill="#ffd166"/>
+  <circle cx="12" cy="24" r="1.4" fill="#ff9fb2"/>
+  <circle cx="35" cy="35" r="1.2" fill="#cfd8ff"/>
+</svg>

package/templates/topdown/assets/hedge.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+  <!-- Tile: a dense hedge, seen from above. Walls of the grove. -->
+  <rect width="20" height="20" fill="#2d6a3e"/>
+  <circle cx="5" cy="5" r="5" fill="#3f8a50"/>
+  <circle cx="15" cy="6" r="5" fill="#357a46"/>
+  <circle cx="10" cy="14" r="6" fill="#3f8a50"/>
+  <circle cx="4" cy="4" r="1.6" fill="#5fbf6a"/>
+  <circle cx="13" cy="12" r="1.8" fill="#5fbf6a"/>
+  <circle cx="17" cy="17" r="1" fill="#1f4d2c"/>
+</svg>

package/templates/topdown/assets/hero.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="24" viewBox="0 0 48 24">
+  <!-- Spritesheet: 2 frames of 24x24, a hooded explorer seen from above, facing right. -->
+  <g>
+    <ellipse cx="12" cy="20" rx="8" ry="3" fill="#0f2418" opacity="0.5"/>
+    <rect x="6" y="17" width="5" height="5" rx="2" fill="#3f5a8a"/>
+    <rect x="13" y="17" width="5" height="5" rx="2" fill="#3f5a8a"/>
+    <circle cx="12" cy="12" r="8" fill="#ff9f68"/>
+    <path d="M4 12 a8 8 0 0 1 16 0 l-3 -1 a5 5 0 0 0 -10 0 z" fill="#e8613c"/>
+    <circle cx="14.5" cy="12" r="1.6" fill="#1d2333"/>
+    <circle cx="18" cy="12" r="1.6" fill="#1d2333"/>
+    <rect x="2" y="9" width="3" height="7" rx="1.5" fill="#c2492a"/>
+  </g>
+  <g transform="translate(24 0)">
+    <ellipse cx="12" cy="20" rx="8" ry="3" fill="#0f2418" opacity="0.5"/>
+    <rect x="5" y="16" width="5" height="5" rx="2" fill="#3f5a8a"/>
+    <rect x="14" y="18" width="5" height="5" rx="2" fill="#3f5a8a"/>
+    <circle cx="12" cy="11" r="8" fill="#ff9f68"/>
+    <path d="M4 11 a8 8 0 0 1 16 0 l-3 -1 a5 5 0 0 0 -10 0 z" fill="#e8613c"/>
+    <circle cx="14.5" cy="11" r="1.6" fill="#1d2333"/>
+    <circle cx="18" cy="11" r="1.6" fill="#1d2333"/>
+    <rect x="2" y="8" width="3" height="7" rx="1.5" fill="#c2492a"/>
+  </g>
+</svg>