Class ProBuilderMesh

This component is responsible for storing all the data necessary for editing and compiling UnityEngine.Mesh objects.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
ProBuilderMesh
Inherited Members
Namespace: UnityEngine.ProBuilder
Syntax
[AddComponentMenu("//ProBuilder MeshFilter")]
[RequireComponent(typeof(MeshRenderer))]
[DisallowMultipleComponent]
[ExecuteInEditMode]
[ExcludeFromPreset]
[ExcludeFromObjectFactory]
public sealed class ProBuilderMesh : MonoBehaviour

Fields

maxVertexCount

The maximum number of vertices that a ProBuilderMesh can accomodate.

Declaration
public const uint maxVertexCount = 65535U
Field Value
Type Description
UInt32

Properties

colors

Declaration
public IList<Color> colors { get; set; }
Property Value
Type Description
IList<Color>

Vertex colors array for this mesh. When setting, the value must match the length of positions.

edgeCount

Declaration
public int edgeCount { get; }
Property Value
Type Description
Int32

How many edges compose this mesh.

faceCount

Declaration
public int faceCount { get; }
Property Value
Type Description
Int32

How many faces does this mesh have?

faces

Meshes are composed of vertices and faces. Faces primarily contain triangles and material information. With these components, ProBuilder will compile a mesh.

Declaration
public IList<Face> faces { get; set; }
Property Value
Type Description
IList<Face>

A collection of the @"UnityEngine.ProBuilder.Face"'s that make up this mesh.

indexCount

Declaration
public int indexCount { get; }
Property Value
Type Description
Int32

How many vertex indexes make up this mesh.

meshSyncState

Ensure that the UnityEngine.Mesh is in sync with the ProBuilderMesh.

Declaration
public MeshSyncState meshSyncState { get; }
Property Value
Type Description
MeshSyncState

A flag describing the state of the synchronicity between the MeshFilter.sharedMesh and ProBuilderMesh components.

normals

Declaration
public IList<Vector3> normals { get; }
Property Value
Type Description
IList<Vector3>

The mesh normals.

positions

Declaration
public IList<Vector3> positions { get; set; }
Property Value
Type Description
IList<Vector3>

The vertex positions that make up this mesh.

preserveMeshAssetOnDestroy

Declaration
public bool preserveMeshAssetOnDestroy { get; set; }
Property Value
Type Description
Boolean

In the editor, when you delete a ProBuilderMesh you usually also want to destroy the mesh asset. However, there are situations you'd want to keep the mesh around, like when stripping probuilder scripts.

selectable

Declaration
public bool selectable { get; set; }
Property Value
Type Description
Boolean

If false mesh elements will not be selectable. This is used by @"UnityEditor.ProBuilder.ProBuilderEditor".

selectedEdgeCount

Declaration
public int selectedEdgeCount { get; }
Property Value
Type Description
Int32

Get the number of selected edges.

selectedEdges

Declaration
public ReadOnlyCollection<Edge> selectedEdges { get; }
Property Value
Type Description
ReadOnlyCollection<Edge>

A collection of the currently selected edges.

selectedFaceCount

Declaration
public int selectedFaceCount { get; }
Property Value
Type Description
Int32

Get the number of faces that are currently selected on this object.

selectedFaceIndexes

Declaration
public ReadOnlyCollection<int> selectedFaceIndexes { get; }
Property Value
Type Description
ReadOnlyCollection<Int32>

A collection of the currently selected faces by their index in the @"UnityEngine.ProBuilder.ProBuilderMesh.faces" array.

selectedVertexCount

Declaration
public int selectedVertexCount { get; }
Property Value
Type Description
Int32

Get the number of selected vertex indexes.

selectedVertices

Declaration
public ReadOnlyCollection<int> selectedVertices { get; }
Property Value
Type Description
ReadOnlyCollection<Int32>

A collection of the currently selected vertices by their index in the @"UnityEngine.ProBuilder.ProBuilderMesh.positions" array.

sharedVertices

ProBuilder makes the assumption that no @"UnityEngine.ProBuilder.Face" references a vertex used by another. However, we need a way to associate vertices in the editor for many operations. These vertices are usually called coincident, or shared vertices. ProBuilder manages these associations with the sharedIndexes array. Each array contains a list of triangles that point to vertices considered to be coincident. When ProBuilder compiles a UnityEngine.Mesh from the ProBuilderMesh, these vertices will be condensed to a single vertex where possible.

