makepad/libs/model/API.md

Editable model worker API

makepad-model owns its state on one worker. The sandbox host handles bounded jobs, verified asset fetch and publication through nonblocking queues.

Use metres, Y-up, local f64 authoring coordinates. Render export validates f32 range. Flat polygon faces/corners are authoritative; derived edge/radial queries provide topology traversal. Stable element IDs and revision generations are decimal strings in JSON. Material and joint ordinals are ordinary integers.

1. model.open {"document":"robot"} creates an empty document. The host can also open a stored binary source by alias. It must never replace an already open document without closing it explicitly.
2. Read head: {"generation":"0","content":"<64 lowercase hex digits>"}. Pass that exact head to every mutation. Generation always advances on edits/undo/redo; undo can restore a content hash but never an old head.
3. model.apply {"document":"robot","request_id":"create-body", "expected":<head>,"operations":[{"op":"cube","object":"body", "size":[0.7,1.0,0.4]}]} applies the entire batch or nothing. Results contain stable selections for subsequent edits. Repeating the same request ID and payload returns the original result; a reused ID with different payload fails. Result receipts retain at most 128 successful requests and 2 MiB by default; oldest receipts, including an oversized newest receipt, may be evicted; a persisted bounded request-ID ledger refuses reuse after receipt eviction. Exhausting the ledger is an explicit admission error, never silent reuse. Query the job when the host returns an accepted job ID: accepted does not mean completed or published.
4. model.inspect accepts document, optional object, domain, offset, and limit (1–128). Without object, use overview, objects, materials, joints, clips, or clip_keys. With object, use overview, vertices, faces, corners, edges, or weights. Face rows expose corner offsets/counts; page corners for their ordered vertex IDs, UVs and normals. Every reply is capped at 12 KiB of serialized JSON; follow the returned cursors described below. The solid domain performs bounded global intersection and orientation checks; ordinary local mesh validation explicitly leaves global solidity unchecked.
5. model.history {"document":"robot","expected":<head>,"action":"undo"} also supports redo and checkpoint. Checkpoint explicitly discards undo/redo history, advances generation, and preserves content and retry receipts.
6. model.cancel {"job":"<accepted job id>"} requests cancellation. Queued jobs are removed; running jobs cancel at checkpoints. Once publication commit begins, cancellation is too late and the result remains queryable.
7. model.close {"document":"robot","expected":<head>} releases the document.

Inspection pages return items,total,offset,limit,count,omitted,next_offset, byte_limited. Follow the actual next_offset until null; restart if head changes. Limits may stop pages early. overview.inventories supplies each inventory's totals and preview cursor; object validation supplies issue_offset,issues_returned,issues_omitted,next_issue_offset.

Vertex rows inline only a bounded weight prefix. Use weight_offset to page weights (vertex, weight_index, joint, weight), ordered by vertex then joint. Clip rows expose keyframes,key_offset; page clip_keys for clip, channel, joint, path, key, time and value, ordered by clip name/channel/time. Offsets refer to the entire domain; filter identities when crossing rows.

Apply replies retain current head, original committed, and replayed. A shared 256-ID budget limits selections. results_total,results_returned, results_omitted,results_truncated describe result rows. Rows contain result_index,object,face_count,vertex_count,selections_truncated; full counts include omitted IDs. selection_face_total,selection_vertex_total, selection_ids_returned,selection_ids_omitted account for all results. Selections refer to committed; inspection recovers surviving elements at the current head, not intermediate elements deleted later in a batch. Large replies never turn a successful commit into an error.

Supported operation objects (all include op; mesh edits also include object):

