@ludra/core 0.5.0 → 0.8.0

package/src/browser.ts

@@ -3,10 +3,11 @@ import { parseFrames, type Sprite } from "./components.ts";
 import { collectAssetPaths } from "./effects.ts";
 import { InputScript } from "./input.ts";
 import { ParticleSystem } from "./particles.ts";
-import type { Script } from "./script.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";
+import type { Action, PostFxDef, SceneDef } from "./types.ts";
+import { World, type Entity, type GameEvent } from "./world.ts";
 
 const KEYMAP: Record<string, Action> = {
   ArrowLeft: "left",
@@ -35,6 +36,11 @@ export interface GameOptions {
   scriptBase?: string;
   /** Scripts to load. Defaults to those the scene references; include any that `world.spawn` uses. */
   scriptPaths?: readonly string[];
+  /**
+   * Loads another scene by path, for goals with `next` and `world.goto`. Without it the
+   * game stays on its first scene. Throw with a readable message if the scene is invalid.
+   */
+  loadScene?: (path: string) => Promise<SceneDef>;
 }
 
 /** Imports the game's script modules, keyed by their path in the scene. */
@@ -52,26 +58,182 @@ async function loadScripts(scene: SceneDef, options: GameOptions): Promise<Map<s
   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))]);
+}
+
+/** A scene's postfx shader source, or why it couldn't be fetched. */
+async function loadShader(scene: SceneDef, assetBase: string): Promise<string | Error | undefined> {
+  const path = scene.postfx?.shader;
+  if (!path) return undefined;
+  const response = await fetch(assetBase + path).catch((err: unknown) => err as Error);
+  if (response instanceof Error) return response;
+  return response.ok ? response.text() : new Error(`could not load ${path} (${response.status})`);
+}
+
+/**
+ * The canvas players see. The game always draws into the 2D canvas; when a scene
+ * has `postfx`, a WebGL canvas running its shader takes the 2D canvas's place in
+ * the page, and goes away again for a scene without one.
+ */
+class Screen {
+  readonly ctx: CanvasRenderingContext2D;
+  output: HTMLCanvasElement;
+  private readonly canvas: HTMLCanvasElement;
+  private fx: PostFx | undefined;
+
+  constructor(canvas: HTMLCanvasElement) {
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("Canvas 2D context is not available.");
+    this.ctx = ctx;
+    this.canvas = canvas;
+    this.output = canvas;
+  }
+
+  /** Switches to a scene's shader, or to none. Returns why the shader can't run, if it can't. */
+  use(postfx: PostFxDef | undefined, shader: string | Error | undefined): string | undefined {
+    let fx: PostFx | undefined;
+    let error: string | undefined;
+    if (postfx && shader !== undefined) {
+      try {
+        if (shader instanceof Error) throw shader;
+        fx = new PostFx(this.canvas.width, this.canvas.height, shader, postfx);
+      } catch (err) {
+        error = `postfx: ${message(err)}`;
+        console.error("[ludra]", err);
+      }
+    }
+    const target = fx?.canvas ?? this.canvas;
+    if (target !== this.output) {
+      target.id = this.canvas.id;
+      target.className = this.canvas.className;
+      target.style.cssText = this.canvas.style.cssText;
+      this.output.replaceWith(target);
+      this.output = target;
+    }
+    this.fx = fx;
+    return error;
+  }
+
+  /** Shows the frame the game just drew, through the shader if there is one. */
+  present(time: number): void {
+    this.fx?.render(this.canvas, time);
+  }
+}
+
+/** What a scene needs before it can be drawn. */
+async function loadScene(scene: SceneDef, options: GameOptions, scripts: Map<string, Script>) {
+  const assetBase = options.assetBase ?? "";
+  const [images, more, shader] = await Promise.all([
+    loadImages(scene, assetBase),
+    loadScripts(scene, options),
+    loadShader(scene, assetBase),
+    loadFonts(scene, assetBase),
+  ]);
+  for (const [path, script] of more) scripts.set(path, script);
+  return { images, shader };
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Seconds the win screen shows before the next scene, and the fade into a world.goto scene. */
+const WIN_PAUSE = 1.6;
+const GOTO_FADE = 0.35;
+
 /**
  * Runs a scene in a canvas with keyboard controls, images, particles and
  * sound. The simulation uses the same fixed step as headless runs, so what
  * tests verify is what players get; everything added here is presentation.
+ * With `options.loadScene`, won goals with `next` and `world.goto` move on
+ * to other scenes, keeping score, deaths and lives.
  * 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, scripts] = await Promise.all([loadImages(scene, assetBase), loadScripts(scene, options)]);
-  const sounds = new SoundPlayer(assetBase);
-  const view = new View(scene, images);
+export async function startGame(canvas: HTMLCanvasElement, firstScene: SceneDef, options: GameOptions = {}): Promise<() => void> {
+  const screen = new Screen(canvas);
+  const ctx = screen.ctx;
+  const sounds = new SoundPlayer(options.assetBase ?? "");
+  const scripts = new Map<string, Script>();
 
-  let world = new World(scene, { scripts });
+  type Carry = { score: number; deaths: number; lives: number | undefined };
+  let scene = firstScene;
+  let startCarry: Carry | undefined;
+  let view: View;
+  let world: World;
   let crash: string | undefined;
+  let sceneError: string | undefined;
+  /** Real time when the world asked to move on, while waiting to load the next scene. */
+  let exitSince: number | undefined;
+  let loading = false;
+
+  const enter = async (next: SceneDef, carry: Carry | undefined) => {
+    const { images, shader } = await loadScene(next, options, scripts);
+    scene = next;
+    startCarry = carry;
+    view = new View(next, images);
+    sceneError = screen.use(next.postfx, shader);
+    crash = sceneError;
+    exitSince = undefined;
+    try {
+      world = new World(next, { scripts, carry });
+    } catch (err) {
+      crash = message(err);
+      world = new World({ ...next, entities: [] });
+    }
+  };
+  await enter(firstScene, undefined);
+
+  // Game over starts the whole game again; otherwise R restarts the current scene as it began.
   const restart = () => {
-    world = new World(scene, { scripts });
+    if (loading) return;
+    if (world.lost && scene !== firstScene) {
+      loading = true;
+      void enter(firstScene, undefined).finally(() => (loading = false));
+      return;
+    }
+    world = new World(scene, { scripts, carry: startCarry });
     view.reset();
-    crash = undefined;
+    crash = sceneError;
+    exitSince = undefined;
+  };
+
+  const moveOn = (path: string) => {
+    if (!options.loadScene) return;
+    loading = true;
+    const carry = { score: world.score, deaths: world.deaths, lives: world.lives };
+    options
+      .loadScene(path)
+      .then((next) => enter(next, carry))
+      .catch((err: unknown) => {
+        crash = `Could not load the next scene "${path}": ${message(err)}`;
+      })
+      .finally(() => (loading = false));
   };
 
   const held = new Set<Action>();
@@ -105,20 +267,42 @@ 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 && !crash) {
+    while (accumulator >= FIXED_DT && !crash && !loading) {
       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 = err instanceof Error ? err.message : String(err);
+        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);
+
+    // Moving on: let the win screen show, or fade out for a world.goto, then load.
+    let fade = 0;
+    if (world.exit !== undefined && options.loadScene && !crash) {
+      exitSince ??= now;
+      const pause = world.won ? WIN_PAUSE : GOTO_FADE;
+      const elapsed = (now - exitSince) / 1000;
+      fade = Math.min(1, Math.max(0, (elapsed - (pause - GOTO_FADE)) / GOTO_FADE));
+      if (elapsed >= pause && !loading) moveOn(world.exit);
+    }
+
+    try {
+      view.draw(ctx, world, sounds.muted, options.loadScene !== undefined);
+    } catch (err) {
+      // A draw hook threw. Same treatment as a simulation error.
+      if (!crash) console.error("[ludra]", err);
+      crash ??= message(err);
+    }
+    if (fade > 0 || loading) {
+      ctx.fillStyle = `rgba(0, 0, 0, ${loading ? 1 : fade})`;
+      ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    }
     if (crash) drawCrash(ctx, crash);
+    screen.present(world.time);
     raf = requestAnimationFrame(frame);
   };
   raf = requestAnimationFrame(frame);