Declaration
public IList<SharedVertex> sharedVertices { get; set; }
Property Value
Type Description
IList<SharedVertex>

The shared (or common) index array for this mesh.

tangents

Declaration
public IList<Vector4> tangents { get; set; }
Property Value
Type Description
IList<Vector4>

Get the user-set tangents array for this mesh. If tangents have not been explicitly set, this value will be null.
Remarks

To get the generated tangents that are applied to the mesh through Refresh(), use GetTangents().

See Also

textures

Declaration
public IList<Vector2> textures { get; set; }
Property Value
Type Description
IList<Vector2>

The UV0 channel. Null if not present.
See Also

triangleCount

Declaration
public int triangleCount { get; }
Property Value
Type Description
Int32

How many triangles make up this mesh.

unwrapParameters

Declaration
public UnwrapParameters unwrapParameters { get; set; }
Property Value
Type Description
UnwrapParameters

UV2 generation parameters.

userCollisions

Declaration
public bool userCollisions { get; set; }
Property Value
Type Description
Boolean

If false, ProBuilder will automatically create and scale colliders.

vertexCount

Declaration
public int vertexCount { get; }
Property Value
Type Description
Int32

How many vertices are in the positions array.

Methods

Clear()

Reset all the attribute arrays on this object.

Declaration
public void Clear()

ClearSelection()

Clears selected face, edge, and vertex arrays. You do not need to call this when setting an individual array, as the setter methods will handle updating the associated caches.

Declaration
public void ClearSelection()

CopyFrom(ProBuilderMesh)

Copy mesh data from another mesh to self.

Declaration
public void CopyFrom(ProBuilderMesh other)
Parameters
Type Name Description
ProBuilderMesh other

Create()

Create a new GameObject with a ProBuilderMesh component, MeshFilter, and MeshRenderer. All arrays are initialized as empty.

Declaration
public static ProBuilderMesh Create()
Returns
Type Description
ProBuilderMesh

A reference to the new ProBuilderMesh component.

Create(IEnumerable<Vector3>, IEnumerable<Face>)

Create a new GameObject with a ProBuilderMesh component, MeshFilter, and MeshRenderer, then initializes the ProBuilderMesh with a set of positions and faces.

Declaration
public static ProBuilderMesh Create(IEnumerable<Vector3> positions, IEnumerable<Face> faces)
Parameters
Type Name Description
IEnumerable<Vector3> positions

Vertex positions array.
IEnumerable<Face> faces

Faces array.
Returns
Type Description
ProBuilderMesh

A reference to the new ProBuilderMesh component.

Create(IList<Vertex>, IList<Face>, IList<SharedVertex>, IList<SharedVertex>, IList<Material>)

Create a new GameObject with a ProBuilderMesh component, MeshFilter, and MeshRenderer, then initializes the ProBuilderMesh with a set of positions and faces.

Declaration
public static ProBuilderMesh Create(IList<Vertex> vertices, IList<Face> faces, IList<SharedVertex> sharedVertices = null, IList<SharedVertex> sharedTextures = null, IList<Material> materials = null)
Parameters
Type Name Description
IList<Vertex> vertices

Vertex positions array.
IList<Face> faces

Faces array.
IList<SharedVertex> sharedVertices

Optional SharedVertex[] defines coincident vertices.
IList<SharedVertex> sharedTextures

Optional SharedVertex[] defines coincident texture coordinates (UV0).
IList<Material> materials

Optional array of materials that will be assigned to the MeshRenderer.
Returns
Type Description
ProBuilderMesh

GetCoincidentVertices(IEnumerable<Int32>)

Get a list of vertices that are coincident to any of the vertices in the passed vertices parameter.

Declaration
public List<int> GetCoincidentVertices(IEnumerable<int> vertices)
Parameters
Type Name Description
IEnumerable<Int32> vertices

A collection of indexes relative to the mesh positions.
Returns
Type Description
List<Int32>

A list of all vertices that share a position with any of the passed vertices.
Exceptions
Type Condition
ArgumentNullException

The vertices parameter may not be null.

GetCoincidentVertices(IEnumerable<Int32>, List<Int32>)

Populate a list of vertices that are coincident to any of the vertices in the passed vertices parameter.

Declaration
public void GetCoincidentVertices(IEnumerable<int> vertices, List<int> coincident)
Parameters
Type Name Description
IEnumerable<Int32> vertices

