Last reviewed 31 Jul 2026

Applies to

Unity 2022.3 Mesh painting and sculpting VRChat world projects

Difficulty Intermediate

Polybrush in Unity 2022.3

Polybrush edits meshes directly in the Unity Scene view. Its five modes sculpt or smooth vertices, paint vertex colors, blend textures, and scatter prefabs across a mesh surface.

First Polybrush test

Install the released package, duplicate a test mesh, and confirm the material supports the data you want to paint.

Install Polybrush from Window > Package Manager.
Open Tools > Polybrush > Polybrush Window.
Select a mesh, activate one brush mode, and test it on the duplicate.

VRChat project note

After changing meshes, materials, or scattered prefabs, use the VRChat SDK's local Build & Test workflow before publishing the world. Test every target platform that uses a different material or shader setup.

Package Support

Editor	Polybrush status
Unity 2022.3	Unity lists Polybrush 1.1.8 as released and versions 1.2.0 and 1.2.1 as compatible.
Unity 6.3 and later	Polybrush 1.2 documentation marks the package deprecated and unsupported.

This guide targets Unity 2022.3. Let Package Manager resolve a compatible version for the project instead of copying a package version from a tutorial made for another Unity release.

Install and Open Polybrush

Open Window > Package Manager.
Select Unity Registry.
Select Polybrush and click Install.
Open Tools > Polybrush > Polybrush Window.

Polybrush 1.0 and newer is distributed through Package Manager. The package name is com.unity.polybrush.

The window contains:

the Mode toolbar;
shared Brush Settings for radius, falloff, strength, and falloff curve;
Brush Mirroring controls;
settings for the active mode.

Click the active mode again, select a normal Unity transform tool, or press Esc to deactivate the brush.

Choose the Correct Mode

Mode	What Unity says it changes	Required preparation
Sculpt	Moves mesh vertices.	Use a mesh with vertices where the surface needs to move.
Smooth	Smooths differences between vertex positions.	Work on a duplicate when the original form must be preserved.
Color	Paints colors on mesh vertices.	Apply a material whose shader supports vertex colors.
Texture	Paints and blends textures across a mesh.	Use a shader configured for texture blending.
Scatter	Places prefabs on a mesh surface.	Add prefabs to the current palette and brush loadout.

Polybrush does not work on Unity Terrain. Use Unity's dedicated Terrain tools for Terrain objects.

Paint Vertex Colors

Most default Unity shaders do not display vertex colors. Apply a compatible material before painting, or import one of the Polybrush sample shaders.

Select the mesh.
Activate Paint vertex colors on meshes in the Mode toolbar.
Set the brush radius, falloff, and strength.
Select Brush, Fill, or Flood under Color Paint Settings.
Select a color swatch.
Hover over the mesh and left-click to paint.
Hold Ctrl on Windows or Command on macOS while left-clicking to erase painted vertex colors.

The color mode can enable or disable the R, G, B, and A channels independently. Leave a channel disabled when the shader uses it for data that the current paint pass must not change.

Paint and Blend Textures

Texture mode requires a material whose shader defines how mesh channels control texture blending. Polybrush displays a warning when the shader is incompatible.

Select the mesh and activate Paint textures on meshes.
Choose the material if the mesh has more than one.
Select Configure if the shader's texture slots are not already configured.
Choose a texture slot.
Set radius, falloff, strength, and optional mirroring.
Left-click the mesh to paint.
Hold Ctrl on Windows or Command on macOS while painting to remove the selected texture.

Polybrush can use mesh Color, Tangent, UV1, UV2, UV3, or UV4 channels for texture data. The shader metadata determines which channel and component controls each texture.

Import the Sample Shaders

Polybrush includes sample shaders for vertex colors and texture blending:

Open Polybrush in Package Manager.
Find the Samples section.
Import the shader sample for the material workflow or render pipeline.
Find the imported files under Assets/Samples/Polybrush.
Apply a compatible sample material to a test mesh before painting.

Importing a sample does not automatically replace materials already assigned in the scene.

Scatter Prefabs

Select the mesh that will receive the prefabs.
Activate Scatter Prefabs on meshes.
Drag prefabs into the Current Palette and enable the ones to use.
Select one or more prefabs in the Brush Loadout.
Configure radius, falloff, strength, and Prefab Scatter Settings.
Left-click the mesh to place prefabs.
Hold Ctrl on Windows or Command on macOS while painting to erase selected prefabs.

Useful scatter settings include:

Use Pivot places the prefab's pivot on the surface instead of its center.
Hit Surface is Parent parents placed prefabs to the painted surface.
Avoid Overlap reduces overlapping placement.

Review the resulting hierarchy after scattering so the new instances remain easy to select and remove.

Sculpt and Smooth Meshes

Sculpt mode moves existing vertices; Smooth mode reduces differences between their positions. Neither mode creates a Unity Terrain.

Before editing:

Duplicate the object or work in a copied scene.
Confirm the selected object is the intended mesh.
Start with a low brush strength.
Check the silhouette from more than one Scene view angle.
Save only after comparing the edited form with the original.

The available vertices determine where the surface can change. If a brush produces broad or angular results, inspect the mesh topology instead of repeatedly increasing brush strength.

How Polybrush Stores Edited Data

Polybrush 1.0 and newer uses a PolybrushMesh component to manage its mesh data. Older projects may contain the deprecated Z_AdditionalVertexStreams component.

For an older project, Unity provides Tools > Polybrush > Upgrade Z_AdditionalVertexStreams to convert loaded scenes to the newer component. Back up the project, run the conversion in a migration copy, and save the scenes only after checking the result.

Legacy Video Reference

This Unity video uses the older Unity 2019 interface, but it demonstrates the same brush-based mesh workflow.

Open the Polybrush video on YouTube

Troubleshooting

Polybrush does not appear in Package Manager

Confirm Package Manager is showing Unity Registry and that the project is open in its intended Unity version. Unity lists Polybrush as a released package for Unity 2022.3.

The brush does not affect a Terrain

Polybrush is not compatible with Unity Terrain. Select a mesh object or use the dedicated Unity Terrain tools.

Painted vertex colors are invisible

The material's shader must support vertex colors. Apply a compatible material or import a Polybrush sample shader, then test the mesh again.

Texture slots are missing or Polybrush shows a shader warning

The shader does not expose compatible texture-blending metadata. Use Configure for a compatible custom shader or test with an imported Polybrush sample shader.

Sculpting looks angular or barely changes the surface

Sculpt mode moves existing vertices. Inspect the mesh topology and vertex spacing; brush radius and strength cannot provide control points that the mesh does not contain.

Scattered prefabs overlap or sit inside the surface

Enable Avoid Overlap, check whether Use Pivot matches the prefab's pivot placement, and reduce brush strength before painting again.

The Polybrush tool remains active

Click the active mode, select Move, Rotate, or Scale, or press Esc to return to normal Scene view controls.