@ludra/core 0.3.1 → 0.5.0

package/dist/script.js

@@ -0,0 +1,87 @@
+import { closestName } from "./validate.js";
+export const SCRIPT_HOOKS = ["start", "update", "touch"];
+/** 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 function getScript(modules, src) {
+    if (!modules)
+        return undefined;
+    return modules instanceof Map ? modules.get(src) : modules[src];
+}
+/** A script threw, or was used wrongly. Names the file, entity, hook and frame. */
+export class ScriptError extends Error {
+    src;
+    entity;
+    hook;
+    frame;
+    constructor(details, message, options) {
+        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, src) {
+    const diagnostics = [];
+    const script = module?.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.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) {
+    const imports = [];
+    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/dist/types.d.ts

@@ -20,13 +20,18 @@ 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[];
 }
 export interface Diagnostic {

package/dist/validate.d.ts

@@ -10,3 +10,5 @@ export interface ValidationResult {
  * where possible, a fix an agent can apply without guessing.
  */
 export declare function validateScene(raw: unknown): ValidationResult;
+/** Returns the candidate within a small edit distance of `input`, if any. */
+export declare function closestName(input: string, candidates: readonly string[]): string | undefined;

package/dist/validate.js

@@ -32,6 +32,9 @@ export function validateScene(raw) {
                     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)}.`);
             }
@@ -73,7 +76,7 @@ export function validateScene(raw) {
         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, `Unknown component "${name}" on entity ${label}.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Run \`ludra components\` to list every component.`);
                 continue;
             }
@@ -97,6 +100,10 @@ export function validateScene(raw) {
         if (sprite && typeof sprite.image === "string" && sprite.image !== "" && !hasExtension(sprite.image, IMAGE_EXTENSIONS)) {
             error("E_INVALID_IMAGE", `${path}.components.sprite.image`, `"${sprite.image}" on entity ${label} is not an image file.`, `Use a path ending in ${IMAGE_EXTENSIONS.join(", ")}. SVG is easiest: you can write it as text.`);
         }
+        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") {
@@ -155,7 +162,7 @@ function validateFields(fields, value, path, owner, where, error, warn, ignore =
             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}`, `"${owner}" has no field "${field}", so it is ignored.`, suggestion ? `Did you mean "${suggestion}"?` : `Valid fields: ${Object.keys(fields).join(", ")}.`);
             continue;
         }
@@ -178,9 +185,11 @@ function validateEffects(effects, error, warn) {
     for (const [event, effect] of Object.entries(effects)) {
         const path = `effects.${event}`;
         if (!EVENT_TYPES.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 } }.`);
