Back to Details

text-to-blender

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Text-to-Blender Orchestrator

文本转Blender协调器

Turn plain-English requests into Blender work. You are the conductor: read the request, decide which sub-skills to chain-load, sequence them in the right order, and execute via the Blender MCP.
将通俗易懂的英文请求转化为Blender操作。你作为协调者：读取请求，决定链式加载哪些子技能，按正确顺序排列，并通过Blender MCP执行。

Multi-skill harmonization

多技能协调

For complex tasks that trigger multiple Blender skills, especially reference/template/brand work, load 
blender-skill-harmonizer
before choosing the execution order. It owns precedence, handoff artifacts, and conflict policy.
If the user rejects an output as sub-par, says the same issue is recurring, or asks to improve the skill stack before retrying, load 
quality-refinement-autoloop
before further product work. It turns evidence into a sanitized reusable lesson, patches generic skills/docs/versioning when explicitly requested, and only then resumes the Blender repair loop.
对于触发多个Blender技能的复杂任务，尤其是参考/模板/品牌相关工作，请在选择执行顺序前加载
blender-skill-harmonizer
。它负责优先级处理、任务交接工件和冲突策略。
如果用户认为输出质量不佳、表示同一问题反复出现，或要求在重试前优化技能栈，请在进一步操作前加载
quality-refinement-autoloop
。它会将问题证据转化为可复用的标准化经验，在明确请求时修补通用技能/文档/版本控制，之后再恢复Blender修复流程。

How this skill works

本技能工作流程

The user speaks in tasks ("render a hero shot of a sword on a stone"); you:
  1. Identify intent → which capabilities are needed (modeling? materials? lighting? rendering? export?).
  2. Check prerequisites → MCP server reachable, scene state.
  3. Reset world to a known-good baseline (see World reset below) — prevents leftover broken HDRI / Environment Texture nodes from previous runs corrupting the render.
  4. Look up real-world dimensions for the subject (
    references/common-object-dimensions.md
    ) BEFORE generating Python. A "sword" has specific proportions; a "chair" has specific proportions; do not guess.
  5. Route to sub-skills → load the relevant ones via 
    Read
    and follow their instructions.
  6. Sequence the work in the order pros use (see 
    references/assembly-order.md
    ).
  7. Execute generated Python via 
    mcp__blender__execute_blender_code
    .
  8. Validate with 
    mcp__blender__get_scene_info
    , 
    get_object_info
    , AND 
    get_viewport_screenshot
     — see Visual validation checkpoint below. Numerical validation alone is not enough: the API can report success while geometry is grossly wrong.
  9. Iterate — if the visual check shows an obvious problem (subject barely visible, wrong proportions, wrong orientation), fix and re-render BEFORE reporting success.
  10. Report to the user with concrete numbers AND a path to the proof render they can inspect.
用户提出任务（如“渲染石头上的剑的特写镜头”），你需要：
  1. 识别意图 → 需要哪些功能（建模？材质？灯光？渲染？导出？）。
  2. 检查先决条件 → MCP服务器是否可达、场景状态。
  3. 重置场景至已知良好基准（见下方「场景重置」）——避免之前运行留下的损坏HDRI/环境纹理节点破坏渲染效果。
  4. 查找对象真实尺寸（参考
    references/common-object-dimensions.md
    ）在生成Python代码之前。“剑”有特定比例；“椅子”也有特定比例；请勿猜测。
  5. 路由到子技能 → 通过
    Read
    加载相关子技能并遵循其指示。
  6. 排序 → 按照专业人员的操作顺序执行（见
    references/assembly-order.md
    ）。
  7. 执行 → 通过
    mcp__blender__execute_blender_code
    运行生成的Python代码。
  8. 验证 → 使用
    mcp__blender__get_scene_info
    、
    get_object_info
    以及**
    get_viewport_screenshot
    **——见下方「视觉验证检查点」。仅数值验证不够：API可能报告成功，但几何体可能严重错误。
  9. 迭代 —— 如果视觉检查发现明显问题（对象几乎不可见、比例错误、方向错误），请修复并重新渲染，然后再报告成功。
  10. 汇报 → 向用户提供具体数据以及他们可查看的渲染成果路径。

