@ludra/core 0.5.0 → 0.8.0

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./world.ts";
 export * from "./simulate.ts";
 export * from "./assertions.ts";
 export * from "./ascii.ts";
+export * from "./drawcheck.ts";

package/src/postfx.ts

@@ -0,0 +1,110 @@
+import type { PostFxDef } from "./types.ts";
+
+/** Declared by the engine for every postfx shader, so shaders only write `main`. */
+const ENGINE_HEADER = `precision mediump float;
+uniform sampler2D u_image;
+uniform vec2 u_resolution;
+uniform float u_time;
+varying vec2 v_uv;
+`;
+
+const VERTEX_SHADER = `attribute vec2 a_position;
+varying vec2 v_uv;
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}`;
+
+/**
+ * Runs a scene's GLSL fragment shader over each rendered frame. The game draws
+ * into an offscreen 2D canvas; this uploads it as a texture and draws it
+ * through the shader onto a WebGL canvas.
+ */
+export class PostFx {
+  readonly canvas: HTMLCanvasElement;
+  private readonly gl: WebGLRenderingContext;
+  private readonly program: WebGLProgram;
+  private readonly texture: WebGLTexture;
+  private readonly uniforms: Array<{ location: WebGLUniformLocation | null; value: number }>;
+  private readonly time: WebGLUniformLocation | null;
+
+  /** Throws with the GLSL compiler's message if the shader doesn't compile. */
+  constructor(width: number, height: number, source: string, def: PostFxDef) {
+    this.canvas = document.createElement("canvas");
+    this.canvas.width = width;
+    this.canvas.height = height;
+    // preserveDrawingBuffer keeps the frame readable for screenshots.
+    const gl = this.canvas.getContext("webgl", { preserveDrawingBuffer: true, premultipliedAlpha: false });
+    if (!gl) throw new Error("postfx needs WebGL, which this browser doesn't provide.");
+    this.gl = gl;
+
+    const custom = Object.keys(def.uniforms ?? {});
+    // #line 1 makes compiler errors point at lines of the shader file itself.
+    const header = ENGINE_HEADER + custom.map((name) => `uniform float ${name};\n`).join("") + "#line 1\n";
+    this.program = link(gl, VERTEX_SHADER, header + stripDeclarations(source, ["u_image", "u_resolution", "u_time", "v_uv", ...custom]), def.shader);
+    gl.useProgram(this.program);
+
+    const buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+    const position = gl.getAttribLocation(this.program, "a_position");
+    gl.enableVertexAttribArray(position);
+    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+
+    this.texture = gl.createTexture()!;
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    for (const [key, value] of [
+      [gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE],
+      [gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE],
+      [gl.TEXTURE_MIN_FILTER, gl.LINEAR],
+      [gl.TEXTURE_MAG_FILTER, gl.LINEAR],
+    ] as const) {
+      gl.texParameteri(gl.TEXTURE_2D, key, value);
+    }
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+
+    gl.uniform1i(gl.getUniformLocation(this.program, "u_image"), 0);
+    gl.uniform2f(gl.getUniformLocation(this.program, "u_resolution"), width, height);
+    this.time = gl.getUniformLocation(this.program, "u_time");
+    this.uniforms = custom.map((name) => ({ location: gl.getUniformLocation(this.program, name), value: def.uniforms![name]! }));
+  }
+
+  /** Draws `source` (the frame the game just rendered) through the shader. */
+  render(source: HTMLCanvasElement, time: number): void {
+    const gl = this.gl;
+    gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    gl.uniform1f(this.time, time);
+    for (const u of this.uniforms) gl.uniform1f(u.location, u.value);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+  }
+}
+
+/** Drops the shader's own declarations of names the engine already declares, so either style compiles. */
+function stripDeclarations(source: string, names: string[]): string {
+  return source
+    .split("\n")
+    .map((line) => (/^\s*(uniform|varying)\b/.test(line) && names.some((name) => new RegExp(`\\b${name}\\b`).test(line)) ? "" : line))
+    .join("\n");
+}
+
+function link(gl: WebGLRenderingContext, vertex: string, fragment: string, path: string): WebGLProgram {
+  const program = gl.createProgram()!;
+  gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, vertex, "the engine's vertex shader"));
+  gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, fragment, path));
+  gl.linkProgram(program);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(`${path} failed to link: ${gl.getProgramInfoLog(program)}`);
+  return program;
+}
+
+function compile(gl: WebGLRenderingContext, type: number, source: string, path: string): WebGLShader {
+  const shader = gl.createShader(type)!;
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = String(gl.getShaderInfoLog(shader)).trim();
+    throw new Error(`${path} failed to compile: ${log}`);
+  }
+  return shader;
+}

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 {
@@ -39,6 +41,16 @@ export interface ScriptWorld {
   readonly width: number;
   readonly height: number;
   score: number;
+  /** Times a player has died so far. */
+  readonly deaths: number;
+  /** True once the level is complete. */
+  readonly won: boolean;
+  /** 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[];
@@ -50,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. */
@@ -73,6 +93,50 @@ export interface ScriptContext {
   dt: number;
 }
 
+/** A game event as draw hooks see it. Custom events carry the name passed to world.emit. */
+export interface DrawEvent {
+  /** Built-in type ("collect", "die", "bounce"...) or the custom event's name. */
+  name: string;
+  time: number;
+  x: number;
+  y: number;
+  /** The entity that caused it. */
+  entity: string;
+  /** 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;
+}
+
+/**
+ * What `draw` and `drawUI` receive. `g` is the real Canvas 2D context, so
+ * anything the canvas can do is allowed: gradients, glow (shadowBlur), blend
+ * modes (globalCompositeOperation), paths, text, filters, images.
+ *
+ * Draw hooks only paint. `self` and `world` are read-only here (changing the
+ * game must happen in `update` so tests see it); keep animation memory in `local`.
+ */
+export interface DrawContext {
+  g: CanvasRenderingContext2D;
+  self: ScriptEntity;
+  world: ScriptWorld;
+  params: Record<string, unknown>;
+  /** Simulation time in seconds. Animate with it so screenshots stay reproducible. */
+  time: number;
+  /** Per-entity memory for presentation (trails, tweens). Not part of the game state and not testable. */
+  local: Record<string, unknown>;
+  /** Visible area: canvas size, camera position (world px at the top-left) and zoom. */
+  view: { width: number; height: number; cameraX: number; cameraY: number; zoom: number };
+  /** Events that happened in the last `seconds` (default 0.5), optionally only those named `name`. Newest last. */
+  recent(name?: string, seconds?: number): DrawEvent[];
+  /** An image from the project, e.g. "assets/glow.png". Images in sprites or in string script params are preloaded. */
+  image(path: string): HTMLImageElement | undefined;
+  /** A particle burst through the engine's particle system (same fields as effects particles). */
+  burst(x: number, y: number, particles?: Record<string, unknown>): void;
+  /** Shakes the screen by `amount` px (decays on its own). */
+  shake(amount: number): void;
+  /** A number in [0, 1) for visual variety. Seeded, independent of world.random, so it never affects the game. */
+  random(): number;
+}
+
 /**
  * The default export of a script file. All hooks are optional.
  *
@@ -90,9 +154,20 @@ export interface Script {
   update?(ctx: ScriptContext): void;
   /** Runs when this entity starts touching another one (after physics). */
   touch?(ctx: ScriptContext, other: ScriptEntity): void;
+  /**
+   * Paints this entity in world space, every rendered frame, right after its sprite
+   * (or instead of one: an entity without a sprite is drawn only by this hook).
+   * Order follows `sprite.layer` (0 without a sprite). Browser only; tests never call it.
+   */
+  draw?(ctx: DrawContext): void;
+  /**
+   * Paints in screen space, above the world. If any script has `drawUI`, the engine's
+   * default HUD and "Level complete" screen are turned off: the game draws its own.
+   */
+  drawUI?(ctx: DrawContext): void;
 }
 
-export const SCRIPT_HOOKS = ["start", "update", "touch"] as const;
+export const SCRIPT_HOOKS = ["start", "update", "touch", "draw", "drawUI"] as const;
 
 /** Printed by `ludra components script`. Keep in sync with the interfaces above. */
 export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "import type" is allowed: scripts run without a bundler.
@@ -102,22 +177,43 @@ export const SCRIPT_API_REFERENCE = `A script file default-exports hooks. Only "
     start(ctx) {},           // once, on the entity's first frame
     update(ctx) {},          // every frame, after player input, before physics
     touch(ctx, other) {},    // when this entity starts touching another body (after physics)
+    draw(ctx) {},            // paint this entity in world space (browser only, every rendered frame)
+    drawUI(ctx) {},          // paint screen-space UI; replaces the default HUD and win screen
   } satisfies Script;
 
 ctx.self      the entity: id, x, y, vx, vy (read/write); grounded, width, height, exists (read);
               state (object kept between frames, testable as "<id>.state.<key>");
               has("component"), touches(otherOrId)
-ctx.world     time, frame, width, height, score (read/write)
+ctx.world     time, frame, width, height, deaths, won, 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
 ctx.params    the "params" object from the script component
 ctx.dt        seconds per frame (1/60)
 
+Drawing: draw and drawUI get the real Canvas 2D context, so there are no limits on looks.
+ctx.g         CanvasRenderingContext2D: gradients, shadowBlur glow, globalCompositeOperation ("lighter" for
+              additive light), paths, text with any loaded font, ctx.g.filter, drawImage...
+              draw: origin is the world (use self.x/self.y); drawUI: origin is the screen top-left
+ctx.time      simulation seconds; animate with it so screenshots are reproducible
+ctx.local     per-entity presentation memory (trails, tweens); not game state
+ctx.view      width, height, cameraX, cameraY, zoom
+ctx.recent(name?, seconds = 0.5)   recent events [{ name, time, x, y, entity, data }]: flash on hit, pop scores
+ctx.image(path)   a loaded image (sprite images and string params ending in .svg/.png/... are preloaded)
+ctx.burst(x, y, particles?)  ctx.shake(px)  ctx.random()   presentation-only helpers
+self/world/params as in update, but read-only: changing the game in a draw hook is an error.
+
+Scene-level presentation (all optional):
+  "fonts": { "Orbitron": "google", "Pixel": "assets/pixel.woff2" }   load fonts for ctx.g.font
+  "postfx": { "shader": "shaders/crt.frag", "uniforms": { "strength": 0.6 } }
+     a GLSL ES 1.0 fragment shader over the whole frame. It gets: uniform sampler2D u_image;
+     uniform vec2 u_resolution; uniform float u_time; varying vec2 v_uv; plus each uniform as a float.
+
 Scripts in scripts/ are loaded even if no entity uses them, so world.spawn can attach them.
 Errors name the file, entity, hook and frame.`;
 

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"] 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`. */
@@ -12,9 +12,18 @@ export interface EffectDef {
   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;
+  /** Name of a prefab to start from. Gone after validation: its components are merged in. */
+  prefab?: string;
   components: Record<string, Record<string, unknown>>;
 }
 
@@ -27,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`). */
@@ -38,6 +55,19 @@ export interface SceneDef {
    * Keys are built-in event types or names scripts pass to `world.emit`.
    */
   effects?: Partial<Record<GameEventType, EffectDef>> & Record<string, EffectDef | undefined>;
+  /**
+   * Fonts that draw hooks can use in `ctx.g.font`: family name → "google" (loaded from
+   * Google Fonts) or a font file in the project (.woff2, .woff, .ttf, .otf).
+   */
+  fonts?: Record<string, string>;
+  /** A GLSL fragment shader applied to every rendered frame. Presentation only. */
+  postfx?: PostFxDef;
+  /**
+   * 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

@@ -1,5 +1,5 @@
 import { COMPONENT_NAMES, COMPONENTS, isComponentName, isFrameList, PARTICLE_FIELDS, type ComponentName, type FieldSpec } from "./components.ts";
-import { AUDIO_EXTENSIONS, EFFECT_FIELDS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.ts";
+import { AUDIO_EXTENSIONS, EFFECT_FIELDS, FONT_EXTENSIONS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.ts";
 import { EVENT_TYPES, type Diagnostic, type SceneDef } from "./types.ts";
 
 export interface ValidationResult {
@@ -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,10 +54,16 @@ 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.");
+      }
     }
   }
 
   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": [].');
@@ -63,6 +73,7 @@ export function validateScene(raw: unknown): ValidationResult {
   const ids = new Map<string, number>();
   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: { path: string; label: string; requireScore: number }[] = [];
@@ -150,6 +161,22 @@ export function validateScene(raw: unknown): ValidationResult {
 
     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",
@@ -181,8 +208,10 @@ export function validateScene(raw: unknown): ValidationResult {
     if (isObject(components.hazard) && components.hazard.stompable === true) 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) hasPlayer = true;
-    if (body && bodyType === "dynamic") hasDynamic = true;
+    if ("platformer" in components || "topdown" in components) hasPlayer = true;
+    // 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;
   });
 
@@ -205,7 +234,7 @@ export function validateScene(raw: unknown): ValidationResult {
     }
   }
   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();
@@ -216,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;
 }
@@ -263,6 +353,35 @@ function validateFields(
   }
 }
 
+function validateFonts(fonts: unknown, error: Report): void {
+  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: unknown, error: Report): void {
+  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: unknown, error: Report, warn: Report): void {
   if (!isObject(effects)) {
     error("E_EFFECTS_NOT_OBJECT", "effects", '"effects" must map event names to effects.', 'Use "effects": { "collect": { "sound": "coin" } }.');