Back to Details

scenario-blender-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blender expert (router and agent protocol)

Blender 专家（路由器与 Agent 协议）

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.
专家级 Blender 工作是一个循环，而不是一段脚本：先从大处搭建，再逐步细化，并且在每个阶段都要旋转模型、测量模型并修复问题，然后才添加细节。该 skill 是所有 Blender 任务都应遵循的协议，也是一张领域 skill 地图；这些领域 skill 提炼自 Blender Studio 艺术家、Blender Conference 演讲和顶尖讲师的经验（各 skill 中均附有来源）。如果此处提到的某个同级 skill 不在可用 skill 列表中，请让用户安装它（
npx skills add scenario-labs/skills --skill <name>
）；在无人值守的情况下，则根据 tool schema 继续执行，并明确指出这一缺口。

1. Execution channel

1. 执行通道

ChannelUse forRules
Live GUI Blender (user's session over the MCP bridge)anything interactive: real sculpt/paint brushes, weight painting, viewport screenshotsOne 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
renders, audits, batch ops, anything when no bridge is upAlways 
--factory-startup
: without it the user's add-ons load (on this machine one of them makes network API calls). 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).
Check 
bpy.app.version
first; this skill set targets 5.2 LTS. Many tutorials the experts recorded use 2.8x to 4.2 UI: read 
references/blender-5.2-deltas.md
 before trusting any remembered operator, brush name or API.
Verified capability matrix (Blender 5.2.1):
ActionHeadlessGUI session
Voxel remesh, QuadriFlow, multires subdivide, modifiers, bmesh, UV ops with edit-mode context, Cycles/EEVEE/Workbench renders, bakingyesyes
bpy.ops.brush.asset_activate
, dyntopo toggle		yesyes
Brush strokes (
sculpt.brush_stroke
, 
paint.image_paint
, 
paint.weight_paint
)		no (poll fails)yes, via 
scripts/bx_gui.py
paint.mask_flood_fill
, 
sculpt.mesh_filter
CRASHES Blenderyes, via 
bx_gui.run()
Programmatic sculpting on mesh datayes, 
scenario-blender-sculpting/scripts/bx_sculpt.py
yes
执行通道用途规则
Live GUI Blender（通过 MCP bridge 操作用户的会话）任何交互式操作：真实 Sculpt/Paint Brush、权重绘制、视口截图每次调用只运行一个简短、幂等的脚本，并返回紧凑的结果字典。按名称执行 get-or-create。绝不触碰并非由你创建的对象。每个阶段后使用 
bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)
保存阶段性备份。
Headless helper 
blender -b [file] --factory-startup --python-exit-code 1 -P x.py -- args
渲染、审计、批处理操作，以及 bridge 不可用时的所有任务始终使用 
--factory-startup
：否则用户的 add-on 会被加载（在此机器上，其中一个会发起 network API 调用）。缺少 
--python-exit-code
时，即使脚本失败仍会以 0 退出。最后打印一行机器可读的结果。
绝不要在用户机器上自行打开 GUI Blender 窗口进行测试：窗口会抢占焦点并不断堆积。实时工作应通过用户已经运行的 Blender 进行；其他所有工作均以 headless 方式运行，每个 Agent 同时只能运行一个 Blender 进程（同一机器上的其他会话可能正在渲染）。
首先检查 
bpy.app.version
；本 skill 集以 5.2 LTS 为目标。专家录制的许多教程使用的是 2.8x 至 4.2 UI：在信任任何凭记忆掌握的 operator、brush 名称或 API 之前，先阅读 
references/blender-5.2-deltas.md
。
已验证的能力矩阵（Blender 5.2.1）：
操作HeadlessGUI 会话
Voxel remesh、QuadriFlow、多分辨率细分、修改器、bmesh、带 edit-mode context 的 UV 操作、Cycles/EEVEE/Workbench 渲染、baking是是
bpy.ops.brush.asset_activate
、dyntopo 开关		是是
Brush stroke（
sculpt.brush_stroke
、
paint.image_paint
、
paint.weight_paint
）		否（poll 失败）是，通过 
scripts/bx_gui.py
paint.mask_flood_fill
、
sculpt.mesh_filter
会导致 Blender 崩溃是，通过 
bx_gui.run()
对 mesh data 进行程序化雕刻是，
scenario-blender-sculpting/scripts/bx_sculpt.py
是

