@ludra/core 0.7.0 → 0.8.0

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;

package/dist/validate.js

@@ -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,6 +42,10 @@ 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)
@@ -161,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;
 }

package/dist/world.d.ts

@@ -43,6 +43,7 @@ export interface Entity {
     patrol?: PatrolState;
     hazard?: Hazard;
     goal?: Goal;
+    checkpoint?: Record<string, never>;
     emitter?: Emitter;
     camera?: Camera;
 }
@@ -80,6 +81,18 @@ export type GameEvent = {
     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). */
  | {
@@ -100,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;
@@ -107,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 {
@@ -130,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;
@@ -145,6 +175,8 @@ export declare class World {
     /** 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;
@@ -192,6 +224,9 @@ export declare class World {
     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;
 }

package/dist/world.js

@@ -2,7 +2,7 @@ import { resolveComponent, } from "./components.js";
 import { getScript, ScriptError, } from "./script.js";
 import { FIXED_DT } from "./time.js";
 import { EVENT_TYPES } from "./types.js";
-import { validateScene } from "./validate.js";
+import { mergeComponents, validateScene } from "./validate.js";
 export class SceneValidationError extends Error {
     diagnostics;
     constructor(diagnostics) {
@@ -43,6 +43,14 @@ export class World {
     deaths = 0;
     /** Set when a player reaches a goal. The simulation stops changing after that. */
     won = false;
+    /** Set when the game is over: out of lives, or a script called world.lose(). */
+    lost = false;
+    /** Lives left, or undefined for unlimited retries. */
+    lives;
+    /** The scene to play next (a won goal's `next`, or world.goto). Hosts that can load scenes move on to it. */
+    exit;
+    prefabs;
+    reached = new Set();
     previousInput = new Set();
     scripts;
     seed;
@@ -61,6 +69,10 @@ export class World {
         this.background = scene.world?.background ?? "#1d2333";
         this.seed = scene.world?.seed ?? 1;
         this.scripts = options.scripts;
+        this.prefabs = scene.prefabs ?? {};
+        this.score = options.carry?.score ?? 0;
+        this.deaths = options.carry?.deaths ?? 0;
+        this.lives = options.carry?.lives ?? scene.world?.lives;
         this.entities = scene.entities.map((def) => this.createEntity(def));
     }
     /** Validates raw scene JSON and builds a world, throwing on errors. */
@@ -73,6 +85,10 @@ export class World {
     get time() {
         return this.frame * FIXED_DT;
     }
+    /** True once nothing more happens in this scene: won, lost, or moving on to another scene. */
+    get over() {
+        return this.won || this.lost || this.exit !== undefined;
+    }
     get(id) {
         return this.entities.find((e) => e.id === id);
     }
@@ -81,20 +97,23 @@ export class World {
         const pressed = new Set([...input].filter((action) => !this.previousInput.has(action)));
         this.previousInput = new Set(input);
         this.frame++;
-        if (this.won)
+        if (this.over)
             return;
         this.updatePlatformers(input, pressed);
         this.updateTopdown(input);
         this.updateScripts(input, pressed);
-        if (this.won)
+        if (this.over)
             return;
         this.updatePatrols();
         this.updateBodies();
         this.updateTouches();
-        if (this.won)
+        if (this.over)
             return;
         this.updateCollectibles();
+        this.updateCheckpoints();
         this.updateHazards();
+        if (this.over)
+            return;
         this.updateGoals();
     }
     snapshot() {
@@ -111,7 +130,7 @@ export class World {
             if (Object.keys(e.state).length > 0)
                 entities[e.id].state = JSON.parse(JSON.stringify(e.state));
         }
-        return { frame: this.frame, time: this.time, score: this.score, deaths: this.deaths, won: this.won, entities };
+        return { frame: this.frame, time: this.time, score: this.score, deaths: this.deaths, won: this.won, lost: this.lost, lives: this.lives, entities };
     }
     emit(event) {
         this.events.push({ ...event, frame: this.frame, time: this.time });
@@ -146,9 +165,9 @@ export class World {
                 e.script.started = true;
                 this.callHook(e, "start");
             }
-            if (!e.removed && !this.won)
+            if (!e.removed && !this.over)
                 this.callHook(e, "update");
-            if (this.won)
+            if (this.over)
                 return;
         }
     }
@@ -324,6 +343,23 @@ export class World {
             get won() {
                 return world.won;
             },
+            get lost() {
+                return world.lost;
+            },
+            get exit() {
+                return world.exit;
+            },
+            get lives() {
+                return world.lives;
+            },
+            set lives(value) {
+                world.guard("Setting lives");
+                if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))
+                    throw world.misuse("world.lives must be a number.");
+                world.lives = value;
+                if (value !== undefined && value <= 0)
+                    world.gameOver(world.current?.entity.id ?? "script", "script");
+            },
             set score(value) {
                 world.guard("Setting score");
                 world.score = value;
@@ -365,6 +401,20 @@ export class World {
                 world.won = true;
                 world.emit({ type: "win", entity: by?.id ?? "script", goal: by?.id ?? "script", x: by?.transform.x ?? 0, y: by?.transform.y ?? 0 });
             },
+            lose: () => {
+                world.guard("world.lose");
+                world.gameOver(world.current?.entity.id ?? "script", "script");
+            },
+            goto: (scene) => {
+                world.guard("world.goto");
+                if (typeof scene !== "string" || scene === "")
+                    throw world.misuse('world.goto needs a scene path, e.g. "scenes/level-1.scene.json".');
+                if (world.exit !== undefined)
+                    return;
+                world.exit = scene;
+                const by = world.current?.entity;
+                world.emit({ type: "goto", entity: by?.id ?? "script", scene, x: by?.transform.x ?? 0, y: by?.transform.y ?? 0 });
+            },
             emit: (name, data) => {
                 world.guard("world.emit");
                 if (typeof name !== "string" || name === "")
@@ -383,19 +433,28 @@ export class World {
         return this.scriptApi;
     }
     spawn(def) {
-        if (typeof def !== "object" || def === null || typeof def.components !== "object") {
-            throw this.misuse('world.spawn needs { components: { ... } }, e.g. { components: { transform: { x: 0, y: 0 } } }.');
+        if (typeof def !== "object" || def === null || (def.prefab === undefined && typeof def.components !== "object")) {
+            throw this.misuse('world.spawn needs { components: { ... } } or { prefab: "name" }, e.g. { prefab: "bullet", components: { transform: { x: 0, y: 0 } } }.');
+        }
+        let components = def.components ?? {};
+        if (def.prefab !== undefined) {
+            const prefab = this.prefabs[def.prefab];
+            if (!prefab) {
+                const names = Object.keys(this.prefabs);
+                throw this.misuse(`world.spawn: prefab "${def.prefab}" does not exist.${names.length > 0 ? ` Prefabs: ${names.join(", ")}.` : " Create prefabs/<name>.prefab.json."}`);
+            }
+            components = mergeComponents(prefab.components, components);
         }
         const id = def.id ?? `${this.current?.entity.id ?? "spawned"}-${++this.spawnCount}`;
         if (this.get(id))
             throw this.misuse(`world.spawn: an entity with id "${id}" already exists. Leave id out to get a unique one.`);
-        const { diagnostics } = validateScene({ entities: [{ id, components: def.components }] });
+        const { diagnostics } = validateScene({ entities: [{ id, components }] });
         const errors = diagnostics.filter((d) => d.severity === "error" && d.code !== "E_GOAL_UNREACHABLE");
         if (errors.length > 0) {
             const details = errors.map((d) => `${d.path.replace("entities[0]", id)}: ${d.message}${d.fix ? ` Fix: ${d.fix}` : ""}`);
             throw this.misuse(`world.spawn got an invalid entity. ${details.join(" ")}`);
         }
-        const entity = this.createEntity({ id, components: def.components });
+        const entity = this.createEntity({ id, components });
         this.entities.push(entity);
         return this.handle(entity);
     }
@@ -618,15 +677,44 @@ export class World {
             if (!player)
                 continue;
             this.won = true;
+            if (goal.goal.next)
+                this.exit = goal.goal.next;
             this.emit({ type: "win", entity: player.id, goal: goal.id, ...goal.transform });
             return;
         }
     }
+    /** A touched checkpoint becomes the player's respawn point, standing on the checkpoint's bottom edge. */
+    updateCheckpoints() {
+        for (const checkpoint of this.entities.filter((e) => e.checkpoint && e.body)) {
+            for (const player of this.players()) {
+                const key = `${player.id}>${checkpoint.id}`;
+                if (this.reached.has(key) || !overlaps(player, checkpoint))
+                    continue;
+                this.reached.add(key);
+                const bottom = checkpoint.transform.y + checkpoint.body.height / 2;
+                player.spawn = { x: checkpoint.transform.x, y: player.platformer ? bottom - player.body.height / 2 : checkpoint.transform.y };
+                this.emit({ type: "checkpoint", entity: player.id, checkpoint: checkpoint.id, ...checkpoint.transform });
+            }
+        }
+    }
+    gameOver(entity, cause) {
+        if (this.lost)
+            return;
+        this.lost = true;
+        const e = this.get(entity);
+        this.emit({ type: "gameover", entity, cause, x: e?.transform.x ?? 0, y: e?.transform.y ?? 0 });
+    }
     /** Sends a player back to where it started. Collected items stay collected. */
     kill(player, cause) {
         const b = player.body;
         this.deaths++;
         this.emit({ type: "die", entity: player.id, cause, ...player.transform });
+        if (this.lives !== undefined) {
+            this.lives--;
+            // Out of lives: the player stays where it fell and the game is over.
+            if (this.lives <= 0)
+                return this.gameOver(player.id, cause);
+        }
         player.transform.x = player.spawn?.x ?? player.transform.x;
         player.transform.y = player.spawn?.y ?? player.transform.y;
         b.vx = 0;
@@ -669,6 +757,8 @@ function createEntity(def) {
         entity.hazard = resolveComponent("hazard", c.hazard);
     if (c.goal)
         entity.goal = resolveComponent("goal", c.goal);
+    if (c.checkpoint)
+        entity.checkpoint = {};
     if (c.emitter)
         entity.emitter = resolveComponent("emitter", c.emitter);
     if (c.camera)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Ludra engine runtime: scene format, validation, deterministic simulation and rendering.",
   "license": "MIT",
   "repository": {

package/src/assertions.ts

@@ -10,7 +10,7 @@ type Operator = (typeof OPERATORS)[number];
 const ENTITY_FIELDS = ["x", "y", "vx", "vy", "grounded", "exists"] as const;
 type EntityField = (typeof ENTITY_FIELDS)[number];
 
-const WORLD_FIELDS = ["score", "deaths", "won"] as const;
+const WORLD_FIELDS = ["score", "deaths", "won", "lost", "lives"] as const;
 type WorldField = (typeof WORLD_FIELDS)[number];
 
 type Subject =
@@ -100,6 +100,9 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
     case "world":
       actual = snapshot[subject.field];
       label = subject.field;
+      if (actual === undefined) {
+        return { source, pass: false, actual, time, message: `${label} is not set: the scene has unlimited retries. Add "lives" to "world" to count them.` };
+      }
       break;
     case "events": {
       const matches = (e: GameEvent) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
@@ -184,6 +187,8 @@ function round(n: number): number {
 /** One case in a `tests/*.test.json` file. */
 export interface TestCase {
   name: string;
+  /** Scene to run, relative to the project. Defaults to the entry scene in ludra.json. */
+  scene?: string;
   /** Input script, see `InputScript`. */
   inputs?: string;
   /** Run length, e.g. "3s". Defaults to the inputs plus one second, or the latest `at`. */
@@ -197,6 +202,8 @@ export interface TestResult {
   duration: number;
   results: AssertionResult[];
   error?: string;
+  /** Names of the events that fired during the run (built-in types and custom names). */
+  events: string[];
 }
 
 export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions = {}): TestResult {
@@ -215,7 +222,7 @@ export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions =
         ? secondsToFrames(typeof test.duration === "number" ? test.duration : parseDuration(test.duration))
         : Math.max(secondsToFrames(defaultDuration(script)), latestAt);
   } catch (err) {
-    return { name: test.name, pass: false, duration: 0, results: [], error: (err as Error).message };
+    return { name: test.name, pass: false, duration: 0, results: [], error: (err as Error).message, events: [] };
   }
 
   const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
@@ -228,12 +235,13 @@ export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions =
     });
   } catch (err) {
     // A throwing script fails this test, not the whole run.
-    return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: (err as Error).message };
+    return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: (err as Error).message, events: [] };
   }
 
   const results = assertions.map((a) => {
     const frame = a.at === "end" ? frames : Math.min(a.at, frames);
     return evaluateAssertion(a, snapshots.get(frame)!, world.events);
   });
-  return { name: test.name, pass: results.every((r) => r.pass), duration: frames * FIXED_DT, results };
+  const events = [...new Set(world.events.map((e) => (e.type === "custom" ? e.name : e.type)))];
+  return { name: test.name, pass: results.every((r) => r.pass), duration: frames * FIXED_DT, results, events };
 }