55 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

EditableMesh

Inherits from: Object

EditableMesh changes the applied visual mesh when linked to a MeshPart, allowing for querying and modification of the mesh both in Studio and in-game.

Enabling for published games

For security purposes, using EditableMesh fails by default for published games. To enable usage of EditableMesh, you must be 13+ age verified and ID verified. After you are verified, open the Creator Dashboard and toggle on Enable Mesh / Image APIs. Remember to review the Terms of Use before enabling the toggle.

Permissions

To prevent misuse, AssetService:CreateEditableMeshAsync() only allows you to load and edit mesh assets if any of the following is true:

• Owned by or explicitly shared with the game owner.
• Owned by or explicitly shared with the logged in Studio user.
• Owned by or explicitly shared with the logged in player if the EditableMesh is on the client side.
• Owned by a group where the game owner, Studio user, or player has a role with permission to edit the group's assets. See Roles and permissions for more information.

See Grant permissions to learn how to share assets with users or groups.

The APIs throw an error if they are used to load an asset that does not meet the criteria above.

Memory limits

Editable assets are currently expensive for memory usage. To minimize its impact on client performance, EditableMesh has strict client-side memory budgets, although the server, Studio, and plugins operate with unlimited memory. Using FixedSize may help you stay within the memory budget and, in some scenarios, linking one EditableMesh to multiple MeshParts (multi-referencing) can help with memory optimization.

Creation and display

An EditableMesh can be created from an existing Content of a MeshPart or a mesh ID using AssetService:CreateEditableMeshAsync(), or a blank EditableMesh can be created with AssetService:CreateEditableMesh(). It can then be displayed, modified, and its collision model updated. Not all of the steps are necessary; for example, you might want to create an EditableMesh just to raycast without ever displaying it.

local AssetService = game:GetService("AssetService")

-- Create empty EditableMesh
local editableMesh = AssetService:CreateEditableMesh()

-- Create EditableMesh from asset ID
local editableMeshFromAsset = nil
local success, errorMessage = pcall(function()
	editableMeshFromAsset = AssetService:CreateEditableMeshAsync(Content.fromAssetId(ASSET_ID))
end)

-- Create EditableMesh from another EditableMesh
local editableMeshFromAnother = nil
local success, errorMessage = pcall(function()
	editableMeshFromAnother = AssetService:CreateEditableMeshAsync(Content.fromObject(OTHER_EDITABLE_MESH))
end)

-- Create EditableMesh from MeshPart
local editableMeshFromMeshPart = nil
local success, errorMessage = pcall(function()
	editableMeshFromMeshPart = AssetService:CreateEditableMeshAsync(MESH_PART.MeshContent)
end)

An EditableMesh is displayed when it's linked to a new MeshPart, through AssetService:CreateMeshPartAsync(). You can create more MeshPart instances that reference the same EditableMesh Content, or link to an existing MeshPart through MeshPart:ApplyMesh().

local AssetService = game:GetService("AssetService")
local Workspace = game:GetService("Workspace")

-- Create EditableMesh from asset ID
local editableMeshFromAsset = nil
local success, errorMessage = pcall(function()
	editableMeshFromAsset = AssetService:CreateEditableMeshAsync(Content.fromAssetId(ASSET_ID))
end)

-- Create new MeshPart linked to the EditableMesh
local newMeshPart = nil
local success, errorMessage = pcall(function()
	newMeshPart = AssetService:CreateMeshPartAsync(Content.fromObject(editableMeshFromAsset))
end)

-- Alternatively, link the new MeshPart created above to an existing MeshPart
local existingMeshPart = Workspace:FindFirstChild("EXISTING_MESH_PART")
existingMeshPart:ApplyMesh(newMeshPart)

To recalculate collision and fluid geometry after editing, you can again call AssetService:CreateMeshPartAsync() and MeshPart:ApplyMesh() to update an existing MeshPart. It's generally recommended to do this at the end of a conceptual edit, not after individual calls to methods that manipulate geometry. Visual changes to the mesh will always be immediately reflected by the engine, without the need to call AssetService:CreateMeshPartAsync().

Fixed-size meshes

When creating an EditableMesh from an existing mesh asset (via AssetService:CreateEditableMeshAsync()), the resulting editable mesh is fixed-size by default. Fixed-size meshes are more efficient in terms of memory but you cannot change the number of vertices, faces, or attributes. Only the values of vertex attributes and positions can be edited.

