@ludra/core 0.4.0 → 0.7.0

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;
@@ -20,13 +26,25 @@ 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>;
+    /**
+     * 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.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;

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 }',
@@ -32,6 +32,9 @@ export function validateScene(raw) {
                     error("E_INVALID_WORLD", `world.${key}`, `world.${key} must be a non-negative number, got ${describe(value)}.`);
                 }
             }
+            if (raw.world.seed !== undefined && (typeof raw.world.seed !== "number" || !Number.isFinite(raw.world.seed))) {
+                error("E_INVALID_WORLD", "world.seed", `world.seed must be a number, got ${describe(raw.world.seed)}.`);
+            }
             if (raw.world.background !== undefined && typeof raw.world.background !== "string") {
                 error("E_INVALID_WORLD", "world.background", `world.background must be a CSS color string, got ${describe(raw.world.background)}.`);
             }
@@ -39,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();
@@ -46,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 = [];
@@ -73,7 +81,7 @@ export function validateScene(raw) {
         for (const [name, value] of Object.entries(components)) {
             const componentPath = `${path}.components.${name}`;
             if (!isComponentName(name)) {
-                const suggestion = closest(name, COMPONENT_NAMES);
+                const suggestion = closestName(name, COMPONENT_NAMES);
                 error("E_UNKNOWN_COMPONENT", componentPath, `Unknown component "${name}" on entity ${label}.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Run \`ludra components\` to list every component.`);
                 continue;
             }
@@ -97,8 +105,18 @@ export function validateScene(raw) {
         if (sprite && typeof sprite.image === "string" && sprite.image !== "" && !hasExtension(sprite.image, IMAGE_EXTENSIONS)) {
             error("E_INVALID_IMAGE", `${path}.components.sprite.image`, `"${sprite.image}" on entity ${label} is not an image file.`, `Use a path ending in ${IMAGE_EXTENSIONS.join(", ")}. SVG is easiest: you can write it as text.`);
         }
+        const script = isObject(components.script) ? components.script : undefined;
+        if (script && typeof script.src === "string" && !hasExtension(script.src, SCRIPT_EXTENSIONS)) {
+            error("E_INVALID_SCRIPT_PATH", `${path}.components.script.src`, `"${script.src}" on entity ${label} is not a script file.`, 'Use a path ending in .ts or .js, e.g. "scripts/chase.ts".');
+        }
         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.');
         }
@@ -116,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;
@@ -132,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();
 }
@@ -155,7 +175,7 @@ function validateFields(fields, value, path, owner, where, error, warn, ignore =
             continue;
         const spec = fields[field];
         if (!spec) {
-            const suggestion = closest(field, Object.keys(fields));
+            const suggestion = closestName(field, Object.keys(fields));
             warn("W_UNKNOWN_FIELD", `${path}.${field}`, `"${owner}" has no field "${field}", so it is ignored.`, suggestion ? `Did you mean "${suggestion}"?` : `Valid fields: ${Object.keys(fields).join(", ")}.`);
             continue;
         }
@@ -170,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" } }.');
@@ -178,9 +229,11 @@ function validateEffects(effects, error, warn) {
     for (const [event, effect] of Object.entries(effects)) {
         const path = `effects.${event}`;
         if (!EVENT_TYPES.includes(event)) {
-            const suggestion = closest(event, EVENT_TYPES);
-            error("E_UNKNOWN_EVENT", path, `There is no "${event}" event.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Events: ${EVENT_TYPES.join(", ")}.`);
-            continue;
+            // Any other name is a custom event that scripts fire with world.emit(). Flag likely typos of built-in ones.
+            const suggestion = closestName(event, EVENT_TYPES);
+            if (suggestion) {
+                warn("W_EVENT_LOOKS_LIKE_TYPO", path, `"${event}" is not a built-in event, so it only fires if a script calls world.emit("${event}").`, `Did you mean "${suggestion}"? Built-in events: ${EVENT_TYPES.join(", ")}.`);
+            }
         }
         if (!isObject(effect)) {
             error("E_EFFECT_NOT_OBJECT", path, `effects.${event} must be an object.`, `Use { "sound": "blip", "particles": { "count": 8 } }.`);
@@ -188,7 +241,7 @@ function validateEffects(effects, error, warn) {
         }
         validateFields(EFFECT_FIELDS, effect, path, `effects.${event}`, "", error, warn, ["particles"]);
         if (typeof effect.sound === "string" && effect.sound !== "" && !isSoundPreset(effect.sound) && !hasExtension(effect.sound, AUDIO_EXTENSIONS)) {
-            const suggestion = closest(effect.sound, SOUND_PRESETS);
+            const suggestion = closestName(effect.sound, SOUND_PRESETS);
             error("E_INVALID_SOUND", `${path}.sound`, `"${effect.sound}" is neither a sound preset nor an audio file.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Presets: ${SOUND_PRESETS.join(", ")}. Files must end in ${AUDIO_EXTENSIONS.join(", ")}.`);
         }
         if (effect.particles !== undefined) {
@@ -201,6 +254,7 @@ function validateEffects(effects, error, warn) {
         }
     }
 }
+const SCRIPT_EXTENSIONS = [".ts", ".js"];
 function hasExtension(path, extensions) {
     const lower = path.toLowerCase();
     return extensions.some((ext) => lower.endsWith(ext));
@@ -223,6 +277,8 @@ function checkField(spec, value) {
                 : `must be one of ${spec.values.map((v) => `"${v}"`).join(", ")}, got ${describe(value)}.`;
         case "frames":
             return typeof value === "string" && isFrameList(value) ? undefined : `must be a frame list like "0", "1-4" or "0,2-3", got ${describe(value)}.`;
+        case "object":
+            return isObject(value) ? undefined : `must be an object like { "speed": 80 }, got ${describe(value)}.`;
     }
 }
 function fixFor(spec) {
@@ -241,7 +297,7 @@ function describe(value) {
     return value === undefined ? "nothing" : JSON.stringify(value);
 }
 /** Returns the candidate within a small edit distance of `input`, if any. */