2. The expert loop (every domain)

2. 专家工作循环（所有领域）

  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
     for meshes, the domain's own checks) AND render a review sheet (
    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. 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.
  1. 用数字明确需求：用途（电影、游戏引擎、静帧、动画）、预算（三角形数、纹理尺寸、帧范围）、风格（风格化或写实）、参考资料。当需求未说明时，从领域 skill 中选择一个有文档记录的默认值并写下来。
  2. 规划阶段：按领域 skill 定义的方式规划各个阶段。绝不要从细节开始。
  3. 构建单个阶段：使用能够完成该阶段的最小脚本。
  4. 为阶段设置关卡：运行可量化的检查（网格使用 
    scripts/bx_audit.py
    ，并使用该领域自身的检查）并渲染一张审阅图（
    scripts/bx_review.py
    ：从正面、侧面、四分之三视角和低视角呈现 silhouette、matcap、wire），然后用 image reader 打开。专家会持续环绕观察；审阅图就是 Agent 的环绕视角。依据该领域的 
    references/critique.md
    进行评判。
  5. 推进之前先修复。 在 blockout 阶段发现的问题只需一个脚本；等到贴图完成后才发现，就会损失整个阶段。
  6. **交付时附上证据：**最终渲染、审计数值，以及尚未验证的内容。
绝不能在没有查看过模型、rig、动画或渲染结果的情况下，宣称其已完成。

3. Persona pipelines

3. 角色工作流

Persona / briefSkill chainDeliverable
Character artist, stylized or realisticscenario-blender-sculpting, scenario-blender-retopology, scenario-blender-uv-baking, scenario-blender-texturing-shading, scenario-blender-hairsculpt, 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-3dclean, UV'd, baked asset at a stated budget
Game asset artistscenario-blender-hard-surface or scenario-blender-sculpting, scenario-blender-retopology (game budget), scenario-blender-uv-baking, scenario-blender-texturing-shadinglow poly + PBR set, exported glTF/FBX
Rigger / character TDscenario-blender-riggingrig with controls, weights, deformation tests
Animatorscenario-blender-previs-storyboard (shot planning), scenario-blender-animationblocked, splined, polished shot + playblast
Story / previs artistscenario-blender-previs-storyboard, scenario-blender-grease-pencilshots, cameras, animatic
Look-dev and lighting artistscenario-blender-texturing-shading, scenario-blender-lighting-renderinglit, color-managed, composited renders
Technical artist / proceduralscenario-blender-geometry-nodesnode-group assets, procedural systems
2D / 2.5D animatorscenario-blender-grease-pencilGP 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).
角色/需求Skill 链交付物
角色艺术家（风格化或写实）scenario-blender-sculpting、scenario-blender-retopology、scenario-blender-uv-baking、scenario-blender-texturing-shading、scenario-blender-hair雕刻成果、可用于动画的 low poly、UV、baked maps、材质
AI mesh 完善师（将 Scenario 3D 输出投入生产）审计生成的 mesh、scenario-blender-retopology（或 cleanup + remesh）、scenario-blender-uv-baking（从生成的高模 bake）、scenario-blender-texturing-shading；生成本身：scenario-3d在既定预算下完成清理、UV 展开和 bake 的资产
游戏资产艺术家scenario-blender-hard-surface 或 scenario-blender-sculpting、scenario-blender-retopology（游戏预算）、scenario-blender-uv-baking、scenario-blender-texturing-shadinglow poly + PBR 贴图集，导出 glTF/FBX
Rigger/角色 TDscenario-blender-rigging带 controls、weights 和 deformation tests 的 rig
动画师scenario-blender-previs-storyboard（镜头规划）、scenario-blender-animation完成 blocking、spline 处理和润色的镜头 + playblast
故事/Previs 艺术家scenario-blender-previs-storyboard、scenario-blender-grease-pencil镜头、摄像机、animatic
Look-dev 与灯光艺术家scenario-blender-texturing-shading、scenario-blender-lighting-rendering完成布光、色彩管理和合成的渲染
技术美术/程序化scenario-blender-geometry-nodes节点组资产、程序化系统
2D/2.5D 动画师scenario-blender-grease-pencilGP 动画
本 skill 集之外的相关 skill：scenario-3d（生成网格以在此处完善）、scenario-textures（AI 纹理）、text-image-to-blender-blockout（用于 render-to-real 视频的 camera-locked blockout）。

