@ludra/core 0.5.0 → 0.8.0

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 }',
@@ -9,18 +9,22 @@ const REQUIRED_EXAMPLES = {
  * Checks a parsed scene file. Every diagnostic names the exact JSON path and,
  * where possible, a fix an agent can apply without guessing.
  */
-export function validateScene(raw) {
+export function validateScene(input) {
     const diagnostics = [];
     const error = (code, path, message, fix) => diagnostics.push({ severity: "error", code, path, message, fix });
     const warn = (code, path, message, fix) => diagnostics.push({ severity: "warning", code, path, message, fix });
     const result = () => {
         const ok = !diagnostics.some((d) => d.severity === "error");
-        return { ok, diagnostics, scene: ok ? raw : undefined };
+        return { ok, diagnostics, scene: ok ? scene : undefined };
     };
-    if (!isObject(raw)) {
+    let scene = input;
+    if (!isObject(input)) {
         error("E_SCENE_NOT_OBJECT", "$", "A scene must be a JSON object.", 'Start from { "entities": [] }.');
         return result();
     }
+    // Prefabs become plain entities first, so everything below sees the final components.
+    const raw = expandPrefabs(input, error);
+    scene = raw;
     if (raw.world !== undefined) {
         if (!isObject(raw.world)) {
             error("E_WORLD_NOT_OBJECT", "world", '"world" must be an object.', 'Use "world": { "width": 960, "height": 540 }.');
@@ -38,10 +42,18 @@ export function validateScene(raw) {
             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)}.`);
             }
+            const lives = raw.world.lives;
+            if (lives !== undefined && (typeof lives !== "number" || !Number.isInteger(lives) || lives < 1)) {
+                error("E_INVALID_WORLD", "world.lives", `world.lives must be a whole number of at least 1, got ${describe(lives)}.`, "Leave it out for unlimited retries.");
+            }
         }
     }
     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 +61,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 +119,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 +142,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 +160,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();
 }
@@ -148,7 +169,68 @@ const SENSOR_COMPONENTS = [
     ["collectible", "players would bump into it instead of picking it up"],
     ["hazard", "players would stand on it instead of being hurt"],
     ["goal", "players would bump into it instead of reaching it"],
+    ["checkpoint", "players would bump into it instead of passing through"],
 ];
+/**
+ * Replaces `"prefab": "<name>"` entities with the prefab's components, with the
+ * entity's own components merged over them (field by field; `null` removes a
+ * component). Returns a new scene object; reports unknown prefabs.
+ */
+function expandPrefabs(raw, error) {
+    const prefabs = raw.prefabs;
+    if (prefabs !== undefined) {
+        if (!isObject(prefabs)) {
+            error("E_PREFABS_NOT_OBJECT", "prefabs", '"prefabs" must map names to { "components": { ... } }.');
+            return raw;
+        }
+        for (const [name, prefab] of Object.entries(prefabs)) {
+            if (!isObject(prefab) || !isObject(prefab.components)) {
+                error("E_INVALID_PREFAB", `prefabs.${name}`, `Prefab "${name}" needs a "components" object.`, 'Use { "components": { "body": { ... }, "sprite": { ... } } }.');
+                continue;
+            }
+            for (const component of Object.keys(prefab.components)) {
+                if (!isComponentName(component)) {
+                    const suggestion = closestName(component, COMPONENT_NAMES);
+                    error("E_UNKNOWN_COMPONENT", `prefabs.${name}.components.${component}`, `Unknown component "${component}" in prefab "${name}".`, suggestion ? `Did you mean "${suggestion}"?` : undefined);
+                }
+            }
+        }
+    }
+    if (!Array.isArray(raw.entities))
+        return raw;
+    const known = isObject(prefabs) ? prefabs : {};
+    const entities = raw.entities.map((entity, i) => {
+        if (!isObject(entity) || entity.prefab === undefined)
+            return entity;
+        const name = entity.prefab;
+        const prefab = typeof name === "string" ? known[name] : undefined;
+        if (!isObject(prefab) || !isObject(prefab.components)) {
+            const names = Object.keys(known);
+            const suggestion = typeof name === "string" ? closestName(name, names) : undefined;
+            error("E_UNKNOWN_PREFAB", `entities[${i}].prefab`, `Prefab ${describe(name)} does not exist.`, suggestion ? `Did you mean "${suggestion}"?` : names.length > 0 ? `Prefabs: ${names.join(", ")}.` : "Create prefabs/<name>.prefab.json with { \"components\": { ... } }.");
+            return entity;
+        }
+        const { prefab: _, ...rest } = entity;
+        return { ...rest, components: mergeComponents(prefab.components, isObject(entity.components) ? entity.components : {}) };
+    });
+    return { ...raw, entities };
+}
+/** A prefab's components with overrides merged in, one level deep. `null` drops a component. */
+export function mergeComponents(base, overrides) {
+    const merged = {};
+    for (const [name, value] of Object.entries(base))
+        if (isObject(value))
+            merged[name] = structuredClone(value);
+    for (const [name, value] of Object.entries(overrides)) {
+        if (value === null)
+            delete merged[name];
+        else if (isObject(value) && isObject(merged[name]))
+            merged[name] = { ...merged[name], ...structuredClone(value) };
+        else
+            merged[name] = structuredClone(value);
+    }
+    return merged;
+}
 function numberOr(value, fallback) {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
@@ -177,6 +259,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,10 +33,17 @@ 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;
     goal?: Goal;
+    checkpoint?: Record<string, never>;
     emitter?: Emitter;
     camera?: Camera;
 }
@@ -72,6 +77,22 @@ export type GameEvent = {
     type: "win";
     entity: string;
     goal: string;
+} | {
+    type: "bounce";
+    entity: string;
+    other: string;
+} | {
+    type: "checkpoint";
+    entity: string;
+    checkpoint: string;
+} | {
+    type: "gameover";
+    entity: string;
+    cause: string;
+} | {
+    type: "goto";
+    entity: string;
+    scene: string;
 }
 /** Fired by a script with world.emit(name, data). */
  | {
@@ -92,6 +113,12 @@ export interface EntitySnapshot {
 export interface WorldOptions {
     /** Loaded script modules, keyed by the `src` path used in the scene. */
     scripts?: ScriptModules;
+    /** Values carried over from the previous scene, so a run keeps its score and lives. */
+    carry?: {
+        score?: number;
+        deaths?: number;
+        lives?: number;
+    };
 }
 export interface WorldSnapshot {
     frame: number;
@@ -99,6 +126,9 @@ export interface WorldSnapshot {
     score: number;
     deaths: number;
     won: boolean;
+    lost: boolean;
+    /** Lives left; undefined when the scene has unlimited retries. */
+    lives?: number;
     entities: Record<string, EntitySnapshot>;
 }
 export declare class SceneValidationError extends Error {
@@ -122,6 +152,14 @@ export declare class World {
     deaths: number;
     /** Set when a player reaches a goal. The simulation stops changing after that. */
     won: boolean;
+    /** Set when the game is over: out of lives, or a script called world.lose(). */
+    lost: boolean;
+    /** Lives left, or undefined for unlimited retries. */
+    lives: number | undefined;
+    /** The scene to play next (a won goal's `next`, or world.goto). Hosts that can load scenes move on to it. */
+    exit: string | undefined;
+    private readonly prefabs;
+    private readonly reached;
     private previousInput;
     private readonly scripts;
     private seed;
@@ -131,10 +169,14 @@ 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;
     get time(): number;
+    /** True once nothing more happens in this scene: won, lost, or moving on to another scene. */
+    get over(): boolean;
     get(id: string): Entity | undefined;
     /** Advances one frame with the given actions held down. */
     step(input: ReadonlySet<Action>): void;
@@ -146,6 +188,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,14 +208,25 @@ 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;
+    /** A touched checkpoint becomes the player's respawn point, standing on the checkpoint's bottom edge. */
+    private updateCheckpoints;
+    private gameOver;
     /** Sends a player back to where it started. Collected items stay collected. */
     private kill;
 }