World reset (always step 3, before any composition)

场景重置（始终为第3步，在任何合成操作之前）

Previous tests can leave the scene's world in a broken state — particularly an 
Environment Texture
node with 
image=None
cascading into Background, which produces a magenta-flooded render. Reset world to a neutral baseline at the start of every scene-build:
python
def reset_world(scene, color=(0.04, 0.04, 0.05, 1.0), strength=0.4):
    world = scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    for n in list(nodes):
        nodes.remove(n)
    output = nodes.new('ShaderNodeOutputWorld')
    bg = nodes.new('ShaderNodeBackground')
    bg.inputs['Color'].default_value = color
    bg.inputs['Strength'].default_value = strength
    world.node_tree.links.new(bg.outputs['Background'], output.inputs['Surface'])
If the user wants HDRI lighting, override this AFTER it runs (load the actual 
.hdr
file and verify 
env.image is not None
).
之前的测试可能会导致场景世界处于损坏状态——尤其是
Environment Texture
节点的
image=None
会导致背景出现洋红色泛滥的渲染问题。在每次场景构建开始时，将世界重置为中性基准：
python
def reset_world(scene, color=(0.04, 0.04, 0.05, 1.0), strength=0.4):
    world = scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    for n in list(nodes):
        nodes.remove(n)
    output = nodes.new('ShaderNodeOutputWorld')
    bg = nodes.new('ShaderNodeBackground')
    bg.inputs['Color'].default_value = color
    bg.inputs['Strength'].default_value = strength
    world.node_tree.links.new(bg.outputs['Background'], output.inputs['Surface'])
如果用户需要HDRI灯光，请在重置完成后覆盖此设置（加载实际的
.hdr
文件并验证
env.image is not None
）。

Visual validation checkpoint (always between steps 8 and 10)

视觉验证检查点（始终在第8步和第10步之间）

After rendering, always:
  1. Call 
    mcp__blender__get_viewport_screenshot
    (or read the rendered file with 
    Read
    ).
  2. Visually verify against the user's request. Specifically:
    • Subject is visible and recognisable (not a thin streak, not magenta-flooded, not entirely in shadow)
    • Proportions match the real-world reference dimensions for that subject
    • Composition is reasonable (subject in frame, not clipped at edges, not microscopic in one corner)
    • Materials have visible variation (not perfectly flat plastic-looking surfaces) — for production-quality scenes, add procedural texture nodes
  3. If the render is obviously wrong, do NOT report success. Iterate: identify the specific problem, fix it, re-render, re-check.
A render passing every numerical check (object count, vertex count, file size, no error messages) can still look completely wrong. The user only sees the picture. Make sure the picture matches the request before declaring done.
渲染完成后，必须：
  1. 调用
    mcp__blender__get_viewport_screenshot
    （或通过
    Read
    读取渲染文件）。
  2. 对照用户请求进行视觉验证，具体包括：
    • 对象可见且可识别（不是细线条、没有洋红色泛滥、未完全处于阴影中）
    • 比例与该对象的真实参考尺寸匹配
    • 构图合理（对象在画面中、未被边缘裁剪、未缩放在角落）
    • 材质有可见变化（不是完全平坦的塑料质感表面）——对于生产级场景，添加程序化纹理节点
  3. 如果渲染明显错误，请勿报告成功。迭代修复：识别具体问题，修复后重新渲染并再次检查。
即使所有数值检查（对象数量、顶点数量、文件大小、无错误信息）都通过，渲染结果仍可能完全不符合预期。用户只看最终画面，请确保画面符合请求后再宣告完成。

Set viewport to Material Preview mode (last step before reporting)

将视口设置为材质预览模式（汇报前的最后一步）