-function closest(input, candidates) {
+export function closestName(input, candidates) {
     let best;
     let bestDistance = Math.max(2, Math.floor(input.length / 3)) + 1;
     for (const candidate of candidates) {

package/dist/world.d.ts

@@ -1,5 +1,6 @@
-import { type Body, type Camera, type Collectible, type Emitter, type Goal, type Hazard, type Patrol, type Platformer, type Sprite, type Transform } from "./components.ts";
-import type { Action, Diagnostic, SceneDef } from "./types.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;
     /** The solid this body is standing on, so moving platforms can carry it. */
@@ -7,20 +8,37 @@ export interface BodyState extends Body {
 }
 export interface PlatformerState extends Platformer {
     coyoteTimer: number;
+    /** 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;
     originY: number;
 }
+export interface ScriptState extends ScriptComponent {
+    module: Script;
+    started: boolean;
+    /** Ids of entities touched last frame, so `touch` fires only when touching starts. */
+    touching: Set<string>;
+}
 export interface Entity {
     id: string;
+    /** Script-owned data, kept between frames and included in snapshots. */
+    state: Record<string, unknown>;
+    /** Set once destroyed or collected, so stale script handles report `exists: false`. */
+    removed?: boolean;
+    script?: ScriptState;
     transform: Transform;
     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;
@@ -58,6 +76,17 @@ export type GameEvent = {
     type: "win";
     entity: string;
     goal: string;
+} | {
+    type: "bounce";
+    entity: string;
+    other: string;
+}
+/** Fired by a script with world.emit(name, data). */
+ | {
+    type: "custom";
+    name: string;
+    entity: string;
+    data?: unknown;
 });
 export interface EntitySnapshot {
     x: number;
@@ -65,6 +94,12 @@ export interface EntitySnapshot {
     vx: number;
     vy: number;
     grounded: boolean;
+    /** Present when a script stored data on the entity. */
+    state?: Record<string, unknown>;
+}
+export interface WorldOptions {
+    /** Loaded script modules, keyed by the `src` path used in the scene. */
+    scripts?: ScriptModules;
 }
 export interface WorldSnapshot {
     frame: number;
@@ -96,9 +131,19 @@ export declare class World {
     /** Set when a player reaches a goal. The simulation stops changing after that. */
     won: boolean;
     private previousInput;
-    constructor(scene: SceneDef);
+    private readonly scripts;
+    private seed;
+    private spawnCount;
+    private readonly handles;
+    private scriptApi;
+    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): World;
+    static fromJSON(raw: unknown, options?: WorldOptions): World;
     get time(): number;
     get(id: string): Entity | undefined;
     /** Advances one frame with the given actions held down. */
@@ -106,16 +151,52 @@ export declare class World {
     snapshot(): WorldSnapshot;
     private emit;
     private remove;
+    private createEntity;
+    private updateScripts;
+    /** 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. */
+    private handle;
+    private resolve;
+    /** The `world` object scripts receive. */
+    private api;
+    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;
     /** Sends a player back to where it started. Collected items stay collected. */
     private kill;
 }
-/** Strict overlap: bodies that merely touch (e.g. standing on the ground) do not overlap. */
-export declare function overlaps(a: Entity, b: Entity): boolean;
+/**
+ * Strict overlap: bodies that merely touch (e.g. standing on the ground) do not overlap.
+ * A positive `margin` grows both boxes, so touching counts too.
+ */
+export declare function overlaps(a: Entity, b: Entity, margin?: number): boolean;