@@ -152,9 +336,11 @@ 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, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
+  const screen = new Screen(canvas);
+  const scripts = new Map<string, Script>();
+  const { images, shader } = await loadScene(scene, options, scripts);
+  const error = screen.use(scene.postfx, shader);
+  if (error) throw new Error(error);
   const view = new View(scene, images);
   const world = new World(scene, { scripts });
   const script = InputScript.parse(options.inputs ?? "");
@@ -164,8 +350,9 @@ 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") });
+      view.draw(screen.ctx, world, false, false);
+      screen.present(world.time);
+      captured.push({ frame, time: frame * FIXED_DT, png: screen.output.toDataURL("image/png") });
     }
     if (frame >= last) break;
     world.step(script.at(frame));
@@ -228,20 +415,29 @@ 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;
   private readonly images: Map<string, HTMLImageElement>;
 
+  /** Whether the scene can award points at all, so the default HUD can leave the score out. */
+  private readonly scoring: boolean;
+
   constructor(scene: SceneDef, images: Map<string, HTMLImageElement>) {
     this.scene = scene;
     this.images = images;
+    this.scoring = scene.entities.some(
+      (e) => e.components.collectible || (e.components.hazard && Number(e.components.hazard.score) > 0) || Number(e.components.goal?.requireScore) > 0,
+    );
   }
 
   reset(): void {
     this.particles.clear();
     this.facing.clear();
     this.emitTimers.clear();
+    this.local.clear();
     this.shake = 0;
     this.handledEvents = 0;
   }