4. Shared toolkit (
scripts/
, all tested on 5.2.1)

4. 共享工具包（
scripts/
，全部在 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(path)
    ; 
    turntable(obj, path)
    .
  • 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
.
  • bx_audit.py
    ：
    audit(obj, high=None)
    返回四边形占比、n-gon、极点（valence 3 / 5+ / 6+）、非流形、游离几何、重复项、翻转面、自交、边界循环、对称率、边长 CV，以及与 high poly 的保真度；
    verdict(report)
    列出问题。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)
    在临时 scene 中写入一张 contact sheet（行 = 模式，列 = 视角），且不改动用户设置；
    playblast(path)
    ；
    turntable(obj, path)
    。
  • bx_gui.py
    ：在实时会话中使用真实 Brush：
    set_view
    、
    activate_brush(mode, name)
    、
    stroke(mode, world_points, size, strength)
    、
    run(op, **kw)
    、
    set_paint_color
    、
    screenshot
    。
导入方式：
import sys; sys.path.append("<this skill>/scripts"); import bx_audit, bx_review
。

5. Version traps that break most remembered code

5. 令大多数凭记忆编写的代码失效的版本陷阱

  • 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()
    .
  • Brush 在 4.3 中是 asset：
    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 是直径（5.0）；Flatten/Fill/Scrape 已合并到 Plane type。
  • Auto Smooth 已移除（4.1）：使用 
    mesh.shade_smooth()
    / Smooth by Angle modifier；voxel remesh 输出采用 flat shading，直到调用 
    shade_smooth()
    。
  • Principled BSDF v2（4.0）：按名称引用 socket；Emission strength 默认值为 0。
  • 在 5.x 中，
    BLENDER_EEVEE
    是 EEVEE Next 的标识符（
    BLENDER_EEVEE_NEXT
    会失败）。
  • Compositor 在 5.0 中是 node group：使用 
    scene.compositing_node_group
    ，而不是 
    scene.node_tree
    。
  • 视频输出：先设置 
    image_settings.media_type = 'VIDEO'
    ，再设置 
    file_format = 'FFMPEG'
    （5.0）。
  • Slotted actions（4.4）以及 
    action.fcurves
    已移除（5.0）：使用 
    bpy_extras.anim_utils.action_get_channelbag_for_slot(action, slot)
    。
  • Bone collections 取代 armature layers（4.0）；Grease Pencil v3 是 
    GREASEPENCIL
    ，搭配 
    bpy.ops.grease_pencil.*
    （4.3）。
  • operator 的位置型 context dict 已移除：使用 
    with bpy.context.temp_override(...)
    。
  • 设置 location/scale 后，
    obj.matrix_world
    会立即过期，直到调用 
    view_layer.update()
    。

References

参考资料

  • 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).
  • references/bpy-reliability.md
    ：可靠 bpy 的检查清单和经过测试的流程（operator 与 data API、过期引用、evaluated 与 original data、幂等 headless 作业、numpy 批量访问、节点树、持久化）。编写任何非平凡脚本之前先加载。
  • references/blender-5.2-deltas.md
    ：完整的、带引用的变更清单，涵盖从 2.8x 到 5.2 各领域的差异（根据记忆编写代码或遵循旧教程之前先加载）。