The user is often looking at Blender's viewport, not the rendered file. Blender defaults the viewport to Solid shading mode which ignores all materials and shows everything as flat grey. After scene assembly, switch the viewport to Material Preview so the user actually sees the materials they got:
python
import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'           # or 'RENDERED' for full quality
                space.shading.use_scene_lights = True
                space.shading.use_scene_world = True
Skip this only when the user has explicitly asked you to leave the viewport alone.
用户通常查看Blender的视口而非渲染文件。Blender默认视口为实体着色模式，会忽略所有材质，显示为纯灰色。场景组装完成后，将视口切换为材质预览模式，让用户能实际看到应用的材质：
python
import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'           # 或选择'RENDERED'以获得完整画质
                space.shading.use_scene_lights = True
                space.shading.use_scene_world = True
仅当用户明确要求保留视口设置时才跳过此步骤。

Real-world dimension lookup

真实尺寸查找

Before sizing any subject from natural language, consult 
references/common-object-dimensions.md
. It lists realistic proportions for common requests:
SubjectTotalNotes
One-handed sword~95-100 cm longBlade 78cm × 4.5cm × 0.8cm; guard 20cm × 2.5cm; grip 13cm; pommel 5.6cm
Chairseat ~45cm × 45cm × 4cmSeat height 45cm; back ~45cm tall
Bottle25-30cm tallBody ø8-10cm; neck ø2-3cm
The full reference list lives in 
references/common-object-dimensions.md
. Do not guess.
在根据自然语言确定任何对象的尺寸之前，请查阅
references/common-object-dimensions.md
。其中列出了常见请求对象的真实比例：
对象尺寸说明
单手剑约95-100厘米长剑身78cm × 4.5cm × 0.8cm；护手20cm × 2.5cm；握柄13cm；剑柄尾端5.6cm
椅子座椅约45cm × 45cm × 4cm座椅高度45cm；椅背约45cm高
瓶子25-30厘米高瓶身直径8-10cm；瓶颈直径2-3cm
完整参考列表位于
references/common-object-dimensions.md
，请勿猜测。

Prerequisites — always check first

先决条件——始终先检查

Before any work, verify:
  1. Blender MCP is reachable. Call 
    mcp__blender__get_scene_info
    . If it errors with "Could not connect to Blender":
    "Blender's MCP addon isn't running. Start Blender, enable the BlenderMCP addon (port 9876 default), then re-run."
    Stop and ask the user to fix this.
  2. Scene state. 
    get_scene_info
    returns the current objects. Decide:
    • Empty scene? → Start fresh; build from primitives.
    • Existing objects? → Operate on them; do NOT delete unless asked.
    • Default cube only? → Probably safe to delete (
      bpy.ops.object.delete()
      ).
  3. The user's actual request. If ambiguous, ask one question. Otherwise proceed with sensible defaults.
开始任何工作前，请验证：
  1. Blender MCP是否可达。调用
    mcp__blender__get_scene_info
    。如果返回错误“Could not connect to Blender”：
    "Blender的MCP插件未运行。请启动Blender，启用BlenderMCP插件（默认端口9876），然后重新运行。"
    停止操作并请用户解决此问题。
  2. 场景状态。
    get_scene_info
    会返回当前对象。请判断：
    • 空场景？ → 从头开始；从基本几何体构建。
    • 已有对象？ → 对其进行操作；除非用户要求，否则请勿删除。
    • 仅默认立方体？ → 通常可以安全删除（
      bpy.ops.object.delete()
      ）。
  3. 用户的实际请求。如果请求模糊，请询问一个问题。否则使用合理默认值继续。

Intent → sub-skill routing table

意图→子技能路由表