@@ -272,13 +468,14 @@ class View {
     this.shake = this.shake < 0.5 ? 0 : this.shake * SHAKE_DECAY;
   }
 
-  draw(ctx: CanvasRenderingContext2D, world: World, muted: boolean): void {
+  /** `continues`: the host loads next scenes, so a won scene with `next` says so instead of offering a replay. */
+  draw(ctx: CanvasRenderingContext2D, world: World, muted: boolean, continues: boolean): void {
     const { width: viewWidth, height: viewHeight } = ctx.canvas;
     ctx.imageSmoothingEnabled = false;
     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;
@@ -289,33 +486,75 @@ 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;
+    }
+
+    // Only what this scene uses: no "Score 0" in a game without points.
+    const parts: string[] = [];
+    if (world.lives !== undefined) parts.push(`${"♥".repeat(Math.max(0, Math.min(world.lives, 10)))}${world.lives > 10 ? ` ${world.lives}` : ""}`);
+    if (this.scoring || world.score !== 0) parts.push(`Score ${world.score}`);
+    if (world.lives === undefined) parts.push(`Deaths ${world.deaths}`);
     ctx.textAlign = "left";
     ctx.font = "600 18px system-ui, sans-serif";
     ctx.fillStyle = "#ffffff";
-    ctx.fillText(`Score ${world.score}   Deaths ${world.deaths}`, 16, 30);
+    ctx.fillText(parts.join("   "), 16, 30);
     ctx.textAlign = "right";
     ctx.font = "500 13px system-ui, sans-serif";
     ctx.fillStyle = "rgba(255, 255, 255, 0.6)";
     ctx.fillText(`M: sound ${muted ? "off" : "on"} · R: restart`, viewWidth - 16, 28);
 
-    if (world.won) {
+    if (world.won || world.lost) {
       ctx.fillStyle = "rgba(0, 0, 0, 0.55)";
       ctx.fillRect(0, 0, viewWidth, viewHeight);
       ctx.fillStyle = "#ffffff";
       ctx.textAlign = "center";
       ctx.font = "700 44px system-ui, sans-serif";
-      ctx.fillText("Level complete!", viewWidth / 2, viewHeight / 2 - 10);
+      ctx.fillText(world.won ? "Level complete!" : "Game over", viewWidth / 2, viewHeight / 2 - 10);
       ctx.font = "500 18px system-ui, sans-serif";
-      const winTime = world.events.find((e) => e.type === "win")?.time ?? world.time;
-      ctx.fillText(`Score ${world.score} · ${winTime.toFixed(1)}s · Press R to play again`, viewWidth / 2, viewHeight / 2 + 30);
+      const endTime = world.events.find((e) => e.type === "win" || e.type === "gameover")?.time ?? world.time;
+      const next = world.won && world.exit !== undefined && continues ? "Get ready…" : `Press R to ${world.won ? "play again" : "try again"}`;
+      const score = this.scoring || world.score !== 0 ? `Score ${world.score} · ` : "";
+      ctx.fillText(`${score}${endTime.toFixed(1)}s · ${next}`, viewWidth / 2, viewHeight / 2 + 30);
+    }
+  }
+
+  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();
     }
   }
 
