@ludra/core 0.4.0 → 0.7.0

package/src/assertions.ts

@@ -1,8 +1,8 @@
 import { InputScript } from "./input.ts";
 import { defaultDuration, simulate } from "./simulate.ts";
 import { FIXED_DT, parseDuration, secondsToFrames } from "./time.ts";
-import { EVENT_TYPES, type GameEventType, type SceneDef } from "./types.ts";
-import { World, type GameEvent, type WorldSnapshot } from "./world.ts";
+import { EVENT_TYPES, type SceneDef } from "./types.ts";
+import { World, type GameEvent, type WorldOptions, type WorldSnapshot } from "./world.ts";
 
 const OPERATORS = ["<=", ">=", "==", "!=", "<", ">"] as const;
 type Operator = (typeof OPERATORS)[number];
@@ -15,14 +15,18 @@ type WorldField = (typeof WORLD_FIELDS)[number];
 
 type Subject =
   | { kind: "world"; field: WorldField }
-  | { kind: "events"; type: GameEventType }
-  | { kind: "entity"; id: string; field: EntityField };
+  /** Built-in event types, or custom events fired by scripts with world.emit(name). */
+  | { kind: "events"; name: string; builtin: boolean }
+  | { kind: "entity"; id: string; field: EntityField }
+  | { kind: "state"; id: string; key: string };
+
+type Value = number | boolean | string;
 
 export interface Assertion {
   source: string;
   subject: Subject;
   operator: Operator;
-  expected: number | boolean;
+  expected: Value;
   /** Frame to check at, or "end" for the last frame of the run. */
   at: number | "end";
 }
