unity-probuilder

**在调用此模块中的任何技能之前：**如果你正打算根据技能名称或描述猜测参数来调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其 schema）。如果你已从 recommend/schema 获取参数定义，则可直接进行 dryRun。

触发条件

• 搭建关卡
• 创建或编辑 ProBuilder 几何体
• 在编辑器内快速搭建形状
• 搭建关卡灰盒、创建或编辑 ProBuilder 几何体、在编辑器内快速搭形

Unity ProBuilder 技能

此模块用于可编辑的 ProBuilder 网格，而非普通的原始形状 GameObject。它最适合用于灰盒搭建、关卡几何体和程序化网格优化。

需要：com.unity.probuilder 包。 **优先批量创建：**创建场景灰盒或生成关卡时，创建 2+ 个形状请优先使用 probuilder_create_batch。

防护措施

运行模式（v1.9 三层模式）：

• Approval（默认）：查询技能（例如 probuilder_get_info、probuilder_get_vertices）可直接运行。创建/修改技能为 FullAuto——调用一次后会返回 MODE_RESTRICTED，然后运行授权流程；成功调用 /permission/grant 后，服务端会执行技能并在同一响应中返回结果。
• Auto / Bypass：SemiAuto 和 FullAuto 可直接运行。
• 本模块中禁止 Auto 模式运行的技能：probuilder_combine_meshes（SkillOperation.Modify | Delete，其中 Delete 位会触发 NeverInSemi）。此技能只能在 Bypass 模式下调用，或在用户将其添加到 Allowlist 后调用；授权流程会返回 MODE_FORBIDDEN。注意，probuilder_delete_faces 仅为 Operation = SkillOperation.Modify，在 Approval/Auto 模式下仍可授权。
• 缺少 com.unity.probuilder 时，每项技能都会返回缺包诊断信息，而不会执行。

不要（常见幻觉）：

• probuilder_create_mesh 不存在 → 请使用 probuilder_create_shape
• probuilder_edit_face 不存在 → 请使用特定的面技能，例如 probuilder_extrude_faces、probuilder_delete_faces、probuilder_merge_faces
• probuilder_set_material 和 probuilder_set_face_material 各不相同 → 前者用于整个对象，后者用于选中的面
• 普通网格不会自动变成 ProBuilder 网格
• 网格重建调用（ToMesh() + Refresh()）已由技能处理。不要虚构手动重建步骤

路由：

• 对于没有可编辑拓扑的普通原始形状对象 → 使用 gameobject_create
• 对于材质资源创建或着色器工作 → 使用 material
• 对于大型灰盒生成 → 将此模块与 material 和 light 结合使用，但几何体创建应在此处进行

对象定位

大多数编辑/查询技能接受以下任一参数：

• name
• instanceId
• path

多个场景对象名称相同时，优先使用 instanceId。

技能

创建与批量创建

技能	用途	关键参数
probuilder_create_shape	创建参数化 ProBuilder 形状	shape、name?、x/y/z?、sizeX/Y/Z?、rotX/Y/Z?
probuilder_create_batch	一次调用创建多个形状	items、defaultParent?

支持的 shape 值：Cube、Sphere、Cylinder、Cone、Torus、Prism、Arch、Pipe、Stairs、Door、Plane。

面与边编辑

技能	用途	关键参数
probuilder_extrude_faces	挤出选中的面	target、faceIndexes?、distance?、method?
probuilder_delete_faces	按索引删除面	target、faceIndexes
probuilder_merge_faces	将多个面合并为一个	target、faceIndexes?
probuilder_flip_normals	反转面的方向	target、faceIndexes?
probuilder_detach_faces	将面从共享顶点处分离	target、faceIndexes?、deleteSourceFaces?
probuilder_bevel_edges	倒角边	target、edgeIndexes?、amount?
probuilder_extrude_edges	向外挤出边	target、edgeIndexes、distance?、extrudeAsGroup?
probuilder_bridge_edges	用新面桥接两条边	target、edgeA、edgeB、allowNonManifold?

网格、顶点、UV、材质

技能	用途	关键参数
probuilder_subdivide	通过细分增加细节	target、faceIndexes?
probuilder_conform_normals	使法线方向一致地朝外	target、faceIndexes?
probuilder_move_vertices	按增量偏移顶点	target、vertexIndexes、deltaX/Y/Z?
probuilder_set_vertices	设置顶点的绝对位置	target、vertices
probuilder_get_vertices	查询顶点位置	target、vertexIndexes?、verbose?
probuilder_weld_vertices	合并距离较近的顶点	target、vertexIndexes、radius?
probuilder_project_uv	盒式投射 UV	target、faceIndexes?、channel?
probuilder_set_face_material	为面指定材质	target、faceIndexes?、materialPath?、submeshIndex?
probuilder_set_material	为整个对象指定材质或快速设置颜色	target、materialPath?、r/g/b/a?
probuilder_combine_meshes	合并多个网格	names

查询与轴心点

技能	用途	关键参数
probuilder_get_info	获取面、顶点和材质统计信息	target
probuilder_center_pivot	居中或重新定位轴心点	target、worldX/Y/Z?

白盒搭建工作流

1. 使用 probuilder_create_batch 创建主要体块。
2. 在添加细节前，确认通行路线和游戏玩法的尺度。
3. 使用面和边操作细化表面。
4. 使用顶点编辑制作坡道、斜坡和不规则轮廓。
5. 布局稳定后，应用快速颜色或实际材质。

最简示例

import unity_skills

unity_skills.call_skill("probuilder_create_batch", items=[
    {"shape": "Cube", "name": "Ground", "sizeX": 20, "sizeY": 0.5, "sizeZ": 12, "y": -0.25},
    {"shape": "Cube", "name": "Platform_A", "sizeX": 3, "sizeY": 0.3, "sizeZ": 3, "x": 4, "y": 1.5},
    {"shape": "Cube", "name": "Ramp", "sizeX": 3, "sizeY": 1, "sizeZ": 5, "x": 8, "y": 0.5}
])

unity_skills.call_skill("probuilder_move_vertices",
    name="Ramp",
    vertexIndexes="4,5",
    deltaY=-0.8
)

unity_skills.call_skill("probuilder_set_material",
    name="Platform_A",
    r=0.2, g=0.6, b=1.0
)

重要说明

1. ProBuilder 对象会通过 ProBuilderMesh 保留可编辑拓扑。
2. 编辑面前使用 probuilder_get_info，编辑顶点前使用 probuilder_get_vertices。
3. 由物理驱动的道具上的 MeshCollider 必须为凸面。
4. 快速指定颜色适用于原型制作阶段；生产环境请使用材质资源。
5. 如果未安装 ProBuilder，出现缺少软件包的错误属于预期情况。

精确签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文件。 加载 MODELING_REFERENCE.md，查看场景设计启发、家具拆分、详细示例和扩展建模技巧。