@ludra/core 0.7.0 → 0.8.0

package/src/browser.ts

@@ -6,8 +6,8 @@ import { ParticleSystem } from "./particles.ts";
 import { PostFx } from "./postfx.ts";
 import type { DrawContext, DrawEvent, Script } from "./script.ts";
 import { FIXED_DT } from "./time.ts";
-import type { Action, SceneDef } from "./types.ts";
-import { World, type Entity } from "./world.ts";
+import type { Action, PostFxDef, SceneDef } from "./types.ts";
+import { World, type Entity, type GameEvent } from "./world.ts";
 
 const KEYMAP: Record<string, Action> = {
   ArrowLeft: "left",
@@ -36,6 +36,11 @@ export interface GameOptions {
   scriptBase?: string;
   /** Scripts to load. Defaults to those the scene references; include any that `world.spawn` uses. */
   scriptPaths?: readonly string[];
+  /**
+   * Loads another scene by path, for goals with `next` and `world.goto`. Without it the
+   * game stays on its first scene. Throw with a readable message if the scene is invalid.
+   */
+  loadScene?: (path: string) => Promise<SceneDef>;
 }
 
 /** Imports the game's script modules, keyed by their path in the scene. */
@@ -82,76 +87,153 @@ async function loadFonts(scene: SceneDef, assetBase: string): Promise<void> {
   await Promise.race([all, new Promise((resolve) => setTimeout(resolve, 4000))]);
 }
 
-interface Stage {
-  /** Where the game draws. With postfx this is an offscreen canvas. */
-  ctx: CanvasRenderingContext2D;
-  /** The canvas players see. */
-  output: HTMLCanvasElement;
-  images: Map<string, HTMLImageElement>;
-  scripts: Map<string, Script>;
-  /** Shows the drawn frame: runs the postfx shader, or does nothing without one. */
-  present(time: number): void;
-  /** Why postfx couldn't start (the game then runs without it and shows this message). */
-  error?: string;
+/** A scene's postfx shader source, or why it couldn't be fetched. */
+async function loadShader(scene: SceneDef, assetBase: string): Promise<string | Error | undefined> {
+  const path = scene.postfx?.shader;
+  if (!path) return undefined;
+  const response = await fetch(assetBase + path).catch((err: unknown) => err as Error);
+  if (response instanceof Error) return response;
+  return response.ok ? response.text() : new Error(`could not load ${path} (${response.status})`);
 }
 
 /**
- * Loads everything a scene needs and sets up its canvases. With `postfx`, `canvas`
- * becomes the offscreen source and a WebGL canvas takes its place in the page.
+ * The canvas players see. The game always draws into the 2D canvas; when a scene
+ * has `postfx`, a WebGL canvas running its shader takes the 2D canvas's place in
+ * the page, and goes away again for a scene without one.
  */
-async function prepare(canvas: HTMLCanvasElement, scene: SceneDef, options: GameOptions): Promise<Stage> {
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Canvas 2D context is not available.");
+class Screen {
+  readonly ctx: CanvasRenderingContext2D;
+  output: HTMLCanvasElement;
+  private readonly canvas: HTMLCanvasElement;
+  private fx: PostFx | undefined;
+
+  constructor(canvas: HTMLCanvasElement) {
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("Canvas 2D context is not available.");
+    this.ctx = ctx;
+    this.canvas = canvas;
+    this.output = canvas;
+  }
+
+  /** Switches to a scene's shader, or to none. Returns why the shader can't run, if it can't. */
+  use(postfx: PostFxDef | undefined, shader: string | Error | undefined): string | undefined {
+    let fx: PostFx | undefined;
+    let error: string | undefined;
+    if (postfx && shader !== undefined) {
+      try {
+        if (shader instanceof Error) throw shader;
+        fx = new PostFx(this.canvas.width, this.canvas.height, shader, postfx);
+      } catch (err) {
+        error = `postfx: ${message(err)}`;
+        console.error("[ludra]", err);
+      }
+    }
+    const target = fx?.canvas ?? this.canvas;
+    if (target !== this.output) {
+      target.id = this.canvas.id;
+      target.className = this.canvas.className;
+      target.style.cssText = this.canvas.style.cssText;
+      this.output.replaceWith(target);
+      this.output = target;
+    }
+    this.fx = fx;
+    return error;
+  }
+
+  /** Shows the frame the game just drew, through the shader if there is one. */
+  present(time: number): void {
+    this.fx?.render(this.canvas, time);
+  }
+}
+
+/** What a scene needs before it can be drawn. */
+async function loadScene(scene: SceneDef, options: GameOptions, scripts: Map<string, Script>) {
   const assetBase = options.assetBase ?? "";
-  const shaderPath = scene.postfx?.shader;
-  const [images, scripts, shader] = await Promise.all([
+  const [images, more, shader] = await Promise.all([
     loadImages(scene, assetBase),
     loadScripts(scene, options),
-    shaderPath
-      ? fetch(assetBase + shaderPath).then(async (r) => (r.ok ? r.text() : new Error(`could not load ${shaderPath} (${r.status})`)))
-      : undefined,
+    loadShader(scene, assetBase),
     loadFonts(scene, assetBase),
   ]);
-  const stage: Stage = { ctx, output: canvas, images, scripts, present: () => {} };
-  if (scene.postfx && shader !== undefined) {
-    try {
-      if (shader instanceof Error) throw shader;
-      const fx = new PostFx(canvas.width, canvas.height, shader, scene.postfx);
-      fx.canvas.id = canvas.id;
-      fx.canvas.className = canvas.className;
-      fx.canvas.style.cssText = canvas.style.cssText;
-      canvas.replaceWith(fx.canvas);
-      stage.output = fx.canvas;
-      stage.present = (time) => fx.render(canvas, time);
-    } catch (err) {
-      stage.error = `postfx: ${message(err)}`;
-      console.error("[ludra]", err);
-    }
-  }
-  return stage;
+  for (const [path, script] of more) scripts.set(path, script);
+  return { images, shader };
 }
 
 function message(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** Seconds the win screen shows before the next scene, and the fade into a world.goto scene. */
+const WIN_PAUSE = 1.6;
+const GOTO_FADE = 0.35;
+
 /**
  * Runs a scene in a canvas with keyboard controls, images, particles and
  * sound. The simulation uses the same fixed step as headless runs, so what
  * tests verify is what players get; everything added here is presentation.
+ * With `options.loadScene`, won goals with `next` and `world.goto` move on
+ * to other scenes, keeping score, deaths and lives.
  * Resolves (after images load) to a function that stops the game.
  */
-export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, options: GameOptions = {}): Promise<() => void> {
-  const { ctx, images, scripts, present, error } = await prepare(canvas, scene, options);
+export async function startGame(canvas: HTMLCanvasElement, firstScene: SceneDef, options: GameOptions = {}): Promise<() => void> {
+  const screen = new Screen(canvas);
+  const ctx = screen.ctx;
   const sounds = new SoundPlayer(options.assetBase ?? "");
-  const view = new View(scene, images);
+  const scripts = new Map<string, Script>();
 
-  let world = new World(scene, { scripts });
-  let crash: string | undefined = error;
+  type Carry = { score: number; deaths: number; lives: number | undefined };
+  let scene = firstScene;
+  let startCarry: Carry | undefined;
+  let view: View;
+  let world: World;
+  let crash: string | undefined;
+  let sceneError: string | undefined;
+  /** Real time when the world asked to move on, while waiting to load the next scene. */
+  let exitSince: number | undefined;
+  let loading = false;
+
+  const enter = async (next: SceneDef, carry: Carry | undefined) => {
+    const { images, shader } = await loadScene(next, options, scripts);
+    scene = next;
+    startCarry = carry;
+    view = new View(next, images);
+    sceneError = screen.use(next.postfx, shader);
+    crash = sceneError;
+    exitSince = undefined;
+    try {
+      world = new World(next, { scripts, carry });
+    } catch (err) {
+      crash = message(err);
+      world = new World({ ...next, entities: [] });
+    }
+  };
+  await enter(firstScene, undefined);
+
+  // Game over starts the whole game again; otherwise R restarts the current scene as it began.
   const restart = () => {
-    world = new World(scene, { scripts });
+    if (loading) return;
+    if (world.lost && scene !== firstScene) {
+      loading = true;
+      void enter(firstScene, undefined).finally(() => (loading = false));
+      return;
+    }
+    world = new World(scene, { scripts, carry: startCarry });
     view.reset();
-    crash = error;
+    crash = sceneError;
+    exitSince = undefined;
+  };
+
+  const moveOn = (path: string) => {
+    if (!options.loadScene) return;
+    loading = true;
+    const carry = { score: world.score, deaths: world.deaths, lives: world.lives };
+    options
+      .loadScene(path)
+      .then((next) => enter(next, carry))
+      .catch((err: unknown) => {
+        crash = `Could not load the next scene "${path}": ${message(err)}`;
+      })
+      .finally(() => (loading = false));
   };
 
   const held = new Set<Action>();
@@ -185,7 +267,7 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
   const frame = (now: number) => {
     accumulator += Math.min(MAX_FRAME_TIME, (now - last) / 1000);
     last = now;
-    while (accumulator >= FIXED_DT && !crash) {
+    while (accumulator >= FIXED_DT && !crash && !loading) {
       try {
         world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
       } catch (err) {
@@ -197,15 +279,30 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
       view.step(world, (sound) => sounds.play(sound));
       accumulator -= FIXED_DT;
     }
+
+    // Moving on: let the win screen show, or fade out for a world.goto, then load.
+    let fade = 0;
+    if (world.exit !== undefined && options.loadScene && !crash) {
+      exitSince ??= now;
+      const pause = world.won ? WIN_PAUSE : GOTO_FADE;
+      const elapsed = (now - exitSince) / 1000;
+      fade = Math.min(1, Math.max(0, (elapsed - (pause - GOTO_FADE)) / GOTO_FADE));
+      if (elapsed >= pause && !loading) moveOn(world.exit);
+    }
+
     try {
-      view.draw(ctx, world, sounds.muted);
+      view.draw(ctx, world, sounds.muted, options.loadScene !== undefined);
     } catch (err) {
       // A draw hook threw. Same treatment as a simulation error.
       if (!crash) console.error("[ludra]", err);
       crash ??= message(err);
     }
+    if (fade > 0 || loading) {
+      ctx.fillStyle = `rgba(0, 0, 0, ${loading ? 1 : fade})`;
+      ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    }
     if (crash) drawCrash(ctx, crash);
-    present(world.time);
+    screen.present(world.time);
     raf = requestAnimationFrame(frame);
   };
   raf = requestAnimationFrame(frame);
@@ -239,7 +336,10 @@ export interface CapturedFrame {
  * `ludra play --screenshot`.
  */
 export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef, options: CaptureOptions): Promise<CapturedFrame[]> {
-  const { ctx, output, images, scripts, present, error } = await prepare(canvas, scene, options);
+  const screen = new Screen(canvas);
+  const scripts = new Map<string, Script>();
+  const { images, shader } = await loadScene(scene, options, scripts);
+  const error = screen.use(scene.postfx, shader);
   if (error) throw new Error(error);
   const view = new View(scene, images);
   const world = new World(scene, { scripts });
@@ -250,9 +350,9 @@ export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef,
 
   for (let frame = 0; ; frame++) {
     if (wanted.has(frame)) {
-      view.draw(ctx, world, false);
-      present(world.time);
-      captured.push({ frame, time: frame * FIXED_DT, png: output.toDataURL("image/png") });
+      view.draw(screen.ctx, world, false, false);
+      screen.present(world.time);
+      captured.push({ frame, time: frame * FIXED_DT, png: screen.output.toDataURL("image/png") });
     }
     if (frame >= last) break;
     world.step(script.at(frame));
@@ -322,9 +422,15 @@ class View {
   private readonly scene: SceneDef;
   private readonly images: Map<string, HTMLImageElement>;
 
+  /** Whether the scene can award points at all, so the default HUD can leave the score out. */
+  private readonly scoring: boolean;
+
   constructor(scene: SceneDef, images: Map<string, HTMLImageElement>) {
     this.scene = scene;
     this.images = images;
+    this.scoring = scene.entities.some(
+      (e) => e.components.collectible || (e.components.hazard && Number(e.components.hazard.score) > 0) || Number(e.components.goal?.requireScore) > 0,
+    );
   }
 
   reset(): void {
@@ -362,7 +468,8 @@ class View {
     this.shake = this.shake < 0.5 ? 0 : this.shake * SHAKE_DECAY;
   }
 
-  draw(ctx: CanvasRenderingContext2D, world: World, muted: boolean): void {
+  /** `continues`: the host loads next scenes, so a won scene with `next` says so instead of offering a replay. */
+  draw(ctx: CanvasRenderingContext2D, world: World, muted: boolean, continues: boolean): void {
     const { width: viewWidth, height: viewHeight } = ctx.canvas;
     ctx.imageSmoothingEnabled = false;
     ctx.fillStyle = world.background;
@@ -398,25 +505,32 @@ class View {
       return;
     }
 
+    // Only what this scene uses: no "Score 0" in a game without points.
+    const parts: string[] = [];
+    if (world.lives !== undefined) parts.push(`${"♥".repeat(Math.max(0, Math.min(world.lives, 10)))}${world.lives > 10 ? ` ${world.lives}` : ""}`);
+    if (this.scoring || world.score !== 0) parts.push(`Score ${world.score}`);
+    if (world.lives === undefined) parts.push(`Deaths ${world.deaths}`);
     ctx.textAlign = "left";
     ctx.font = "600 18px system-ui, sans-serif";
     ctx.fillStyle = "#ffffff";
-    ctx.fillText(`Score ${world.score}   Deaths ${world.deaths}`, 16, 30);
+    ctx.fillText(parts.join("   "), 16, 30);
     ctx.textAlign = "right";
     ctx.font = "500 13px system-ui, sans-serif";
     ctx.fillStyle = "rgba(255, 255, 255, 0.6)";
     ctx.fillText(`M: sound ${muted ? "off" : "on"} · R: restart`, viewWidth - 16, 28);
 
-    if (world.won) {
+    if (world.won || world.lost) {
       ctx.fillStyle = "rgba(0, 0, 0, 0.55)";
       ctx.fillRect(0, 0, viewWidth, viewHeight);
       ctx.fillStyle = "#ffffff";
       ctx.textAlign = "center";
       ctx.font = "700 44px system-ui, sans-serif";
-      ctx.fillText("Level complete!", viewWidth / 2, viewHeight / 2 - 10);
+      ctx.fillText(world.won ? "Level complete!" : "Game over", viewWidth / 2, viewHeight / 2 - 10);
       ctx.font = "500 18px system-ui, sans-serif";
-      const winTime = world.events.find((e) => e.type === "win")?.time ?? world.time;
-      ctx.fillText(`Score ${world.score} · ${winTime.toFixed(1)}s · Press R to play again`, viewWidth / 2, viewHeight / 2 + 30);
+      const endTime = world.events.find((e) => e.type === "win" || e.type === "gameover")?.time ?? world.time;
+      const next = world.won && world.exit !== undefined && continues ? "Get ready…" : `Press R to ${world.won ? "play again" : "try again"}`;
+      const score = this.scoring || world.score !== 0 ? `Score ${world.score} · ` : "";
+      ctx.fillText(`${score}${endTime.toFixed(1)}s · ${next}`, viewWidth / 2, viewHeight / 2 + 30);
     }
   }
 
@@ -524,7 +638,10 @@ function recentEvents(world: World, name: string | undefined, seconds: number):
     if (event.time < since) break;
     const eventName = event.type === "custom" ? event.name : event.type;
     if (name !== undefined && eventName !== name) continue;
-    result.push({ name: eventName, time: event.time, x: event.x, y: event.y, entity: event.entity, data: event.type === "custom" ? event.data : undefined });
+    // Custom events carry what the script passed; built-in ones their own details (item, enemy, checkpoint...).
+    const { type: _type, frame: _frame, time, x, y, entity, ...details } = event as GameEvent & { data?: unknown };
+    const data = event.type === "custom" ? event.data : details;
+    result.push({ name: eventName, time, x, y, entity, data });
   }
   return result.reverse();
 }

package/src/components.ts

@@ -25,6 +25,7 @@ export const COMPONENT_NAMES = [
   "patrol",
   "hazard",
   "goal",
+  "checkpoint",
   "emitter",
   "script",
   "camera",
@@ -155,8 +156,19 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
     requires: ["transform", "body"],
     fields: {
       requireScore: { type: "number", min: 0, default: 0, description: "Score needed before the goal accepts the player." },
+      next: {
+        type: "string",
+        default: "",
+        description: 'Scene to play after this one is won, e.g. "scenes/level-2.scene.json". The browser moves on and keeps score, deaths and lives; each scene is tested on its own.',
+      },
     },
   },
+  checkpoint: {
+    description:
+      "When a player touches it, that player respawns here after dying (standing on the checkpoint's bottom edge). Fires a checkpoint event once. Its body must be a sensor.",
+    requires: ["transform", "body"],
+    fields: {},
+  },
   emitter: {
     description: "Continuously emits visual particles from the entity (torches, sparkles, smoke). It does not affect gameplay.",
     requires: ["transform"],
@@ -268,6 +280,7 @@ export interface Hazard {
 
 export interface Goal {
   requireScore: number;
+  next: string;
 }
 
 export interface Camera {

package/src/effects.ts

@@ -19,7 +19,7 @@ export const EFFECT_FIELDS: Record<string, FieldSpec> = {
 };
 
 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.';
+  '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: string): sound is SoundPreset {
   return (SOUND_PRESETS as readonly string[]).includes(sound);
@@ -30,7 +30,7 @@ export interface AssetReference {
   path: string;
   /** JSON path of the field that references it. */
   at: string;
-  kind: "image" | "audio" | "script" | "font" | "shader";
+  kind: "image" | "audio" | "script" | "font" | "shader" | "scene";
 }
 
 /** Every file a scene points at, so tools can check that they exist. */
@@ -39,6 +39,8 @@ export function collectAssetPaths(scene: SceneDef): AssetReference[] {
   scene.entities.forEach((entity, i) => {
     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).

package/src/script.ts

@@ -30,7 +30,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 {
@@ -43,6 +45,12 @@ export interface ScriptWorld {
   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[];
@@ -54,6 +62,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. */
@@ -86,6 +102,7 @@ export interface DrawEvent {
   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;
 }
 
@@ -167,11 +184,12 @@ export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "
 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, deaths, won (read); 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

package/src/types.ts

@@ -2,7 +2,7 @@ export type Action = "left" | "right" | "up" | "down" | "jump" | "action";
 
 export const ACTIONS: readonly Action[] = ["left", "right", "up", "down", "jump", "action"];
 
-export const EVENT_TYPES = ["jump", "land", "collect", "die", "stomp", "win", "bounce"] as const;
+export const EVENT_TYPES = ["jump", "land", "collect", "die", "stomp", "win", "bounce", "checkpoint", "gameover", "goto"] as const;
 export type GameEventType = (typeof EVENT_TYPES)[number];
 
 /** What happens visually and audibly when a game event fires. See `EFFECT_FIELDS`. */
@@ -22,6 +22,8 @@ export interface PostFxDef {
 /** 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>>;
 }
 
@@ -34,6 +36,14 @@ 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`). */
@@ -52,6 +62,12 @@ export interface SceneDef {
   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[];
 }
 

package/src/validate.ts

@@ -18,7 +18,7 @@ const REQUIRED_EXAMPLES: Partial<Record<ComponentName, string>> = {
  * 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: unknown): ValidationResult {
+export function validateScene(input: unknown): ValidationResult {
   const diagnostics: Diagnostic[] = [];
   const error = (code: string, path: string, message: string, fix?: string) =>
     diagnostics.push({ severity: "error", code, path, message, fix });
@@ -26,13 +26,17 @@ export function validateScene(raw: unknown): ValidationResult {
     diagnostics.push({ severity: "warning", code, path, message, fix });
   const result = (): ValidationResult => {
     const ok = !diagnostics.some((d) => d.severity === "error");
-    return { ok, diagnostics, scene: ok ? (raw as SceneDef) : undefined };
+    return { ok, diagnostics, scene: ok ? (scene as SceneDef) : undefined };
   };
 
-  if (!isObject(raw)) {
+  let scene: unknown = 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)) {
@@ -50,6 +54,10 @@ export function validateScene(raw: unknown): ValidationResult {
       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.");
+      }
     }
   }
 
@@ -237,8 +245,69 @@ const SENSOR_COMPONENTS: [ComponentName, string][] = [
   ["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: Record<string, unknown>, error: Report): Record<string, unknown> {
+  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: unknown, i: number) => {
+    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: Record<string, unknown>, overrides: Record<string, unknown>): Record<string, Record<string, unknown>> {
+  const merged: Record<string, Record<string, unknown>> = {};
+  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) as Record<string, unknown>;
+  }
+  return merged;
+}
+
 function numberOr(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }