zblend
A modeling document: Zero's .blend. One <Name>.zblend/ folder holds the editable scene, the history of every script run against it, and a live output bundle that is the model itself. Edit it with the blender toolbox; place it in any scene; placed copies follow later edits.
Folder
| Path | What it is |
|---|---|
scene.json | The editable scene (schema zero.bpy.session/v1), see below. The asset's primary. |
history.json | Every script run against the document, in order. |
README.md | Generated on every edit: object count, triangles, dimensions, materials, object names. Indexed for search. |
images/ | Image pixel data: <name>.pixels (PNG) and <name>.fpixels (float32). |
output.bundle/ | The live model, rewritten on every edit (only changed objects are rebuilt). What instantiate places. |
preview.png | Rendered still, generated by the asset system from instantiate. |
references/, shots/, REPORT.md | Optional; written by the model workflow. |
scene.json
| Key | Holds |
|---|---|
objects[] | Name, id, type data (mesh / curve / text / armature / empty), location, rotation, scale, parent, parent_type/parent_bone, matrix_parent_inverse, modifier stack with settings, material slots, selection and visibility. Meshes carry vertices, faces, per-face material index, smoothing, UV layers, loose edges. |
| per object, animation | pose (per-bone channels), animation_data (action + slot), vgroups (vertex groups and weights), constraints, bone_constraints, drivers, nla (tracks, strips, action blend/influence). |
materials, material_graphs | Principled values and shader node graphs (Principled BSDF, Image Texture, Normal Map, ShaderNodeZeroShader), or a bound zero_material. |
images, textures | Image datablocks (size, colorspace, float, sidecar path) and IMAGE textures. |
armatures | Bones: head, tail, roll, parent, connect, deform. |
actions | Blender 5 slotted actions: slots, F-Curves, keyframes with handles and interpolation. |
frames | Frame start/end/current, fps, fps_base. |
collections, root_children, cursor | Collections (objects, children, visibility, instance offset), which hang off the Scene Collection, and the 3D cursor. Objects carry root, empty display, instance_collection, zero_instance; linked duplicates store mesh_ref/curve_ref to share data. |
view, active, mode, counter | Viewport state, active object, mode, id counter. |
output.bundle/
| Path | Holds |
|---|---|
mesh/ | One mesh per object and material slot (object_N, object_N_sM); skinned meshes object_N_skinM; zblend_animation (the clip driver). |
material/, texture/ | Materials (Zero PBR, or the bound Zero shader) and textures from images. |
rig/ | <doc>.rig for object animation; <doc>_<Armature>.rig per deforming armature. |
animation/ | One clip per action (<Action>), a combined Scene clip when there is more than one action or any NLA, and <Action>_<Armature> bone clips for deformed meshes. |
entity_template | The object hierarchy with Model, SkinnedModel and ClipPlayer components. |
How animation reaches the bundle: clips are sampled once per frame over the action (or whole scene) range, with NLA, drivers, constraints and IK already evaluated. Animated objects become joints of the document rig and play through the zblend_animation entity (SkinnedModel + ClipPlayer). ARMATURE-deformed meshes become SkinnedModels under the armature entity, with one child entity per deform bone plus __rest for unweighted vertices, each with its own ClipPlayer.
Editing
blender.execute_blender_code(code, session="<name or folder/Name>") runs Blender-style Python (bpy, bmesh, mathutils) against the document. A bare name maps to modeling/models/<name>.zblend; "<folder>/<Name>" maps to <folder>/<Name>.zblend. The other tools take the same session: get_scene_info, get_object_info, get_viewport_screenshot, bpy_api_lookup, get_addon_status, compare_to_reference.
What the API covers (full list: blender.toolbox/api.json or bpy_api_lookup):
- Modeling: primitives, edit mode (extrude, inset, subdivide, loop cut, bevel, bridge, spin, remove doubles, knife project, UV smart project), bmesh,
from_pydata, join, transform apply, parenting. - Modifiers: BEVEL, BOOLEAN, ARRAY, SUBSURF, MIRROR, SOLIDIFY, SCREW, WELD, DISPLACE (image textures), ARMATURE.
- Curves and text: POLY/BEZIER/NURBS, bevel, extrude, fills with holes, bevel/taper objects, FONT text with Zero fonts, convert to mesh.
- Materials: Principled BSDF, image textures, normal maps, Zero shaders as nodes, 8-bit and float images, multiple UV layers.
- Rigging: armatures, edit bones, pose bones, bone parenting, vertex groups, ARMATURE modifier, automatic weights (
parent_set(type='ARMATURE_AUTO')). - Animation: keyframes on objects and pose bones, slotted actions and F-Curves,
frame_set, constraints (copy/limit/track/child-of, IK with pole), drivers, NLA tracks and strips. - Scene arrangement: empties, duplicates and linked duplicates, collections and nesting, collection instances,
Object.zero_instance(an empty placing another.zblenddocument, live),origin_set, the 3D cursor and snapping. - Viewport: view axes, orbit, framing, perspective/ortho, lens; screenshots render the document.
Bone matrices, deformation, weights, F-Curves, constraints, IK and NLA match Blender 5.2.1 (checked against the live Blender MCP); the modeling parity suite is in modeling/references/parity/.
Not implemented yet: ARMATURE envelopes and preserve volume; Python classes, yield, decorators and *args. Unsupported calls raise NotImplementedError naming the missing API.
Where editing happens
A document's preview lives in the ModelingWorkspace additive scene layer (zblend.package/workspace/ModelingWorkspace.scene), loaded on first use, so modeling never writes into the scene open in the editor. Old modeling/sessions/<name>/ folders migrate to modeling/models/<name>.zblend on first open.
Using one
- Place: drag the
.zblendinto the viewport, orasset.resolve("<identity>", "zblend"):instantiate(target, opts). This adds anAssetcomponent pointing at the liveoutput.bundle, so the copy follows later edits and plays its clips. Unfold the placed asset to edit the entities in the scene. - Inspect:
asset.resolve(id, "zblend"):inspect()returns object names, materials, script count and whether an output exists. - Freeze:
bpy.ops.export_scene.zero_bundle(filepath="/zero/source/<folder>/<Name>.bundle")writes a standalone snapshot bundle withprovenance.json; an existing path is refused unlessoverwrite=True. - Leave Zero:
bpy.ops.export_scene.gltf(filepath=..., export_format='GLB')is optional interchange; nothing in Zero needs it, and it cannot carry Zero shaders. - Find: documents are indexed by their generated README and preview image.
- Model from scratch: the
modelingskill starts themodelworkflow, which gathers references and refines the document over several critic/builder rounds.
Scoped to this part · feeds back into the world's score.