@ludra/core 0.4.0 → 0.7.0

package/dist/components.js

@@ -3,11 +3,13 @@ export const COMPONENT_NAMES = [
     "body",
     "sprite",
     "platformer",
+    "topdown",
     "collectible",
     "patrol",
     "hazard",
     "goal",
     "emitter",
+    "script",
     "camera",
 ];
 /** Shared by the `emitter` component and the particles of scene `effects`. Purely visual. */
@@ -43,6 +45,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." },
         },
@@ -79,8 +87,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." },
@@ -118,6 +140,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/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[];

package/dist/drawcheck.js

@@ -0,0 +1,81 @@
+import { ScriptError } from "./script.js";
+import { World } from "./world.js";
+/** Simulation frames at which `checkDrawHooks` paints: the start, and after things have moved. */
+const CHECK_FRAMES = [0, 30, 120];
+/**
+ * A stand-in for CanvasRenderingContext2D that accepts every call and property,
+ * so draw hooks can run outside a browser. It catches the hook's own mistakes
+ * (typos, undefined values, changing the game while drawing), not what it looks like.
+ */
+function mockCanvas() {
+    const handler = {
+        get: (_target, key) => (key === Symbol.toPrimitive ? () => 0 : key === "then" ? undefined : any),
+        set: () => true,
+        apply: () => any,
+    };
+    const any = new Proxy(() => undefined, handler);
+    return any;
+}
+/**
+ * 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 function checkDrawHooks(scene, scripts) {
+    let world;
+    try {
+        world = new World(scene, { scripts });
+    }
+    catch {
+        return []; // Load problems are reported elsewhere.
+    }
+    const reported = new Set();
+    const diagnostics = [];
+    const g = mockCanvas();
+    const view = { width: world.width, height: world.height, cameraX: 0, cameraY: 0, zoom: 1 };
+    const locals = new Map();
+    for (let frame = 0; frame <= CHECK_FRAMES.at(-1); frame++) {
+        if (CHECK_FRAMES.includes(frame)) {
+            for (const e of [...world.entities]) {
+                for (const hook of ["draw", "drawUI"]) {
+                    if (!e.script?.module[hook])
+                        continue;
+                    if (!locals.has(e.id))
+                        locals.set(e.id, {});
+                    try {
+                        world.callDrawHook(e, hook, {
+                            g,
+                            time: world.time,
+                            local: locals.get(e.id),
+                            view,
+                            recent: () => [],
+                            image: () => undefined,
+                            burst: () => { },
+                            shake: () => { },
+                            random: () => 0.5,
+                        });
+                    }
+                    catch (err) {
+                        const key = `${e.script.src}:${hook}`;
+                        if (reported.has(key))
+                            continue;
+                        reported.add(key);
+                        diagnostics.push({
+                            severity: "error",
+                            code: "E_DRAW_HOOK",
+                            path: `${e.script.src} → ${hook}`,
+                            message: err instanceof ScriptError ? err.message : String(err),
+                            fix: "Draw hooks run every rendered frame in the browser. Fix the error; ctx.image() can return undefined, so check it before drawing.",
+                        });
+                    }
+                }
+            }
+        }
+        try {
+            world.step(new Set());
+        }
+        catch {
+            break; // Simulation errors surface in play and test.
+        }
+    }
+    return diagnostics;
+}

package/dist/effects.d.ts

@@ -5,6 +5,7 @@ export declare const SOUND_PRESETS: readonly ["jump", "coin", "hit", "explosion"
 export type SoundPreset = (typeof SOUND_PRESETS)[number];
 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 function isSoundPreset(sound: string): sound is SoundPreset;
@@ -13,7 +14,7 @@ export interface AssetReference {
     path: string;
     /** JSON path of the field that references it. */
     at: string;