local AssetService = game:GetService("AssetService")

-- Create EditableMesh without fixed-size default
local editableMeshFromAsset = nil
local success, errorMessage = pcall(function()
	editableMeshFromAsset = AssetService:CreateEditableMeshAsync(Content.fromAssetId(ASSET_ID), {FixedSize = false})
end)

Stable IDs

Many EditableMesh methods take vertex, normal, UV, color and face IDs. These are represented as integers in Luau but they require some special handling. The main difference is that IDs are stable and they remain the same even if other parts of the mesh change. For example, if an EditableMesh has five vertices {1, 2, 3, 4, 5} and you remove vertex 4, the new vertices will be {1, 2, 3, 5}.

Note that the IDs are not guaranteed to be in order and there may be holes in the numbering, so when iterating through vertices or faces, you should iterate through the table returned by GetVertices() or GetFaces().

For debugging purposes, it can be very helpful to get a more readable string for a stable ID with IdDebugString().

Split vertex attributes

A vertex is a corner of a face, and topologically connects faces together. Each vertex has a single position, while its normal, UV coordinate, and color (with transparency) are stored per face corner. A vertex shared by multiple faces can use the same values on every face, or different values on each.

Sometimes it's useful for all faces that touch a vertex to use the same attribute values, but sometimes you'll want different faces to use different attribute values on the same vertex. For example, on a smooth sphere, each vertex will only have a single normal. In contrast, at the corner of a cube, the vertex will have 3 different normals (one for each adjacent face). You can also have seams in the UV coordinates or sharp changes in the vertex colors.

When creating faces with AddFace() or AddTriangle(), each corner of the new face is automatically assigned a normal, UV, and color attribute. If a vertex already belongs to an existing face, the new face reuses that vertex's existing attributes (producing smooth shading and continuous UVs). If the vertex is new, fresh attribute IDs are created with default values (auto-computed normal, UV of (0, 0), white color). To create a seam, you should create new attributes and set them on the face. For example, this code will create a sharp cube:

local AssetService = game:GetService("AssetService")

-- Given 4 vertex IDs, adds a new normal and a quad face, making a sharp quad
local function addSharpQuad(editableMesh, vid0, vid1, vid2, vid3)
	local nid = editableMesh:AddNormal() -- This creates a normal ID which is automatically computed

	local fid = editableMesh:AddFace({vid0, vid1, vid2, vid3})
	editableMesh:SetFaceNormals(fid, {nid, nid, nid, nid})
end

-- Makes a cube with creased edges between the 6 sides
local function makeSharpCube()
	local editableMesh = AssetService:CreateEditableMesh()

	local v1 = editableMesh:AddVertex(Vector3.new(0, 0, 0))
	local v2 = editableMesh:AddVertex(Vector3.new(1, 0, 0))
	local v3 = editableMesh:AddVertex(Vector3.new(0, 1, 0))
	local v4 = editableMesh:AddVertex(Vector3.new(1, 1, 0))
	local v5 = editableMesh:AddVertex(Vector3.new(0, 0, 1))
	local v6 = editableMesh:AddVertex(Vector3.new(1, 0, 1))
	local v7 = editableMesh:AddVertex(Vector3.new(0, 1, 1))
	local v8 = editableMesh:AddVertex(Vector3.new(1, 1, 1))

	addSharpQuad(editableMesh, v5, v6, v8, v7) -- Front
	addSharpQuad(editableMesh, v1, v3, v4, v2) -- Back
	addSharpQuad(editableMesh, v1, v5, v7, v3) -- Left
	addSharpQuad(editableMesh, v2, v4, v8, v6) -- Right
	addSharpQuad(editableMesh, v1, v2, v6, v5) -- Bottom
	addSharpQuad(editableMesh, v3, v7, v8, v4) -- Top

	editableMesh:RemoveUnused()
	return editableMesh
end

Winding

Mesh faces have a front side and a back side. When drawing meshes, only the front of the faces are drawn by default, although you can change this by setting the mesh' DoubleSided property to true.

The order of the vertices around the face determines whether you are looking at the front or the back. The front of the face is visible when the vertices go counterclockwise around it.

FACS poses

Animatable heads use the Facial Action Coding System (FACS). See the FACS poses reference for helpful information when using GetFacsPoses() and similar methods.