For each intent the user expresses, load (via 
Read
) the matching sub-skill's 
SKILL.md
and follow its patterns. Multiple intents = chain multiple sub-skills.
User intent (paraphrased)Load these sub-skillsOrder
"Make a 3D model of X"
blender-modeling
1st
"From this wireframe drawing"
wireframe-to-3d
1st
"Use these materials / make it look like X"
blender-materials
After modeling
"Light it / studio setup / cinematic"
blender-lighting
After geometry exists
"Hero shot / camera angle / DoF"
blender-cameras
After lighting
"Render it / produce an image"
blender-rendering
Last visual step
"Animate / move / rotate over time"
blender-animation
After geometry
"Export as glTF / FBX / OBJ / for web / for Unity"
blender-export
Final step
"Set up a scene / production-quality result"
blender-pro-workflow
First — guides everything
"I'm new / not sure where to start"
blender-pro-workflow
First
"This is sub-par / still wrong / same issue again"
quality-refinement-autoloop
, then 
blender-skill-harmonizer
First — learn, sanitize, patch, then retry
"Match these templates / wireframes / textures exactly"
blender-skill-harmonizer
, then reference-specific fit skills		First — establish source-of-truth gates
Multi-intent example: "Model a sword with materials, light it dramatically, and export as glTF" →
  1. blender-pro-workflow
    (sequencing strategy)
  2. blender-modeling
    (sword geometry)
  3. blender-materials
    (steel + leather grip)
  4. blender-lighting
    (dramatic 1-point or rim setup)
  5. blender-export
    (glTF settings)
对于用户表达的每个意图，通过
Read
加载匹配子技能的
SKILL.md
并遵循其模式。多个意图=链式加载多个子技能。
用户意图（转述）加载的子技能顺序
"创建X的3D模型"
blender-modeling
第1步
"根据此线稿图创建"
wireframe-to-3d
第1步
"使用这些材质/让它看起来像X"
blender-materials
建模之后
"打光/工作室设置/电影级效果"
blender-lighting
几何体创建之后
"特写镜头/相机角度/景深"
blender-cameras
打光之后
"渲染/生成图像"
blender-rendering
最后视觉步骤
"制作动画/移动/随时间旋转"
blender-animation
几何体创建之后
"导出为glTF/FBX/OBJ/用于web/用于Unity"
blender-export
最终步骤
"搭建场景/生产级成果"
blender-pro-workflow
第一步——指导所有操作
"我是新手/不确定从哪里开始"
blender-pro-workflow
第一步
"这个质量不佳/仍然错误/同一问题再次出现"
quality-refinement-autoloop
，然后是
blender-skill-harmonizer
第一步——学习、标准化、修补，然后重试
"完全匹配这些模板/线稿/纹理"
blender-skill-harmonizer
，然后是参考特定适配技能		第一步——建立事实来源标准
多意图示例："建模一把带材质的剑，进行戏剧性打光，并导出为glTF格式" →
  1. blender-pro-workflow
    （排序策略）
  2. blender-modeling
    （剑的几何体）
  3. blender-materials
    （钢材质+皮革握柄）
  4. blender-lighting
    （戏剧性单点光或轮廓光设置）
  5. blender-export
    （glTF设置）

Pro assembly order (when in doubt)

专业组装顺序（不确定时遵循）

This order minimizes rework. When the user gives a multi-step request, follow it:
  1. Reference + plan — note the goal.
  2. Block-out — primitives + camera + composition. Cheapest to iterate.
  3. Camera lock — pick focal length, frame the shot.
  4. Light v1 — three-point (key/fill/rim) before any material work. Light defines mood.
  5. Refine geometry — replace primitives with real models.
  6. Materials v1 — flat colors first, get values right.
  7. Light v2 — color + ratios.
  8. Detail pass — only after the above is right.
  9. Final render — production samples + denoise.
  10. Composite — color grade, glare, vignette.
  11. Export — for the target platform.
