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.

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.

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

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

Enabling EditableMesh for Published Experiences

For security purposes, using EditableMesh fails by default for published experiences. To enable usage, 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).

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

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.

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(eMesh, vid0, vid1, vid2, vid3)
	local nid = eMesh:AddNormal()  -- This creates a normal ID which is automatically computed

	local fid1 = eMesh:AddTriangle(vid0, vid1, vid2)
	eMesh:SetFaceNormals(fid1, {nid, nid, nid})

	local fid2 = eMesh:AddTriangle(vid0, vid2, vid3)
	eMesh:SetFaceNormals(fid2, {nid, nid, nid})
end

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

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

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

	eMesh:RemoveUnused()
	return eMesh
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.

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.