企业官网建设流程全解析

Unity MCP 中 manage_probuilder 工具全解析：用 AI 在编辑器内完成 ProBuilder 三维建模

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp

导读

manage_probuilder是 Unity MCP 为编辑器内三维建模提供的统一 ProBuilder 网格管理工具，它把 Unity ProBuilder 的面、边、顶点级建模操作封装成一组可供 LLM/AI 助手直接调用的 MCP action，覆盖从创建基础几何体、多边形拉伸，到挤出/倒角/桥接等网格编辑，再到顶点焊接、UV 与材质设置、网格校验修复的完整流程。读完本文你将掌握该工具的全部 action 清单与参数契约，理解 Python 服务端与 Unity C# 端如何协作执行命令，并能用真实可复制的调用示例驱动 AI 完成从零建模到网格优化的实战任务。

一、工具定位：一个 action，数十种建模能力

manage_probuilder归属于 MCP 工具的probuilder分组，服务端模块位于 Server/src/services/tools/manage_probuilder.py。它遵循该仓库“单一工具 + 多 action 分派”的统一设计模式：Python 端只负责参数校验与转发，真正的建模逻辑全部由 Unity 编辑器内的 C# 实现完成（见 MCPForUnity/Editor/Tools/ProBuilder/ManageProBuilder.cs）。

该工具以注解形式向 MCP 注册，声明了group="probuilder"与destructiveHint=True——后者告诉 LLM 此工具可能产生破坏性修改（删除面、合并顶点等），在使用前应谨慎确认目标对象（参见 manage_probuilder.py）。工具描述中明确标注了前提条件：

Requirescom.unity.probuilderpackage.

如果编辑器未安装该包，Unity 端HandleCommand会直接返回错误响应，提示通过 Package Manager 安装com.unity.probuilder（见 ManageProBuilder.cs）。值得注意的是，C# 实现通过反射解析UnityEngine.ProBuilder的程序集类型（ManageProBuilder.cs），因此该工具不会对未安装 ProBuilder 的项目造成编译依赖，类型解析失败时优雅降级为错误提示。

action 全量清单

从服务端源码的常量定义（manage_probuilder.py）可以精确还原全部 action，共 40+ 个，按 9 大类别组织：

服务端对 action 做了小写归一化（action.lower()），因此大小写混写也能正确匹配（如Create_Shape→create_shape），测试 test_manage_probuilder.py 专门验证了这一行为。当传入未知 action 时，服务端不会调用 Unity，而是按类别返回可用的 action 建议列表（manage_probuilder.py），这有助于 LLM 自我纠正。

二、通用参数契约

该工具的参数结构简单统一，具体见 manage_probuilder.py：

调用与转发逻辑非常直接：properties、target、search_method三个可选参数中，非空者会被写入发送给 Unity 的参数包，且search_method在转发时被转换为驼峰键searchMethod（manage_probuilder.py）。最终通过send_with_unity_instance与async_send_command_with_retry走 Unity 传输层（HTTP/StdIO 均可），并将 Unity 返回的 dict 原样返回给调用方；若返回非 dict 则包装为失败响应。

返回值

返回一个包含 Unity 响应的dict，其具体结构取决于 action。成功响应通常形如{"success": true, "message": "..."}（部分 action 还会附带数据，如get_mesh_info返回的网格详情）；失败响应为{"success": false, "message": "..."}。

三、形状创建：从零生成几何体

create_shape —— 生成 ProBuilder 基础几何体

支持 12 种形状：Cube / Cylinder / Sphere / Plane / Cone / Torus / Pipe / Arch / Stair / CurvedStair / Door / Prism。形状专属参数放在properties中，例如size、radius、height、depth、width、segments、rows、columns、innerRadius、outerRadius等，最终通过 Unity 端反射调用ShapeGenerator的Generate*系列方法，保证生成的是带有真实尺寸的网格（ManageProBuilder.cs）。

{ "action": "create_shape", "target": "MyParent", "properties": { "shapeType": "Cube", "size": [2, 2, 2] } }

若提供了target，新形状会作为该 GameObject 的子物体生成（test_manage_probuilder.py）。

create_poly_shape —— 由 2D 多边形轮廓挤出立体

以points: [[x,y,z], ...]指定二维平面上的多边形足迹，配合extrudeHeight挤出高度与flipNormals（是否翻转法线）生成体块：

{ "action": "create_poly_shape", "properties": { "points": [[0, 0, 0], [5, 0, 0], [5, 0, 5], [0, 0, 5]], "extrudeHeight": 3.0 } }

对应测试见 test_manage_probuilder.py，它验证了extrudeHeight会被透传到 Unity。该 action 特别适合程序化生成建筑轮廓、地形基座等扁平足迹类几何体。

