# 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")
```
# ZeroBlender
Blender-style modeling inside Zero. Install this package and you get the whole surface: the `.zblend` document type, the tools that edit it, the Python/bpy runtime behind them, the layer previews live in, and the workflow that drives a modeling job to the end.
## Contents
| Path | What it is |
|---|---|
| `zblend.assetType/` | The `.zblend` document (Zero's `.blend`): editable `scene.json`, history, images, and a live `output.bundle`. Scene-instantiable, previewed, searchable. Its ref methods open and edit documents (below); `M.modules` exposes every module here to instances. |
| `blender.toolbox/` | Blender MCP-compatible tools: `execute_blender_code`, `get_scene_info`, `get_object_info`, `get_viewport_screenshot`, `bpy_api_lookup`, `get_addon_status`, `compare_to_reference`. `api.json` is the implemented bpy surface. |
| `modules/blenderSession` | The bpy/bmesh/mathutils session: objects, meshes, modifiers, materials, viewport, flush to the document and bundle. |
| `modules/pythonParser`, `pythonRuntime` | The Python subset the scripts run in (Luau-hosted, not CPython). |
| `modules/animation`, `rigging` | Armatures, pose, vertex groups, ARMATURE deform, auto weights, keyframes/actions/F-Curves, constraints, IK, drivers, NLA; clip baking. |
| `modules/sceneOps` | Empties, duplicates, collections, collection instances, `zero_instance`, `origin_set`, cursor, snapping. |
| `modules/curves`, `meshOps`, `polygonTopology`, `xform` | Curve/text meshing, edit-mode operators, topology and evaluation, matrix math. |
| `modules/referenceCompare` | Silhouette scoring against a reference image. |
| `modules/bpy`, `hardSurface`, `kestrel` | Older core geometry layer and hard-surface helpers used by the session. |
| `workspace/ModelingWorkspace.scene` | Additive layer holding document previews, on render layer `modelingWorkspace` (hidden from the editor camera, drawn by screenshots). |
| `model.workflow/` | Multi-pass modeling job: reference → model → critic/builder rounds → finish. |
| `modeling.agentSkill/` | The `modeling` skill that starts the workflow. |
## Usage
```luau
-- Make or open a document and edit it
local doc = asset.create("zblend", "Lantern", { folder = "models" })
doc:run([[import bpy
bpy.ops.mesh.primitive_cylinder_add(radius=0.1, depth=0.3)]])
doc:screenshot("ISO")
doc:sceneInfo()
doc:open() -- load as a live session, returns its name
-- Place it (live: placed copies follow edits and play its clips)
doc:instantiate(entity.find("Shelf"))
-- Frozen copy
doc:exportBundle("/zero/source/models/Lantern_v1.bundle")
```
Agents use the `blender` toolbox directly with `session="<folder>/<Name>"`, or start the `model` workflow for a full modeling job (`zero workflow start --name model --args '{"subject":"..."}'`).
Documents default to `modeling/models/<name>.zblend`; user data (models, references, reports) is not part of the package.