GDnD Wiki

GDnD Wiki

This site is for Ulster University students and staff. Enter the class access password to continue.

Unity ProBuilder

14 min read

Unity ProBuilder

Overview

ProBuilder is a Unity package for creating and editing meshes directly in the Scene view. It can draw parametric shapes (cubes, stairs, arches, doors, pipes and more), then edit their vertices, edges and faces with modelling actions such as extrude, inset and edge loops. ProBuilder meshes stay ordinary GameObjects with a Mesh Renderer and, by default, a collider, so they can be walked on, lit, baked and turned into prefabs while a level is still rough.

For students, ProBuilder’s main job is 3d-blocking-and-greyboxing: building a level at real scale from simple shapes so that routes, sightlines, step heights and the camera can be tested before any final art exists. It is not a replacement for a modelling package such as Blender (blender-overview) for detailed props; the ProBuilder manual itself frames its export feature around using a ProBuilder mesh “as a placeholder while greyboxing” before building a more complex mesh elsewhere (Unity Technologies, ProBuilder 6 manual, “Exporting and re-importing”).

This page covers ProBuilder 6, the version line for Unity 6 (its package manifest declares Unity 6000.0 as the minimum editor). The earlier source summary source-unity-probuilder-greyboxing used the ProBuilder 5.2 Shape tool page; the workflow is the same, but some menus and overlays have moved.

Setup

  1. Install. ProBuilder has been distributed only through the Package Manager since version 3.0 (Unity Technologies, ProBuilder 6 manual, “Installing ProBuilder”). In Unity 6.3, open Window > Package Management > Package Manager (Unity Technologies, Unity 6.3 Manual, “Access the Package Manager window”), choose Unity Registry, select ProBuilder and click Install. Earlier Unity 6 versions use Window > Package Manager.
  2. Render pipeline samples (only if needed). For URP or HDRP, the manual says to import the matching support shaders from the Samples section of the ProBuilder package page so that vertex colours and textures display correctly (Unity Technologies, ProBuilder 6 manual, “Installing ProBuilder”). Plain colour materials for greyboxing usually work without this; import the sample if vertex colours or textures look wrong.
  3. Turn on snapping. In the Scene view Grid and Snap overlay, activate Grid Snapping and set Increment Snap (for example 0.5 or 1 m). See Snapping below.
  4. Add a scale reference. Place a default capsule (2 m tall) in the scene before building anything. Every measurement in a greybox is checked against it.
  5. Preferences. ProBuilder’s defaults (default material, collider type, static flags, shadow casting, lightmap UV generation) live in Edit > Preferences > ProBuilder (macOS: Unity > Settings) (Unity Technologies, ProBuilder 6 manual, “ProBuilder Preferences”).

Usage

Creating shapes with the New Shape tool

Activate New Shape from the Scene view Tools overlay (a short click creates the selected shape; a long click opens a menu of shapes) or from Tools > ProBuilder > Editors > New Shape (Unity Technologies, ProBuilder 6 manual, “New Shape and Edit Shape tools”). You then draw the shape’s bounding box in the Scene view. The first click is the box’s “first corner”, and the x, y and z sizes are measured from it. You can type exact dimensions into the Shape Settings window before drawing, and the shape conforms to them.

Shapes available include Cube, Sphere, Plane, Cylinder, Cone, Prism, Stairs, Torus, Pipe, Arch, Door and Sprite. Stairs, Arch and Door are especially useful for greyboxing because they produce a parametric doorway or staircase in one step.

To change a shape later, select it, switch to the ProBuilder context and use Edit ProBuilder Shape. The manual warns that re-entering shape editing discards any changes made with actions or the Cut tool since the shape was created (Unity Technologies, ProBuilder 6 manual, “ProBuilder mesh components”). Treat the parametric settings as the first pass, and switch to element editing only once the size is settled.

Tool contexts and edit modes