-    kind: "image" | "audio";
+    kind: "image" | "audio" | "script" | "font" | "shader";
 }
 /** Every file a scene points at, so tools can check that they exist. */
 export declare function collectAssetPaths(scene: SceneDef): AssetReference[];

package/dist/effects.js

@@ -2,6 +2,7 @@
 export const SOUND_PRESETS = ["jump", "coin", "hit", "explosion", "powerup", "blip", "thud"];
 export const AUDIO_EXTENSIONS = [".wav", ".mp3", ".ogg"];
 export const IMAGE_EXTENSIONS = [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"];
+export const FONT_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf"];
 export const EFFECT_FIELDS = {
     sound: {
         type: "string",
@@ -21,11 +22,29 @@ 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" });
+        // Images named in script params are preloaded for draw hooks (ctx.image).
+        const params = entity.components.script?.params;
+        if (params && typeof params === "object") {
+            for (const [key, value] of Object.entries(params)) {
+                if (typeof value === "string" && IMAGE_EXTENSIONS.some((ext) => value.toLowerCase().endsWith(ext))) {
+                    refs.push({ path: value, at: `entities[${i}].components.script.params.${key}`, kind: "image" });
+                }
+            }
+        }
     });
     for (const [event, effect] of Object.entries(scene.effects ?? {})) {
         const sound = effect?.sound;
         if (typeof sound === "string" && sound !== "" && !isSoundPreset(sound))
             refs.push({ path: sound, at: `effects.${event}.sound`, kind: "audio" });
     }
+    for (const [family, src] of Object.entries(scene.fonts ?? {})) {
+        if (typeof src === "string" && src !== "google")
+            refs.push({ path: src, at: `fonts.${family}`, kind: "font" });
+    }
+    if (typeof scene.postfx?.shader === "string" && scene.postfx.shader !== "")
+        refs.push({ path: scene.postfx.shader, at: "postfx.shader", kind: "shader" });
     return refs;
 }

package/dist/index.d.ts

@@ -4,7 +4,9 @@ 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";
 export * from "./ascii.ts";
+export * from "./drawcheck.ts";

package/dist/index.js

@@ -4,7 +4,9 @@ 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";
 export * from "./ascii.js";
+export * from "./drawcheck.js";

package/dist/postfx.d.ts

@@ -0,0 +1,18 @@
+import type { PostFxDef } from "./types.ts";
+/**
+ * Runs a scene's GLSL fragment shader over each rendered frame. The game draws
+ * into an offscreen 2D canvas; this uploads it as a texture and draws it
+ * through the shader onto a WebGL canvas.
+ */
+export declare class PostFx {
+    readonly canvas: HTMLCanvasElement;
+    private readonly gl;
+    private readonly program;
+    private readonly texture;
+    private readonly uniforms;
+    private readonly time;
+    /** Throws with the GLSL compiler's message if the shader doesn't compile. */
+    constructor(width: number, height: number, source: string, def: PostFxDef);
+    /** Draws `source` (the frame the game just rendered) through the shader. */
+    render(source: HTMLCanvasElement, time: number): void;
+}

package/dist/postfx.js

