blender-geometry-nodes

几何节点

执行模型位于 blender-core 中。使用 scripts/gn_builder.py 构建节点树；它采用紧凑的 JSON 规格，开销远低于原始 bpy。请先查明准确的插口名称，因为它们会随版本变化：

scripts/gn_builder.py -- --describe GeometryNodeDistributePointsOnFaces GeometryNodeInstanceOnPoints
scripts/gn_builder.py -- --spec scatter.json --apply Ground --set Density=20 Seed=3 Mask=@paint_mask

--set Name=@attr 会将命名属性作为修改器输入。结果会报告计算后的顶点／面数量和节点警告。规格格式见脚本文档字符串；完整示例见 references/recipes.md。

核心概念（务必掌握，否则一切都无法运行）

• 几何体通过具有圆形形状的插口从左向右流动。字段（菱形插口）是函数，会在使用它们的节点上按元素计算，并遵循该节点的域／上下文。
• 域：点、边、面、面角、样条线、实例、图层。Capture Attribute 会在图表中的某个位置冻结字段（在拓扑变化之前），而 Evaluate on Domain 会在不同域之间转换。
• 属性：内置属性（position、normal、sharp_face、material_index、UVMap……），以及通过 Store Named Attribute 存储的命名属性。命名属性会在修改器运行后保留。这是 GN 数据传递到着色器（Attribute 节点）和导出器（glTF export_attributes 会导出名称以 _ 开头的属性）的方式。
• 实例开销很低（一个网格、多个变换）。只有在必须编辑每个实例的几何体或导出单个网格时，才使用 Realize Instances。尽可能晚地实现实例化。
• 节点组接口中公开的输入会成为修改器输入（5.2：mod.properties.inputs.<identifier>.value）。面板可将输入分组，菜单插口则提供枚举选项。

区域与高级类型

功能	节点	用途
仿真区域	GeometryNodeSimulationInput/Output（成对使用）	逐帧状态：生长、粒子、侵蚀；烘焙后可保留
重复区域	GeometryNodeRepeatInput/Output	迭代 N 次（L 系统、松弛、递归细分）
对每个元素执行	GeometryNodeForeachGeometryElementInput/Output	对每个元素运行子图（例如每个建筑地块、每个岛）
闭包／Bundle（5.0+）	NodeClosureInput/Output、NodeCombineBundle/NodeSeparateBundle、Evaluate Closure	传递函数／结构化数据；创建可复用的“策略”节点组
列表（5.2）	GeometryNodeFieldToList、ListGetItem、ListLength、SortList、FilterList	真正的数组，而非字段
网格／SDF（4.x–5.x）	MeshToSDFGrid、SDFGridBoolean、SDFGridFillet、SDFGridOffset、GridToMesh	平滑布尔运算、重网格化、圆角、体素效果
物理（5.2，实验性）	GeometryNodeXPBDSolver + bundles	基于节点的布料／毛发，见 blender-simulation
操纵器	GizmoLinear/Dial/Transform	用于输入的视口手柄
区域需要调用 input.pair_with_output(output)（规格键 pairs），并在输出节点上添加条目（repeat_items、state_items 等；规格中的第 4 个节点字段）。

操作步骤

1. 勾勒数据流：源几何体 → 选择／遮罩（字段）→ 生成／实例化 → 变换／随机化 → 实现实例／合并 → 设置材质／着色 → 输出。
2. 对要使用的每种节点类型运行 --describe，然后编写规格并构建。检查 node_warnings 和计算后的数量。
3. 只公开有意义的输入（密度、种子、缩放范围、材质），并设置最小值／最大值。
4. 查看效果（look）；如果结果将要导出（已实现的几何体），请检查 blender-asset-qa；对于实例数量和三角形数，请检查 blender-game-optimization。
5. 交付：要么保持程序化形式（.blend／资产库），要么应用修改器／使用 visual_geometry_to_objects 供导出器使用。

规则

• 随机性：始终公开一个 Seed，并将 Random Value 与 ID/Index 字段配合使用，以便计数变化时结果仍保持稳定。
• 与比例无关的设置使用 Object Info（Relative）和实际单位。应用对象缩放，或明确读取缩放值。
• 材质：在节点树中使用 Set Material。材质必须存在于文件中，实例会保留各自的材质。
• 着色：GN 输出会丢失自动平滑设置，除非添加 Set Shade Smooth +（5.x）Smooth by Angle 基础节点组，或存储 sharp_edge。
• UV：基元通过其 UV 输出生成 UVMap。使用 Store Named Attribute（Face Corner、2D Vector，名称为 UVMap）存储，否则它会被丢弃。
• 性能：避免实现数百万个实例；散布时优先使用点 + 实例；谨慎使用 Merge by Distance；模拟区域需要烘焙才能播放/导出（object.geometry_node_bake_single 或修改器 bakes）。
• 节点工具（ng.is_tool = True、is_mode_edit 等）会将节点组转换为 3D 视图菜单中的操作符，用于编辑工作流。

易错点

• 5.2：mod["Socket_2"] 不再可用。请使用 getattr(mod.properties.inputs, ident).value；对于属性输入，使用 .type = "ATTRIBUTE" + .attribute_name。Compare 和 Random Value 插槽已更改：Random Value 现在有由 data_type 决定类型的单组动态 Min/Max/Value 插槽。按名称连接；不确定时使用 --describe。
• 当前模式/数据类型下被禁用的插槽仍会以相同名称保留在 node.inputs 中。构建器会选择已启用的插槽。请先设置 data_type/mode 属性（构建器会在连接前设置属性）。
• nt.interface.new_socket(...) 是 4.0+ API（ng.inputs.new 已移除）。
• 导出器会读取求值后的网格。实例会成为 glTF 实例（export_gpu_instances），或在导出时被实现。