scenario-blender-expert · git:20261017.c94fc7d · 2026-10-17 · sha256 79777263987ea61a
scenario-blender-expert git:20261017.c94fc7dA
Immutable. This exact content never changes and is served at /api/v1/blob/79777263987ea61a.
---
name: scenario-blender-expert
description: "Use when doing any 3D work in Blender through Python or an MCP bridge, headless or in a live session: modeling, sculpting a character or head, retopology, UV unwrapping, baking, texturing, rigging, animating, previs, geometry nodes, lighting and rendering, grease pencil, or finishing an AI-generated mesh into a production asset. Also when a bpy script fails on Blender 5.x API changes, a brush or sculpt operator fails or crashes headless, or a result has to be judged like a professional 3D artist would."
license: MIT
---
# Blender expert (router and agent protocol)
Expert-level Blender work is a loop, not a script: build big to small, and at every stage turn the
model, measure it and fix it before adding detail. This skill is the protocol every Blender task
follows and the map to the domain skills distilled from Blender Studio artists, Blender Conference
talks and top instructors (sources in each skill). If a sibling skill named here is missing from
your available skills, ask the user to install it
(`npx skills add scenario-labs/skills --skill <name>`); unattended, proceed from tool schemas and
flag the gap.
## 1. Execution channel
- **Live GUI Blender** (user's session over the MCP bridge), for anything interactive: real
sculpt/paint brushes, weight painting, viewport screenshots. One short, idempotent script per call
returning a compact result dict. Get-or-create by name. Never touch objects you did not create.
Save a stage backup `bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)` after each stage.
- **Headless helper** `blender -b [file] --factory-startup --python-exit-code 1 -P x.py -- args`,
for renders, audits, batch ops, anything when no bridge is up. Use `--factory-startup` so the
user's add-ons and preferences stay out of the run (an add-on can call the network or change
defaults); the Scenario Blender Plugin's headless server,
`blender --background scene.blend --command scenario_blender`, is the exception because it needs
the extension loaded. Without `--python-exit-code` a failing script still exits 0. Print a final
machine-readable result line.
Never open your own GUI Blender window to test things on the user's machine: windows steal focus and
pile up. Live work goes through the user's already-running Blender; everything else runs headless,
one Blender process at a time per agent (other sessions may be rendering on the same machine).
**Live channel: the Scenario Blender Plugin.** When the user's Blender runs the Scenario Blender
Plugin, its local MCP server `scenario-blender` is the bridge. Setup, quotes, generation and placing
results are the `scenario-blender` skill's work; this section covers the bpy side (guide at
[blender.scenario.com](https://blender.scenario.com/)). Its tool names differ from other Blender MCP
servers: there is no `execute_blender_code`, `get_scene_info`, `get_viewport_screenshot` or
`import_asset`.
| Step | Plugin tool and main arguments |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Read the scene before acting | `scene_summary`, then `object_detail` with `name` for one object and `datablocks_summary` for counts |
| Check an API before scripting | `blender_api_help` with `path`, such as `bpy.types.BevelModifier` |
| Run bpy | `execute_python` with `code`; `bpy` and `result = {}` are preloaded, so fill `result` |
| Look | `screenshot_viewport` (viewport with overlays), `render_still` with `source` (`CAMERA` or `VIEWPORT`), `width` and `height`; both need the GUI |
| Select, move the timeline | `select_objects` with `names` (a list), `set_frame` with `frame` |
Read each tool's input schema from the server before its first call: it is the reference for
optional arguments.
- `execute_python` stays off until the user enables **Allow connected agents to run Python** in the
plugin preferences. A `PermissionError` means ask for it or stay on the specific tools. A refused
spelling (quit, factory reset, file deletion) changed nothing: rewrite the call.
- Budget every call: the plugin stops a call after 120 s and some agent clients stop waiting after
60 s. Make one logical change per call, so one Undo reverts it, and send bakes, QuadriFlow on
dense meshes, turntables, playblasts and final renders to a headless Blender working on a saved
copy.
- A timed-out call has an unknown outcome: read the scene again before retrying, never resend it
blindly.
- The plugin's tools never save the user's own file. The live channel's stage backup
(`save_as_mainfile(..., copy=True)` through `execute_python`) writes a separate file and leaves
the open file and its unsaved state alone: it is also the saved copy that headless work starts
from. Ask the user to save their own file at milestones; with no one to ask, keep working from the
copies and say in the report that the open file is still unsaved.
Check `bpy.app.version` first; this skill set targets 5.2 LTS, while the Scenario Blender Plugin
also runs on 5.0 and 5.1 (`scene_summary` reports the version), so check the version timeline in the
deltas before using a recent API. Many tutorials the experts recorded use 2.8x to 4.2 UI: read
[`references/blender-5.2-deltas.md`](references/blender-5.2-deltas.md) before trusting any
remembered operator, brush name or API.
**Verified capability matrix (Blender 5.2.1):**
| Action | Headless | GUI session |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------- |
| Voxel remesh, QuadriFlow, multires subdivide, modifiers, bmesh, UV ops with edit-mode context, Cycles/EEVEE/Workbench renders, baking | yes | yes |
| `bpy.ops.brush.asset_activate`, dyntopo toggle | yes | yes |
| Brush strokes (`sculpt.brush_stroke`, `paint.image_paint`, `paint.weight_paint`) | no (poll fails) | yes, via [`scripts/bx_gui.py`](scripts/bx_gui.py) |
| `paint.mask_flood_fill`, `sculpt.mesh_filter` | CRASHES Blender | yes, via `bx_gui.run()` |
| Programmatic sculpting on mesh data | yes, `scenario-blender-sculpting/scripts/bx_sculpt.py` | yes |
## 2. The expert loop (every domain)
1. **Establish the brief** in numbers: purpose (film, game engine, still, animation), budgets (tris,
texture size, frame range), style (stylized or realistic), references. When the brief is silent,
choose a documented default from the domain skill and write it down.
2. **Plan the stages** the domain skill defines. Never start with detail.
3. **Build one stage** with the smallest scripts that do it.
4. **Gate the stage:** run the measurable checks ([`scripts/bx_audit.py`](scripts/bx_audit.py) for
meshes, the domain's own checks) AND render a review sheet
([`scripts/bx_review.py`](scripts/bx_review.py): silhouette, matcap, wire from
front/side/three-quarter/low) and open it with the image reader. Experts orbit constantly; the
review sheet is the agent's orbit. Every image read stays in the agent's context: for quick looks
use `render_still` at about 768 px wide or `screenshot_viewport`, and keep review sheets near
1600 px (`res=400` for four views and three modes). Judge with the domain's
`references/critique.md`.
5. **Fix before advancing.** A problem found at blockout costs one script; found after texturing it
costs the stage.
6. **Deliver with evidence:** final renders, audit numbers, and what was not verified.
Never report a model, rig, animation or render as done without having looked at a render of it.
## 3. Persona pipelines
| Persona / brief | Skill chain | Deliverable |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Character artist, stylized or realistic | scenario-blender-sculpting, scenario-blender-retopology, scenario-blender-uv-baking, scenario-blender-texturing-shading, scenario-blender-hair | sculpt, animation-ready low poly, UVs, baked maps, materials |
| AI-mesh finisher (Scenario 3D output to production) | audit the generated mesh, scenario-blender-retopology (or cleanup + remesh), scenario-blender-uv-baking (bake FROM the generated high), scenario-blender-texturing-shading; generation itself: scenario-3d | clean, UV'd, baked asset at a stated budget |
| Game asset artist | scenario-blender-hard-surface or scenario-blender-sculpting, scenario-blender-retopology (game budget), scenario-blender-uv-baking, scenario-blender-texturing-shading | low poly + PBR set, exported glTF/FBX |
| Rigger / character TD | scenario-blender-rigging | rig with controls, weights, deformation tests |
| Animator | scenario-blender-previs-storyboard (shot planning), scenario-blender-animation | blocked, splined, polished shot + playblast |
| Story / previs artist | scenario-blender-previs-storyboard, scenario-blender-grease-pencil | shots, cameras, animatic |
| Look-dev and lighting artist | scenario-blender-texturing-shading, scenario-blender-lighting-rendering | lit, color-managed, composited renders |
| Technical artist / procedural | scenario-blender-geometry-nodes | node-group assets, procedural systems |
| 2D / 2.5D animator | scenario-blender-grease-pencil | GP animation |
Related skills outside this set: scenario-3d (generate meshes to finish here), scenario-textures (AI
textures), text-image-to-blender-blockout (camera-locked blockouts for render-to-real video).
## 4. Shared toolkit (`scripts/`, all tested on 5.2.1)
- `bx_audit.py`: `audit(obj, high=None)` returns quads %, n-gons, poles (valence 3 / 5+ / 6+),
non-manifold, loose, duplicates, flipped faces, self-intersections, boundary loops, symmetry %,
edge-length CV, and fidelity to a high poly; `verdict(report)` lists problems. CLI:
`blender -b f.blend --python bx_audit.py -- --object Name [--high Sculpt] [--json out.json]`.
- `bx_review.py`: `review(objs, out_dir, views, modes)` writes one contact sheet (rows = modes, cols
= views) in a temporary scene, user settings untouched; `playblast(out_path, res_pct=50)`;
`turntable(obj, out_path, frames=72, res=720)`. Only `review` has a command line: call the others
from a short wrapper script.
- `bx_gui.py`: real brushes in a live session: `set_view`, `activate_brush(mode, name)`,
`stroke(mode, world_points, size, strength)`, `run(op, **kw)`, `set_paint_color`, `screenshot`.
Import pattern: `import sys; sys.path.append("<this skill>/scripts"); import bx_audit, bx_review`.
Replace `<this skill>` with the absolute path of the installed skill folder: Blender's Python does
not share the agent's working directory, and over a live bridge the code runs inside the user's
Blender. Check the path in the first call (`result["ok"] = os.path.isdir(path)`) and
`importlib.reload` a module after the skill updates.
## 5. Version traps that break most remembered code
- Brushes are assets (4.3):
`bpy.ops.brush.asset_activate(asset_library_type='ESSENTIALS', asset_library_identifier="", relative_asset_identifier="brushes/essentials_brushes-mesh_sculpt.blend/Brush/Clay Strips")`;
brush size is a diameter (5.0); Flatten/Fill/Scrape merged into the Plane type.
- Auto Smooth removed (4.1): `mesh.shade_smooth()` / Smooth by Angle modifier; voxel remesh output
is flat-shaded until you call `shade_smooth()`.
- Principled BSDF v2 (4.0): address sockets by name; Emission strength defaults to 0.
- `BLENDER_EEVEE` is the EEVEE Next identifier in 5.x (`BLENDER_EEVEE_NEXT` fails).
- Compositor is a node group (5.0): `scene.compositing_node_group`, not `scene.node_tree`.
- Video output: set `image_settings.media_type = 'VIDEO'` before `file_format = 'FFMPEG'` (5.0).
- Slotted actions (4.4), `action.fcurves` removed (5.0): use
`bpy_extras.anim_utils.action_get_channelbag_for_slot(action, slot)`.
- Bone collections replace armature layers (4.0); Grease Pencil v3 is `GREASEPENCIL` with
`bpy.ops.grease_pencil.*` (4.3).
- Positional context dicts for operators are gone: `with bpy.context.temp_override(...)`.
- `obj.matrix_world` is stale right after setting location/scale until `view_layer.update()`.
## References
- [`references/bpy-reliability.md`](references/bpy-reliability.md): checklist and tested procedures
for reliable bpy (operators vs data API, stale references, evaluated vs original data, idempotent
headless jobs, numpy bulk access, node trees, persistence). Load before writing any non-trivial
script.
- `references/blender-5.2-deltas.md`: full, cited list of what changed from 2.8x to 5.2 per domain
(load before writing code from memory or following an old tutorial).