<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=verbs]]

<div class="doc">

<!-- GENERATED by love-shared/scripts/verb_sheet.py from the app's registry (scripts/verb_inventory.lua): do not edit; run it. -->

# blender · the verbs

<p class="plain"><a href="../../verbs/blender.md">this page as plaintext</a></p>

*Blender, through starlab-bridge: its scene, objects, materials, modifiers and keys, renders and recordings, the lab's elements and worlds, and the house UI's frames, layouts, motions, shells and bench specs. 79 verbs in 9 categories: 20 undoable, 19 read-only. The app-verbs protocol (`love-shared/docs/app-verbs.md`): `staros-tap blender verbs` lists them live, `staros-tap blender verb <name> '<json>'` runs one, `activity --since N` reads the journal. Loaded headless in Blender (the 5.2 LTS pin) by starlab-bridge's `tools/verb_inventory.py`, into `blender.inventory.json` beside this page; `script.run` is hidden unless the operator allows scripts.*

## animate

### `anim.clear` — medium, undoable

Remove an object's animation.

| argument | type | notes |
|---|---|---|
| `object` | string | required |

    staros-tap blender verb anim.clear '{"object": "…"}'

### `anim.key` — low, undoable

Set location / rotation (degrees) / scale at a frame and key them.

| argument | type | notes |
|---|---|---|
| `frame` | integer | required |
| `location` | array |  |
| `object` | string | required |
| `rotation_deg` | array |  |
| `scale` | array |  |

    staros-tap blender verb anim.key '{"object": "…", "frame": 0}'

### `anim.range` — low, undoable

The scene's frame range, fps and current frame.

| argument | type | notes |
|---|---|---|
| `current` | integer |  |
| `end` | integer |  |
| `fps` | integer | minimum 1; maximum 240 |
| `start` | integer |  |

    staros-tap blender verb anim.range '{}'

## atelier

### `atelier.run` — medium

Run an atelier exercise in a PRIVATE headless Blender (never this scene): its steps, its gate, and with film its how-to film, put in StarSaga as story://ex-<id>. With walk, the exercise's walk instead (the demo end to end, and its devlog written again). A JOB: poll job.status, whose progress is the runner's events file (a line a step or chapter, then done); `events` names that file.

| argument | type | notes |
|---|---|---|
| `drop_last` | boolean | the selftest's red half: the last step left out |
| `events` | string | where the runner writes its progress (default under out/atelier-runs/) |
| `film` | boolean | make the how-to film (default true) |
| `id` | string | required; an exercise id (atelier.list) |
| `percent` | integer | minimum 5; maximum 100; the stills' size (default 60) |
| `to_starsaga` | boolean | put the film's story in StarSaga (default true) |
| `walk` | boolean | run the exercise's walk and write its devlog (default false) |

    staros-tap blender verb atelier.run '{"id": "…"}'

### `atelier.watch` — low

Open an exercise's film in StarSaga as its story (story://ex-<id>), to scrub it, change a caption, render it again: through StarSaga's tap, or StarSaga started on it.

| argument | type | notes |
|---|---|---|
| `id` | string | required |

    staros-tap blender verb atelier.watch '{"id": "…"}'

## camera

### `camera.frame` — low, undoable

