# pythonRuntime
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# blender
Blender MCP-compatible modeling surface for Zero. `execute_blender_code` runs Python/bpy as Zero world content; no external Blender is used. Tool names and argument names mirror Blender MCP.
The Python is interpreted in Luau (`modeling/pythonParser`, `modeling/pythonRuntime`) — a subset, not CPython. The `bpy`/`bmesh`/`mathutils` surface is `modeling/blenderSession`.
## Tools
| Tool | Notes |
|---|---|
| `get_addon_status(user_prompt?)` | Implementation and compatibility version. |
| `bpy_api_lookup(query, user_prompt?)` | Returns the schema from `api.json`. Unknown names return `NotImplementedError` plus related supported names. |
| `execute_blender_code(code, user_prompt?, session?)` | Runs Python, then evaluates modifiers and writes meshes/materials/entities under `modeling/sessions/<session>`. Sessions are isolated; default `default`. |
| `get_scene_info(session?)` | Objects, locations, material count. |
| `get_object_info(object_name, session?)` | Dimensions, mesh counts, evaluated triangles, modifier stack, topology audit. |
| `get_viewport_screenshot(max_size?, session?, view?, perspective?)` | Renders the session's viewport state, which scripts drive through bpy (`bpy.ops.view3d.view_axis/view_all/view_selected/view_orbit/view_persportho`, or `region_3d.view_rotation/view_location/view_distance/view_perspective`). `view` (FRONT…BOTTOM, ISO) and `perspective` (PERSP/ORTHO) override it for one capture. Rendered by Zero, not a Blender viewport. |
## Coordinates
Scripts use Blender coordinates (Z-up, right-handed). Zero entities receive `(x, y, z) -> (x, z, -y)`.
## Supported API
Authoritative list: `api.json` (or `bpy_api_lookup`). Summary:
- **Primitives:** cube, plane, cylinder, cone, uv_sphere, ico_sphere, torus, circle, grid — with `location`, `rotation`, `scale`, `enter_editmode`. New primitives are fully selected, as in Blender.
- **Object ops:** `mode_set` (OBJECT/EDIT), `select_all`, `delete`, `transform_apply`, `shade_smooth/flat`, `modifier_apply`, `modifier_move_up`.
- **Edit ops:** `select_mode`, `select_all`, `extrude_region_move`, `inset` (region and individual, `depth`), `subdivide` (`number_cuts` 1–100), `loopcut_slide`, `bevel` (edges and vertices, segments), `bridge_edge_loops`, `spin`, `remove_doubles`, `object.material_slot_assign`.
- **Transform:** `translate`, `resize`, `rotate`. In EDIT mode the pivot defaults to the selection median; `center_override` sets it explicitly.
- **Data:** `bpy.data.meshes/objects/materials.new`, `objects.remove`, `Mesh.from_pydata`, `mesh.vertices/edges/polygons/materials`, `collection.objects.link`, `view_layer.objects.active`.
- **bmesh:** `new`, `from_edit_mesh`, `update_edit_mesh`, `from_mesh`, `to_mesh`, `verts.new`, `faces.new`, `edges` (`verts`, `link_faces`, `is_boundary`, `is_manifold`, `calc_length`, `select`), `calc_volume`, `ops.recalc_face_normals`.
- **Modifiers:** BEVEL (ANGLE/NONE limit), BOOLEAN (DIFFERENCE/UNION/INTERSECT), ARRAY (with merge), SUBSURF, MIRROR (with merge), SOLIDIFY (offset −1/0/1), SCREW, WELD, DISPLACE (no texture).
- **Curves and text:** `bpy.data.curves.new(name, 'CURVE'|'FONT')`, POLY, BEZIER and NURBS splines, `bevel_depth`, `extrude`, 2D fills with holes, `object.text_add`, `curve.primitive_bezier_curve_add/circle_add`, `object.convert(target='MESH')`. Text uses Zero fonts via `curve.zero_font` (default Arimo).
- **UVs:** `bpy.ops.uv.smart_project`, `mesh.uv_layers` (one layer). UVs are carried into rendered meshes and bundles.
- **Images and shader nodes:** `bpy.data.images.new/load/remove`, `Image.pixels` (incl. `[:]` assignment), `colorspace_settings.name`; node tree with Principled BSDF, Image Texture and Normal Map nodes; texture links to Base Color, Roughness, Metallic, Emission Color and Normal become Zero PBR texture slots (roughness/metallic packed).
- **Zero shaders as nodes:** `nt.nodes.new('ShaderNodeZeroShader')`, set `node.shader` to any Zero shader; its properties become inputs.
- **Knife project, texture DISPLACE, Closest interpolation, float images, multiple UV layers** are implemented (see api.json).
- **Hierarchy:** `Object.parent`, `parent_set`, `parent_clear`, `matrix_world` and friends, `object.join`, `mathutils.Matrix`.
- **Viewport:** `bpy.ops.view3d.*` above, `RegionView3D`, `SpaceView3D.lens`, `context.screen.areas`, `temp_override`.
- **Compare to reference:** `blender.compare_to_reference(reference, session)` scores the session's FRONT elevation against a reference sheet (silhouette IoU, per-band scores, overlay image).
- **Output (preferred):** `bpy.ops.export_scene.zero_bundle(filepath='/zero/source/<folder>/<Name>.bundle')` writes a native Zero bundle — meshes and materials inside it, one Model per material slot, spawnable with the `Asset` component. A material bound with `mat.zero_material = '<material identity>'` keeps its custom Zero shader. Exports are frozen snapshots: an existing path is refused unless `overwrite=True`, and each bundle carries `provenance.json`.
- **Interchange (optional):** `bpy.ops.export_scene.gltf(..., export_format='GLB')` exists for leaving Zero; nothing inside Zero needs it.
- **Materials:** Principled BSDF `Base Color`, `Metallic`, `Roughness`, `Alpha`, `IOR`; multiple slots with per-face `material_index`; `material_slots`, `active_material(_index)`; `zero_material` binds an existing Zero material asset.
## Rigging and animation
Armatures (`bpy.data.armatures`, `object.armature_add`, `edit_bones`, `pose.bones`), bone parenting (`parent_set(type='BONE')`), keyframes (`keyframe_insert` on objects and pose bones), Blender 5 slotted actions and F-Curves, and `scene.frame_set`. Bone matrices and F-Curve evaluation match Blender 5.2.1.
Actions are written into the document's `output.bundle` as animation clips; a placed `.zblend` plays them (SkinnedModel + ClipPlayer). Vertex groups, the ARMATURE modifier and automatic weights deform meshes; constraints (incl. IK), drivers and NLA are implemented and baked into the clips.
## Documents: `.zblend` (live)
`session` names a `.zblend` document, Zero's `.blend`: a bare name maps to `modeling/models/<name>.zblend`, or pass `"<folder>/<Name>"`. The document holds `scene.json` (objects, meshes, curves, modifier stacks, node graphs, images, UV layers, view), `history.json`, `images/`, and `output.bundle/`.
Every `execute_blender_code` updates the document and its `output.bundle` in place (only changed objects are rebuilt). A `.zblend` is scene-instantiable: drag it into a scene or call `asset.resolve(id, "zblend"):instantiate(...)`. Placed copies follow later edits. It has a preview and is indexed for search. `export_scene.zero_bundle` is only for a frozen snapshot; nothing needs an export step to use the model inside Zero.
Session previews live in the `ModelingWorkspace` additive scene layer (`ZeroBlender.package/workspace/ModelingWorkspace.scene`, loaded persistent on first use), so modeling never touches or saves into the scene open in the editor.
Old `modeling/sessions/<name>/` folders migrate automatically on first open.
## Known differences and limits
- Unsupported calls raise `NotImplementedError: …` or `AttributeError: …` naming the missing API. Nothing is silently ignored except `calc_uvs`.
- `subdivide` requires all faces selected; `number_cuts > 1` requires quads.
- `inset` expects planar selections; `extrude_region_move` requires FACE selection.
- BOOLEAN operands must be closed manifold solids.
- ARRAY merge, bevel `limit_method` WEIGHT/VGROUP, and adding primitives in EDIT mode are not implemented.
- SUBSURF: `get_object_info` reports the dimensions of the smoothed surface; Blender with GPU subdivision may report the cage size.
- Python: one number type (so `24.0` prints as `24`); no classes, generators, decorators or `*args`.
## Parity suite
`modeling/references/parity/cases.json` holds scripts with numbers captured from native Blender 5.2.1. Run `execute { file = "/zero/source/modeling/references/parity/run.luau" }`; currently 76/76 pass (subsurf counted as a documented difference).
## Not implemented yet
Scene arrangement is implemented: empties, duplicates and linked duplicates, collections, collection instances, `Object.zero_instance` (place another `.zblend`), `origin_set`, the 3D cursor and snapping.
# model
Keeps a modeling job going until the model holds up beside its reference.
Reference → Model → Refine (a critic who didn't build it lists differences, the builder fixes them; up to `rounds`, default 6) → Finish.
The prompts state goals only; how to get there is left to the agent.
```bash
zero workflow start --name model --args '{"subject":"a brass ship lantern","name":"lantern"}'
```
# modeling
One paragraph on what this skill teaches and who it is for. This README is
the asset summary shown when a tool or human inspects the folder directly.
`instructions.md` is what an agent receives on `agent_skill { name = "modeling" }`.
`skill.yaml` declares the description that rides tool responses, plus the
assets, toolboxes, and guides the job runs through.
# animation
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# blenderSession
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# bpy
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# curves
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# hardSurface
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# kestrel
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# meshBuf
Polygon meshes kept entirely in substrate (engine) memory, for ZeroBlender documents and every algorithm that edits them. No mesh-sized Luau table is ever built: every array is a CPU substrate buffer read and written in place.
## Stores
- `M.words(n, fill?)` -> `W`: n numbers. `:get(i)`, `:set(i,v)`, `:add(i,v)`, `:push(v)`, `:resize(n,fill?)`, `:reserve(n)`, `:fill(v)`, `:copy()`, `:free()`; field `.n`. Indices are 0-based. Integers are exact below 2^24.
- `M.vec3s(n)` -> `V3`: n xyz records. `:get(i)->x,y,z`, `:set(i,x,y,z)`, `:add(i,x,y,z)`, `:push(x,y,z)`, `:zero()`, `:copy()`, `:free()`.
- `M.hash(arity, expected?)` -> `Hash`: integer keys (1-3, each in [0,2^24)) mapping to a number. `:get(a,b?,c?)`, `:put(v,a,b?,c?)`, `:each(fn(v,a,b,c))`, `:free()`; field `.n`.
## Mesh (`M.new()`)
Fields: `P` (V3 positions, `nv`), `C` (W corner vertex ids), `O` (W face offsets, `nf+1` words), `FM` (W material slot per face, or nil), `UV` (list of `{name, W}`, two words per corner; `uvActive`/`uvRender` 1-based), `LE` (W loose edges, 2 words each), `SEL` + `selMode`, `ver` (bumped by every edit).
Reading: `co(i)`, `faceStart(f)`, `faceEnd(f)`, `faceLen(f)`, `corner(c)`, `faceMat(f)`, `uv(layer,c)`, `faceNormal(f)`, `faceNormalRaw(f)`, `faceCenter(f)`, `faceArea(f)`, `bounds()`, `triangleCount()`, `signedVolume()`, `looseCount()`, `isSel(i)`.
Writing: `addVert(x,y,z)`, `setCo`, `pushCorner(v)` then `closeFace(slot?)`, `setCorner`, `setFaceMat`, `addUVLayer(name,init?)`, `setUV`, `removeUVLayer`, `addLooseEdge(a,b)`, `setSel`, `clearSel`, `reverseFace(f)`, `filterFaces(keep)`, `compactVerts()`, `append(src,T,remap,flip)`, `clearFaces()`, `clear()`, `copy()`, `assign(src)` (takes src's stores), `free()`.
## Derived data
- `M.edges(m)` -> unique undirected edges, numbered in (low, high) vertex order: `.n`, `:verts(e)`, `:find(a,b)`, `:faceCount(e)`, `.CE` (edge of corner c -> c+1). Cached until `m.ver` changes.
- `M.vertexCorners(m)` -> `{off, vc, cf}` CSR: the corners of vertex v are `vc[off[v] .. off[v+1])`, `cf[c]` is the face of corner c. Call `:free()`.
- `M.triangulate(m)` -> `T` (3 corner ids per triangle), `TF` (face per triangle). Quads and n-gons ear-clipped against the face normal.
- `M.vertexNormals(m)`, `M.cornerNormalsByAngle(m, angle)` -> V3.
- `M.weldIds(m, tol)`, `M.audit(m)`.
## Drawing and saving
- `M.upload(m, slot|nil, "flat"|"smooth"|"angle", normals?, name)` builds GPU vertex and index buffers and a renderer mesh from them (Zero basis x, z, -y). `M.release(up)` frees them.
- `M.save(m)` -> blob string, `M.load(blob, uvNames)` -> Mesh.
```luau
local MB = require("~ZeroBlender.modules.meshBuf")
local m = MB.new()
for _, p in { {0,0,0}, {1,0,0}, {0,1,0} } do m:addVert(p[1], p[2], p[3]) end
m:pushCorner(0); m:pushCorner(1); m:pushCorner(2); m:closeFace()
local up = MB.upload(m, nil, "flat", nil, "tri")
```
# meshEdit
Blender edit-mode operations on meshBuf Meshes, in place, with no mesh-sized Luau tables. Used by `bpy` (B.ops.mesh / B.ops.transform, SUBSURF modifier).
Selection lives on the mesh: `m.selMode` ("VERT" | "EDGE" | "FACE") and `m.SEL` (per vertex, per `MB.edges(m)` edge id, or per face).
- `selectAll(m, action)` — "SELECT" | "DESELECT" | "INVERT"; `selectMode(m, mode)` (clears the selection)
- `selectedVerts(m)` -> W flags, count; `median(m)` -> x, y, z
- `translate(m, v)`, `resize(m, v, center?)`, `rotate(m, angle, axis, center?)` — on the selected vertices; center defaults to the selection median. `v`/`center` are `{x,y,z}`, `{x=,y=,z=}` or a vector.
- `extrudeRegion(m, t)` — FACE mode; selected faces become the moved caps (keep indices, stay selected), side quads appended; originals kept flipped when the region touches an open boundary.
- `inset(m, thickness, depth, individual?)` — FACE mode; region (default) or per-face.
- `subdivide(m, cuts)` — all faces selected; cuts=1 simple split, cuts>1 grid split of quads.
- `subsurf(m, levels, simple)` -> NEW Mesh (caller frees). Catmull-Clark with Blender boundary rules (boundary vertex 3/4 p + 1/8 neighbours, boundary edge midpoints, non-manifold vertices fixed).
- `triangulateFace` = `MB.triangulateFace`.
Material slots (FM) and UV layers are carried onto every created face.
# meshMods
Blender's DECIMATE, TRIANGULATE and WEIGHTED_NORMAL modifiers over `meshBuf` meshes (Blender space). Each function takes an MB Mesh and returns a NEW one, leaving the input untouched, with material slots (`FM`), smooth flags (`SMF`) and UV layers carried over. All per-element data stays in substrate stores (`MB.words` / `MB.vec3s` / `MB.hash`), never in mesh-sized Luau tables, and every scratch store is freed when the call ends, including when it fails. The modifier stack (blenderSession) uses it to evaluate these modifiers.
```luau
local Mods = require("~ZeroBlender.modules.meshMods")
local low = Mods.decimate(m, {decimate_type="COLLAPSE", ratio=0.5})
local tri = Mods.triangulate(m, {quad_method="BEAUTY", ngon_method="BEAUTY", min_vertices=4})
local wn = Mods.weightedNormal(m, {mode="FACE_AREA", weight=50, thresh=0.01}) -- wn.CNC: V3 per corner
local r = Mods.apply(m, "DECIMATE", values) -- dispatch by type
```
## decimate(m, values)
- `COLLAPSE`: triangulates, then does Garland-Heckbert quadric edge collapse until there are at most `ratio * triangles` faces. Boundary edges add perpendicular penalty planes (weight 100). A collapse is rejected when it would flip or degenerate a face normal, or when it would break the link condition (keeping the surface manifold). A binary heap in word stores with lazy invalidation orders the collapses. With `use_collapse_triangulate=false`, faces whose vertices never moved come back as the original quads and n-gons. `use_symmetry` keeps vertices on the mirror plane on it.
- `DISSOLVE` (planar): adjacent faces join while their area-weighted normals stay within `angle_limit`. Each region bounded by one simple loop becomes an n-gon, found by walking its boundary. Vertices left between two nearly collinear edges are dropped. Supports `delimit` containing "MATERIAL" and `use_dissolve_boundaries`.
- `UNSUBDIV`: reverses grid subdivision `iterations` times on all-quad meshes. Vertices are classified by 2-colouring the edge graph and then the quad diagonals. A mesh that is not a subdivided grid raises `NotImplementedError: DECIMATE UNSUBDIV ...`.
## triangulate(m, values)
Faces with `min_vertices` or more corners are split. `quad_method` is one of BEAUTY, FIXED (0-2), FIXED_ALTERNATE (1-3), SHORTEST_DIAGONAL or LONGEST_DIAGONAL. `ngon_method` CLIP ear-clips (`MB.triangulateFace`), and BEAUTY ear-clips and then flips edges. Every output corner copies the UVs of its source corner exactly. `keep_custom_normals` carries `CNC`/`CNV`.
## weightedNormal(m, values)
Follows MOD_weighted_normal.cc. Values are corner angle, face area, or both multiplied, depending on `mode`. Items (fans) receive them in descending order: `num_set` grows when a value differs from the current one by more than `thresh`, and the face normal is added with weight `val / weight^num_set`. Here `weight` is the modifier weight divided by 50 (32767 at 100, 1/32767 at 1, and `(w-1)*25` when that is greater than 1). With `keep_sharp`, fans split at `m.SHARP` edges (a W per `MB.edges(m)` edge), at flat faces (`m.SMF`) and at boundaries. Otherwise there is one fan per vertex. `use_face_influence` reads `m.FSTR` (a W per face: -1 weak, 0 medium, 1 strong). The result is a copy of `m` with `CNC`, a V3 with one normal per corner.
# meshOps
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# meshProxy
The bpy mesh data views for the ZeroBlender session: `Mesh`, `MeshVertex`,
`MeshPolygon`, `MeshEdge`, `MeshLoop`, UV layers, and the `bmesh` module and
`bmesh.ops`. Every sequence (`mesh.vertices`, `mesh.polygons`, `bm.faces`, ...)
is a lazy view over the session's meshBuf stores, so Python scripts read and
write vertex positions, face data and UVs in engine buffers without copying the
mesh into Luau tables.
Called by `blenderSession`, which installs it once per session with
`MeshProxy.install(S, helpers)` and uses the returned `meshProxy`,
`vertexProxy`, `faceProxy`, `edgeProxy`, `bmeshProxy` and `bmeshOps`.
# meshStore
Holds a ZeroBlender document's polygon meshes in substrate (engine) memory between calls.
A mesh record's geometry (positions, face corners, face offsets, per-face material, UV layers) is packed into substrate columns. Reading `vertices`, `faces`, `uv`, `uv_layers` or `face_mat` unpacks that one mesh for the call that needs it, and `M.pack` puts it back and drops the tables. A document at rest therefore holds no per-vertex Luau tables.
```luau
local MeshStore = require("~ZeroBlender.modules.meshStore")
MeshStore.pack(mesh, uvSync) -- geometry -> substrate, tables dropped
print(MeshStore.faceCount(mesh)) -- answered without unpacking
local fs = mesh.faces -- unpacks this mesh on first read
```
# polygonTopology
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# pythonParser
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# referenceCompare
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# rigging
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# sceneOps
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# xform
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
# pyModule
A Python package for the ZeroBlender Python interpreter (the runtime behind
`execute_blender_code`). A `<name>.pyModule/` folder holds `__init__.py` (the
package body) and any further `.py` files as submodules.
Scripts import it like any Python package: `import name`, `from name import x`,
`from name.sub import y`. The interpreter's import system searches, in order:
`sys.modules`, every folder on `sys.path` (default `/zero/source/python`, for
loose `.py` files and package folders), then the asset index for `<name>.pyModule`.
So the interpreter is extended by writing Python, not Luau.
Methods on `AssetRef<pyModule>`:
- `check()` → `{ ok, diagnostics }`: parse errors and imports that resolve to nothing. Runs no Python.
- `exports()` → a table of the package's top-level names (functions stay callable).
- `run(code)` → runs a script with this package importable, returns its output.
# [scene_name]
One-paragraph description of what this scene is — the level, screen or
area it represents, and when the world loads it. This README describes
*this* scene; what a scene is and how loading works live in the scene
assetType README.
## Contents
- What the entity hierarchy holds — the terrain, props, lights and
spawn points a reader should expect to find.
- Which player intent `scene.json` declares (`"spawns"` places the local
player and its camera on join; `"none"` leaves both to the entrypoint).
## Entry point
- `entrypoint.luau` — what it sets up when this scene loads, and
anything a caller has to do before loading it.
# 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 `SkinnedModel`s 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 `.zblend` document, 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 (`ZeroBlender.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 `.zblend` into the viewport, or `asset.resolve("<identity>", "zblend"):instantiate(target, opts)`. This adds an `Asset` component pointing at the live `output.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 with `provenance.json`; an existing path is refused unless `overwrite=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 `modeling` skill starts the `model` workflow, which gathers references and refines the document over several critic/builder rounds.
# bpy_api_lookup
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# compare_to_reference
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# execute_blender_code
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# get_addon_status
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# get_object_info
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# get_scene_info
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# get_viewport_screenshot
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# replay_capture
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this tool provides and who
consumes it, then delete both comment lines. -->
TODO: describe this tool.
# shared
Cross-tool helpers for the blender toolbox. Every tool inside the
toolbox can pull these in with `require(".shared")`. Holds the small
set of helpers that more than one tool needs — typically the
`ok(value, formatted?)` / `fail(message, exitCode?)` constructors that
produce the canonical `blenderToolResult` shape, plus any toolbox-wide
parsers, validators, or shared state. Per-tool implementation stays
inside each `<x>.tool/init.luau`; this module is not a place to
forward logic from.
## Exports
- `M.ok(value: any?, formatted: string?) -> blenderToolResult` — success envelope (`exitCode = 0`, `ok = true`).
- `M.fail(message: string, exitCode: number?) -> blenderToolResult` — failure envelope (`exitCode` defaults to 1, `ok = false`).
Types:
- `blenderToolResult = { stdout: string, stderr: string, exitCode: number, ok: boolean, value: any? }`
- `stdout` — human-readable formatted output; empty when the op produces no text.
- `stderr` — error message on failure; empty on success.
- `exitCode` — POSIX-style exit code: `0` success, `1` generic failure, `2` bad arguments.
- `ok` — `true` iff `exitCode == 0`.
- `value` — structured return from the underlying op; `nil` for void ops.
## Usage
```luau
local shared = require(".shared")
function M.someTool(args)
if not args.id then
return shared.fail("missing id", 2)
end
return shared.ok({ id = args.id }, "created " .. args.id)
end
```
## Notes
- Pure constructors — no engine calls, no state. Safe to call from any
context.
- Tools that opt into this shape get a stable envelope every other tool
in the toolbox can rely on. Tools that do something custom can return
whatever shape they want — `blenderToolResult` is opt-in.
- Per-tool implementations still own their own `--!desc` / `--!arg` /
`--!return` / `--!example` annotations even when their result is
constructed through these helpers.