Class ProBuilderMesh

Represents the ProBuilder MeshFilter component, which is responsible for storing all the data necessary for editing and compiling Mesh objects.

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

Fields

maxVertexCount

The maximum number of vertices that a ProBuilderMesh can accomodate.

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

Properties

colors

Gets or sets a collecton of the vertex colors for this mesh. When setting, the value must match the length of the positions.

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

A collection of colors for this mesh.

edgeCount

Gets the number of edges that compose this mesh.

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

The number of edges in this mesh.

faceCount

Gets the number of faces that this mesh has.

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

The number of faces on this mesh.

faces

Gets or sets the faces that ProBuilder uses to compile a mesh.

Meshes are composed of vertices and faces. Faces primarily contain triangles and material information.

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

A collection of the Face objects that make up this mesh.

indexCount

Gets the number of vertex indices that compose this mesh.

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

The number of vertices in this mesh.

meshSyncState

Gets a flag that indicates whether the Mesh is in sync with the ProBuilderMesh.

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

A flag that describes the state of the synchronicity between the sharedMesh and ProBuilderMesh components.

normals

Gets the normals for this mesh.

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

A collection of normals for this mesh.

positions

Gets or sets the vertex positions that compose this mesh.

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

preserveMeshAssetOnDestroy

Gets or sets whether to destroy the mesh asset if this ProBuilderMesh is deleted.

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.

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

True to keep the mesh asset; false to destroy it.

selectable

Gets or sets whether elements can be selected. Used by UnityEditor.ProBuilder.ProBuilderEditor.

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

False if mesh elements are not selectable.

selectedEdgeCount

Gets the number of selected edges.

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

Number of selected edges.

selectedEdges

Gets a collection of the currently selected edges.

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

Collection of Edge objects representing the currently selected edges.

selectedFaceCount

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

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

Number of selected faces.

selectedFaceIndexes

Gets a collection of the currently selected faces by their index in the faces array.

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

Array of indices representing the currently selected faces.

selectedVertexCount

Gets the number of selected vertex indices.

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

Number of selected vertices.

selectedVertices

Gets a collection of the currently selected vertices by their index in the positions array.

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

Array of indices representing the currently selected vertices.

sharedVertices

Gets or sets the sharedVertices for this ProBuilderMesh object.

ProBuilder makes the assumption that no Face references a vertex used by another. However, ProBuilder needs to be able 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 points to vertices considered to be coincident. When ProBuilder compiles a Mesh from the ProBuilderMesh, it condenses these vertices 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

Gets or sets the array of tangents that the user explicitly set for this mesh.

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

A collection of tangents for this mesh or null if the user hasn't set any tangents yet.
Remarks

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

See Also

textures

Gets or sets the UV0 channel.

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

The list of texture UVs for this mesh or null if there are none.
See Also

triangleCount

Gets the number of triangles that compose this mesh.

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

The number of triangles in this mesh.

unwrapParameters

UV2 generation parameters.

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

userCollisions

If false, ProBuilder will automatically create and scale colliders.

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

vertexCount

Gets the number of vertices in the positions array.

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

The number of vertex positions for this mesh.

Methods

Clear()

Resets (empties) all the attribute arrays on this object and clears any selected elements. The attribute arrays include faces, positions, texture UVs, tangents, shared vertices, shared textures, and vertex colors.

Declaration
public void Clear()

ClearSelection()

Clears the arrays of selected faces, edges, and vertices. You don't need to call this when setting an individual array, as the setter methods handle updating the associated caches.

Declaration
public void ClearSelection()

CopyFrom(ProBuilderMesh)

Copies the mesh data from another mesh to this one.

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

The mesh to copy from.

Create()

Creates a new GameObject with a ProBuilderMesh, MeshFilter, and MeshRenderer component but leaves the position and face information empty.

Declaration
public static ProBuilderMesh Create()
Returns
Type Description
ProBuilderMesh

A reference to the new ProBuilderMesh component.

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

Creates a new GameObject with a ProBuilderMesh, MeshFilter, and MeshRenderer component. Then it initializes the ProBuilderMesh with the specified sets 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>)

Creates a new GameObject with a ProBuilderMesh, MeshFilter, and MeshRenderer component. Then it initializes the ProBuilderMesh with the specified sets of positions and faces, and if specified, coincident vertices, texture coordinates, and materials.

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

Array of vertex positions to use.
IList<Face> faces

Array of faces to use.
IList<SharedVertex> sharedVertices

Optional SharedVertex array to define the coincident vertices.
IList<SharedVertex> sharedTextures

Optional SharedVertex array to define the coincident texture coordinates (UV0).
IList<Material> materials

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

A reference to the new ProBuilderMesh component.

GetCoincidentVertices(IEnumerable<int>)

Returns a list of vertices that are coincident to any of the specified vertices.

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

A collection of indices relative to the mesh positions.
Returns
Type Description
List<int>

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

The vertices parameter may not be null.

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

Populates a list of vertices that are coincident to any of the specified vertices.

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

A collection of indices relative to the mesh positions.
List<int> coincident

The list to clear and populate with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

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

Populates a list of vertices that are coincident to any of the specified vertices.

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<int> coincident

The list to clear and populate with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

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

