@ludra/core 0.3.1 → 0.5.0

package/src/browser.ts

@@ -1,7 +1,9 @@
 import { SoundPlayer } from "./audio.ts";
 import { parseFrames, type Sprite } from "./components.ts";
 import { collectAssetPaths } from "./effects.ts";
+import { InputScript } from "./input.ts";
 import { ParticleSystem } from "./particles.ts";
+import type { Script } from "./script.ts";
 import { FIXED_DT } from "./time.ts";
 import type { Action, SceneDef } from "./types.ts";
 import { World, type Entity } from "./world.ts";
@@ -29,6 +31,25 @@ const SHAKE_DECAY = 0.88;
 export interface GameOptions {
   /** URL prefix for image and audio paths in the scene. Defaults to "". */
   assetBase?: string;
+  /** URL prefix the scene's script paths are imported from. Defaults to `assetBase`. */
+  scriptBase?: string;
+  /** Scripts to load. Defaults to those the scene references; include any that `world.spawn` uses. */
+  scriptPaths?: readonly string[];
+}
+
+/** Imports the game's script modules, keyed by their path in the scene. */
+async function loadScripts(scene: SceneDef, options: GameOptions): Promise<Map<string, Script>> {
+  const base = options.scriptBase ?? options.assetBase ?? "";
+  const paths = options.scriptPaths ?? collectAssetPaths(scene).filter((ref) => ref.kind === "script").map((ref) => ref.path);
+  const scripts = new Map<string, Script>();
+  await Promise.all(
+    [...new Set(paths)].map(async (path) => {
+      const module = (await import(base + path)) as { default?: Script };
+      if (!module.default) throw new Error(`Script ${path} has no default export.`);
+      scripts.set(path, module.default);
+    }),
+  );
+  return scripts;
 }
 
 /**
@@ -41,14 +62,16 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Canvas 2D context is not available.");
   const assetBase = options.assetBase ?? "";
-  const images = await loadImages(scene, assetBase);
+  const [images, scripts] = await Promise.all([loadImages(scene, assetBase), loadScripts(scene, options)]);
   const sounds = new SoundPlayer(assetBase);
   const view = new View(scene, images);
 
-  let world = new World(scene);
+  let world = new World(scene, { scripts });
+  let crash: string | undefined;
   const restart = () => {
-    world = new World(scene);
+    world = new World(scene, { scripts });
     view.reset();
+    crash = undefined;
   };
 
   const held = new Set<Action>();
@@ -82,13 +105,20 @@ 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) {
-      world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
+    while (accumulator >= FIXED_DT && !crash) {
+      try {
+        world.step(tapped.size > 0 ? new Set([...held, ...tapped]) : held);
+      } catch (err) {
+        // A script threw: freeze the game and show why, instead of failing silently.
+        crash = err instanceof Error ? err.message : String(err);
+        console.error("[ludra]", err);
+      }
       tapped.clear();
       view.step(world, (sound) => sounds.play(sound));
       accumulator -= FIXED_DT;
     }
     view.draw(ctx, world, sounds.muted);
+    if (crash) drawCrash(ctx, crash);
     raf = requestAnimationFrame(frame);
   };
   raf = requestAnimationFrame(frame);
@@ -101,6 +131,74 @@ export async function startGame(canvas: HTMLCanvasElement, scene: SceneDef, opti
   };
 }
 
+export interface CaptureOptions extends GameOptions {
+  /** Input script, e.g. `"right:1s, jump:0.4s"`. See `InputScript`. */
+  inputs?: string;
+  /** Simulation frames to capture (60 per second). Frame 0 is the starting state. */
+  frames: readonly number[];
+}
+
+export interface CapturedFrame {
+  frame: number;
+  time: number;
+  /** PNG as a data URL. */
+  png: string;
+}
+
+/**
+ * Plays a scene without a clock or keyboard and returns the requested frames
+ * as PNGs. Same renderer, effects and particles as `startGame`, stepped
+ * deterministically, so a frame always looks the same. Used by
+ * `ludra play --screenshot`.
+ */
+export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef, options: CaptureOptions): Promise<CapturedFrame[]> {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Canvas 2D context is not available.");
+  const [images, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
+  const view = new View(scene, images);
+  const world = new World(scene, { scripts });
+  const script = InputScript.parse(options.inputs ?? "");
+  const wanted = new Set(options.frames);
+  const last = Math.max(0, ...options.frames);
+  const captured: CapturedFrame[] = [];
+
+  for (let frame = 0; ; frame++) {
+    if (wanted.has(frame)) {
+      view.draw(ctx, world, false);
+      captured.push({ frame, time: frame * FIXED_DT, png: canvas.toDataURL("image/png") });
+    }
+    if (frame >= last) break;
+    world.step(script.at(frame));
+    view.step(world, () => {});
+  }
+  return captured;
+}
+
+function drawCrash(ctx: CanvasRenderingContext2D, message: string): void {
+  const { width, height } = ctx.canvas;
+  ctx.fillStyle = "rgba(20, 0, 8, 0.85)";
+  ctx.fillRect(0, 0, width, height);
+  ctx.fillStyle = "#ff9b9b";
+  ctx.textAlign = "left";
+  ctx.font = "700 22px system-ui, sans-serif";
+  ctx.fillText("Script error", 32, 56);
+  ctx.font = "15px ui-monospace, monospace";
+  // Wrap the message to the canvas width.
+  let line = "";
+  let y = 92;
+  for (const word of message.split(" ")) {
+    if (ctx.measureText(line + word).width > width - 64) {
+      ctx.fillText(line, 32, y);
+      line = "";
+      y += 22;
+    }
+    line += `${word} `;
+  }
+  ctx.fillText(line, 32, y);
+  ctx.fillStyle = "rgba(255, 255, 255, 0.6)";
+  ctx.fillText("Fix the script; the page reloads on save. R restarts.", 32, y + 40);
+}
+
 async function loadImages(scene: SceneDef, assetBase: string): Promise<Map<string, HTMLImageElement>> {
   const images = new Map<string, HTMLImageElement>();
   const paths = new Set(collectAssetPaths(scene).filter((ref) => ref.kind === "image").map((ref) => ref.path));
@@ -151,7 +249,7 @@ class View {
   /** Runs once per simulation step: turns new events into effects and advances particles. */
   step(world: World, playSound: (sound: string) => void): void {
     for (const event of world.events.slice(this.handledEvents)) {
-      const effect = this.scene.effects?.[event.type];
+      const effect = this.scene.effects?.[event.type === "custom" ? event.name : event.type];
       if (!effect) continue;
       if (effect.particles) this.particles.burst(event.x, event.y, effect.particles);
       if (effect.sound) playSound(effect.sound);

package/src/components.ts

@@ -4,7 +4,9 @@ export type FieldSpec =
   | { type: "boolean"; default?: boolean; description: string }
   | { type: "enum"; values: readonly string[]; default?: string; description: string }
   /** Spritesheet frame indices: "0", "1-4" or "0,2,4-6". Empty = not used. */
-  | { type: "frames"; default?: string; description: string };
+  | { type: "frames"; default?: string; description: string }
+  /** Any JSON object. */
+  | { type: "object"; default?: Record<string, unknown>; description: string };
 
 export interface ComponentSpec {
   description: string;
@@ -23,6 +25,7 @@ export const COMPONENT_NAMES = [
   "hazard",
   "goal",
   "emitter",
+  "script",
   "camera",
 ] as const;
 export type ComponentName = (typeof COMPONENT_NAMES)[number];
@@ -140,6 +143,15 @@ export const COMPONENTS: Record<ComponentName, ComponentSpec> = {
       ...Object.fromEntries(Object.entries(PARTICLE_FIELDS).filter(([field]) => field !== "count")),
     },
   },
+  script: {
+    description:
+      "Custom behavior written in TypeScript or JavaScript: a file that default-exports hooks (start, update, touch). Use it for anything the built-in components don't do: chasing, doors and keys, timers, shooting, boss phases. Run `ludra components script` for the API.",
+    requires: ["transform"],
+    fields: {
+      src: { type: "string", description: 'Script path relative to the project, e.g. "scripts/chase.ts".' },
+      params: { type: "object", default: {}, description: "Values passed to the script as ctx.params, so one script can serve many entities." },
+    },
+  },
   camera: {
     description: "The browser camera follows this entity. Without it, the camera follows the first platformer.",
     requires: ["transform"],
@@ -197,6 +209,11 @@ export interface Emitter extends Omit<ParticleSpec, "count"> {
   rate: number;
 }
 
+export interface ScriptComponent {
+  src: string;
+  params: Record<string, unknown>;
+}
+
 export interface Platformer {
   speed: number;
   jumpSpeed: number;

package/src/effects.ts

@@ -29,7 +29,7 @@ export interface AssetReference {
   path: string;
   /** JSON path of the field that references it. */
   at: string;
-  kind: "image" | "audio";
+  kind: "image" | "audio" | "script";
 }
 
 /** Every file a scene points at, so tools can check that they exist. */
@@ -38,6 +38,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 src = entity.components.script?.src;
+    if (typeof src === "string" && src !== "") refs.push({ path: src, at: `entities[${i}].components.script.src`, kind: "script" });
   });
   for (const [event, effect] of Object.entries(scene.effects ?? {})) {
     const sound = effect?.sound;

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./components.ts";
 export * from "./effects.ts";
 export * from "./validate.ts";
 export * from "./input.ts";
+export * from "./script.ts";
 export * from "./world.ts";
 export * from "./simulate.ts";
 export * from "./assertions.ts";

package/src/script.ts

@@ -0,0 +1,184 @@
+import type { Action, Diagnostic } from "./types.ts";
+import { closestName } from "./validate.ts";
+
+/**
+ * A game object as scripts see it. Reading and writing `x`, `y`, `vx` and
+ * `vy` changes the entity directly.
+ */
+export interface ScriptEntity {
+  readonly id: string;
+  x: number;
+  y: number;
+  /** Velocity in px/s. Always 0 for entities without a body. */
+  vx: number;
+  vy: number;
+  readonly grounded: boolean;
+  readonly width: number;
+  readonly height: number;
+  /** False once the entity has been destroyed or collected. */
+  readonly exists: boolean;
+  /**
+   * Data kept between frames. Use JSON values only. Tests can read it as
+   * `<id>.state.<key>`, for example `"door.state.open == true"`.
+   */
+  readonly state: Record<string, unknown>;
+  has(component: string): boolean;
+  /** True when this entity overlaps or touches the other one. */
+  touches(other: ScriptEntity | string): boolean;
+}
+
+export interface SpawnDef {
+  /** Generated when left out. */
+  id?: string;
+  components: Record<string, Record<string, unknown>>;
+}
+
+export interface ScriptWorld {
+  readonly time: number;
+  readonly frame: number;
+  readonly width: number;
+  readonly height: number;
+  score: number;
+  get(id: string): ScriptEntity | undefined;
+  /** Every entity, or only those with the given component. */
+  all(component?: string): ScriptEntity[];
+  /** The first entity with a `platformer` component. */
+  player(): ScriptEntity | undefined;
+  spawn(def: SpawnDef): ScriptEntity;
+  destroy(entity: ScriptEntity | string): void;
+  /** Players die and respawn; anything else is destroyed. */
+  kill(entity: ScriptEntity | string): void;
+  /** Completes the level, like reaching a goal. */
+  win(): 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. */
+  random(): number;
+}
+
+export interface ScriptInput {
+  /** True while the action is held. */
+  held(action: Action): boolean;
+  /** True only on the frame the action is pressed. */
+  pressed(action: Action): boolean;
+}
+
+export interface ScriptContext {
+  self: ScriptEntity;
+  world: ScriptWorld;
+  input: ScriptInput;
+  /** The `params` object from the entity's `script` component. */
+  params: Record<string, unknown>;
+  /** Seconds per frame (1/60). */
+  dt: number;
+}
+
+/**
+ * The default export of a script file. All hooks are optional.
+ *
+ * ```ts
+ * import type { Script } from "@ludra/core";
+ * export default {
+ *   update({ self, world, params }) { ... },
+ * } satisfies Script;
+ * ```
+ */
+export interface Script {
+  /** Runs once, on the entity's first frame. */
+  start?(ctx: ScriptContext): void;
+  /** Runs every frame, after player input and before physics. */
+  update?(ctx: ScriptContext): void;
+  /** Runs when this entity starts touching another one (after physics). */
+  touch?(ctx: ScriptContext, other: ScriptEntity): void;
+}
+
+export const SCRIPT_HOOKS = ["start", "update", "touch"] 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.
+
+  import type { Script } from "@ludra/core";
+  export default {
+    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)
+  } 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)
+              get(id), all(component?), player()
+              spawn({ id?, components }) -> entity    destroy(entityOrId)
+              kill(entityOrId)  players respawn, others are destroyed
+              win()             completes the level
+              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)
+
+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.`;
+
+export type ScriptModules = ReadonlyMap<string, Script> | Readonly<Record<string, Script>>;
+
+export function getScript(modules: ScriptModules | undefined, src: string): Script | undefined {
+  if (!modules) return undefined;
+  return modules instanceof Map ? modules.get(src) : (modules as Record<string, Script>)[src];
+}
+
+/** A script threw, or was used wrongly. Names the file, entity, hook and frame. */
+export class ScriptError extends Error {
+  readonly src: string;
+  readonly entity: string;
+  readonly hook: string;
+  readonly frame: number;
+
+  constructor(details: { src: string; entity: string; hook: string; frame: number }, message: string, options?: ErrorOptions) {
+    super(`${details.src} (${details.hook} on entity "${details.entity}", frame ${details.frame}): ${message}`, options);
+    this.src = details.src;
+    this.entity = details.entity;
+    this.hook = details.hook;
+    this.frame = details.frame;
+  }
+}
+
+/** Checks that a loaded module looks like a script. */
+export function validateScriptModule(module: unknown, src: string): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const script = (module as { default?: unknown } | null)?.default;
+  if (typeof script !== "object" || script === null) {
+    diagnostics.push({
+      severity: "error",
+      code: "E_SCRIPT_NO_DEFAULT_EXPORT",
+      path: src,
+      message: `${src} must default-export an object with script hooks.`,
+      fix: "Use: export default { update({ self, world }) { ... } } satisfies Script;",
+    });
+    return diagnostics;
+  }
+  for (const [key, value] of Object.entries(script)) {
+    if (!(SCRIPT_HOOKS as readonly string[]).includes(key)) {
+      const suggestion = closestName(key, SCRIPT_HOOKS);
+      diagnostics.push({
+        severity: "warning",
+        code: "W_SCRIPT_UNKNOWN_HOOK",
+        path: `${src} → ${key}`,
+        message: `"${key}" is not a script hook, so it is never called.`,
+        fix: `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Hooks are ${SCRIPT_HOOKS.join(", ")}. Put helpers outside the exported object.`,
+      });
+    } else if (typeof value !== "function") {
+      diagnostics.push({ severity: "error", code: "E_SCRIPT_HOOK_NOT_FUNCTION", path: `${src} → ${key}`, message: `"${key}" must be a function.` });
+    }
+  }
+  return diagnostics;
+}
+
+/** Scripts run in the engine without a bundler, so they cannot import runtime code. */
+export function findRuntimeImports(source: string): string[] {
+  const imports: string[] = [];
+  for (const match of source.matchAll(/^\s*import\s+(?!type\b)([^;\n]*?)\s+from\s+["']([^"']+)["']/gm)) imports.push(match[2]!);
+  for (const match of source.matchAll(/^\s*import\s+["']([^"']+)["']/gm)) imports.push(match[1]!);
+  return imports;
+}

package/src/types.ts

@@ -25,14 +25,19 @@ export interface WorldSettings {
   /** Downward acceleration in px/s². Defaults to 1800. */
   gravity?: number;
   background?: string;
+  /** Seed for `world.random()` in scripts. Defaults to 1. */
+  seed?: number;
 }
 
 /** A scene file (`*.scene.json`). */
 export interface SceneDef {
   name?: string;
   world?: WorldSettings;
-  /** Feedback for game events, e.g. `{ "collect": { "sound": "coin" } }`. Visual and audio only. */
-  effects?: Partial<Record<GameEventType, EffectDef>>;
+  /**
+   * Feedback for game events, e.g. `{ "collect": { "sound": "coin" } }`. Visual and audio only.
+   * Keys are built-in event types or names scripts pass to `world.emit`.
+   */
+  effects?: Partial<Record<GameEventType, EffectDef>> & Record<string, EffectDef | undefined>;
   entities: EntityDef[];
 }
 

package/src/validate.ts

@@ -44,6 +44,9 @@ export function validateScene(raw: unknown): ValidationResult {
           error("E_INVALID_WORLD", `world.${key}`, `world.${key} must be a non-negative number, got ${describe(value)}.`);
         }
       }
+      if (raw.world.seed !== undefined && (typeof raw.world.seed !== "number" || !Number.isFinite(raw.world.seed))) {
+        error("E_INVALID_WORLD", "world.seed", `world.seed must be a number, got ${describe(raw.world.seed)}.`);
+      }
       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)}.`);
       }
@@ -94,7 +97,7 @@ export function validateScene(raw: unknown): ValidationResult {
     for (const [name, value] of Object.entries(components)) {
       const componentPath = `${path}.components.${name}`;
       if (!isComponentName(name)) {
-        const suggestion = closest(name, COMPONENT_NAMES);
+        const suggestion = closestName(name, COMPONENT_NAMES);
         error(
           "E_UNKNOWN_COMPONENT",
           componentPath,
@@ -135,6 +138,16 @@ export function validateScene(raw: unknown): ValidationResult {
       );
     }
 
+    const script = isObject(components.script) ? components.script : undefined;
+    if (script && typeof script.src === "string" && !hasExtension(script.src, SCRIPT_EXTENSIONS)) {
+      error(
+        "E_INVALID_SCRIPT_PATH",
+        `${path}.components.script.src`,
+        `"${script.src}" on entity ${label} is not a script file.`,
+        'Use a path ending in .ts or .js, e.g. "scripts/chase.ts".',
+      );
+    }
+
     const body = isObject(components.body) ? components.body : undefined;
     const bodyType = body?.type ?? "static";
     if ("platformer" in components && body && bodyType !== "dynamic") {
@@ -229,7 +242,7 @@ function validateFields(
     if (ignore.includes(field)) continue;
     const spec = fields[field];
     if (!spec) {
-      const suggestion = closest(field, Object.keys(fields));
+      const suggestion = closestName(field, Object.keys(fields));
       warn(
         "W_UNKNOWN_FIELD",
         `${path}.${field}`,
@@ -258,9 +271,16 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
   for (const [event, effect] of Object.entries(effects)) {
     const path = `effects.${event}`;
     if (!(EVENT_TYPES as readonly string[]).includes(event)) {
-      const suggestion = closest(event, EVENT_TYPES);
-      error("E_UNKNOWN_EVENT", path, `There is no "${event}" event.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Events: ${EVENT_TYPES.join(", ")}.`);
-      continue;
+      // Any other name is a custom event that scripts fire with world.emit(). Flag likely typos of built-in ones.
+      const suggestion = closestName(event, EVENT_TYPES);
+      if (suggestion) {
+        warn(
+          "W_EVENT_LOOKS_LIKE_TYPO",
+          path,
+          `"${event}" is not a built-in event, so it only fires if a script calls world.emit("${event}").`,
+          `Did you mean "${suggestion}"? Built-in events: ${EVENT_TYPES.join(", ")}.`,
+        );
+      }
     }
     if (!isObject(effect)) {
       error("E_EFFECT_NOT_OBJECT", path, `effects.${event} must be an object.`, `Use { "sound": "blip", "particles": { "count": 8 } }.`);
@@ -268,7 +288,7 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
     }
     validateFields(EFFECT_FIELDS, effect, path, `effects.${event}`, "", error, warn, ["particles"]);
     if (typeof effect.sound === "string" && effect.sound !== "" && !isSoundPreset(effect.sound) && !hasExtension(effect.sound, AUDIO_EXTENSIONS)) {
-      const suggestion = closest(effect.sound, SOUND_PRESETS);
+      const suggestion = closestName(effect.sound, SOUND_PRESETS);
       error(
         "E_INVALID_SOUND",
         `${path}.sound`,
@@ -286,6 +306,8 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
   }
 }
 
+const SCRIPT_EXTENSIONS = [".ts", ".js"] as const;
+
 function hasExtension(path: string, extensions: readonly string[]): boolean {
   const lower = path.toLowerCase();
   return extensions.some((ext) => lower.endsWith(ext));
@@ -307,6 +329,8 @@ function checkField(spec: FieldSpec, value: unknown): string | undefined {
         : `must be one of ${spec.values.map((v) => `"${v}"`).join(", ")}, got ${describe(value)}.`;
     case "frames":
       return typeof value === "string" && isFrameList(value) ? undefined : `must be a frame list like "0", "1-4" or "0,2-3", got ${describe(value)}.`;
+    case "object":
+      return isObject(value) ? undefined : `must be an object like { "speed": 80 }, got ${describe(value)}.`;
   }
 }
 
@@ -326,7 +350,7 @@ function describe(value: unknown): string {
 }
 
 /** Returns the candidate within a small edit distance of `input`, if any. */
-function closest(input: string, candidates: readonly string[]): string | undefined {
+export function closestName(input: string, candidates: readonly string[]): string | undefined {
   let best: string | undefined;
   let bestDistance = Math.max(2, Math.floor(input.length / 3)) + 1;
   for (const candidate of candidates) {