Move the camera (the scene's unless named) back along its own axis until the named objects (or all) fit the frame, with a margin.

| argument | type | notes |
|---|---|---|
| `camera` | string |  |
| `margin` | number | minimum 1; maximum 3 |
| `objects` | array |  |

    staros-tap blender verb camera.frame '{}'

### `camera.look` — low, undoable

Make a camera (the scene's unless named) track a target object (a Track To constraint).

| argument | type | notes |
|---|---|---|
| `camera` | string |  |
| `target` | string | required |

    staros-tap blender verb camera.look '{"target": "…"}'

## file

### `file.new` — high

A fresh document from the startup file (replaces the document).

    staros-tap blender verb file.new '{}'

### `file.open` — high

Open a .blend (replaces the document; the undo history starts over).

| argument | type | notes |
|---|---|---|
| `path` | string | required |

    staros-tap blender verb file.open '{"path": "…"}'

### `file.save` — medium

Save the document as a .blend: a name under the lab's save dir, or an absolute path under it or a temp folder, or the open file itself (a tap caller's path is confined there; the operator's own panel saves anywhere).

| argument | type | notes |
|---|---|---|
| `path` | string | required |

    staros-tap blender verb file.save '{"path": "…"}'

## model

### `collection.put` — low, undoable

Put objects in a collection (created if missing; unlinked from the others).

| argument | type | notes |
|---|---|---|
| `collection` | string | required |
| `objects` | array | required |

    staros-tap blender verb collection.put '{"collection": "…", "objects": []}'

### `material.set` — low, undoable

Give an object a Principled material: base colour (rgba 0..1), metallic, roughness, emission; creates or reuses by name.

| argument | type | notes |
|---|---|---|
| `color` | array |  |
| `emission` | array |  |
| `emission_strength` | number | minimum 0 |
| `metallic` | number | minimum 0; maximum 1 |
| `name` | string |  |
| `object` | string | required |
| `roughness` | number | minimum 0; maximum 1 |

    staros-tap blender verb material.set '{"object": "…"}'

### `mesh.shade` — low, undoable

Shade a mesh smooth or flat.

| argument | type | notes |
|---|---|---|
| `object` | string | required |
| `smooth` | boolean |  |

    staros-tap blender verb mesh.shade '{"object": "…"}'

### `modifier.add` — low, undoable

Add a modifier (SUBSURF, BEVEL, ARRAY, SOLIDIFY, MIRROR, BOOLEAN, …) with parameters named as Blender names them (levels, width, count, thickness, …).

| argument | type | notes |
|---|---|---|
| `name` | string |  |
| `object` | string | required |
| `params` | object |  |
| `type` | string | required; one of SUBSURF, BEVEL, ARRAY, SOLIDIFY, MIRROR, BOOLEAN, DISPLACE, WIREFRAME, DECIMATE, SCREW, SIMPLE_DEFORM, SHRINKWRAP, SMOOTH, TRIANGULATE, WELD |

    staros-tap blender verb modifier.add '{"object": "…", "type": "SUBSURF"}'

### `modifier.apply` — medium, undoable

Apply a modifier into the mesh (irreversible except by undo).

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `object` | string | required |

    staros-tap blender verb modifier.apply '{"object": "…", "name": "…"}'

### `object.add` — low, undoable

Add a primitive (cube, plane, sphere, icosphere, cylinder, cone, torus, monkey, empty, camera, light, text), named, at a location, with a size.

| argument | type | notes |
|---|---|---|
| `light_type` | string | one of POINT, SUN, SPOT, AREA |
| `location` | array |  |
| `name` | string |  |
| `rotation_deg` | array |  |
| `size` | number | minimum 0.001 |
| `text` | string |  |
| `type` | string | required; one of camera, cone, cube, cylinder, empty, icosphere, light, monkey, plane, sphere, text, torus |

    staros-tap blender verb object.add '{"type": "camera"}'

### `object.delete` — medium, undoable

Delete objects by name.

| argument | type | notes |
|---|---|---|
| `names` | array | required |

    staros-tap blender verb object.delete '{"names": []}'

### `object.select` — low

Select objects by name (the first is active); an empty list deselects all.

| argument | type | notes |
|---|---|---|
| `names` | array | required |

    staros-tap blender verb object.select '{"names": []}'

### `object.set` — low, undoable

Set an object's location, rotation (degrees), scale, parent, name or visibility.

| argument | type | notes |
|---|---|---|
| `hidden` | boolean |  |
| `location` | array |  |
| `name` | string | required |
| `parent` | string |  |
| `rename` | string |  |
| `rotation_deg` | array |  |
| `scale` | array |  |

    staros-tap blender verb object.set '{"name": "…"}'

## read

### `asset.list` — low, read-only

The lab's exports in bridge/ (name, kind, thumb, mtime).

| argument | type | notes |
|---|---|---|
| `kind` | string | one of level, character, recording, camera, animation |

    staros-tap blender verb asset.list '{}'

### `atelier.list` — low, read-only

The atelier's runnable exercises (the bridge's exercises/*.toml): each one's title, card, skill, steps, its walk if it has one (the demo that also writes a devlog), and its last run (verdict, film).

    staros-tap blender verb atelier.list '{}'

### `atelier.show` — low, read-only

Show an exercise: first in the panel's Atelier box, its Run set to this walk and film. Runs nothing (what an atelier:// link opens); the answer names the exercise, its last run, whether its film is in StarSaga, and the verb and arguments that would run it.

| argument | type | notes |
|---|---|---|
| `film` | boolean | with its film (default true) |
| `id` | string | required; an exercise id (atelier.list) |
| `walk` | boolean | the exercise's walk (default false) |

    staros-tap blender verb atelier.show '{"id": "…"}'

### `bridge.version` — low, read-only

The running bridge's build id, the Blender version and the module it runs as.

    staros-tap blender verb bridge.version '{}'

### `element.list` — low, read-only

The element slugs the lab defines (shared.element_defs).

    staros-tap blender verb element.list '{}'

### `job.status` — low, read-only

The jobs (running, done, failed), or one by id.

| argument | type | notes |
|---|---|---|
| `job` | string |  |

    staros-tap blender verb job.status '{}'

### `render.still` — medium

A camera still to shots/<name>.png through the renderer (works headless; the scene's camera unless named). `scene` renders another scene by name, through its own camera: a background Blender cannot switch scenes, so a headless caller names the one it built. Synchronous; keep it small with percent.

| argument | type | notes |
|---|---|---|
| `camera` | string |  |
| `engine` | string | one of BLENDER_WORKBENCH, BLENDER_EEVEE_NEXT, BLENDER_EEVEE, CYCLES |
| `name` | string |  |
| `percent` | integer | minimum 5; maximum 100 |
| `scene` | string |  |

    staros-tap blender verb render.still '{}'

### `scene.query` — low, read-only

Objects with their transforms, dimensions, parents, collections, materials, modifiers, animation; all or named.

| argument | type | notes |
|---|---|---|
| `names` | array |  |
| `type` | string |  |

    staros-tap blender verb scene.query '{}'

### `scene.state` — low, read-only

A compact summary of the open scene: counts, active, selected, frame range, the edit scene, jobs, busy.

    staros-tap blender verb scene.state '{}'

### `tile.plan` — low, read-only

A tile's lid and tray as the planner reads them from its layout file, without building: the cutouts by kind, the screws, the tray's walls, bosses, mounts and port, the problems, and a mass estimate (PLA lid, PETG tray). full = true lists every cutout.

| argument | type | notes |
|---|---|---|
| `clearance_mm` | number | minimum 0; maximum 1; widen every cutout this much a side (0.2) unless the control names its own |
| `full` | boolean |  |
| `name` | string | a tile by name, found under startune/tiles (STARTUNE_TILES) |
| `path` | string | a tile's layout file (tiles/<name>.tile.toml) |

    staros-tap blender verb tile.plan '{}'

### `view.shot` — medium, read-only

A still of the 3D view to shots/<name>.png (needs a window; headless refuses).

| argument | type | notes |
|---|---|---|
| `name` | string |  |

    staros-tap blender verb view.shot '{}'

### `world.info` — low, read-only

A StarLab world's dims, format, digest (the engine's grid_hash of its cells), cells by element and its census (each element's faces as built and the world's solid shell: open and non-manifold edges, watertight), without building it.

| argument | type | notes |
|---|---|---|
| `cell` | number | minimum 0.001 |
| `census` | boolean | the census too (default true) |
| `name` | string | a world under the console's worlds folder (where world save writes) |
| `path` | string | a world folder (grid.png + meta.lua) or a starlab.world/1 cart |

    staros-tap blender verb world.info '{}'

## ui

### `ui.capture` — low

Capture a live app's next frame (its tap's ui.frame: every draw op, its colour's token, the named layers, the widgets' notes) and build it as the scene 'UI <app>'. A job.

| argument | type | notes |
|---|---|---|
| `app` | string | the app's name in ports.json (starbench, starsaga, …) |
| `every` | integer | minimum 1; maximum 60; record one draw in `every` |
| `frames` | integer | minimum 1; maximum 240; more than one: the motion, each frame at its own time, keyed in Blender |
| `images` | boolean | every canvas and image the frame drew, read back as its own texture (default true; a big canvas costs its readback) |
| `plate` | boolean | also the frame's screenshot (default true) |
| `port` | integer | minimum 1; maximum 65535; its tap port (the launcher never announces: 7321) |
| `show` | boolean | switch the window to the new scene (default true) |
| `source` | boolean | every op names the code lines that drew and coloured it (slower; the inspector shows them) |
| `text` | boolean | the text atlas: the app's own glyphs, drawn exactly (default true; false: FONT objects) |
| `timeout_s` | number | minimum 1; maximum 300 |
| `trigger` | object | a tap command the app runs after the first frame (a toast pushed, a drawer opened): the frames show its effect |

    staros-tap blender verb ui.capture '{}'

### `ui.contrast` — low, read-only

Every text in the frame against the house's floor (4.5:1), lowest first: what an edit would break, or already breaks.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.contrast '{}'

### `ui.cycle` — low

A widget's STATE CYCLE: each gated state of a bench unit (its legend's, e.g. D1-the-controls buttons.launcher-dark: rest, mid-press, released) opened on a bench runner over its tap, captured, cropped to the specimen's marked nodes, and built as one scene 'UI cycle <unit> <specimen.context>': the states in turn on the timeline (a marker each, every object keyed visible on its state's frames) or side by side (layout sheet). A job.

| argument | type | notes |
|---|---|---|
| `app` | string |  |
| `context` | string |  |
| `crop` | boolean |  |
| `frames` | integer | minimum 1; maximum 600 |
| `layout` | string | one of timeline, sheet |
| `plate` | boolean |  |
| `port` | integer | minimum 1; maximum 65535 |
| `show` | boolean |  |
| `specimen` | string |  |
| `states` | array |  |
| `unit` | string | required |

    staros-tap blender verb ui.cycle '{"unit": "…"}'

### `ui.explode` — low, undoable

Fan the frame's layers out along Z: 0 is the frame as drawn, 1 spreads every draw rank by `gap`.

| argument | type | notes |
|---|---|---|
| `amount` | number | minimum 0; maximum 1 |
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `gap` | number | minimum 0 |

    staros-tap blender verb ui.explode '{}'

### `ui.import` — low

Build a staros.ui-frame/1 document already on disk as the scene 'UI <app>'.

| argument | type | notes |
|---|---|---|
| `path` | string | required |
| `plate` | boolean |  |
| `port` | integer | minimum 1; maximum 65535 |
| `show` | boolean |  |

    staros-tap blender verb ui.import '{"path": "…"}'

### `ui.layers` — low, read-only

The frame's named layers (the error boundary's scopes, the house overlays, the editor) and their objects.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.layers '{}'

### `ui.layout` — low, read-only

The frame's layout tokens (a widget's corner and inset: love-shared [theme.corner], [theme.inset], the kit's radii), each its ladder step and px, the widgets that read it, and the corners a caller drew otherwise.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (default: the latest UI scene) |

    staros-tap blender verb ui.layout '{}'

### `ui.layout_set` — low

Send a layout token's new step to the app (its ui.set: live, unsaved): radius.2 for theme.corner.button. ui.capture shows it; ui.save writes it, ui.revert puts it back.

| argument | type | notes |
|---|---|---|
| `app` | string |  |
| `name` | string | required; the token's dotted name, as ui.layout lists it (theme.corner.button) |
| `step` | string | required; a step of its ladder (radius.N for a corner or radius, space.N for an inset, pad or space) |

    staros-tap blender verb ui.layout_set '{"name": "…", "step": "…"}'

### `ui.live` — low

Live: every swatch change goes to the app at once (debounced).

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `on` | boolean |  |

    staros-tap blender verb ui.live '{}'

### `ui.motion_read` — low, undoable

Read the Graph Editor back: each transition proxy's curve (`eased`), its two keys' distance a duration; a motion whose duration moved takes it (whole ms).

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.motion_read '{}'

### `ui.motion_set` — low, undoable

Change one of a named motion's values (ms 260, easing ease_out_cubic, law step): with Live on the app gets it as ui.set and the next motion that starts takes it; ui.save writes it through the app's one writer.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `key` | string | required; one of ms, tau_ms, period_ms, amp, duty, k, easing, law |
| `name` | string | required |
| `value` | any | required |

    staros-tap blender verb ui.motion_set '{"name": "…", "key": "ms", "value": "…"}'

### `ui.motions` — low, read-only

The app's named motions as its frame names them (tokens.toml's [motion.<use>.<name>]: a transition's ms and easing, an approach's tau_ms and law, a cycle's period, a life's ms): value, as captured, changed; a widget's own default is listed with no token to save it to.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `changed` | boolean |  |

    staros-tap blender verb ui.motions '{}'

### `ui.node` — low, read-only

What a run's object is: its kind, layer, widget (note) and touch target, its ops' provenance, tokens and source lines, and for a text its contrast against what lies beneath it.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `name` | string | required |

    staros-tap blender verb ui.node '{"name": "…"}'

### `ui.ops` — low, read-only

The edits as the writer's token ops.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.ops '{}'

### `ui.push` — low

Send every changed token to the app (ui.set): it draws them on its next frame, unsaved.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.push '{}'

### `ui.render` — low

Render the frame's scene through its camera (flat at 1:1: the app's own pixels, within 2/255 at one sample; `samples` > 1 antialiases text and edges for a picture). `path` defaults to Blender's temp folder; a tap caller's own is confined to the lab's save dir or a temp folder.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `path` | string |  |
| `samples` | integer | minimum 1; maximum 64 |

    staros-tap blender verb ui.render '{}'

### `ui.revert` — low

Put every edit back, in the scene and in the app.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |

    staros-tap blender verb ui.revert '{}'

### `ui.save` — medium

Save the edits through the app's one writer (its ui.save: scripts/ui_edit.py, the contrast floors held); dry_run reports without writing.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `dry_run` | boolean |  |

    staros-tap blender verb ui.save '{}'

### `ui.session` — low

Build a tape's session as one scene on the timeline: each checkpoint the app's own frame (scripts/app-tape.py frames <tape> writes the index and the frames), at its own time, every run shown only on the steps it was drawn in, a marker a step naming its ops.

| argument | type | notes |
|---|---|---|
| `path` | string | required; the session index (session.json) app-tape.py frames wrote |
| `plate` | boolean | the first step's plate as the reference plane, each step's for its image crops (default true) |
| `show` | boolean | switch the window to the session's scene (default true) |

    staros-tap blender verb ui.session '{"path": "…"}'

### `ui.shell` — low

Build an app's SHELL document (its seed's splits and leaves, toolbar and sheet: docs/formats/shell.md, read over its tap's ui.shell) as the scene 'UI shell <identity>': drag a divider along its split, or the toolbar's buttons and the sheet's rows into a new order, then ui.shell_read.

| argument | type | notes |
|---|---|---|
| `app` | string |  |
| `port` | integer | minimum 1; maximum 65535 |
| `show` | boolean |  |

    staros-tap blender verb ui.shell '{}'

### `ui.shell_read` — low

What moved in the shell scene, as the app's editor's own edits (ui.shell_set a ratio, ui.shell_move a row: the fewest moves); push (default) sends them and rebuilds the scene from the document the app then holds. Unsaved until ui.shell_save.

| argument | type | notes |
|---|---|---|
| `app` | string |  |
| `push` | boolean |  |

    staros-tap blender verb ui.shell_read '{}'

### `ui.shell_revert` — low

The app's revert (every unsaved edit, the shell's among them), and the shell scene rebuilt from the document as it was.

| argument | type | notes |
|---|---|---|
| `app` | string |  |

    staros-tap blender verb ui.shell_revert '{}'

### `ui.shell_save` — medium

The app's save (its ui.save: the one writer, scripts/ui_edit.py; the shell format checked first): dry_run reports without writing. Saves every unsaved edit the app holds.

| argument | type | notes |
|---|---|---|
| `app` | string |  |
| `dry_run` | boolean |  |

    staros-tap blender verb ui.shell_save '{}'

### `ui.spec` — low, read-only

The open draft: its folder, the state shown, its states, its nodes (path, kind, id, rect), the edits undo can take back, the last gate's verdict.

| argument | type | notes |
|---|---|---|
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |

    staros-tap blender verb ui.spec '{}'

### `ui.spec_add` — low

Add a node of a catalog kind, with what it needs to draw (a fresh id): into a container (`into`, default the frame; a leaf named puts it after the leaf) or after a node (`after`).

| argument | type | notes |
|---|---|---|
| `after` | string |  |
| `into` | string |  |
| `kind` | string | required |
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |
| `props` | object |  |

    staros-tap blender verb ui.spec_add '{"kind": "…"}'

### `ui.spec_gate` — low

Gate the draft as Track D gates a unit's spec (starbench/tools/spec_draft.py gate: the catalog, the fixtures twice, the floors, 24/44 pt, the mutants, every state twice and under fengari): green writes its legend; `cart` then writes it as a specimen cartridge the runner opens.

| argument | type | notes |
|---|---|---|
| `cart` | boolean |  |
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |

    staros-tap blender verb ui.spec_gate '{}'

### `ui.spec_open` — low

Open a bench DRAFT (a spec outside a unit: starbench/tools/spec_draft.py) as the scene 'UI spec <name>': the bench runner's own drawing of it at one state (when a runner is up: its tap's draft kind) with a HANDLE a node of the spec's tree, each widget riding its handle. Drag handles to reorder or move nodes, scale a leaf's to size it, then ui.spec_read; the panel edits props. `from` a unit (D1) starts a new draft from its spec.

| argument | type | notes |
|---|---|---|
| `app` | string | the runner's app name in ports.json (default starbench) |
| `context` | string |  |
| `dir` | string | required; the draft's folder: under starbench/drafts/ (the bench's habit) or a temp folder (a tap caller's is confined there) |
| `from` | string | a Track D unit whose spec a new draft starts from (D1, D4-the-panel) |
| `name` | string | the new draft's spec name (a slug; default the folder's) |
| `port` | integer | minimum 1; maximum 65535 |
| `runner` | boolean | draw through a bench runner (default true; false: the nodes alone) |
| `show` | boolean |  |
| `specimen` | string |  |
| `state` | string | <specimen>.<context> |

    staros-tap blender verb ui.spec_open '{"dir": "…"}'

### `ui.spec_read` — low

Read what the hands did to the handles as the spec's edits: each container's children in the order their handles now stand along its axis (a row across, a stack down, a grid row by row), a node dropped inside another container moved there, a leaf scaled its new w and h; written and built again.

| argument | type | notes |
|---|---|---|
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |

    staros-tap blender verb ui.spec_read '{}'

### `ui.spec_remove` — low

Remove a node (and what it holds).

| argument | type | notes |
|---|---|---|
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |
| `path` | string | required |

    staros-tap blender verb ui.spec_remove '{"path": "…"}'

### `ui.spec_set` — low

Set one prop of a node (its path, as the scene's handles name it: f.2): `value` a JSON value, or `text` as the panel types it (read by the prop's type); an empty text or a null value unsets it. Written through the bench's writer (refused by the catalog: nothing written).

| argument | type | notes |
|---|---|---|
| `key` | string | required |
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |
| `path` | string | required |
| `text` | string |  |
| `value` | any |  |

    staros-tap blender verb ui.spec_set '{"path": "…", "key": "…"}'

### `ui.spec_step` — low

Step a node's gap or pad one or more rungs up or down its ladder (space.4 -> space.5), held to the catalog's steps.

| argument | type | notes |
|---|---|---|
| `delta` | integer |  |
| `key` | string | required; one of gap, pad |
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |
| `path` | string | required |

    staros-tap blender verb ui.spec_step '{"path": "…", "key": "gap"}'

### `ui.spec_undo` — low

Put the spec back as it was before the last edit (written through the bench's writer).

| argument | type | notes |
|---|---|---|
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |

    staros-tap blender verb ui.spec_undo '{}'

### `ui.spec_view` — low

Show the draft at another state: a specimen and a context by name, or a step through them.

| argument | type | notes |
|---|---|---|
| `context` | string |  |
| `context_step` | integer |  |
| `name` | string | the draft (its spec's name or its folder); the newest spec scene when omitted |
| `specimen` | string |  |
| `specimen_step` | integer |  |

    staros-tap blender verb ui.spec_view '{}'

### `ui.token_set` — low, undoable

Change a token's colour in the scene (hex or [r, g, b(, a)] in 0..1, sRGB): every face carrying it is recoloured; with Live on the app gets it as ui.set.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `name` | string | required |
| `value` | any | required |

    staros-tap blender verb ui.token_set '{"name": "…", "value": "…"}'

### `ui.tokens` — low, read-only

The tokens the frame used: value, the value as captured, changed.

| argument | type | notes |
|---|---|---|
| `app` | string | the frame's app (its UI scene); the newest frame when omitted |
| `changed` | boolean |  |

    staros-tap blender verb ui.tokens '{}'

## view

### `view.set` — low

The 3D view's shading (WIREFRAME, SOLID, MATERIAL, RENDERED), its angle (FRONT … CAMERA, PERSP) and frame-all; needs a window.

| argument | type | notes |
|---|---|---|
| `frame_all` | boolean |  |
| `overlays` | boolean |  |
| `shading` | string | one of WIREFRAME, SOLID, MATERIAL, RENDERED |
| `view` | string | one of FRONT, BACK, LEFT, RIGHT, TOP, BOTTOM, CAMERA, PERSP |

    staros-tap blender verb view.set '{}'

## write

### `asset.export` — medium

Export the named objects (or the selection) to import/<name>.glb for the lab.

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `objects` | array |  |

    staros-tap blender verb asset.export '{"name": "…"}'

### `asset.import` — low, undoable

Import a bridge/ .glb by name into the scene; a recording is set up for video (cameras, markers, the edit scene).

| argument | type | notes |
|---|---|---|
| `name` | string | required |
| `setup_recording` | boolean |  |

    staros-tap blender verb asset.import '{"name": "…"}'

### `bridge.reload` — medium

Reload the extension from its installed files without restarting Blender (the tap stops and comes back on the new code; answered first, reloaded a moment later).

    staros-tap blender verb bridge.reload '{}'

### `camera.export_rail` — medium

Bake the named camera (or the scene camera) to a rail .glb in import/.

| argument | type | notes |
|---|---|---|
| `camera` | string |  |
| `name` | string | required |

    staros-tap blender verb camera.export_rail '{"name": "…"}'

### `edit.undo` — low

Pop undo steps (1..20).

| argument | type | notes |
|---|---|---|
| `steps` | integer | minimum 1; maximum 20 |

    staros-tap blender verb edit.undo '{}'

### `element.add` — low, undoable

Add one of the lab's elements as a mesh at a location.

| argument | type | notes |
|---|---|---|
| `location` | array |  |
| `slug` | string | required |

    staros-tap blender verb element.add '{"slug": "…"}'

### `job.cancel` — low

Cancel a running job.

| argument | type | notes |
|---|---|---|
| `job` | string | required |

    staros-tap blender verb job.cancel '{"job": "…"}'

### `recording.setup` — low, undoable

Make the named objects (or the selection) video-ready: rail camera, frame range, shot markers, the edit scene.

| argument | type | notes |
|---|---|---|
| `objects` | array |  |

    staros-tap blender verb recording.setup '{}'

### `render.edit` — medium

Render the edit scene's cut to renders/<name>.mp4. A JOB: answered at once with {job}; poll job.status. In the GUI it is Blender's own threaded render job; headless it renders in line (the tap is quiet until it ends).

| argument | type | notes |
|---|---|---|
| `engine` | string | one of BLENDER_WORKBENCH, BLENDER_EEVEE_NEXT, BLENDER_EEVEE, CYCLES |
| `frame_end` | integer | minimum 0 |
| `frame_start` | integer | minimum 0 |
| `name` | string |  |

    staros-tap blender verb render.edit '{}'

### `tile.panel` — low

Build a tile's printable lid and tray from its layout file as the scene 'Tile <name>': the lid a plate with a cutout per control (a square for a pad, a stepped MX plate cutout for a key, a round hole for an encoder, a slot for a fader, the display's window, the screw holes), the tray an open box with insert bosses under the screws, standoffs and pillars for the boards its [[mount]] entries name, and the port's cutout. Each part is held to a census (open and non-manifold edges, watertight, V-E+F) and written as a binary STL in millimetres beside a plan.json, under out_dir (the lab's save dir, tiles/<name>/, by default). A plan with problems is refused unless force.

| argument | type | notes |
|---|---|---|
| `clearance_mm` | number | minimum 0; maximum 1; widen every cutout this much a side (0.2) unless the control names its own |
| `force` | boolean |  |
| `name` | string | a tile by name, found under startune/tiles (STARTUNE_TILES) |
| `out_dir` | string | where the STLs go (the lab's save dir or the temp folder) |
| `parts` | array |  |
| `path` | string | a tile's layout file (tiles/<name>.tile.toml) |
| `show` | boolean |  |
| `write` | boolean | write the STLs and plan (default true) |

    staros-tap blender verb tile.panel '{}'

### `world.import` — low

Build a StarLab world (starlab.world/1: the console's world save, starlab-replay write, a cart) as the scene 'World <name>': an object an element, its exposed cell faces in the element library's material (EL_<slug>, both pages of shared.element_defs), WELDED (faces share their corners). Answers the decode's digest (the engine's grid_hash), each element's cells, faces and census (open and non-manifold edges, watertight: a render shows none of it), and the census of the world's solid shell (every solid as one surface: what a print or a solid export takes).

| argument | type | notes |
|---|---|---|
| `cell` | number | minimum 0.001; metres a cell (0.1) |
| `gases` | boolean | build the gases too (default true; their own collection) |
| `name` | string | a world under the console's worlds folder (where world save writes) |
| `path` | string | a world folder (grid.png + meta.lua) or a starlab.world/1 cart |
| `show` | boolean |  |
| `weld` | boolean | share each corner between the faces on it (default true; false: four vertices a face, each its own) |

    staros-tap blender verb world.import '{}'

### `world.replay` — low

Build a StarLab replay (starlab.replay/1: starlab-replay record) on the timeline as 'Replay <name>': each frame its own collection shown from its marker to the next, a Blender frame a step of the sim, every frame's decode held to the digest the reference recorded for it (a marker shows ≠ where it is not). A job.

| argument | type | notes |
|---|---|---|
| `cell` | number | minimum 0.001 |
| `frames` | integer | minimum 1; build the first N frames (default all) |
| `gases` | boolean |  |
| `path` | string | a replay folder (replay.lua + frames/) or a starlab.replay/1 cart |
| `show` | boolean |  |

    staros-tap blender verb world.replay '{}'

<details class="changes">
<summary>The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks</summary>

[[timeline: src=love-shared/docs/verbs/blender.md | kinds=commit | days=30]]

[[work: open | src=love-shared/docs/verbs/blender.md]]

[[work: checks | rows=lint/web-reference,lint/verb-sheets]]

</details>

<nav class="pager"><span></span><a href="../../">The reference</a><span></span></nav>

*Generated by `tools/reference_pages.py` from `love-shared/docs/verbs/blender.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