Each FACS pose is specified by an FacsActionUnit value. For the FACS pose, virtual bones can each have a CFrame that transforms the bones' initial CFrame in the bind pose of the mesh into the CFrame for that FACS action unit's pose. All bone CFrames are in the mesh's local space.

These FACS poses are blended together during animation. Sometimes, the blending of the base poses produces poor results. In those cases, you can override the blending of specific combinations of base poses with a corrective pose that is more pleasing. A corrective pose is specified by 2 or 3 FacsActionUnit values. Like a base FACS pose, for a corrective pose, virtual bones can each have a CFrame that transforms the bones' initial CFrame in the bind pose of the mesh into the CFrame for that FACS corrective.

Please note that corrective poses that operate on both left and right action units are not currently expressible. For example, using LeftCheekPuff and RightEyeClosed together in a corrective pose is not currently possible.

Batching

The batch methods let you create, read, update, and remove many mesh elements in a single call instead of invoking the singular methods (AddVertex(), SetPosition(), GetColor(), and so on) once per element. Batching your mesh operations is typically much more performant than handling them one by one.

Rather than one method per attribute, each batch method shares a small set of general entry points and uses an MeshAttribute value (or the type already encoded in each mesh ID) to determine which attribute you mean. For example, BatchSetValues() sets positions when called with vertex IDs, but sets normals when called with normal IDs. You cannot mix-and-match ID types within a single call.

Batch setters take parallel arrays: element i of every argument array describes the same logical operation. In BatchSetValues(ids, values), values[i] is written to ids[i]. All argument arrays must be the same length or the call errors. Batch getters take an array of IDs and return results in the same order.

If a mesh ID is invalid, batching still applies updates to all elements before the invalid ID, then stops.

Limitations

EditableMesh currently has a limit of 60,000 vertices and 20,000 triangles. Faces can be triangles or quads, and each quad counts as 2 triangles toward the triangle limit. Attempting to add too many vertices or triangles will cause an error.

Inherits from: Object

Memory category: Instances

Tags: NotCreatable

Properties

Inherited from Object

EditableMesh.FixedSize

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

Methods

Inherited from Object

EditableMesh:AddBone

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.

Parameters

Returns

EditableMesh:AddColor

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

Parameters

Returns

EditableMesh:AddFace

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.

Parameters

Returns

EditableMesh:AddNormal

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.

Parameters

Returns

EditableMesh:AddTriangle

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.

Parameters

Returns

EditableMesh:AddUV

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

Parameters

Returns

EditableMesh:AddVertex

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.

Parameters

Returns

EditableMesh:BatchAdd

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]},
})

Parameters

Returns

EditableMesh:BatchGetFaceAttributes

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}}

Parameters

Returns

EditableMesh:BatchGetValues

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}

Parameters

Returns

EditableMesh:BatchGetVertexAttributes

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}}

Parameters

Returns

EditableMesh:BatchGetVertexFaceAttributes

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

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

Parameters

Returns

EditableMesh:BatchRemove

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)

Parameters

Returns

EditableMesh:BatchSetFaceAttributes

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},
})

Parameters

Returns

EditableMesh:BatchSetValues

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

Parameters

Returns

EditableMesh:BatchSetVertexFaceAttributes

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)

Parameters

Returns

EditableMesh:Clear

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.

Returns

EditableMesh:Destroy

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

Returns

EditableMesh:FindClosestPointOnSurface

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.

Parameters

Returns

EditableMesh:FindClosestVertex

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.

Parameters

Returns

EditableMesh:FindVerticesWithinSphere

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.

Parameters

Returns

EditableMesh:GetAdjacentFaces

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

Parameters

Returns

EditableMesh:GetAdjacentVertices

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

Parameters

Returns

EditableMesh:GetBoneByName

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

Parameters

Returns

EditableMesh:GetBoneCFrame

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

Parameters

Returns

EditableMesh:GetBoneIsVirtual

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

Parameters

Returns

EditableMesh:GetBoneName

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.

Parameters

Returns

EditableMesh:GetBoneParent

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

Parameters

Returns

EditableMesh:GetBones

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

Returns

EditableMesh:GetCenter

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

Returns

EditableMesh:GetColor

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

Parameters

Returns

EditableMesh:GetColorAlpha

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.

Parameters

Returns

EditableMesh:GetColors

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

