makepad/libs/model/SCENE_API.md

Object scene and ordered modifiers

All operations are transactional and require the expected document head. Scene transforms use local TRS; attachments may target root, an object, or a joint.

object_node replaces the entire node; omitted parent/link fields become null and omitted TRS components become zero translation, identity rotation and unit scale. dimensions sets that node's scale from evaluated local mesh extents; it does not resize source vertices. Place/rotate with object_node BEFORE calling dimensions, or preserve the existing complete TRS when repositioning a sized part. model.inspect domain scene_nodes exposes the current node transforms.

op	Additional fields
object_node	object, node: {parent?, linked_to?, transform?}
instance	object, source, transform?
duplicate	object, source
make_unique	object; bakes evaluated linked geometry and clears applied modifiers
join	object: new name, sources: distinct object names
separate	object: source, name: new name, faces: ID strings
pivot	object, position: local XYZ; relocate origin while preserving geometry, child transforms, sockets and lights in world space
snap	object, grid: positive metres
dimensions	object, size: positive local XYZ extents
light	name, attachment, transform?, kind: point/spot, color: linear RGB, intensity: candela, range: metres; spot adds inner/outer cone radians
delete_light	name
socket	name, attachment, transform
delete_socket	name
vehicle_wheel	object, connection, pivot: local XYZ, radius, width; see VEHICLE_API.md
delete_vehicle_wheel	object
lods	object, levels: [{target_faces,max_error,distance}]; 1–4 levels, face counts decrease and distances increase
collider	object, kind: box/sphere/mesh; mesh adds source object

A transform is {translation:XYZ, rotation:normalized XYZW, scale:nonzero XYZ}; omitted transform is identity. An attachment is null (root), {object:name}, or {joint:ordinal}. Point/spot lights are distinct emitters, not emissive materials. Counts are bounded to 32 emitters and 128 sockets. Spotlights shine along local -Z; rotate 180 degrees around Y for a +Z-facing headlight. Range is metres and intensity is candela. Parent/link/modifier cycles are refused.

modifier sets or replaces a named ordered entry:

{"op":"modifier","object":"body","name":"copies","enabled":true,
 "operation":{"op":"array","count":3,"offset":[2,0,0]}}

enabled defaults to true. Inner object may be omitted; if supplied it must match the outer object. Each object allows 16 entries and a document allows 128. Supported entries are subdivision, mirror, array, solidify, decimate, normals, and deform/lattice/shrinkwrap with vertices: []. For a modifier, that empty selection resolves all current evaluated vertices; an ordinary edit still treats an empty selection as empty. Fixed element selections cannot be stored in a stack because earlier modifiers may change topology.

Use modifier_order {object,names:[...]} with an exact permutation to reorder, remove_modifier {object,name} to remove, and apply_modifiers {object} to bake the evaluated result and clear the stack/link. A linked instance starts from its source's evaluated mesh, then applies its own entries. Parent/link/enabled modifier dependencies form one acyclic graph. Shared references use one immutable cache per evaluation, and source cage meshes remain unchanged until baked. Shrinkwrap references are evaluated once, then transformed by inverse(owner_world) * reference_world into the owner's local coordinates. Its offset and distance limit use that owner-local space.

join copies evaluated objects through their world transforms and preserves UVs, weights, material IDs, split normals, seam/crease markers, and pins. separate preserves those attributes and the selected element IDs in the new object scope. Linked geometry and stacks must be made unique/baked before a face selection is separated.

Exported LODs use hidden MSFT_lod geometry nodes and extras.MAKEPAD_lod_distances. Sandbox prepares all variants on a worker and selects one per instance by camera distance from the instance origin in world metres. The runtime admits up to eight distinct thresholds across an asset; all variants share one combined upload budget. Lower variants retain node IDs, animation targets, material layers, and the skeleton. Collision and shadow geometry use the highest-detail mesh; changing LOD does not change physics. Hidden targets must be leaf geometry with the owner's skin, local transform, and node weights. Shape keys must be baked/removed on objects whose LOD geometry is generated, since decimation changes their vertex correspondence.

Pivot edits require unique geometry with its modifiers applied; shared sources must first have their linked instances made unique. Morph deltas and vertex IDs survive a pivot edit. LOD distances must be at most 1,000,000 metres; unreachable reduction targets fail compilation with an explicit protected-topology error. Box colliders require positive volume. Worker-cooked box, sphere and mesh proxies provide collision independent of visual LOD.