EditableMesh

Fixed-sized meshes allow changing the values of vertex attributes but do not allow vertices and faces to be added or deleted.

Adds a new bone to the mesh and returns a bone ID that persists across topology changes. An error is thrown if the bone name is already in use, the parent ID is invalid, or the mesh already contains the maximum number of bones.

Adds a new vertex color attribute to the mesh and returns a color ID.

Adds a new face from an array of vertex IDs and returns a stable face ID. A face is either a triangle (3 vertex IDs) or a quad (4 vertex IDs); any other count throws an error. For adding triangles specifically, it is preferable to use AddTriangle(), which is equivalent but slightly more performant as it avoids constructing an array for the vertices.

For rendering and collision, each quad is internally split into 2 triangles, so a quad counts as 2 triangles toward the mesh's triangle limit.

Automatic attribute assignment#

AddFace() only takes vertex IDs as arguments. For each vertex of the new face, it automatically assigns normal, UV, and color attributes using the following logic:

• If the vertex already belongs to another face, the new face corner reuses the same normal, UV, and color IDs from the existing face. This produces smooth shading and continuous UVs across adjacent faces by default.
• If the vertex does not yet belong to any face, new normal, UV, and color IDs are created with default values (auto-computed normal, UV coordinate of (0, 0), and white color).

Overriding attributes after adding a face#

The auto-assigned attributes can be customized after adding a face. The approach depends on whether you want to change attribute values while keeping the topology intact, or create entirely new attribute IDs to add or remove seams between faces.

To change values in-place, retrieve the auto-created IDs with methods like GetVertexFaceUV() and set their values directly. This is more performant and avoids leaving unused IDs in the mesh:

-- Create a triangle
local faceId = editableMesh:AddFace({v0, v1, v2})

-- Get the UV IDs that were automatically created
local uvId0 = editableMesh:GetVertexFaceUV(v0, faceId)
local uvId1 = editableMesh:GetVertexFaceUV(v1, faceId)
local uvId2 = editableMesh:GetVertexFaceUV(v2, faceId)

-- Set UV values on those existing UV IDs
editableMesh:SetUV(uvId0, Vector2.new(0, 0))
editableMesh:SetUV(uvId1, Vector2.new(1, 0))
editableMesh:SetUV(uvId2, Vector2.new(0, 1))

To create a seam — where the same vertex needs different attribute values on different faces (for example, a UV seam or a sharp edge) — create new attribute IDs with AddUV(), AddNormal(), or AddColor(), then assign them to the face with SetFaceUVs(), SetFaceNormals(), or SetFaceColors():

-- Create a triangle
local faceId = editableMesh:AddFace({v0, v1, v2})

-- Create new UV IDs with custom coordinates
local uv0 = editableMesh:AddUV(Vector2.new(0, 0))
local uv1 = editableMesh:AddUV(Vector2.new(1, 0))
local uv2 = editableMesh:AddUV(Vector2.new(0, 1))

-- Replace the face's UV IDs (creates a seam if the vertex had different UVs on another face)
editableMesh:SetFaceUVs(faceId, {uv0, uv1, uv2})

Normal sharing and smooth vs. sharp edges#

Because new faces reuse normal IDs from adjacent faces by default, meshes appear smooth. To create a sharp edge (crease) between faces, create a separate normal ID for each face and assign it with SetFaceNormals():

-- Two triangles sharing vertices v0 and v1, but with a sharp edge between them
local fid1 = editableMesh:AddFace({v0, v1, v2})
local fid2 = editableMesh:AddFace({v0, v3, v1})

-- Create separate normals for each face to produce a hard edge
local n1 = editableMesh:AddNormal() -- Auto-computed for fid1
local n2 = editableMesh:AddNormal() -- Auto-computed for fid2
editableMesh:SetFaceNormals(fid1, {n1, n1, n1})
editableMesh:SetFaceNormals(fid2, {n2, n2, n2})

See also SetNormal() to manually specify a normal vector, and ResetNormal() to revert a normal back to automatic computation.

Adds a new normal to the geometry and returns a normal ID. If the normal value isn't specified, the normal will be automatically calculated.

Adds a new triangle to the mesh and returns a stable face ID. This is equivalent to passing an array of 3 vertex IDs to AddFace(), but is slightly more performant as it avoids constructing an array for each call.

