/probuilder

name: unity-probuilder
description: Model editable meshes with ProBuilder for blockout

> **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.

Triggers

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

Unity ProBuilder Skills

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.

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

Object Targeting

Most edit/query skills accept one of:

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

Prefer `instanceId` when multiple scene objects share the same name.

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`.

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?` |

Mesh, Vertex, UV, Material

| 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` |

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?` |

Blockout Workflow

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

Minimal Example

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, "s