@ludra/core 0.4.0 → 0.5.0

package/dist/assertions.d.ts

@@ -1,5 +1,5 @@
-import { type GameEventType, type SceneDef } from "./types.ts";
-import { type GameEvent, type WorldSnapshot } from "./world.ts";
+import { type SceneDef } from "./types.ts";
+import { type GameEvent, type WorldOptions, type WorldSnapshot } from "./world.ts";
 declare const OPERATORS: readonly ["<=", ">=", "==", "!=", "<", ">"];
 type Operator = (typeof OPERATORS)[number];
 declare const ENTITY_FIELDS: readonly ["x", "y", "vx", "vy", "grounded", "exists"];
@@ -9,19 +9,27 @@ type WorldField = (typeof WORLD_FIELDS)[number];
 type Subject = {
     kind: "world";
     field: WorldField;
-} | {
+}
+/** Built-in event types, or custom events fired by scripts with world.emit(name). */
+ | {
     kind: "events";
-    type: GameEventType;
+    name: string;
+    builtin: boolean;
 } | {
     kind: "entity";
     id: string;
     field: EntityField;
+} | {
+    kind: "state";
+    id: string;
+    key: string;
 };
+type Value = number | boolean | string;
 export interface Assertion {
     source: string;
     subject: Subject;
     operator: Operator;
-    expected: number | boolean;
+    expected: Value;
     /** Frame to check at, or "end" for the last frame of the run. */
     at: number | "end";
 }
@@ -32,7 +40,7 @@ export declare function parseAssertion(source: string): Assertion;
 export interface AssertionResult {
     source: string;
     pass: boolean;
-    actual: number | boolean | undefined;
+    actual: unknown;
     time: number;
     message: string;
 }
@@ -53,5 +61,5 @@ export interface TestResult {
     results: AssertionResult[];
     error?: string;
 }
-export declare function runTest(scene: SceneDef, test: TestCase): TestResult;
+export declare function runTest(scene: SceneDef, test: TestCase, options?: WorldOptions): TestResult;
 export {};

package/dist/assertions.js

@@ -8,7 +8,7 @@ const ENTITY_FIELDS = ["x", "y", "vx", "vy", "grounded", "exists"];
 const WORLD_FIELDS = ["score", "deaths", "won"];
 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".';
