blender-geometry-nodes

Blender Geometry Nodes 专家

概述

本技能为 Blender 5.x 几何节点提供专家指导：设计节点设置、编写 Python 脚本以程序化构建节点树、调试性能问题，以及了解完整的节点目录。参考文件包含完整的节点列表和 Python API 用法模式。

MCP 优先方式

优先使用 官方 Blender MCP Server（Blender Lab，Blender 5.1+）创建节点组、连接字段、散布实例，并直接读取运行中的 Blender 会话输出。只有在 MCP 服务未连接时，才退回到生成 Python 脚本。

检测： 在会话开始时，查找名称符合 execute_blender_code、get_objects_summary 或 search_api_docs 的工具——这些工具属于官方 blender-mcp 服务。如果存在其中任意工具，即表示 MCP 可用。

本技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 修改场景前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 清点文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 调用 API 或操作符前确认名称是否正确
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉结果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操作 UI，让更改可见
• render_thumbnail_to_path、render_viewport_to_path — 快速获取视觉反馈

工作流： 使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持简短且可幂等执行，以便轻松定位故障。

设置方法：参阅 docs/blender-mcp-setup.md。

任务决策树

• “为 X 创建几何节点设置” -> 设计节点树，然后生成 Python 代码来构建（参见生成节点树）
• “我的几何节点运行很慢” -> 按照调试与优化工作流操作
• “X 是什么节点？” -> 查阅 references/node_reference.md 获取完整节点目录
• “如何将 X 连接到 Y？” -> 检查插槽兼容性，并建议正确的节点链
• “编写几何节点树脚本” -> 查阅 references/python_api.md 获取 API 用法模式

生成节点树

通过 Python 创建几何节点设置时：

1. 阅读 references/python_api.md，了解正确的 API 用法模式和节点类型名称
2. 按照以下模式组织脚本：
   • 创建节点组
   • 设置组接口（输入/输出）
   • 使用正确的类型字符串添加所有节点
   • 将节点排列为易读的从左到右布局（x 间距约为 200-300，y 间距约为 200）
   • 为输入设置默认值
   • 创建节点间的所有连线
   • 将其作为修改器应用到目标对象
3. 使用 Frame 节点将复杂设置整理为逻辑分区
4. 显式添加 Group Input 和 Group Output 节点

节点类型字符串约定

• 大多数几何节点：GeometryNode<PascalCaseName>（例如，GeometryNodeMeshCube、GeometryNodeSetPosition）
• 与着色器编辑器共用的数学/纹理/颜色节点：ShaderNode<Name>（例如，ShaderNodeMath、ShaderNodeTexNoise、ShaderNodeValToRGB）
• 布尔/比较/随机节点：FunctionNode<Name>（例如，FunctionNodeBooleanMath、FunctionNodeCompare、FunctionNodeRandomValue）
• 不确定确切的类型字符串时，请查阅 references/python_api.md

组接口的插槽类型

NodeSocketFloat, NodeSocketVector, NodeSocketColor, NodeSocketBool,
NodeSocketInt, NodeSocketString, NodeSocketGeometry, NodeSocketObject,
NodeSocketCollection, NodeSocketMaterial, NodeSocketImage,
NodeSocketRotation, NodeSocketMatrix, NodeSocketMenu

常见节点模式

散布系统

1. 基础网格（例如 Grid 或任意网格）-> Distribute Points on Faces -> Instance on Points <- 实例几何体
2. 添加 Random Value，为实例添加旋转／缩放变化
3. 如果需要对结果执行更多网格操作，请使用 Realize Instances

程序化变形

1. Group Input（Geometry）-> Set Position
2. 将 Position 输入数学运算节点（Noise Texture -> Vector Math -> Math），以计算偏移量
3. 使用 Vector Math（Add）将偏移量添加到原始位置

条件几何体

1. 使用 Separate Geometry 和选择字段拆分几何体
2. 分别处理每个分支
3. 使用 Join Geometry 将结果合并

挤出 + 变换模式

1. Extrude Mesh（Faces）-> 输出 Top 选择
2. 将 Top 输出用作 Set Position、Scale Elements 或后续挤出的选择

基于曲线的生成

