@openbone/mcp 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/bridge.js ADDED
@@ -0,0 +1,79 @@
1
+ import { WebSocketServer } from "ws";
2
+ import { isLocalRequest } from "./local-only.js";
3
+ /**
4
+ * Live bridge: the OpenBone editor connects here (ws://localhost:PORT) so changes made by the
5
+ * agent appear instantly in the editor, and edits made in the editor are visible to the agent.
6
+ *
7
+ * Messages (JSON):
8
+ * editor → server: {type:"hello"} | {type:"op", op, args} | {type:"undo"} | {type:"redo"} | {type:"load", doc}
9
+ * server → editor: {type:"load", doc, path} | {type:"ops", ops} | {type:"error", message}
10
+ */
11
+ export function startBridge(session, port, log) {
12
+ const wss = new WebSocketServer({
13
+ port,
14
+ host: "127.0.0.1",
15
+ // Only the editor (local page or desktop app) and non-browser clients: web pages on other sites are refused.
16
+ verifyClient: ({ req }) => {
17
+ const ok = isLocalRequest({ origin: req.headers.origin, host: req.headers.host });
18
+ if (!ok)
19
+ log(`bridge: refused a connection from ${req.headers.origin ?? "?"} (not the OpenBone editor)`);
20
+ return ok;
21
+ },
22
+ });
23
+ const clients = new Set();
24
+ const send = (ws, msg) => ws.readyState === ws.OPEN && ws.send(JSON.stringify(msg));
25
+ const broadcast = (msg, except) => {
26
+ for (const c of clients)
27
+ if (c !== except)
28
+ send(c, msg);
29
+ };
30
+ let current;
31
+ session.store.subscribe((doc, e) => {
32
+ const origin = e.origin;
33
+ const except = origin === "bridge" ? current : undefined;
34
+ if (e.kind === "op" || e.kind === "transaction")
35
+ broadcast({ type: "ops", ops: e.ops }, except);
36
+ else
37
+ broadcast({ type: "load", doc, path: session.filePath });
38
+ });
39
+ wss.on("connection", (ws) => {
40
+ clients.add(ws);
41
+ log(`editor connected (${clients.size})`);
42
+ send(ws, { type: "load", doc: session.doc, path: session.filePath });
43
+ ws.on("close", () => clients.delete(ws));
44
+ ws.on("message", async (raw) => {
45
+ let msg;
46
+ try {
47
+ msg = JSON.parse(String(raw));
48
+ }
49
+ catch {
50
+ return;
51
+ }
52
+ current = ws;
53
+ try {
54
+ if (msg.type === "hello")
55
+ send(ws, { type: "load", doc: session.doc, path: session.filePath });
56
+ else if (msg.type === "op" && msg.op)
57
+ session.store.apply(msg.op, msg.args ?? {}, "bridge");
58
+ else if (msg.type === "undo")
59
+ session.store.undo();
60
+ else if (msg.type === "redo")
61
+ session.store.redo();
62
+ else if (msg.type === "load" && msg.doc)
63
+ session.store.load(msg.doc);
64
+ await session.maybeAutosave();
65
+ }
66
+ catch (e) {
67
+ send(ws, { type: "error", message: e.message });
68
+ // Resync the editor so it does not drift from the server copy.
69
+ send(ws, { type: "load", doc: session.doc, path: session.filePath });
70
+ }
71
+ finally {
72
+ current = undefined;
73
+ }
74
+ });
75
+ });
76
+ wss.on("listening", () => log(`live bridge on ws://127.0.0.1:${port}`));
77
+ wss.on("error", (e) => log(`bridge error: ${e.message}`));
78
+ return wss;
79
+ }
@@ -0,0 +1,97 @@
1
+ import { type OpenBoneDocument } from "@openbone/core";
2
+ import { type Frame, type SheetEngine, type TimedMixCommand } from "@openbone/export";
3
+ import { type AtlasSettings } from "@openbone/render-canvas";
4
+ import { type ScriptHost } from "@openbone/runtime";
5
+ import type { ProjectSession } from "./session.js";
6
+ /**
7
+ * Every export format, headless: the one code path behind the MCP `export_file` tool and `openbone export`, using
8
+ * the same encoders, atlas packer and runtime-data export as the editor's Export dialog.
9
+ */
10
+ export declare const EXPORT_FORMATS: readonly ["obone", "json", "obonb", "atlas", "png", "jpeg", "apng", "gif", "psd", "avi", "mov", "mp4", "webm", "spritesheet", "web"];
11
+ export type ExportFormat = (typeof EXPORT_FORMATS)[number];
12
+ export type Step = {
13
+ advance?: number;
14
+ setInputs?: Record<string, boolean | number | string>;
15
+ fire?: string[];
16
+ pointer?: {
17
+ type: "down" | "up" | "move";
18
+ x: number;
19
+ y: number;
20
+ };
21
+ };
22
+ /** Texture atlas settings (the Export dialog's "Texture atlas" group): the packer settings shared with the CLI and editor. */
23
+ export type AtlasExportOptions = AtlasSettings;
24
+ export interface ExportRequest {
25
+ format: ExportFormat;
26
+ animation?: string;
27
+ stateMachine?: string;
28
+ steps?: Step[];
29
+ skin?: string;
30
+ /** json/obonb/atlas: animations to keep (names; default all marked for export). spritesheet: clips. */
31
+ animations?: string[];
32
+ stateMachines?: string[];
33
+ duration?: number;
34
+ fps?: number;
35
+ scale?: number;
36
+ transparent?: boolean;
37
+ /** png/jpeg: every frame in a ZIP instead of one frame. */
38
+ sequence?: boolean;
39
+ /** png/jpeg single frame: time in the animation. */
40
+ time?: number;
41
+ engine?: SheetEngine;
42
+ singleFile?: boolean;
43
+ minify?: boolean;
44
+ binary?: boolean;
45
+ /** avi/mov/mp4/webm: include the sound the run plays (default true). */
46
+ audio?: boolean;
47
+ /** mp4/webm: quality 0..1 (default 0.85). */
48
+ quality?: number;
49
+ /** json/obonb: pack images into an embedded texture atlas (like the dialog's Pack option). */
50
+ pack?: boolean;
51
+ /** obone/json/obonb: embed every image and audio file as data: URIs, so the file opens anywhere on its own. */
52
+ embed?: boolean;
53
+ atlas?: AtlasExportOptions;
54
+ }
55
+ export interface ExportResult {
56
+ bytes: Uint8Array;
57
+ /** File extension (without the dot), e.g. "png" or "zip"; APNG is "png" with `suffix` ".apng". */
58
+ ext: string;
59
+ /** Extra name part before the extension: ".apng", or "-atlas", "-web", "-png", "-spritesheet-unity" … for ZIPs. */
60
+ suffix: string;
61
+ /** Human summary: frames, sheets, warnings. */
62
+ note: string;
63
+ }
64
+ /** Render frames of an animation or a state machine run (RGBA, artboard size × scale). */
65
+ export declare function renderFrames(session: ProjectSession, req: {
66
+ animation?: string;
67
+ stateMachine?: string;
68
+ steps?: Step[];
69
+ skin?: string;
70
+ duration?: number;
71
+ fps: number;
72
+ scale: number;
73
+ background: string | null;
74
+ }, scriptHost?: ScriptHost | null,
75
+ /** Filled with the audio commands the run emits, with their time (for the sound track of a video). */
76
+ audioOut?: TimedMixCommand[]): Promise<Frame[]>;
77
+ /** A frame as JPEG (flattened onto `bg`). */
78
+ export declare function jpegOf(f: Frame, bg: string, quality?: number): Uint8Array;
79
+ /** Bytes of a document asset src (data: URI or a path relative to the project). */
80
+ export declare function assetBytes(session: ProjectSession, src: string): Promise<Buffer>;
81
+ /** Copy of a document with every image, atlas page and audio file embedded as data: URIs (for self-contained exports). */
82
+ export declare function embedAssets(session: ProjectSession, d: OpenBoneDocument): Promise<OpenBoneDocument>;
83
+ /** Pack a (runtime) document's images into atlas pages with the dialog's settings; returns a packed copy and any warnings. */
84
+ export declare function packDocument(session: ProjectSession, d: OpenBoneDocument, o?: AtlasExportOptions): Promise<{
85
+ doc: OpenBoneDocument;
86
+ warnings: string[];
87
+ }>;
88
+ /** One packed copy per scale variant (`o.scales`), images loaded once. */
89
+ export declare function packDocumentScales(session: ProjectSession, d: OpenBoneDocument, o: AtlasExportOptions): Promise<{
90
+ suffix: string;
91
+ doc: OpenBoneDocument;
92
+ warnings: string[];
93
+ }[]>;
94
+ /** Base name for exported files: the project file's name, else the document name. */
95
+ export declare function exportBaseName(session: ProjectSession): string;
96
+ /** Export the session's document in one format. Pure apart from reading assets: the caller writes the bytes. */
97
+ export declare function exportFile(session: ProjectSession, a: ExportRequest, scriptHost: () => Promise<ScriptHost>): Promise<ExportResult>;
package/dist/export.js ADDED
@@ -0,0 +1,309 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { createCanvas } from "@napi-rs/canvas";
4
+ import { animationDuration, applyOp, exportDocument, serialize, serializeBinary } from "@openbone/core";
5
+ import { buildSpriteSheets, createZip, encodeApng, encodeAviMjpeg, encodeGif, encodeMovMjpeg, encodePng, encodePsd, atlasExportFiles, floatToPcm, mixAudioCommands, enginePackZip, webIndexHtml, webPackZip, } from "@openbone/export";
6
+ import { CanvasRenderer, atlasBuildOptions, describeAtlas } from "@openbone/render-canvas";
7
+ import { OpenBoneInstance } from "@openbone/runtime";
8
+ import { decodeAudio, encodeVideoFfmpeg, findFfmpeg } from "./media.js";
9
+ import { loadImages, packAtlasFull, packAtlasScales, useSkin } from "./render.js";
10
+ /**
11
+ * Every export format, headless: the one code path behind the MCP `export_file` tool and `openbone export`, using
12
+ * the same encoders, atlas packer and runtime-data export as the editor's Export dialog.
13
+ */
14
+ export const EXPORT_FORMATS = ["obone", "json", "obonb", "atlas", "png", "jpeg", "apng", "gif", "psd", "avi", "mov", "mp4", "webm", "spritesheet", "web"];
15
+ /** Render frames of an animation or a state machine run (RGBA, artboard size × scale). */
16
+ export async function renderFrames(session, req, scriptHost,
17
+ /** Filled with the audio commands the run emits, with their time (for the sound track of a video). */
18
+ audioOut) {
19
+ const doc = session.doc;
20
+ const images = await loadImages(session, doc);
21
+ const w = Math.max(1, Math.round(doc.width * req.scale));
22
+ const h = Math.max(1, Math.round(doc.height * req.scale));
23
+ const canvas = createCanvas(w, h);
24
+ const ctx = canvas.getContext("2d");
25
+ const renderer = new CanvasRenderer(ctx, (id) => images.get(id));
26
+ const inst = new OpenBoneInstance(doc, { scriptHost });
27
+ useSkin(inst, req.skin);
28
+ const sm = req.stateMachine !== undefined || req.steps ? inst.useStateMachine(req.stateMachine || undefined) : null;
29
+ let duration = req.duration;
30
+ if (!sm) {
31
+ const anim = doc.animations.find((a) => a.name === req.animation || a.id === req.animation) ?? doc.animations[0];
32
+ if (!anim)
33
+ throw new Error("No animation to render");
34
+ inst.animationState.setAnimation(0, anim.name, true, 0);
35
+ duration ??= Math.max(animationDuration(anim), 1 / req.fps);
36
+ }
37
+ duration ??= 2;
38
+ const schedule = [];
39
+ let acc = 0;
40
+ for (const s of req.steps ?? []) {
41
+ schedule.push({ at: acc, step: s });
42
+ acc += s.advance ?? 0;
43
+ }
44
+ const frames = [];
45
+ const count = Math.max(1, Math.round(duration * req.fps));
46
+ let t = 0;
47
+ // Commands emitted while advancing to a frame are stamped with that frame's time.
48
+ let stamp = 0;
49
+ if (audioOut)
50
+ inst.on("audio", (c) => audioOut.push({ time: stamp, command: c }));
51
+ for (let f = 0; f < count; f++) {
52
+ stamp = f === 0 ? 0 : t + 1 / req.fps;
53
+ if (sm)
54
+ while (schedule.length && schedule[0].at <= t + 1e-9) {
55
+ const { step } = schedule.shift();
56
+ for (const [k, v] of Object.entries(step.setInputs ?? {}))
57
+ sm.setInput(k, v);
58
+ for (const n of step.fire ?? [])
59
+ sm.fire(n);
60
+ if (step.pointer)
61
+ sm.pointer(step.pointer.type, ...inst.artboardToSkeleton(step.pointer.x, step.pointer.y));
62
+ }
63
+ inst.advance(f === 0 ? 0 : 1 / req.fps);
64
+ if (f)
65
+ t += 1 / req.fps;
66
+ ctx.clearRect(0, 0, w, h);
67
+ renderer.render(inst.skeleton, { view: { x: 0, y: 0, zoom: req.scale }, bones: false, background: req.background });
68
+ frames.push({ width: w, height: h, data: new Uint8ClampedArray(ctx.getImageData(0, 0, w, h).data) });
69
+ }
70
+ return frames;
71
+ }
72
+ /** A frame as JPEG (flattened onto `bg`). */
73
+ export function jpegOf(f, bg, quality = 90) {
74
+ const c = createCanvas(f.width, f.height);
75
+ const g = c.getContext("2d");
76
+ const tmp = createCanvas(f.width, f.height);
77
+ const tg = tmp.getContext("2d");
78
+ const id = tg.createImageData(f.width, f.height);
79
+ id.data.set(f.data);
80
+ tg.putImageData(id, 0, 0);
81
+ g.fillStyle = bg;
82
+ g.fillRect(0, 0, f.width, f.height);
83
+ g.drawImage(tmp, 0, 0);
84
+ return new Uint8Array(c.toBuffer("image/jpeg", quality));
85
+ }
86
+ const MIME = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif", wav: "audio/wav", mp3: "audio/mpeg", ogg: "audio/ogg" };
87
+ /** Bytes of a document asset src (data: URI or a path relative to the project). */
88
+ export async function assetBytes(session, src) {
89
+ if (src.startsWith("data:"))
90
+ return Buffer.from(src.slice(src.indexOf(",") + 1), "base64");
91
+ if (/^https?:/.test(src))
92
+ return Buffer.from(await (await fetch(src)).arrayBuffer());
93
+ return readFile(path.isAbsolute(src) ? src : path.join(session.baseDir, src));
94
+ }
95
+ /** Copy of a document with every image, atlas page and audio file embedded as data: URIs (for self-contained exports). */
96
+ export async function embedAssets(session, d) {
97
+ const out = structuredClone(d);
98
+ const embed = async (src) => {
99
+ if (!src || src.startsWith("data:"))
100
+ return src;
101
+ const ext = src.split(".").pop().toLowerCase();
102
+ return `data:${MIME[ext] ?? "application/octet-stream"};base64,${(await assetBytes(session, src)).toString("base64")}`;
103
+ };
104
+ for (const img of out.images)
105
+ if (img.src)
106
+ img.src = await embed(img.src);
107
+ for (const p of out.atlas?.pages ?? [])
108
+ p.src = await embed(p.src);
109
+ for (const a of out.audio?.assets ?? [])
110
+ a.src = await embed(a.src);
111
+ return out;
112
+ }
113
+ /** Pack a (runtime) document's images into atlas pages with the dialog's settings; returns a packed copy and any warnings. */
114
+ export async function packDocument(session, d, o = {}) {
115
+ const out = structuredClone(d);
116
+ if (!out.images.length)
117
+ return { doc: out, warnings: [] };
118
+ const { atlas, warnings } = await packAtlasFull(session, out, atlasBuildOptions(o));
119
+ applyOp(out, "setAtlas", { atlas, stripImageSources: true });
120
+ return { doc: out, warnings };
121
+ }
122
+ /** One packed copy per scale variant (`o.scales`), images loaded once. */
123
+ export async function packDocumentScales(session, d, o) {
124
+ const built = await packAtlasScales(session, d, atlasBuildOptions(o), o.scales ?? []);
125
+ return built.map((b) => {
126
+ const out = structuredClone(d);
127
+ applyOp(out, "setAtlas", { atlas: b.atlas, stripImageSources: true });
128
+ return { suffix: b.suffix, doc: out, warnings: b.warnings };
129
+ });
130
+ }
131
+ /** Base name for exported files: the project file's name, else the document name. */
132
+ export function exportBaseName(session) {
133
+ return (session.filePath ? path.basename(session.filePath).replace(/\.\w+$/, "") : session.doc.name || "openbone").replace(/[^\w.-]+/g, "_");
134
+ }
135
+ /** Export the session's document in one format. Pure apart from reading assets: the caller writes the bytes. */
136
+ export async function exportFile(session, a, scriptHost) {
137
+ const doc = session.doc;
138
+ const fps = a.fps ?? 30;
139
+ const scale = a.scale ?? 1;
140
+ const time = a.time ?? 0;
141
+ const base = exportBaseName(session);
142
+ const bg = a.transparent ? null : (doc.background ?? "#ffffff");
143
+ const ids = (list, names) => (names ? list.filter((x) => names.includes(x.name) || names.includes(x.id)).map((x) => x.id) : undefined);
144
+ const runtimeData = () => exportDocument(doc, {
145
+ animations: ids(doc.animations, a.animations) ?? doc.animations.filter((x) => x.export !== false).map((x) => x.id),
146
+ stateMachines: ids(doc.stateMachines, a.stateMachines),
147
+ nonessential: false,
148
+ });
149
+ const ext = {
150
+ obone: "obone",
151
+ json: "json",
152
+ obonb: "obonb",
153
+ atlas: "zip",
154
+ png: a.sequence ? "zip" : "png",
155
+ jpeg: a.sequence ? "zip" : "jpg",
156
+ apng: "png",
157
+ gif: "gif",
158
+ psd: "psd",
159
+ avi: "avi",
160
+ mov: "mov",
161
+ mp4: "mp4",
162
+ webm: "webm",
163
+ spritesheet: "zip",
164
+ web: a.singleFile ? "html" : "zip",
165
+ };
166
+ // Every ZIP format gets its own suffix, so exporting several formats into one folder never overwrites a file.
167
+ const suffix = a.format === "apng" ? ".apng"
168
+ : a.format === "spritesheet" ? `-spritesheet-${a.engine ?? "generic"}`
169
+ : ext[a.format] === "zip" ? `-${a.format}`
170
+ : "";
171
+ const done = (bytes, note = "") => ({ bytes, ext: ext[a.format], suffix, note });
172
+ if (a.format === "obone") {
173
+ // Paths are relative to the project folder: embedded, the file can be opened from anywhere (also in the web editor,
174
+ // which can't read the files next to an opened file).
175
+ const out = a.embed ? await embedAssets(session, doc) : doc;
176
+ return done(new TextEncoder().encode(serialize(out)), a.embed ? " · images and audio embedded" : "");
177
+ }
178
+ if (a.format === "json" || a.format === "obonb") {
179
+ const r = runtimeData();
180
+ let d = r.doc;
181
+ const warnings = [...r.warnings];
182
+ if (a.pack && d.images.length) {
183
+ const p = await packDocument(session, d, a.atlas);
184
+ d = p.doc;
185
+ warnings.push(...p.warnings);
186
+ }
187
+ if (a.embed)
188
+ d = await embedAssets(session, d);
189
+ const bytes = a.format === "json" ? new TextEncoder().encode(serialize(d)) : serializeBinary(d, { precision: "float32" });
190
+ return done(bytes, warnings.length ? ` · ${warnings.join("; ")}` : "");
191
+ }
192
+ if (a.format === "atlas") {
193
+ // Runtime data next to its atlas pages as separate image files (smaller JSON, cacheable textures); one set per scale.
194
+ const r = runtimeData();
195
+ if (!r.doc.images.length)
196
+ throw new Error("No images to pack");
197
+ const variants = a.atlas?.scales?.length ? await packDocumentScales(session, r.doc, a.atlas) : [{ suffix: "", ...(await packDocument(session, r.doc, a.atlas)) }];
198
+ const files = atlasExportFiles(base, variants, { binary: a.binary ?? false });
199
+ const warnings = [...new Set(variants.flatMap((v) => v.warnings))];
200
+ const desc = variants.map((v) => `${variants.length > 1 ? `${v.suffix || "(base)"}: ` : ""}${describeAtlas(v.doc.atlas)}`).join(" · ");
201
+ return done(createZip(files), ` · ${desc}${warnings.length ? ` · ${warnings.join("; ")}` : ""}`);
202
+ }
203
+ if (a.format === "web") {
204
+ const { buildWebBundle } = await import("@openbone/player/bundle");
205
+ const minify = a.minify ?? true;
206
+ const binary = a.binary ?? true;
207
+ let rd = exportDocument(doc, { pruneUnused: true, nonessential: false }).doc;
208
+ if (a.pack && rd.images.length)
209
+ rd = (await packDocument(session, rd, a.atlas)).doc;
210
+ const d = await embedAssets(session, rd);
211
+ const docBytes = binary ? serializeBinary(d, { precision: "float32" }) : new TextEncoder().encode(serialize(d));
212
+ const sm = (a.stateMachine ? d.stateMachines.find((m) => m.name === a.stateMachine) : null) ?? d.stateMachines[0];
213
+ const hasScripts = d.scripts.length > 0;
214
+ const lazy = hasScripts && !a.singleFile;
215
+ const playerCode = await buildWebBundle({ format: "iife", minify, scripts: lazy ? "lazy" : hasScripts });
216
+ let scriptsAddon;
217
+ if (lazy) {
218
+ const { buildScriptsAddon, quickJsWasmBytes } = await import("@openbone/player/bundle");
219
+ scriptsAddon = { code: await buildScriptsAddon({ minify }), wasm: quickJsWasmBytes() };
220
+ }
221
+ const pack = {
222
+ title: doc.name || base,
223
+ baseName: base,
224
+ playerCode,
225
+ format: "iife",
226
+ minified: minify,
227
+ scripts: hasScripts,
228
+ scriptsAddon,
229
+ doc: docBytes,
230
+ docExt: (binary ? "obonb" : "obone"),
231
+ singleFile: !!a.singleFile,
232
+ demoControls: true,
233
+ stateMachine: sm?.name,
234
+ animation: sm ? undefined : (a.animation ?? d.animations[0]?.name),
235
+ width: d.width,
236
+ height: d.height,
237
+ background: a.transparent ? "transparent" : undefined,
238
+ inputs: sm?.inputs.map((i) => ({ name: i.name, type: i.type })) ?? [],
239
+ hasScripts,
240
+ hasAudio: !!d.audio?.assets.length,
241
+ };
242
+ return done(a.singleFile ? new TextEncoder().encode(webIndexHtml(pack)) : webPackZip(pack));
243
+ }
244
+ if (a.format === "spritesheet") {
245
+ const names = a.animations ?? doc.animations.filter((x) => x.export !== false).map((x) => x.name);
246
+ if (!names.length)
247
+ throw new Error("No animations to put on the sheet");
248
+ const clips = [];
249
+ for (const name of names) {
250
+ const frames = await renderFrames(session, { animation: name, skin: a.skin, fps, scale, background: bg }, await scriptHost());
251
+ clips.push({ name, fps, loop: true, frames });
252
+ }
253
+ const set = buildSpriteSheets(clips, { trim: true, padding: 2, maxSize: 2048 });
254
+ const bytes = await enginePackZip(a.engine ?? "generic", set, { name: base, scale });
255
+ return done(bytes, ` · ${set.pages.length} sheet(s), ${clips.reduce((n, c) => n + c.frames.length, 0)} frames`);
256
+ }
257
+ const single = (a.format === "png" || a.format === "jpeg") && !a.sequence;
258
+ const video = a.format === "avi" || a.format === "mov" || a.format === "mp4" || a.format === "webm";
259
+ const timed = video && a.audio !== false ? [] : undefined;
260
+ const flat = doc.background ?? "#ffffff";
261
+ const frames = single
262
+ ? await (async () => {
263
+ // One frame at `time`: run up to it at the export frame rate (one big step would skip the state machine steps
264
+ // scheduled in between, e.g. a trigger fired at 0.5 s for a frame at 2 s) and keep the last frame.
265
+ const fr = await renderFrames(session, { animation: a.animation, stateMachine: a.stateMachine, steps: a.steps, skin: a.skin, duration: time + 1 / fps, fps, scale, background: a.format === "jpeg" ? flat : bg }, await scriptHost());
266
+ return [fr[fr.length - 1]];
267
+ })()
268
+ : await renderFrames(session, { animation: a.animation, stateMachine: a.stateMachine, steps: a.steps, skin: a.skin, duration: a.duration, fps, scale, background: a.format === "jpeg" || video ? flat : bg }, await scriptHost(), timed);
269
+ const { width, height } = frames[0];
270
+ const delayMs = Math.round(1000 / fps);
271
+ let bytes;
272
+ if (a.format === "png")
273
+ bytes = single ? await encodePng(frames[0]) : createZip(await Promise.all(frames.map(async (f, i) => ({ name: `${base}_${String(i + 1).padStart(4, "0")}.png`, data: await encodePng(f) }))));
274
+ else if (a.format === "jpeg")
275
+ bytes = single ? jpegOf(frames[0], flat) : createZip(frames.map((f, i) => ({ name: `${base}_${String(i + 1).padStart(4, "0")}.jpg`, data: jpegOf(f, flat) })));
276
+ else if (a.format === "apng")
277
+ bytes = await encodeApng(frames, { delayMs });
278
+ else if (a.format === "gif")
279
+ bytes = encodeGif(frames, { delayMs, transparent: !!a.transparent });
280
+ else if (a.format === "psd")
281
+ bytes = encodePsd(frames.map((f, i) => ({ name: `frame ${i + 1}`, frame: f })));
282
+ let sound = "";
283
+ if (video) {
284
+ // The sound track: what the run played, mixed like the players mix it.
285
+ let mix = null;
286
+ if (timed?.length) {
287
+ const decoded = new Map();
288
+ for (const c of timed)
289
+ if (c.command.type === "play" && !decoded.has(c.command.asset)) {
290
+ const asset = doc.audio?.assets.find((x) => x.id === c.command.asset);
291
+ decoded.set(c.command.asset, asset ? await decodeAudio(await assetBytes(session, asset.src)).catch(() => null) : null);
292
+ }
293
+ const missing = new Set();
294
+ mix = mixAudioCommands(doc, timed, frames.length / fps, (id) => decoded.get(id) ?? null, { missing });
295
+ const names = [...missing].map((id) => doc.audio?.assets.find((x) => x.id === id)?.name ?? id);
296
+ if (names.length)
297
+ sound = ` · without ${names.join(", ")} (${findFfmpeg() ? "could not be decoded" : "only WAV decodes without ffmpeg on the PATH"})`;
298
+ if (mix)
299
+ sound = ` · with sound${sound}`;
300
+ }
301
+ if (a.format === "mp4" || a.format === "webm")
302
+ bytes = await encodeVideoFfmpeg(frames, { format: a.format, fps, quality: a.quality, audio: mix });
303
+ else
304
+ bytes = (a.format === "avi" ? encodeAviMjpeg : encodeMovMjpeg)(frames.map((f) => jpegOf(f, flat)), { width, height, fps, audio: mix ? floatToPcm(mix.channels, mix.sampleRate) : null });
305
+ }
306
+ else if (!bytes)
307
+ throw new Error(`Unknown format ${a.format}`);
308
+ return done(bytes, single ? "" : ` · ${frames.length} frames at ${fps} fps, ${width}×${height}${sound}`);
309
+ }
@@ -0,0 +1 @@
1
+ export declare const GUIDE = "# OpenBone authoring guide (for agents)\n\nCoordinate system: skeleton space is y-UP, rotations in degrees counter-clockwise. The skeleton origin (0,0)\nsits at (originX, originY) pixels in the artboard (artboard pixels are y-down). Default artboard 800x600,\norigin (400,450) \u2014 so y=0 is near the bottom, positive y goes up.\n\nEverything can be referenced by **name or id**. Every edit tool validates its input and returns ids.\n\n## Typical workflow\n1. new_project {name, path} (autosaves to path) \u2014 or open_project.\n2. Rig: add_bone (parent defaults to root; x/y/rotation are LOCAL to the parent). A bone points along its local +x.\n E.g. an upright torso: add_bone {name:\"torso\", y:100, rotation:90, length:120}.\n Children of a rotated parent use the parent's frame: a head on top of that torso is add_bone {name:\"head\", parent:\"torso\", x:120}.\n3. Visuals: add_slot {bone} then add_shape (no art needed) or import_image + add_region / add_mesh.\n Art prep: process_image {input, out, ops:[...], importAs | replace} keys out flat backgrounds (keyColor), cuts an object\n out by comparing with a painted-out copy (differenceMatte), trims, crops, resizes, flips and feathers edges; its \"box\"\n says where the result sat in the input picture, so a layer cut from a full scene can be placed exactly where it was.\n Attachments are positioned in the slot BONE's local frame (x along the bone).\n Draw order = slot order (first is back). Use update_slot {index} to reorder.\n4. Deformation: add_mesh {cols, rows} (or trace_mesh on a region) then auto_weights {bones:[...]} so the mesh bends with bones.\n trace_mesh on a mesh re-traces it in place and rebinds the same bones (tolerance 1\u20132 for detailed edges such as feet).\n set_weights_in_area {slot, attachment, area:{yMax:...} | polygon, influences, blend} pins every vertex in an area\n to bones (e.g. everything below the knees to the legs bone) without listing vertex indices.\n5. Constraints (solved every frame in one list; default order IK, transform, path, physics \u2014 set_constraint_order\n {constraints:[every constraint, first applied first]} changes it, [] restores the default):\n add_ik_constraint {bones:[\"thigh\",\"shin\"], target:\"foot-target\"} (target must not be a child of the chain);\n optional softness (2-bone), stretch, compress (1-bone).\n add_transform_constraint {bones, target, mixRotate, mixTranslate, mixScale, mixShear, local?, relative?}.\n Path: add_path {slot, anchors:[x0,y0,x1,y1,...]} (smooth bezier in the slot bone's frame; bind it to control bones\n with auto_weights or set_weights so moving them bends it), then add_path_constraint {bones:[parent..child], target:slot,\n positionMode:\"fixed\"|\"percent\", spacingMode:\"length\"|\"fixed\"|\"percent\"|\"proportional\", rotateMode:\"tangent\"|\"chain\"|\"chainScale\"}.\n Physics: add_physics_constraint {bone, inertia, strength, damping, mass, gravity, wind, mix} per bone (parent first)\n for hair/cloth/tails. It simulates over time, so check it with render_gif rather than a single frame.\n Physics gravity/wind and IK softness scale with the skeleton's size relative to set_document {referenceScale} (default 100 %).\n6. Animate: create_animation {name}, then set_keys with absolute values:\n set_keys {animation:\"walk\", target:\"bone\", id:\"thigh\", property:\"rotation\", keys:[{time:0,value:-20},{time:0.5,value:20,curve:\"easeInOut\"},{time:1,value:-20}]}\n Properties: bone rotation|x|y|scaleX|scaleY|shearX|shearY|inherit (stepped string: normal|onlyTranslation|noRotation|noScale), slot color (\"#rrggbbaa\") | dark (two-colour tint \"#rrggbb\") | attachment (name or null),\n ik mix|softness, transform mix|mixRotate|mixTranslate|mixScale|mixShear, path position|spacing|mixRotate|mixX|mixY,\n physics mix|inertia|strength|damping|mass|gravity|wind, deform offsets (mesh or path), sequence frame (with attachment), drawOrder. Curves: linear, stepped, easeIn, easeOut, easeInOut, backOut or [cx1,cy1,cx2,cy2].\n set_keys merges into the timeline; pass replace:true to set the whole timeline (e.g. when redoing a motion path).\n Loop cleanly by making the last key equal the first. add_event_key fires events (footsteps, sounds).\n7. Interactivity (Rive-style): create_state_machine \u2192 add_input (bool/number/trigger) \u2192 add_state {animation}\n (first state = entry) \u2192 add_transition {from, to, conditions:[{input, op, value}], duration, exitTime}.\n Transition with no conditions waits for the source animation to finish (exitTime 1).\n from:\"@any\" fires from any state. blend1d states blend animations by a number input.\n Pointer: add_bounding_box on a slot, then add_listener {slot, event:\"click\"|\"down\"|\"up\"|\"enter\"|\"exit\"|\"move\", actions:[...]}.\n Staged flows: add_state {..., loop:false, onComplete:\"next\"} plays once then moves on (its own transitions can still interrupt).\n Live data: add_input {type:\"string\"} or number inputs; add_text {slot, text:\"{multiplier:0.00}x\", size, weight, color, outline}\n shows inputs (number patterns: 0.00, #,##0, +0, 0%); add_binding {input, target:\"bone\"|\"slot\"|\"ik\"|..., object, property,\n inMin, inMax, outMin, outMax} drives a property from a number input every frame (slot color takes hex outMin/outMax).\n simulate_state_machine / render_frame steps accept setInputs with strings too.\n Scripts: add_script {code} + attach_script. Script API (global ob): ob.input(n), ob.setInput(n,v), ob.fire(n),\n ob.emit(event,{int,float,string}), ob.bone(n), ob.setBone(n,{rotation,...}) (per-frame override), ob.slot(n,{color,attachment}),\n ob.pointer(), ob.time(), ob.log(...). Hooks: onStart(), onUpdate(dt), onEvent(e), onPointer(p), or named fns for runScript actions.\n8. Particles: add_particles {slot, preset:\"fire\"|\"smoke\"|\"sparks\"|\"confetti\"|\"exhaust\"|\"coins\", ...overrides} emits from the\n slot bone (rotation = emission direction in the bone's frame, e.g. -90 for exhaust under an upright rocket bone; space\n \"world\" leaves trails). update_particles changes settings. Key it with set_keys {target:\"particles\", id:slot,\n property:\"emitting\" (true/false) | \"rate\"}. State machines: set_state_emitter {state, slot, emitting} and listener actions\n {type:\"setEmitter\", slot, emitting} / {type:\"emitParticles\", slot, count}. Seeded and deterministic; check with render_gif.\n9. Skins (outfits): the first skin is the default skin, shared by all. add_skin {name}, then either pass skin:\"<name>\" to\n add_shape/add_region/... or copy_attachment {slot, attachment, toSkin} and update_attachment {..., skin} to override a\n default attachment under the same name. rename_skin, duplicate_skin, delete_skin manage them; render_frame {skin} previews one.\n Skin bones/constraints: add_to_skin {skin, bones?, constraints?} makes them skin-only (active only while a skin listing\n them is set; inactive bones and their children aren't posed and their slots aren't drawn); remove_from_skin undoes it.\n10. Audio: import_audio {path} (or add_audio {name, src:data:/path, duration}) creates an asset and a same-named sound on the\n sfx bus. Play it with add_audio_key {animation, sound, time, volume?, rate?, loop?}, set_event_sound {event, sound} (plays\n whenever the event fires), set_state_sound {stateMachine, state, sound, on:\"enter\"|\"exit\", action:\"play\"|\"stop\"} or a\n listener action {type:\"playSound\", sound} / {type:\"stopSound\", sound, fade?}. Mute buttons: listener action\n {type:\"setMute\", bus:\"music\"|\"sfx\"|... (null = everything), muted:true|false|\"toggle\"} (pair it with toggleInput on a bool\n input and a slot color binding to show the state). Looping sounds stop when their state or\n animation ends. Mix with update_sound {volume, rate, loop, fadeIn, fadeOut, bus}, add_bus/update_bus {volume, muted},\n set_audio_mix {master, muted}. simulate_state_machine lists the audio commands.\n11. Sprite sequences (frame-by-frame, e.g. fire or explosions): add_image for each frame (or one sheet image), then\n add_sequence {slot, frames:[\"fire_0001\",\"fire_0002\",...], fps, mode:\"loop\"|\"once\"|\"pingPong\"|\"holdLast\", offset}\n or add_sequence {slot, grid:{image:\"sheet\", cols, rows}}. Bind input (a number input) to pick the frame from a state\n machine, or set_keys target:\"sequence\" {id:slot, attachment, property:\"frame\"}. set_sequence_frames replaces/reorders frames.\n12. Check your work: render_frame (returns a PNG; bones are drawn as blue wedges) and simulate_state_machine (text log of\n state changes/events). render_gif for motion. get_summary for an outline, validate for problems.\n\nTips: keep bones' length meaningful (used by IK and auto weights). Use update_* tools to fix mistakes, undo to revert.\n";
package/dist/guide.js ADDED
@@ -0,0 +1,81 @@
1
+ export const GUIDE = `# OpenBone authoring guide (for agents)
2
+
3
+ Coordinate system: skeleton space is y-UP, rotations in degrees counter-clockwise. The skeleton origin (0,0)
4
+ sits at (originX, originY) pixels in the artboard (artboard pixels are y-down). Default artboard 800x600,
5
+ origin (400,450) — so y=0 is near the bottom, positive y goes up.
6
+
7
+ Everything can be referenced by **name or id**. Every edit tool validates its input and returns ids.
8
+
9
+ ## Typical workflow
10
+ 1. new_project {name, path} (autosaves to path) — or open_project.
11
+ 2. Rig: add_bone (parent defaults to root; x/y/rotation are LOCAL to the parent). A bone points along its local +x.
12
+ E.g. an upright torso: add_bone {name:"torso", y:100, rotation:90, length:120}.
13
+ Children of a rotated parent use the parent's frame: a head on top of that torso is add_bone {name:"head", parent:"torso", x:120}.
14
+ 3. Visuals: add_slot {bone} then add_shape (no art needed) or import_image + add_region / add_mesh.
15
+ Art prep: process_image {input, out, ops:[...], importAs | replace} keys out flat backgrounds (keyColor), cuts an object
16
+ out by comparing with a painted-out copy (differenceMatte), trims, crops, resizes, flips and feathers edges; its "box"
17
+ says where the result sat in the input picture, so a layer cut from a full scene can be placed exactly where it was.
18
+ Attachments are positioned in the slot BONE's local frame (x along the bone).
19
+ Draw order = slot order (first is back). Use update_slot {index} to reorder.
20
+ 4. Deformation: add_mesh {cols, rows} (or trace_mesh on a region) then auto_weights {bones:[...]} so the mesh bends with bones.
21
+ trace_mesh on a mesh re-traces it in place and rebinds the same bones (tolerance 1–2 for detailed edges such as feet).
22
+ set_weights_in_area {slot, attachment, area:{yMax:...} | polygon, influences, blend} pins every vertex in an area
23
+ to bones (e.g. everything below the knees to the legs bone) without listing vertex indices.
24
+ 5. Constraints (solved every frame in one list; default order IK, transform, path, physics — set_constraint_order
25
+ {constraints:[every constraint, first applied first]} changes it, [] restores the default):
26
+ add_ik_constraint {bones:["thigh","shin"], target:"foot-target"} (target must not be a child of the chain);
27
+ optional softness (2-bone), stretch, compress (1-bone).
28
+ add_transform_constraint {bones, target, mixRotate, mixTranslate, mixScale, mixShear, local?, relative?}.
29
+ Path: add_path {slot, anchors:[x0,y0,x1,y1,...]} (smooth bezier in the slot bone's frame; bind it to control bones
30
+ with auto_weights or set_weights so moving them bends it), then add_path_constraint {bones:[parent..child], target:slot,
31
+ positionMode:"fixed"|"percent", spacingMode:"length"|"fixed"|"percent"|"proportional", rotateMode:"tangent"|"chain"|"chainScale"}.
32
+ Physics: add_physics_constraint {bone, inertia, strength, damping, mass, gravity, wind, mix} per bone (parent first)
33
+ for hair/cloth/tails. It simulates over time, so check it with render_gif rather than a single frame.
34
+ Physics gravity/wind and IK softness scale with the skeleton's size relative to set_document {referenceScale} (default 100 %).
35
+ 6. Animate: create_animation {name}, then set_keys with absolute values:
36
+ set_keys {animation:"walk", target:"bone", id:"thigh", property:"rotation", keys:[{time:0,value:-20},{time:0.5,value:20,curve:"easeInOut"},{time:1,value:-20}]}
37
+ Properties: bone rotation|x|y|scaleX|scaleY|shearX|shearY|inherit (stepped string: normal|onlyTranslation|noRotation|noScale), slot color ("#rrggbbaa") | dark (two-colour tint "#rrggbb") | attachment (name or null),
38
+ ik mix|softness, transform mix|mixRotate|mixTranslate|mixScale|mixShear, path position|spacing|mixRotate|mixX|mixY,
39
+ physics mix|inertia|strength|damping|mass|gravity|wind, deform offsets (mesh or path), sequence frame (with attachment), drawOrder. Curves: linear, stepped, easeIn, easeOut, easeInOut, backOut or [cx1,cy1,cx2,cy2].
40
+ set_keys merges into the timeline; pass replace:true to set the whole timeline (e.g. when redoing a motion path).
41
+ Loop cleanly by making the last key equal the first. add_event_key fires events (footsteps, sounds).
42
+ 7. Interactivity (Rive-style): create_state_machine → add_input (bool/number/trigger) → add_state {animation}
43
+ (first state = entry) → add_transition {from, to, conditions:[{input, op, value}], duration, exitTime}.
44
+ Transition with no conditions waits for the source animation to finish (exitTime 1).
45
+ from:"@any" fires from any state. blend1d states blend animations by a number input.
46
+ Pointer: add_bounding_box on a slot, then add_listener {slot, event:"click"|"down"|"up"|"enter"|"exit"|"move", actions:[...]}.
47
+ Staged flows: add_state {..., loop:false, onComplete:"next"} plays once then moves on (its own transitions can still interrupt).
48
+ Live data: add_input {type:"string"} or number inputs; add_text {slot, text:"{multiplier:0.00}x", size, weight, color, outline}
49
+ shows inputs (number patterns: 0.00, #,##0, +0, 0%); add_binding {input, target:"bone"|"slot"|"ik"|..., object, property,
50
+ inMin, inMax, outMin, outMax} drives a property from a number input every frame (slot color takes hex outMin/outMax).
51
+ simulate_state_machine / render_frame steps accept setInputs with strings too.
52
+ Scripts: add_script {code} + attach_script. Script API (global ob): ob.input(n), ob.setInput(n,v), ob.fire(n),
53
+ ob.emit(event,{int,float,string}), ob.bone(n), ob.setBone(n,{rotation,...}) (per-frame override), ob.slot(n,{color,attachment}),
54
+ ob.pointer(), ob.time(), ob.log(...). Hooks: onStart(), onUpdate(dt), onEvent(e), onPointer(p), or named fns for runScript actions.
55
+ 8. Particles: add_particles {slot, preset:"fire"|"smoke"|"sparks"|"confetti"|"exhaust"|"coins", ...overrides} emits from the
56
+ slot bone (rotation = emission direction in the bone's frame, e.g. -90 for exhaust under an upright rocket bone; space
57
+ "world" leaves trails). update_particles changes settings. Key it with set_keys {target:"particles", id:slot,
58
+ property:"emitting" (true/false) | "rate"}. State machines: set_state_emitter {state, slot, emitting} and listener actions
59
+ {type:"setEmitter", slot, emitting} / {type:"emitParticles", slot, count}. Seeded and deterministic; check with render_gif.
60
+ 9. Skins (outfits): the first skin is the default skin, shared by all. add_skin {name}, then either pass skin:"<name>" to
61
+ add_shape/add_region/... or copy_attachment {slot, attachment, toSkin} and update_attachment {..., skin} to override a
62
+ default attachment under the same name. rename_skin, duplicate_skin, delete_skin manage them; render_frame {skin} previews one.
63
+ Skin bones/constraints: add_to_skin {skin, bones?, constraints?} makes them skin-only (active only while a skin listing
64
+ them is set; inactive bones and their children aren't posed and their slots aren't drawn); remove_from_skin undoes it.
65
+ 10. Audio: import_audio {path} (or add_audio {name, src:data:/path, duration}) creates an asset and a same-named sound on the
66
+ sfx bus. Play it with add_audio_key {animation, sound, time, volume?, rate?, loop?}, set_event_sound {event, sound} (plays
67
+ whenever the event fires), set_state_sound {stateMachine, state, sound, on:"enter"|"exit", action:"play"|"stop"} or a
68
+ listener action {type:"playSound", sound} / {type:"stopSound", sound, fade?}. Mute buttons: listener action
69
+ {type:"setMute", bus:"music"|"sfx"|... (null = everything), muted:true|false|"toggle"} (pair it with toggleInput on a bool
70
+ input and a slot color binding to show the state). Looping sounds stop when their state or
71
+ animation ends. Mix with update_sound {volume, rate, loop, fadeIn, fadeOut, bus}, add_bus/update_bus {volume, muted},
72
+ set_audio_mix {master, muted}. simulate_state_machine lists the audio commands.
73
+ 11. Sprite sequences (frame-by-frame, e.g. fire or explosions): add_image for each frame (or one sheet image), then
74
+ add_sequence {slot, frames:["fire_0001","fire_0002",...], fps, mode:"loop"|"once"|"pingPong"|"holdLast", offset}
75
+ or add_sequence {slot, grid:{image:"sheet", cols, rows}}. Bind input (a number input) to pick the frame from a state
76
+ machine, or set_keys target:"sequence" {id:slot, attachment, property:"frame"}. set_sequence_frames replaces/reorders frames.
77
+ 12. Check your work: render_frame (returns a PNG; bones are drawn as blue wedges) and simulate_state_machine (text log of
78
+ state changes/events). render_gif for motion. get_summary for an outline, validate for problems.
79
+
80
+ Tips: keep bones' length meaningful (used by IK and auto weights). Use update_* tools to fix mistakes, undo to revert.
81
+ `;
@@ -0,0 +1,9 @@
1
+ import { type Image } from "@napi-rs/canvas";
2
+ /**
3
+ * A PNG without its metadata chunks. Generated art often carries large ones (C2PA "caBX" content credentials, XMP)
4
+ * before the pixel data, and @napi-rs/canvas then fails to recognise the buffer ("Invalid SVG image"). Returns the
5
+ * input unchanged when it is not a PNG or has nothing to drop.
6
+ */
7
+ export declare function stripPngMetadata(buf: Buffer): Buffer;
8
+ /** loadImage for image bytes, a data: URI, a URL or a path, robust to PNG metadata chunks. */
9
+ export declare function decodeImage(src: Buffer | string): Promise<Image>;
@@ -0,0 +1,40 @@
1
+ import { loadImage } from "@napi-rs/canvas";
2
+ const SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
3
+ /** PNG chunks that affect how pixels decode; everything else (text, EXIF, C2PA content credentials…) is dropped. */
4
+ const KEEP = new Set(["IHDR", "PLTE", "IDAT", "IEND", "tRNS", "gAMA", "cHRM", "sRGB", "iCCP", "sBIT", "pHYs", "acTL", "fcTL", "fdAT"]);
5
+ /**
6
+ * A PNG without its metadata chunks. Generated art often carries large ones (C2PA "caBX" content credentials, XMP)
7
+ * before the pixel data, and @napi-rs/canvas then fails to recognise the buffer ("Invalid SVG image"). Returns the
8
+ * input unchanged when it is not a PNG or has nothing to drop.
9
+ */
10
+ export function stripPngMetadata(buf) {
11
+ if (buf.length < 8 || SIG.some((b, i) => buf[i] !== b))
12
+ return buf;
13
+ const parts = [buf.subarray(0, 8)];
14
+ let dropped = false;
15
+ for (let p = 8; p + 12 <= buf.length;) {
16
+ const len = buf.readUInt32BE(p);
17
+ const type = buf.toString("latin1", p + 4, p + 8);
18
+ const end = p + 12 + len;
19
+ if (end > buf.length)
20
+ return buf; // truncated: leave it to the decoder
21
+ if (KEEP.has(type))
22
+ parts.push(buf.subarray(p, end));
23
+ else
24
+ dropped = true;
25
+ p = end;
26
+ if (type === "IEND")
27
+ break;
28
+ }
29
+ return dropped ? Buffer.concat(parts) : buf;
30
+ }
31
+ /** loadImage for image bytes, a data: URI, a URL or a path, robust to PNG metadata chunks. */
32
+ export async function decodeImage(src) {
33
+ if (typeof src === "string") {
34
+ const m = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(src);
35
+ if (m?.[2])
36
+ return loadImage(stripPngMetadata(Buffer.from(m[3], "base64")));
37
+ return loadImage(src);
38
+ }
39
+ return loadImage(stripPngMetadata(src));
40
+ }