A collection of indexes relative to the mesh positions.
List<Int32> coincident

A list to be cleared and populated with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

GetCoincidentVertices(IEnumerable<Edge>, List<Int32>)

Populate a list of vertices that are coincident to any of the vertices in the passed vertices parameter.

Declaration
public void GetCoincidentVertices(IEnumerable<Edge> edges, List<int> coincident)
Parameters
Type Name Description
IEnumerable<Edge> edges

A collection of edges to gather vertices from.
List<Int32> coincident

A list to be cleared and populated with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

GetCoincidentVertices(IEnumerable<Face>, List<Int32>)

Populate a list of vertices that are coincident to any of the vertices in the passed vertices parameter.

Declaration
public void GetCoincidentVertices(IEnumerable<Face> faces, List<int> coincident)
Parameters
Type Name Description
IEnumerable<Face> faces

A collection of faces to gather vertices from.
List<Int32> coincident

A list to be cleared and populated with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

GetCoincidentVertices(Int32, List<Int32>)

Populate a list with all the vertices that are coincident to the requested vertex.

Declaration
public void GetCoincidentVertices(int vertex, List<int> coincident)
Parameters
Type Name Description
Int32 vertex

An index relative to a positions array.
List<Int32> coincident

A list to be populated with all coincident vertices.
Exceptions
Type Condition
ArgumentNullException

The coincident list may not be null.
ArgumentOutOfRangeException

The SharedVertex[] does not contain an entry for the requested vertex.

GetColors()

Get an array of Color values from the mesh.

Declaration
public Color[] GetColors()
Returns
Type Description
Color[]

The colors array for this mesh. If mesh does not contain colors, a new array is returned filled with the default value (Color.white).

GetNormals()

Declaration
public Vector3[] GetNormals()
Returns
Type Description
Vector3[]

Get the normals array for this mesh.

GetSelectedFaces()

Get a copy of the selected face array.

Declaration
public Face[] GetSelectedFaces()
Returns
Type Description
Face[]

GetTangents()

Get the tangents applied to the mesh, or create and cache them if not yet initialized.

Declaration
public Vector4[] GetTangents()
Returns
Type Description
Vector4[]

The tangents applied to the MeshFilter.sharedMesh. If the tangents array length does not match the vertex count, null is returned.

GetUVs(Int32, List<Vector4>)

Copy values in a UV channel to uvs.

Declaration
public void GetUVs(int channel, List<Vector4> uvs)
Parameters
Type Name Description
Int32 channel

The index of the UV channel to fetch values from. The valid range is {0, 1, 2, 3}.
List<Vector4> uvs

A list that will be cleared and populated with the UVs copied from this mesh.

GetVertices(IList<Int32>)

Creates a new array of vertices with values from a @"UnityEngine.ProBuilder.ProBuilderMesh" component.

Declaration
public Vertex[] GetVertices(IList<int> indexes = null)
Parameters
Type Name Description
IList<Int32> indexes

An optional list of indexes pointing to the mesh attribute indexes to include in the returned Vertex array.
Returns
Type Description
Vertex[]

An array of vertices.

HasArrays(MeshArrays)

Check if the mesh contains the requested arrays.

Declaration
public bool HasArrays(MeshArrays channels)
Parameters
Type Name Description
MeshArrays channels

A flag containing the array types that a ProBuilder mesh stores.
Returns
Type Description
Boolean

True if all arrays in the flag are present, false if not.

RebuildWithPositionsAndFaces(IEnumerable<Vector3>, IEnumerable<Face>)

Clear all mesh attributes and reinitialize with new positions and face collections.

Declaration
public void RebuildWithPositionsAndFaces(IEnumerable<Vector3> vertices, IEnumerable<Face> faces)
Parameters
Type Name Description
IEnumerable<Vector3> vertices

Vertex positions array.
IEnumerable<Face> faces

Faces array.

Refresh(RefreshMask)

Recalculates mesh attributes: normals, collisions, UVs, tangents, and colors.

Declaration
public void Refresh(RefreshMask mask = RefreshMask.UV | RefreshMask.Colors | RefreshMask.Normals | RefreshMask.Tangents | RefreshMask.Collisions | RefreshMask.All)
Parameters
Type Name Description
RefreshMask mask

Optionally pass a mask to define what components are updated (UV and collisions are expensive to rebuild, and can usually be deferred til completion of task).

