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

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

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or 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.