See AddFace() for information on how all faces are added, including those added by AddTriangle(). This includes details related to automatic attribute assignment, overriding attributes, and more.

Adds a new UV coordinate attribute to the mesh and returns a UV ID.

Adds a new vertex to the mesh and returns a vertex ID. The position is specified in the mesh's local object space. An error is thrown if the mesh already contains 60,000 vertices.

Creates new mesh elements of the given attribute type and returns their IDs in the same order as the input data. This method always requires an explicit MeshAttribute because its input is raw values with no existing IDs to inspect. Throws an error if the attribute type is invalid, the data format does not match, or adding the elements would exceed mesh limits.

local vIds = mesh:BatchAdd(Enum.MeshAttribute.Vertex, positions)     -- Positions: {Vector3}
local nIds = mesh:BatchAdd(Enum.MeshAttribute.Normal, normals)       -- Normals: {Vector3}
local uIds = mesh:BatchAdd(Enum.MeshAttribute.UV, uvs)               -- UVs: {Vector2}
local cIds = mesh:BatchAdd(Enum.MeshAttribute.Color, colors, alphas) -- Colors: {Color3}, Alphas: {number}
local fIds = mesh:BatchAdd(Enum.MeshAttribute.Face, {
    {vIds[1], vIds[2], vIds[3]},
    {vIds[1], vIds[3], vIds[4]},
})

Returns, for each face, the array of per-corner attribute IDs, one per corner in the same order as GetFaceVertices().

local faceNormals = mesh:BatchGetFaceAttributes(Enum.MeshAttribute.Normal, faceIds) -- {{normalId}}
local faceVerts = mesh:BatchGetFaceAttributes(Enum.MeshAttribute.Vertex, faceIds)   -- {{vertexId}}

Returns attribute values for the given IDs in the same order as the input. Passing an empty array returns an empty result.

local positions = mesh:BatchGetValues(vertexIds)     -- {Vector3}
local normals = mesh:BatchGetValues(normalIds)       -- {Vector3}
local uvs = mesh:BatchGetValues(uvIds)               -- {Vector2}
local colors, alphas = mesh:BatchGetValues(colorIds) -- {Color3}, {number}

Returns, for each vertex, the array of associated attribute IDs, gathered across all faces adjacent to that vertex. For example, using MeshAttribute.Face returns every face that references each vertex.

local adjFaces = mesh:BatchGetVertexAttributes(Enum.MeshAttribute.Face, vertexIds) -- {{faceId}}

Returns the attribute ID at each corner specified by a vertex–face pair.

local cornerColors = mesh:BatchGetVertexFaceAttributes(Enum.MeshAttribute.Color, vertexIds, faceIds)

Removes a batch of faces. As with RemoveFace(), the vertices and attributes used by the removed faces are not automatically deleted; call RemoveUnused() afterward to clean up unused elements.

mesh:BatchRemove(faceIds)

Sets the per-corner attribute IDs for each face.

-- Assign normal IDs to every corner of two faces
mesh:BatchSetFaceAttributes(faceIds, {
	{n1, n2, n3},
	{n4, n5, n6},
})

Writes attribute values to the given IDs. values[i] is written to ids[i]; the ids and values arrays must be the same length, unless values is nil to reset normals.

For color IDs, pass an array of Color3 to set the colors, or an array of numbers to set the alphas. Mixing types in one call is an error.

mesh:BatchSetValues(vertexIds, positions) -- Positions: {Vector3}
mesh:BatchSetValues(normalIds, normals)   -- Normals: {Vector3}
mesh:BatchSetValues(uvIds, uvs)           -- UVs: {Vector2}
mesh:BatchSetValues(colorIds, colors)     -- Colors: {Color3}
mesh:BatchSetValues(colorIds, alphas)     -- Alphas: {number}
mesh:BatchSetValues(normalIds, nil)       -- Resets each normal to auto-computed

Sets the attribute at a specific corner — identified by a vertex–face pair — for each element in the batch. For each index i, the attribute at corner (vertexIds[i], faceIds[i]) is set to attrIds[i].

mesh:BatchSetVertexFaceAttributes(vertexIds, faceIds, colorIds)

Removes all vertex data (including positions, normals, UV coordinates, and colors), faces, bones, and FACS data without destroying the EditableMesh or its allocated space.

