@ludra/core 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @ludra/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runtime of [Ludra](https://github.com/ersingvn/ludra), the game engine built for AI agents. Most people want the [`@ludra/cli`](https://www.npmjs.com/package/@ludra/cli) command instead; use this package to embed the engine.
+
+- **Scene format and validation:** `validateScene(json)` returns diagnostics with a JSON path and a concrete fix.
+- **Deterministic simulation:** `new World(scene)` advances only through `world.step(heldActions)` at a fixed 60 Hz.
+- **Headless testing:** `InputScript.parse("right:1s, jump:0.4s")`, `simulate(...)`, `runTest(scene, { inputs, assert: ["won == true"] })` and `renderAscii(world)`.
+- **Browser runtime** (`@ludra/core/browser`): `startGame(canvas, scene, { assetBase })` adds sprites, animations, particles, sound and keyboard input. It never changes what the simulation does.
+
+```ts
+import { InputScript, simulate, World } from "@ludra/core";
+
+const world = World.fromJSON(sceneJson); // throws with diagnostics if invalid
+simulate(world, InputScript.parse("right:0.5s, right+jump:0.45s"), 120);
+console.log(world.snapshot());
+```
+
+Zero dependencies. Requires Node.js 22.18 or newer, or any modern browser. MIT licensed.

package/dist/ascii.d.ts

@@ -0,0 +1,11 @@
+import type { World } from "./world.ts";
+export interface AsciiOptions {
+    /** Width of the map in characters. Defaults to 80. */
+    columns?: number;
+}
+/**
+ * Draws the world as text so an agent can "see" a frame without a browser.
+ * Characters are about twice as tall as they are wide, so each row covers
+ * two columns' worth of pixels.
+ */
+export declare function renderAscii(world: World, options?: AsciiOptions): string;

package/dist/ascii.js

@@ -0,0 +1,62 @@
+const LEGEND = "@ player  # solid  = moving solid  o collectible  ^ hazard  E enemy  G goal  + sensor  D dynamic";
+/**
+ * Draws the world as text so an agent can "see" a frame without a browser.
+ * Characters are about twice as tall as they are wide, so each row covers
+ * two columns' worth of pixels.
+ */
+export function renderAscii(world, options = {}) {
+    const columns = options.columns ?? 80;
+    const cellWidth = world.width / columns;
+    const cellHeight = cellWidth * 2;
+    const rows = Math.max(1, Math.ceil(world.height / cellHeight));
+    const grid = Array.from({ length: rows }, () => Array(columns).fill(" "));
+    const outside = [];
+    const paint = (e, char) => {
+        const b = e.body;
+        const left = Math.floor((e.transform.x - b.width / 2) / cellWidth);
+        const right = Math.max(left, Math.ceil((e.transform.x + b.width / 2) / cellWidth) - 1);
+        const top = Math.floor((e.transform.y - b.height / 2) / cellHeight);
+        const bottom = Math.max(top, Math.ceil((e.transform.y + b.height / 2) / cellHeight) - 1);
+        if (right < 0 || left >= columns || bottom < 0 || top >= rows) {
+            // Off-screen static bodies (boundary walls) are expected; moving ones usually mean a bug.
+            if (b.type !== "static")
+                outside.push(`${char} ${e.id} is outside the world at (${Math.round(e.transform.x)}, ${Math.round(e.transform.y)})`);
+            return;
+        }
+        for (let row = Math.max(0, top); row <= Math.min(rows - 1, bottom); row++) {
+            for (let col = Math.max(0, left); col <= Math.min(columns - 1, right); col++) {
+                grid[row][col] = char;
+            }
+        }
+    };
+    // Later passes draw on top of earlier ones.
+    const withBody = world.entities.filter((e) => e.body);
+    const passes = [
+        ["#", (e) => e.body.type === "static" && !e.body.sensor],
+        ["=", (e) => e.body.type === "kinematic" && !e.body.sensor],
+        ["+", (e) => e.body.sensor && !e.collectible && !e.hazard && !e.goal],
+        ["o", (e) => !!e.collectible],
+        ["G", (e) => !!e.goal],
+        ["^", (e) => !!e.hazard && e.body.type !== "kinematic"],
+        ["E", (e) => !!e.hazard && e.body.type === "kinematic"],
+        ["D", (e) => e.body.type === "dynamic" && !e.platformer],
+        ["@", (e) => !!e.platformer],
+    ];
+    for (const [char, test] of passes) {
+        for (const e of withBody.filter(test))
+            paint(e, char);
+    }
+    const border = `+${"-".repeat(columns)}+`;
+    const lines = [
+        `t=${world.time.toFixed(2)}s  frame ${world.frame}  score ${world.score}  deaths ${world.deaths}${world.won ? "  WON" : ""}  (1 char = ${round(cellWidth)}x${round(cellHeight)}px)`,
+        border,
+        ...grid.map((row) => `|${row.join("")}|`),
+        border,
+        LEGEND,
+        ...outside,
+    ];
+    return lines.join("\n");
+}
+function round(n) {
+    return Math.round(n * 10) / 10;
+}

package/dist/assertions.d.ts

@@ -0,0 +1,57 @@
+import { type GameEventType, type SceneDef } from "./types.ts";
+import { type GameEvent, type WorldSnapshot } from "./world.ts";
+declare const OPERATORS: readonly ["<=", ">=", "==", "!=", "<", ">"];
+type Operator = (typeof OPERATORS)[number];
+declare const ENTITY_FIELDS: readonly ["x", "y", "vx", "vy", "grounded", "exists"];
+type EntityField = (typeof ENTITY_FIELDS)[number];
+declare const WORLD_FIELDS: readonly ["score", "deaths", "won"];
+type WorldField = (typeof WORLD_FIELDS)[number];
+type Subject = {
+    kind: "world";
+    field: WorldField;
+} | {
+    kind: "events";
+    type: GameEventType;
+} | {
+    kind: "entity";
+    id: string;
+    field: EntityField;
+};
+export interface Assertion {
+    source: string;
+    subject: Subject;
+    operator: Operator;
+    expected: number | boolean;
+    /** Frame to check at, or "end" for the last frame of the run. */
+    at: number | "end";
+}
+export declare class AssertionSyntaxError extends Error {
+}
+/** Parses `<subject> <op> <value> [at <time|end>]`. */
+export declare function parseAssertion(source: string): Assertion;
+export interface AssertionResult {
+    source: string;
+    pass: boolean;
+    actual: number | boolean | undefined;
+    time: number;
+    message: string;
+}
+export declare function evaluateAssertion(assertion: Assertion, snapshot: WorldSnapshot, events: readonly GameEvent[]): AssertionResult;
+/** One case in a `tests/*.test.json` file. */
+export interface TestCase {
+    name: string;
+    /** Input script, see `InputScript`. */
+    inputs?: string;
+    /** Run length, e.g. "3s". Defaults to the inputs plus one second, or the latest `at`. */
+    duration?: string | number;
+    assert: string[];
+}
+export interface TestResult {
+    name: string;
+    pass: boolean;
+    duration: number;
+    results: AssertionResult[];
+    error?: string;
+}
+export declare function runTest(scene: SceneDef, test: TestCase): TestResult;
+export {};

package/dist/assertions.js

@@ -0,0 +1,147 @@
+import { InputScript } from "./input.js";
+import { defaultDuration, simulate } from "./simulate.js";
+import { FIXED_DT, parseDuration, secondsToFrames } from "./time.js";
+import { EVENT_TYPES } from "./types.js";
+import { World } from "./world.js";
+const OPERATORS = ["<=", ">=", "==", "!=", "<", ">"];
+const ENTITY_FIELDS = ["x", "y", "vx", "vy", "grounded", "exists"];
+const WORLD_FIELDS = ["score", "deaths", "won"];
+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".';
+/** Parses `<subject> <op> <value> [at <time|end>]`. */
+export function parseAssertion(source) {
+    const match = /^\s*([\w.-]+)\s*(<=|>=|==|!=|<|>)\s*(\S+?)(?:\s+at\s+(\S+))?\s*$/.exec(source);
+    if (!match)
+        throw new AssertionSyntaxError(`Cannot parse assertion "${source}". ${EXAMPLES}`);
+    const [, lhs = "", operator, rhs = "", at] = match;
+    let subject;
+    if (WORLD_FIELDS.includes(lhs)) {
+        subject = { kind: "world", field: lhs };
+    }
+    else if (lhs.startsWith("events.")) {
+        const type = lhs.slice("events.".length);
+        if (!EVENT_TYPES.includes(type)) {
+            throw new AssertionSyntaxError(`Unknown event "${type}" in "${source}". Events: ${EVENT_TYPES.join(", ")}.`);
+        }
+        subject = { kind: "events", type: type };
+    }
+    else {
+        const dot = lhs.lastIndexOf(".");
+        const field = lhs.slice(dot + 1);
+        if (dot <= 0 || !ENTITY_FIELDS.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("|")}>.`);
+        }
+        subject = { kind: "entity", id: lhs.slice(0, dot), field: field };
+    }
+    let expected;
+    if (rhs === "true" || rhs === "false")
+        expected = rhs === "true";
+    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}".`);
+    let frame = "end";
+    if (at !== undefined && at !== "end") {
+        try {
+            frame = secondsToFrames(parseDuration(at));
+        }
+        catch (err) {
+            throw new AssertionSyntaxError(`${err.message} (in "${source}")`);
+        }
+    }
+    return { source, subject, operator: operator, expected, at: frame };
+}
+export function evaluateAssertion(assertion, snapshot, events) {
+    const { subject, operator, expected, source } = assertion;
+    const time = snapshot.time;
+    let actual;
+    let label;
+    switch (subject.kind) {
+        case "world":
+            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}`;
+            break;
+        case "entity": {
+            const entity = snapshot.entities[subject.id];
+            label = `${subject.id}.${subject.field}`;
+            if (subject.field === "exists")
+                actual = entity !== undefined;
+            else if (entity)
+                actual = entity[subject.field];
+            else {
+                return {
+                    source,
+                    pass: false,
+                    actual: undefined,
+                    time,
+                    message: `entity "${subject.id}" does not exist at ${time.toFixed(2)}s (wrong id, or it was collected/removed).`,
+                };
+            }
+        }
+    }
+    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)}.` };
+    }
+    if (typeof actual === "boolean" && operator !== "==" && operator !== "!=") {
+        return { source, pass: false, actual, time, message: `${label} is true/false, so only == and != can be used.` };
+    }
+    const pass = compare(actual, operator, expected);
+    const shown = typeof actual === "number" ? round(actual) : actual;
+    return { source, pass, actual, time, message: `${label} = ${shown} at ${time.toFixed(2)}s` };
+}
+function compare(a, operator, b) {
+    switch (operator) {
+        case "<":
+            return a < b;
+        case "<=":
+            return a <= b;
+        case ">":
+            return a > b;
+        case ">=":
+            return a >= b;
+        case "==":
+            return a === b;
+        case "!=":
+            return a !== b;
+    }
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+export function runTest(scene, test) {
+    let script;
+    let assertions;
+    let frames;
+    try {
+        if (!Array.isArray(test.assert) || test.assert.length === 0) {
+            throw new AssertionSyntaxError(`Test "${test.name}" has no "assert" list. ${EXAMPLES}`);
+        }
+        script = InputScript.parse(test.inputs ?? "");
+        assertions = test.assert.map(parseAssertion);
+        const latestAt = Math.max(0, ...assertions.map((a) => (a.at === "end" ? 0 : a.at)));
+        frames =
+            test.duration !== undefined
+                ? secondsToFrames(typeof test.duration === "number" ? test.duration : parseDuration(test.duration))
+                : Math.max(secondsToFrames(defaultDuration(script)), latestAt);
+    }
+    catch (err) {
+        return { name: test.name, pass: false, duration: 0, results: [], error: err.message };
+    }
+    const wanted = new Set(assertions.map((a) => (a.at === "end" ? frames : Math.min(a.at, frames))));
+    const snapshots = new Map();
+    const world = new World(scene);
+    simulate(world, script, frames, (w) => {
+        if (wanted.has(w.frame))
+            snapshots.set(w.frame, w.snapshot());
+    });
+    const results = assertions.map((a) => {
+        const frame = a.at === "end" ? frames : Math.min(a.at, frames);
+        return evaluateAssertion(a, snapshots.get(frame), world.events);
+    });
+    return { name: test.name, pass: results.every((r) => r.pass), duration: frames * FIXED_DT, results };
+}

package/dist/audio.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plays presets and audio files. Browsers only allow audio after a user
+ * gesture, so the context is created by `unlock()` on the first key press.
+ */
+export declare class SoundPlayer {
+    muted: boolean;
+    private context;
+    private output;
+    private readonly buffers;
+    private readonly assetBase;
+    constructor(assetBase: string);
+    unlock(): void;
+    play(sound: string): void;
+    private playPreset;
+    private playFile;
+}

package/dist/audio.js

@@ -0,0 +1,106 @@
+import { isSoundPreset } from "./effects.js";
+const MASTER_VOLUME = 0.5;
+/** Each preset is a few short oscillator or noise layers, in the spirit of sfxr. */
+const PRESETS = {
+    jump: { tones: [{ wave: "square", from: 280, to: 560, duration: 0.14, volume: 0.12 }] },
+    coin: {
+        tones: [
+            { wave: "square", from: 988, duration: 0.07, volume: 0.1 },
+            { wave: "square", from: 1319, start: 0.07, duration: 0.2, volume: 0.1 },
+        ],
+    },
+    hit: {
+        tones: [{ wave: "sawtooth", from: 220, to: 60, duration: 0.14, volume: 0.15 }],
+        noise: { duration: 0.12, volume: 0.25, from: 3000, to: 300 },
+    },
+    explosion: { noise: { duration: 0.55, volume: 0.45, from: 1600, to: 60 } },
+    powerup: {
+        tones: [523, 659, 784, 1047].map((from, i) => ({ wave: "triangle", from, start: i * 0.08, duration: 0.14, volume: 0.16 })),
+    },
+    blip: { tones: [{ wave: "sine", from: 880, duration: 0.06, volume: 0.15 }] },
+    thud: { tones: [{ wave: "sine", from: 150, to: 50, duration: 0.1, volume: 0.3 }] },
+};
+/**
+ * Plays presets and audio files. Browsers only allow audio after a user
+ * gesture, so the context is created by `unlock()` on the first key press.
+ */
+export class SoundPlayer {
+    muted = false;
+    context;
+    output;
+    buffers = new Map();
+    assetBase;
+    constructor(assetBase) {
+        this.assetBase = assetBase;
+    }
+    unlock() {
+        if (this.context)
+            return;
+        this.context = new AudioContext();
+        this.output = this.context.createGain();
+        this.output.gain.value = MASTER_VOLUME;
+        this.output.connect(this.context.destination);
+    }
+    play(sound) {
+        if (this.muted || !this.context || !this.output || sound === "")
+            return;
+        if (isSoundPreset(sound))
+            this.playPreset(this.context, this.output, sound);
+        else
+            void this.playFile(this.context, this.output, sound);
+    }
+    playPreset(ac, out, preset) {
+        const { tones = [], noise } = PRESETS[preset];
+        for (const tone of tones) {
+            const t = ac.currentTime + (tone.start ?? 0);
+            const osc = ac.createOscillator();
+            const gain = ac.createGain();
+            osc.type = tone.wave;
+            osc.frequency.setValueAtTime(tone.from, t);
+            osc.frequency.exponentialRampToValueAtTime(tone.to ?? tone.from, t + tone.duration);
+            gain.gain.setValueAtTime(tone.volume, t);
+            gain.gain.exponentialRampToValueAtTime(0.001, t + tone.duration);
+            osc.connect(gain).connect(out);
+            osc.start(t);
+            osc.stop(t + tone.duration + 0.02);
+        }
+        if (noise) {
+            const t = ac.currentTime;
+            const buffer = ac.createBuffer(1, Math.ceil(ac.sampleRate * noise.duration), ac.sampleRate);
+            const data = buffer.getChannelData(0);
+            for (let i = 0; i < data.length; i++)
+                data[i] = Math.random() * 2 - 1;
+            const source = ac.createBufferSource();
+            const filter = ac.createBiquadFilter();
+            const gain = ac.createGain();
+            source.buffer = buffer;
+            filter.type = "lowpass";
+            filter.frequency.setValueAtTime(noise.from, t);
+            filter.frequency.exponentialRampToValueAtTime(noise.to, t + noise.duration);
+            gain.gain.setValueAtTime(noise.volume, t);
+            gain.gain.exponentialRampToValueAtTime(0.001, t + noise.duration);
+            source.connect(filter).connect(gain).connect(out);
+            source.start(t);
+        }
+    }
+    async playFile(ac, out, path) {
+        let pending = this.buffers.get(path);
+        if (!pending) {
+            pending = fetch(this.assetBase + path)
+                .then((res) => (res.ok ? res.arrayBuffer() : Promise.reject(new Error(`${res.status}`))))
+                .then((data) => ac.decodeAudioData(data))
+                .catch((err) => {
+                console.warn(`[ludra] could not load sound "${path}":`, err);
+                return undefined;
+            });
+            this.buffers.set(path, pending);
+        }
+        const buffer = await pending;
+        if (!buffer)
+            return;
+        const source = ac.createBufferSource();
+        source.buffer = buffer;
+        source.connect(out);
+        source.start();
+    }
+}

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+import type { SceneDef } from "./types.ts";
+export interface GameOptions {
+    /** URL prefix for image and audio paths in the scene. Defaults to "". */
+    assetBase?: string;
+}
+/**
+ * Runs a scene in a canvas with keyboard controls, images, particles and
+ * sound. The simulation uses the same fixed step as headless runs, so what
+ * tests verify is what players get; everything added here is presentation.
+ * Resolves (after images load) to a function that stops the game.
+ */
+export declare function startGame(canvas: HTMLCanvasElement, scene: SceneDef, options?: GameOptions): Promise<() => void>;