@@ -390,6 +629,23 @@ 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;
+    // Custom events carry what the script passed; built-in ones their own details (item, enemy, checkpoint...).
+    const { type: _type, frame: _frame, time, x, y, entity, ...details } = event as GameEvent & { data?: unknown };
+    const data = event.type === "custom" ? event.data : details;
+    result.push({ name: eventName, time, x, y, entity, data });
+  }
+  return result.reverse();
+}
+
 function animationState(e: Entity): AnimationState {
   const b = e.body;
   if (!b) return "idle";

package/src/components.ts

@@ -20,10 +20,12 @@ export const COMPONENT_NAMES = [
   "body",
   "sprite",
   "platformer",
+  "topdown",
   "collectible",
   "patrol",
   "hazard",
   "goal",
+  "checkpoint",
   "emitter",
   "script",
   "camera",
@@ -65,6 +67,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." },
     },
@@ -102,8 +110,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." },
@@ -133,8 +156,19 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
     requires: ["transform", "body"],
     fields: {
       requireScore: { type: "number", min: 0, default: 0, description: "Score needed before the goal accepts the player." },
+      next: {
+        type: "string",
+        default: "",
+        description: 'Scene to play after this one is won, e.g. "scenes/level-2.scene.json". The browser moves on and keeps score, deaths and lives; each scene is tested on its own.',
+      },
     },
   },