+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".';
 /** Parses `<subject> <op> <value> [at <time|end>]`. */
 export function parseAssertion(source) {
     const match = /^\s*([\w.-]+)\s*(<=|>=|==|!=|<|>)\s*(\S+?)(?:\s+at\s+(\S+))?\s*$/.exec(source);
@@ -16,31 +16,35 @@ export function parseAssertion(source) {
         throw new AssertionSyntaxError(`Cannot parse assertion "${source}". ${EXAMPLES}`);
     const [, lhs = "", operator, rhs = "", at] = match;
     let subject;
+    const stateMatch = /^(.+)\.state\.([\w-]+)$/.exec(lhs);
     if (WORLD_FIELDS.includes(lhs)) {
         subject = { kind: "world", field: lhs };
     }
-    else if (lhs.startsWith("events.")) {
-        const type = lhs.slice("events.".length);
-        if (!EVENT_TYPES.includes(type)) {
-            throw new AssertionSyntaxError(`Unknown event "${type}" in "${source}". Events: ${EVENT_TYPES.join(", ")}.`);
-        }
-        subject = { kind: "events", type: type };
+    else if (lhs.startsWith("events.") && lhs.length > "events.".length) {
+        const name = lhs.slice("events.".length);
+        subject = { kind: "events", name, builtin: EVENT_TYPES.includes(name) };
+    }
+    else if (stateMatch) {
+        subject = { kind: "state", id: stateMatch[1], key: stateMatch[2] };
     }
     else {
         const dot = lhs.lastIndexOf(".");
         const field = lhs.slice(dot + 1);
         if (dot <= 0 || !ENTITY_FIELDS.includes(field)) {
-            throw new AssertionSyntaxError(`"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<${EVENT_TYPES.join("|")}> or <entityId>.<${ENTITY_FIELDS.join("|")}>.`);
+            throw new AssertionSyntaxError(`"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<name>, <entityId>.<${ENTITY_FIELDS.join("|")}> or <entityId>.state.<key>.`);
         }
         subject = { kind: "entity", id: lhs.slice(0, dot), field: field };
     }
     let expected;
     if (rhs === "true" || rhs === "false")
         expected = rhs === "true";
+    else if (/^".*"$/.test(rhs))
+        expected = rhs.slice(1, -1);
     else if (Number.isFinite(Number(rhs)))
         expected = Number(rhs);
-    else
-        throw new AssertionSyntaxError(`Expected a number or true/false after "${operator}" in "${source}", got "${rhs}".`);
+    else {
+        throw new AssertionSyntaxError(`Expected a number, true/false or a "quoted string" after "${operator}" in "${source}", got ${rhs}.`);
+    }
     let frame = "end";
     if (at !== undefined && at !== "end") {
         try {
@@ -62,10 +66,30 @@ export function evaluateAssertion(assertion, snapshot, events) {
             actual = snapshot[subject.field];
             label = subject.field;
             break;
-        case "events":
-            actual = events.filter((e) => e.type === subject.type && e.frame <= snapshot.frame).length;
-            label = `events.${subject.type}`;
+        case "events": {
+            const matches = (e) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
+            actual = events.filter((e) => matches(e) && e.frame <= snapshot.frame).length;
+            label = `events.${subject.name}`;
+            break;
+        }
+        case "state": {
+            const entity = snapshot.entities[subject.id];
+            label = `${subject.id}.state.${subject.key}`;
+            if (!entity) {
+                return { source, pass: false, actual: undefined, time, message: `entity "${subject.id}" does not exist at ${time.toFixed(2)}s.` };
+            }
+            actual = entity.state?.[subject.key];
+            if (actual === undefined) {
+                return {
+                    source,
+                    pass: false,
+                    actual,
+                    time,
+                    message: `${label} is not set at ${time.toFixed(2)}s. Scripts set it with self.state.${subject.key} = ...`,
+                };
+            }
             break;
+        }
         case "entity": {
             const entity = snapshot.entities[subject.id];
             label = `${subject.id}.${subject.field}`;
@@ -85,13 +109,19 @@ export function evaluateAssertion(assertion, snapshot, events) {
         }
     }
     if (typeof actual !== typeof expected) {
-        return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, but it is compared with ${JSON.stringify(expected)}.` };
+        return {
+            source,
+            pass: false,
+            actual,
+            time,
+            message: `${label} is ${JSON.stringify(actual)} (a ${typeof actual}), but it is compared with ${JSON.stringify(expected)}.`,
+        };
     }
-    if (typeof actual === "boolean" && operator !== "==" && operator !== "!=") {
-        return { source, pass: false, actual, time, message: `${label} is true/false, so only == and != can be used.` };
+    if (typeof actual !== "number" && operator !== "==" && operator !== "!=") {
+        return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, so only == and != can be used.` };
     }
     const pass = compare(actual, operator, expected);
-    const shown = typeof actual === "number" ? round(actual) : actual;
+    const shown = typeof actual === "number" ? round(actual) : JSON.stringify(actual);
     return { source, pass, actual, time, message: `${label} = ${shown} at ${time.toFixed(2)}s` };
 }
 function compare(a, operator, b) {
@@ -113,7 +143,7 @@ function compare(a, operator, b) {
 function round(n) {
     return Math.round(n * 100) / 100;
 }
-export function runTest(scene, test) {
+export function runTest(scene, test, options = {}) {
     let script;
     let assertions;
     let frames;
@@ -134,11 +164,18 @@ export function runTest(scene, test) {
     }
     const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
     const snapshots = new Map();
-    const world = new World(scene);
-    simulate(world, script, frames, (w) => {
-        if (wanted.has(w.frame))
-            snapshots.set(w.frame, w.snapshot());
-    });
+    let world;
+    try {
+        world = new World(scene, options);
+        simulate(world, script, frames, (w) => {
+            if (wanted.has(w.frame))
+                snapshots.set(w.frame, w.snapshot());
+        });
+    }
+    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 };
+    }
     const results = assertions.map((a) => {
         const frame = a.at === "end" ? frames : Math.min(a.at, frames);
         return evaluateAssertion(a, snapshots.get(frame), world.events);

package/dist/browser.d.ts

@@ -2,6 +2,10 @@ import type { SceneDef } from "./types.ts";
 export interface GameOptions {
     /** URL prefix for image and audio paths in the scene. Defaults to "". */
     assetBase?: string;
+    /** URL prefix the scene's script paths are imported from. Defaults to `assetBase`. */
+    scriptBase?: string;
+    /** Scripts to load. Defaults to those the scene references; include any that `world.spawn` uses. */
+    scriptPaths?: readonly string[];
 }
 /**
  * Runs a scene in a canvas with keyboard controls, images, particles and

package/dist/browser.js

@@ -1,3 +1,11 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { SoundPlayer } from "./audio.js";
 import { parseFrames } from "./components.js";
 import { collectAssetPaths } from "./effects.js";
@@ -23,6 +31,19 @@ const KEYMAP = {
 const MAX_FRAME_TIME = 0.25;
 /** Screen shake decays by this factor every step. */
 const SHAKE_DECAY = 0.88;
+/** Imports the game's script modules, keyed by their path in the scene. */
+async function loadScripts(scene, options) {
+    const base = options.scriptBase ?? options.assetBase ?? "";
+    const paths = options.scriptPaths ?? collectAssetPaths(scene).filter((ref) => ref.kind === "script").map((ref) => ref.path);
+    const scripts = new Map();
+    await Promise.all([...new Set(paths)].map(async (path) => {
+        const module = (await import(__rewriteRelativeImportExtension(base + path)));
+        if (!module.default)
+            throw new Error(`Script ${path} has no default export.`);
+        scripts.set(path, module.default);
+    }));
+    return scripts;
+}
 /**
  * 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
@@ -34,13 +55,15 @@ export async function startGame(canvas, scene, options = {}) {
     if (!ctx)
         throw new Error("Canvas 2D context is not available.");
     const assetBase = options.assetBase ?? "";
-    const images = await loadImages(scene, 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);
+    let world = new World(scene, { scripts });
+    let crash;
     const restart = () => {
-        world = new World(scene);
+        world = new World(scene, { scripts });
         view.reset();
+        crash = undefined;
     };
     const held = new Set();
     // Keys pressed since the last step. A tap shorter than one frame still reaches the simulation.
@@ -76,13 +99,22 @@ 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) {
-            world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
+        while (accumulator >= FIXED_DT && !crash) {
+            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);
+                console.error("[ludra]", err);
+            }
             tapped.clear();
             view.step(world, (sound) => sounds.play(sound));
             accumulator -= FIXED_DT;
         }
         view.draw(ctx, world, sounds.muted);
+        if (crash)
+            drawCrash(ctx, crash);
         raf = requestAnimationFrame(frame);
     };
     raf = requestAnimationFrame(frame);
@@ -103,9 +135,9 @@ 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 = await loadImages(scene, options.assetBase ?? "");
+    const [images, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
     const view = new View(scene, images);
-    const world = new World(scene);
+    const world = new World(scene, { scripts });
     const script = InputScript.parse(options.inputs ?? "");
     const wanted = new Set(options.frames);
     const last = Math.max(0, ...options.frames);
@@ -122,6 +154,30 @@ export async function captureFrames(canvas, scene, options) {
     }
     return captured;
 }
+function drawCrash(ctx, message) {
+    const { width, height } = ctx.canvas;
+    ctx.fillStyle = "rgba(20, 0, 8, 0.85)";
+    ctx.fillRect(0, 0, width, height);
+    ctx.fillStyle = "#ff9b9b";
+    ctx.textAlign = "left";
+    ctx.font = "700 22px system-ui, sans-serif";
+    ctx.fillText("Script error", 32, 56);
+    ctx.font = "15px ui-monospace, monospace";
+    // Wrap the message to the canvas width.
+    let line = "";
+    let y = 92;
+    for (const word of message.split(" ")) {
+        if (ctx.measureText(line + word).width > width - 64) {
+            ctx.fillText(line, 32, y);
+            line = "";
+            y += 22;
+        }
+        line += `${word} `;
+    }
+    ctx.fillText(line, 32, y);
+    ctx.fillStyle = "rgba(255, 255, 255, 0.6)";
+    ctx.fillText("Fix the script; the page reloads on save. R restarts.", 32, y + 40);
+}
 async function loadImages(scene, assetBase) {
     const images = new Map();
     const paths = new Set(collectAssetPaths(scene).filter((ref) => ref.kind === "image").map((ref) => ref.path));
@@ -163,7 +219,7 @@ class View {
     /** Runs once per simulation step: turns new events into effects and advances particles. */
     step(world, playSound) {
         for (const event of world.events.slice(this.handledEvents)) {
-            const effect = this.scene.effects?.[event.type];
+            const effect = this.scene.effects?.[event.type === "custom" ? event.name : event.type];
             if (!effect)
                 continue;
             if (effect.particles)

package/dist/components.d.ts

@@ -22,6 +22,12 @@ export type FieldSpec = {
     type: "frames";
     default?: string;
     description: string;
+}
+/** Any JSON object. */
+ | {
+    type: "object";
+    default?: Record<string, unknown>;
+    description: string;
 };
 export interface ComponentSpec {
     description: string;
@@ -29,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", "camera"];
+export declare const COMPONENT_NAMES: readonly ["transform", "body", "sprite", "platformer", "collectible", "patrol", "hazard", "goal", "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>;
@@ -82,6 +88,10 @@ export interface ParticleSpec {
 export interface Emitter extends Omit<ParticleSpec, "count"> {
     rate: number;
 }
+export interface ScriptComponent {
+    src: string;
+    params: Record<string, unknown>;
+}
 export interface Platformer {
     speed: number;
     jumpSpeed: number;

package/dist/components.js

@@ -8,6 +8,7 @@ export const COMPONENT_NAMES = [
     "hazard",
     "goal",
     "emitter",
+    "script",
     "camera",
 ];
 /** Shared by the `emitter` component and the particles of scene `effects`. Purely visual. */
@@ -118,6 +119,14 @@ export const COMPONENTS = {
             ...Object.fromEntries(Object.entries(PARTICLE_FIELDS).filter(([field]) => field !== "count")),
         },
     },
+    script: {
+        description: "Custom behavior written in TypeScript or JavaScript: a file that default-exports hooks (start, update, touch). Use it for anything the built-in components don't do: chasing, doors and keys, timers, shooting, boss phases. Run `ludra components script` for the API.",
+        requires: ["transform"],
+        fields: {
+            src: { type: "string", description: 'Script path relative to the project, e.g. "scripts/chase.ts".' },
+            params: { type: "object", default: {}, description: "Values passed to the script as ctx.params, so one script can serve many entities." },
+        },
+    },
     camera: {
         description: "The browser camera follows this entity. Without it, the camera follows the first platformer.",
         requires: ["transform"],

package/dist/effects.d.ts

@@ -13,7 +13,7 @@ export interface AssetReference {
     path: string;
     /** JSON path of the field that references it. */
     at: string;
-    kind: "image" | "audio";
+    kind: "image" | "audio" | "script";
 }
 /** Every file a scene points at, so tools can check that they exist. */
 export declare function collectAssetPaths(scene: SceneDef): AssetReference[];

package/dist/effects.js

@@ -21,6 +21,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 src = entity.components.script?.src;
+        if (typeof src === "string" && src !== "")
+            refs.push({ path: src, at: `entities[${i}].components.script.src`, kind: "script" });
     });
     for (const [event, effect] of Object.entries(scene.effects ?? {})) {
         const sound = effect?.sound;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./components.ts";
 export * from "./effects.ts";
 export * from "./validate.ts";
 export * from "./input.ts";
+export * from "./script.ts";
 export * from "./world.ts";
 export * from "./simulate.ts";
 export * from "./assertions.ts";

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./components.js";
 export * from "./effects.js";
 export * from "./validate.js";
 export * from "./input.js";
+export * from "./script.js";
 export * from "./world.js";
 export * from "./simulate.js";
 export * from "./assertions.js";

package/dist/script.d.ts

@@ -0,0 +1,108 @@
+import type { Action, Diagnostic } from "./types.ts";
+/**
+ * A game object as scripts see it. Reading and writing `x`, `y`, `vx` and
+ * `vy` changes the entity directly.
+ */
+export interface ScriptEntity {
+    readonly id: string;
+    x: number;
+    y: number;
+    /** Velocity in px/s. Always 0 for entities without a body. */
+    vx: number;
+    vy: number;
+    readonly grounded: boolean;
+    readonly width: number;
+    readonly height: number;
+    /** False once the entity has been destroyed or collected. */
+    readonly exists: boolean;
+    /**
+     * Data kept between frames. Use JSON values only. Tests can read it as
+     * `<id>.state.<key>`, for example `"door.state.open == true"`.
+     */
+    readonly state: Record<string, unknown>;
+    has(component: string): boolean;
+    /** True when this entity overlaps or touches the other one. */
+    touches(other: ScriptEntity | string): boolean;
+}
+export interface SpawnDef {
+    /** Generated when left out. */
+    id?: string;
+    components: Record<string, Record<string, unknown>>;
+}
+export interface ScriptWorld {
+    readonly time: number;
+    readonly frame: number;
+    readonly width: number;
+    readonly height: number;
+    score: number;
+    get(id: string): ScriptEntity | undefined;
+    /** Every entity, or only those with the given component. */
+    all(component?: string): ScriptEntity[];
+    /** The first entity with a `platformer` component. */
+    player(): ScriptEntity | undefined;
+    spawn(def: SpawnDef): ScriptEntity;
+    destroy(entity: ScriptEntity | string): void;
+    /** Players die and respawn; anything else is destroyed. */
+    kill(entity: ScriptEntity | string): void;
+    /** Completes the level, like reaching a goal. */
+    win(): 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. */
+    random(): number;
+}
+export interface ScriptInput {
+    /** True while the action is held. */
+    held(action: Action): boolean;
+    /** True only on the frame the action is pressed. */
+    pressed(action: Action): boolean;
+}
+export interface ScriptContext {
+    self: ScriptEntity;
+    world: ScriptWorld;
+    input: ScriptInput;
+    /** The `params` object from the entity's `script` component. */
+    params: Record<string, unknown>;
+    /** Seconds per frame (1/60). */
+    dt: number;
+}
+/**
+ * The default export of a script file. All hooks are optional.
+ *
+ * ```ts
+ * import type { Script } from "@ludra/core";
+ * export default {
+ *   update({ self, world, params }) { ... },
+ * } satisfies Script;
+ * ```
+ */
+export interface Script {
+    /** Runs once, on the entity's first frame. */
+    start?(ctx: ScriptContext): void;
+    /** Runs every frame, after player input and before physics. */
+    update?(ctx: ScriptContext): void;
+    /** Runs when this entity starts touching another one (after physics). */
+    touch?(ctx: ScriptContext, other: ScriptEntity): void;
+}
+export declare const SCRIPT_HOOKS: readonly ["start", "update", "touch"];
+/** 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  } 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, 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\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. */
+export declare class ScriptError extends Error {
+    readonly src: string;
+    readonly entity: string;
+    readonly hook: string;
+    readonly frame: number;
+    constructor(details: {
+        src: string;
+        entity: string;
+        hook: string;
+        frame: number;
+    }, message: string, options?: ErrorOptions);
+}
+/** Checks that a loaded module looks like a script. */
+export declare function validateScriptModule(module: unknown, src: string): Diagnostic[];
+/** Scripts run in the engine without a bundler, so they cannot import runtime code. */
+export declare function findRuntimeImports(source: string): string[];

package/dist/script.js

@@ -0,0 +1,87 @@
+import { closestName } from "./validate.js";
+export const SCRIPT_HOOKS = ["start", "update", "touch"];
+/** Printed by `ludra components script`. Keep in sync with the interfaces above. */
+export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "import type" is allowed: scripts run without a bundler.
+
+  import type { Script } from "@ludra/core";
+  export default {
+    start(ctx) {},           // once, on the entity's first frame
+    update(ctx) {},          // every frame, after player input, before physics
+    touch(ctx, other) {},    // when this entity starts touching another body (after physics)
+  } satisfies Script;
+
+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, score (read/write)
+              get(id), all(component?), player()
+              spawn({ id?, components }) -> entity    destroy(entityOrId)
+              kill(entityOrId)  players respawn, others are destroyed
+              win()             completes the level
+              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
+ctx.params    the "params" object from the script component
+ctx.dt        seconds per frame (1/60)
+
+Scripts in scripts/ are loaded even if no entity uses them, so world.spawn can attach them.
+Errors name the file, entity, hook and frame.`;
+export function getScript(modules, src) {
+    if (!modules)
+        return undefined;
+    return modules instanceof Map ? modules.get(src) : modules[src];
+}
+/** A script threw, or was used wrongly. Names the file, entity, hook and frame. */
+export class ScriptError extends Error {
+    src;
+    entity;
+    hook;
+    frame;
+    constructor(details, message, options) {
+        super(`${details.src} (${details.hook} on entity "${details.entity}", frame ${details.frame}): ${message}`, options);
+        this.src = details.src;
+        this.entity = details.entity;
+        this.hook = details.hook;
+        this.frame = details.frame;
+    }
+}
+/** Checks that a loaded module looks like a script. */
+export function validateScriptModule(module, src) {
+    const diagnostics = [];
+    const script = module?.default;
+    if (typeof script !== "object" || script === null) {
+        diagnostics.push({
+            severity: "error",
+            code: "E_SCRIPT_NO_DEFAULT_EXPORT",
+            path: src,
+            message: `${src} must default-export an object with script hooks.`,
+            fix: "Use: export default { update({ self, world }) { ... } } satisfies Script;",
+        });
+        return diagnostics;
+    }
+    for (const [key, value] of Object.entries(script)) {
+        if (!SCRIPT_HOOKS.includes(key)) {
+            const suggestion = closestName(key, SCRIPT_HOOKS);
+            diagnostics.push({
+                severity: "warning",
+                code: "W_SCRIPT_UNKNOWN_HOOK",
+                path: `${src} → ${key}`,
+                message: `"${key}" is not a script hook, so it is never called.`,
+                fix: `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Hooks are ${SCRIPT_HOOKS.join(", ")}. Put helpers outside the exported object.`,
+            });
+        }
+        else if (typeof value !== "function") {
+            diagnostics.push({ severity: "error", code: "E_SCRIPT_HOOK_NOT_FUNCTION", path: `${src} → ${key}`, message: `"${key}" must be a function.` });
+        }
+    }
+    return diagnostics;
+}
+/** Scripts run in the engine without a bundler, so they cannot import runtime code. */
+export function findRuntimeImports(source) {
+    const imports = [];
+    for (const match of source.matchAll(/^\s*import\s+(?!type\b)([^;\n]*?)\s+from\s+["']([^"']+)["']/gm))
+        imports.push(match[2]);
+    for (const match of source.matchAll(/^\s*import\s+["']([^"']+)["']/gm))
+        imports.push(match[1]);
+    return imports;
+}

package/dist/types.d.ts

@@ -20,13 +20,18 @@ export interface WorldSettings {
     /** Downward acceleration in px/s². Defaults to 1800. */
     gravity?: number;
     background?: string;
+    /** Seed for `world.random()` in scripts. Defaults to 1. */
+    seed?: number;
 }
 /** A scene file (`*.scene.json`). */
 export interface SceneDef {
     name?: string;
     world?: WorldSettings;
-    /** Feedback for game events, e.g. `{ "collect": { "sound": "coin" } }`. Visual and audio only. */
-    effects?: Partial<Record<GameEventType, EffectDef>>;
+    /**
+     * Feedback for game events, e.g. `{ "collect": { "sound": "coin" } }`. Visual and audio only.
+     * Keys are built-in event types or names scripts pass to `world.emit`.
+     */
+    effects?: Partial<Record<GameEventType, EffectDef>> & Record<string, EffectDef | undefined>;
     entities: EntityDef[];
 }
 export interface Diagnostic {

package/dist/validate.d.ts

@@ -10,3 +10,5 @@ export interface ValidationResult {
  * where possible, a fix an agent can apply without guessing.
  */
 export declare function validateScene(raw: unknown): ValidationResult;
+/** Returns the candidate within a small edit distance of `input`, if any. */
+export declare function closestName(input: string, candidates: readonly string[]): string | undefined;