EditableMesh
EditableMesh changes the applied visual mesh when parented 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 mesh ID using AssetService:CreateEditableMeshAsync(), or a blank EditableMesh can be created with Instance.new(). 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 parented to a MeshPart, but only the part's appearance changes while the collision model remains the same.
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:
-- 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 = Instance.new("EditableMesh")
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.
Resumen
Propiedades
The Offset of a mesh determines the relative position from the BasePart.Position of a BasePart that the mesh will be displayed at.
The Scale of a mesh determines the size of the mesh relative to its original dimensions.
Changes the hue of a mesh's texture, used with FileMesh.TextureId.
Métodos
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.
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.
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 all faces of the mesh.
Returns a list of faces that use a given attribute ID.
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 all vertices as a list of stable vertex IDs.
Returns a list of vertices that use a given attribute ID.
Returns a string describing a stable ID, useful for debugging purposes.
Merges vertices that touch together.
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.
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 the normal for a normal ID.
Sets a vertex position in the mesh's local object space.
Sets UV coordinates for a UV ID.
Splits all faces on the mesh to be triangles.
Propiedades
SkinningEnabled
Métodos
AddColor
Adds a new color to the geometry and returns a stable color ID.
Parámetros
Devuelve
Stable color ID of the new color.
AddNormal
Adds a new normal to the geometry and returns a stable normal ID. If the normal value isn't specified, the normal will be automatically calculated.
Parámetros
The normal vector. If the normal value isn't specified, the normal will be automatically calculated.
Devuelve
Stable normal ID of the new normal.
AddTriangle
Adds a new triangle to the mesh and returns a stable face ID.
Parámetros
ID of the first vertex of the triangle.
ID of the second vertex of the triangle.
ID of the third vertex of the triangle.
Devuelve
AddUV
Adds a new UV to the geometry and returns a stable UV ID.
Parámetros
The new UV coordinate.
Devuelve
Stable UV ID of the new UV.
AddVertex
Adds a new vertex to the geometry and returns a stable vertex ID.
Parámetros
Position in the mesh's local object space.
Devuelve
Stable vertex ID of the new vertex.
FindClosestPointOnSurface
Finds the closest point on the mesh's surface. Returns the face ID, point on the mesh in local object space, and the barycentric coordinate of the position within the face. See RaycastLocal() for more information on barycentric coordinates.
Parámetros
Point position in the mesh's local object space.
Devuelve
Tuple of the face ID, point on the mesh in local object space, and the barycentric coordinate of the position within the face.
FindClosestVertex
Finds the closest vertex to a specific point in space and returns a stable vertex ID.
Parámetros
Point position in the mesh's local object space.
Devuelve
Closest stable vertex ID to the specified point in space.
FindVerticesWithinSphere
Finds all vertices within a specific sphere and returns a list of stable vertex IDs.
Parámetros
Center of the sphere in the mesh's local object space.
Radius of the sphere.
Devuelve
List of stable vertex IDs within the requested sphere.
GetAdjacentFaces
Given a stable face ID, returns a list of adjacent faces.
Parámetros
Devuelve
GetAdjacentVertices
Given a stable vertex ID, returns a list of adjacent vertices.
Parámetros
Vertex ID around which to get adjacent vertices.
Devuelve
List of IDs of adjacent vertices around the given vertex ID.
GetColor
Returns the color for the given color ID.
Parámetros
Color ID for which to get the color.
Devuelve
Color for the requested stable color ID.
GetColorAlpha
Returns the color alpha (transparency) at the given stable color ID.
Parámetros
Color ID for which to get the alpha.
Devuelve
Color alpha at the request stable color ID.
GetColors
Returns all colors of the mesh as a list of stable color IDs.
Devuelve
List of stable color IDs.
GetFaceColors
Returns the face's color IDs for the vertices on the face.
Parámetros
Face ID for which to get the color IDs.
Devuelve
List of color IDs used for the vertices on the given face.
GetFaceNormals
Returns the face's normal IDs for the vertices on the face.
Parámetros
Face ID for which to get the normal IDs.
Devuelve
List of normal IDs used for the vertices on the given face.
GetFaceUVs
Returns the face's UV IDs for the vertices on the face.
Parámetros
Face ID for which to get the UV IDs.
Devuelve
List of UV IDs used for the vertices on the given face.
GetFacesWithAttribute
Returns a list of faces that use a given vertex ID, normal ID, UV ID, or color ID.
Parámetros
Attribute ID for which to find faces that use it.
Devuelve
List of face IDs which use the given attribute ID.
GetNormal
Returns the normal vector for the given normal ID.
Parámetros
Normal ID for which to get the normal vector.
Devuelve
Normal vector at the requested normal ID.
GetNormals
Returns all normals of the mesh as a list of stable normal IDs.
Devuelve
List of stable normal IDs.
GetPosition
Gets the position of a vertex in the mesh's local object space.
Parámetros
Stable vertex ID for which to get the position.
Devuelve
Position of a vertex in the mesh's local object space.
GetUV
Returns UV coordinates at the given UV ID.
Parámetros
UV ID for which to get the UV coordinate.
Devuelve
UV coordinates at the requested UV ID.
GetUVs
Returns all UVs of the mesh as a list of stable UV IDs.
Devuelve
List of stable UV IDs.
GetVertices
Returns all vertices as a list of stable vertex IDs.
Devuelve
List of stable vertex IDs.
GetVerticesWithAttribute
Returns a list of vertices that use a given face ID, normal ID, UV ID, or color ID.
Parámetros
Attribute ID for which to find vertices that use it.
Devuelve
List of vertex IDs which use the given attribute ID.
IdDebugString
Returns a string describing a stable ID, useful for debugging purposes, like f17 or v12, containing the type, ID number, and version.
Parámetros
ID for which to return a debugging information string.
Devuelve
String that describes the ID in human-readable format.
MergeVertices
Merges vertices that touch together, to use a single vertex ID but keep the other original attribute IDs.
Parámetros
The distance at which the vertices are considered to touch each other.
Devuelve
A mapping of old vertex ID to new vertex ID for vertices that have been merged.
RaycastLocal
Casts a ray and returns a point of intersection, face ID, and barycentric coordinates. The inputs and outputs of this method are in the mesh's local object space.
A barycentric coordinate is a way of specifying a point within a face as a weighted combination of the 3 vertices of the face. This is useful as a general way of blending vertex attributes. See this method's code sample as an illustration.
Parámetros
Origin of the ray in the mesh's local object space.
Direction of the ray.
Devuelve
Tuple of the point of intersection, face ID, and barycentric coordinates.
Muestras de código
local AssetService = game:GetService("AssetService")
local meshPart = Instance.new("MeshPart")
meshPart.Parent = workspace
-- Initialize EditableMesh in space
local success, editableMesh = pcall(function()
return AssetService:CreateEditableMeshAsync("rbxassetid://ASSET_ID")
end)
if success then
editableMesh.Parent = meshPart
end
local function castRayFromCamera(position)
if not editableMesh then return end
-- Create ray from camera along the direction of a clicked point
local camera = workspace.CurrentCamera
local ray = camera:ScreenPointToRay(position.X, position.Y)
-- Convert to object space to use with RaycastLocal()
local relativeOrigin = meshPart.CFrame:PointToObjectSpace(ray.Origin)
local relativeDirection = meshPart.CFrame:VectorToObjectSpace(ray.Direction)
local triangleId, point, barycentricCoordinate
triangleId, point, barycentricCoordinate = editableMesh:RaycastLocal(relativeOrigin, relativeDirection * 100)
if not triangleId then
-- Didn't hit any triangles
return
end
-- Interpolate UVs within the triangle
local vert1, vert2, vert3 = editableMesh:GetTriangleVertices(triangleId)
local uv0 = editableMesh:GetUV(vert1)
local uv1 = editableMesh:GetUV(vert2)
local uv2 = editableMesh:GetUV(vert3)
local u = (barycentricCoordinate.x * uv0.x) + (barycentricCoordinate.y * uv1.x) + (barycentricCoordinate.z * uv2.x)
local v = (barycentricCoordinate.x * uv0.y) + (barycentricCoordinate.y * uv1.y) + (barycentricCoordinate.z * uv2.y)
return Vector2.new(u, v)
end
RemoveUnused
Removes all vertices, normals, UVs, and colors which are not used in any face, and returns the removed IDs.
Devuelve
All of the removed stable IDs.
ResetNormal
Reset this normal ID to be automatically calculated based on the shape of the mesh, instead of manually set.
Parámetros
Stable normal ID to reset.
Devuelve
SetColor
Sets the color for a color ID.
Parámetros
Devuelve
SetColorAlpha
Sets the color alpha (transparency) for a color ID.
Parámetros
Devuelve
SetFaceColors
Sets the face's vertex colors to new color IDs.
Parámetros
Face ID for which to update the vertex colors.
List of new stable color IDs to use for the given face's vertices.
Devuelve
SetFaceNormals
Sets the face's vertex normals to new normal IDs.
Parámetros
Face ID for which to update the vertex normals.
List of new stable normal IDs to use for the given face's vertices.
Devuelve
SetFaceUVs
Sets the face's vertex UVs to new UV IDs.
Parámetros
Face ID for which to update the vertex UVs.
List of new stable UV IDs to use for the given face's vertices.
Devuelve
SetFaceVertices
Sets the face's vertices to new vertex IDs.
Parámetros
Face ID for which to update the vertices.
List of new stable vertex IDs to use for the given face.
Devuelve
SetNormal
Set the normal for a normal ID. This will change the normal value for every face vertex which is using the normal ID.
Parámetros
Stable normal ID for which to set the normal vector.
Normal vector to set.
Devuelve
SetPosition
Sets a vertex position in the mesh's local object space.
Parámetros
Stable vertex ID of the vertex to position.
Position in the mesh's local object space.
Devuelve
SetUV
Sets UV coordinates for a UV ID.
Parámetros
Devuelve
Triangulate
Splits all faces on the mesh to be triangles. Currently this does nothing since only triangles can be created, but if your code relies on triangles, it's recommended that you call this method after calling AssetService:CreateEditableMeshAsync().