@ludra/core 0.4.0 → 0.5.0

package/src/assertions.ts

@@ -1,8 +1,8 @@
 import { InputScript } from "./input.ts";
 import { defaultDuration, simulate } from "./simulate.ts";
 import { FIXED_DT, parseDuration, secondsToFrames } from "./time.ts";
-import { EVENT_TYPES, type GameEventType, type SceneDef } from "./types.ts";
-import { World, type GameEvent, type WorldSnapshot } from "./world.ts";
+import { EVENT_TYPES, type SceneDef } from "./types.ts";
+import { World, type GameEvent, type WorldOptions, type WorldSnapshot } from "./world.ts";
 
 const OPERATORS = ["<=", ">=", "==", "!=", "<", ">"] as const;
 type Operator = (typeof OPERATORS)[number];
@@ -15,14 +15,18 @@ type WorldField = (typeof WORLD_FIELDS)[number];
 
 type Subject =
   | { kind: "world"; field: WorldField }
-  | { kind: "events"; type: GameEventType }
-  | { kind: "entity"; id: string; field: EntityField };
+  /** Built-in event types, or custom events fired by scripts with world.emit(name). */
+  | { kind: "events"; name: string; builtin: boolean }
+  | { kind: "entity"; id: string; field: EntityField }
+  | { kind: "state"; id: string; key: string };
+
+type Value = number | boolean | string;
 
 export interface Assertion {
   source: string;
   subject: Subject;
   operator: Operator;
-  expected: number | boolean;
+  expected: Value;
   /** Frame to check at, or "end" for the last frame of the run. */
   at: number | "end";
 }
