# 1. ProBuilder Install and Mental Model
Part of [[ProBuilder Gray-Boxing and Landmarks]]. Next: [[2. Blockout Workflow and Metrics]].
ProBuilder is an in-Editor mesh kit: you draw cubes, stairs, doors and arches in the scene, then push faces around until the space is right. It is not a DCC replacement. When a piece needs to be a hero mesh, you export and replace it; the *space* you already proved stays.
## 1.1 Install
1. Unity **6000.5+** project. URP is assumed in this series.
2. **Window > Package Manager > Unity Registry > ProBuilder** (`com.unity.probuilder`).
3. Confirm a **6.1.x** version. For Editor 6000.5 the official package page lists **6.1.2, 6.1.3, and 6.1.4** as released; prefer **6.1.4** unless you have a reason to pin an earlier 6.1.
4. **Samples** (required on URP / HDRP): in the package details, expand **Samples** and import the support entry that matches your render pipeline. The 6.1 manual says these shaders are what display **vertex colors and textures** correctly, and that they land under `Assets/Samples/ProBuilder/<version>/` after import. Without them, a vertex-colored gray-box can look pink, black, or unlit in URP and you will think the tool is broken.
The 6.1 install page's compatibility line ("2019.4 and later") is package boilerplate; your pin is **6.1.x on 6000.5**.
## 1.2 ProBuilderMesh is the source of truth
From the official API overview:
- Namespaces: `UnityEngine.ProBuilder` (runtime mesh compile), `UnityEngine.ProBuilder.MeshOperations` (edit operations, also runtime), `UnityEditor.ProBuilder` (menus, windows, Editor-only optimize).
- Data lives on a **`ProBuilderMesh`** component: positions, UVs, faces, triangles, material, smoothing, colors, shared vertices. Unity's `MeshFilter.sharedMesh` is a **compiled** output.
- After you change ProBuilder data, call **`ToMesh()`** (rebuild triangles / submeshes, apply positions) then **`Refresh()`** (UVs, normals, tangents, collisions). Never assign a mutually competing mesh to `MeshFilter.sharedMesh` and expect ProBuilder to keep it.
- In the Editor, `EditorMeshUtility.Optimize(mesh, true)` generates UV2 and collapses duplicate vertices. That type is **not** available at runtime; the official sample uses `MeshUtility.CollapseSharedVertices` on the compiled Unity mesh instead, and warns that later ProBuilder edits will overwrite it.
```csharp
using UnityEngine;
using UnityEngine.ProBuilder;
#if UNITY_EDITOR
using UnityEditor.ProBuilder;
#endif
public static class PbUtil
{
public static void Commit(ProBuilderMesh pb)
{
pb.ToMesh();
pb.Refresh();
#if UNITY_EDITOR
EditorMeshUtility.Optimize(pb, true);
#endif
}
}
```
## 1.3 New Shape, in the Editor
The 6.1 manual's New Shape tool:
1. **Tools overlay > New Shape** (short click uses the current shape; long click picks another), or **Tools > ProBuilder > Editors > New Shape**.
2. Draw the 2D outline in the Scene view; **Snap to Grid** is your friend for metrics work.
3. Close the outline and extrude to 3D, or type dimensions in the Shape Settings window first and then draw.
4. To edit: select the shape, set the Tools overlay context to **ProBuilder**, use **Edit ProBuilder Shape** for settings and element modes (face, edge, vertex).
You will also live on: Face / Edge / Vertex selection, Extrude, Inset, Cut, Merge, and Vertex Colors (the blockout language in part 2). Exact button labels can drift with Editor chrome; if a menu has moved, use the overlay search rather than inventing a path.
**Pivot:** `PivotLocation.Center` or `FirstCorner`. `GenerateCube`'s `size` is a **bounding box**, not a Transform scale. Prefer leaving scale at (1,1,1) and setting size in the generator (or face extrusion) so metrics stay honest.
## 1.4 ShapeGenerator for scripts
`ShapeGenerator` (6.1.4) is the runtime/editor API used in the official sample (`CreateShape(ShapeType.Cube)`). Useful overloads for gray-boxes:
| Method | Use |
|---|---|
| `GenerateCube(pivot, size)` | Walls, floors, cover, boxes |
| `GenerateStair(pivot, size, steps, buildSides)` | Metrics-accurate stairs |
| `GenerateCone(pivot, radius, height, subdivAxis)` | A cheap weenie / spire |
| `GenerateArch(...)` / `GenerateDoor(...)` | Openings you can walk |
| `GeneratePlane(...)` | Floors and sightline strips |
| `GenerateCylinder(...)` | Columns, towers |
| `CreateShape(ShapeType, pivot)` | Defaults, then edit |
`GenerateCube` documentation: the size is the opposite corner of the bounding box, **not** applied as Transform scale.
After you move the GameObject, assign a material, or tint vertex colors, `Commit`. Add a `MeshCollider` (or let ProBuilder refresh collisions - confirm the collider on the object after `Refresh`; if it is missing, add one).
## 1.5 Exercise
Install 6.1.x, import the URP sample, create a 2 x 2 x 2 cube with New Shape, paint a vertex color, and confirm it reads in Game view. Then delete the sample folder *on a throwaway branch or a copy* and look at the cube again so you remember what "forgot the samples" looks like. Do not leave the samples deleted on the teaching project.
## Sources
- Installing ProBuilder (6.1): https://docs.unity3d.com/Packages/
[email protected]/manual/installing.html
- New Shape tool (6.1): https://docs.unity3d.com/Packages/
[email protected]/manual/shape-tool.html
- API overview (6.1.4): https://docs.unity3d.com/Packages/
[email protected]/manual/api.html
- `ShapeGenerator` (6.1.4): https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.ProBuilder.ShapeGenerator.html