ProBuilder 6 uses Unity’s tool contexts (Unity Technologies, ProBuilder 6 manual, “Edit modes and active tool contexts”):

Context / modeWhat you selectTypical use
GameObject context (the default)the whole objectmove, rotate and scale whole pieces; Export, Center Pivot and other whole-mesh actions from the Scene view context menu
ProBuilder context, Vertex modeindividual verticesnudge a corner, weld or collapse vertices
ProBuilder context, Edge modeedgesinsert edge loops, bevel, bridge
ProBuilder context, Face modefacesmove, extrude, inset or delete faces; apply a material to part of a mesh

Switch context with the Tool Context button at the top of the Tools overlay; you can enter the ProBuilder context only when the selected object has ProBuilder components. Choose vertex, edge or face mode in the Tool Settings overlay. G cycles the edit modes and Escape returns to the GameObject context. Right-clicking a ProBuilder object opens a context menu that lists actions for the current mode.

The handful of actions a greybox needs

  • Extrude Faces. Select one or more faces and use Extrude Faces (Ctrl/Cmd+E, default distance 0.5), or hold Shift while moving a face with the transform handle. Shift with the scale handle creates an inset instead (Unity Technologies, ProBuilder 6 manual, “Extrude Faces”). Extruding the top face of a floor tile upwards is a quick way to make a ledge or wall.
  • Insert Edge Loop. Select an edge and use Insert Edge Loop (Alt/Opt+U). It adds a loop of edges right round the object, continuing only through quads. The manual recommends it over Connect Edges because connecting edges on one face leaves a T-junction, whereas a loop keeps the same topology all the way round (Unity Technologies, ProBuilder 6 manual, “Insert Edge Loop”; “Modeling tips for beginners”). Use a loop when you need to split a wall to extrude a doorway or window ledge.
  • Merge Faces joins selected faces into one and removes the edges between them. The manual cautions that it can leave T-junctions or floating vertices and is best used only when necessary (Unity Technologies, ProBuilder 6 manual, “Merge Faces”).
  • Merge Objects combines several ProBuilder objects into one; merging intersecting objects can give overlapping UVs (Unity Technologies, ProBuilder 6 manual, “Merge Objects”). In a greybox it is usually better to keep walls, floors and stairs as separate objects until the layout is final, because separate pieces are easier to move.

Pivots

A ProBuilder shape’s pivot can be placed at the centre of its bounding box or at its first vertex (the ProBuilder 6 source defines these two PivotLocation options; Shape Settings shows them under Pivot). Three actions fix pivots afterwards (Unity Technologies, ProBuilder 6 manual, “Center Pivot”, “Set Pivot - Faces”, “Freeze Transform”):

  • Center Pivot moves the pivot to the centre of the object’s bounds. Use it after heavy vertex editing has left the object rotating around a point outside itself.
  • Set Pivot (Ctrl/Cmd+J) in face, edge or vertex mode moves the pivot to the average centre of the selection. Selecting a door’s hinge edge, or the bottom face of a column, gives a pivot you can rotate or place from.
  • Freeze Transform resets position, rotation and scale to the world origin without moving any vertices, so the object keeps its place but its pivot moves to the world origin and its scale reads 1, 1, 1.

Pivot choice matters later: a door that should swing needs a pivot on its hinge, and a prop that should sit on the floor is easier to place with a pivot at its base (unity-3d-import-pipeline makes the same point for imported models).

Materials and UVs (basic level)

For a greybox, flat-colour materials are enough: drag a material onto a whole object, or select faces and use the Material Editor (Tools > ProBuilder > Editors > Open Material Editor) to apply materials to individual faces (Unity Technologies, ProBuilder 6 manual, “Material Editor window”). A consistent colour code (floor, wall, goal, danger) is part of the design test (3d-blocking-and-greyboxing).