@@ -0,0 +1,100 @@
+/** Declared by the engine for every postfx shader, so shaders only write `main`. */
+const ENGINE_HEADER = `precision mediump float;
+uniform sampler2D u_image;
+uniform vec2 u_resolution;
+uniform float u_time;
+varying vec2 v_uv;
+`;
+const VERTEX_SHADER = `attribute vec2 a_position;
+varying vec2 v_uv;
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}`;
+/**
+ * Runs a scene's GLSL fragment shader over each rendered frame. The game draws
+ * into an offscreen 2D canvas; this uploads it as a texture and draws it
+ * through the shader onto a WebGL canvas.
+ */
+export class PostFx {
+    canvas;
+    gl;
+    program;
+    texture;
+    uniforms;
+    time;
+    /** Throws with the GLSL compiler's message if the shader doesn't compile. */
+    constructor(width, height, source, def) {
+        this.canvas = document.createElement("canvas");
+        this.canvas.width = width;
+        this.canvas.height = height;
+        // preserveDrawingBuffer keeps the frame readable for screenshots.
+        const gl = this.canvas.getContext("webgl", { preserveDrawingBuffer: true, premultipliedAlpha: false });
+        if (!gl)
+            throw new Error("postfx needs WebGL, which this browser doesn't provide.");
+        this.gl = gl;
+        const custom = Object.keys(def.uniforms ?? {});
+        // #line 1 makes compiler errors point at lines of the shader file itself.
+        const header = ENGINE_HEADER + custom.map((name) => `uniform float ${name};\n`).join("") + "#line 1\n";
+        this.program = link(gl, VERTEX_SHADER, header + stripDeclarations(source, ["u_image", "u_resolution", "u_time", "v_uv", ...custom]), def.shader);
+        gl.useProgram(this.program);
+        const buffer = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+        const position = gl.getAttribLocation(this.program, "a_position");
+        gl.enableVertexAttribArray(position);
+        gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+        this.texture = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        for (const [key, value] of [
+            [gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE],
+            [gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE],
+            [gl.TEXTURE_MIN_FILTER, gl.LINEAR],
+            [gl.TEXTURE_MAG_FILTER, gl.LINEAR],
+        ]) {
+            gl.texParameteri(gl.TEXTURE_2D, key, value);
+        }
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+        gl.uniform1i(gl.getUniformLocation(this.program, "u_image"), 0);
+        gl.uniform2f(gl.getUniformLocation(this.program, "u_resolution"), width, height);
+        this.time = gl.getUniformLocation(this.program, "u_time");
+        this.uniforms = custom.map((name) => ({ location: gl.getUniformLocation(this.program, name), value: def.uniforms[name] }));
+    }
+    /** Draws `source` (the frame the game just rendered) through the shader. */
+    render(source, time) {
+        const gl = this.gl;
+        gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+        gl.uniform1f(this.time, time);
+        for (const u of this.uniforms)
+            gl.uniform1f(u.location, u.value);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+    }
+}
+/** Drops the shader's own declarations of names the engine already declares, so either style compiles. */
+function stripDeclarations(source, names) {
+    return source
+        .split("\n")
+        .map((line) => (/^\s*(uniform|varying)\b/.test(line) && names.some((name) => new RegExp(`\\b${name}\\b`).test(line)) ? "" : line))
+        .join("\n");
+}
+function link(gl, vertex, fragment, path) {
+    const program = gl.createProgram();
+    gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, vertex, "the engine's vertex shader"));
+    gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, fragment, path));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS))
+        throw new Error(`${path} failed to link: ${gl.getProgramInfoLog(program)}`);
+    return program;
+}
+function compile(gl, type, source, path) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        const log = String(gl.getShaderInfoLog(shader)).trim();
+        throw new Error(`${path} failed to compile: ${log}`);
+    }
+    return shader;
+}

package/dist/script.d.ts

