@ludra/core 0.5.0 → 0.7.0

package/dist/world.js

@@ -23,6 +23,8 @@ const STOMP_TOLERANCE = 8;
 const FALL_MARGIN = 100;
 /** Bodies this close count as touching for `touch` hooks, so solids (doors, walls) can be touched too. */
 const TOUCH_MARGIN = 1;
+/** Impacts slower than this (px/s, after bounce) stop instead of bouncing. */
+const MIN_BOUNCE_SPEED = 40;
 const EPSILON = 1e-4;
 /**
  * The simulation. It advances only through `step`, one fixed frame at a time,
@@ -50,6 +52,8 @@ export class World {
     scriptInput = { held: () => false, pressed: () => false };
     /** The script hook currently running, for error messages and event attribution. */
     current;
+    /** True while a draw hook runs: the game can't be changed then. */
+    drawing = false;
     constructor(scene, options = {}) {
         this.width = scene.world?.width ?? 960;
         this.height = scene.world?.height ?? 540;
@@ -80,6 +84,7 @@ export class World {
         if (this.won)
             return;
         this.updatePlatformers(input, pressed);
+        this.updateTopdown(input);
         this.updateScripts(input, pressed);
         if (this.won)
             return;
@@ -171,9 +176,35 @@ export class World {
         if (!fn)
             return;
         const ctx = { self: this.handle(entity), world: this.api(), input: this.scriptInput, params: script.params, dt: FIXED_DT };
+        this.run(entity, hook, () => fn.call(script.module, ctx, other));
+    }
+    /**
+     * Runs an entity's `draw` or `drawUI` hook. Called by the renderer, never by the
+     * simulation. `self` and `world` are read-only for the duration.
+     */
+    callDrawHook(entity, hook, extras) {
+        const script = entity.script;
+        const fn = script?.module[hook];
+        if (!script || !fn || entity.removed)
+            return;
+        const ctx = { ...extras, self: this.handle(entity), world: this.api(), params: script.params };
+        this.drawing = true;
+        try {
+            this.run(entity, hook, () => fn.call(script.module, ctx));
+        }
+        finally {
+            this.drawing = false;
+        }
+    }
+    /** True when any live entity's script has the given hook. */
+    hasHook(hook) {
+        return this.entities.some((e) => !e.removed && typeof e.script?.module[hook] === "function");
+    }
+    run(entity, hook, call) {
+        const script = entity.script;
         this.current = { entity, hook };
         try {
-            fn.call(script.module, ctx, other);
+            call();
         }
         catch (err) {
             if (err instanceof ScriptError)
@@ -185,6 +216,12 @@ export class World {
             this.current = undefined;
         }
     }
+    /** Draw hooks only paint, so the browser can't drift from what tests verified. */
+    guard(what) {
+        if (this.drawing) {
+            throw this.misuse(`${what} changes the game, which a draw hook can't do. Change the game in update or touch, and keep visual memory in ctx.local.`);
+        }
+    }
     /** An error caused by how a script used the API, reported against the running script. */
     misuse(message) {
         const running = this.current;
@@ -204,18 +241,21 @@ export class World {
                 return e.transform.x;
             },
             set x(value) {
+                world.guard("Setting x");
                 e.transform.x = value;
             },
             get y() {
                 return e.transform.y;
             },
             set y(value) {
+                world.guard("Setting y");
                 e.transform.y = value;
             },
             get vx() {
                 return e.body?.vx ?? 0;
             },
             set vx(value) {
+                world.guard("Setting vx");
                 if (e.body)
                     e.body.vx = value;
             },
@@ -223,6 +263,7 @@ export class World {
                 return e.body?.vy ?? 0;
             },
             set vy(value) {
+                world.guard("Setting vy");
                 if (e.body)
                     e.body.vy = value;
             },
@@ -239,7 +280,8 @@ export class World {
                 return !e.removed;
             },
             get state() {
-                return e.state;
+                // A frozen copy while drawing, so a draw hook can't write game state by accident.
+                return world.drawing ? Object.freeze({ ...e.state }) : e.state;
             },
             has(component) {
                 return component === "transform" || (component in e && e[component] !== undefined);
@@ -276,7 +318,14 @@ export class World {
             get score() {
                 return world.score;
             },
+            get deaths() {
+                return world.deaths;
+            },
+            get won() {
+                return world.won;
+            },
             set score(value) {
+                world.guard("Setting score");
                 world.score = value;
             },
             get: (id) => {
@@ -285,25 +334,31 @@ export class World {
             },
             all: (component) => world.entities.filter((e) => !component || world.handle(e).has(component)).map((e) => world.handle(e)),
             player: () => {
-                const e = world.entities.find((candidate) => candidate.platformer);
+                const e = world.entities.find(isPlayer);
                 return e ? world.handle(e) : undefined;
             },
-            spawn: (def) => world.spawn(def),
+            spawn: (def) => {
+                world.guard("world.spawn");
+                return world.spawn(def);
+            },
             destroy: (target) => {
+                world.guard("world.destroy");
                 const e = world.resolve(target);
                 if (e)
                     world.remove(e);
             },
             kill: (target) => {
+                world.guard("world.kill");
                 const e = world.resolve(target);
                 if (!e)
                     return;
-                if (e.platformer && e.body)
+                if (isPlayer(e))
                     world.kill(e, world.current?.entity.id ?? "script");
                 else
                     world.remove(e);
             },
             win: () => {
+                world.guard("world.win");
                 if (world.won)
                     return;
                 const by = world.current?.entity;
@@ -311,6 +366,7 @@ export class World {
                 world.emit({ type: "win", entity: by?.id ?? "script", goal: by?.id ?? "script", x: by?.transform.x ?? 0, y: by?.transform.y ?? 0 });
             },
             emit: (name, data) => {
+                world.guard("world.emit");
                 if (typeof name !== "string" || name === "")
                     throw world.misuse("world.emit needs a non-empty event name.");
                 if (EVENT_TYPES.includes(name)) {
@@ -319,7 +375,10 @@ export class World {
                 const by = world.current?.entity;
                 world.emit({ type: "custom", name, entity: by?.id ?? "script", data, x: by?.transform.x ?? 0, y: by?.transform.y ?? 0 });
             },
-            random: () => world.random(),
+            random: () => {
+                world.guard("world.random (it advances the game's seed; use ctx.random in draw hooks)");
+                return world.random();
+            },
         };
         return this.scriptApi;
     }
@@ -349,13 +408,36 @@ export class World {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     }
     // ------------------------------------------------------------ built-ins
+    /** Entities the player controls: platformers and topdown movers. */
     players() {
-        return this.entities.filter((e) => e.platformer && e.body);
+        return this.entities.filter(isPlayer);
+    }
+    updateTopdown(held) {
+        for (const e of this.entities) {
+            const t = e.topdown;
+            const b = e.body;
+            if (!t || !b)
+                continue;
+            let dx = (held.has("right") ? 1 : 0) - (held.has("left") ? 1 : 0);
+            let dy = (held.has("down") ? 1 : 0) - (held.has("up") ? 1 : 0);
+            if (t.directions === "x")
+                dy = 0;
+            if (t.directions === "y")
+                dx = 0;
+            if (t.directions === "4" && dx !== 0)
+                dy = 0;
+            // Diagonals move at the same speed as straight lines.
+            const length = Math.hypot(dx, dy) || 1;
+            b.vx = (dx / length) * t.speed;
+            b.vy = (dy / length) * t.speed;
+        }
     }
     updatePlatformers(held, pressed) {
-        for (const e of this.players()) {
+        for (const e of this.entities) {
             const p = e.platformer;
             const b = e.body;
+            if (!p || !b)
+                continue;
             const direction = (held.has("right") ? 1 : 0) - (held.has("left") ? 1 : 0);
             b.vx = direction * p.speed;
             // Timers get a tiny extra margin so a value of 0 still allows a jump on the exact frame.
@@ -404,15 +486,27 @@ export class World {
     updateBodies() {
         // Kinematic bodies move first, so anything standing on them can follow.
         const moved = new Map();
+        const walls = this.entities.filter((e) => e.body?.type === "static" && !e.body.sensor);
         for (const e of this.entities) {
             const b = e.body;
             if (!b || b.type !== "kinematic")
                 continue;
             const { x, y } = e.transform;
             e.transform.x += b.vx * FIXED_DT;
+            // A player-steered kinematic body (a paddle) stops at walls; scripted movers pass through.
+            if (e.topdown)
+                for (const wall of walls)
+                    if (overlaps(e, wall))
+                        e.transform.x = wall.transform.x + (Math.sign(e.transform.x - wall.transform.x) * (wall.body.width + b.width)) / 2;
             e.transform.y += b.vy * FIXED_DT;
+            if (e.topdown)
+                for (const wall of walls)
+                    if (overlaps(e, wall))
+                        e.transform.y = wall.transform.y + (Math.sign(e.transform.y - wall.transform.y) * (wall.body.height + b.height)) / 2;
             if (e.patrol)
                 clampToPatrol(e, e.patrol);
+            if (e.topdown?.clampToWorld)
+                this.clampToWorld(e);
             moved.set(e, { dx: e.transform.x - x, dy: e.transform.y - y });
         }
         const solids = this.entities.filter((e) => e.body && !e.body.sensor && e.body.type !== "dynamic");
@@ -425,7 +519,9 @@ export class World {
                 e.transform.x += carried.dx;
                 e.transform.y += carried.dy;
             }
-            b.vy = Math.min(b.vy + this.gravity * b.gravityScale * FIXED_DT, MAX_FALL_SPEED);
+            // Top-down movers ignore gravity; everything else falls.
+            if (!e.topdown)
+                b.vy = Math.min(b.vy + this.gravity * b.gravityScale * FIXED_DT, MAX_FALL_SPEED);
             const wasGrounded = b.grounded;
             b.grounded = false;
             b.standingOn = undefined;
@@ -439,27 +535,48 @@ export class World {
                     e.transform.x = solid.transform.x - half;
                 else if (b.vx < 0)
                     e.transform.x = solid.transform.x + half;
-                b.vx = 0;
+                b.vx = this.rebound(e, solid, b.vx);
             }
             e.transform.y += b.vy * FIXED_DT;
             for (const solid of solids) {
                 if (!overlaps(e, solid))
                     continue;
                 const half = (solid.body.height + b.height) / 2;
-                if (b.vy > 0) {
+                const falling = b.vy > 0;
+                if (b.vy > 0)
                     e.transform.y = solid.transform.y - half;
+                else if (b.vy < 0)
+                    e.transform.y = solid.transform.y + half;
+                b.vy = this.rebound(e, solid, b.vy);
+                // A body that stopped on top of something is standing on it; one that bounced off is airborne.
+                if (falling && b.vy === 0) {
                     b.grounded = true;
                     b.standingOn = solid;
                 }
-                else if (b.vy < 0) {
-                    e.transform.y = solid.transform.y + half;
-                }
-                b.vy = 0;
             }
+            if (e.topdown?.clampToWorld)
+                this.clampToWorld(e);
             if (b.grounded && !wasGrounded)
                 this.emit({ type: "land", entity: e.id, ...feet(e) });
         }
     }
+    /**
+     * The velocity along one axis after hitting `solid`: 0, or reversed and scaled by `bounce`.
+     * Slow impacts stop instead, so resting bodies don't jitter.
+     */
+    rebound(e, solid, velocity) {
+        const bounce = e.body.bounce;
+        if (bounce <= 0 || Math.abs(velocity) * bounce < MIN_BOUNCE_SPEED)
+            return 0;
+        this.emit({ type: "bounce", entity: e.id, other: solid.id, ...e.transform });
+        return -velocity * bounce;
+    }
+    clampToWorld(e) {
+        const halfWidth = (e.body?.width ?? 0) / 2;
+        const halfHeight = (e.body?.height ?? 0) / 2;
+        e.transform.x = Math.min(this.width - halfWidth, Math.max(halfWidth, e.transform.x));
+        e.transform.y = Math.min(this.height - halfHeight, Math.max(halfHeight, e.transform.y));
+    }
     updateCollectibles() {
         const players = this.players();
         for (const item of this.entities.filter((e) => e.collectible && e.body)) {
@@ -481,7 +598,7 @@ export class World {
             for (const hazard of this.entities.filter((e) => e.hazard && e.body)) {
                 if (!overlaps(player, hazard))
                     continue;
-                if (hazard.hazard.stompable && isStomp(player, hazard)) {
+                if (hazard.hazard.stompable && player.platformer && isStomp(player, hazard)) {
                     this.remove(hazard);
                     b.vy = -player.platformer.jumpSpeed * STOMP_BOUNCE;
                     this.score += hazard.hazard.score;
@@ -508,18 +625,20 @@ export class World {
     /** Sends a player back to where it started. Collected items stay collected. */
     kill(player, cause) {
         const b = player.body;
-        const p = player.platformer;
         this.deaths++;
         this.emit({ type: "die", entity: player.id, cause, ...player.transform });
-        player.transform.x = p.spawnX;
-        player.transform.y = p.spawnY;
+        player.transform.x = player.spawn?.x ?? player.transform.x;
+        player.transform.y = player.spawn?.y ?? player.transform.y;
         b.vx = 0;
         b.vy = 0;
         b.grounded = false;
         b.standingOn = undefined;
-        p.coyoteTimer = 0;
-        p.bufferTimer = 0;
-        p.jumping = false;
+        const p = player.platformer;
+        if (p) {
+            p.coyoteTimer = 0;
+            p.bufferTimer = 0;
+            p.jumping = false;
+        }
     }
 }
 function createEntity(def) {
@@ -536,10 +655,12 @@ function createEntity(def) {
             coyoteTimer: 0,
             bufferTimer: 0,
             jumping: false,
-            spawnX: transform.x,
-            spawnY: transform.y,
         };
     }
+    if (c.topdown)
+        entity.topdown = resolveComponent("topdown", c.topdown);
+    if (entity.platformer || entity.topdown)
+        entity.spawn = { x: transform.x, y: transform.y };
     if (c.collectible)
         entity.collectible = resolveComponent("collectible", c.collectible);
     if (c.patrol)
@@ -554,6 +675,9 @@ function createEntity(def) {
         entity.camera = resolveComponent("camera", c.camera);
     return entity;
 }
+function isPlayer(e) {
+    return !!(e.platformer || e.topdown) && !!e.body;
+}
 function feet(e) {
     return { x: e.transform.x, y: e.transform.y + (e.body?.height ?? 0) / 2 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Ludra engine runtime: scene format, validation, deterministic simulation and rendering.",
   "license": "MIT",
   "repository": {

package/src/ascii.ts

@@ -48,8 +48,8 @@ export function renderAscii(world: World, options: AsciiOptions = {}): string {
     ["G", (e) => !!e.goal],
     ["^", (e) => !!e.hazard && e.body!.type !== "kinematic"],
     ["E", (e) => !!e.hazard && e.body!.type === "kinematic"],
-    ["D", (e) => e.body!.type === "dynamic" && !e.platformer],
-    ["@", (e) => !!e.platformer],
+    ["D", (e) => e.body!.type === "dynamic" && !e.platformer && !e.topdown],
+    ["@", (e) => !!(e.platformer || e.topdown)],
   ];
   for (const [char, test] of passes) {
     for (const e of withBody.filter(test)) paint(e, char);

package/src/browser.ts

@@ -3,7 +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 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";
@@ -52,6 +53,88 @@ 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))]);
+}
+
+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);
+}
+
 /**
  * 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
@@ -59,19 +142,16 @@ async function loadScripts(scene: SceneDef, options: GameOptions): Promise<Map<s
  * 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 { 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, { scripts });
-  let crash: string | undefined;
+  let crash: string | undefined = error;
   const restart = () => {
     world = new World(scene, { scripts });
     view.reset();
-    crash = undefined;
+    crash = error;
   };
 
   const held = new Set<Action>();
@@ -110,15 +190,22 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
         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);
+    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);
@@ -152,9 +239,8 @@ 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 { 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, { scripts });
   const script = InputScript.parse(options.inputs ?? "");
@@ -165,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));
@@ -228,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;
@@ -242,6 +331,7 @@ class View {
     this.particles.clear();
     this.facing.clear();
     this.emitTimers.clear();
+    this.local.clear();
     this.shake = 0;
     this.handledEvents = 0;
   }
@@ -278,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;
@@ -289,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";
@@ -319,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;
@@ -390,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";