@ludra/core 0.7.0 → 0.8.0

package/dist/assertions.d.ts

@@ -4,7 +4,7 @@ declare const OPERATORS: readonly ["<=", ">=", "==", "!=", "<", ">"];
 type Operator = (typeof OPERATORS)[number];
 declare const ENTITY_FIELDS: readonly ["x", "y", "vx", "vy", "grounded", "exists"];
 type EntityField = (typeof ENTITY_FIELDS)[number];
-declare const WORLD_FIELDS: readonly ["score", "deaths", "won"];
+declare const WORLD_FIELDS: readonly ["score", "deaths", "won", "lost", "lives"];
 type WorldField = (typeof WORLD_FIELDS)[number];
 type Subject = {
     kind: "world";
@@ -48,6 +48,8 @@ export declare function evaluateAssertion(assertion: Assertion, snapshot: WorldS
 /** 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`. */
@@ -60,6 +62,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 declare function runTest(scene: SceneDef, test: TestCase, options?: WorldOptions): TestResult;
 export {};

package/dist/assertions.js

@@ -5,7 +5,7 @@ import { EVENT_TYPES } from "./types.js";
 import { World } from "./world.js";
 const OPERATORS = ["<=", ">=", "==", "!=", "<", ">"];
 const ENTITY_FIELDS = ["x", "y", "vx", "vy", "grounded", "exists"];
-const WORLD_FIELDS = ["score", "deaths", "won"];
+const WORLD_FIELDS = ["score", "deaths", "won", "lost", "lives"];
 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", "door.state.open == true", "boss.state.phase == \\"angry\\"", "events.shoot >= 3".';
@@ -65,6 +65,9 @@ export function evaluateAssertion(assertion, snapshot, events) {
         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) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
@@ -160,7 +163,7 @@ export function runTest(scene, test, options = {}) {
                 : Math.max(secondsToFrames(defaultDuration(script)), latestAt);
     }
     catch (err) {
-        return { name: test.name, pass: false, duration: 0, results: [], error: err.message };
+        return { name: test.name, pass: false, duration: 0, results: [], error: err.message, events: [] };
     }
     const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
     const snapshots = new Map();
@@ -174,11 +177,12 @@ export function runTest(scene, test, options = {}) {
     }
     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.message };
+        return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: err.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 };
 }

package/dist/browser.d.ts

@@ -6,14 +6,21 @@ 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>;
 }
 /**
  * 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 declare function startGame(canvas: HTMLCanvasElement, scene: SceneDef, options?: GameOptions): Promise<() => void>;
+export declare function startGame(canvas: HTMLCanvasElement, firstScene: SceneDef, options?: GameOptions): Promise<() => void>;
 export interface CaptureOptions extends GameOptions {
     /** Input script, e.g. `"right:1s, jump:0.4s"`. See `InputScript`. */
     inputs?: string;

package/dist/browser.js

@@ -74,63 +74,149 @@ async function loadFonts(scene, assetBase) {
     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, assetBase) {
+    const path = scene.postfx?.shader;
+    if (!path)
+        return undefined;
+    const response = await fetch(assetBase + path).catch((err) => err);
+    if (response instanceof Error)
+        return response;
+    return response.ok ? response.text() : new Error(`could not load ${path} (${response.status})`);
+}
 /**
- * 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.
+ * 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.
  */
