unity-probuilder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via
GET /skills/recommend?includeSchema=true
) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

调用本模块中的任何技能之前：如果您打算根据技能名称或描述猜测参数来调用技能，请停止——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其架构）。如果您已经从推荐/架构中获得了参数定义，可以直接进行dryRun。

Triggers

触发场景

Blocking out levels
Building or editing ProBuilder geometry
Prototyping shapes in-editor
搭建关卡灰盒、创建或编辑 ProBuilder 几何体、在编辑器内快速搭形

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

Unity ProBuilder Skills

Unity ProBuilder 技能

Use this module for editable ProBuilder meshes, not regular primitive GameObjects. It is best for blockout, level geometry, and procedural mesh refinement.

Requires:
com.unity.probuilder
package. Batch-first: For scene blockout or level generation, prefer
probuilder_create_batch
when creating
2+
shapes.

本模块适用于可编辑的ProBuilder网格，而非普通的基础GameObject。它最适合用于关卡灰盒搭建、关卡几何体制作以及程序化网格优化。

依赖要求：
com.unity.probuilder
包。 批量优先：对于场景灰盒搭建或关卡生成，当创建
2+
个形状时，优先使用
probuilder_create_batch
。

Guardrails

防护规则

Operating Mode (v1.9 three-tier):

Approval (default): query skills (e.g.
```
probuilder_get_info
```
,
```
probuilder_get_vertices
```
) run directly. Create/modify skills are FullAuto — call once, get
```
MODE_RESTRICTED
```
, run the grant protocol; a successful
```
/permission/grant
```
executes the skill server-side and returns the result in the same response.
Auto / Bypass: SemiAuto and FullAuto run directly.
Auto-forbidden in this module:
```
probuilder_combine_meshes
```
(
```
SkillOperation.Modify | Delete
```
, the
```
Delete
```
bit triggers NeverInSemi). It is callable only under Bypass mode or after the user adds it to the Allowlist; the grant flow returns
```
MODE_FORBIDDEN
```
. Note
```
probuilder_delete_faces
```
is
```
Operation = SkillOperation.Modify
```
only and remains grantable under Approval/Auto.
When
```
com.unity.probuilder
```
is missing, every skill returns a package-missing diagnostic instead of executing.

DO NOT (common hallucinations):

probuilder_create_mesh

does not exist -> use

probuilder_create_shape

probuilder_edit_face

does not exist -> use the specific face skills such as

probuilder_extrude_faces

probuilder_delete_faces

probuilder_merge_faces

probuilder_set_material

and

probuilder_set_face_material

are different -> whole object vs selected faces

Regular meshes do not become ProBuilder meshes automatically
Mesh rebuild calls (
```
ToMesh()
```
+
```
Refresh()
```
) are already handled by the skills. Do not invent a manual rebuild step

Routing:

For ordinary primitive objects without editable topology -> use
```
gameobject_create
```
For material asset creation or shader work -> use
```
material
```
For large blockout generation -> combine this module with
```
material
```
and
```
light
```
, but keep geometry creation here

操作模式（v1.9 三级模式）：

审批模式（默认）：查询类技能（如
```
probuilder_get_info
```
、
```
probuilder_get_vertices
```
）可直接运行。创建/修改类技能为全自动模式——调用一次后会返回
```
MODE_RESTRICTED
```
，需执行授权流程；成功调用
```
/permission/grant
```
后，技能将在服务器端执行，并在同一响应中返回结果。
自动模式 / 绕过模式：半自动和全自动技能可直接运行。
本模块中自动禁用的技能：
```
probuilder_combine_meshes
```
（
```
SkillOperation.Modify | Delete
```
，其中
```
Delete
```
标志触发NeverInSemi）。仅在绕过模式下或用户将其添加至允许列表后才可调用；授权流程会返回
```
MODE_FORBIDDEN
```
。注意
```
probuilder_delete_faces
```
仅为
```
Operation = SkillOperation.Modify
```
，在审批/自动模式下仍可申请授权。
当缺少
```
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
```
模块结合使用，但几何体创建仍需在此模块中进行

Object Targeting

对象定位

Most edit/query skills accept one of:

```
name
```
```
instanceId
```
```
path
```

Prefer

instanceId

when multiple scene objects share the same name.

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

```
name
```
```
instanceId
```
```
path
```

当多个场景对象共享同一名称时，优先使用

instanceId

。

Skills

技能列表

Create and Batch

创建与批量创建

Skill	Use	Key parameters
`probuilder_create_shape`	Create a parametric ProBuilder shape	`shape` , `name?` , `x/y/z?` , `sizeX/Y/Z?` , `rotX/Y/Z?`
`probuilder_create_batch`	Create multiple shapes in one call	`items` , `defaultParent?`