四、网格编辑：面、边、体操作

这是工具的核心部分，涵盖 14 个编辑 action。以下示例均来自真实测试用例（test_manage_probuilder.py）：

实操示例——挤出立方体的两个面：

{ "action": "extrude_faces", "target": "MyCube", "properties": { "faceIndices": [0, 1], "distance": 1.5 } }

用顶点对指定边做倒角：

{ "action": "bevel_edges", "target": "MyCube", "properties": { "edges": [{ "a": 0, "b": 1 }, { "a": 2, "b": 3 }], "amount": 0.15 } }

桥接两条开放边并允许非流形结果：

{ "action": "bridge_edges", "target": "MyCube", "properties": { "edgeA": { "a": 0, "b": 1 }, "edgeB": { "a": 2, "b": 3 }, "allowNonManifold": true } }

这些 action 在 Unity 端一一映射到 ProBuilder 的MeshOperations反射调用（ExtrudeElements、Bevel、DeleteElements、AppendElements、ConnectElements、MergeElements、CombineMeshes等，见 ManageProBuilder.cs）。每次几何修改后，Unity 端会统一执行ToMesh()+Refresh()+EditorMeshUtility.Optimize()完成网格重建与优化（ManageProBuilder.cs），确保修改结果立即可见且拓扑干净。

五、顶点操作：精修到顶点级

示例——按偏移移动顶点：

{ "action": "move_vertices", "target": "MyCube", "properties": { "vertexIndices": [0, 1, 2], "offset": [0, 1, 0] } }

按半径焊接邻近顶点：

{ "action": "weld_vertices", "target": "MyCube", "properties": { "vertexIndices": [0, 1, 2], "radius": 0.05 } }

在指定边上插入顶点：

{ "action": "insert_vertex", "target": "MyCube", "properties": { "edge": { "a": 0, "b": 1 }, "point": [0.5, 0, 0] } }

在边上均匀追加 3 个点：

{ "action": "append_vertices_to_edge", "target": "MyCube", "properties": { "edgeIndices": [0, 1], "count": 3 } }

对应测试见 test_manage_probuilder.py。其中merge_vertices的collapseToFirst行为也有专门测试覆盖（test_manage_probuilder.py）。

六、语义化面选择与查询

select_faces —— 按方向/拓扑语义选面

select_faces是文档强调的“语义选择”能力，参数包括：

• direction：up/down/forward/back/left/right，按面朝向筛选；
• tolerance：方向容差；
• growFrom/growAngle、floodFrom/floodAngle、loopFrom、ring：基于 ProBuilder 元素选择算法的拓扑生长/环选/圈选参数。

调用后返回faceIndices数组，可直接喂给其他 action 使用：

{ "action": "select_faces", "target": "MyCube", "properties": { "direction": "up", "tolerance": 0.9 } }

测试验证了该调用会把direction与tolerance原样转发（test_manage_probuilder.py）。Unity 端对未知方向值会返回明确的错误提示（有效值仅上述 6 个方向，见 ManageProBuilder.cs）。

get_mesh_info —— 网格体检与编辑前侦察

通过include参数控制信息粒度：

每个面的direction（top/bottom/front/back/left/right）由 Unity 端根据法线计算并分类（ClassifyDirection，见 ManageProBuilder.cs），这正是支撑语义选择的底层依据。出于性能考虑，面详情最多输出 100 条、边详情最多 200 条，超出时会附带truncated标志（ManageProBuilder.cs）。

{ "action": "get_mesh_info", "target": "MyCube", "properties": { "include": "faces" } }

convert_to_probuilder —— 普通网格转 ProBuilder

把标准 Unity Mesh（如导入的 FBX 网格）转换为可编辑的 ProBuilderMesh，转换后即可使用本工具的全部编辑能力：

{ "action": "convert_to_probuilder", "target": "StandardMesh" }

七、UV 与材质

示例——给 0 号面贴材质：

{ "action": "set_face_material", "target": "MyCube", "properties": { "faceIndices": [0], "materialPath": "Assets/Materials/Red.mat" } }

调整 UV 缩放与旋转：

{ "action": "set_face_uvs", "target": "MyCube", "properties": { "faceIndices": [0, 1], "scale": [2, 2], "rotation": 45 } }

对应测试见 test_manage_probuilder.py。注意：当faceIndices被省略时，Unity 端会返回全部面（ManageProBuilder.cs），这与文档中“省略则作用于所有面”的语义一致。

八、平滑组与网格工具

平滑相关（SMOOTHING_ACTIONS）

• set_smoothing：faceIndices、smoothingGroup（0= 硬边，1+= 平滑组编号）；
• auto_smooth：angleThreshold（默认30度），按相邻面夹角自动分配平滑组。

