@ludra/core 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @ludra/core
 
-The runtime of [Ludra](https://github.com/ersingvn/ludra), the game engine built for AI agents. Most people want the [`ludra`](https://www.npmjs.com/package/ludra) CLI instead; use this package to embed the engine.
+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.

package/dist/browser.d.ts

@@ -10,3 +10,22 @@ export interface GameOptions {
  * Resolves (after images load) to a function that stops the game.
  */
 export declare function startGame(canvas: HTMLCanvasElement, scene: SceneDef, options?: GameOptions): Promise<() => void>;
+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 declare function captureFrames(canvas: HTMLCanvasElement, scene: SceneDef, options: CaptureOptions): Promise<CapturedFrame[]>;

package/dist/browser.js

@@ -1,6 +1,7 @@
 import { SoundPlayer } from "./audio.js";
 import { parseFrames } from "./components.js";
 import { collectAssetPaths } from "./effects.js";
+import { InputScript } from "./input.js";
 import { ParticleSystem } from "./particles.js";
 import { FIXED_DT } from "./time.js";
 import { World } from "./world.js";
@@ -92,6 +93,35 @@ export async function startGame(canvas, scene, options = {}) {
         window.removeEventListener("blur", onBlur);
     };
 }
+/**
+ * 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, scene, options) {
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        throw new Error("Canvas 2D context is not available.");
+    const images = await loadImages(scene, options.assetBase ?? "");
+    const view = new View(scene, images);
+    const world = new World(scene);
+    const script = InputScript.parse(options.inputs ?? "");
+    const wanted = new Set(options.frames);
+    const last = Math.max(0, ...options.frames);
+    const captured = [];
+    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;
+}
 async function loadImages(scene, assetBase) {
     const images = new Map();
     const paths = new Set(collectAssetPaths(scene).filter((ref) => ref.kind === "image").map((ref) => ref.path));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Ludra engine runtime: scene format, validation, deterministic simulation and rendering.",
   "license": "MIT",
   "repository": {

package/src/browser.ts

@@ -1,6 +1,7 @@
 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 { FIXED_DT } from "./time.ts";
 import type { Action, SceneDef } from "./types.ts";
@@ -101,6 +102,49 @@ 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 = await loadImages(scene, options.assetBase ?? "");
+  const view = new View(scene, images);
+  const world = new World(scene);
+  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;
+}
+
 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));