EditableMesh
EditableMesh changes the applied visual mesh when linked to a MeshPart, allowing for querying and modification of the mesh both in Studio and in experience.
Enabling for Published Experiences
For security purposes, using EditableMesh fails by default for published experiences. To enable usage of EditableMesh, you must be 13+ age verified and ID verified. After you are verified, open Studio's Game Settings, select Security, and enable the Allow Mesh & Image APIs toggle. Remember to review the Terms of Use before enabling the toggle.
Permissions
To prevent misuse, AssetService:CreateEditableMeshAsync() will only allow you to load and edit mesh assets:
- That are owned by the creator of the experience (if the experience is owned by an individual).
- That are owned by a group (if the experience is owned by the group).
- That are owned by the logged in Studio user (if the place file has not yet been saved or published to Roblox).
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 Vertex/Face 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().
Split Vertex Attributes
A vertex is a corner of a face, and topologically connects faces together. Vertices can have several attributes: position, normal, UV coordinate, color, and transparency.
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, every vertex will by default have one of each attribute: one normal, one UV coordinate, and one color/transparency. If you want 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 2 triangles, 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 fid1 = editableMesh:AddTriangle(vid0, vid1, vid2)
editableMesh:SetFaceNormals(fid1, {nid, nid, nid})
local fid2 = editableMesh:AddTriangle(vid0, vid2, vid3)
editableMesh:SetFaceNormals(fid2, {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 Enum.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 Enum.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.
Limitations
EditableMesh currently has a limit of 60,000 vertices and 20,000 triangles. Attempting to add too many vertices or triangles will cause an error.
Summary
Methods
Adds a new bone and returns a stable bone ID.
Adds a new color to the geometry and returns a stable color ID.
Adds a new normal to the geometry and returns a stable normal ID.
Adds a new triangle to the mesh and returns a stable face ID.
Adds a new UV to the geometry and returns a stable UV ID.
Adds a new vertex to the geometry and returns a stable vertex ID.
Destroys the mesh.
Finds the closest point on the mesh's surface.
Finds the closest vertex to a specific point in space.
Finds all vertices within a specific sphere.
Returns a list of faces adjacent to a given face.
Returns a list of vertices adjacent to a given vertex.
Finds the bone ID of the bone with the given name.
Returns the initial CFrame of the bone in the bind pose of the mesh.
Returns true if the bone is virtual.
Returns the bone name.
Returns the parent bone ID, if any.
Returns all bones of the mesh.
Returns the color for the given color ID.
Returns the color alpha (transparency) at the given color ID.
Returns all colors of the mesh.
Returns the face's color IDs for the vertices on the face.
Returns the face's normal IDs for the vertices on the face.
Returns the face's UV IDs for the vertices on the face.
Returns the face's vertex IDs.
Returns all faces of the mesh.
Returns bone IDs and bone CFrames for all bones in a specific FACS corrective pose.
Returns all FACS corrective poses that are in use.
Returns bone IDs and bone CFrames for all bones in a specific FACS action unit.
Returns all FACS action units that have poses defined.
Returns the normal vector for the given normal ID.
Returns all normals of the mesh.
Gets the position of a vertex.
Returns UV coordinates at the given UV ID.
Returns all UVs of the mesh.
Returns skinning blend weights for each bone that is associated with the vertex.
Returns all bone IDs that are associated with the vertex for skinning.
Returns all vertices as a list of stable vertex IDs.
Returns a string describing a stable ID, useful for debugging purposes.
Merges vertices that touch together.
Removes a bone using its stable bone ID.
Removes a face using its stable face ID.
Removes all unused vertices, normals, UVs, and colors, and returns the removed IDs.
Reset this normal ID to be automatically calculated.
Set the initial CFrame for a bone in the mesh's bind pose.
Set whether a bone is virtual.
Sets the name for a bone.
Set a parent for a bone.
Sets the color for a color ID.
Sets the color alpha (transparency) for a color ID.
Sets the face's vertex colors to new color IDs.
Sets the face's vertex normals to new normal IDs.
Sets the face's vertex UVs to new UV IDs.
Sets the face's vertices to new vertex IDs.
Set CFrame for an individual bone in a specific FACS action unit.
Set pose for all bones in a specific FACS corrective pose.
Set pose for all bones in a specific FACS action unit.
Set the normal for a normal ID.
Sets a vertex position in the mesh's local object space.
Sets UV coordinates for a UV ID.
Sets skinning blend weights for each bone associated with the vertex.
Assign a list of bones with the vertex for skinning.
Splits all faces on the mesh to be triangles.
Properties
FixedSize
Methods
AddTriangle
Parameters
Returns
Destroy
Returns
RaycastLocal
Parameters
Returns
Code Samples
local AssetService = game:GetService("AssetService")
local Workspace = game:GetService("Workspace")
-- Initialize EditableMesh in space
local editableMesh = nil
local success, errorMsg = pcall(function()
editableMesh = AssetService:CreateEditableMeshAsync(Content.fromUri("rbxassetid://ASSET_ID"))
end)
local meshPart = nil
if success and editableMesh then
meshPart = AssetService:CreateMeshPartAsync(
Content.fromObject(editableMesh),
{ CollisionFidelity = Enum.CollisionFidelity.Hull }
)
meshPart.Parent = Workspace
else
warn(errorMsg)
end
-- Function that will cast a ray from the given point, returning the world point of the hit and the UV coordinate
local function castRayFromCamera(meshPart : MeshPart, editableMesh : EditableMesh, viewportPoint : Vector3)
if not meshPart then
return
end
-- Calculate how much the object is being scaled in each dimension
local renderScale = meshPart.Size / meshPart.MeshSize
-- Create ray from camera along the direction of a clicked point
local ray = Workspace.CurrentCamera:ViewportPointToRay(viewportPoint.X, viewportPoint.Y)
-- Convert to object space to use with RaycastLocal()
local relativeOrigin = meshPart.CFrame:PointToObjectSpace(ray.Origin) / renderScale
local relativeTarget = meshPart.CFrame:PointToObjectSpace(ray.Origin + ray.Direction * 100) / renderScale
local relativeDirection = relativeTarget - relativeOrigin
local faceId, point, barycentricCoordinate, vertId1, vertId2, vertId3 = editableMesh:RaycastLocal(relativeOrigin, relativeDirection)
if not faceId then
-- Didn't hit any faces
return
end
-- Compute the hit point in world space
local worldHitPoint = meshPart.CFrame:PointToWorldSpace(point * renderScale)
-- Get the UVs on the face
local uvId1 = editableMesh:GetVertexFaceUV(vertId1, faceId)
local uvId2 = editableMesh:GetVertexFaceUV(vertId2, faceId)
local uvId3 = editableMesh:GetVertexFaceUV(vertId3, faceId)
local uv1 = editableMesh:GetUV(uvId1)
local uv2 = editableMesh:GetUV(uvId2)
local uv3 = editableMesh:GetUV(uvId3)
-- Interpolate UVs within the face based on the barycentric coordinate
local u = (barycentricCoordinate.x * uv1.x) + (barycentricCoordinate.y * uv2.x) + (barycentricCoordinate.z * uv3.x)
local v = (barycentricCoordinate.x * uv1.y) + (barycentricCoordinate.y * uv2.y) + (barycentricCoordinate.z * uv3.y)
return worldHitPoint, Vector2.new(u, v)
end