Unity Procedural Mesh

Unity Procedural Mesh Generation

Retrieval Sources

Key Guidelines

Basic Mesh Construction (vertices/triangles/UVs)

A Mesh stores vertex data as several parallel arrays of equal length — position, normal, tangent, color, and up to 8 UV channels — where index i in every array describes the same logical vertex (Manual/mesh-vertex-data.html). Positions are required; everything else is optional and can be left unassigned if a shader doesn't need it. Triangles are a flat int[] of indices into the vertex arrays, taken three at a time; Unity culls back-facing triangles by default using a clockwise winding rule, so the indices for each face must run clockwise as seen from the visible side or the triangle renders invisible from the front and visible from the back (Manual/mesh-index-data.html). The Mesh class exposes two parallel scripting surfaces: a "simple" API (SetVertices, SetTriangles, SetNormals, SetUVs, SetColors, SetIndices, SetBoneWeights, plus the older bare array properties like .vertices/.triangles/.uv) that validates the data you hand it and is the right default for nearly all procedural-mesh code, and an "advanced" buffer API (covered below) for cases where that validation overhead actually shows up in a profile (ScriptReference/Mesh.html). When building a mesh from scratch, always assign vertices before triangles — Unity validates triangle indices against the current vertex count at assignment time, so assigning triangles first (or against a stale, smaller vertex array) throws an out-of-bounds exception. When rebuilding a mesh that already has data (e.g. regenerating a procedural terrain chunk in place), call Mesh.Clear() first so the old, larger index buffer can't reference vertices that no longer exist once the new (possibly smaller) vertex array is assigned.

using UnityEngine;

[RequireComponent(typeof(MeshFilter), typeof(MeshRenderer))]
public class ProceduralGrid : MonoBehaviour
{
    [SerializeField] private int width = 10;
    [SerializeField] private int depth = 10;
    [SerializeField] private float cellSize = 1f;

    void Start()
    {
        Mesh mesh = new Mesh { name = "ProceduralGrid" };

        int vertsPerRow = width + 1;
        int vertsPerCol = depth + 1;
        var vertices = new Vector3[vertsPerRow * vertsPerCol];
        var uvs = new Vector2[vertices.Length];

        for (int z = 0; z < vertsPerCol; z++)
        {
            for (int x = 0; x < vertsPerRow; x++)
            {
                int i = z * vertsPerRow + x;
                vertices[i] = new Vector3(x * cellSize, 0f, z * cellSize);
                uvs[i] = new Vector2((float)x / width, (float)z / depth);
            }
        }

        var triangles = new int[width * depth * 6];
        int t = 0;
        for (int z = 0; z < depth; z++)
        {
            for (int x = 0; x < width; x++)
            {
                int a = z * vertsPerRow + x;
                int b = a + vertsPerRow;
                // Clockwise winding as seen from above (+Y) so the top face is front-facing.
                triangles[t++] = a;
                triangles[t++] = b + 1;
                triangles[t++] = b;
                triangles[t++] = a;
                triangles[t++] = a + 1;
                triangles[t++] = b + 1;
            }
        }

        // Order matters: vertices/UVs first, triangles last, so index validation always succeeds.
        mesh.vertices = vertices;
        mesh.uv = uvs;
        mesh.triangles = triangles;
        mesh.RecalculateNormals();
        mesh.RecalculateBounds();

        GetComponent<MeshFilter>().mesh = mesh; // .mesh instances a per-object copy, safe to own and later mutate
    }
}

Normals, Tangents, and Bounds Recalculation

Normals, tangents, and bounds are all derived data that Unity does not keep in sync automatically once you hand-edit vertex positions — every one of them requires an explicit recalculation call, and each has a different dependency chain. Mesh.RecalculateNormals() derives per-vertex normals from the triangle/vertex data; because normals are averaged across every triangle sharing a vertex, vertices that were deliberately duplicated at a UV seam or hard edge (so each triangle can have visually distinct normals there) get correctly sharp results, while unintentionally duplicated vertices produce faceted shading where smooth was expected (ScriptReference/Mesh.RecalculateNormals.html). Mesh.RecalculateTangents() must run after normals and UV0 are both present, since it derives the 4-component tangent (xyz direction + w sign for the binormal cross product) from vertex positions, normals, and texture coordinates together — skipping this on a mesh whose shader samples a normal map produces broken or flat-looking normal mapping even though normals themselves look correct (ScriptReference/Mesh.RecalculateTangents.html, Manual/mesh-vertex-data.html). Mesh.RecalculateBounds() recomputes the bounding volume used for frustum culling; assigning through the simple .triangles property triggers this automatically, but the advanced buffer API and Mesh.MeshData.SetSubMesh do not always recalculate mesh-level bounds, so an explicit call is required after buffer-API writes or the mesh may vanish prematurely under culling despite rendering correctly up close. Both RecalculateNormals and RecalculateTangents silently convert the mesh's vertex position (and normal/UV0, respectively) data to VertexAttributeFormat.Float32 if a different format was in use, which is a hidden cost worth knowing about if a mesh was deliberately built with a compressed (FP16) position or normal format via the advanced API.