@@ -0,0 +1,170 @@
+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;
+    /** Times a player has died so far. */
+    readonly deaths: number;
+    /** True once the level is complete. */
+    readonly won: boolean;
+    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;
+}
+/** A game event as draw hooks see it. Custom events carry the name passed to world.emit. */
+export interface DrawEvent {
+    /** Built-in type ("collect", "die", "bounce"...) or the custom event's name. */
+    name: string;
+    time: number;
+    x: number;
+    y: number;
+    /** The entity that caused it. */
+    entity: string;
+    data?: unknown;
+}
+/**
+ * What `draw` and `drawUI` receive. `g` is the real Canvas 2D context, so
+ * anything the canvas can do is allowed: gradients, glow (shadowBlur), blend
+ * modes (globalCompositeOperation), paths, text, filters, images.
+ *
+ * Draw hooks only paint. `self` and `world` are read-only here (changing the
+ * game must happen in `update` so tests see it); keep animation memory in `local`.
+ */
+export interface DrawContext {
+    g: CanvasRenderingContext2D;
+    self: ScriptEntity;
+    world: ScriptWorld;
+    params: Record<string, unknown>;
+    /** Simulation time in seconds. Animate with it so screenshots stay reproducible. */
+    time: number;
+    /** Per-entity memory for presentation (trails, tweens). Not part of the game state and not testable. */
+    local: Record<string, unknown>;
+    /** Visible area: canvas size, camera position (world px at the top-left) and zoom. */
+    view: {
+        width: number;
+        height: number;
+        cameraX: number;
+        cameraY: number;
+        zoom: number;
+    };
+    /** Events that happened in the last `seconds` (default 0.5), optionally only those named `name`. Newest last. */
+    recent(name?: string, seconds?: number): DrawEvent[];
+    /** An image from the project, e.g. "assets/glow.png". Images in sprites or in string script params are preloaded. */
+    image(path: string): HTMLImageElement | undefined;
+    /** A particle burst through the engine's particle system (same fields as effects particles). */
+    burst(x: number, y: number, particles?: Record<string, unknown>): void;
+    /** Shakes the screen by `amount` px (decays on its own). */
+    shake(amount: number): void;
+    /** A number in [0, 1) for visual variety. Seeded, independent of world.random, so it never affects the game. */
+    random(): 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;
+    /**
+     * Paints this entity in world space, every rendered frame, right after its sprite
+     * (or instead of one: an entity without a sprite is drawn only by this hook).
+     * Order follows `sprite.layer` (0 without a sprite). Browser only; tests never call it.
+     */
+    draw?(ctx: DrawContext): void;
+    /**
+     * Paints in screen space, above the world. If any script has `drawUI`, the engine's
+     * default HUD and "Level complete" screen are turned off: the game draws its own.
+     */
+    drawUI?(ctx: DrawContext): void;
+}
+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 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,107 @@
+import { closestName } from "./validate.js";
+export const SCRIPT_HOOKS = ["start", "update", "touch", "draw", "drawUI"];
+/** 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)
+    draw(ctx) {},            // paint this entity in world space (browser only, every rendered frame)
+    drawUI(ctx) {},          // paint screen-space UI; replaces the default HUD and win screen
+  } 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, deaths, won (read); 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)
+
+Drawing: draw and drawUI get the real Canvas 2D context, so there are no limits on looks.
+ctx.g         CanvasRenderingContext2D: gradients, shadowBlur glow, globalCompositeOperation ("lighter" for
+              additive light), paths, text with any loaded font, ctx.g.filter, drawImage...
+              draw: origin is the world (use self.x/self.y); drawUI: origin is the screen top-left
+ctx.time      simulation seconds; animate with it so screenshots are reproducible
+ctx.local     per-entity presentation memory (trails, tweens); not game state
+ctx.view      width, height, cameraX, cameraY, zoom
+ctx.recent(name?, seconds = 0.5)   recent events [{ name, time, x, y, entity, data }]: flash on hit, pop scores
+ctx.image(path)   a loaded image (sprite images and string params ending in .svg/.png/... are preloaded)
+ctx.burst(x, y, particles?)  ctx.shake(px)  ctx.random()   presentation-only helpers
+self/world/params as in update, but read-only: changing the game in a draw hook is an error.
+
+Scene-level presentation (all optional):
+  "fonts": { "Orbitron": "google", "Pixel": "assets/pixel.woff2" }   load fonts for ctx.g.font
+  "postfx": { "shader": "shaders/crt.frag", "uniforms": { "strength": 0.6 } }
+     a GLSL ES 1.0 fragment shader over the whole frame. It gets: uniform sampler2D u_image;
+     uniform vec2 u_resolution; uniform float u_time; varying vec2 v_uv; plus each uniform as a float.
+
+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;
+}