This method cannot be called on a fixed-size mesh (where FixedSize is true). Attempting to do so throws an error because fixed-size meshes do not allow adding or removing elements.

Destroys the contents of the mesh, immediately reclaiming used memory.

Finds the closest point on the mesh's surface. Returns the face ID, point on the mesh in local object space, the barycentric coordinates of the position within the face, and the 3 vertex IDs that the barycentric coordinates correspond to. See RaycastLocal() for more information on barycentric coordinates, including how they apply to quad faces. When the mesh is skinned, this query operates against the bind-pose geometry, not the deformed mesh as it appears at runtime.

Finds the closest vertex to a specific point in space and returns a vertex ID. When the mesh is skinned, this query operates against the bind-pose geometry, not the deformed mesh as it appears at runtime.

Finds all vertices within a specific sphere and returns a list of vertex IDs. When the mesh is skinned, this query operates against the bind-pose geometry, not the deformed mesh as it appears at runtime.

Given a face ID, returns a list of adjacent faces.

Given a vertex ID, returns a list of adjacent vertices.

Finds the bone ID of the bone with the given name. Errors if no bone with that name exists.

Returns the initial CFrame of the bone in the bind pose of the mesh, in the mesh's local space.

Returns true if the bone is virtual. Virtual bones can only be bound to a FaceControls instance.

Returns the name string of the bone identified by the given bone ID. Bone names are unique within the mesh and can be up to 100 characters long.

Returns the bone ID of the parent bone in the bone hierarchy. If the bone has no parent, returns 0.

Returns all bones of the mesh as a list of bone IDs.

Returns the center of the mesh's axis-aligned bounding box, in the mesh's local object space.

Returns the Color3 value stored at the given color ID. Use GetColorAlpha() to retrieve the alpha component separately.

Returns the alpha component of the vertex color at the given color ID as a number between 0 (fully transparent) and 1 (fully opaque). Use GetColor() to retrieve the RGB component.

Returns all colors of the mesh as a list of color IDs.

Returns an array of color IDs, one per vertex corner of the specified face, in the same order as GetFaceVertices(). Use these IDs with GetColor() and GetColorAlpha() to read the actual color values.

Returns an array of normal IDs, one per vertex corner of the specified face, in the same order as GetFaceVertices(). Use these IDs with GetNormal() to read the actual normal vectors.

Returns all faces of the mesh as a list of face IDs.

Returns a list of faces that use a given vertex ID, normal ID, UV ID, or color ID.

Returns an array of face IDs that use the given color ID. Use together with GetVerticesWithColor() to obtain all face/vertex pairs.

Returns an array of face IDs that use the given normal ID. Use together with GetVerticesWithNormal() to obtain all face/vertex pairs.

Returns an array of face IDs that use the given UV ID. Use together with GetVerticesWithUV() to obtain all face/vertex pairs.

Returns an array of UV IDs, one per vertex corner of the specified face, in the same order as GetFaceVertices(). Use these IDs with GetUV() to read the actual UV coordinates.

Returns an array of vertex IDs that define the corners of the given face, in the same order used when the face was created.

Returns bone IDs and bone CFrames for all bones in a specific FACS corrective pose. Each bone CFrame transforms the bone from the initial bone CFrame in the bind pose of the mesh to the combined bone CFrame for this pose. All CFrames are in the mesh's local space.

Returns all FACS corrective poses that are in use. Each corrective pose is specified by 2 or 3 FacsActionUnit values.

Returns bone IDs and bone CFrames for all bones in a specific FACS action unit. Each bone CFrame transforms the bone from the initial bone CFrame in the bind pose of the mesh to the combined bone CFrame for this pose. All CFrames are in the mesh's local space.

Returns an array of FacsActionUnit values representing all base FACS poses currently defined on this mesh. Use each returned value with GetFacsPose() to retrieve the bone transforms for that pose. See also GetFacsCorrectivePoses() for corrective poses.

Returns the Vector3 normal vector at the given normal ID. If the normal vector was manually specified it will return that vector. If the normal vector was not specified or was reset, this will return an automatically calculated normal vector based on the shape of the mesh.

Returns all normals of the mesh as a list of normal IDs.

Gets the position of a vertex in the mesh's local object space.

Returns the size of the mesh's axis-aligned bounding box, in the mesh's local object space.

Returns the Vector2 texture coordinate stored at the given UV ID. UV coordinates map the mesh surface to a 2D texture.