@@ -30,7 +34,7 @@ export interface Assertion {
 export class AssertionSyntaxError extends Error {}
 
 const EXAMPLES =
-  'Examples: "player.x > 400", "player.grounded == true at 1s", "score >= 3", "won == true", "deaths == 0", "events.jump == 1 at end", "coin1.exists == false".';
+  'Examples: "player.x > 400", "player.grounded == true at 1s", "score >= 3", "won == true", "deaths == 0", "events.jump == 1 at end", "coin1.exists == false", "door.state.open == true", "boss.state.phase == \\"angry\\"", "events.shoot >= 3".';
 
 /** Parses `<subject> <op> <value> [at <time|end>]`. */
 export function parseAssertion(source: string): Assertion {
@@ -39,29 +43,32 @@ export function parseAssertion(source: string): Assertion {
   const [, lhs = "", operator, rhs = "", at] = match;
 
   let subject: Subject;
+  const stateMatch = /^(.+)\.state\.([\w-]+)$/.exec(lhs);
   if ((WORLD_FIELDS as readonly string[]).includes(lhs)) {
     subject = { kind: "world", field: lhs as WorldField };
-  } else if (lhs.startsWith("events.")) {
-    const type = lhs.slice("events.".length);
-    if (!(EVENT_TYPES as readonly string[]).includes(type)) {
-      throw new AssertionSyntaxError(`Unknown event "${type}" in "${source}". Events: ${EVENT_TYPES.join(", ")}.`);
-    }
-    subject = { kind: "events", type: type as GameEventType };
+  } else if (lhs.startsWith("events.") && lhs.length > "events.".length) {
+    const name = lhs.slice("events.".length);
+    subject = { kind: "events", name, builtin: (EVENT_TYPES as readonly string[]).includes(name) };
+  } else if (stateMatch) {
+    subject = { kind: "state", id: stateMatch[1]!, key: stateMatch[2]! };
   } else {
     const dot = lhs.lastIndexOf(".");
     const field = lhs.slice(dot + 1);
     if (dot <= 0 || !(ENTITY_FIELDS as readonly string[]).includes(field)) {
       throw new AssertionSyntaxError(
-        `"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<${EVENT_TYPES.join("|")}> or <entityId>.<${ENTITY_FIELDS.join("|")}>.`,
+        `"${lhs}" is not something Ludra can check. Use ${WORLD_FIELDS.join(", ")}, events.<name>, <entityId>.<${ENTITY_FIELDS.join("|")}> or <entityId>.state.<key>.`,
       );
     }
     subject = { kind: "entity", id: lhs.slice(0, dot), field: field as EntityField };
   }
 
-  let expected: number | boolean;
+  let expected: Value;
   if (rhs === "true" || rhs === "false") expected = rhs === "true";
+  else if (/^".*"$/.test(rhs)) expected = rhs.slice(1, -1);
   else if (Number.isFinite(Number(rhs))) expected = Number(rhs);
-  else throw new AssertionSyntaxError(`Expected a number or true/false after "${operator}" in "${source}", got "${rhs}".`);
+  else {
+    throw new AssertionSyntaxError(`Expected a number, true/false or a "quoted string" after "${operator}" in "${source}", got ${rhs}.`);
+  }
 
   let frame: number | "end" = "end";
   if (at !== undefined && at !== "end") {
@@ -78,7 +85,7 @@ export function parseAssertion(source: string): Assertion {
 export interface AssertionResult {
   source: string;
   pass: boolean;
-  actual: number | boolean | undefined;
+  actual: unknown;
   time: number;
   message: string;
 }
@@ -86,7 +93,7 @@ export interface AssertionResult {
 export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot, events: readonly GameEvent[]): AssertionResult {
   const { subject, operator, expected, source } = assertion;
   const time = snapshot.time;
-  let actual: number | boolean | undefined;
+  let actual: unknown;
   let label: string;
 
   switch (subject.kind) {
@@ -94,10 +101,30 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
       actual = snapshot[subject.field];
       label = subject.field;
       break;
-    case "events":
-      actual = events.filter((e) => e.type === subject.type && e.frame <= snapshot.frame).length;
-      label = `events.${subject.type}`;
+    case "events": {
+      const matches = (e: GameEvent) => (subject.builtin ? e.type === subject.name : e.type === "custom" && e.name === subject.name);
+      actual = events.filter((e) => matches(e) && e.frame <= snapshot.frame).length;
+      label = `events.${subject.name}`;
+      break;
+    }
+    case "state": {
+      const entity = snapshot.entities[subject.id];
+      label = `${subject.id}.state.${subject.key}`;
+      if (!entity) {
+        return { source, pass: false, actual: undefined, time, message: `entity "${subject.id}" does not exist at ${time.toFixed(2)}s.` };
+      }
+      actual = entity.state?.[subject.key];
+      if (actual === undefined) {
+        return {
+          source,
+          pass: false,
+          actual,
+          time,
+          message: `${label} is not set at ${time.toFixed(2)}s. Scripts set it with self.state.${subject.key} = ...`,
+        };
+      }
       break;
+    }
     case "entity": {
       const entity = snapshot.entities[subject.id];
       label = `${subject.id}.${subject.field}`;
@@ -116,14 +143,20 @@ export function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot,
   }
 
   if (typeof actual !== typeof expected) {
-    return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, but it is compared with ${JSON.stringify(expected)}.` };
+    return {
+      source,
+      pass: false,
+      actual,
+      time,
+      message: `${label} is ${JSON.stringify(actual)} (a ${typeof actual}), but it is compared with ${JSON.stringify(expected)}.`,
+    };
   }
-  if (typeof actual === "boolean" && operator !== "==" && operator !== "!=") {
-    return { source, pass: false, actual, time, message: `${label} is true/false, so only == and != can be used.` };
+  if (typeof actual !== "number" && operator !== "==" && operator !== "!=") {
+    return { source, pass: false, actual, time, message: `${label} is a ${typeof actual}, so only == and != can be used.` };
   }
 
   const pass = compare(actual as number, operator, expected as number);
-  const shown = typeof actual === "number" ? round(actual) : actual;
+  const shown = typeof actual === "number" ? round(actual) : JSON.stringify(actual);
   return { source, pass, actual, time, message: `${label} = ${shown} at ${time.toFixed(2)}s` };
 }
 
@@ -166,7 +199,7 @@ export interface TestResult {
   error?: string;
 }
 
-export function runTest(scene: SceneDef, test: TestCase): TestResult {
+export function runTest(scene: SceneDef, test: TestCase, options: WorldOptions = {}): TestResult {
   let script: InputScript;
   let assertions: Assertion[];
   let frames: number;
@@ -187,10 +220,16 @@ export function runTest(scene: SceneDef, test: TestCase): TestResult {
 
   const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
   const snapshots = new Map<number, WorldSnapshot>();
-  const world = new World(scene);
-  simulate(world, script, frames, (w) => {
-    if (wanted.has(w.frame)) snapshots.set(w.frame, w.snapshot());
-  });
+  let world: World;
+  try {
+    world = new World(scene, options);
+    simulate(world, script, frames, (w) => {
+      if (wanted.has(w.frame)) snapshots.set(w.frame, w.snapshot());
+    });
+  } catch (err) {
+    // A throwing script fails this test, not the whole run.
+    return { name: test.name, pass: false, duration: frames * FIXED_DT, results: [], error: (err as Error).message };
+  }
 
   const results = assertions.map((a) => {
     const frame = a.at === "end" ? frames : Math.min(a.at, frames);

package/src/browser.ts

@@ -3,6 +3,7 @@ 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";
@@ -30,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;
 }
 
 /**
@@ -42,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>();
@@ -83,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);
@@ -125,9 +154,9 @@ export interface CapturedFrame {
 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 = await loadImages(scene, options.assetBase ?? "");
+  const [images, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
   const view = new View(scene, images);
-  const world = new World(scene);
+  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);
@@ -145,6 +174,31 @@ export async function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef,
   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));
@@ -195,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[];
 }