@ludra/core 0.5.0 → 0.7.0

package/dist/script.d.ts

@@ -35,6 +35,10 @@ 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;
     get(id: string): ScriptEntity | undefined;
     /** Every entity, or only those with the given component. */
     all(component?: string): ScriptEntity[];
@@ -66,6 +70,53 @@ 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;
+    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 +134,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 (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. */

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,12 +8,14 @@ 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 (read); score (read/write)
               get(id), all(component?), player()
               spawn({ id?, components }) -> entity    destroy(entityOrId)
               kill(entityOrId)  players respawn, others are destroyed
@@ -24,6 +26,24 @@ ctx.input     held(action), pressed(action)   actions: left right up down jump a
 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"];
 export type GameEventType = (typeof EVENT_TYPES)[number];
 /** What happens visually and audibly when a game event fires. See `EFFECT_FIELDS`. */
 export interface EffectDef {
@@ -8,6 +8,12 @@ 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;
@@ -32,6 +38,13 @@ 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;
     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"];

package/dist/validate.js

@@ -1,5 +1,5 @@
 import { COMPONENT_NAMES, COMPONENTS, isComponentName, isFrameList, PARTICLE_FIELDS } from "./components.js";
-import { AUDIO_EXTENSIONS, EFFECT_FIELDS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.js";
+import { AUDIO_EXTENSIONS, EFFECT_FIELDS, FONT_EXTENSIONS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.js";
 import { EVENT_TYPES } from "./types.js";
 const REQUIRED_EXAMPLES = {
     transform: '{ "x": 0, "y": 0 }',
@@ -42,6 +42,10 @@ export function validateScene(raw) {
     }
     if (raw.effects !== undefined)
         validateEffects(raw.effects, error, warn);
+    if (raw.fonts !== undefined)
+        validateFonts(raw.fonts, error);
+    if (raw.postfx !== undefined)
+        validatePostFx(raw.postfx, error);
     if (!Array.isArray(raw.entities)) {
         error("E_NO_ENTITIES", "entities", 'A scene needs an "entities" array.', 'Add "entities": [].');
         return result();
@@ -49,6 +53,7 @@ export function validateScene(raw) {
     const ids = new Map();
     let hasPlayer = false;
     let hasDynamic = false;
+    const worldGravity = isObject(raw.world) && typeof raw.world.gravity === "number" ? raw.world.gravity : 1800;
     let hasSolid = false;
     let availableScore = 0;
     const goals = [];
@@ -106,6 +111,12 @@ export function validateScene(raw) {
         }
         const body = isObject(components.body) ? components.body : undefined;
         const bodyType = body?.type ?? "static";
+        if ("topdown" in components && body && bodyType === "static") {
+            error("E_TOPDOWN_NEEDS_MOVING_BODY", `${path}.components.body.type`, `Entity ${label} has "topdown" but a static body, so it can never move.`, 'Use "type": "dynamic" to collide with walls, or "kinematic" to pass through them (a paddle or a ship).');
+        }
+        if ("topdown" in components && "platformer" in components) {
+            error("E_TWO_CONTROLLERS", `${path}.components`, `Entity ${label} has both "platformer" and "topdown", which would fight over its movement.`, "Keep one: platformer for side-view games with gravity, topdown for top-down games, paddles and ships.");
+        }
         if ("platformer" in components && body && bodyType !== "dynamic") {
             error("E_PLATFORMER_NEEDS_DYNAMIC_BODY", `${path}.components.body.type`, `Entity ${label} has "platformer" but its body is "${String(bodyType)}", so it can never move.`, 'Set "type": "dynamic" on its body.');
         }
@@ -123,9 +134,11 @@ export function validateScene(raw) {
             availableScore += numberOr(components.hazard.score, 0);
         if (isObject(components.goal))
             goals.push({ path: `${path}.components.goal.requireScore`, label, requireScore: numberOr(components.goal.requireScore, 0) });
-        if ("platformer" in components)
+        if ("platformer" in components || "topdown" in components)
             hasPlayer = true;
-        if (body && bodyType === "dynamic")
+        // Only bodies that gravity actually pulls down need something to stand on.
+        const falls = body && bodyType === "dynamic" && !("topdown" in components) && body.gravityScale !== 0;
+        if (falls && worldGravity !== 0)
             hasDynamic = true;
         if (body && bodyType !== "dynamic" && body.sensor !== true)
             hasSolid = true;
@@ -139,7 +152,7 @@ export function validateScene(raw) {
         }
     }
     if (!hasPlayer) {
-        warn("W_NO_PLAYER", "entities", 'No entity has a "platformer" component, so nothing responds to input.');
+        warn("W_NO_PLAYER", "entities", 'No entity has a "platformer" or "topdown" component, so nothing responds to input (fine if scripts read input).');
     }
     return result();
 }
@@ -177,6 +190,37 @@ function validateFields(fields, value, path, owner, where, error, warn, ignore =
         }
     }
 }
+function validateFonts(fonts, error) {
+    const example = 'Use "fonts": { "Orbitron": "google", "Pixel": "assets/pixel.woff2" }.';
+    if (!isObject(fonts))
+        return void error("E_FONTS_NOT_OBJECT", "fonts", '"fonts" must map font family names to "google" or a font file.', example);
+    for (const [family, src] of Object.entries(fonts)) {
+        const ok = typeof src === "string" && (src === "google" || FONT_EXTENSIONS.some((ext) => src.toLowerCase().endsWith(ext)));
+        if (!ok) {
+            error("E_INVALID_FONT", `fonts.${family}`, `fonts.${family} must be "google" or a font file (${FONT_EXTENSIONS.join(", ")}), got ${describe(src)}.`, example);
+        }
+    }
+}
+function validatePostFx(postfx, error) {
+    const example = 'Use "postfx": { "shader": "shaders/crt.frag", "uniforms": { "strength": 0.5 } }.';
+    if (!isObject(postfx))
+        return void error("E_POSTFX_NOT_OBJECT", "postfx", '"postfx" must be an object.', example);
+    if (typeof postfx.shader !== "string" || postfx.shader === "") {
+        error("E_POSTFX_SHADER", "postfx.shader", "postfx.shader must be the path of a GLSL fragment shader.", example);
+    }
+    if (postfx.uniforms !== undefined) {
+        if (!isObject(postfx.uniforms))
+            return void error("E_POSTFX_UNIFORMS", "postfx.uniforms", "postfx.uniforms must map names to numbers.", example);
+        for (const [name, value] of Object.entries(postfx.uniforms)) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || name.startsWith("u_")) {
+                error("E_POSTFX_UNIFORMS", `postfx.uniforms.${name}`, `"${name}" is not a usable uniform name. Use a GLSL identifier that doesn't start with "u_" (reserved for the engine).`);
+            }
+            else if (typeof value !== "number" || !Number.isFinite(value)) {
+                error("E_POSTFX_UNIFORMS", `postfx.uniforms.${name}`, `postfx.uniforms.${name} must be a number, got ${describe(value)}.`);
+            }
+        }
+    }
+}
 function validateEffects(effects, error, warn) {
     if (!isObject(effects)) {
         error("E_EFFECTS_NOT_OBJECT", "effects", '"effects" must map event names to effects.', 'Use "effects": { "collect": { "sound": "coin" } }.');

package/dist/world.d.ts

@@ -1,5 +1,5 @@
-import { type Body, type Camera, type Collectible, type Emitter, type Goal, type Hazard, type Patrol, type Platformer, type ScriptComponent, type Sprite, type Transform } from "./components.ts";
-import { type Script, type ScriptModules } from "./script.ts";
+import { type Body, type Camera, type Collectible, type Emitter, type Goal, type Hazard, type Patrol, type Platformer, type ScriptComponent, type Sprite, type Topdown, type Transform } from "./components.ts";
+import { type DrawContext, type Script, type ScriptModules } from "./script.ts";
 import { type Action, type Diagnostic, type SceneDef } from "./types.ts";
 export interface BodyState extends Body {
     grounded: boolean;
@@ -11,8 +11,6 @@ export interface PlatformerState extends Platformer {
     /** True from a player-initiated jump until the apex, so only those jumps are cut short on release. */
     jumping: boolean;
     bufferTimer: number;
-    spawnX: number;
-    spawnY: number;
 }
 export interface PatrolState extends Patrol {
     originX: number;
@@ -35,6 +33,12 @@ export interface Entity {
     body?: BodyState;
     sprite?: Sprite;
     platformer?: PlatformerState;
+    topdown?: Topdown;
+    /** Where a player respawns after dying. */
+    spawn?: {
+        x: number;
+        y: number;
+    };
     collectible?: Collectible;
     patrol?: PatrolState;
     hazard?: Hazard;
@@ -72,6 +76,10 @@ export type GameEvent = {
     type: "win";
     entity: string;
     goal: string;
+} | {
+    type: "bounce";
+    entity: string;
+    other: string;
 }
 /** Fired by a script with world.emit(name, data). */
  | {
@@ -131,6 +139,8 @@ export declare class World {
     private scriptInput;
     /** The script hook currently running, for error messages and event attribution. */
     private current;
+    /** True while a draw hook runs: the game can't be changed then. */
+    private drawing;
     constructor(scene: SceneDef, options?: WorldOptions);
     /** Validates raw scene JSON and builds a world, throwing on errors. */
     static fromJSON(raw: unknown, options?: WorldOptions): World;
@@ -146,6 +156,16 @@ export declare class World {
     /** Calls `touch` on scripted entities that started overlapping or touching another body this frame. */
     private updateTouches;
     private callHook;
+    /**
+     * Runs an entity's `draw` or `drawUI` hook. Called by the renderer, never by the
+     * simulation. `self` and `world` are read-only for the duration.
+     */
+    callDrawHook(entity: Entity, hook: "draw" | "drawUI", extras: Omit<DrawContext, "self" | "world" | "params">): void;
+    /** True when any live entity's script has the given hook. */
+    hasHook(hook: "draw" | "drawUI"): boolean;
+    private run;
+    /** Draw hooks only paint, so the browser can't drift from what tests verified. */
+    private guard;
     /** An error caused by how a script used the API, reported against the running script. */
     private misuse;
     /** A stable script-facing view of an entity. */
@@ -156,11 +176,19 @@ export declare class World {
     private spawn;
     /** mulberry32, seeded by world.seed. */
     private random;
+    /** Entities the player controls: platformers and topdown movers. */
     private players;
+    private updateTopdown;
     private updatePlatformers;
     /** Points each patrolling body toward the end of its path it is heading for. */
     private updatePatrols;
     private updateBodies;
+    /**
+     * The velocity along one axis after hitting `solid`: 0, or reversed and scaled by `bounce`.
+     * Slow impacts stop instead, so resting bodies don't jitter.
+     */
+    private rebound;
+    private clampToWorld;
     private updateCollectibles;
     private updateHazards;
     private updateGoals;