Source: 
references/assembly-order.md
(deeper rationale).
此顺序可最大限度减少返工。当用户提出多步骤请求时，请遵循此顺序：
  1. 参考+规划 —— 明确目标。
  2. 粗模搭建 —— 基本几何体+相机+构图。此阶段迭代成本最低。
  3. 锁定相机 —— 选择焦距，取景。
  4. 灯光v1 —— 在任何材质工作前设置三点布光（主光/补光/轮廓光）。灯光决定氛围。
  5. 细化几何体 —— 用真实模型替换基本几何体。
  6. 材质v1 —— 先使用纯色，确保数值正确。
  7. 灯光v2 —— 调整颜色+比例。
  8. 细节处理 —— 仅在上述步骤完成后进行。
  9. 最终渲染 —— 生产级采样+降噪。
  10. 合成 —— 颜色分级、眩光、暗角。
  11. 导出 —— 针对目标平台。
来源：
references/assembly-order.md
（更详细的原理说明）。

Code-execution rules — non-negotiable

代码执行规则——不可协商

When emitting Python for 
mcp__blender__execute_blender_code
:
  • Each call is a fresh namespace. Only 
    bpy
    is pre-imported; re-import 
    math
    , 
    bmesh
    , 
    numpy
    , etc. each call.
  • Identify objects by stable name, never by Python variable. 
    bpy.data.objects['GEO-sword']
    works across calls; a 
    sword = ...
    assignment does not.
  • Print structured output so you can parse it back. End each chunk with 
    print(f"...")
    reporting what changed (object names, vertex counts, file paths).
  • Chunk the work. 180-second timeout per call. Don't dump 500 lines in one call — split into ~5–20-line chunks.
  • Use Blender Studio naming conventions for everything you create: 
    GEO-
    , 
    MAT-
    , 
    LGT-
    , 
    CAM-
    , 
    ARM-
    , 
    COL-
    . Never leave anything as 
    Cube.027
    .
当生成用于
mcp__blender__execute_blender_code
的Python代码时：
  • 每次调用都是全新命名空间。仅预导入
    bpy
    ；每次调用都需重新导入
    math
    、
    bmesh
    、
    numpy
    等模块。
  • 通过稳定名称识别对象，绝不要使用Python变量。
    bpy.data.objects['GEO-sword']
    可跨调用生效；而
    sword = ...
    的赋值则不行。
  • 输出结构化内容以便解析。每个代码块末尾添加
    print(f"...")
    报告更改内容（对象名称、顶点数量、文件路径）。
  • 拆分工作。每次调用超时时间为180秒。不要一次性提交500行代码——拆分为约5-20行的代码块。
  • 使用Blender Studio命名规范命名所有创建的对象：
    GEO-
    、
    MAT-
    、
    LGT-
    、
    CAM-
    、
    ARM-
    、
    COL-
    。绝不要保留默认名称如
    Cube.027
    。

Standard skeleton for every operation

所有操作的标准框架

python
import bpy
python
import bpy

(re-import other modules here as needed)

（根据需要在此重新导入其他模块）

1. Scope: identify or create objects by NAME

1. 范围：通过名称识别或创建对象

obj = bpy.data.objects.get('GEO-target') or bpy.data.objects.new('GEO-target', None)
obj = bpy.data.objects.get('GEO-target') or bpy.data.objects.new('GEO-target', None)

2. Do the work

2. 执行操作

...

...

3. Report

3. 汇报

print(f"done:GEO-target {len(obj.data.vertices) if obj.data else 0}")
undefined
print(f"done:GEO-target {len(obj.data.vertices) if obj.data else 0}")
undefined

Naming conventions (apply to everything you create)

命名规范（适用于所有创建的对象）

PrefixMeaning
GEO-
Geometry / mesh objects
MAT-
Materials
LGT-
Lights
CAM-
Cameras
ARM-
Armatures (rigs)
COL-
Collections
WGT-
Custom bone shapes / widgets
Suffix 
.L
/ 
.R
for left/right. Examples: 
GEO-sword_blade
, 
MAT-steel_brushed
, 
LGT-key
.
前缀含义
GEO-
几何体/网格对象
MAT-
材质
LGT-
灯光
CAM-
相机
ARM-
骨架（绑定）
COL-
集合
WGT-
自定义骨骼形状/控件
使用后缀
.L
/
.R
表示左/右。示例：
GEO-sword_blade
、
MAT-steel_brushed
、
LGT-key
。

