Protocol version 1; recipe format brasset, version 1. Legacy .brasset.json extensions are deliberately retained. MCP uses newline-delimited JSON-RPC over stdio and negotiates protocol 2024-11-05. Its bridge forwards commands to the authenticated loopback Godot endpoint. Start with capabilities and inspect; operation validation is authoritative.
Meters; +X asset-right, +Y up, +Z asset-front; degrees. Transforms and animation values are parent-local and absolute. A sphere has unit diameter. IDs and file names allow letters, digits, _, -, up to 64 characters. User-selected paths are not accepted; files stay under output/. load also reads the bundled examples/assets/ recipes when no saved file has that name.
| MCP name | Arguments | Result |
|---|---|---|
studio_capabilities |
{} |
Constructors, parameter names, views, conventions, budgets |
studio_inspect |
{} |
Revision, complete part/clip recipes, history depths, mesh-build counter |
studio_apply |
request_id, base_revision, ops |
Atomic commit, new revision, part/build counts |
studio_preview |
name, revision; optional fields below |
PNGs, per-view camera metadata, optional part bounds |
studio_pose |
revision, clip, time |
Seek an existing clip; does not edit recipe |
studio_validate |
{} |
Mesh/vertex/triangle counts and finite/degenerate geometry diagnostics |
studio_save |
name |
Editable recipe path |
studio_load |
name, base_revision |
Undoable load with a new revision |
studio_export |
name, revision |
GLB path, roundtrip mesh/animation counts, diagnostics |
studio_undo, studio_redo |
base_revision |
One history step, new revision |
For the CLI omit studio_. Use python bridge/studio.py METHOD --file request.json to avoid shell quoting issues. Request JSON contains arguments, not a method wrapper.
{"request_id":"unique-edit-001","base_revision":0,"ops":[
{"op":"create","id":"body","spec":{"kind":"box","params":{"size":[1,2,1],"bevel":0.12}}}
]}| Operation | Fields |
|---|---|
create |
id, spec |
update |
id, changes — absolute property replacement |
delete |
id — dependencies must remain valid |
lock |
id, value (boolean) |
mirror |
id, source, axis (x, y, z) |
repeat |
id, source, count (1–64), step (XYZ) |
reset |
name — replaces active recipe |
name |
name — changes document title |
clip |
name, clip — animation definition |
All operations validate together before committing. Unknown fields, invalid geometry, dangling references, cycles, and locked-part edits reject the batch. On uncertain retries reuse both ID and payload; the newest 512 receipts are retained. A fresh logical edit requires a fresh ID. Revisions also protect undo/redo against duplicate requests. History retains 64 states.
Mirroring reflects across the source parent's origin. Repeat creates id_00, id_01, etc. at successive multiples of step, starting one step after the source. Derived parts refer to an original source; deriving from another derived part is rejected. Geometry-only caching means material-only edits reuse meshes; the entire node graph can still be recompiled per commit.
kind, params, position, rotation_degrees, scale, pivot, material, parent, anchor, child_anchor, offset, locked. Omitted transforms default to zero position/rotation and unit scale. Scale must be positive. pivot is subtracted from mesh coordinates; the containing node rotates around it. params and material dictionaries are replaced wholesale by update, not deep-merged.
Anchors: center, top, bottom, left, right, front, back. Parent and child anchors align local bounding boxes, then apply offset. This is not a rotated-surface attachment or physics constraint. Material keys: HTML color, and roughness, metallic, emission coefficients from 0–1. Transparency is not part of this alpha's material schema.
| Kind | Parameters |
|---|---|
box |
size XYZ; bevel 0–0.45 of shortest dimension |
sphere |
sides, rings; use scale for ellipsoids |
cylinder |
top_radius, bottom_radius, height, sides; one zero radius makes a cone |
torus |
inner_radius, outer_radius, sides, segments; lies in XZ, hole along Y |
lathe |
profile of [radius,y], sides, caps |
sweep |
points XYZ and equal-length positive radii, sides; capped ends |
extrude |
XY polygon profile, positive Z depth |
Each kind also accepts bend, taper, faceted. These are simple mesh modifiers, not a general modifier stack. Profiles need 3–96 points; sweeps need 2–96 with no duplicate adjacent points or complete reversals. Tessellation values are integers 3–64. The model budget is 256 parts, 256 operations per batch, and an estimated triangle budget; validation is not an exact GPU-memory guarantee.
Up to 16 clips. Each clip has positive duration up to 60 seconds and tracks. Track fields: part, property (position, rotation_degrees, or scale), and 2–128 ascending [time,XYZ] keys within the clip duration. Use an end key matching the first for a seamless loop. Transform animation is exported; skeletal skinning is not implemented.
{"op":"clip","name":"wave","clip":{"duration":2,"tracks":[
{"part":"arm","property":"rotation_degrees","keys":[[0,[0,0,0]],[1,[0,0,45]],[2,[0,0,0]]]}
]}}Omit views to get a labeled 3×2 sheet: front, back, left, right, top, bottom. Four diagonals—front_right, back_right, back_left, front_left—each have level, _high (+30°), and _low (-30°) variants: 18 canonical angles total. Legacy side is right; three_quarter and current remain available. Maximum 18 unique views per request.
Explicit views default to individual full-resolution PNGs. output can override with individual, contact_sheet, or both. Sheet cells are 480×332; six views produce 1440×664 pixels. MCP embeds returned images directly, not merely file links. The default embeds one sheet.
Other options: include_bounds (default true), include_ui (false), show_floor (false, to expose the underside). Camera state, floor, UI visibility and playback are restored after capture. Named cameras use fixed rest-pose framing; current preserves the exact user camera. Seek with pose before each animation capture.
Each view reports camera position, target, up vector, perspective field of view, source dimensions, revision, clip and timestamp. Each part optionally reports conservative world-space min/max bounds at that pose. These are not visibility, collision, overlap or watertightness tests. No image cache, delta output, occlusion estimates, or arbitrary close-up camera command yet.
Responses use ok:false, code, message, and usually revision. Common codes include STALE_REVISION, REQUEST_ID_REUSED, INVALID_REQUEST, INVALID_RECIPE, INVALID_VIEW, BUSY, NOT_FOUND, WRITE_FAILED, EXPORT_FAILED, and REIMPORT_FAILED. Read the actual result rather than inferring success from a written file. Exports check mesh count and report animation counts; diagnostics do not establish artistic quality.
The app is single-user local software. The endpoint accepts at most four pending connections with a 2 MB request cap and timeouts. Autosave is recovery, not source control. Save valuable work outside recovery history. Do not run untrusted server-side code or publish the private session directory.