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 注册声明了groupprobuilder与destructiveHintTrue——后者告诉 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 大类别组织类别actions连接测试ping形状创建 (SHAPE_ACTIONS)create_shape、create_poly_shape网格编辑 (MESH_ACTIONS)extrude_faces、extrude_edges、bevel_edges、subdivide、delete_faces、bridge_edges、connect_elements、detach_faces、flip_normals、merge_faces、combine_meshes、merge_objects、duplicate_and_flip、create_polygon顶点操作 (VERTEX_ACTIONS)merge_vertices、weld_vertices、split_vertices、move_vertices、insert_vertex、append_vertices_to_edge选择 (SELECTION_ACTIONS)select_facesUV 与材质 (UV_MATERIAL_ACTIONS)set_face_material、set_face_color、set_face_uvs查询 (QUERY_ACTIONS)get_mesh_info、convert_to_probuilder平滑 (SMOOTHING_ACTIONS)set_smoothing、auto_smooth网格工具 (UTILITY_ACTIONS)center_pivot、freeze_transform、set_pivot、validate_mesh、repair_mesh服务端对 action 做了小写归一化action.lower()因此大小写混写也能正确匹配如Create_Shape→create_shape测试 test_manage_probuilder.py 专门验证了这一行为。当传入未知 action 时服务端不会调用 Unity而是按类别返回可用的 action 建议列表manage_probuilder.py这有助于 LLM 自我纠正。二、通用参数契约该工具的参数结构简单统一具体见 manage_probuilder.py名称类型必填说明actionstr是要执行的操作见上文清单targetstr \| None—目标 GameObject名称/路径/IDsearch_methodLiteral[by_id, by_name, by_path, by_tag, by_layer] \| None—查找目标 GameObject 的方式propertiesdict[str, Any] \| str \| None—特定 action 的参数dict 或 JSON 字符串调用与转发逻辑非常直接properties、target、search_method三个可选参数中非空者会被写入发送给 Unity 的参数包且search_method在转发时被转换为驼峰键searchMethodmanage_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.pyaction关键 properties说明extrude_facesfaceIndices、distance、method(FaceNormal/VertexNormal/IndividualFaces)沿法线挤出指定面extrude_edgesedgeIndices或edges: [{a,b},...]、distance、asGroup挤出边可用顶点对描述边bevel_edgesedgeIndices或edges: [{a,b},...]、amount(0-1)边倒角amount 为倒角量subdividefaceIndices省略则细分全部细分面增加拓扑密度delete_facesfaceIndices删除面bridge_edgesedgeA、edgeB均为{a,b}顶点对、allowNonManifold桥接两条开放边connect_elementsedgeIndices/edges或faceIndices连接边或面detach_facesfaceIndices、deleteSourceFaces(bool)分离面可选删除源面flip_normalsfaceIndices翻转面法线merge_facesfaceIndices合并多个面为一个combine_meshestargets: [GameObject列表]组合多个 ProBuilder 物体merge_objectstargets列表自动转换非 ProBuilder 物体合并物体为一个 ProBuilder 网格duplicate_and_flipfaceIndices复制并翻转生成双面几何create_polygonvertexIndices、unordered(bool)用已有顶点连成新面实操示例——挤出立方体的两个面{ 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关键 properties说明merge_verticesvertexIndices、collapseToFirst(bool)把多个顶点塌缩为一个点可选保留首个顶点位置weld_verticesvertexIndices、radius在邻近半径内焊接顶点split_verticesvertexIndices拆分共享顶点move_verticesvertexIndices、offset: [x,y,z]平移顶点insert_vertexedge: {a,b}或faceIndex、point: [x,y,z]在边/面上插入新顶点append_vertices_to_edgeedgeIndices/edges、count在边上插入均匀分布的点示例——按偏移移动顶点{ 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是文档强调的“语义选择”能力参数包括directionup/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参数控制信息粒度include 值返回内容summary默认面数、顶点数、包围盒 bounds、材质列表faces在 summary 之上追加每个面的法线 normal、中心 center、方向 direction、平滑组、manualUV 标志edges追加每条边的顶点对及端点世界坐标all上述全部信息每个面的directiontop/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 与材质action关键 properties说明set_face_materialfaceIndices省略则作用于所有面、materialPath给面指定材质Assets 内路径set_face_colorfaceIndices省略则全部、color: [r,g,b,a]设置顶点色set_face_uvsfaceIndices省略则全部、scale、offset、rotation、flipU、flipV设置 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_ACTIONSset_smoothingfaceIndices、smoothingGroup0 硬边1 平滑组编号auto_smoothangleThreshold默认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_ACTIONSaction说明center_pivot把枢轴点移到网格包围盒中心同时反向补偿顶点与 transform 位置set_pivot把枢轴设到任意世界坐标position: [x,y,z]freeze_transform把位置/旋转/缩放烘焙进顶点数据并重置 transformvalidate_mesh只读体检检查退化三角形、未使用顶点repair_mesh自动修复退化三角形与未使用顶点示例——设置枢轴到任意世界位置{ 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。九、调用链路与测试保障一次调用的完整链路从源码可以还原出完整的执行链路服务端 Pythonmanage_probuilder.py校验并小写化 action → 解析上下文获取目标 Unity 实例get_unity_instance_from_context→ 组装参数action/properties/target/searchMethod→ 经send_with_unity_instance转发命令。Unity 端 C#ManageProBuilder.csHandleCommand通过EnsureProBuilder()反射加载 ProBuilder 类型 → 按 action 分派到对应私有方法 → 经ObjectResolver.ResolveGameObject按target/searchMethod定位对象 → 执行建模操作 →RefreshMesh重建网格。返回结果Unity 端返回SuccessResponse/ErrorResponsePython 端原样回传为dict。值得注意的一个细节Unity 端在首次调用时会执行PatchProBuilderDefaultMaterial()把 ProBuilder 默认材质的发射色Emission清零并设置EmissiveIsBlack标志以修复 URP 项目下新网格被误判为全白发光体、导致 Bloom 泛光的已知问题——该补丁仅修改内存中的材质对象每次域重载后自动重放ManageProBuilder.cs。测试保障服务端测试 test_manage_probuilder.py 对每个 action 类别都提供了参数透传验证并特别覆盖action 完整性ALL_ACTIONS必须等于九大类子列表的并集且无重复L53-L63非法 action返回success: false且不调用 UnityL69-L86大小写归一化L314-L323非 dict 返回值包装为失败响应L330-L347searchMethod透传为驼峰键L285-L295边以顶点对{a,b}指定的两种写法edgeIndices与edges均有验证L593-L617。此外TestProjects 内也包含 Unity 端编辑模式测试 ManageProBuilderTests.cs与仓库“服务端测试 编辑器内测试”的双层保障体系保持一致。十、推荐工作流先侦察后编辑工具描述中给出的 WORKFLOW TIP 是实战中最有价值的习惯manage_probuilder.py在编辑前先调用get_mesh_info且includefaces查看每个面的法线与方向分类每个面都会返回top/bottom/front/back/left/right方向语义据此挑选正确的面索引再执行extrude_faces或delete_faces等操作。推荐的完整 AI 建模工作流建形create_shape或create_poly_shape生成初始几何体侦察get_mesh_infoincludefaces获取面索引、方向、法线、材质语义选择select_faces按方向/拓扑生成faceIndices编辑extrude_faces/bevel_edges/delete_faces等按需组合精修weld_vertices/move_vertices处理拓扑细节set_smoothing/auto_smooth控制渲染平滑收尾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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考