Validation rule of thumb

验证经验法则

After significant work, call 
mcp__blender__get_scene_info
and verify:
  • Expected objects exist with correct names.
  • Object counts make sense (no runaway duplication).
  • Polycount roughly matches target.
Before reporting success on a render or export, confirm the file actually exists (use 
Bash
: 
ls -la /path/to/output
).
完成重要操作后，调用
mcp__blender__get_scene_info
并验证：
  • 预期对象存在且名称正确。
  • 对象数量合理（无失控重复）。
  • 多边形数量大致符合目标。
在报告渲染或导出成功前，请确认文件实际存在（使用
Bash
命令：
ls -la /path/to/output
）。

When to load deeper references

何时加载深度参考文档

  • references/assembly-order.md
     — the canonical scene-assembly sequence, time budgets, recovery patterns. Load when planning a multi-step pipeline or when the user asks "what's the right order?".
  • references/intent-routing.md
     — fuller intent-to-skill mapping with edge cases. Load when the request is ambiguous and you need to disambiguate.
  • references/code-execution-rules.md
     — detailed rules for 
    execute_blender_code
    (namespace, timeouts, stdout capture). Load when tracking down execution errors.
  • references/assembly-order.md
     —— 标准场景组装顺序、时间预算、恢复模式。在规划多步骤流程或用户询问“正确顺序是什么？”时加载。
  • references/intent-routing.md
     —— 更完整的意图-技能映射，包含边缘情况。当请求模糊需要明确时加载。
  • references/code-execution-rules.md
     —— 
    execute_blender_code
    的详细规则（命名空间、超时、标准输出捕获）。在排查执行错误时加载。

Reporting back to the user

向用户汇报

When work is done, report concretely:
  • ✅ Created: list objects + polycounts.
  • ✅ Lit: list lights + their roles.
  • ✅ Rendered: file path + size + dimensions + render time.
  • ⚠️ Warnings: any auto-decimation, naming conflicts, fallback materials.
Example:
Created 
GEO-sword_blade
(1 240 verts), 
GEO-sword_grip
(320 verts).
Materials: 
MAT-steel_brushed
, 
MAT-leather_dark
.
Lit with 
LGT-key
(warm 3200K), 
LGT-fill
(cool 5500K), 
LGT-rim
(cool blue).
Rendered to 
/tmp/sword_hero.png
(1920×1080, 2.3 MB, 38 s with 256 samples + OptiX denoise).
工作完成后，提供具体汇报：
  • ✅ 已创建：列出对象+多边形数量。
  • ✅ 已打光：列出灯光及其作用。
  • ✅ 已渲染：文件路径+大小+尺寸+渲染时间。
  • ⚠️ 警告：任何自动减面、命名冲突、 fallback材质。
示例：
已创建
GEO-sword_blade
（1240个顶点）、
GEO-sword_grip
（320个顶点）。
材质：
MAT-steel_brushed
、
MAT-leather_dark
。
灯光：
LGT-key
（暖光3200K）、
LGT-fill
（冷光5500K）、
LGT-rim
（冷蓝色）。
渲染输出至
/tmp/sword_hero.png
（1920×1080，2.3 MB，38秒，256采样+OptiX降噪）。

Failure modes — what to do when…

故障处理——出现以下问题时该怎么做