When you add textures, ProBuilder’s Auto UV mode projects the texture automatically and keeps the projection consistent as you edit the geometry; you set tiling, offset and rotation rather than unwrapping by hand. The UV Editor (Tools > ProBuilder > Editors > Open UV Editor) is there for manual adjustments, and faces can be grouped so a texture tiles continuously across them (Unity Technologies, ProBuilder 6 manual, “Mapping Textures with UVs”). For what UVs are and why they matter, see 3d-materials-and-uvs.

Baked lighting needs a second UV set (lightmap UVs). ProBuilder can generate these: the Auto Lightmap UVs preference regenerates them after every edit, the Lightmap UVs action generates any that are missing, and the ProBuilder MeshFilter component shows a warning and a Generate Lightmap UVs button when they are absent (Unity Technologies, ProBuilder 6 manual, “ProBuilder Preferences”; “Lightmap UVs”; “ProBuilder MeshFilter component”). Check this before a bake (unity-lighting-for-3d-scenes).

Snapping and the end of ProGrids

Older tutorials use ProGrids, a separate preview package for grid snapping. Its last release was 3.0.3-preview.6 in February 2020 (Unity Technologies, ProGrids changelog), and ProBuilder 6’s own documentation no longer refers to it except in one preference description. ProBuilder 6 documents snapping through Unity’s built-in Grid and Snap overlay instead (Unity Technologies, ProBuilder 6 manual, “Snap to grid”):

  • for constant snapping, set Tool Handle Rotation to Global in the Tool Settings overlay, then activate Grid Snapping in the Grid and Snap overlay;
  • or hold Ctrl (macOS: Cmd) while drawing;
  • set the step size with Increment Snap in the same overlay.

The manual’s beginner tips add that buildings are easier to fit together if you stick to 90° and 45° angles and use grid snapping, which also stops you dragging a vertex past its neighbour (Unity Technologies, ProBuilder 6 manual, “Modeling tips for beginners”).

Colliders

New ProBuilder objects get a collider automatically. The Collider Type preference sets which: the default is a Mesh Collider, with Box Collider and None as alternatives (Unity Technologies, ProBuilder 6 manual, “ProBuilder Preferences”). So a ProBuilder floor and stairs can be walked on by a unity-character-controller as soon as they are drawn.

Two actions turn a ProBuilder object into invisible gameplay volumes. Set Collider keeps (or adds) a Mesh Collider and hides the renderer in Play mode; Set Trigger (shortcut T) also makes the Mesh Collider convex and a trigger, which suits checkpoint zones, kill volumes or “goal reached” areas (Unity Technologies, ProBuilder 6 manual, “Set Trigger and Set Collider”).

Exporting and converting to an ordinary mesh

ProBuilder stores its meshes inside the scene by default (Unity Technologies, ProBuilder 6 manual, “Store meshes as assets”). When a greybox piece needs to leave ProBuilder:

  • Export (Scene view context menu ProBuilderMesh > Export, or Tools > ProBuilder > Export) writes OBJ, STL, PLY or a Unity mesh .asset. OBJ is the usual choice for taking a blockout into Blender to model the final version over it. The OBJ and PLY options include Apply Transforms and Export As Group, which together let you export a whole layout and re-import it in place, and Right Handed for applications that use right-handed coordinates (Unity Technologies, ProBuilder 6 manual, “Export”).
  • The .asset and Prefab export options have Replace Source, which repoints the object’s MeshFilter at the exported mesh. A re-imported mesh is no longer editable with ProBuilder until you ProBuilderize it (Tools > ProBuilder > Object > Pro Builderize), which also converts ordinary meshes into ProBuilder meshes (Unity Technologies, ProBuilder 6 manual, “Exporting and re-importing”; “ProBuilderize”).
  • Strip ProBuilder Scripts in Selection (or in Scene) under the ProBuilder menu’s Actions section removes the ProBuilder components and leaves plain models (Unity Technologies, ProBuilder 6 manual, “The ProBuilder menu”).