+  checkpoint: {
+    description:
+      "When a player touches it, that player respawns here after dying (standing on the checkpoint's bottom edge). Fires a checkpoint event once. Its body must be a sensor.",
+    requires: ["transform", "body"],
+    fields: {},
+  },
   emitter: {
     description: "Continuously emits visual particles from the entity (torches, sparkles, smoke). It does not affect gameplay.",
     requires: ["transform"],
@@ -172,6 +206,7 @@ export interface Body {
   height: number;
   sensor: boolean;
   gravityScale: number;
+  bounce: number;
   vx: number;
   vy: number;
 }
@@ -222,6 +257,12 @@ export interface Platformer {
   variableJump: boolean;
 }
 
+export interface Topdown {
+  speed: number;
+  directions: "8" | "4" | "x" | "y";
+  clampToWorld: boolean;
+}
+
 export interface Collectible {
   score: number;
 }
@@ -239,6 +280,7 @@ export interface Hazard {
 
 export interface Goal {
   requireScore: number;
+  next: string;
 }
 
 export interface Camera {

package/src/drawcheck.ts

@@ -0,0 +1,80 @@
+import { ScriptError, type ScriptModules } from "./script.ts";
+import type { Diagnostic, SceneDef } from "./types.ts";
+import { World } from "./world.ts";
+
+/** Simulation frames at which `checkDrawHooks` paints: the start, and after things have moved. */
+const CHECK_FRAMES = [0, 30, 120];
+
+/**
+ * A stand-in for CanvasRenderingContext2D that accepts every call and property,
+ * so draw hooks can run outside a browser. It catches the hook's own mistakes
+ * (typos, undefined values, changing the game while drawing), not what it looks like.
+ */
+function mockCanvas(): CanvasRenderingContext2D {
+  const handler: ProxyHandler<() => unknown> = {
+    get: (_target, key) => (key === Symbol.toPrimitive ? () => 0 : key === "then" ? undefined : any),
+    set: () => true,
+    apply: () => any,
+  };
+  const any: unknown = new Proxy(() => undefined, handler);
+  return any as CanvasRenderingContext2D;
+}
+
+/**
+ * Runs every `draw` and `drawUI` hook against a mock canvas at a few points of
+ * an idle run, and reports hooks that throw. Used by `ludra check`.
+ */
+export function checkDrawHooks(scene: SceneDef, scripts: ScriptModules): Diagnostic[] {
+  let world: World;
+  try {
+    world = new World(scene, { scripts });
+  } catch {
+    return []; // Load problems are reported elsewhere.
+  }
+  const reported = new Set<string>();
+  const diagnostics: Diagnostic[] = [];
+  const g = mockCanvas();
+  const view = { width: world.width, height: world.height, cameraX: 0, cameraY: 0, zoom: 1 };
+  const locals = new Map<string, Record<string, unknown>>();
+
+  for (let frame = 0; frame <= CHECK_FRAMES.at(-1)!; frame++) {
+    if (CHECK_FRAMES.includes(frame)) {
+      for (const e of [...world.entities]) {
+        for (const hook of ["draw", "drawUI"] as const) {
+          if (!e.script?.module[hook]) continue;
+          if (!locals.has(e.id)) locals.set(e.id, {});
+          try {
+            world.callDrawHook(e, hook, {
+              g,
+              time: world.time,
+              local: locals.get(e.id)!,
+              view,
+              recent: () => [],
+              image: () => undefined,
+              burst: () => {},
+              shake: () => {},
+              random: () => 0.5,
+            });
+          } catch (err) {
+            const key = `${e.script.src}:${hook}`;
+            if (reported.has(key)) continue;
+            reported.add(key);
+            diagnostics.push({
+              severity: "error",
+              code: "E_DRAW_HOOK",
+              path: `${e.script.src} → ${hook}`,
+              message: err instanceof ScriptError ? err.message : String(err),
+              fix: "Draw hooks run every rendered frame in the browser. Fix the error; ctx.image() can return undefined, so check it before drawing.",
+            });
+          }
+        }
+      }
+    }
+    try {
+      world.step(new Set());
+    } catch {
+      break; // Simulation errors surface in play and test.
+    }
+  }
+  return diagnostics;
+}

package/src/effects.ts

@@ -7,6 +7,7 @@ export type SoundPreset = (typeof SOUND_PRESETS)[number];
 
 export const AUDIO_EXTENSIONS = [".wav", ".mp3", ".ogg"] as const;
 export const IMAGE_EXTENSIONS = [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"] as const;
+export const FONT_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf"] as const;
 
 export const EFFECT_FIELDS: Record<string, FieldSpec> = {
   sound: {
@@ -18,7 +19,7 @@ export const EFFECT_FIELDS: Record<string, FieldSpec> = {
 };
 
 export const EFFECTS_DESCRIPTION =
-  'Scene-level "effects" map a game event (jump, land, collect, die, stomp, win) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.';
+  'Scene-level "effects" map a game event (jump, land, collect, die, stomp, win, bounce, checkpoint, gameover, goto, or a custom one) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.';
 
 export function isSoundPreset(sound: string): sound is SoundPreset {
   return (SOUND_PRESETS as readonly string[]).includes(sound);
@@ -29,7 +30,7 @@ export interface AssetReference {
   path: string;
   /** JSON path of the field that references it. */
   at: string;
-  kind: "image" | "audio" | "script";
+  kind: "image" | "audio" | "script" | "font" | "shader" | "scene";
 }
 
 /** Every file a scene points at, so tools can check that they exist. */
@@ -38,12 +39,27 @@ export function collectAssetPaths(scene: SceneDef): AssetReference[] {
   scene.entities.forEach((entity, i) => {
     const image = entity.components.sprite?.image;
     if (typeof image === "string" && image !== "") refs.push({ path: image, at: `entities[${i}].components.sprite.image`, kind: "image" });
+    const next = entity.components.goal?.next;
+    if (typeof next === "string" && next !== "") refs.push({ path: next, at: `entities[${i}].components.goal.next`, kind: "scene" });
     const src = entity.components.script?.src;
     if (typeof src === "string" && src !== "") refs.push({ path: src, at: `entities[${i}].components.script.src`, kind: "script" });
+    // Images named in script params are preloaded for draw hooks (ctx.image).
+    const params = entity.components.script?.params;
+    if (params && typeof params === "object") {
+      for (const [key, value] of Object.entries(params)) {
+        if (typeof value === "string" && IMAGE_EXTENSIONS.some((ext) => value.toLowerCase().endsWith(ext))) {
+          refs.push({ path: value, at: `entities[${i}].components.script.params.${key}`, kind: "image" });
+        }
+      }
+    }
   });
   for (const [event, effect] of Object.entries(scene.effects ?? {})) {
     const sound = effect?.sound;
     if (typeof sound === "string" && sound !== "" && !isSoundPreset(sound)) refs.push({ path: sound, at: `effects.${event}.sound`, kind: "audio" });
   }
+  for (const [family, src] of Object.entries(scene.fonts ?? {})) {
+    if (typeof src === "string" && src !== "google") refs.push({ path: src, at: `fonts.${family}`, kind: "font" });
+  }
+  if (typeof scene.postfx?.shader === "string" && scene.postfx.shader !== "") refs.push({ path: scene.postfx.shader, at: "postfx.shader", kind: "shader" });
   return refs;
 }