ProblemAction
MCP timeoutBreak the failing chunk into smaller pieces
Code execution error: <line>
Read the error; fix that one line; retry
Object not found in next callYou used a Python var instead of 
bpy.data.objects['name']
Render took too longReduce samples, enable adaptive sampling, lower resolution
File not at expected pathUse absolute paths; verify with Bash 
ls
Material looks wrong after exportYou used non-Principled-BSDF nodes; rebuild material with Principled only
'Action' object has no attribute 'fcurves'
Blender 5.x layered Actions; walk 
action.layers[].strips[].channelbags[].fcurves
instead. See 
blender-animation
Recipe 3 for the compat helper.
BLENDER_EEVEE_NEXT
rejected		Blender 5.x renamed it back to 
BLENDER_EEVEE
. See 
blender-rendering
Recipe 3 for the try/except fallback.
KeyError: 'Subsurface IOR'
(or other input names)		Blender 5.x marks some BSDF inputs 
enabled=False
(currently 
Weight
, 
Subsurface IOR
); they're reachable by iteration but not string-key lookup. See 
blender-materials
Recipe 9 for the 
set_input
helper.
Error: Cannot render, no camera
scene.camera is None
. Always run the 
ensure_camera()
guard before any render — see 
blender-rendering
Recipes 5 / 6. The orchestrator must check this before chaining to render even if the user's prompt didn't ask for a camera explicitly.
User reports "scene is grey / no materials visible" while looking at Blender's viewportBlender viewport defaults to Solid shading mode which ignores materials. The render is correct; only the viewport looks grey. After every scene assembly, set viewport to Material Preview: 
space.shading.type = 'MATERIAL'; space.shading.use_scene_lights = True; space.shading.use_scene_world = True
User reports "materials look flat / no texture"Flat PBR colors lack surface variation. Add procedural textures (Noise/Voronoi → ColorRamp → Roughness or Bump) for steel scratches, hammered metal, leather grain, etc. See 
blender-materials
Recipe 12 (procedural wood) for the pattern.
Subject looks wrongly proportioned (e.g. blade too short, chair too narrow)The orchestrator skipped the dimension lookup. Always read 
references/common-object-dimensions.md
BEFORE generating modeling code. Don't guess.
User asks for a "human" / "character" / "face" / "person"Pure-recipe primitives produce a recognisable silhouette only, NOT a human face. Suggest one of: (a) 
mcp__blender__download_polyhaven_asset
/ 
download_sketchfab_model
/ 
generate_hyper3d_model_via_text
for an actual human base mesh, then chain materials + lighting + render; (b) commission a Blender character artist (see 
prompts/04-blender-workflow.md
). Do NOT pretend a sphere-with-features looks human — it doesn't. See 
references/common-object-dimensions.md
"Characters / avatars" section.
Elongated subject renders as a thin pole instead of a recognisable shapeCamera viewing the thin axis of an elongated object. Rotate the object so its broad axis faces the camera. See 
blender-modeling
"Critical: axis orientation for elongated objects".
Blade/spike has a "chiseled flat" tip instead of a pointTop vertices were scaled toward zero but not merged. Use the proper tapering recipe in 
blender-modeling
("Critical: tapering to a point") — collapse top verts to centerline AND 
remove_doubles
.
Coloured glass renders flat/metallic instead of "glass-like"Tint set on 
Base Color
of Principled BSDF only. Real coloured glass needs Volume Absorption for depth-based tint. See 
blender-materials
Recipe 6b. Also: 
Roughness=0.0
produces mirror-flat highlights that look metallic — use 0.02–0.05 instead.
Glass renders black on the inside
transmission_bounces
too low. Default 12 is insufficient for thick or layered glass. Set 
scene.cycles.transmission_bounces = 24
.
问题操作
MCP超时将失败的代码块拆分为更小的部分
Code execution error: <line>
读取错误信息；修复对应行代码；重试
下一次调用中找不到对象你使用了Python变量而非
bpy.data.objects['name']
渲染耗时过长减少采样数、启用自适应采样、降低分辨率
文件不在预期路径使用绝对路径；通过Bash命令
ls
验证
导出后材质显示错误你使用了非Principled-BSDF节点；仅使用Principled节点重建材质
'Action' object has no attribute 'fcurves'
Blender 5.x采用分层Actions；改用
action.layers[].strips[].channelbags[].fcurves
。查看
blender-animation
的方案3获取兼容辅助代码。
BLENDER_EEVEE_NEXT
被拒绝		Blender 5.x将其改回
BLENDER_EEVEE
。查看
blender-rendering
的方案3获取try/except回退代码。
KeyError: 'Subsurface IOR'
（或其他输入名称）		Blender 5.x将部分BSDF输入标记为
enabled=False
（当前为
Weight
、
Subsurface IOR
）；可通过迭代访问，但无法通过字符串键查找。查看
blender-materials
的方案9获取
set_input
辅助函数。
Error: Cannot render, no camera
scene.camera is None
。在任何渲染前务必运行
ensure_camera()
防护代码——查看
blender-rendering
的方案5/6。即使用户请求未明确提及相机，协调器也必须在链式调用渲染前检查此问题。
用户反馈“场景是灰色的/看不到材质”（查看Blender视口时）Blender视口默认使用实体着色模式，会忽略材质。渲染结果正确，只是视口显示为灰色。每次场景组装完成后，将视口设置为材质预览模式：
space.shading.type = 'MATERIAL'; space.shading.use_scene_lights = True; space.shading.use_scene_world = True
用户反馈“材质看起来很平坦/没有纹理”纯PBR颜色缺乏表面变化。添加程序化纹理（Noise/Voronoi → ColorRamp → Roughness或Bump）模拟钢划痕、锻打金属、皮革纹理等效果。查看
blender-materials
的方案12（程序化木纹）获取实现模式。
对象比例错误（如剑身太短、椅子太窄）协调器跳过了尺寸查找步骤。生成建模代码前务必读取
references/common-object-dimensions.md
，请勿猜测。
用户请求“人类”/“角色”/“人脸”/“人物”纯方案生成的基本几何体仅能产生可识别的轮廓，无法生成人脸。建议选择以下方案之一：(a) 使用
mcp__blender__download_polyhaven_asset
/
download_sketchfab_model
/
generate_hyper3d_model_via_text
获取真实的人体基础网格，然后链式调用材质+灯光+渲染；(b) 委托Blender角色艺术家（查看
prompts/04-blender-workflow.md
）。请勿假装带特征的球体看起来像人类——实际并非如此。查看
references/common-object-dimensions.md
的“角色/虚拟形象”部分。
细长对象渲染为细杆而非可识别形状相机正对细长对象的细轴。旋转对象使其宽轴朝向相机。查看
blender-modeling
的“关键：细长对象的轴方向”。
剑刃/尖刺的尖端是“凿平的平面”而非尖点顶部顶点被缩放到零但未合并。使用
blender-modeling
中的正确锥化方案（“关键：锥化至尖点”）——将顶部顶点合并到中心线并执行
remove_doubles
。
有色玻璃渲染为平坦/金属质感而非“玻璃质感”仅在Principled BSDF的
Base Color
上设置了色调。真实有色玻璃需要体积吸收实现基于深度的色调。查看
blender-materials
的方案6b。另外：
Roughness=0.0
会产生镜面高光，看起来像金属——请使用0.02–0.05。
玻璃内部渲染为黑色
transmission_bounces
值过低。默认值12对于厚玻璃或多层玻璃不足。设置
scene.cycles.transmission_bounces = 24
。

What this skill is NOT for

本技能不适用的场景

  • Heavy custom GPU work / writing a render engine (use Blender's existing engines)
  • Real-time game logic (use Unity / Unreal directly)
  • Sculpting strokes from natural language (sculpting is gestural; use brushes interactively)
  • Things outside Blender's capabilities (CAD precision modeling — use FreeCAD; CFD simulation — use Blender's Mantaflow only for VFX-quality, not engineering)
When the user asks for these, redirect them politely and explain.
  • 繁重的自定义GPU工作/编写渲染引擎（使用Blender现有引擎）
  • 实时游戏逻辑（直接使用Unity/Unreal）
  • 通过自然语言生成雕刻笔触（雕刻是手势操作；请交互式使用画笔）
  • Blender能力之外的任务（CAD精密建模——使用FreeCAD；CFD模拟——仅将Blender的Mantaflow用于VFX级效果，而非工程用途）
当用户请求这些内容时，请礼貌地引导他们并说明原因。",