@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/render.js ADDED
@@ -0,0 +1,224 @@
1
+ import { createCanvas } from "@napi-rs/canvas";
2
+ import { decodeImage } from "./image-load.js";
3
+ import { textureAssets } from "@openbone/core";
4
+ import { encodePng } from "@openbone/export";
5
+ import { CanvasRenderer, buildAtlas, buildAtlasScales } from "@openbone/render-canvas";
6
+ import { OpenBoneInstance } from "@openbone/runtime";
7
+ // @ts-expect-error gifenc ships without types (CommonJS)
8
+ import * as gifenc from "gifenc";
9
+ // Node loads the CommonJS build (the functions sit on `default`); bundlers such as Vite and Vitest load the ESM build
10
+ // (the functions are named exports, and `default` is the encoder alone). Take them from whichever has them.
11
+ const gifNs = gifenc;
12
+ const { GIFEncoder, applyPalette, quantize } = (typeof gifNs.GIFEncoder === "function" ? gifNs : gifNs.default);
13
+ export async function loadImages(session, doc) {
14
+ const map = new Map();
15
+ // Atlas pages and loose images, keyed by id (the renderers ask for page ids when images are packed).
16
+ for (const img of textureAssets(doc)) {
17
+ try {
18
+ map.set(img.id, await decodeImage(await session.readImageSrc(img.src)));
19
+ }
20
+ catch {
21
+ /* missing images render as placeholders */
22
+ }
23
+ }
24
+ return map;
25
+ }
26
+ export function useSkin(inst, skin) {
27
+ if (!skin)
28
+ return;
29
+ inst.skeleton.setSkin(skin);
30
+ if (!inst.skeleton.skin)
31
+ throw new Error(`Skin "${skin}" not found. Available: ${inst.doc.skeleton.skins.map((k) => k.name).join(", ")}`);
32
+ }
33
+ /** Build a posed instance for the request. Returns logs from state machine simulation. */
34
+ export function pose(doc, req, scriptHost) {
35
+ const inst = new OpenBoneInstance(doc, { scriptHost });
36
+ useSkin(inst, req.skin);
37
+ const log = [];
38
+ if (req.stateMachine !== undefined || req.steps?.length) {
39
+ const sm = inst.useStateMachine(req.stateMachine || undefined);
40
+ sm.on("stateChange", (e) => log.push(`t=${t.toFixed(3)} [${e.layer}] ${e.from ?? "∅"} → ${e.to}`));
41
+ sm.on("event", (e) => log.push(`t=${t.toFixed(3)} event ${e.name}${e.animation ? ` (from ${e.animation})` : ""} int=${e.int} float=${e.float}${e.string ? ` "${e.string}"` : ""}`));
42
+ sm.on("inputChange", (e) => log.push(`t=${t.toFixed(3)} input ${e.name} = ${e.value}`));
43
+ sm.on("log", (a) => log.push(`t=${t.toFixed(3)} script: ${a.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join(" ")}`));
44
+ sm.on("error", (e) => log.push(`t=${t.toFixed(3)} ERROR ${e.message}`));
45
+ const soundName = (id) => doc.audio?.sounds.find((x) => x.id === id)?.name ?? id;
46
+ sm.on("audio", (c) => log.push(`t=${t.toFixed(3)} audio ${c.type === "play" ? `play ${soundName(c.sound)} [${c.id}]${c.loop ? " loop" : ""} vol ${c.volume} (${c.source})` : c.type === "stop" ? `stop [${c.id}]${c.fade ? ` fade ${c.fade}s` : ""}` : c.type === "fade" ? `fade [${c.id}] → ${c.volume}` : `${c.muted ? "mute" : "unmute"} ${c.bus === null ? "master" : (doc.audio?.buses.find((b) => b.id === c.bus)?.name ?? c.bus)}`}`));
47
+ let t = 0;
48
+ sm.advance(0);
49
+ for (const s of req.steps ?? [{ advance: req.time ?? 0 }]) {
50
+ for (const [k, v] of Object.entries(s.setInputs ?? {}))
51
+ sm.setInput(k, v);
52
+ for (const f of s.fire ?? [])
53
+ sm.fire(f);
54
+ if (s.pointer) {
55
+ const [x, y] = inst.artboardToSkeleton(s.pointer.x, s.pointer.y);
56
+ sm.pointer(s.pointer.type, x, y);
57
+ }
58
+ const dt = s.advance ?? 1 / 30;
59
+ // Advance in small steps so transitions/events resolve like real playback.
60
+ let rem = dt;
61
+ sm.advance(0);
62
+ while (rem > 1e-9) {
63
+ const h = Math.min(rem, 1 / 60);
64
+ sm.advance(h);
65
+ t += h;
66
+ rem -= h;
67
+ }
68
+ }
69
+ log.push(`final states: ${JSON.stringify(sm.activeStates)}; inputs: ${JSON.stringify(Object.fromEntries([...sm.inputs].map(([id, v]) => [sm.data.inputs.find((i) => i.id === id)?.name ?? id, v])))}`);
70
+ }
71
+ else if (req.animation) {
72
+ inst.animationState.setAnimation(0, req.animation, true, 0);
73
+ // Step at 60 Hz so physics constraints are simulated up to the requested time.
74
+ inst.advance(0);
75
+ let rem = req.time ?? 0;
76
+ while (rem > 1e-9) {
77
+ const h = Math.min(rem, 1 / 60);
78
+ inst.advance(h);
79
+ rem -= h;
80
+ }
81
+ }
82
+ else {
83
+ inst.skeleton.updateWorldTransform();
84
+ }
85
+ return { inst, log };
86
+ }
87
+ export async function renderPng(session, req, scriptHost) {
88
+ const doc = session.doc;
89
+ const images = await loadImages(session, doc);
90
+ const { inst, log } = pose(doc, req, scriptHost);
91
+ const scale = req.scale ?? 1;
92
+ const canvas = createCanvas(Math.max(1, Math.round(doc.width * scale)), Math.max(1, Math.round(doc.height * scale)));
93
+ const ctx = canvas.getContext("2d");
94
+ const r = new CanvasRenderer(ctx, (id) => images.get(id));
95
+ r.render(inst.skeleton, {
96
+ view: { x: 0, y: 0, zoom: scale },
97
+ bones: req.showBones ?? true,
98
+ boundingBoxes: req.showBoundingBoxes ?? true,
99
+ wireframe: req.wireframe ?? false,
100
+ background: req.background === undefined ? (doc.background ?? "#f4f4f6") : req.background,
101
+ });
102
+ return { png: canvas.toBuffer("image/png"), log };
103
+ }
104
+ /**
105
+ * Largest GIF returned inline by render_gif. A tool result travels as one JSON-RPC message (the image as base64, a
106
+ * third bigger), and MCP clients drop the connection on very large messages: a 14 MB GIF (19 MB of base64) did. Bigger
107
+ * GIFs are still saved to disk; the result then carries a contact sheet of a few frames instead.
108
+ */
109
+ export const MAX_INLINE_GIF = 4 * 1024 * 1024;
110
+ /** A grid of evenly spaced frames, for a preview of a long render. */
111
+ export function contactSheet(frameW, frameH, count, cols = 3, rows = 2) {
112
+ const n = cols * rows;
113
+ const tw = Math.min(frameW, 480);
114
+ const th = Math.round((frameH * tw) / frameW);
115
+ const sheet = createCanvas(cols * tw, rows * th);
116
+ const sctx = sheet.getContext("2d");
117
+ const picks = Array.from({ length: n }, (_, i) => Math.round((i * (count - 1)) / Math.max(1, n - 1)));
118
+ return {
119
+ add(canvas, index) {
120
+ const k = picks.indexOf(index);
121
+ if (k >= 0)
122
+ sctx.drawImage(canvas, (k % cols) * tw, Math.floor(k / cols) * th, tw, th);
123
+ },
124
+ png: () => sheet.toBuffer("image/png"),
125
+ picks,
126
+ };
127
+ }
128
+ export async function renderGif(session, req, scriptHost,
129
+ /** Called with each rendered frame (e.g. to build a preview); the canvas is reused, so copy what you need. */
130
+ onFrame) {
131
+ const doc = session.doc;
132
+ const images = await loadImages(session, doc);
133
+ const scale = req.scale ?? 0.5;
134
+ const w = Math.max(1, Math.round(doc.width * scale));
135
+ const h = Math.max(1, Math.round(doc.height * scale));
136
+ const canvas = createCanvas(w, h);
137
+ const ctx = canvas.getContext("2d");
138
+ const renderer = new CanvasRenderer(ctx, (id) => images.get(id));
139
+ const inst = new OpenBoneInstance(doc, { scriptHost });
140
+ useSkin(inst, req.skin);
141
+ const sm = req.stateMachine !== undefined || req.steps ? inst.useStateMachine(req.stateMachine || undefined) : null;
142
+ if (!sm) {
143
+ if (!req.animation)
144
+ throw new Error("Give animation or stateMachine");
145
+ inst.animationState.setAnimation(0, req.animation, true, 0);
146
+ }
147
+ const gif = GIFEncoder();
148
+ const frames = Math.max(1, Math.round(req.duration * req.fps));
149
+ const dt = 1 / req.fps;
150
+ // Steps (state machine) are scheduled by cumulative time.
151
+ const schedule = [];
152
+ let acc = 0;
153
+ for (const s of req.steps ?? []) {
154
+ schedule.push({ at: acc, step: s });
155
+ acc += s.advance ?? 0;
156
+ }
157
+ let t = 0;
158
+ for (let f = 0; f < frames; f++) {
159
+ if (sm)
160
+ while (schedule.length && schedule[0].at <= t + 1e-9) {
161
+ const { step } = schedule.shift();
162
+ for (const [k, v] of Object.entries(step.setInputs ?? {}))
163
+ sm.setInput(k, v);
164
+ for (const n of step.fire ?? [])
165
+ sm.fire(n);
166
+ if (step.pointer) {
167
+ const [x, y] = inst.artboardToSkeleton(step.pointer.x, step.pointer.y);
168
+ sm.pointer(step.pointer.type, x, y);
169
+ }
170
+ }
171
+ inst.advance(f === 0 ? 0 : dt);
172
+ t += f === 0 ? 0 : dt;
173
+ renderer.render(inst.skeleton, {
174
+ view: { x: 0, y: 0, zoom: scale },
175
+ bones: req.showBones ?? false,
176
+ background: doc.background ?? "#ffffff",
177
+ });
178
+ onFrame?.(canvas, f, frames);
179
+ const { data } = ctx.getImageData(0, 0, w, h);
180
+ const palette = quantize(data, 256);
181
+ gif.writeFrame(applyPalette(data, palette), w, h, { palette, delay: Math.round(1000 / req.fps) });
182
+ }
183
+ gif.finish();
184
+ return Buffer.from(gif.bytes());
185
+ }
186
+ /**
187
+ * Lay out every image of `doc` on atlas pages and compose the page PNGs (as data: URIs), with the same code the
188
+ * editor uses (`buildAtlas`). Images that already live only in an atlas are cut back out of their page. The result
189
+ * is ready for the `setAtlas` op.
190
+ */
191
+ export async function packAtlas(session, doc, opts = {}) {
192
+ return (await buildAtlas(doc, opts, atlasEnv(session))).atlas;
193
+ }
194
+ /** `packAtlas` with the scale used and any warnings (e.g. JPEG pages losing transparency). */
195
+ export async function packAtlasFull(session, doc, opts = {}) {
196
+ return buildAtlas(doc, opts, atlasEnv(session));
197
+ }
198
+ /** One atlas per scale variant (multi-scale packs), images loaded once. */
199
+ export async function packAtlasScales(session, doc, opts, variants) {
200
+ return buildAtlasScales(doc, opts, variants, atlasEnv(session));
201
+ }
202
+ /** Canvases, image loading and PNG / JPEG encoding for the atlas packer, in Node (@napi-rs/canvas). */
203
+ export function atlasEnv(session) {
204
+ return {
205
+ createCanvas: (w, h) => createCanvas(w, h),
206
+ load: async (src, name) => {
207
+ try {
208
+ return (await decodeImage(await session.readImageSrc(src)));
209
+ }
210
+ catch {
211
+ throw new Error(`Could not load image "${name}" (${src.slice(0, 60)})`);
212
+ }
213
+ },
214
+ encodePng: (data, width, height) => encodePng({ width, height, data }),
215
+ encodeJpeg: async (data, width, height, quality) => {
216
+ const c = createCanvas(width, height);
217
+ const g = c.getContext("2d");
218
+ const id = g.createImageData(width, height);
219
+ id.data.set(data);
220
+ g.putImageData(id, 0, 0);
221
+ return new Uint8Array(c.toBuffer("image/jpeg", quality));
222
+ },
223
+ };
224
+ }
@@ -0,0 +1,28 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import type { ScriptHost } from "@openbone/runtime";
3
+ import { z } from "zod";
4
+ import { ProjectSession } from "./session.js";
5
+ export declare const snake: (s: string) => string;
6
+ export declare const stepSchema: z.ZodObject<{
7
+ advance: z.ZodOptional<z.ZodNumber>;
8
+ setInputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString]>>>;
9
+ fire: z.ZodOptional<z.ZodArray<z.ZodString>>;
10
+ pointer: z.ZodOptional<z.ZodObject<{
11
+ type: z.ZodEnum<{
12
+ down: "down";
13
+ up: "up";
14
+ move: "move";
15
+ }>;
16
+ x: z.ZodNumber;
17
+ y: z.ZodNumber;
18
+ }, z.core.$strip>>;
19
+ }, z.core.$strip>;
20
+ export interface ServerOptions {
21
+ session?: ProjectSession;
22
+ scriptHost?: ScriptHost;
23
+ }
24
+ export declare function createServer(opts?: ServerOptions): {
25
+ server: McpServer;
26
+ session: ProjectSession;
27
+ };
28
+ /** Seconds of PCM audio in a WAV file (0 for other formats or unreadable headers). */
package/dist/server.js ADDED
@@ -0,0 +1,354 @@
1
+ import { existsSync } from "node:fs";
2
+ import { decodeImage } from "./image-load.js";
3
+ import { readFile } from "node:fs/promises";
4
+ import path from "node:path";
5
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6
+ import { isTrimmed, registry, serialize, summarize, validate } from "@openbone/core";
7
+ import { createQuickJsHost } from "@openbone/scripting";
8
+ import { z } from "zod";
9
+ import { GUIDE } from "./guide.js";
10
+ import { atlasBuildOptions } from "@openbone/render-canvas";
11
+ import { atlasSettingsShape } from "./atlas-schema.js";
12
+ import { audioDuration } from "./audio-meta.js";
13
+ import { MAX_INLINE_GIF, contactSheet, packAtlasFull, pose, renderGif, renderPng } from "./render.js";
14
+ import { ProjectSession } from "./session.js";
15
+ import { registerExtraTools } from "./tools-extra.js";
16
+ import { registerImageTools } from "./tools-image.js";
17
+ export const snake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
18
+ const text = (v) => ({ content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 1) }] });
19
+ const fail = (e) => ({ isError: true, content: [{ type: "text", text: `Error: ${e.message}` }] });
20
+ export const stepSchema = z.object({
21
+ advance: z.number().min(0).optional().describe("Seconds to advance after applying this step (default 1/30)"),
22
+ setInputs: z.record(z.string(), z.union([z.boolean(), z.number(), z.string()])).optional(),
23
+ fire: z.array(z.string()).optional().describe("Trigger inputs to fire"),
24
+ pointer: z
25
+ .object({ type: z.enum(["down", "up", "move"]), x: z.number(), y: z.number() })
26
+ .optional()
27
+ .describe("Pointer event in ARTBOARD pixels (y-down, top-left origin)"),
28
+ });
29
+ export function createServer(opts = {}) {
30
+ const session = opts.session ?? new ProjectSession();
31
+ let host = opts.scriptHost;
32
+ const scriptHost = async () => (host ??= await createQuickJsHost({ timeoutMs: 50 }));
33
+ const server = new McpServer({ name: "openbone", version: "0.3.0" }, {
34
+ instructions: "OpenBone: 2D skeletal animation + interactive state machines. Read the openbone://guide resource (or call get_guide) first. Start with new_project or open_project; edit with the add_*/update_*/set_keys tools; verify with render_frame and simulate_state_machine.",
35
+ });
36
+ // ---------- Generated edit tools (one per core op) ----------
37
+ for (const def of registry.values()) {
38
+ server.registerTool(snake(def.name), { title: def.name, description: `[${def.group}] ${def.description}`, inputSchema: def.schema.shape }, async (args) => {
39
+ try {
40
+ const result = session.store.apply(def.name, args);
41
+ await session.maybeAutosave();
42
+ return text({ ok: true, ...(result && typeof result === "object" ? result : { result }) });
43
+ }
44
+ catch (e) {
45
+ return fail(e);
46
+ }
47
+ });
48
+ }
49
+ // ---------- Project tools ----------
50
+ server.registerTool("new_project", {
51
+ description: "Start a new empty project (root bone only). With `path` (.obone), it is saved and autosaved after every edit. An existing file at `path` is never replaced unless `overwrite` is true: use open_project to edit it.",
52
+ inputSchema: {
53
+ name: z.string(),
54
+ path: z.string().optional(),
55
+ overwrite: z.boolean().default(false).describe("Replace an existing file at `path` (its contents are lost)"),
56
+ width: z.number().positive().default(800),
57
+ height: z.number().positive().default(600),
58
+ originX: z.number().optional(),
59
+ originY: z.number().optional(),
60
+ background: z.string().nullable().optional(),
61
+ },
62
+ }, async (a) => {
63
+ try {
64
+ if (a.path && !a.overwrite && existsSync(path.resolve(a.path)))
65
+ throw new Error(`${a.path} already exists: open it with open_project, or pass overwrite: true to replace it`);
66
+ session.newProject(a.name, a.path ?? null, {
67
+ width: a.width,
68
+ height: a.height,
69
+ originX: a.originX ?? a.width / 2,
70
+ originY: a.originY ?? a.height * 0.75,
71
+ background: a.background ?? null,
72
+ });
73
+ if (session.filePath)
74
+ await session.save();
75
+ return text({ ok: true, path: session.filePath, rootBone: session.doc.skeleton.bones[0].id });
76
+ }
77
+ catch (e) {
78
+ return fail(e);
79
+ }
80
+ });
81
+ server.registerTool("open_project", { description: "Open an .obone file.", inputSchema: { path: z.string() } }, async (a) => {
82
+ try {
83
+ await session.open(a.path);
84
+ return text(summarize(session.doc));
85
+ }
86
+ catch (e) {
87
+ return fail(e);
88
+ }
89
+ });
90
+ server.registerTool("save_project", { description: "Save the project (optionally to a new path).", inputSchema: { path: z.string().optional() } }, async (a) => {
91
+ try {
92
+ return text({ ok: true, path: await session.save(a.path) });
93
+ }
94
+ catch (e) {
95
+ return fail(e);
96
+ }
97
+ });
98
+ server.registerTool("get_guide", { description: "How to use OpenBone tools: coordinate system, workflow, examples." }, async () => text(GUIDE));
99
+ server.registerTool("get_summary", { description: "Readable outline of the open project: bones, slots, animations, state machines." }, async () => text(summarize(session.doc)));
100
+ server.registerTool("get_document", {
101
+ description: "Raw JSON of the open document or one section of it.",
102
+ inputSchema: { section: z.enum(["all", "skeleton", "animations", "stateMachines", "scripts", "events", "images"]).default("all") },
103
+ }, async (a) => {
104
+ const d = session.doc;
105
+ if (a.section === "all")
106
+ return text(serialize(d, false));
107
+ if (a.section === "images")
108
+ return text(d.images.map(({ src, ...rest }) => ({ ...rest, src: src.startsWith("data:") ? `${src.slice(0, 40)}…` : src })));
109
+ return text(JSON.stringify(d[a.section]));
110
+ });
111
+ server.registerTool("validate", { description: "Check the document for broken references and problems." }, async () => {
112
+ const issues = validate(session.doc);
113
+ return text(issues.length ? issues : "No issues found.");
114
+ });
115
+ server.registerTool("undo", { description: "Undo the last edit." }, async () => {
116
+ const ok = session.store.undo();
117
+ await session.maybeAutosave();
118
+ return text({ ok });
119
+ });
120
+ server.registerTool("redo", { description: "Redo the last undone edit." }, async () => {
121
+ const ok = session.store.redo();
122
+ await session.maybeAutosave();
123
+ return text({ ok });
124
+ });
125
+ server.registerTool("import_image", {
126
+ description: "Import a PNG/JPG/WebP from disk as an image asset (size detected). Stored as a path relative to the project file, or embedded when `embed` is true or the project is unsaved.",
127
+ inputSchema: { path: z.string(), name: z.string().optional(), embed: z.boolean().default(false) },
128
+ }, async (a) => {
129
+ try {
130
+ const abs = path.resolve(a.path);
131
+ const buf = await readFile(abs);
132
+ const img = await decodeImage(buf);
133
+ const ext = path.extname(abs).slice(1).toLowerCase().replace("jpg", "jpeg");
134
+ const src = a.embed || !session.filePath
135
+ ? `data:image/${ext};base64,${buf.toString("base64")}`
136
+ : path.relative(session.baseDir, abs).split(path.sep).join("/");
137
+ const result = session.store.apply("addImage", {
138
+ name: a.name ?? path.basename(abs, path.extname(abs)),
139
+ src,
140
+ width: img.width,
141
+ height: img.height,
142
+ });
143
+ await session.maybeAutosave();
144
+ return text({ ok: true, ...result, width: img.width, height: img.height });
145
+ }
146
+ catch (e) {
147
+ return fail(e);
148
+ }
149
+ });
150
+ server.registerTool("import_audio", {
151
+ description: "Import a WAV/MP3/OGG/FLAC file from disk (its duration is read from the file) as an audio asset plus a sound of the same name (on the sfx bus unless `bus` is given). Stored as a path relative to the project file, or embedded when `embed` is true or the project is unsaved. Then play it with add_audio_key, set_event_sound, set_state_sound or a playSound listener action.",
152
+ inputSchema: {
153
+ path: z.string(),
154
+ name: z.string().optional(),
155
+ embed: z.boolean().default(false),
156
+ bus: z.string().optional(),
157
+ loop: z.boolean().default(false),
158
+ },
159
+ }, async (a) => {
160
+ try {
161
+ const abs = path.resolve(a.path);
162
+ const buf = await readFile(abs);
163
+ const ext = path.extname(abs).slice(1).toLowerCase();
164
+ const mime = ext === "mp3" ? "audio/mpeg" : ext === "wav" ? "audio/wav" : ext === "ogg" || ext === "oga" ? "audio/ogg" : `audio/${ext}`;
165
+ const src = a.embed || !session.filePath ? `data:${mime};base64,${buf.toString("base64")}` : path.relative(session.baseDir, abs).split(path.sep).join("/");
166
+ const duration = audioDuration(buf);
167
+ const result = session.store.apply("addAudio", {
168
+ name: a.name ?? path.basename(abs, path.extname(abs)),
169
+ src,
170
+ duration,
171
+ loop: a.loop,
172
+ ...(a.bus ? { bus: a.bus } : {}),
173
+ });
174
+ await session.maybeAutosave();
175
+ return text({ ok: true, ...result, duration });
176
+ }
177
+ catch (e) {
178
+ return fail(e);
179
+ }
180
+ });
181
+ server.registerTool("pack_atlas", {
182
+ description: "Pack every image into texture atlas pages (embedded PNGs, or JPEGs) and store them with set_atlas, so renderers draw packed images (and shapes) from one texture: fewer WebGL draw calls. Re-run after adding images. With stripImageSources the file carries only the pages. Identical images are stored once (alias) and blank ones take no space (ignoreBlank) by default; filterMin/filterMag/wrapX/wrapY/pixelFormat are written for runtimes; debug outlines every region.",
183
+ inputSchema: {
184
+ ...atlasSettingsShape,
185
+ stripImageSources: z.boolean().default(false),
186
+ },
187
+ }, async (a) => {
188
+ try {
189
+ if (!session.doc.images.length)
190
+ throw new Error("No images to pack");
191
+ const { stripImageSources, scales, ...settings } = a;
192
+ if (scales?.length)
193
+ throw new Error("pack_atlas stores one atlas in the project; use export_file with format atlas for several scales");
194
+ const { atlas, warnings } = await packAtlasFull(session, session.doc, atlasBuildOptions(settings));
195
+ session.store.apply("setAtlas", { atlas, stripImageSources });
196
+ await session.maybeAutosave();
197
+ const shared = atlas.regions.length - new Set(atlas.regions.map((r) => `${r.page}:${r.x},${r.y}`)).size;
198
+ return text({
199
+ ok: true,
200
+ pages: atlas.pages.map((p) => `${p.id} ${p.width}x${p.height}`),
201
+ regions: atlas.regions.length,
202
+ rotated: atlas.regions.filter((r) => r.rotated).length,
203
+ trimmed: atlas.regions.filter((r) => isTrimmed(r) && !r.empty).length,
204
+ polygons: atlas.regions.filter((r) => r.polygon).length,
205
+ aliased: Math.max(0, shared - Math.max(0, atlas.regions.filter((r) => r.empty).length - 1)),
206
+ blank: atlas.regions.filter((r) => r.empty).length,
207
+ premultipliedAlpha: !!atlas.premultipliedAlpha,
208
+ scale: atlas.scale ?? 1,
209
+ ...(warnings.length ? { warnings } : {}),
210
+ });
211
+ }
212
+ catch (e) {
213
+ return fail(e);
214
+ }
215
+ });
216
+ // ---------- Preview / verification ----------
217
+ server.registerTool("render_frame", {
218
+ description: "Render the artboard to a PNG you can look at. Setup pose by default; or an animation at `time`; or a state machine after `steps`. Bones are drawn as blue wedges, bounding boxes dashed orange, clipping masks dashed violet.",
219
+ inputSchema: {
220
+ animation: z.string().optional(),
221
+ time: z.number().min(0).optional(),
222
+ stateMachine: z.string().optional().describe("State machine name (empty string = first)"),
223
+ steps: z.array(stepSchema).optional(),
224
+ skin: z.string().optional().describe("Skin (outfit) name to show; default skin only when omitted"),
225
+ scale: z.number().positive().max(4).default(1),
226
+ showBones: z.boolean().default(true),
227
+ showBoundingBoxes: z.boolean().default(true),
228
+ wireframe: z.boolean().default(false),
229
+ },
230
+ }, async (a) => {
231
+ try {
232
+ const needsScripts = a.stateMachine !== undefined || !!a.steps;
233
+ const { png, log } = await renderPng(session, a, needsScripts ? await scriptHost() : null);
234
+ return {
235
+ content: [
236
+ { type: "image", data: png.toString("base64"), mimeType: "image/png" },
237
+ ...(log.length ? [{ type: "text", text: log.join("\n") }] : []),
238
+ ],
239
+ };
240
+ }
241
+ catch (e) {
242
+ return fail(e);
243
+ }
244
+ });
245
+ server.registerTool("render_gif", {
246
+ description: "Render an animated GIF of an animation or state machine run, saved to `out` (and returned as an image).",
247
+ inputSchema: {
248
+ animation: z.string().optional(),
249
+ stateMachine: z.string().optional(),
250
+ skin: z.string().optional().describe("Skin (outfit) name to show; default skin only when omitted"),
251
+ steps: z.array(stepSchema).optional().describe("State machine inputs over time (each step's advance is its duration)"),
252
+ duration: z.number().positive().max(20).default(2),
253
+ fps: z.number().int().min(1).max(60).default(20),
254
+ scale: z.number().positive().max(2).default(0.5),
255
+ showBones: z.boolean().default(false),
256
+ out: z.string().optional().describe("Output path (default next to the project)"),
257
+ },
258
+ }, async (a) => {
259
+ try {
260
+ let sheet;
261
+ const gif = await renderGif(session, a, await scriptHost(), (canvas, i, count) => {
262
+ sheet ??= contactSheet(canvas.width, canvas.height, count);
263
+ sheet.add(canvas, i);
264
+ });
265
+ const { writeFile } = await import("node:fs/promises");
266
+ const out = path.resolve(session.baseDir, a.out ?? `${(a.animation ?? a.stateMachine ?? "preview").replace(/\W+/g, "_")}.gif`);
267
+ await writeFile(out, gif);
268
+ const saved = `Saved ${out} (${(gif.length / 1024).toFixed(0)} KB)`;
269
+ if (gif.length <= MAX_INLINE_GIF || !sheet)
270
+ return { content: [{ type: "text", text: saved }, { type: "image", data: gif.toString("base64"), mimeType: "image/gif" }] };
271
+ const at = sheet.picks.map((f) => `${(f / a.fps).toFixed(2)}s`).join(", ");
272
+ return {
273
+ content: [
274
+ {
275
+ type: "text",
276
+ text: `${saved}. Too big to return inline (limit ${MAX_INLINE_GIF / 1048576} MB), so here are frames at ${at}, left to right, top to bottom. Lower fps, scale or duration for an inline GIF.`,
277
+ },
278
+ { type: "image", data: sheet.png().toString("base64"), mimeType: "image/png" },
279
+ ],
280
+ };
281
+ }
282
+ catch (e) {
283
+ return fail(e);
284
+ }
285
+ });
286
+ server.registerTool("simulate_state_machine", {
287
+ description: "Run a state machine headlessly through steps (set inputs, fire triggers, pointer events, advance time) and get a log of state changes, events, input changes, audio commands and script output. Use to test interactivity.",
288
+ inputSchema: { stateMachine: z.string().optional(), steps: z.array(stepSchema).min(1) },
289
+ }, async (a) => {
290
+ try {
291
+ const { log } = pose(session.doc, { stateMachine: a.stateMachine ?? "", steps: a.steps }, await scriptHost());
292
+ return text(log.join("\n"));
293
+ }
294
+ catch (e) {
295
+ return fail(e);
296
+ }
297
+ });
298
+ server.registerTool("inspect_pose", {
299
+ description: "World positions/rotations of bones (skeleton space, y-up) for the setup pose or an animation at a time.",
300
+ inputSchema: { animation: z.string().optional(), time: z.number().min(0).optional(), bones: z.array(z.string()).optional() },
301
+ }, async (a) => {
302
+ try {
303
+ const { inst } = pose(session.doc, { animation: a.animation, time: a.time });
304
+ const list = inst.skeleton.bones.filter((b) => !a.bones || a.bones.includes(b.data.name) || a.bones.includes(b.data.id));
305
+ const r = (n) => Math.round(n * 100) / 100;
306
+ return text(list.map((b) => ({
307
+ bone: b.data.name,
308
+ worldX: r(b.world.x),
309
+ worldY: r(b.world.y),
310
+ worldRotation: r(b.worldRotation),
311
+ local: { x: r(b.x), y: r(b.y), rotation: r(b.applied.rotation) },
312
+ })));
313
+ }
314
+ catch (e) {
315
+ return fail(e);
316
+ }
317
+ });
318
+ // ---------- Resources & prompts ----------
319
+ server.registerResource("guide", "openbone://guide", { mimeType: "text/markdown", description: "Agent authoring guide" }, async (uri) => ({
320
+ contents: [{ uri: uri.href, mimeType: "text/markdown", text: GUIDE }],
321
+ }));
322
+ server.registerResource("document", "openbone://document", { mimeType: "application/json", description: "The open document" }, async (uri) => ({
323
+ contents: [{ uri: uri.href, mimeType: "application/json", text: serialize(session.doc) }],
324
+ }));
325
+ server.registerResource("summary", "openbone://summary", { mimeType: "text/plain", description: "Outline of the open document" }, async (uri) => ({
326
+ contents: [{ uri: uri.href, mimeType: "text/plain", text: summarize(session.doc) }],
327
+ }));
328
+ registerExtraTools(server, session, scriptHost);
329
+ registerImageTools(server, session);
330
+ server.registerPrompt("rig_character", { description: "Rig and animate a character", argsSchema: { description: z.string(), path: z.string() } }, (a) => ({
331
+ messages: [
332
+ {
333
+ role: "user",
334
+ content: {
335
+ type: "text",
336
+ text: `Using the OpenBone tools, create a project at ${a.path} and build: ${a.description}.\nRead get_guide first. Build the bone hierarchy, add shapes or images, add IK for limbs, create idle and walk animations that loop cleanly, then a state machine with a 'speed' number input blending idle→walk. Check with render_frame after each major step.`,
337
+ },
338
+ },
339
+ ],
340
+ }));
341
+ server.registerPrompt("interactive_button", { description: "Build an interactive animated button", argsSchema: { label: z.string(), path: z.string() } }, (a) => ({
342
+ messages: [
343
+ {
344
+ role: "user",
345
+ content: {
346
+ type: "text",
347
+ text: `Using the OpenBone tools, create a project at ${a.path}: an animated "${a.label}" button with idle, hover and press states driven by pointer listeners on a bounding box, and a 'clicked' event reported on click. Verify with simulate_state_machine using pointer steps, then render_frame.`,
348
+ },
349
+ },
350
+ ],
351
+ }));
352
+ return { server, session };
353
+ }
354
+ /** Seconds of PCM audio in a WAV file (0 for other formats or unreadable headers). */
@@ -0,0 +1,16 @@
1
+ import { DocumentStore } from "@openbone/core";
2
+ import type { OpenBoneDocument } from "@openbone/core";
3
+ /** One open project: the store plus where it lives on disk. */
4
+ export declare class ProjectSession {
5
+ store: DocumentStore;
6
+ filePath: string | null;
7
+ autosave: boolean;
8
+ get doc(): OpenBoneDocument;
9
+ get baseDir(): string;
10
+ newProject(name: string, filePath: string | null, opts?: Partial<OpenBoneDocument>): void;
11
+ open(filePath: string): Promise<void>;
12
+ save(filePath?: string): Promise<string>;
13
+ maybeAutosave(): Promise<void>;
14
+ /** Resolve an image src (data URI, URL, or path relative to the project) to something loadImage accepts. */
15
+ readImageSrc(src: string): Promise<Buffer | string>;
16
+ }
@@ -0,0 +1,43 @@
1
+ import { readFile, writeFile } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { DocumentStore, createDocument, deserialize, serialize } from "@openbone/core";
4
+ /** One open project: the store plus where it lives on disk. */
5
+ export class ProjectSession {
6
+ store = new DocumentStore(createDocument("Untitled"));
7
+ filePath = null;
8
+ autosave = true;
9
+ get doc() {
10
+ return this.store.doc;
11
+ }
12
+ get baseDir() {
13
+ return this.filePath ? path.dirname(this.filePath) : process.cwd();
14
+ }
15
+ newProject(name, filePath, opts = {}) {
16
+ this.store.load(createDocument(name, opts));
17
+ this.filePath = filePath ? path.resolve(filePath) : null;
18
+ }
19
+ async open(filePath) {
20
+ const abs = path.resolve(filePath);
21
+ const doc = deserialize(await readFile(abs, "utf8"));
22
+ this.store.load(doc);
23
+ this.filePath = abs;
24
+ }
25
+ async save(filePath) {
26
+ if (filePath)
27
+ this.filePath = path.resolve(filePath);
28
+ if (!this.filePath)
29
+ throw new Error("No file path: pass `path` to save_project or create the project with a path");
30
+ await writeFile(this.filePath, serialize(this.doc));
31
+ return this.filePath;
32
+ }
33
+ async maybeAutosave() {
34
+ if (this.autosave && this.filePath)
35
+ await this.save();
36
+ }
37
+ /** Resolve an image src (data URI, URL, or path relative to the project) to something loadImage accepts. */
38
+ async readImageSrc(src) {
39
+ if (src.startsWith("data:") || /^https?:/.test(src))
40
+ return src;
41
+ return readFile(path.isAbsolute(src) ? src : path.join(this.baseDir, src));
42
+ }
43
+ }