1. 曲线基元（Circle、Line 等）-> Curve to Mesh，并提供轮廓曲线
2. 或：Mesh to Curve -> 曲线操作 -> Curve to Mesh

Repeat Zone（迭代操作）

1. Repeat Input -> 处理节点 -> Repeat Output
2. 在 Repeat Zone 上设置迭代次数
3. 使用 Iteration 输入，在每次迭代中改变行为

Simulation Zone（类物理行为）

1. Simulation Input -> 处理节点 -> Simulation Output
2. 状态会跨帧保留
3. 使用 Scene Time 或帧间隔执行依赖时间的行为

Simulation Zone 注意事项

重要：这些经验来自真实项目，来之不易。违反这些规则会导致难以察觉的错误。

• Group Input 的值不会传递到 Simulation Zone 内部——模拟区域内的节点接收的是接口的默认值，而不是修改器覆盖值。解决方法：将值作为状态项传递到模拟区域中。
• Object Info 可在 Sim Zone 内部使用——但只有直接在节点插口上设置对象引用时才行（不能通过 Group Input 设置）。设置 transform_space = 'ORIGINAL'。
• Scene Time 可在 Sim Zone 内部使用——可用于基于帧的激活逻辑（例如，在第 N 帧启动效果）。
• Sim Zone 的几何体会在第 1 帧后冻结——输入几何体上的 Named Attributes 在后续帧中不会更新。只有状态项会传递到后续帧。
• Sim Zone 后需要使用 Set Position——位置状态项会追踪数值，但不会移动顶点。将追踪到的位置输入到模拟区域输出之后的 Set Position 节点。
• Collection Info 中的 Instance Scale 始终返回 (1,1,1)——请在源对象上使用单独的修改器，将缩放写入命名属性。
• Empty 经 Realize Instances 后不会生成几何体——请改用单顶点网格对象作为轻量级代理对象。
• Capture Attribute 的匿名属性无法通过 Realize Instances 保留——请改用带有明确字符串名称的 Store Named Attribute。
• 可见性控制——使用 Delete Geometry 输出空几何体以隐藏对象。不要依赖几何节点内部的 hide_viewport／hide_render。
• to_mesh() 无法实现实例——Instance on Points 的输出通过 obj.to_mesh() 会返回 0 个顶点。请在 depsgraph 上使用 realize_instances=True 调用 evaluated_get(depsgraph)，或者在节点树中添加 Realize Instances 节点。

For Each Element Zone（逐元素处理）

1. For Each Element Input -> 处理 -> For Each Element Output
2. 独立处理每个元素（点、面、样条线、实例）
3. Blender 5.0 中新增

Bundle 系统（Blender 5.0+）

1. 使用 Combine Bundle 将多个数据流组合到一个连接中
2. 使用 Separate Bundle 或 Get Bundle Item 提取数据
3. 适用于通过单个插口传递复杂数据

Get/Store Bundle Item（Blender 5.1）

1. Get Bundle Item 按索引从 Bundle 中获取特定项——5.1 中新增
2. Store Bundle Item 将值存储到 Bundle 的特定槽位中——5.1 中新增
3. 无需分开操作和组合操作，即可更灵活地操纵 Bundle

骨骼信息节点（Blender 5.1）

1. 骨骼信息节点可读取骨架对象的骨骼变换
2. 输出：姿势、局部姿势、变换姿势、静止姿势、静止长度
3. 接受骨架对象和骨骼名称作为输入
4. 可在几何节点中实现由绑定驱动的节点设置和骨架变形
5. 注意：如果该节点读取某根骨骼，而同一骨架中的另一根骨骼又依赖于已修改的对象，请留意依赖循环

字符串转曲线（Blender 5.1）

1. 现在每个输入都是可调整的字段，包括 字体（5.1 中新增的插槽类型）
2. 新增 单词输出，可对动态图形进行逐词控制
3. 支持逐字符和逐词自定义

体积网格节点（Blender 5.1）

1. 立方体网格拓扑——用于结构化网格的新基元
2. 裁剪网格——停用边界框之外的体素
3. 网格平均值 / 网格中位数——对网格数据执行统计运算
4. 网格转点——将网格体素转换为点云
5. 网格膨胀和腐蚀——对网格执行形态学操作
6. 改进的设置网格背景——设置网格的背景值

