Mesh

Description

A class that allows creating or modifying meshes from scripts.

Meshes contain vertex data (Positions, Normals, TexCoords etc.) and "face" data, with faces most often being triangles.

Conceptually, all vertex data is stored in separate arrays of the same size. For example, if you have a mesh of 100 Vertices, and want to have a position, normal and two texture coordinates for each vertex, then the mesh should have vertices, normals, uv and uv2 arrays, each being 100 in size. Data for i-th vertex is at index "i" in each array.

For every vertex there can be a vertex position, normal, tangent, color and up to 8 texture coordinates. Texture coordinates most often are 2D data (Vector2), but it is possible to make them Vector3 or Vector4 if needed. This is most often used for holding arbitrary data in mesh vertices, for special effects used in shaders. For skinned meshes, the vertex data can also contain boneWeights.

The mesh face data, i.e. the triangles it is made of, is simply three vertex indices for each triangle. For example, if the mesh has 10 triangles, then the triangles array should be 30 numbers, with each number indicating which vertex to use. The first three elements in the triangles array are the indices for the vertices that make up that triange; the second three elements make up another triangle and so on.

Note that while triangle meshes are the most common use case, Unity also supports other mesh topology types, for example Line or Point meshes. For line meshes, each line is composed of two vertex indices and so on. See SetIndices and MeshTopology.

Simple vs Advanced Mesh API

The Mesh class has two sets of methods for assigning data to a Mesh from script. The "simple" set of methods provide a basis for setting the indices, triangle, normals, tangents, etc. These methods include validation checks, for example to ensure that you are not passing in data that would include out-of-bounds indices. They represent the standard way to assign Mesh data from script in Unity.

The "simple" methods are: SetColors, SetIndices, SetNormals, SetTangents, SetTriangles, SetUVs, SetVertices, SetBoneWeights

There is also an "advanced" set of methods, which allow you to directly write to the mesh data with control over whether any checks or validation should be performed. These methods are intended for advanced use cases which require maximum performance. They are faster, but allow you to skip the checks on the data you supply. If you use these methods you must make sure that you are not supplying invalid data, because Unity will not check for you.

The "advanced" methods are: SetVertexBufferParams, SetVertexBufferData, SetIndexBufferParams, SetIndexBufferData, SetSubMesh, and you can use the MeshUpdateFlags to control which checks or validation are performed or omitted.



Manipulating meshes from a script

There are three common tasks that might want to use the Mesh API for:

1. Building a mesh from scratch: should always be done in the following order:
a) Assign vertices
b) Assign triangles.

using UnityEngine;

public class Example : MonoBehaviour
{
    Vector3[] newVertices;
    Vector2[] newUV;
    int[] newTriangles;

    void Start()
    {
        Mesh mesh = new Mesh();
        GetComponent<MeshFilter>().mesh = mesh;
        mesh.vertices = newVertices;
        mesh.uv = newUV;
        mesh.triangles = newTriangles;
    }
}

2. Modifying vertex attributes every frame:
a) Get vertices
b) Modify them
c) Assign them back to the mesh.

using UnityEngine;

public class Example : MonoBehaviour
{
    void Update()
    {
        Mesh mesh = GetComponent<MeshFilter>().mesh;
        Vector3[] vertices = mesh.vertices;
        Vector3[] normals = mesh.normals;

        for (var i = 0; i < vertices.Length; i++)
        {
            vertices[i] += normals[i] * Mathf.Sin(Time.time);
        }

        mesh.vertices = vertices;
    }
}

3. Continously changing the mesh triangles and vertices:
a) Call Clear to start fresh
b) Assign vertices and other attributes
c) Assign triangle indices.

It is important to call Clear before assigning new vertices or triangles. Unity always checks the supplied triangle indices whether they don't reference out of bounds vertices. Calling Clear then assigning vertices then triangles makes sure you never have out of bounds data.

using UnityEngine;

public class ExampleClass : MonoBehaviour
{
    Vector3[] newVertices;
    Vector2[] newUV;
    int[] newTriangles;

    void Start()
    {
        Mesh mesh = GetComponent<MeshFilter>().mesh;

        mesh.Clear();

        // Do some calculations...
        mesh.vertices = newVertices;
        mesh.uv = newUV;
        mesh.triangles = newTriangles;
    }
}

Variables

Constructors

Public Functions

Inherited members