Populates a list of vertices that are coincident to any of the specified vertices.

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<int> coincident

The list to clear and populate with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The vertices and coincident parameters may not be null.

GetCoincidentVertices(int, List<int>)

Populates a list with all the vertices that are coincident to the specified vertex.

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

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

The list to clear and populate with any vertices that are coincident.
Exceptions
Type Condition
ArgumentNullException

The coincident list may not be null.
ArgumentOutOfRangeException

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

GetColors()

Returns the Color values from the mesh.

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

An array of colors for this mesh. If the mesh does not contain colors, it returns a new array filled with the default value (white).

GetNormals()

Gets the normals array for this mesh.

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

An array of normals for this mesh.

GetSelectedFaces()

Returns a copy of the array of selected faces.

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

Array of currently selected faces.

GetTangents()

Returns the tangents applied to the mesh. If they haven't been initialized yet, it creates and caches them.

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

The tangents applied to sharedMesh or null if the tangents array length doesn't match the vertex count.

GetUVs(int, List<Vector4>)

Copies values from the specified UV channel to the list of texture UVs.

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

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

The list of texture UVs to clear and populate with the copied UVs.

GetVertices(IList<int>)

Creates a new array of vertices with values from a ProBuilderMesh component.

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

An optional list of indices used to designate the subset of vertices values to retrieve from the mesh in the array.
Returns
Type Description
Vertex[]

An array of vertices matching either the specified list in the indexes parameter. If the indexes parameter contains no list, this returns all mesh vertices.

HasArrays(MeshArrays)

Tests whether 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
bool

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

MakeUnique()

Ensures that the UnityEngine.Mesh associated with this object is unique. When instantiating a ProBuilderMesh, the mesh asset will reference the original instance. If you are making a copy to edit, you must call MakeUnique to avoid modifying a shared mesh asset.

Declaration
public void MakeUnique()

OnAfterDeserialize()

Implement this method to receive a callback after Unity deserializes your object.

Declaration
public void OnAfterDeserialize()

OnBeforeSerialize()

Implement this method to receive a callback before Unity serializes your object.

Declaration
public void OnBeforeSerialize()

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

Clears all mesh attributes and reinitializes the mesh with new positions and face collections.

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

New vertex positions array to use.
IEnumerable<Face> faces

New faces array to use.

Refresh(RefreshMask)

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

Declaration
public void Refresh(RefreshMask mask = RefreshMask.All)
Parameters
Type Name Description
RefreshMask mask

Optional. Specify a RefreshMask to indicate which components to update. Use this when you want to wait until later to rebuild some components in order to save processing power, since UVs and collisions are expensive to rebuild and can usually be deferred until the task finishes.

RefreshUV(IEnumerable<Face>)

Rebuilds the UV arrays on the specified faces.

This usually applies only to faces set to use Auto UVs. However, if ProBuilder can't detect any valid UV arrays, it resets the faces from Manual to Auto before rebuilding them.

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

The set of faces to process.
See Also

SetFaceColor(Face, Color)

Applies a vertex color to the specified Face.

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

The target face to apply the colors to.
Color color

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

SetMaterial(IEnumerable<Face>, Material)

Sets a specific material on 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 Mesh, call ToMesh(MeshTopology) and Refresh(RefreshMask).

SetSelectedEdges(IEnumerable<Edge>)

Sets the edge selection for this mesh. Also sets the vertex selection to match and clears the selected faces.

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

A set of edges to select.

SetSelectedFaces(IEnumerable<Face>)

Sets 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

A set of faces to select.

SetSelectedVertices(IEnumerable<int>)

Sets the selected vertices array. Clears the selected faces and selected edges arrays.

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

The new vertices to select.

SetUVs(int, List<Vector4>)

Sets the mesh UVs per channel. Channels 0 and 1 are cast to Vector2, but channels 2 and 3 remain Vector4.

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

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

The list of new UV values.
Remarks

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

SetVertices(IList<Vertex>, bool)

Sets 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.
bool applyMesh

Optionally indicate whether to apply elements to the sharedMesh. Note that you should only use this when the mesh is in its original state, not optimized (that is, when it won't affect triangles which can be UnityEditor.ProBuilder.EditorMeshUtility.Optimize).

SetVerticesCoincident(IEnumerable<int>)

Marks the specified vertices as coincident on this mesh.

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

The list of vertices to be marked as coincident.
Remarks

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

ToMesh(MeshTopology)

Rebuilds the mesh positions and submeshes.

If the vertex count matches the new positions array, the existing attributes are kept (except for UV2s, which are always cleared). Otherwise, the mesh is cleared.

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

You can specify MeshTopology.Quads if you don't want to use the default MeshTopology.Triangles.

Events

elementSelectionChanged

Invoked when the element selection changes on any ProBuilderMesh.

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

meshWillBeDestroyed

Invoked when this ProBuilderMesh is deleted.

In the Editor, when a ProBuilderMesh is destroyed it also destroys the sharedMesh that it finds with the parent GameObject. To override the default behavior, subscribe to onDestroyObject. When onDestroyObject has a subscriber, ProBuilder invokes it instead of cleaning up unused meshes by itself.

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

Implements

Extension Methods