op	Additional fields
cube	size: XYZ
plane	size: XZ
sphere	radius: metres, segments: 3–128, rings: 2–128, smooth?: boolean (default true); analytic radial normals, UV seam supplied
cylinder	radius, height: metres, segments: 3–128, smooth?: boolean (default true); centered along Y, smooth radial sides and hard caps
polygon_mesh	positions: XYZ arrays; polygons: [{vertices: zero-based input indices, uvs?: UV arrays, material?: integer}]
transform	vertices: ID strings, matrix: four row-major affine rows
extrude	face: ID string, offset: XYZ
inset	face: ID string, distance: metres; conservative planar convex inset
mirror	axis: 0/1/2, offset: reflection-plane coordinate; duplicates geometry
weld	vertices: ID strings, distance: metres
delete_faces	faces: ID strings
delete_object	none
uv	corner: ID string, uv: UV
corner_normal	corner: ID string, normal: XYZ or null to derive
edge_attributes	vertices: two ID strings, seam: boolean, crease: number
weights	vertex: ID string, weights: [{joint,weight}]
assign_material	faces: ID strings, material: integer
material	material: integer, color: linear RGB 0–1; replaces material/texture
texture_solid	material, width, height, color: RGB byte triple
paint_texture	material, center: normalized UV with top-left origin, radius: normalized distance, color: RGB byte triple
skeleton	joints: [{name,parent:null or earlier joint ordinal,translation: parent-local XYZ}]
auto_weights	object; initial rigid nearest-bone binding, editable afterward
subdivide	levels: 1–3; Catmull–Clark cage subdivision; preserves UV and marked edge seams; refuses creases and explicit loose-edge data
smooth	vertices: ID strings, iterations: 1–64, factor: 0–1, preserve_boundary: boolean
project_uv	faces: ID strings, axis: dropped 0/1/2 (YZ/ZX/XY), scale: UV, offset: UV
brush	vertices: ID strings, center: XYZ, radius: metres, delta: XYZ, max_displacement: metres; smooth grab falloff
clip	name, channels: [{joint,path,keys:[{time,value}]}]
delete_clip	name

Skeletons have one root and parents precede children. Use rig_rest for arbitrary local rest translation, rotation and scale; animation supports all three paths, FK/IK controls and portable baking. Clip paths are translation, rotation, or scale. Key values have four lanes: XYZ plus zero for translation/scale; normalized XYZW quaternion for rotation. Times are increasing seconds. Skin export requires at most four known normalized influences per rendered vertex and preserves each material/texture primitive.

Materials support layered PBR channels, masks, RGBA textures, alpha modes, vertex color, emissive strength and bounded procedural/paint/bake operations. PNG decoding and mip construction run on workers. Shape keys export real position/normal targets and animated weights. Arbitrary shader graphs are outside this portable material contract. Topology edits preserve corner UV seams and vertex weights where the operation defines a mapping. Simple nonplanar cage polygons use deterministic projected triangulation; nonplanarity is reported, and planar inset refuses those faces. Selectors are scoped to the expected document head and object name: an undone/recreated branch may reuse a numeric element ID, so a selector must never be replayed against an unrelated head.

Document::compile produces GLB, bounds, counts and face provenance. Document::compile_preview produces a static draft at the same source head, including textures, current shape-key weights and rest-position lights while wheel or skin binding is unfinished. The derived draft omits animation, skin, wheel driving connections, sockets, collision and delivery LODs. It does not modify source or relax the completion checks used for publication. to_bytes stores versioned checkpoint, undo log and receipts; from_bytes verifies canonical content. Publication uses to_snapshot_bytes to store current editable state without cross-platform floating-point replay. The working document retains its undo history. Transaction admission also bounds aggregate replay work, including checkpoint decode, every retained transaction, the most expensive undo cursor, and canonical source re-encoding. If another edit would exceed that bound, it fails atomically with a checkpoint-required error; call checkpoint explicitly to discard undo/redo before retrying. Undo history is never silently truncated, and hostile source input keeps the same aggregate work cap. Replay costs are measured from execution, not trusted fields in serialized input.

The asset host publishes source and GLB in one existing Prop (static) or Character (skinned) asset revision (Source/Bin, RenderGlb/Glb). Alias publication requires an expected alias head or explicit absence and a persisted asset identity. A separate expected document head pins the intended edited content. New game clients fetch the compiled GLB; they do not replay modeling operations. Old CSG ModelProgram source remains text.

Limits are provisional resource guards, not measured Quest 3 performance claims. The default document admits 2048 objects and 512 materials, with at most 256 operations per batch. Working memory is 2 GiB, with 10 billion work units, 4,000,000 compiled triangles, 256 MiB source and 64 MiB transactions. Undo history retains up to 4096 batches before an explicit checkpoint. Sixteen open documents, one admitted authoring operation per host, bounded queues, cancellation checkpoints and prepared render products prevent UI-side modeling work. Global geometry operations have explicit resource and attribute admission rules.

The complete operation families and inspection domains are described in MESH_API.md, CONSTRUCTION_API.md, SCENE_API.md, SURFACE_API.md, RIG_API.md, and SELECTION_API.md. world.api exposes these contracts to the AI. Use surface_material to modify rich materials: legacy material refuses to discard an existing layer stack. Deleting a clip removes its event/interpolation/morph options; deleting a morph removes that morph's keys from all clips. Delete inbound attachments/references in the same transaction before deleting an object they target.