RefreshUV(IEnumerable<Face>)

Declaration
public void RefreshUV(IEnumerable<Face> facesToRefresh)
Parameters
Type Name Description
IEnumerable<Face> facesToRefresh

SetFaceColor(Face, Color)

Set the vertex colors for a @"UnityEngine.ProBuilder.Face".

Declaration
public void SetFaceColor(Face face, Color color)
Parameters
Type Name Description
Face face

The target face.
Color color

The color to set this face's referenced vertices to.

SetMaterial(IEnumerable<Face>, Material)

Set the material for a collection of faces.

Declaration
public void SetMaterial(IEnumerable<Face> faces, Material material)
Parameters
Type Name Description
IEnumerable<Face> faces

The faces to apply the material to.
Material material

The material to apply.
Remarks

To apply the changes to the UnityEngine.Mesh, make sure to call ToMesh and Refresh.

SetSelectedEdges(IEnumerable<Edge>)

Set the edge selection for this mesh. Also sets the face and vertex selection to match.

Declaration
public void SetSelectedEdges(IEnumerable<Edge> edges)
Parameters
Type Name Description
IEnumerable<Edge> edges

The new edge selection.

SetSelectedFaces(IEnumerable<Face>)

Set the face selection for this mesh. Also sets the vertex and edge selection to match.

Declaration
public void SetSelectedFaces(IEnumerable<Face> selected)
Parameters
Type Name Description
IEnumerable<Face> selected

The new face selection.

SetSelectedVertices(IEnumerable<Int32>)

Sets the selected vertices array. Clears SelectedFaces and SelectedEdges arrays.

Declaration
public void SetSelectedVertices(IEnumerable<int> vertices)
Parameters
Type Name Description
IEnumerable<Int32> vertices

The new vertex selection.

SetUVs(Int32, List<Vector4>)

Set the mesh UVs per-channel. Channels 0 and 1 are cast to Vector2, where channels 2 and 3 are kept Vector4.

Declaration
public void SetUVs(int channel, List<Vector4> uvs)
Parameters
Type Name Description
Int32 channel

The index of the UV channel to fetch values from. The valid range is {0, 1, 2, 3}.
List<Vector4> uvs

The new UV values.
Remarks

Does not apply to mesh (use Refresh to reflect changes after application).

SetVertices(IList<Vertex>, Boolean)

Set the vertex element arrays on this mesh.

Declaration
public void SetVertices(IList<Vertex> vertices, bool applyMesh = false)
Parameters
Type Name Description
IList<Vertex> vertices

The new vertex array.
Boolean applyMesh

An optional parameter that will apply elements to the MeshFilter.sharedMesh. Note that this should only be used when the mesh is in its original state, not optimized (meaning it won't affect triangles which can be modified by Optimize).

SetVerticesCoincident(IEnumerable<Int32>)

Sets the passed vertices as being considered coincident by the ProBuilderMesh.

Declaration
public void SetVerticesCoincident(IEnumerable<int> vertices)
Parameters
Type Name Description
IEnumerable<Int32> vertices

Returns a list of vertices to be associated as coincident.
Remarks

Note that it is up to the caller to ensure that the passed vertices are indeed sharing a position.

ToMesh(MeshTopology)

Rebuild the mesh positions and submeshes. If vertex count matches new positions array the existing attributes are kept, otherwise the mesh is cleared. UV2 is the exception, it is always cleared.

Declaration
public void ToMesh(MeshTopology preferredTopology = MeshTopology.Triangles)
Parameters
Type Name Description
MeshTopology preferredTopology

Triangles and Quads are supported.

Events

elementSelectionChanged

Declaration
public static event Action<ProBuilderMesh> elementSelectionChanged
Event Type
Type Description
Action<ProBuilderMesh>

Invoked when the element selection changes on any ProBuilderMesh.
See Also

meshWillBeDestroyed

In the editor, when a ProBuilderMesh is destroyed it will also destroy the MeshFilter.sharedMesh that is found with the parent GameObject. You may override this behaviour by subscribing to onDestroyObject.

Declaration
public static event Action<ProBuilderMesh> meshWillBeDestroyed
Event Type
Type Description
Action<ProBuilderMesh>

If onDestroyObject has a subscriber ProBuilder will invoke it instead of cleaning up unused meshes by itself.
See Also

Extension Methods