Gotchas

  • Re-editing a shape undoes element edits. Opening Edit ProBuilder Shape after extruding or cutting throws those edits away. Settle the size first.
  • Snapping seems not to work. For constant snapping the handle rotation must be Global, and Grid Snapping must be active in the Grid and Snap overlay; holding Ctrl/Cmd while drawing works regardless.
  • Edge loops stop part-way. Insert Edge Loop only travels through quads. A triangle in the path ends the loop.
  • Merging leaves stray geometry. Merge Faces can leave T-junctions and floating vertices; use Collapse Vertices to clean a floating vertex (Unity Technologies, ProBuilder 6 manual, “Modeling tips for beginners”).
  • The object rotates around empty space. After vertex editing, run Center Pivot or Set Pivot.
  • Blotchy or seamed baked lighting. Lightmap UVs are missing or out of date. Generate them before baking.
  • Textured or vertex-coloured faces look wrong in URP. Import the URP support sample from the ProBuilder package page.
  • Mesh Colliders on moving or physics objects. The default Mesh Collider is fine for static floors and walls. For a ProBuilder piece that must move as a Rigidbody, use a Box Collider or a convex Mesh Collider. Unity’s manual says concave (non-convex) Mesh Colliders can only be static or kinematic, and recommends Mesh Colliders for static scene geometry and compound colliders for moving objects (Unity Technologies, Unity 6.3 Manual, “Introduction to Mesh colliders”).
  • Decorating too early. ProBuilder makes it easy to bevel and detail. In a greybox, every minute spent on detail is a minute not spent testing the layout (3d-blocking-and-greyboxing).

Practice

Greybox a single room with ProBuilder in under 40 minutes:

  • a floor of about 12 × 12 m, drawn with grid snapping at 0.5 m
  • walls about 3 m high with one doorway at least 1.2 m wide and 2.2 m high
  • a Stairs shape leading to a raised platform
  • one wall split with Insert Edge Loop, with the new face extruded to make a ledge or alcove
  • a goal plinth with Set Pivot used to put its pivot on the bottom face
  • a 2 m capsule kept in the scene as a scale reference

Success test:

  • the capsule fits through the doorway and stands on every stair tread without overlapping the risers
  • every floor, wall and stair piece shows a collider in the Inspector
  • there are no gaps between walls when viewed from above (snapping was on)
  • rotating the plinth in the GameObject context turns it around its base, not around empty space
  • you can name which edit mode (vertex, edge or face) you used for each step

Extension:

  • export the room as one OBJ with Export As Group and Apply Transforms enabled, import it into Blender, and confirm it arrives at the right size and in the right place

Self-test

  1. Where do you switch between vertex, edge and face editing in ProBuilder 6?
  2. What does ProBuilder 6 use for grid snapping now that ProGrids is no longer maintained?
  3. Why does the ProBuilder manual prefer Insert Edge Loop to Connect Edges?
  4. What happens to your extrusions if you re-open Edit ProBuilder Shape afterwards?
  5. What collider does a new ProBuilder shape get by default, and where can you change that?
  6. Which action moves the pivot to the centre of the selected faces?

Answers

  1. Enter the ProBuilder context from the Tools overlay, then choose the mode in the Tool Settings overlay (or press G to cycle modes).
  2. Unity’s built-in Grid and Snap overlay: activate Grid Snapping with handle rotation set to Global, or hold Ctrl/Cmd while drawing, and set Increment Snap.
  3. Connecting edges on one face leaves a T-junction; an edge loop continues round the object through quads, keeping the topology clean.
  4. They are lost; re-entering shape editing discards changes made with actions or the Cut tool.
  5. A Mesh Collider; the Collider Type setting in Edit > Preferences > ProBuilder can change it to Box Collider or None.
  6. Set Pivot (Ctrl/Cmd+J) with the faces selected in face mode.

Graph View

Backlinks