void RebuildWithNormals(Mesh mesh, Vector3[] vertices, int[] triangles, Vector2[] uvs)
{
    mesh.Clear();
    mesh.vertices = vertices;
    mesh.uv = uvs;
    mesh.triangles = triangles;

    mesh.RecalculateNormals();   // from triangles + vertices
    mesh.RecalculateTangents();  // needs normals + UV0 already set
    mesh.RecalculateBounds();    // redundant here since .triangles already did it, but required after buffer-API writes
}

Submeshes & Multi-Material Meshes

A submesh is a slice of the shared index buffer rendered with one material; a Renderer with N materials needs exactly N submeshes on its mesh, matched by array order to the Renderer.materials array. Mesh.subMeshCount sets how many slices exist, and each slice's index range/topology is described by a SubMeshDescriptor (indexStart, indexCount, topology, baseVertex, plus an auto-computed bounds/firstVertex/vertexCount unless MeshUpdateFlags.DontRecalculateBounds is passed) set via Mesh.SetSubMesh (ScriptReference/Rendering.SubMeshDescriptor.html, ScriptReference/Mesh.SetSubMesh.html). The simple API's SetTriangles(triangles, submeshIndex) overload is the easiest path for a small, fixed number of materials — call it once per submesh index after the shared vertex array is assigned. Submesh index ranges must not overlap one another; the advanced API does not check this for you and an overlap produces undefined rendering rather than an exception.

void BuildTwoMaterialMesh(Mesh mesh, Vector3[] vertices, int[] groundTriangles, int[] roadTriangles)
{
    mesh.Clear();
    mesh.vertices = vertices;
    mesh.subMeshCount = 2;
    mesh.SetTriangles(groundTriangles, 0); // rendered with materials[0]
    mesh.SetTriangles(roadTriangles, 1);   // rendered with materials[1]
    mesh.RecalculateNormals();
    mesh.RecalculateBounds();
}

Advanced MeshData API for Performance

Mesh.MeshData/Mesh.MeshDataArray (in UnityEngine, backed by Unity.Collections.NativeArray) is a lower-level API purpose-built for writing mesh data from worker threads inside C# Jobs, with Burst compilation, instead of the managed-array simple API which only the main thread can touch. Mesh.AllocateWritableMeshData(meshCount) returns a MeshDataArray of writable MeshData structs; populate each one by calling SetVertexBufferParams with a VertexAttributeDescriptor[] layout (which attributes, their VertexAttributeFormat/dimension, and which of up to 4 interleaved streams each lives in), writing into the NativeArray<T> returned by GetVertexData<T>(), then SetIndexBufferParams + writing into GetIndexData<T>(), then setting subMeshCount and calling SetSubMesh per submesh (ScriptReference/Mesh.AllocateWritableMeshData.html). Finally, Mesh.ApplyAndDisposeWritableMeshData(dataArray, mesh) commits the data to real Mesh object(s) and disposes the array in one call — after this the MeshDataArray is invalid and must not be touched again. The mirror-image read path, Mesh.AcquireReadOnlyMeshData(mesh), snapshots an existing mesh's data for job-safe reading (zero-copy as long as the source mesh isn't modified while the snapshot is alive, and it must be disposed, ideally via a using block); it throws if Mesh.isReadable is false, whereas the Editor-only MeshUtility.AcquireReadOnlyMeshData skips that check. A parallel, main-thread-only "advanced" surface exists directly on Mesh (SetVertexBufferParams/SetVertexBufferData/SetIndexBufferParams/SetIndexBufferData/SetSubMesh) for cases that want raw-buffer performance without going through Jobs at all — same validation tradeoffs, no MeshData/allocation ceremony (ScriptReference/Mesh.SetVertexBufferParams.html). Every advanced-API call performs minimal validation by default; Rendering.MeshUpdateFlags (Default, DontValidateIndices, DontResetBoneBounds, DontNotifyMeshUsers, DontRecalculateBounds, DontValidateLodRanges) lets you selectively re-enable or suppress specific checks per call.

