@ludra/core 0.5.0 → 0.8.0

package/dist/ascii.js

@@ -39,8 +39,8 @@ export function renderAscii(world, options = {}) {
         ["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))

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

@@ -11,6 +11,7 @@ import { parseFrames } from "./components.js";
 import { collectAssetPaths } from "./effects.js";
 import { InputScript } from "./input.js";
 import { ParticleSystem } from "./particles.js";
+import { PostFx } from "./postfx.js";
 import { FIXED_DT } from "./time.js";
 import { World } from "./world.js";
 const KEYMAP = {
@@ -44,26 +45,178 @@ async function loadScripts(scene, options) {
     }));
     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, assetBase) {
+    const fonts = Object.entries(scene.fonts ?? {});
+    if (fonts.length === 0)
+        return;
+    const load = async ([family, src]) => {
+        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.add(await face.load());
+        }
+    };
+    const all = Promise.all(fonts.map((font) => load(font).catch((err) => console.warn(`[ludra] could not load font "${font[0]}": ${err}`))));
+    await Promise.race([all, new Promise((resolve) => setTimeout(resolve, 4000))]);
+}
+/** A scene's postfx shader source, or why it couldn't be fetched. */
+async function loadShader(scene, 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})`);
+}
+/**
+ * The canvas players see. The game always draws into the 2D canvas; when a scene
+ * has `postfx`, a WebGL canvas running its shader takes the 2D canvas's place in
+ * the page, and goes away again for a scene without one.
+ */
+class Screen {
+    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 [images, more, shader] = await Promise.all([
+        loadImages(scene, assetBase),
+        loadScripts(scene, options),
+        loadShader(scene, assetBase),
+        loadFonts(scene, assetBase),
+    ]);
+    for (const [path, script] of more)
+        scripts.set(path, script);
+    return { images, shader };
+}
+function message(err) {
+    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 = canvas.getContext("2d");
-    if (!ctx)
-        throw new Error("Canvas 2D context is not available.");
-    const assetBase = options.assetBase ?? "";
-    const [images, scripts] = await Promise.all([loadImages(scene, assetBase), loadScripts(scene, options)]);
-    const sounds = new SoundPlayer(assetBase);
-    const view = new View(scene, images);
-    let world = new World(scene, { scripts });
+export async function startGame(canvas, firstScene, options = {}) {
+    const screen = new Screen(canvas);
+    const ctx = screen.ctx;
+    const sounds = new SoundPlayer(options.assetBase ?? "");
+    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 = undefined;
+        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.
@@ -99,22 +252,45 @@ 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);
             }
             catch (err) {
                 // A script threw: freeze the game and show why, instead of failing silently.
-                crash = err instanceof Error ? err.message : String(err);
+                crash = message(err);
                 console.error("[ludra]", err);
             }
             tapped.clear();
             view.step(world, (sound) => sounds.play(sound));
             accumulator -= FIXED_DT;
         }
-        view.draw(ctx, world, sounds.muted);
+        // Moving on: let the win screen show, or fade out for a world.goto, then load.
+        let fade = 0;
+        if (world.exit !== undefined && options.loadScene && !crash) {
+            exitSince ??= now;
+            const pause = world.won ? WIN_PAUSE : GOTO_FADE;
+            const elapsed = (now - exitSince) / 1000;
+            fade = Math.min(1, Math.max(0, (elapsed - (pause - GOTO_FADE)) / GOTO_FADE));
+            if (elapsed >= pause && !loading)
+                moveOn(world.exit);
+        }
+        try {
+            view.draw(ctx, world, sounds.muted, options.loadScene !== undefined);
+        }
+        catch (err) {
+            // A draw hook threw. Same treatment as a simulation error.
+            if (!crash)
+                console.error("[ludra]", err);
+            crash ??= message(err);
+        }
+        if (fade > 0 || loading) {
+            ctx.fillStyle = `rgba(0, 0, 0, ${loading ? 1 : fade})`;
+            ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+        }
         if (crash)
             drawCrash(ctx, crash);
+        screen.present(world.time);
         raf = requestAnimationFrame(frame);
     };
     raf = requestAnimationFrame(frame);
@@ -132,10 +308,12 @@ export async function startGame(canvas, scene, options = {}) {
  * `ludra play --screenshot`.
  */
 export async function captureFrames(canvas, scene, options) {
-    const ctx = canvas.getContext("2d");
-    if (!ctx)
-        throw new Error("Canvas 2D context is not available.");
-    const [images, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
+    const screen = new Screen(canvas);
+    const scripts = new Map();
+    const { images, shader } = await loadScene(scene, options, scripts);
+    const error = screen.use(scene.postfx, shader);
+    if (error)
+        throw new Error(error);
     const view = new View(scene, images);
     const world = new World(scene, { scripts });
     const script = InputScript.parse(options.inputs ?? "");
@@ -144,8 +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);
-            captured.push({ frame, time: frame * FIXED_DT, png: canvas.toDataURL("image/png") });
+            view.draw(screen.ctx, world, false, false);
+            screen.present(world.time);
+            captured.push({ frame, time: frame * FIXED_DT, png: screen.output.toDataURL("image/png") });
         }
         if (frame >= last)
             break;
@@ -201,18 +380,24 @@ class View {
     facing = new Map();
     emitTimers = new Map();
     frameCache = new Map();
+    /** ctx.local for each entity's draw hooks. */
+    local = new Map();
     shake = 0;
     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();
         this.facing.clear();
         this.emitTimers.clear();
+        this.local.clear();
         this.shake = 0;
         this.handledEvents = 0;
     }
@@ -246,12 +431,13 @@ 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;
         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;
@@ -261,32 +447,80 @@ class View {
             cameraX += (this.particles.random() - 0.5) * 2 * this.shake;
             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) => e.sprite?.layer ?? 0;
+        const visible = world.entities.filter((e) => e.sprite || e.script?.module.draw).sort((a, b) => layer(a) - layer(b));
+        for (const e of visible) {
+            if (e.sprite)
+                this.drawSprite(ctx, e, world.time);
+            if (e.script?.module.draw)
+                this.drawHook(ctx, world, e, "draw", viewInfo);
+        }
         this.particles.draw(ctx);
         ctx.restore();
+        if (world.hasHook("drawUI")) {
+            // The game draws its own interface.
+            for (const e of [...world.entities])
+                if (e.script?.module.drawUI)
+                    this.drawHook(ctx, world, e, "drawUI", viewInfo);
+            return;
+        }
+        // Only what this scene uses: no "Score 0" in a game without points.
+        const parts = [];
+        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) {
+        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();
         }
     }
     drawSprite(ctx, e, time) {
@@ -356,6 +590,24 @@ class View {
         return [0];
     }
 }
+function recentEvents(world, name, seconds) {
+    const since = world.time - seconds;
+    const result = [];
+    // Events are in time order, so walk back until they get too old.
+    for (let i = world.events.length - 1; i >= 0; i--) {
+        const event = world.events[i];
+        if (event.time < since)
+            break;
+        const eventName = event.type === "custom" ? event.name : event.type;
+        if (name !== undefined && eventName !== name)
+            continue;
+        // Custom events carry what the script passed; built-in ones their own details (item, enemy, checkpoint...).
+        const { type: _type, frame: _frame, time, x, y, entity, ...details } = event;
+        const data = event.type === "custom" ? event.data : details;
+        result.push({ name: eventName, time, x, y, entity, data });
+    }
+    return result.reverse();
+}
 function animationState(e) {
     const b = e.body;
     if (!b)

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", "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>;
@@ -55,6 +55,7 @@ export interface Body {
     height: number;
     sensor: boolean;
     gravityScale: number;
+    bounce: number;
     vx: number;
     vy: number;
 }
@@ -99,6 +100,11 @@ export interface Platformer {
     jumpBuffer: number;
     variableJump: boolean;
 }
+export interface Topdown {
+    speed: number;
+    directions: "8" | "4" | "x" | "y";
+    clampToWorld: boolean;
+}
 export interface Collectible {
     score: number;
 }
@@ -113,6 +119,7 @@ export interface Hazard {
 }
 export interface Goal {
     requireScore: number;
+    next: string;
 }
 export interface Camera {
     zoom: number;

package/dist/components.js

@@ -3,10 +3,12 @@ export const COMPONENT_NAMES = [
     "body",
     "sprite",
     "platformer",
+    "topdown",
     "collectible",
     "patrol",
     "hazard",
     "goal",
+    "checkpoint",
     "emitter",
     "script",
     "camera",
@@ -44,6 +46,12 @@ export const COMPONENTS = {
             height: { type: "number", min: 1, description: "Collider height in pixels." },
             sensor: { type: "boolean", default: false, description: "Sensors detect overlaps but never block movement (coins, triggers)." },
             gravityScale: { type: "number", default: 1, description: "Multiplier on world gravity for dynamic bodies." },
+            bounce: {
+                type: "number",
+                min: 0,
+                default: 0,
+                description: "How much speed a dynamic body keeps when it hits a solid: 0 stops it, 1 bounces it back at full speed (balls, pinballs).",
+            },
             vx: { type: "number", default: 0, description: "Initial horizontal velocity in px/s." },
             vy: { type: "number", default: 0, description: "Initial vertical velocity in px/s." },
         },
@@ -80,8 +88,22 @@ export const COMPONENTS = {
             variableJump: { type: "boolean", default: true, description: "Releasing jump early cuts the jump short." },
         },
     },
+    topdown: {
+        description: "Player control seen from above or for vehicles: moves with the arrow keys, no gravity. directions picks 8-way, 4-way, or one axis (\"x\" for a breakout paddle or a shooter ship). Needs a dynamic body (collides with walls) or a kinematic one (passes through, use clampToWorld).",
+        requires: ["transform", "body"],
+        fields: {
+            speed: { type: "number", min: 0, default: 200, description: "Move speed in px/s." },
+            directions: {
+                type: "enum",
+                values: ["8", "4", "x", "y"],
+                default: "8",
+                description: '"8": any direction (diagonals keep the same speed). "4": up/down/left/right only. "x" or "y": one axis.',
+            },
+            clampToWorld: { type: "boolean", default: true, description: "Keep the entity inside the world bounds." },
+        },
+    },
     collectible: {
-        description: "Removed when a platformer entity touches it and adds to the score. Its body must be a sensor.",
+        description: "Removed when a player (platformer or topdown) touches it and adds to the score. Its body must be a sensor.",
         requires: ["transform", "body"],
         fields: {
             score: { type: "number", default: 1, description: "Points added when collected." },
@@ -109,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/drawcheck.d.ts

@@ -0,0 +1,7 @@
+import { type ScriptModules } from "./script.ts";
+import type { Diagnostic, SceneDef } from "./types.ts";
+/**
+ * Runs every `draw` and `drawUI` hook against a mock canvas at a few points of
+ * an idle run, and reports hooks that throw. Used by `ludra check`.
+ */
+export declare function checkDrawHooks(scene: SceneDef, scripts: ScriptModules): Diagnostic[];