Returns all UVs of the mesh as a list of UV IDs.

Returns an array of bone IDs that influence the given vertex during skinning deformation. A vertex can be influenced by up to 4 bones. The returned array corresponds index-by-index with the weights returned by GetVertexBoneWeights() for the same vertex.

Returns an array of blend weights (each between 0 and 1) for the bones influencing this vertex during skeletal deformation. The returned array corresponds index-by-index with the bone IDs returned by GetVertexBones() for the same vertex.

Returns an array of color IDs used on all face corners that reference the given vertex. A vertex shared by multiple faces can have different color IDs on each face (a color seam); this method returns all of them.

Returns the color ID assigned to a specific corner of a face, identified by the vertex/face pair. This is useful when a vertex is shared by multiple faces and you need the color for one particular face corner rather than all of them.

Returns the normal ID assigned to a specific corner of a face, identified by the vertex/face pair. This is useful when a vertex has split normals (a sharp edge) and you need the normal for one particular face corner rather than all of them.

Returns an array of face IDs for all faces that have the given vertex as one of their corners. Use this to traverse the mesh topology around a vertex, for example to find all faces affected by moving a vertex.

Returns the UV ID assigned to a specific corner of a face, identified by the vertex/face pair. This is useful when a vertex has a UV seam and you need the UV for one particular face corner rather than all of them.

Returns an array of normal IDs used on all face corners that reference the given vertex. A vertex shared by multiple faces can have different normal IDs on each face (a hard/sharp edge); this method returns all of them.

Returns an array of UV IDs used on all face corners that reference the given vertex. A vertex shared by multiple faces can have different UV IDs on each face (a UV seam); this method returns all of them.

Returns all vertex IDs in the mesh as a list of IDs. The IDs may not be contiguous. Use this list to iterate over vertices safely, rather than assuming consecutive numbering.

Returns a list of vertices that use a given face ID, normal ID, UV ID, or color ID.

Returns an array of vertex IDs that use the given color ID. Use together with GetFacesWithColor() to obtain all face/vertex pairs.

Returns an array of vertex IDs that use the given normal ID. Use together with GetFacesWithNormal() to obtain all face/vertex pairs.

Returns an array of vertex IDs that use the given UV ID. Use together with GetFacesWithUV() to obtain all face/vertex pairs.

Returns a string describing an ID, useful for debugging purposes, like f17 or v12, containing the type, ID number, and version.

Merges vertices that touch together, to use a single vertex ID but keep the other original attribute IDs.

Casts a ray and returns the face ID, point of intersection, barycentric coordinates, and the 3 vertex IDs that the barycentric coordinates correspond to. The inputs and outputs of this method are in the mesh's local object space. When the mesh is skinned, this raycast operates against the bind-pose geometry, not the deformed mesh as it appears at runtime.

A barycentric coordinate is a way of specifying a point within a triangle as a weighted combination of the triangle's 3 vertices. This is useful as a general way of blending vertex attributes. See this method's code sample as an illustration.

Because a barycentric coordinate is defined over exactly 3 vertices, when the hit face is a quad, the coordinate and the returned vertex IDs refer to 3 of the quad's 4 vertices forming the corners of the sub-triangle that was hit. Use the returned vertex IDs, rather than the face's full vertex list, to identify which vertices the weights apply to.

Removes a bone from the mesh using its bone ID. Any vertex skinning weights that referenced the removed bone are also cleared.

Removes a face from the mesh using its face ID. The vertices and attributes that were used by the face are not automatically deleted; call RemoveUnused() afterward if you want to clean up unused vertices and attributes.

Removes all vertices, normals, UVs, and colors which are not used in any face, and returns the removed IDs.

Reset this normal ID to be automatically calculated based on the shape of the mesh, instead of manually set.

Set the initial CFrame for a bone in the mesh's bind pose, in the mesh's local space.

Set whether a bone is virtual. Virtual bones can only be bound to a FaceControls instance.

Sets the name for a bone. Bone names can be 100 characters long and must be unique in the mesh.

Sets the parent of a bone in the bone hierarchy. Pass a valid bone ID to parent the bone, or 0 to make it a root bone. The engine validates that the new parent does not create a cycle in the bone hierarchy and throws an error if the parent ID is invalid or would produce a circular dependency.