@@ -30,7 +34,7 @@ export interface Assertion {
 export class AssertionSyntaxError extends Error {}
 
 const EXAMPLES =
-  'Examples: "player.x > 400", "player.grounded == true at 1s", "score >= 3", "won == true", "deaths == 0", "events.jump == 1 at end", "coin1.exists == false".';
+  'Examples: "player.x > 400", "player.grounded == true at 1s", "score >= 3", "won == true", "deaths == 0", "events.jump == 1 at end", "coin1.exists == false", "door.state.open == true", "boss.state.phase == \\"angry\\"", "events.shoot >= 3".';
 
 /** Parses `<subject> <op> <value> [at <time|end>]`. */
 export function parseAssertion(source: string): Assertion {
@@ -39,29 +43,32 @@ export function parseAssertion(source: string): Assertion {
   const [, lhs = "", operator, rhs = "", at] = match;
 
   let subject: Subject;
+  const stateMatch = /^(.+)\.state\.([\w-]+)$/.exec(lhs);
   if ((WORLD_FIELDS as readonly string[]).includes(lhs)) {
     subject = { kind: "world", field: lhs as WorldField };
-  } else if (lhs.startsWith("events.")) {
-    const type = lhs.slice("events.".length);
-    if (!(EVENT_TYPES as readonly string[]).includes(type)) {
-      throw new AssertionSyntaxError(`Unknown event "${type}" in "${source}". Events: ${EVENT_TYPES.join(", ")}.`);
-    }
-    subject = { kind: "events", type: type as GameEventType };
+  } else if (lhs.startsWith("events.") && lhs.length > "events.".length) {
+    const name = lhs.slice("events.".length);
+    subject = { kind: "events", name, builtin: (EVENT_TYPES as readonly string[]).includes(name) };
+  } else if (stateMatch) {
+    subject = { kind: "state", id: stateMatch[1]!, key: stateMatch[2]! };
   } else {
     const dot = lhs.lastIndexOf(".");
     const field = lhs.slice(dot + 1);
     if (dot <= 0 || !(ENTITY_FIELDS as readonly string[]).includes(field)) {
       throw new AssertionSyntaxError(
-        `"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<${EVENT_TYPES.join("|")}> or <entityId>.<${ENTITY_FIELDS.join("|")}>.`,
+        `"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<name>, <entityId>.<${ENTITY_FIELDS.join("|")}> or <entityId>.state.<key>.`,
       );
     }
     subject = { kind: "entity", id: lhs.slice(0, dot), field: field as EntityField };
   }
 
-  let expected: number | boolean;
+  let expected: Value;
   if (rhs === "true" || rhs === "false") expected = rhs === "true";
+  else if (/^".*"$/.test(rhs)) expected = rhs.slice(1, -1);
   else if (Number.isFinite(Number(rhs))) expected = Number(rhs);
-  else throw new AssertionSyntaxError(`Expected a number or true/false after "${operator}" in "${source}", got "${rhs}".`);
+  else {
+    throw new AssertionSyntaxError(`Expected a number, true/false or a "quoted string" after "${operator}" in "${source}", got ${rhs}.`);
+  }
 
   let frame: number | "end" = "end";
   if (at !== undefined && at !== "end") {
@@ -78,7 +85,7 @@ export function parseAssertion(source: string): Assertion {
 export interface AssertionResult {
   source: string;
   pass: boolean;
-  actual: number | boolean | undefined;
+  actual: unknown;
   time: number;
   message: string;
 }
@@ -86,7 +93,7 @@ export interface AssertionResult {
 export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot, events: readonly GameEvent[]): AssertionResult {
   const { subject, operator, expected, source } = assertion;
   const time = snapshot.time;
-  let actual: number | boolean | undefined;
+  let actual: unknown;
   let label: string;
 
   switch (subject.kind) {
@@ -94,10 +101,30 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
       actual = snapshot[subject.field];
       label = subject.field;
       break;
-    case "events":
-      actual = events.filter((e) => e.type === subject.type && e.frame <= snapshot.frame).length;
-      label = `events.${subject.type}`;
+    case "events": {
+      const matches = (e: GameEvent) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
+      actual = events.filter((e) => matches(e) && e.frame <= snapshot.frame).length;
+      label = `events.${subject.name}`;
+      break;
+    }
+    case "state": {
+      const entity = snapshot.entities[subject.id];
+      label = `${subject.id}.state.${subject.key}`;
+      if (!entity) {
+        return { source, pass: false, actual: undefined, time, message: `entity "${subject.id}" does not exist at ${time.toFixed(2)}s.` };
+      }
+      actual = entity.state?.[subject.key];
+      if (actual === undefined) {
+        return {
+          source,
+          pass: false,
+          actual,
+          time,
+          message: `${label} is not set at ${time.toFixed(2)}s. Scripts set it with self.state.${subject.key} = ...`,
+        };
+      }
       break;
+    }
     case "entity": {
       const entity = snapshot.entities[subject.id];
       label = `${subject.id}.${subject.field}`;
@@ -116,14 +143,20 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
   }
 
   if (typeof actual !== typeof expected) {
-    return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, but it is compared with ${JSON.stringify(expected)}.` };
+    return {
+      source,
+      pass: false,
+      actual,
+      time,
+      message: `${label} is ${JSON.stringify(actual)} (a ${typeof actual}), but it is compared with ${JSON.stringify(expected)}.`,
+    };
   }
-  if (typeof actual === "boolean" && operator !== "==" && operator !== "!=") {
-    return { source, pass: false, actual, time, message: `${label} is true/false, so only == and != can be used.` };
+  if (typeof actual !== "number" && operator !== "==" && operator !== "!=") {
+    return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, so only == and != can be used.` };
   }
 
   const pass = compare(actual as number, operator, expected as number);
-  const shown = typeof actual === "number" ? round(actual) : actual;
+  const shown = typeof actual === "number" ? round(actual) : JSON.stringify(actual);
   return { source, pass, actual, time, message: `${label} = ${shown} at ${time.toFixed(2)}s` };
 }
 
@@ -166,7 +199,7 @@ export interface TestResult {
   error?: string;
 }
 
-export function runTest(scene: SceneDef, test: TestCase): TestResult {
+export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions = {}): TestResult {
   let script: InputScript;
   let assertions: Assertion[];
   let frames: number;
@@ -187,10 +220,16 @@ export function runTest(scene: SceneDef, test: TestCase): TestResult {
 
   const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
   const snapshots = new Map<number, WorldSnapshot>();
-  const world = new World(scene);
-  simulate(world, script, frames, (w) => {
-    if (wanted.has(w.frame)) snapshots.set(w.frame, w.snapshot());
-  });
+  let world: World;
+  try {
+    world = new World(scene, options);
+    simulate(world, script, frames, (w) => {
+      if (wanted.has(w.frame)) snapshots.set(w.frame, w.snapshot());
+    });
+  } catch (err) {
+    // A throwing script fails this test, not the whole run.
+    return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: (err as Error).message };
+  }
 
   const results = assertions.map((a) => {
     const frame = a.at === "end" ? frames : Math.min(a.at, frames);

package/src/browser.ts

@@ -3,6 +3,8 @@ import { parseFrames, type Sprite } from "./components.ts";
 import { collectAssetPaths } from "./effects.ts";
 import { InputScript } from "./input.ts";
 import { ParticleSystem } from "./particles.ts";
+import { PostFx } from "./postfx.ts";
+import type { DrawContext, DrawEvent, Script } from "./script.ts";
 import { FIXED_DT } from "./time.ts";
 import type { Action, SceneDef } from "./types.ts";
 import { World, type Entity } from "./world.ts";
@@ -30,6 +32,107 @@ const SHAKE_DECAY = 0.88;
 export interface GameOptions {
   /** URL prefix for image and audio paths in the scene. Defaults to "". */
   assetBase?: string;
+  /** URL prefix the scene's script paths are imported from. Defaults to `assetBase`. */
+  scriptBase?: string;
+  /** Scripts to load. Defaults to those the scene references; include any that `world.spawn` uses. */
+  scriptPaths?: readonly string[];
+}
+
+/** Imports the game's script modules, keyed by their path in the scene. */
+async function loadScripts(scene: SceneDef, options: GameOptions): Promise<Map<string, Script>> {
+  const base = options.scriptBase ?? options.assetBase ?? "";
+  const paths = options.scriptPaths ?? collectAssetPaths(scene).filter((ref) => ref.kind === "script").map((ref) => ref.path);
+  const scripts = new Map<string, Script>();
+  await Promise.all(
+    [...new Set(paths)].map(async (path) => {
+      const module = (await import(base + path)) as { default?: Script };
+      if (!module.default) throw new Error(`Script ${path} has no default export.`);
+      scripts.set(path, module.default);
+    }),
+  );
+  return scripts;
+}
+
+/** Fonts load from Google Fonts or project files; a slow or offline font never blocks the game for long. */
+async function loadFonts(scene: SceneDef, assetBase: string): Promise<void> {
+  const fonts = Object.entries(scene.fonts ?? {});
+  if (fonts.length === 0) return;
+  const load = async ([family, src]: [string, string]) => {
+    if (src === "google") {
+      const name = encodeURIComponent(family).replace(/%20/g, "+");
+      // Not every family has every weight, and Google rejects the request if one is missing.
+      for (const weights of [":wght@400;500;600;700;800;900", ":wght@400;700", ""]) {
+        const response = await fetch(`https://fonts.googleapis.com/css2?family=${name}${weights}&display=block`);
+        if (!response.ok) continue;
+        const style = document.createElement("style");
+        style.textContent = await response.text();
+        document.head.append(style);
+        break;
+      }
+      await Promise.all(["400", "700", "900"].map((weight) => document.fonts.load(`${weight} 16px "${family}"`)));
+    } else {
+      const face = new FontFace(family, `url("${assetBase}${src}")`);
+      // FontFaceSet.add is missing from some TypeScript DOM typings.
+      (document.fonts as unknown as Set<FontFace>).add(await face.load());
+    }
+  };
+  const all = Promise.all(
+    fonts.map((font) => load(font).catch((err) => console.warn(`[ludra] could not load font "${font[0]}": ${err}`))),
+  );
+  await Promise.race([all, new Promise((resolve) => setTimeout(resolve, 4000))]);
+}
+
+interface Stage {
+  /** Where the game draws. With postfx this is an offscreen canvas. */
+  ctx: CanvasRenderingContext2D;
+  /** The canvas players see. */
+  output: HTMLCanvasElement;
+  images: Map<string, HTMLImageElement>;
+  scripts: Map<string, Script>;
+  /** Shows the drawn frame: runs the postfx shader, or does nothing without one. */
+  present(time: number): void;
+  /** Why postfx couldn't start (the game then runs without it and shows this message). */
+  error?: string;
+}
+
+/**
+ * Loads everything a scene needs and sets up its canvases. With `postfx`, `canvas`
+ * becomes the offscreen source and a WebGL canvas takes its place in the page.
+ */
+async function prepare(canvas: HTMLCanvasElement, scene: SceneDef, options: GameOptions): Promise<Stage> {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Canvas 2D context is not available.");
+  const assetBase = options.assetBase ?? "";
+  const shaderPath = scene.postfx?.shader;
+  const [images, scripts, shader] = await Promise.all([
+    loadImages(scene, assetBase),
+    loadScripts(scene, options),
+    shaderPath
+      ? fetch(assetBase + shaderPath).then(async (r) => (r.ok ? r.text() : new Error(`could not load ${shaderPath} (${r.status})`)))
+      : undefined,
+    loadFonts(scene, assetBase),
+  ]);
+  const stage: Stage = { ctx, output: canvas, images, scripts, present: () => {} };
+  if (scene.postfx && shader !== undefined) {
+    try {
+      if (shader instanceof Error) throw shader;
+      const fx = new PostFx(canvas.width, canvas.height, shader, scene.postfx);
+      fx.canvas.id = canvas.id;
+      fx.canvas.className = canvas.className;
+      fx.canvas.style.cssText = canvas.style.cssText;
+      canvas.replaceWith(fx.canvas);
+      stage.output = fx.canvas;
+      stage.present = (time) => fx.render(canvas, time);
+    } catch (err) {
+      stage.error = `postfx: ${message(err)}`;
+      console.error("[ludra]", err);
+    }
+  }
+  return stage;
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
 }
 
 /**
@@ -39,17 +142,16 @@ export interface GameOptions {
  * Resolves (after images load) to a function that stops the game.
  */
 export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, options: GameOptions = {}): Promise<() => void> {
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Canvas 2D context is not available.");
-  const assetBase = options.assetBase ?? "";
-  const images = await loadImages(scene, assetBase);
-  const sounds = new SoundPlayer(assetBase);
+  const { ctx, images, scripts, present, error } = await prepare(canvas, scene, options);
+  const sounds = new SoundPlayer(options.assetBase ?? "");
   const view = new View(scene, images);
 
-  let world = new World(scene);
+  let world = new World(scene, { scripts });
+  let crash: string | undefined = error;
   const restart = () => {
-    world = new World(scene);
+    world = new World(scene, { scripts });
     view.reset();
+    crash = error;
   };
 
   const held = new Set<Action>();
@@ -83,13 +185,27 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
   const frame = (now: number) => {
     accumulator += Math.min(MAX_FRAME_TIME, (now - last) / 1000);
     last = now;
-    while (accumulator >= FIXED_DT) {
-      world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
+    while (accumulator >= FIXED_DT && !crash) {
+      try {
+        world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
+      } catch (err) {
+        // A script threw: freeze the game and show why, instead of failing silently.
+        crash = message(err);
+        console.error("[ludra]", err);
+      }
       tapped.clear();
       view.step(world, (sound) => sounds.play(sound));
       accumulator -= FIXED_DT;
     }
-    view.draw(ctx, world, sounds.muted);
+    try {
+      view.draw(ctx, world, sounds.muted);
+    } catch (err) {
+      // A draw hook threw. Same treatment as a simulation error.
+      if (!crash) console.error("[ludra]", err);
+      crash ??= message(err);
+    }
+    if (crash) drawCrash(ctx, crash);
+    present(world.time);
     raf = requestAnimationFrame(frame);
   };
   raf = requestAnimationFrame(frame);
@@ -123,11 +239,10 @@ export interface CapturedFrame {
  * `ludra play --screenshot`.
  */
 export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef, options: CaptureOptions): Promise<CapturedFrame[]> {
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Canvas 2D context is not available.");
-  const images = await loadImages(scene, options.assetBase ?? "");
+  const { ctx, output, images, scripts, present, error } = await prepare(canvas, scene, options);
+  if (error) throw new Error(error);
   const view = new View(scene, images);
-  const world = new World(scene);
+  const world = new World(scene, { scripts });
   const script = InputScript.parse(options.inputs ?? "");
   const wanted = new Set(options.frames);
   const last = Math.max(0, ...options.frames);
@@ -136,7 +251,8 @@ export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef,
   for (let frame = 0; ; frame++) {
     if (wanted.has(frame)) {
       view.draw(ctx, world, false);
-      captured.push({ frame, time: frame * FIXED_DT, png: canvas.toDataURL("image/png") });
+      present(world.time);
+      captured.push({ frame, time: frame * FIXED_DT, png: output.toDataURL("image/png") });
     }
     if (frame >= last) break;
     world.step(script.at(frame));
@@ -145,6 +261,31 @@ export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef,
   return captured;
 }
 
+function drawCrash(ctx: CanvasRenderingContext2D, message: string): void {
+  const { width, height } = ctx.canvas;
+  ctx.fillStyle = "rgba(20, 0, 8, 0.85)";
+  ctx.fillRect(0, 0, width, height);
+  ctx.fillStyle = "#ff9b9b";
+  ctx.textAlign = "left";
+  ctx.font = "700 22px system-ui, sans-serif";
+  ctx.fillText("Script error", 32, 56);
+  ctx.font = "15px ui-monospace, monospace";
+  // Wrap the message to the canvas width.
+  let line = "";
+  let y = 92;
+  for (const word of message.split(" ")) {
+    if (ctx.measureText(line + word).width > width - 64) {
+      ctx.fillText(line, 32, y);
+      line = "";
+      y += 22;
+    }
+    line += `${word} `;
+  }
+  ctx.fillText(line, 32, y);
+  ctx.fillStyle = "rgba(255, 255, 255, 0.6)";
+  ctx.fillText("Fix the script; the page reloads on save. R restarts.", 32, y + 40);
+}
+
 async function loadImages(scene: SceneDef, assetBase: string): Promise<Map<string, HTMLImageElement>> {
   const images = new Map<string, HTMLImageElement>();
   const paths = new Set(collectAssetPaths(scene).filter((ref) => ref.kind === "image").map((ref) => ref.path));
@@ -174,6 +315,8 @@ class View {
   private readonly facing = new Map<string, number>();
   private readonly emitTimers = new Map<string, number>();
   private readonly frameCache = new Map<string, number[]>();
+  /** ctx.local for each entity's draw hooks. */
+  private readonly local = new Map<string, Record<string, unknown>>();
   private shake = 0;
   private handledEvents = 0;
   private readonly scene: SceneDef;
@@ -188,6 +331,7 @@ class View {
     this.particles.clear();
     this.facing.clear();
     this.emitTimers.clear();
+    this.local.clear();
     this.shake = 0;
     this.handledEvents = 0;
   }
@@ -195,7 +339,7 @@ class View {
   /** Runs once per simulation step: turns new events into effects and advances particles. */
   step(world: World, playSound: (sound: string) => void): void {
     for (const event of world.events.slice(this.handledEvents)) {
-      const effect = this.scene.effects?.[event.type];
+      const effect = this.scene.effects?.[event.type === "custom" ? event.name : event.type];
       if (!effect) continue;
       if (effect.particles) this.particles.burst(event.x, event.y, effect.particles);
       if (effect.sound) playSound(effect.sound);
@@ -224,7 +368,7 @@ class View {
     ctx.fillStyle = world.background;
     ctx.fillRect(0, 0, viewWidth, viewHeight);
 
-    const target = world.entities.find((e) => e.camera) ?? world.entities.find((e) => e.platformer);
+    const target = world.entities.find((e) => e.camera) ?? world.entities.find((e) => e.platformer || e.topdown);
     const zoom = target?.camera?.zoom ?? 1;
     const visibleWidth = viewWidth / zoom;
     const visibleHeight = viewHeight / zoom;
@@ -235,14 +379,25 @@ class View {
       cameraY += (this.particles.random() - 0.5) * 2 * this.shake;
     }
 
+    const viewInfo = { width: viewWidth, height: viewHeight, cameraX, cameraY, zoom };
     ctx.save();
     ctx.scale(zoom, zoom);
     ctx.translate(-cameraX, -cameraY);
-    const visible = world.entities.filter((e) => e.sprite).sort((a, b) => a.sprite!.layer - b.sprite!.layer);
-    for (const e of visible) this.drawSprite(ctx, e, world.time);
+    const layer = (e: Entity) => e.sprite?.layer ?? 0;
+    const visible = world.entities.filter((e) => e.sprite || e.script?.module.draw).sort((a, b) => layer(a) - layer(b));
+    for (const e of visible) {
+      if (e.sprite) this.drawSprite(ctx, e, world.time);
+      if (e.script?.module.draw) this.drawHook(ctx, world, e, "draw", viewInfo);
+    }
     this.particles.draw(ctx);
     ctx.restore();
 
+    if (world.hasHook("drawUI")) {
+      // The game draws its own interface.
+      for (const e of [...world.entities]) if (e.script?.module.drawUI) this.drawHook(ctx, world, e, "drawUI", viewInfo);
+      return;
+    }
+
     ctx.textAlign = "left";
     ctx.font = "600 18px system-ui, sans-serif";
     ctx.fillStyle = "#ffffff";
@@ -265,6 +420,30 @@ class View {
     }
   }
 
+  private drawHook(ctx: CanvasRenderingContext2D, world: World, e: Entity, hook: "draw" | "drawUI", view: DrawContext["view"]): void {
+    let local = this.local.get(e.id);
+    if (!local) this.local.set(e.id, (local = {}));
+    ctx.save();
+    try {
+      world.callDrawHook(e, hook, {
+        g: ctx,
+        time: world.time,
+        local,
+        view,
+        recent: (name, seconds = 0.5) => recentEvents(world, name, seconds),
+        image: (path) => this.images.get(path),
+        burst: (x, y, particles = {}) => this.particles.burst(x, y, particles),
+        shake: (amount) => {
+          this.shake = Math.max(this.shake, amount);
+        },
+        random: () => this.particles.random(),
+      });
+    } finally {
+      // Whatever the hook changed (transform, alpha, blend mode, filter) ends with it.
+      ctx.restore();
+    }
+  }
+
   private drawSprite(ctx: CanvasRenderingContext2D, e: Entity, time: number): void {
     const sprite = e.sprite!;
     const width = sprite.width || e.body?.width || 16;
@@ -336,6 +515,20 @@ class View {
 
 type AnimationState = "idle" | "run" | "jump" | "fall";
 
+function recentEvents(world: World, name: string | undefined, seconds: number): DrawEvent[] {
+  const since = world.time - seconds;
+  const result: DrawEvent[] = [];
+  // Events are in time order, so walk back until they get too old.
+  for (let i = world.events.length - 1; i >= 0; i--) {
+    const event = world.events[i]!;
+    if (event.time < since) break;
+    const eventName = event.type === "custom" ? event.name : event.type;
+    if (name !== undefined && eventName !== name) continue;
+    result.push({ name: eventName, time: event.time, x: event.x, y: event.y, entity: event.entity, data: event.type === "custom" ? event.data : undefined });
+  }
+  return result.reverse();
+}
+
 function animationState(e: Entity): AnimationState {
   const b = e.body;
   if (!b) return "idle";

package/src/components.ts

@@ -4,7 +4,9 @@ export type FieldSpec =
   | { type: "boolean"; default?: boolean; description: string }
   | { type: "enum"; values: readonly string[]; default?: string; description: string }
   /** Spritesheet frame indices: "0", "1-4" or "0,2,4-6". Empty = not used. */
-  | { type: "frames"; default?: string; description: string };
+  | { type: "frames"; default?: string; description: string }
+  /** Any JSON object. */
+  | { type: "object"; default?: Record<string, unknown>; description: string };
 
 export interface ComponentSpec {
   description: string;
@@ -18,11 +20,13 @@ export const COMPONENT_NAMES = [
   "body",
   "sprite",
   "platformer",
+  "topdown",
   "collectible",
   "patrol",
   "hazard",
   "goal",
   "emitter",
+  "script",
   "camera",
 ] as const;
 export type ComponentName = (typeof COMPONENT_NAMES)[number];
@@ -62,6 +66,12 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       height: { type: "number", min: 1, description: "Collider height in pixels." },
       sensor: { type: "boolean", default: false, description: "Sensors detect overlaps but never block movement (coins, triggers)." },
       gravityScale: { type: "number", default: 1, description: "Multiplier on world gravity for dynamic bodies." },
+      bounce: {
+        type: "number",
+        min: 0,
+        default: 0,
+        description: "How much speed a dynamic body keeps when it hits a solid: 0 stops it, 1 bounces it back at full speed (balls, pinballs).",
+      },
       vx: { type: "number", default: 0, description: "Initial horizontal velocity in px/s." },
       vy: { type: "number", default: 0, description: "Initial vertical velocity in px/s." },
     },
@@ -99,8 +109,23 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       variableJump: { type: "boolean", default: true, description: "Releasing jump early cuts the jump short." },
     },
   },
+  topdown: {
+    description:
+      "Player control seen from above or for vehicles: moves with the arrow keys, no gravity. directions picks 8-way, 4-way, or one axis (\"x\" for a breakout paddle or a shooter ship). Needs a dynamic body (collides with walls) or a kinematic one (passes through, use clampToWorld).",
+    requires: ["transform", "body"],
+    fields: {
+      speed: { type: "number", min: 0, default: 200, description: "Move speed in px/s." },
+      directions: {
+        type: "enum",
+        values: ["8", "4", "x", "y"],
+        default: "8",
+        description: '"8": any direction (diagonals keep the same speed). "4": up/down/left/right only. "x" or "y": one axis.',
+      },
+      clampToWorld: { type: "boolean", default: true, description: "Keep the entity inside the world bounds." },
+    },
+  },
   collectible: {
-    description: "Removed when a platformer entity touches it and adds to the score. Its body must be a sensor.",
+    description: "Removed when a player (platformer or topdown) touches it and adds to the score. Its body must be a sensor.",
     requires: ["transform", "body"],
     fields: {
       score: { type: "number", default: 1, description: "Points added when collected." },
@@ -140,6 +165,15 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       ...Object.fromEntries(Object.entries(PARTICLE_FIELDS).filter(([field]) => field !== "count")),
     },
   },
+  script: {
+    description:
+      "Custom behavior written in TypeScript or JavaScript: a file that default-exports hooks (start, update, touch). Use it for anything the built-in components don't do: chasing, doors and keys, timers, shooting, boss phases. Run `ludra components script` for the API.",
+    requires: ["transform"],
+    fields: {
+      src: { type: "string", description: 'Script path relative to the project, e.g. "scripts/chase.ts".' },
+      params: { type: "object", default: {}, description: "Values passed to the script as ctx.params, so one script can serve many entities." },
+    },
+  },
   camera: {
     description: "The browser camera follows this entity. Without it, the camera follows the first platformer.",
     requires: ["transform"],
@@ -160,6 +194,7 @@ export interface Body {
   height: number;
   sensor: boolean;
   gravityScale: number;
+  bounce: number;
   vx: number;
   vy: number;
 }
@@ -197,6 +232,11 @@ export interface Emitter extends Omit<ParticleSpec, "count"> {
   rate: number;
 }
 
+export interface ScriptComponent {
+  src: string;
+  params: Record<string, unknown>;
+}
+
 export interface Platformer {
   speed: number;
   jumpSpeed: number;
@@ -205,6 +245,12 @@ export interface Platformer {
   variableJump: boolean;
 }
 
+export interface Topdown {
+  speed: number;
+  directions: "8" | "4" | "x" | "y";
+  clampToWorld: boolean;
+}
+
 export interface Collectible {
   score: number;
 }