using UnityEngine;
using UnityEngine.Rendering;

[RequireComponent(typeof(MeshFilter))]
public class TetrahedronMeshData : MonoBehaviour
{
    void Start()
    {
        // Allocate mesh data for one mesh.
        var dataArray = Mesh.AllocateWritableMeshData(1);
        var data = dataArray[0];

        // 4 faces, 3 unique vertices per face (12 total) since normals differ per face.
        data.SetVertexBufferParams(12,
            new VertexAttributeDescriptor(VertexAttribute.Position),
            new VertexAttributeDescriptor(VertexAttribute.Normal, stream: 1));

        var sqrt075 = Mathf.Sqrt(0.75f);
        var p0 = new Vector3(0, 0, 0);
        var p1 = new Vector3(1, 0, 0);
        var p2 = new Vector3(0.5f, 0, sqrt075);
        var p3 = new Vector3(0.5f, sqrt075, sqrt075 / 3);

        var pos = data.GetVertexData<Vector3>();
        pos[0] = p0; pos[1] = p1; pos[2] = p2;
        pos[3] = p0; pos[4] = p2; pos[5] = p3;
        pos[6] = p2; pos[7] = p1; pos[8] = p3;
        pos[9] = p0; pos[10] = p3; pos[11] = p1;
        // Normals are left unset here and filled in later by RecalculateNormals.

        data.SetIndexBufferParams(12, IndexFormat.UInt16);
        var ib = data.GetIndexData<ushort>();
        for (ushort i = 0; i < ib.Length; ++i) ib[i] = i;

        data.subMeshCount = 1;
        data.SetSubMesh(0, new SubMeshDescriptor(0, ib.Length));

        var mesh = new Mesh { name = "Tetrahedron" };
        Mesh.ApplyAndDisposeWritableMeshData(dataArray, mesh); // dataArray is invalid after this call
        mesh.RecalculateNormals();
        mesh.RecalculateBounds();

        GetComponent<MeshFilter>().mesh = mesh;
    }
}

(Worked example per ScriptReference/Mesh.AllocateWritableMeshData.html.) The same struct family also underlies reading: wrap Mesh.AcquireReadOnlyMeshData in a using block, index into the returned MeshDataArray, and call data.GetVertices(destinationNativeArray) or the equivalent Get* accessor to pull data out for a Job without allocating a managed array copy.

Combining Meshes (CombineInstance)

Mesh.CombineMeshes merges several source meshes into one destination Mesh, which is a legitimate draw-call optimization for meshes that sit close together and never move relative to each other (a static cabinet made of many drawer meshes, for example) — each CombineInstance in the input array pairs a source mesh with a transform matrix, and one CombineInstance is required per submesh if a source mesh has more than one (Manual/combining-meshes.html, ScriptReference/CombineInstance.html). mergeSubMeshes = true flattens every instance into a single submesh (only valid when every instance shares one material and topology); mergeSubMeshes = false keeps each instance as its own submesh in the result, for combining meshes that still need distinct materials. useMatrices = true applies each instance's transform to the vertices during the combine so everything lands in a common space; source meshes must be CPU-readable (Mesh.isReadable == true) or Unity logs a warning and skips that instance entirely, silently producing an incomplete combined mesh. Note the explicit tradeoff versus the technique this replaces: Unity cannot cull parts of a combined mesh individually — if any part of the combined result is onscreen, all of it draws — so for scenes that need per-object culling, static batching is the better default and manual combining is reserved for cases where the combine itself removes enough draw calls to be worth that loss.

[RequireComponent(typeof(MeshFilter), typeof(MeshRenderer))]
public class CombineChildren : MonoBehaviour
{
    void Start()
    {
        MeshFilter[] meshFilters = GetComponentsInChildren<MeshFilter>();
        var instances = new CombineInstance[meshFilters.Length];

        for (int i = 0; i < meshFilters.Length; i++)
        {
            instances[i] = new CombineInstance
            {
                mesh = meshFilters[i].sharedMesh,
                transform = meshFilters[i].transform.localToWorldMatrix,
            };
            meshFilters[i].gameObject.SetActive(false);
        }

        var combinedMesh = new Mesh();
        combinedMesh.CombineMeshes(instances); // mergeSubMeshes defaults true, useMatrices defaults true
        GetComponent<MeshFilter>().sharedMesh = combinedMesh;
    }
}

Skinned & Blend-Shape Meshes