Returns

EditableMesh:GetFaceColors

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.

Parameters

Returns

EditableMesh:GetFaceNormals

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.

Parameters

Returns

EditableMesh:GetFaces

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

Returns

EditableMesh:GetFacesWithAttribute

Deprecated. This method is deprecated. Do not use it for new work.

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

Parameters

Returns

EditableMesh:GetFacesWithColor

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

Parameters

Returns

EditableMesh:GetFacesWithNormal

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

Parameters

Returns

EditableMesh:GetFacesWithUV

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

Parameters

Returns

EditableMesh:GetFaceUVs

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.

Parameters

Returns

EditableMesh:GetFaceVertices

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

Parameters

Returns

EditableMesh:GetFacsCorrectivePose

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.

Parameters

Returns

EditableMesh:GetFacsCorrectivePoses

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

Returns

EditableMesh:GetFacsPose

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.

Parameters

Returns

EditableMesh:GetFacsPoses

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

EditableMesh:GetNormal

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.

Parameters

Returns

EditableMesh:GetNormals

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

Returns

EditableMesh:GetPosition

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

Parameters

Returns

EditableMesh:GetSize

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

Returns

EditableMesh:GetUV

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

Parameters

Returns

EditableMesh:GetUVs

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

Returns

EditableMesh:GetVertexBones

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.

Parameters

Returns

EditableMesh:GetVertexBoneWeights

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.

Parameters

Returns

EditableMesh:GetVertexColors

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.

Parameters

Returns

EditableMesh:GetVertexFaceColor

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.

Parameters

Returns

EditableMesh:GetVertexFaceNormal

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.

Parameters

Returns

EditableMesh:GetVertexFaces

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.

Parameters

Returns

EditableMesh:GetVertexFaceUV

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.

Parameters

Returns

EditableMesh:GetVertexNormals

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.

Parameters

Returns

EditableMesh:GetVertexUVs

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.

Parameters

Returns

EditableMesh:GetVertices

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

EditableMesh:GetVerticesWithAttribute

Deprecated. This method is deprecated. Do not use it for new work.

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

Parameters

Returns

EditableMesh:GetVerticesWithColor

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

Parameters

Returns

EditableMesh:GetVerticesWithNormal

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

Parameters

Returns

EditableMesh:GetVerticesWithUV

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

Parameters

Returns

EditableMesh:IdDebugString

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

Parameters

Returns

EditableMesh:MergeVertices

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

Parameters

Returns

EditableMesh:RaycastLocal

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.

Parameters

Returns

Code samples: View on Creator Hub (EditableMesh-RaycastLocal).

EditableMesh:RemoveBone

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

Parameters

Returns

EditableMesh:RemoveFace

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.

Parameters

Returns

EditableMesh:RemoveUnused

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

Returns

EditableMesh:ResetNormal

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

Parameters

Returns

EditableMesh:SetBoneCFrame

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

Parameters

Returns

EditableMesh:SetBoneIsVirtual

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

Parameters

Returns

EditableMesh:SetBoneName

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

Parameters

Returns

EditableMesh:SetBoneParent

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.

Parameters

Returns

EditableMesh:SetColor

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.

Parameters

Returns

EditableMesh:SetColorAlpha

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.

Parameters

Returns

EditableMesh:SetFaceColors

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.

Parameters

Returns

EditableMesh:SetFaceNormals

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.

Parameters

Returns

EditableMesh:SetFaceUVs

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.

Parameters

Returns

EditableMesh:SetFaceVertices

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().

Parameters

Returns

EditableMesh:SetFacsBonePose

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.

Parameters

Returns

EditableMesh:SetFacsCorrectivePose

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.

Parameters

Returns

EditableMesh:SetFacsPose

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.

Parameters

Returns

EditableMesh:SetNormal

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

Parameters

Returns

EditableMesh:SetPosition

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().

Parameters

Returns

EditableMesh:SetUV

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

Parameters

Returns

EditableMesh:SetVertexBones

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().

Parameters

Returns

EditableMesh: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().

Parameters

Returns

EditableMesh:SetVertexFaceColor

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.

Parameters

Returns

EditableMesh:SetVertexFaceNormal

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.

Parameters

Returns

EditableMesh:SetVertexFaceUV

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.

Parameters

Returns

EditableMesh:Triangulate

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.

Returns

Events

Inherited from Object