Sets the Color3 value for a color ID. This changes the vertex color for every face corner that references this color ID. Use SetColorAlpha() to change the alpha component separately.

Sets the alpha (transparency) component of the vertex color at the given color ID. The value is a number between 0 (fully transparent) and 1 (fully opaque). This changes the alpha for every face corner that references this color ID.

Assigns new color IDs to the corners of a face, replacing whatever color IDs were previously set. The array must contain one color ID per vertex of the face, in the same winding order as GetFaceVertices(). Use this to create a color seam at a vertex shared by multiple faces.

Assigns new normal IDs to the corners of a face, replacing whatever normal IDs were previously set. The array must contain one normal ID per vertex of the face, in the same winding order as GetFaceVertices(). Use this to create a hard/sharp edge by giving adjacent faces different normals at the same vertex.

Assigns new UV IDs to the corners of a face, replacing whatever UV IDs were previously set. The array must contain one UV ID per vertex of the face, in the same winding order as GetFaceVertices(). Use this to create a UV seam at a vertex shared by multiple faces.

Replaces the vertex IDs at each corner of the given face, in winding order. Passing 3 vertex IDs makes the face a triangle and 4 makes it a quad, so this can convert a face between a triangle and a quad while keeping the same face ID.

The normal, UV, and color attributes on each of the existing corners are preserved. If a new corner is added, it follows the same automatic attribute assignment described in AddFace().

Sets the CFrame for a single bone within a specific FACS action unit pose, without modifying the other bones in that pose. The bone must be virtual. The CFrame transforms the bone from its initial bind-pose position to the target pose position, in the mesh's local space. Use this for incremental edits to a FACS pose; use SetFacsPose() to set all bones in a pose at once.

Sets all bone transforms for a FACS corrective pose, which overrides the blended result of 2 or 3 base poses when they are active simultaneously. The actions array must contain exactly 2 or 3 FacsActionUnit values that identify the combination. All referenced bones must be virtual. The boneIds and cframes arrays must be the same length; each CFrame transforms the bone from the bind pose to the corrective target, in the mesh's local space. Throws if the action combination is not a valid corrective.

Sets all bone transforms for a FACS base pose (a single action unit). The boneIds and cframes arrays must be the same length; each CFrame transforms the bone from the bind pose to the target pose, in the mesh's local space. All referenced bones must be virtual (non-virtual bones throw an error). This replaces any previously defined pose for the given action unit.

Set the normal for a normal ID. This will change the normal value for every face vertex which is using the normal ID.

Sets a vertex position in the mesh's local object space. Please note that collision and other physics data on linked MeshParts is not updated until you call AssetService:CreateMeshPartAsync() and MeshPart:ApplyMesh().

Sets the Vector2 texture coordinate for a UV ID. This changes the UV mapping for every face corner that references this UV ID.

Assign a list of bones with the vertex for skinning.

Corresponds with the skinning blend weights used in SetVertexBoneWeights(). In other words, GetVertexBoneWeights(vertexId)[i] is the weight on this vertex for GetVertexBones(vertexId)[i].

This method should be called before calling SetVertexBoneWeights().

Sets skinning blend weights for each bone associated with the vertex.

Corresponds with the bone IDs used in SetVertexBones(). In other words, GetVertexBoneWeights(vertexId)[i] is the weight on this vertex for GetVertexBones(vertexId)[i].

This method should be called after calling SetVertexBones().

Sets the color ID for a specific corner of a face, identified by the vertex/face pair. This is equivalent to changing just one element of the array set by SetFaceColors(), and is useful for creating or removing a color seam at a single vertex without affecting the other corners of the face.

Sets the normal ID for a specific corner of a face, identified by the vertex/face pair. This is equivalent to changing just one element of the array set by SetFaceNormals(), and is useful for creating or removing a hard edge at a single vertex without affecting the other corners of the face.

Sets the UV ID for a specific corner of a face, identified by the vertex/face pair. This is equivalent to changing just one element of the array set by SetFaceUVs(), and is useful for creating or removing a UV seam at a single vertex without affecting the other corners of the face.

Splits every quad face on the mesh into two triangle faces each. A heuristic is used to determine which diagonal each quad should be split along to produce better-shaped triangles. If your code relies on faces being triangles, call this method after AssetService:CreateEditableMeshAsync(), which may produce quad faces.