UV 节点（Blender 5.1）

1. UV 展开现在支持最小拉伸（SLIM 算法）和“禁止翻转”设置
2. 打包 UV 岛现在可以输入自定义打包区域

矩阵 SVD 节点（Blender 5.1）

1. 矩阵 SVD（奇异值分解）可将矩阵分解为 U、S、V 分量
2. 可用于分析变换并构建自定义约束系统

字体插槽（Blender 5.1）

1. 新增字体数据插槽类型 NodeSocketFont
2. 供字符串转曲线节点及其他文本相关节点使用

调试与优化

性能诊断

几何节点树运行缓慢的常见原因，按影响程度排序：

1. 过早使用实例实化——尽可能长时间保留实例几何。实化会将实例转换为实际几何，从而增加顶点数量
2. 不必要的属性计算——命名属性和捕获属性节点即使在属性静态时也会在每一帧求值。对静态结果使用烘焙节点
3. 点分布过密——降低密度，或使用网格上分布点，而不是面上分布点，以获得均匀分布
4. 细分曲面级别过高——保持较低的视口级别（1-2），最终输出时再使用渲染级别
5. 对复杂网格执行布尔运算——简化输入网格，或使用 SDF 网格布尔进行基于体积的布尔运算
6. 模拟区开销——尽量减少传入模拟区的几何；只传递每帧会发生变化的内容
7. 嵌套重复区——复杂度会不断累积。可考虑扁平化结构或减少迭代次数
8. 大型属性传递——在高面数网格上使用最近采样/索引采样。使用空间索引（内置），同时降低源网格的复杂度

调试技巧

• 查看器节点：将中间输出连接到查看器节点，以检查节点树中任意位置的几何。在电子表格编辑器中查看属性数据。
• 静音节点：按 Ctrl+M 可静音/取消静音节点，从而定位导致问题的部分
• 电子表格中的命名属性：打开电子表格编辑器，查看所有属性、其域以及每个元素的值
• 帧率叠加层：启用 FPS 叠加层（视口叠加层）以实时监控性能
• 节点计时：在叠加层中启用节点计时，查看哪些节点耗时最多
• 简化场景：使用场景属性 > 简化，在开发期间降低细分级别和粒子数量
• 搜索节点警告：在节点编辑器中按 Ctrl+F 搜索警告（5.1 新增）
• 节点工具：节点工具现在注册为运算符，可通过编程方式访问（5.1 新增）

常见错误及修复方法

• 套接字之间“无法连接”：套接字类型不匹配。请查看 references/node_reference.md，确认正确的套接字类型。使用转换节点（例如 Mesh to Points、Float to Integer）
• 几何体消失：检查 Set/Delete/Separate 节点的选择输入。全为 false 的选择会移除所有内容。使用 Viewer 节点检查
• 属性显示为 0/空值：域不匹配。存储在面上的属性无法直接在点上读取。使用 Evaluate on Domain 或 Capture Attribute 在不同域之间传递属性
• 操作未影响实例：大多数网格操作都需要先执行 Realize Instances。Set Position 作用于实例原点，而不是实例化的几何体本身
• Z 轴冲突／面重叠：执行 Extrude Mesh 后，原始面仍会保留。使用 Delete Geometry 并反转“Top”选择，或使用 Merge by Distance

节点参考

如需查看按类别（Input、Output、Attribute、Curve、Geometry、Mesh、Instances、Point、Volume、Simulation、Color、Texture、Utilities）整理的完整几何节点目录，请参阅 references/node_reference.md。

建议搜索的主要类别：

• 网格基元和操作：在 node_reference.md 中搜索“Mesh”
• 曲线基元和操作：搜索“Curve”
• 点分布：搜索“Point”或“Distribute”
• 实例管理：搜索“Instance”
• 体积／SDF 操作：搜索“Volume”、“Grid”或“SDF”
• 实用数学：搜索“Math”或“Utilities”

Python API 参考

如需查看完整的 Python API 用法模式，包括节点类型字符串、套接字类型、连接和修改器应用，请参阅 references/python_api.md。