@ludra/core 0.5.0 → 0.8.0

package/dist/world.js

@@ -2,7 +2,7 @@ import { resolveComponent, } from "./components.js";
 import { getScript, ScriptError, } from "./script.js";
 import { FIXED_DT } from "./time.js";
 import { EVENT_TYPES } from "./types.js";
-import { validateScene } from "./validate.js";
+import { mergeComponents, validateScene } from "./validate.js";
 export class SceneValidationError extends Error {
     diagnostics;
     constructor(diagnostics) {
@@ -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,
@@ -41,6 +43,14 @@ export class World {
     deaths = 0;
     /** Set when a player reaches a goal. The simulation stops changing after that. */
     won = false;
+    /** Set when the game is over: out of lives, or a script called world.lose(). */
+    lost = false;
+    /** Lives left, or undefined for unlimited retries. */
+    lives;
+    /** The scene to play next (a won goal's `next`, or world.goto). Hosts that can load scenes move on to it. */
+    exit;
+    prefabs;
+    reached = new Set();
     previousInput = new Set();
     scripts;
     seed;
@@ -50,6 +60,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;
@@ -57,6 +69,10 @@ export class World {
         this.background = scene.world?.background ?? "#1d2333";
         this.seed = scene.world?.seed ?? 1;
         this.scripts = options.scripts;
+        this.prefabs = scene.prefabs ?? {};
+        this.score = options.carry?.score ?? 0;
+        this.deaths = options.carry?.deaths ?? 0;
+        this.lives = options.carry?.lives ?? scene.world?.lives;
         this.entities = scene.entities.map((def) => this.createEntity(def));
     }
     /** Validates raw scene JSON and builds a world, throwing on errors. */
@@ -69,6 +85,10 @@ export class World {
     get time() {
         return this.frame * FIXED_DT;
     }
+    /** True once nothing more happens in this scene: won, lost, or moving on to another scene. */
+    get over() {
+        return this.won || this.lost || this.exit !== undefined;
+    }
     get(id) {
         return this.entities.find((e) => e.id === id);
     }
@@ -77,19 +97,23 @@ export class World {
         const pressed = new Set([...input].filter((action) => !this.previousInput.has(action)));
         this.previousInput = new Set(input);
         this.frame++;
-        if (this.won)
+        if (this.over)
             return;
         this.updatePlatformers(input, pressed);
+        this.updateTopdown(input);
         this.updateScripts(input, pressed);
-        if (this.won)
+        if (this.over)
             return;
         this.updatePatrols();
         this.updateBodies();
         this.updateTouches();
-        if (this.won)
+        if (this.over)
             return;
         this.updateCollectibles();
+        this.updateCheckpoints();
         this.updateHazards();
+        if (this.over)
+            return;
         this.updateGoals();
     }
     snapshot() {
@@ -106,7 +130,7 @@ export class World {
             if (Object.keys(e.state).length > 0)
                 entities[e.id].state = JSON.parse(JSON.stringify(e.state));
         }
-        return { frame: this.frame, time: this.time, score: this.score, deaths: this.deaths, won: this.won, entities };
+        return { frame: this.frame, time: this.time, score: this.score, deaths: this.deaths, won: this.won, lost: this.lost, lives: this.lives, entities };
     }
     emit(event) {
         this.events.push({ ...event, frame: this.frame, time: this.time });
@@ -141,9 +165,9 @@ export class World {
                 e.script.started = true;
                 this.callHook(e, "start");
             }
-            if (!e.removed && !this.won)
+            if (!e.removed && !this.over)
                 this.callHook(e, "update");
-            if (this.won)
+            if (this.over)
                 return;
         }
     }
@@ -171,9 +195,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 +235,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 +260,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 +282,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 +299,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 +337,31 @@ export class World {
             get score() {
                 return world.score;
             },
+            get deaths() {
+                return world.deaths;
+            },
+            get won() {
+                return world.won;
+            },
+            get lost() {
+                return world.lost;
+            },
+            get exit() {
+                return world.exit;
+            },
+            get lives() {
+                return world.lives;
+            },
+            set lives(value) {
+                world.guard("Setting lives");
+                if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))
+                    throw world.misuse("world.lives must be a number.");
+                world.lives = value;
+                if (value !== undefined && value <= 0)
+                    world.gameOver(world.current?.entity.id ?? "script", "script");
+            },
             set score(value) {
+                world.guard("Setting score");
                 world.score = value;
             },
             get: (id) => {
@@ -285,32 +370,53 @@ 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;
                 world.won = true;
                 world.emit({ type: "win", entity: by?.id ?? "script", goal: by?.id ?? "script", x: by?.transform.x ?? 0, y: by?.transform.y ?? 0 });
             },
+            lose: () => {
+                world.guard("world.lose");
+                world.gameOver(world.current?.entity.id ?? "script", "script");
+            },
+            goto: (scene) => {
+                world.guard("world.goto");
+                if (typeof scene !== "string" || scene === "")
+                    throw world.misuse('world.goto needs a scene path, e.g. "scenes/level-1.scene.json".');
+                if (world.exit !== undefined)
+                    return;
+                world.exit = scene;
+                const by = world.current?.entity;
+                world.emit({ type: "goto", entity: by?.id ?? "script", scene, 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,24 +425,36 @@ 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;
     }
     spawn(def) {
-        if (typeof def !== "object" || def === null || typeof def.components !== "object") {
-            throw this.misuse('world.spawn needs { components: { ... } }, e.g. { components: { transform: { x: 0, y: 0 } } }.');
+        if (typeof def !== "object" || def === null || (def.prefab === undefined && typeof def.components !== "object")) {
+            throw this.misuse('world.spawn needs { components: { ... } } or { prefab: "name" }, e.g. { prefab: "bullet", components: { transform: { x: 0, y: 0 } } }.');
+        }
+        let components = def.components ?? {};
+        if (def.prefab !== undefined) {
+            const prefab = this.prefabs[def.prefab];
+            if (!prefab) {
+                const names = Object.keys(this.prefabs);
+                throw this.misuse(`world.spawn: prefab "${def.prefab}" does not exist.${names.length > 0 ? ` Prefabs: ${names.join(", ")}.` : " Create prefabs/<name>.prefab.json."}`);
+            }
+            components = mergeComponents(prefab.components, components);
         }
         const id = def.id ?? `${this.current?.entity.id ?? "spawned"}-${++this.spawnCount}`;
         if (this.get(id))
             throw this.misuse(`world.spawn: an entity with id "${id}" already exists. Leave id out to get a unique one.`);
-        const { diagnostics } = validateScene({ entities: [{ id, components: def.components }] });
+        const { diagnostics } = validateScene({ entities: [{ id, components }] });
         const errors = diagnostics.filter((d) => d.severity === "error" && d.code !== "E_GOAL_UNREACHABLE");
         if (errors.length > 0) {
             const details = errors.map((d) => `${d.path.replace("entities[0]", id)}: ${d.message}${d.fix ? ` Fix: ${d.fix}` : ""}`);
             throw this.misuse(`world.spawn got an invalid entity. ${details.join(" ")}`);
         }
-        const entity = this.createEntity({ id, components: def.components });
+        const entity = this.createEntity({ id, components });
         this.entities.push(entity);
         return this.handle(entity);
     }
@@ -349,13 +467,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 +545,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 +578,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 +594,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 +657,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;
@@ -501,25 +677,56 @@ export class World {
             if (!player)
                 continue;
             this.won = true;
+            if (goal.goal.next)
+                this.exit = goal.goal.next;
             this.emit({ type: "win", entity: player.id, goal: goal.id, ...goal.transform });
             return;
         }
     }
+    /** A touched checkpoint becomes the player's respawn point, standing on the checkpoint's bottom edge. */
+    updateCheckpoints() {
+        for (const checkpoint of this.entities.filter((e) => e.checkpoint && e.body)) {
+            for (const player of this.players()) {
+                const key = `${player.id}>${checkpoint.id}`;
+                if (this.reached.has(key) || !overlaps(player, checkpoint))
+                    continue;
+                this.reached.add(key);
+                const bottom = checkpoint.transform.y + checkpoint.body.height / 2;
+                player.spawn = { x: checkpoint.transform.x, y: player.platformer ? bottom - player.body.height / 2 : checkpoint.transform.y };
+                this.emit({ type: "checkpoint", entity: player.id, checkpoint: checkpoint.id, ...checkpoint.transform });
+            }
+        }
+    }
+    gameOver(entity, cause) {
+        if (this.lost)
+            return;
+        this.lost = true;
+        const e = this.get(entity);
+        this.emit({ type: "gameover", entity, cause, x: e?.transform.x ?? 0, y: e?.transform.y ?? 0 });
+    }
     /** 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;
+        if (this.lives !== undefined) {
+            this.lives--;
+            // Out of lives: the player stays where it fell and the game is over.
+            if (this.lives <= 0)
+                return this.gameOver(player.id, cause);
+        }
+        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 +743,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)
@@ -548,12 +757,17 @@ function createEntity(def) {
         entity.hazard = resolveComponent("hazard", c.hazard);
     if (c.goal)
         entity.goal = resolveComponent("goal", c.goal);
+    if (c.checkpoint)
+        entity.checkpoint = {};
     if (c.emitter)
         entity.emitter = resolveComponent("emitter", c.emitter);
     if (c.camera)
         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.8.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/assertions.ts

@@ -10,7 +10,7 @@ type Operator = (typeof OPERATORS)[number];
 const ENTITY_FIELDS = ["x", "y", "vx", "vy", "grounded", "exists"] as const;
 type EntityField = (typeof ENTITY_FIELDS)[number];
 
-const WORLD_FIELDS = ["score", "deaths", "won"] as const;
+const WORLD_FIELDS = ["score", "deaths", "won", "lost", "lives"] as const;
 type WorldField = (typeof WORLD_FIELDS)[number];
 
 type Subject =
@@ -100,6 +100,9 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
     case "world":
       actual = snapshot[subject.field];
       label = subject.field;
+      if (actual === undefined) {
+        return { source, pass: false, actual, time, message: `${label} is not set: the scene has unlimited retries. Add "lives" to "world" to count them.` };
+      }
       break;
     case "events": {
       const matches = (e: GameEvent) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
@@ -184,6 +187,8 @@ function round(n: number): number {
 /** One case in a `tests/*.test.json` file. */
 export interface TestCase {
   name: string;
+  /** Scene to run, relative to the project. Defaults to the entry scene in ludra.json. */
+  scene?: string;
   /** Input script, see `InputScript`. */
   inputs?: string;
   /** Run length, e.g. "3s". Defaults to the inputs plus one second, or the latest `at`. */
@@ -197,6 +202,8 @@ export interface TestResult {
   duration: number;
   results: AssertionResult[];
   error?: string;
+  /** Names of the events that fired during the run (built-in types and custom names). */
+  events: string[];
 }
 
 export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions = {}): TestResult {
@@ -215,7 +222,7 @@ export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions =
         ? secondsToFrames(typeof test.duration === "number" ? test.duration : parseDuration(test.duration))
         : Math.max(secondsToFrames(defaultDuration(script)), latestAt);
   } catch (err) {
-    return { name: test.name, pass: false, duration: 0, results: [], error: (err as Error).message };
+    return { name: test.name, pass: false, duration: 0, results: [], error: (err as Error).message, events: [] };
   }
 
   const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
@@ -228,12 +235,13 @@ export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions =
     });
   } 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 };
+    return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: (err as Error).message, events: [] };
   }
 
   const results = assertions.map((a) => {
     const frame = a.at === "end" ? frames : Math.min(a.at, frames);
     return evaluateAssertion(a, snapshots.get(frame)!, world.events);
   });
-  return { name: test.name, pass: results.every((r) => r.pass), duration: frames * FIXED_DT, results };
+  const events = [...new Set(world.events.map((e) => (e.type === "custom" ? e.name : e.type)))];
+  return { name: test.name, pass: results.every((r) => r.pass), duration: frames * FIXED_DT, results, events };
 }