@ludra/core 0.5.0 → 0.7.0

package/src/components.ts

@@ -20,6 +20,7 @@ export const COMPONENT_NAMES = [
   "body",
   "sprite",
   "platformer",
+  "topdown",
   "collectible",
   "patrol",
   "hazard",
@@ -65,6 +66,12 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       height: { type: "number", min: 1, description: "Collider height in pixels." },
       sensor: { type: "boolean", default: false, description: "Sensors detect overlaps but never block movement (coins, triggers)." },
       gravityScale: { type: "number", default: 1, description: "Multiplier on world gravity for dynamic bodies." },
+      bounce: {
+        type: "number",
+        min: 0,
+        default: 0,
+        description: "How much speed a dynamic body keeps when it hits a solid: 0 stops it, 1 bounces it back at full speed (balls, pinballs).",
+      },
       vx: { type: "number", default: 0, description: "Initial horizontal velocity in px/s." },
       vy: { type: "number", default: 0, description: "Initial vertical velocity in px/s." },
     },
@@ -102,8 +109,23 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       variableJump: { type: "boolean", default: true, description: "Releasing jump early cuts the jump short." },
     },
   },
+  topdown: {
+    description:
+      "Player control seen from above or for vehicles: moves with the arrow keys, no gravity. directions picks 8-way, 4-way, or one axis (\"x\" for a breakout paddle or a shooter ship). Needs a dynamic body (collides with walls) or a kinematic one (passes through, use clampToWorld).",
+    requires: ["transform", "body"],
+    fields: {
+      speed: { type: "number", min: 0, default: 200, description: "Move speed in px/s." },
+      directions: {
+        type: "enum",
+        values: ["8", "4", "x", "y"],
+        default: "8",
+        description: '"8": any direction (diagonals keep the same speed). "4": up/down/left/right only. "x" or "y": one axis.',
+      },
+      clampToWorld: { type: "boolean", default: true, description: "Keep the entity inside the world bounds." },
+    },
+  },
   collectible: {
-    description: "Removed when a platformer entity touches it and adds to the score. Its body must be a sensor.",
+    description: "Removed when a player (platformer or topdown) touches it and adds to the score. Its body must be a sensor.",
     requires: ["transform", "body"],
     fields: {
       score: { type: "number", default: 1, description: "Points added when collected." },
@@ -172,6 +194,7 @@ export interface Body {
   height: number;
   sensor: boolean;
   gravityScale: number;
+  bounce: number;
   vx: number;
   vy: number;
 }
@@ -222,6 +245,12 @@ export interface Platformer {
   variableJump: boolean;
 }
 
+export interface Topdown {
+  speed: number;
+  directions: "8" | "4" | "x" | "y";
+  clampToWorld: boolean;
+}
+
 export interface Collectible {
   score: number;
 }

package/src/drawcheck.ts

@@ -0,0 +1,80 @@
+import { ScriptError, type ScriptModules } from "./script.ts";
+import type { Diagnostic, SceneDef } from "./types.ts";
+import { World } from "./world.ts";
+
+/** Simulation frames at which `checkDrawHooks` paints: the start, and after things have moved. */
+const CHECK_FRAMES = [0, 30, 120];
+
+/**
+ * A stand-in for CanvasRenderingContext2D that accepts every call and property,
+ * so draw hooks can run outside a browser. It catches the hook's own mistakes
+ * (typos, undefined values, changing the game while drawing), not what it looks like.
+ */
+function mockCanvas(): CanvasRenderingContext2D {
+  const handler: ProxyHandler<() => unknown> = {
+    get: (_target, key) => (key === Symbol.toPrimitive ? () => 0 : key === "then" ? undefined : any),
+    set: () => true,
+    apply: () => any,
+  };
+  const any: unknown = new Proxy(() => undefined, handler);
+  return any as CanvasRenderingContext2D;
+}
+
+/**
+ * Runs every `draw` and `drawUI` hook against a mock canvas at a few points of
+ * an idle run, and reports hooks that throw. Used by `ludra check`.
+ */
+export function checkDrawHooks(scene: SceneDef, scripts: ScriptModules): Diagnostic[] {
+  let world: World;
+  try {
+    world = new World(scene, { scripts });
+  } catch {
+    return []; // Load problems are reported elsewhere.
+  }
+  const reported = new Set<string>();
+  const diagnostics: Diagnostic[] = [];
+  const g = mockCanvas();
+  const view = { width: world.width, height: world.height, cameraX: 0, cameraY: 0, zoom: 1 };
+  const locals = new Map<string, Record<string, unknown>>();
+
+  for (let frame = 0; frame <= CHECK_FRAMES.at(-1)!; frame++) {
+    if (CHECK_FRAMES.includes(frame)) {
+      for (const e of [...world.entities]) {
+        for (const hook of ["draw", "drawUI"] as const) {
+          if (!e.script?.module[hook]) continue;
+          if (!locals.has(e.id)) locals.set(e.id, {});
+          try {
+            world.callDrawHook(e, hook, {
+              g,
+              time: world.time,
+              local: locals.get(e.id)!,
+              view,
+              recent: () => [],
+              image: () => undefined,
+              burst: () => {},
+              shake: () => {},
+              random: () => 0.5,
+            });
+          } catch (err) {
+            const key = `${e.script.src}:${hook}`;
+            if (reported.has(key)) continue;
+            reported.add(key);
+            diagnostics.push({
+              severity: "error",
+              code: "E_DRAW_HOOK",
+              path: `${e.script.src} → ${hook}`,
+              message: err instanceof ScriptError ? err.message : String(err),
+              fix: "Draw hooks run every rendered frame in the browser. Fix the error; ctx.image() can return undefined, so check it before drawing.",
+            });
+          }
+        }
+      }
+    }
+    try {
+      world.step(new Set());
+    } catch {
+      break; // Simulation errors surface in play and test.
+    }
+  }
+  return diagnostics;
+}

package/src/effects.ts

@@ -7,6 +7,7 @@ export type SoundPreset = (typeof SOUND_PRESETS)[number];
 
 export const AUDIO_EXTENSIONS = [".wav", ".mp3", ".ogg"] as const;
 export const IMAGE_EXTENSIONS = [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"] as const;
+export const FONT_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf"] as const;
 
 export const EFFECT_FIELDS: Record<string, FieldSpec> = {
   sound: {
@@ -29,7 +30,7 @@ export interface AssetReference {
   path: string;
   /** JSON path of the field that references it. */
   at: string;
-  kind: "image" | "audio" | "script";
+  kind: "image" | "audio" | "script" | "font" | "shader";
 }
 
 /** Every file a scene points at, so tools can check that they exist. */
@@ -40,10 +41,23 @@ export function collectAssetPaths(scene: SceneDef): AssetReference[] {
     if (typeof image === "string" && image !== "") refs.push({ path: image, at: `entities[${i}].components.sprite.image`, kind: "image" });
     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).
+    const params = entity.components.script?.params;
+    if (params && typeof params === "object") {
+      for (const [key, value] of Object.entries(params)) {
+        if (typeof value === "string" && IMAGE_EXTENSIONS.some((ext) => value.toLowerCase().endsWith(ext))) {
+          refs.push({ path: value, at: `entities[${i}].components.script.params.${key}`, kind: "image" });
+        }
+      }
+    }
   });
   for (const [event, effect] of Object.entries(scene.effects ?? {})) {
     const sound = effect?.sound;
     if (typeof sound === "string" && sound !== "" && !isSoundPreset(sound)) refs.push({ path: sound, at: `effects.${event}.sound`, kind: "audio" });
   }
+  for (const [family, src] of Object.entries(scene.fonts ?? {})) {
+    if (typeof src === "string" && src !== "google") refs.push({ path: src, at: `fonts.${family}`, kind: "font" });
+  }
+  if (typeof scene.postfx?.shader === "string" && scene.postfx.shader !== "") refs.push({ path: scene.postfx.shader, at: "postfx.shader", kind: "shader" });
   return refs;
 }

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

@@ -39,6 +39,10 @@ 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;
   get(id: string): ScriptEntity | undefined;
   /** Every entity, or only those with the given component. */
   all(component?: string): ScriptEntity[];
@@ -73,6 +77,49 @@ 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;
+  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 +137,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,12 +160,14 @@ 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 (read); score (read/write)
               get(id), all(component?), player()
               spawn({ id?, components }) -> entity    destroy(entityOrId)
               kill(entityOrId)  players respawn, others are destroyed
@@ -118,6 +178,24 @@ ctx.input     held(action), pressed(action)   actions: left right up down jump a
 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"] as const;
 export type GameEventType = (typeof EVENT_TYPES)[number];
 
 /** What happens visually and audibly when a game event fires. See `EFFECT_FIELDS`. */
@@ -12,6 +12,13 @@ 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;
@@ -38,6 +45,13 @@ 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;
   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 {
@@ -54,6 +54,8 @@ export function validateScene(raw: unknown): ValidationResult {
   }
 
   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 +65,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 +153,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 +200,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 +226,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();
@@ -263,6 +284,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" } }.');