EditableMesh

Mostrar obsoleto

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.

Order of the vertices around the face

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

Propiedades heredados de DataModelMesh

Métodos

Propiedades

SkinningEnabled

Leer paralelo

Métodos

AddColor

Adds a new color to the geometry and returns a stable color ID.

Parámetros

color: Color3

The new color.

alpha: number

The color alpha (transparency).


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

normal: Vector3

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

vertexId0: number

ID of the first vertex of the triangle.

vertexId1: number

ID of the second vertex of the triangle.

vertexId2: number

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: Vector3

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

toThisPoint: Vector3

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: Vector3

Center of the sphere in the mesh's local object space.

radius: number

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.

Adjacent faces indicated around requested face

Parámetros

faceId: number

Devuelve

GetAdjacentVertices

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

Adjacent vertices indicated around requested vertex

Parámetros

vertexId: number

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

colorId: number

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

colorId: number

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

faceId: number

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

faceId: number

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

faceId: number

Face ID for which to get the UV IDs.


Devuelve

List of UV IDs used for the vertices on the given face.

GetFaceVertices

Parámetros

faceId: number

Devuelve

GetFaces

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


Devuelve

GetFacesWithAttribute

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

Parámetros

id: number

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

normalId: number

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

vertexId: number

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

uvId: number

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

id: number

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: number

ID for which to return a debugging information string.


Devuelve

String that describes the ID in human-readable format.

MergeVertices

Map

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

Parámetros

mergeTolerance: number

The distance at which the vertices are considered to touch each other.


Devuelve

Map

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: Vector3

Origin of the ray in the mesh's local object space.

direction: Vector3

Direction of the ray.


Devuelve

Tuple of the point of intersection, face ID, and barycentric coordinates.

Muestras de código

EditableMesh:RaycastLocal()

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

RemoveFace

void

Removes a face using its stable face ID.

Parámetros

faceId: number

Devuelve

void

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

void

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

Parámetros

normalId: number

Stable normal ID to reset.


Devuelve

void

SetColor

void

Sets the color for a color ID.

Parámetros

colorId: number

Stable color ID for which to set the color.

color: Color3

Color to set.


Devuelve

void

SetColorAlpha

void

Sets the color alpha (transparency) for a color ID.

Parámetros

colorId: number

Stable color ID for which to set the color alpha.

alpha: number

Alpha to set.


Devuelve

void

SetFaceColors

void

Sets the face's vertex colors to new color IDs.

Parámetros

faceId: number

Face ID for which to update the vertex colors.

ids: Array

List of new stable color IDs to use for the given face's vertices.


Devuelve

void

SetFaceNormals

void

Sets the face's vertex normals to new normal IDs.

Parámetros

faceId: number

Face ID for which to update the vertex normals.

ids: Array

List of new stable normal IDs to use for the given face's vertices.


Devuelve

void

SetFaceUVs

void

Sets the face's vertex UVs to new UV IDs.

Parámetros

faceId: number

Face ID for which to update the vertex UVs.

ids: Array

List of new stable UV IDs to use for the given face's vertices.


Devuelve

void

SetFaceVertices

void

Sets the face's vertices to new vertex IDs.

Parámetros

faceId: number

Face ID for which to update the vertices.

ids: Array

List of new stable vertex IDs to use for the given face.


Devuelve

void

SetNormal

void

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

normalId: number

Stable normal ID for which to set the normal vector.

normal: Vector3

Normal vector to set.


Devuelve

void

SetPosition

void

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

Parámetros

vertexId: number

Stable vertex ID of the vertex to position.

Position in the mesh's local object space.


Devuelve

void

SetUV

void

Sets UV coordinates for a UV ID.

Parámetros

uvId: number

UV ID for which to set the UV coordinates.

UV coordinates.


Devuelve

void

Triangulate

void

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


Devuelve

void

Eventos