@@ -188,7 +197,7 @@ function validateEffects(effects, error, warn) {
         }
         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`, `"${effect.sound}" is neither a sound preset nor an audio file.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Presets: ${SOUND_PRESETS.join(", ")}. Files must end in ${AUDIO_EXTENSIONS.join(", ")}.`);
         }
         if (effect.particles !== undefined) {
@@ -201,6 +210,7 @@ function validateEffects(effects, error, warn) {
         }
     }
 }
+const SCRIPT_EXTENSIONS = [".ts", ".js"];
 function hasExtension(path, extensions) {
     const lower = path.toLowerCase();
     return extensions.some((ext) => lower.endsWith(ext));
@@ -223,6 +233,8 @@ function checkField(spec, value) {
                 : `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)}.`;
     }
 }
 function fixFor(spec) {
@@ -241,7 +253,7 @@ function describe(value) {
     return value === undefined ? "nothing" : JSON.stringify(value);
 }
 /** Returns the candidate within a small edit distance of `input`, if any. */
-function closest(input, candidates) {
+export function closestName(input, candidates) {
     let best;
     let bestDistance = Math.max(2, Math.floor(input.length / 3)) + 1;
     for (const candidate of candidates) {

package/dist/world.d.ts

@@ -1,5 +1,6 @@
-import { type Body, type Camera, type Collectible, type Emitter, type Goal, type Hazard, type Patrol, type Platformer, type Sprite, type Transform } from "./components.ts";
-import type { Action, Diagnostic, SceneDef } from "./types.ts";
+import { type Body, type Camera, type Collectible, type Emitter, type Goal, type Hazard, type Patrol, type Platformer, type ScriptComponent, type Sprite, type Transform } from "./components.ts";
+import { type Script, type ScriptModules } from "./script.ts";
+import { type Action, type Diagnostic, type SceneDef } from "./types.ts";
 export interface BodyState extends Body {
     grounded: boolean;
     /** The solid this body is standing on, so moving platforms can carry it. */
@@ -7,6 +8,8 @@ export interface BodyState extends Body {
 }
 export interface PlatformerState extends Platformer {
     coyoteTimer: number;
+    /** True from a player-initiated jump until the apex, so only those jumps are cut short on release. */
+    jumping: boolean;
     bufferTimer: number;
     spawnX: number;
     spawnY: number;
@@ -15,8 +18,19 @@ export interface PatrolState extends Patrol {
     originX: number;
     originY: number;
 }
+export interface ScriptState extends ScriptComponent {
+    module: Script;
+    started: boolean;
+    /** Ids of entities touched last frame, so `touch` fires only when touching starts. */
+    touching: Set<string>;
+}
 export interface Entity {
     id: string;
+    /** Script-owned data, kept between frames and included in snapshots. */
+    state: Record<string, unknown>;
+    /** Set once destroyed or collected, so stale script handles report `exists: false`. */
+    removed?: boolean;
+    script?: ScriptState;
     transform: Transform;
     body?: BodyState;
     sprite?: Sprite;
@@ -58,6 +72,13 @@ export type GameEvent = {
     type: "win";
     entity: string;
     goal: string;
+}
+/** Fired by a script with world.emit(name, data). */
+ | {
+    type: "custom";
+    name: string;
+    entity: string;
+    data?: unknown;
 });
 export interface EntitySnapshot {
     x: number;
@@ -65,6 +86,12 @@ export interface EntitySnapshot {
     vx: number;
     vy: number;
     grounded: boolean;
+    /** Present when a script stored data on the entity. */
+    state?: Record<string, unknown>;
+}
+export interface WorldOptions {
+    /** Loaded script modules, keyed by the `src` path used in the scene. */
+    scripts?: ScriptModules;
 }
 export interface WorldSnapshot {
     frame: number;
@@ -96,9 +123,17 @@ export declare class World {
     /** Set when a player reaches a goal. The simulation stops changing after that. */
     won: boolean;
     private previousInput;
-    constructor(scene: SceneDef);
+    private readonly scripts;
+    private seed;
+    private spawnCount;
+    private readonly handles;
+    private scriptApi;
+    private scriptInput;
+    /** The script hook currently running, for error messages and event attribution. */
+    private current;
+    constructor(scene: SceneDef, options?: WorldOptions);
     /** Validates raw scene JSON and builds a world, throwing on errors. */
-    static fromJSON(raw: unknown): World;
+    static fromJSON(raw: unknown, options?: WorldOptions): World;
     get time(): number;
     get(id: string): Entity | undefined;
     /** Advances one frame with the given actions held down. */
@@ -106,6 +141,21 @@ export declare class World {
     snapshot(): WorldSnapshot;
     private emit;
     private remove;
+    private createEntity;
+    private updateScripts;
+    /** Calls `touch` on scripted entities that started overlapping or touching another body this frame. */
+    private updateTouches;
+    private callHook;
+    /** An error caused by how a script used the API, reported against the running script. */
+    private misuse;
+    /** A stable script-facing view of an entity. */
+    private handle;
+    private resolve;
+    /** The `world` object scripts receive. */
+    private api;
+    private spawn;
+    /** mulberry32, seeded by world.seed. */
+    private random;
     private players;
     private updatePlatformers;
     /** Points each patrolling body toward the end of its path it is heading for. */
@@ -117,5 +167,8 @@ export declare class World {
     /** Sends a player back to where it started. Collected items stay collected. */
     private kill;
 }
-/** Strict overlap: bodies that merely touch (e.g. standing on the ground) do not overlap. */
-export declare function overlaps(a: Entity, b: Entity): boolean;
+/**
+ * Strict overlap: bodies that merely touch (e.g. standing on the ground) do not overlap.
+ * A positive `margin` grows both boxes, so touching counts too.
+ */
+export declare function overlaps(a: Entity, b: Entity, margin?: number): boolean;