-async function prepare(canvas, scene, options) {
-    const ctx = canvas.getContext("2d");
-    if (!ctx)
-        throw new Error("Canvas 2D context is not available.");
+class Screen {
+    ctx;
+    output;
+    canvas;
+    fx;
+    constructor(canvas) {
+        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, shader) {
+        let fx;
+        let error;
+        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) {
+        this.fx?.render(this.canvas, time);
+    }
+}
+/** What a scene needs before it can be drawn. */
+async function loadScene(scene, options, scripts) {
     const assetBase = options.assetBase ?? "";
-    const shaderPath = scene.postfx?.shader;
-    const [images, scripts, shader] = await Promise.all([
+    const [images, more, 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,
+        loadShader(scene, assetBase),
         loadFonts(scene, assetBase),
     ]);
-    const 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;
+    for (const [path, script] of more)
+        scripts.set(path, script);
+    return { images, shader };
 }
 function message(err) {
     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, scene, options = {}) {
-    const { ctx, images, scripts, present, error } = await prepare(canvas, scene, options);
+export async function startGame(canvas, firstScene, options = {}) {
+    const screen = new Screen(canvas);
+    const ctx = screen.ctx;
     const sounds = new SoundPlayer(options.assetBase ?? "");
-    const view = new View(scene, images);
-    let world = new World(scene, { scripts });
-    let crash = error;
+    const scripts = new Map();
+    let scene = firstScene;
+    let startCarry;
+    let view;
+    let world;
+    let crash;
+    let sceneError;
+    /** Real time when the world asked to move on, while waiting to load the next scene. */
+    let exitSince;
+    let loading = false;
+    const enter = async (next, carry) => {
+        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 = error;
+        crash = sceneError;
+        exitSince = undefined;
+    };
+    const moveOn = (path) => {
+        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) => {
+            crash = `Could not load the next scene "${path}": ${message(err)}`;
+        })
+            .finally(() => (loading = false));
     };
     const held = new Set();
     // Keys pressed since the last step. A tap shorter than one frame still reaches the simulation.
@@ -166,7 +252,7 @@ export async function startGame(canvas, scene, options = {}) {
     const frame = (now) => {
         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);
             }
@@ -179,8 +265,18 @@ export async function startGame(canvas, scene, options = {}) {
             view.step(world, (sound) => sounds.play(sound));
             accumulator -= FIXED_DT;
         }
+        // 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);
+            view.draw(ctx, world, sounds.muted, options.loadScene !== undefined);
         }
         catch (err) {
             // A draw hook threw. Same treatment as a simulation error.
@@ -188,9 +284,13 @@ export async function startGame(canvas, scene, options = {}) {
                 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);
-        present(world.time);
+        screen.present(world.time);
         raf = requestAnimationFrame(frame);
     };
     raf = requestAnimationFrame(frame);
@@ -208,7 +308,10 @@ export async function startGame(canvas, scene, options = {}) {
  * `ludra play --screenshot`.
  */
 export async function captureFrames(canvas, scene, options) {
-    const { ctx, output, images, scripts, present, error } = await prepare(canvas, scene, options);
+    const screen = new Screen(canvas);
+    const scripts = new Map();
+    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);
@@ -219,9 +322,9 @@ export async function captureFrames(canvas, scene, options) {
     const captured = [];
     for (let frame = 0;; frame++) {
         if (wanted.has(frame)) {
-            view.draw(ctx, world, false);
-            present(world.time);
-            captured.push({ frame, time: frame * FIXED_DT, png: output.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;
@@ -283,9 +386,12 @@ class View {
     handledEvents = 0;
     scene;
     images;
+    /** Whether the scene can award points at all, so the default HUD can leave the score out. */
+    scoring;
     constructor(scene, images) {
         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() {
         this.particles.clear();
@@ -325,7 +431,8 @@ class View {
         this.particles.update(FIXED_DT);
         this.shake = this.shake < 0.5 ? 0 : this.shake * SHAKE_DECAY;
     }
-    draw(ctx, world, muted) {
+    /** `continues`: the host loads next scenes, so a won scene with `next` says so instead of offering a replay. */
+    draw(ctx, world, muted, continues) {
         const { width: viewWidth, height: viewHeight } = ctx.canvas;
         ctx.imageSmoothingEnabled = false;
         ctx.fillStyle = world.background;
@@ -361,24 +468,34 @@ class View {
                     this.drawHook(ctx, world, e, "drawUI", viewInfo);
             return;
         }
+        // Only what this scene uses: no "Score 0" in a game without points.
+        const parts = [];
+        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);
         }
     }
     drawHook(ctx, world, e, hook, view) {
@@ -484,7 +601,10 @@ function recentEvents(world, name, seconds) {
         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 });
+        // 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;
+        const data = event.type === "custom" ? event.data : details;
+        result.push({ name: eventName, time, x, y, entity, data });
     }
     return result.reverse();
 }

package/dist/components.d.ts

@@ -35,7 +35,7 @@ export interface ComponentSpec {
     /** Fields without a default are required. */
     fields: Record<string, FieldSpec>;
 }
-export declare const COMPONENT_NAMES: readonly ["transform", "body", "sprite", "platformer", "topdown", "collectible", "patrol", "hazard", "goal", "emitter", "script", "camera"];
+export declare const COMPONENT_NAMES: readonly ["transform", "body", "sprite", "platformer", "topdown", "collectible", "patrol", "hazard", "goal", "checkpoint", "emitter", "script", "camera"];
 export type ComponentName = (typeof COMPONENT_NAMES)[number];
 /** Shared by the `emitter` component and the particles of scene `effects`. Purely visual. */
 export declare const PARTICLE_FIELDS: Record<string, FieldSpec>;
@@ -119,6 +119,7 @@ export interface Hazard {
 }
 export interface Goal {
     requireScore: number;
+    next: string;
 }
 export interface Camera {
     zoom: number;

package/dist/components.js

@@ -8,6 +8,7 @@ export const COMPONENT_NAMES = [
     "patrol",
     "hazard",
     "goal",
+    "checkpoint",
     "emitter",
     "script",
     "camera",
@@ -130,8 +131,18 @@ export const COMPONENTS = {
         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"],

package/dist/effects.d.ts

@@ -7,14 +7,14 @@ export declare const AUDIO_EXTENSIONS: readonly [".wav", ".mp3", ".ogg"];
 export declare const IMAGE_EXTENSIONS: readonly [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"];
 export declare const FONT_EXTENSIONS: readonly [".woff2", ".woff", ".ttf", ".otf"];
 export declare const EFFECT_FIELDS: Record<string, FieldSpec>;
-export declare 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.";
+export declare const EFFECTS_DESCRIPTION = "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 declare function isSoundPreset(sound: string): sound is SoundPreset;
 export interface AssetReference {
     /** Path relative to the project, as written in the scene. */
     path: string;
     /** JSON path of the field that references it. */
     at: string;
-    kind: "image" | "audio" | "script" | "font" | "shader";
+    kind: "image" | "audio" | "script" | "font" | "shader" | "scene";
 }
 /** Every file a scene points at, so tools can check that they exist. */
 export declare function collectAssetPaths(scene: SceneDef): AssetReference[];

package/dist/effects.js

@@ -11,7 +11,7 @@ export const EFFECT_FIELDS = {
     },
     shake: { type: "number", min: 0, default: 0, description: "Screen shake strength in pixels." },
 };
-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.';
+export const EFFECTS_DESCRIPTION = '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) {
     return SOUND_PRESETS.includes(sound);
 }
@@ -22,6 +22,9 @@ export function collectAssetPaths(scene) {
         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" });

package/dist/script.d.ts

@@ -27,7 +27,9 @@ export interface ScriptEntity {
 export interface SpawnDef {
     /** Generated when left out. */
     id?: string;
-    components: Record<string, Record<string, unknown>>;
+    /** Start from a prefab; `components` then only needs what differs (usually the transform). */
+    prefab?: string;
+    components?: Record<string, Record<string, unknown>>;
 }
 export interface ScriptWorld {
     readonly time: number;
@@ -39,6 +41,12 @@ export interface ScriptWorld {
     readonly deaths: number;
     /** True once the level is complete. */
     readonly won: boolean;
+    /** Lives left, or undefined when the scene has unlimited retries. Writable: an extra life is `world.lives += 1`. */
+    lives: number | undefined;
+    /** True once the game is over (out of lives, or world.lose()). */
+    readonly lost: boolean;
+    /** The scene this one hands over to (a won goal's next, or world.goto), once it does. */
+    readonly exit: string | undefined;
     get(id: string): ScriptEntity | undefined;
     /** Every entity, or only those with the given component. */
     all(component?: string): ScriptEntity[];
@@ -50,6 +58,14 @@ export interface ScriptWorld {
     kill(entity: ScriptEntity | string): void;
     /** Completes the level, like reaching a goal. */
     win(): void;
+    /** Ends the game as lost (a time limit ran out, the base was destroyed...). Fires "gameover". */
+    lose(): void;
+    /**
+     * Moves on to another scene, e.g. world.goto("scenes/level-1.scene.json") from a title
+     * screen. The current scene stops; the browser loads the next one, keeping score,
+     * deaths and lives. Fires "goto" (tests can assert events.goto).
+     */
+    goto(scene: string): void;
     /** Fires a custom event that tests can count (`events.<name>`) and `effects` can react to. */
     emit(name: string, data?: unknown): void;
     /** A number in [0, 1). Seeded by `world.seed`, so runs stay deterministic. Never use Math.random. */
@@ -79,6 +95,7 @@ export interface DrawEvent {
     y: number;
     /** The entity that caused it. */
     entity: string;
+    /** Custom events: what the script passed to world.emit. Built-in ones: their details, e.g. { checkpoint: "lantern" } or { item: "coin-1", score: 1 }. */
     data?: unknown;
 }
 /**
@@ -148,7 +165,7 @@ export interface Script {
 }
 export declare const SCRIPT_HOOKS: readonly ["start", "update", "touch", "draw", "drawUI"];
 /** Printed by `ludra components script`. Keep in sync with the interfaces above. */
-export declare const SCRIPT_API_REFERENCE = "A script file default-exports hooks. Only \"import type\" is allowed: scripts run without a bundler.\n\n  import type { Script } from \"@ludra/core\";\n  export default {\n    start(ctx) {},           // once, on the entity's first frame\n    update(ctx) {},          // every frame, after player input, before physics\n    touch(ctx, other) {},    // when this entity starts touching another body (after physics)\n    draw(ctx) {},            // paint this entity in world space (browser only, every rendered frame)\n    drawUI(ctx) {},          // paint screen-space UI; replaces the default HUD and win screen\n  } satisfies Script;\n\nctx.self      the entity: id, x, y, vx, vy (read/write); grounded, width, height, exists (read);\n              state (object kept between frames, testable as \"<id>.state.<key>\");\n              has(\"component\"), touches(otherOrId)\nctx.world     time, frame, width, height, deaths, won (read); score (read/write)\n              get(id), all(component?), player()\n              spawn({ id?, components }) -> entity    destroy(entityOrId)\n              kill(entityOrId)  players respawn, others are destroyed\n              win()             completes the level\n              emit(name, data?) custom event: counted by \"events.<name>\" in tests, usable as an effects key\n              random()          deterministic, seeded by world.seed. Never use Math.random or Date\nctx.input     held(action), pressed(action)   actions: left right up down jump action\nctx.params    the \"params\" object from the script component\nctx.dt        seconds per frame (1/60)\n\nDrawing: draw and drawUI get the real Canvas 2D context, so there are no limits on looks.\nctx.g         CanvasRenderingContext2D: gradients, shadowBlur glow, globalCompositeOperation (\"lighter\" for\n              additive light), paths, text with any loaded font, ctx.g.filter, drawImage...\n              draw: origin is the world (use self.x/self.y); drawUI: origin is the screen top-left\nctx.time      simulation seconds; animate with it so screenshots are reproducible\nctx.local     per-entity presentation memory (trails, tweens); not game state\nctx.view      width, height, cameraX, cameraY, zoom\nctx.recent(name?, seconds = 0.5)   recent events [{ name, time, x, y, entity, data }]: flash on hit, pop scores\nctx.image(path)   a loaded image (sprite images and string params ending in .svg/.png/... are preloaded)\nctx.burst(x, y, particles?)  ctx.shake(px)  ctx.random()   presentation-only helpers\nself/world/params as in update, but read-only: changing the game in a draw hook is an error.\n\nScene-level presentation (all optional):\n  \"fonts\": { \"Orbitron\": \"google\", \"Pixel\": \"assets/pixel.woff2\" }   load fonts for ctx.g.font\n  \"postfx\": { \"shader\": \"shaders/crt.frag\", \"uniforms\": { \"strength\": 0.6 } }\n     a GLSL ES 1.0 fragment shader over the whole frame. It gets: uniform sampler2D u_image;\n     uniform vec2 u_resolution; uniform float u_time; varying vec2 v_uv; plus each uniform as a float.\n\nScripts in scripts/ are loaded even if no entity uses them, so world.spawn can attach them.\nErrors name the file, entity, hook and frame.";
+export declare const SCRIPT_API_REFERENCE = "A script file default-exports hooks. Only \"import type\" is allowed: scripts run without a bundler.\n\n  import type { Script } from \"@ludra/core\";\n  export default {\n    start(ctx) {},           // once, on the entity's first frame\n    update(ctx) {},          // every frame, after player input, before physics\n    touch(ctx, other) {},    // when this entity starts touching another body (after physics)\n    draw(ctx) {},            // paint this entity in world space (browser only, every rendered frame)\n    drawUI(ctx) {},          // paint screen-space UI; replaces the default HUD and win screen\n  } satisfies Script;\n\nctx.self      the entity: id, x, y, vx, vy (read/write); grounded, width, height, exists (read);\n              state (object kept between frames, testable as \"<id>.state.<key>\");\n              has(\"component\"), touches(otherOrId)\nctx.world     time, frame, width, height, deaths, won, lost, exit (read); score, lives (read/write)\n              get(id), all(component?), player()\n              spawn({ id?, prefab?, components? }) -> entity    destroy(entityOrId)\n              kill(entityOrId)  players respawn, others are destroyed\n              win()             completes the level        lose()   game over\n              goto(scenePath)   moves on to another scene (title -> level 1, a door to the next room)\n              emit(name, data?) custom event: counted by \"events.<name>\" in tests, usable as an effects key\n              random()          deterministic, seeded by world.seed. Never use Math.random or Date\nctx.input     held(action), pressed(action)   actions: left right up down jump action\nctx.params    the \"params\" object from the script component\nctx.dt        seconds per frame (1/60)\n\nDrawing: draw and drawUI get the real Canvas 2D context, so there are no limits on looks.\nctx.g         CanvasRenderingContext2D: gradients, shadowBlur glow, globalCompositeOperation (\"lighter\" for\n              additive light), paths, text with any loaded font, ctx.g.filter, drawImage...\n              draw: origin is the world (use self.x/self.y); drawUI: origin is the screen top-left\nctx.time      simulation seconds; animate with it so screenshots are reproducible\nctx.local     per-entity presentation memory (trails, tweens); not game state\nctx.view      width, height, cameraX, cameraY, zoom\nctx.recent(name?, seconds = 0.5)   recent events [{ name, time, x, y, entity, data }]: flash on hit, pop scores\nctx.image(path)   a loaded image (sprite images and string params ending in .svg/.png/... are preloaded)\nctx.burst(x, y, particles?)  ctx.shake(px)  ctx.random()   presentation-only helpers\nself/world/params as in update, but read-only: changing the game in a draw hook is an error.\n\nScene-level presentation (all optional):\n  \"fonts\": { \"Orbitron\": \"google\", \"Pixel\": \"assets/pixel.woff2\" }   load fonts for ctx.g.font\n  \"postfx\": { \"shader\": \"shaders/crt.frag\", \"uniforms\": { \"strength\": 0.6 } }\n     a GLSL ES 1.0 fragment shader over the whole frame. It gets: uniform sampler2D u_image;\n     uniform vec2 u_resolution; uniform float u_time; varying vec2 v_uv; plus each uniform as a float.\n\nScripts in scripts/ are loaded even if no entity uses them, so world.spawn can attach them.\nErrors name the file, entity, hook and frame.";
 export type ScriptModules = ReadonlyMap<string, Script> | Readonly<Record<string, Script>>;
 export declare function getScript(modules: ScriptModules | undefined, src: string): Script | undefined;
 /** A script threw, or was used wrongly. Names the file, entity, hook and frame. */

package/dist/script.js

@@ -15,11 +15,12 @@ export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "
 ctx.self      the entity: id, x, y, vx, vy (read/write); grounded, width, height, exists (read);
               state (object kept between frames, testable as "<id>.state.<key>");
               has("component"), touches(otherOrId)
-ctx.world     time, frame, width, height, deaths, won (read); score (read/write)
+ctx.world     time, frame, width, height, deaths, won, lost, exit (read); score, lives (read/write)
               get(id), all(component?), player()
-              spawn({ id?, components }) -> entity    destroy(entityOrId)
+              spawn({ id?, prefab?, components? }) -> entity    destroy(entityOrId)
               kill(entityOrId)  players respawn, others are destroyed
-              win()             completes the level
+              win()             completes the level        lose()   game over
+              goto(scenePath)   moves on to another scene (title -> level 1, a door to the next room)
               emit(name, data?) custom event: counted by "events.<name>" in tests, usable as an effects key
               random()          deterministic, seeded by world.seed. Never use Math.random or Date
 ctx.input     held(action), pressed(action)   actions: left right up down jump action

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type Action = "left" | "right" | "up" | "down" | "jump" | "action";
 export declare const ACTIONS: readonly Action[];
-export declare const EVENT_TYPES: readonly ["jump", "land", "collect", "die", "stomp", "win", "bounce"];
+export declare const EVENT_TYPES: readonly ["jump", "land", "collect", "die", "stomp", "win", "bounce", "checkpoint", "gameover", "goto"];
 export type GameEventType = (typeof EVENT_TYPES)[number];
 /** What happens visually and audibly when a game event fires. See `EFFECT_FIELDS`. */
 export interface EffectDef {
@@ -17,6 +17,8 @@ export interface PostFxDef {
 /** An entity as written in a scene file. */
 export interface EntityDef {
     id: string;
+    /** Name of a prefab to start from. Gone after validation: its components are merged in. */
+    prefab?: string;
     components: Record<string, Record<string, unknown>>;
 }
 export interface WorldSettings {
@@ -28,6 +30,13 @@ export interface WorldSettings {
     background?: string;
     /** Seed for `world.random()` in scripts. Defaults to 1. */
     seed?: number;
+    /** Lives before game over. Leave out for unlimited retries. */
+    lives?: number;
+}
+/** A reusable entity template: `prefabs/<name>.prefab.json` or the scene's `prefabs` map. */
+export interface PrefabDef {
+    description?: string;
+    components: Record<string, Record<string, unknown>>;
 }
 /** A scene file (`*.scene.json`). */
 export interface SceneDef {
@@ -45,6 +54,12 @@ export interface SceneDef {
     fonts?: Record<string, string>;
     /** A GLSL fragment shader applied to every rendered frame. Presentation only. */
     postfx?: PostFxDef;
+    /**
+     * Entity templates by name. Entities use one with `"prefab": "<name>"` and override
+     * components; scripts spawn them with `world.spawn({ prefab: "<name>" })`. The CLI
+     * adds every `prefabs/*.prefab.json` file here.
+     */
+    prefabs?: Record<string, PrefabDef>;
     entities: EntityDef[];
 }
 export interface Diagnostic {

package/dist/types.js

@@ -1,2 +1,2 @@
 export const ACTIONS = ["left", "right", "up", "down", "jump", "action"];
-export const EVENT_TYPES = ["jump", "land", "collect", "die", "stomp", "win", "bounce"];
+export const EVENT_TYPES = ["jump", "land", "collect", "die", "stomp", "win", "bounce", "checkpoint", "gameover", "goto"];