Supported

shape

values:

Cube

Sphere

Cylinder

Cone

Torus

Prism

Arch

Pipe

Stairs

Door

Plane

技能	用途	关键参数
`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

。

Face and Edge Editing

面与边编辑

Skill	Use	Key parameters
`probuilder_extrude_faces`	Extrude selected faces	target, `faceIndexes?` , `distance?` , `method?`
`probuilder_delete_faces`	Delete faces by index	target, `faceIndexes`
`probuilder_merge_faces`	Merge faces into one	target, `faceIndexes?`
`probuilder_flip_normals`	Reverse face direction	target, `faceIndexes?`
`probuilder_detach_faces`	Split faces from shared vertices	target, `faceIndexes?` , `deleteSourceFaces?`
`probuilder_bevel_edges`	Chamfer edges	target, `edgeIndexes?` , `amount?`
`probuilder_extrude_edges`	Extrude edges outward	target, `edgeIndexes` , `distance?` , `extrudeAsGroup?`
`probuilder_bridge_edges`	Bridge two edges with new face	target, `edgeA` , `edgeB` , `allowNonManifold?`

技能	用途	关键参数
`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?`

Mesh, Vertex, UV, Material

网格、顶点、UV、材质

Skill	Use	Key parameters
`probuilder_subdivide`	Add detail by subdivision	target, `faceIndexes?`
`probuilder_conform_normals`	Make normals point consistently outward	target, `faceIndexes?`
`probuilder_move_vertices`	Offset vertices by delta	target, `vertexIndexes` , `deltaX/Y/Z?`
`probuilder_set_vertices`	Set absolute vertex positions	target, `vertices`
`probuilder_get_vertices`	Query vertex positions	target, `vertexIndexes?` , `verbose?`
`probuilder_weld_vertices`	Merge close vertices	target, `vertexIndexes` , `radius?`
`probuilder_project_uv`	Box-project UVs	target, `faceIndexes?` , `channel?`
`probuilder_set_face_material`	Assign material to faces	target, `faceIndexes?` , `materialPath?` , `submeshIndex?`
`probuilder_set_material`	Assign whole-object material or quick color	target, `materialPath?` , `r/g/b/a?`
`probuilder_combine_meshes`	Merge multiple meshes	`names`

技能	用途	关键参数
`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`

Query and Pivot

查询与轴心点

Skill	Use	Key parameters
`probuilder_get_info`	Get face/vertex/material stats	target
`probuilder_center_pivot`	Center or reposition pivot	target, `worldX/Y/Z?`

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

Blockout Workflow

灰盒搭建工作流

Create major volumes with
```
probuilder_create_batch
```
.
Verify traversal and gameplay scale before adding detail.
Refine surfaces with face/edge operations.
Use vertex edits for ramps, slopes, and irregular silhouettes.
Apply quick colors or real materials after layout stabilizes.

使用
```
probuilder_create_batch
```
创建主要体积块。
在添加细节前，验证遍历性和游戏玩法比例。
使用面/边操作优化表面。
使用顶点编辑制作坡道、斜面和不规则轮廓。
在布局稳定后，应用快速颜色或真实材质。

Minimal Example

最简示例

python

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
)

python

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
)

Important Notes

重要说明

ProBuilder objects keep editable topology through
```
ProBuilderMesh
```
.
Use
```
probuilder_get_info
```
before face edits and
```
probuilder_get_vertices
```
before vertex edits.
MeshCollider on physics-driven props must be convex.
Quick color assignment is fine for prototype passes; use material assets for production.
Package missing errors are expected if ProBuilder is not installed.

ProBuilder对象通过
```
ProBuilderMesh
```
保持可编辑拓扑结构。
在进行面编辑前使用
```
probuilder_get_info
```
，在进行顶点编辑前使用
```
probuilder_get_vertices
```
。
物理驱动道具上的MeshCollider必须是凸面体。
快速颜色分配适用于原型阶段；生产环境请使用材质资源。
如果未安装ProBuilder，会出现包缺失错误，这是预期情况。

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by

GET /skills/schema

unity_skills.get_skill_schema()

, not by this file. Load

MODELING_REFERENCE.md

for scene design heuristics, furniture decomposition, detailed examples, and extended modeling tips.

技能的精确名称、参数、默认值和返回值由

GET /skills/schema

或

unity_skills.get_skill_schema()

定义，而非本文档。加载

MODELING_REFERENCE.md

可获取场景设计启发、家具分解、详细示例和扩展建模技巧。