@ludra/core 0.5.0 → 0.8.0

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,15 +5,16 @@ 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 const EFFECTS_DESCRIPTION = "Scene-level \"effects\" map a game event (jump, land, collect, die, stomp, win, bounce, checkpoint, gameover, goto, or a custom one) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.";
 export declare function isSoundPreset(sound: string): sound is SoundPreset;
 export interface AssetReference {
     /** Path relative to the project, as written in the scene. */
     path: string;
     /** JSON path of the field that references it. */
     at: string;
-    kind: "image" | "audio" | "script";
+    kind: "image" | "audio" | "script" | "font" | "shader" | "scene";
 }
 /** Every file a scene points at, so tools can check that they exist. */
 export declare function collectAssetPaths(scene: SceneDef): AssetReference[];

package/dist/effects.js

@@ -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",
@@ -10,7 +11,7 @@ export const EFFECT_FIELDS = {
     },
     shake: { type: "number", min: 0, default: 0, description: "Screen shake strength in pixels." },
 };
-export const EFFECTS_DESCRIPTION = 'Scene-level "effects" map a game event (jump, land, collect, die, stomp, win) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.';
+export const EFFECTS_DESCRIPTION = 'Scene-level "effects" map a game event (jump, land, collect, die, stomp, win, bounce, checkpoint, gameover, goto, or a custom one) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.';
 export function isSoundPreset(sound) {
     return SOUND_PRESETS.includes(sound);
 }
@@ -21,14 +22,32 @@ export function collectAssetPaths(scene) {
         const image = entity.components.sprite?.image;
         if (typeof image === "string" && image !== "")
             refs.push({ path: image, at: `entities[${i}].components.sprite.image`, kind: "image" });
+        const next = entity.components.goal?.next;
+        if (typeof next === "string" && next !== "")
+            refs.push({ path: next, at: `entities[${i}].components.goal.next`, kind: "scene" });
         const src = entity.components.script?.src;
         if (typeof src === "string" && src !== "")
             refs.push({ path: src, at: `entities[${i}].components.script.src`, kind: "script" });
+        // 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

@@ -9,3 +9,4 @@ export * from "./world.ts";
 export * from "./simulate.ts";
 export * from "./assertions.ts";
 export * from "./ascii.ts";
+export * from "./drawcheck.ts";

package/dist/index.js

@@ -9,3 +9,4 @@ 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

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

package/dist/script.js

@@ -1,5 +1,5 @@
 import { closestName } from "./validate.js";
-export const SCRIPT_HOOKS = ["start", "update", "touch"];
+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.
 
@@ -8,22 +8,43 @@ export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "
     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, score (read/write)
+ctx.world     time, frame, width, height, deaths, won, lost, exit (read); score, lives (read/write)
               get(id), all(component?), player()
-              spawn({ id?, components }) -> entity    destroy(entityOrId)
+              spawn({ id?, prefab?, components? }) -> entity    destroy(entityOrId)
               kill(entityOrId)  players respawn, others are destroyed
-              win()             completes the level
+              win()             completes the level        lose()   game over
+              goto(scenePath)   moves on to another scene (title -> level 1, a door to the next room)
               emit(name, data?) custom event: counted by "events.<name>" in tests, usable as an effects key
               random()          deterministic, seeded by world.seed. Never use Math.random or Date
 ctx.input     held(action), pressed(action)   actions: left right up down jump action
 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) {

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type Action = "left" | "right" | "up" | "down" | "jump" | "action";
 export declare const ACTIONS: readonly Action[];
-export declare const EVENT_TYPES: readonly ["jump", "land", "collect", "die", "stomp", "win"];
+export declare const EVENT_TYPES: readonly ["jump", "land", "collect", "die", "stomp", "win", "bounce", "checkpoint", "gameover", "goto"];
 export type GameEventType = (typeof EVENT_TYPES)[number];
 /** What happens visually and audibly when a game event fires. See `EFFECT_FIELDS`. */
 export interface EffectDef {
@@ -8,9 +8,17 @@ export interface EffectDef {
     sound?: string;
     shake?: number;
 }
+export interface PostFxDef {
+    /** Path to a GLSL ES 1.0 fragment shader, e.g. "shaders/crt.frag". */
+    shader: string;
+    /** Extra float uniforms, e.g. { "strength": 0.6 } becomes `uniform float strength;`. */
+    uniforms?: Record<string, number>;
+}
 /** An entity as written in a scene file. */
 export interface EntityDef {
     id: string;
+    /** Name of a prefab to start from. Gone after validation: its components are merged in. */
+    prefab?: string;
     components: Record<string, Record<string, unknown>>;
 }
 export interface WorldSettings {
@@ -22,6 +30,13 @@ export interface WorldSettings {
     background?: string;
     /** Seed for `world.random()` in scripts. Defaults to 1. */
     seed?: number;
+    /** Lives before game over. Leave out for unlimited retries. */
+    lives?: number;
+}
+/** A reusable entity template: `prefabs/<name>.prefab.json` or the scene's `prefabs` map. */
+export interface PrefabDef {
+    description?: string;
+    components: Record<string, Record<string, unknown>>;
 }
 /** A scene file (`*.scene.json`). */
 export interface SceneDef {
@@ -32,6 +47,19 @@ export interface SceneDef {
      * Keys are built-in event types or names scripts pass to `world.emit`.
      */
     effects?: Partial<Record<GameEventType, EffectDef>> & Record<string, EffectDef | undefined>;
+    /**
+     * Fonts that draw hooks can use in `ctx.g.font`: family name → "google" (loaded from
+     * Google Fonts) or a font file in the project (.woff2, .woff, .ttf, .otf).
+     */
+    fonts?: Record<string, string>;
+    /** A GLSL fragment shader applied to every rendered frame. Presentation only. */
+    postfx?: PostFxDef;
+    /**
+     * Entity templates by name. Entities use one with `"prefab": "<name>"` and override
+     * components; scripts spawn them with `world.spawn({ prefab: "<name>" })`. The CLI
+     * adds every `prefabs/*.prefab.json` file here.
+     */
+    prefabs?: Record<string, PrefabDef>;
     entities: EntityDef[];
 }
 export interface Diagnostic {

package/dist/types.js

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

package/dist/validate.d.ts

@@ -9,6 +9,8 @@ export interface ValidationResult {
  * Checks a parsed scene file. Every diagnostic names the exact JSON path and,
  * where possible, a fix an agent can apply without guessing.
  */
-export declare function validateScene(raw: unknown): ValidationResult;
+export declare function validateScene(input: unknown): ValidationResult;
+/** A prefab's components with overrides merged in, one level deep. `null` drops a component. */
+export declare function mergeComponents(base: Record<string, unknown>, overrides: Record<string, unknown>): Record<string, Record<string, unknown>>;
 /** Returns the candidate within a small edit distance of `input`, if any. */
 export declare function closestName(input: string, candidates: readonly string[]): string | undefined;