Deformable meshes carry two additional, optional categories of data beyond the base vertex/index buffers: bind poses (for skinned meshes) and blend shapes (for morph-target animation) (Manual/mesh-data-deformable-meshes.html). A skinned mesh's bindposes array stores, per bone, the inverse of that bone's transform at rest — one entry per bone, indexed to match SkinnedMeshRenderer.bones (ScriptReference/Mesh-bindposes.html). Per-vertex bone influence has two parallel APIs: the legacy Mesh.boneWeights property stores a fixed-size BoneWeight struct (exactly 4 bone/weight pairs) per vertex, while the modern BoneWeight1-based Mesh.SetBoneWeights/Mesh.GetAllBoneWeights/Mesh.GetBonesPerVertex trio supports a variable, larger count (up to 255) of weighted bones per vertex and is the preferred path for anything new — weights passed to SetBoneWeights must be sorted most-significant-first, and Unity stores them at reduced (currently ≥16-bit normalized) precision, so don't expect bit-exact round trips (ScriptReference/Mesh.SetBoneWeights.html). Blend shapes are added with Mesh.AddBlendShapeFrame(name, weight, deltaVertices, deltaNormals, deltaTangents): the delta arrays must be Mesh.vertexCount long (deltas, not absolute positions — subtract the base mesh's vertices/normals/tangents to compute them), frames for a multi-frame blend shape must be added in increasing weight order, and frames can only be appended to a brand-new shape or to the last shape already on the mesh, never inserted mid-sequence (ScriptReference/Mesh.AddBlendShapeFrame.html). Procedurally generating a fully rigged skinned mesh from scratch is rare; the far more common pattern is generating or modifying the base geometry (vertices/normals/tangents) procedurally while leaving bind poses and bone weights authored by an importer/DCC tool untouched, or driving existing blend shape weights at runtime via SkinnedMeshRenderer.SetBlendShapeWeight rather than authoring new frames in code.

Common Mistakes

Quick Reference

Advanced Notes

MeshData vs. the classic managed-array API. The classic simple API (SetVertices, .triangles, etc.) operates on ordinary managed C# arrays/lists, which means it can only be called from the main thread and always pays a managed-allocation and per-call validation cost. Mesh.MeshData/MeshDataArray wraps Unity.Collections.NativeArray<T> buffers instead, which are safe to read and write from worker threads inside IJob/IJobParallelFor implementations and are Burst-compilable — this is the intended path for generating large amounts of procedural geometry (terrain chunks, voxel meshes, particle-driven geometry) every frame without spiking the main thread or triggering GC. The tradeoff is ceremony and reduced safety: you must get vertex layout, index format, and submesh ranges correct yourself, since the advanced API performs minimal validation by default (ScriptReference/Mesh.html, "Simple vs Advanced Mesh API"). A reasonable rule of thumb: build correctness with the simple API first, and only move hot, per-frame, high-volume mesh generation to MeshData + Jobs after profiling shows the managed-array path is the actual bottleneck.

MarkDynamic for frequently-updated meshes. Calling Mesh.MarkDynamic() once, ideally before the first vertex/index upload, tells the underlying graphics API (Direct3D/Vulkan/Metal) to allocate the mesh's GPU buffers using a strategy suited for frequent CPU-side writes rather than the default strategy optimized for static, rarely-changing geometry. This meaningfully speeds up repeated SetVertices/SetVertexBufferData/UploadMeshData calls on the same mesh (e.g. a wave-animated water plane, cloth-like deformation, or a mesh driven every Update), at a small potential cost to raw rendering-read throughput — so it should be reserved for meshes that are actually updated every frame or close to it, not applied blanket to every procedurally-generated mesh regardless of how often it changes (ScriptReference/Mesh.MarkDynamic.html).

Mesh Collider cooking cost for procedural geometry. Attaching a MeshCollider to a procedurally generated or frequently regenerated mesh means Unity must "cook" that geometry into a physics-engine-friendly collision representation every time the source mesh changes meaningfully — this cooking step is a distinct, often non-trivial CPU cost on top of the mesh-generation work itself, and its cost is tunable via the Mesh Collider's Cooking Options (Manual/physics-optimization-cpu-mesh-cooking-options.html, Manual/prepare-mesh-for-mesh-collider.html). If a procedural mesh needs to double as a collider and is regenerated often (deforming terrain, runtime-carved geometry), budget for re-cooking cost separately from render-mesh generation cost, and consider whether a simpler proxy collider (primitive shapes, a lower-resolution convex hull) can stand in instead of cooking the full-detail render mesh every update. Full Rigi

…(truncated)