{ "action": "set_smoothing", "target": "MyCube", "properties": { "faceIndices": [0, 1, 2], "smoothingGroup": 1 } }

{ "action": "auto_smooth", "target": "MyCube", "properties": { "angleThreshold": 45 } }

这两个 action 在 Unity 端由独立类 ProBuilderSmoothing.cs 实现，对应测试覆盖了平滑组赋值与角度阈值透传（test_manage_probuilder.py）。

网格工具（UTILITY_ACTIONS）

示例——设置枢轴到任意世界位置：

{ "action": "set_pivot", "target": "MyCube", "properties": { "position": [1.5, 0, 2.3] } }

center_pivot的 Unity 端实现体现了工程细节：它会计算局部空间包围盒中心，将顶点整体平移-center，再把 transform 反向移动以保持物体世界位置不变，且操作前后都通过Undo.RecordObject记录以支持撤销（ProBuilderMeshUtils.cs）。这些工具 action 在服务端测试中均有覆盖（test_manage_probuilder.py）。

九、调用链路与测试保障

一次调用的完整链路

从源码可以还原出完整的执行链路：

1. 服务端 Python（manage_probuilder.py）：校验并小写化 action → 解析上下文获取目标 Unity 实例（get_unity_instance_from_context）→ 组装参数（action/properties/target/searchMethod）→ 经send_with_unity_instance转发命令。
2. Unity 端 C#（ManageProBuilder.cs）：HandleCommand通过EnsureProBuilder()反射加载 ProBuilder 类型 → 按 action 分派到对应私有方法 → 经ObjectResolver.ResolveGameObject按target/searchMethod定位对象 → 执行建模操作 →RefreshMesh重建网格。
3. 返回结果：Unity 端返回SuccessResponse/ErrorResponse，Python 端原样回传为dict。

值得注意的一个细节：Unity 端在首次调用时会执行PatchProBuilderDefaultMaterial()，把 ProBuilder 默认材质的发射色（Emission）清零并设置EmissiveIsBlack标志，以修复 URP 项目下新网格被误判为全白发光体、导致 Bloom 泛光的已知问题——该补丁仅修改内存中的材质对象，每次域重载后自动重放（ManageProBuilder.cs）。

测试保障

服务端测试 test_manage_probuilder.py 对每个 action 类别都提供了参数透传验证，并特别覆盖：

• action 完整性：ALL_ACTIONS必须等于九大类子列表的并集且无重复（L53-L63）；
• 非法 action：返回success: false且不调用 Unity（L69-L86）；
• 大小写归一化（L314-L323）；
• 非 dict 返回值包装为失败响应（L330-L347）；
• searchMethod透传为驼峰键（L285-L295）；
• 边以顶点对{a,b}指定的两种写法（edgeIndices与edges）均有验证（L593-L617）。

此外，TestProjects 内也包含 Unity 端编辑模式测试 ManageProBuilderTests.cs，与仓库“服务端测试 + 编辑器内测试”的双层保障体系保持一致。

十、推荐工作流：先侦察，后编辑

工具描述中给出的 WORKFLOW TIP 是实战中最有价值的习惯（manage_probuilder.py）：

在编辑前先调用get_mesh_info且include='faces'，查看每个面的法线与方向分类；每个面都会返回top/bottom/front/back/left/right方向语义，据此挑选正确的面索引再执行extrude_faces或delete_faces等操作。

推荐的完整 AI 建模工作流：

1. 建形：create_shape或create_poly_shape生成初始几何体；
2. 侦察：get_mesh_info（include='faces'）获取面索引、方向、法线、材质；
3. 语义选择：select_faces按方向/拓扑生成faceIndices；
4. 编辑：extrude_faces/bevel_edges/delete_faces等按需组合；
5. 精修：weld_vertices/move_vertices处理拓扑细节，set_smoothing/auto_smooth控制渲染平滑；
6. 收尾：validate_mesh体检，必要时repair_mesh修复，center_pivot/freeze_transform规整变换。

结语

manage_probuilder用一套统一的参数契约封装了 Unity ProBuilder 的核心建模能力，让 AI 助手可以在编辑器内完成从基础几何体创建到网格级精修的完整三维建模流程。它的可靠性来自服务端与编辑器两端双层实现与测试保障：服务端 manage_probuilder.py 负责 action 归一化、参数组装与统一转发，编辑器端 ManageProBuilder.cs 通过反射驱动 ProBuilder API 并在每次修改后重建优化网格，同时以内存补丁规避 URP 项目的默认材质泛光问题。对于希望用自然语言驱动 Unity 建模的开发者，从ping连通性测试、get_mesh_info侦察到create_shape建形的三步入门路径，是最平滑的上手方式。

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp