@potoru/render

Render frames of a Potoru .poto package to PNG in Node, with the Potoru renderer compiled to WebAssembly. No browser, no Chrome, no native binary.

npm install @potoru/render

import { readFile, writeFile } from "node:fs/promises";
import { render, renderFrames, openRenderer } from "@potoru/render";

const poto = new Uint8Array(await readFile("story.poto"));

// One frame as PNG bytes.
await writeFile("frame.png", await render(poto, { time: 1.5, scale: 0.5 }));

// Several frames through one renderer.
const pngs = await renderFrames(poto, { times: [0, 1, 2], width: 540 });

// Full control: Scenes, States, cameras, raw RGBA.
const renderer = await openRenderer(poto, { camera: "ig" });
console.log(renderer.view, renderer.states, renderer.cameras, renderer.duration());
const { width, height, rgba } = renderer.frame(0.5, { state: "main", scale: 0.25 });
renderer.close();

Options

| Option | Meaning | |---|---| | time | Seconds on the State's clock (default 0). | | scene | A Scene id of a multi-Scene story package (default: the entry Scene). | | state | A State id (default: the initial State). | | camera | A camera id of the package, or "stage" for the whole Stage (default: the package's own view). | | scale | Size relative to the view, the Stage or the camera frame (default 1). | | width, height | Output size in pixels; with only one, the other keeps the aspect. | | background | A CSS colour under the Stage and for the letterbox; null for a transparent frame. Experimental. | | libraries | Library files (Uint8Array) a linked package needs. |

Frames are straight-alpha RGBA8. PNGs are encoded with node:zlib.

Errors

Every failure is a PotoruError with a stable code and a diagnostic ({code, severity, message, fix?, didYouMean?}): decode-error, needs-library, needs-newer-player (the package needs a capability this renderer does not have: update @potoru/render), unknown-scene, unknown-state, unknown-camera (with didYouMean), invalid-option, render-error, missing-engine.

Runtimes

• Node 20 or newer. ES modules only.
• Not for browsers in 1.0: under a browser condition every function rejects with missing-engine. Play packages in a page with @potoru/web.
• Versions move in lockstep with @potoru/web, @potoru/react and @potoru/authoring.

Licence

Apache-2.0 (LICENSE, NOTICE). The wasm engine contains third-party Rust crates (tiny-skia under BSD-3-Clause, rustybuzz, png, flate2 and others) and the package ships three fonts under the SIL Open Font License 1.1: see THIRD-PARTY-NOTICES.txt and dist/fonts/. "Potoru" is a trademark of The Potoru Authors.