Get ready to take your character and mesh animations to the next level! We’re thrilled to announce a powerful set of new APIs for EditableMesh that give you unprecedented control over Skinning, Bones, and Facial Action Coding System (FACS) data.
These additions will empower you to procedurally create, modify, and animate complex meshes with greater fidelity and dynamism right within Roblox.
When working with an animated 3D mesh like a character, you first need to rig it to give the mesh structure. This is done by adding “bones” to the mesh to define where and how the mesh can articulate. Think of these bones like the pieces of a wooden puppet. Next, you would skin the mesh by assigning individual vertices in a mesh to one or more bones so that those vertices would move if you moved the bones. During skinning, you also assign weights to each bone that influences a vertex since you might want one bone to influence a vertex more than another. Once you are done rigging and skinning a mesh, you can then drive the bones with an animation system which would in turn move the vertices of the mesh scaled by the individual weights that were previously assigned. This is akin to moving the strings that control the puppet.
When working with Roblox, you would traditionally do the Rigging and Skinning steps in an external tool like Blender, embed the data into the mesh and then import it into Roblox. You would then use Bone instances or Motor6Ds to address the individual bones within your mesh by name and then hook them up to the animation system or a script to drive the mesh.
With EditableMesh, you now have direct access to modify this embedded bone and skinning data right within your experiences at runtime!
Enabling the Studio Beta
In Studio, go to File > Beta features and enable the EditableMesh Skinning and FACS beta.
Full Control Over Bones!
You can now manipulate the skeleton of your EditableMesh instances with a comprehensive suite of bone-related functions. This allows you to dynamically add, remove, and query bone information, and modify their properties like names, hierarchy, transforms, and whether it is a virtual bone (virtual bones are typically used with FaceControls).
New EditableMesh Bone APIs include:
- Creation & Removal:
EditableMesh:AddBone(): Adds a new bone with specified properties (name, parent, CFrame, virtual status).EditableMesh:RemoveBone(): Removes a bone by its ID.
- Querying Bone Data:
EditableMesh:GetBones(): Lists all bone IDs in the mesh.EditableMesh:GetBoneByName(): Finds a bone ID using its name.EditableMesh:GetBoneName(): Retrieves a bone’s name.EditableMesh:GetBoneParent(): Gets a bone’s parent ID.EditableMesh:GetBoneCFrame(): Returns a bone’s initial CFrame (bind pose).EditableMesh:GetBoneIsVirtual(): Checks if a bone is virtual.
- Modifying Bones:
EditableMesh:SetBoneName(): Updates a bone’s name.EditableMesh:SetBoneParent(): Changes a bone’s parent.EditableMesh:SetBoneCFrame(): Modifies a bone’s initial CFrame.EditableMesh:SetBoneIsVirtual(): Sets a bone’s virtual status.
It’s important to distinguish these EditableMesh bones from Bone instances:
Mesh bones are data embedded within the mesh itself. They define the underlying skeletal structure, bind pose, and FACS data for the mesh and EditableMesh now gives you access to query and modify them.
Bone instances, on the other hand, are typically parented to a Model or MeshPart, and can be used by the animation system or by scripts to drive the bones embedded within meshes.
While Bone instances are live objects in the hierarchy that drive animations, EditableMesh bones are the blueprint within the mesh data that dictates how it can be deformed and animated when applied to a MeshPart (often in conjunction with systems like FaceControls for facial animation). Internal bones and Bone instances are bound to each other by their unique names. For example: The MeshPart.Neck instance will drive the runtime transformation of the EditableMesh:GetBoneByName("Neck") internal bone.
Advanced Skinning Manipulation!
Skinning is crucial for realistic mesh deformation, and now you have direct access to vertex-bone associations and their weights. This means you can define or alter how vertices are influenced by bones.
New Skinning APIs include:
EditableMesh:GetVertexBones(): Returns bone IDs associated with a vertex for skinning.EditableMesh:GetVertexBoneWeights(): Returns the blend weights for those bones.EditableMesh:SetVertexBones(): Assigns bones to a vertex for skinning.EditableMesh:SetVertexBoneWeights(): Sets the blend weights for those assigned bones. (Remember to callSetVertexBonesbeforeSetVertexBoneWeights!)
These APIs open up possibilities for in-experience character customization, and much more!
Expressive Facial Animations with FACS APIs!
Expressive Facial Animations with FACS APIs!We’re also introducing a suite of functions to manage Facial Action Coding System (FACS) poses, giving you fine-grained control over facial expressions on animatable heads!
Understanding FACS Poses:
Animatable heads use FACS to define expressions. Each base facial pose is tied to a FacsActionUnit. For each action unit, virtual bones can have a specific CFrame transforming them from their bind pose to that action unit’s pose. Posing the virtual bones to match the corresponding action units gives the animation system all the data it needs to animate heads on Roblox.
Sometimes, blending base poses can lead to undesirable results. That’s where corrective poses come in! A corrective pose (defined by 2 or 3 Enum.FacsActionUnit values) allows you to specify a more pleasing result for specific combinations of base poses.
For more details on FACS, check out the FACS poses reference and corrective pose documentation.
New FACS APIs include:
- Querying FACS Data:
EditableMesh:GetFacsPoses(): Lists all FacsActionUnits with defined poses.EditableMesh:GetFacsPose(): Gets bone IDs and CFrames for a specific FACS action unit.EditableMesh:GetFacsCorrectivePoses(): Lists all active corrective poses.EditableMesh:GetFacsCorrectivePose(): Gets bone IDs and CFrames for a specific corrective pose.
- Setting FACS Data:
EditableMesh:SetFacsPose(): Sets the pose (bone IDs and CFrames) for a FACS action unit.EditableMesh:SetFacsBonePose(): Sets the CFrame for an individual bone within a FACS action unit.EditableMesh:SetFacsCorrectivePose(): Sets the pose for a FACS corrective pose.
These FACS APIs will be invaluable for creators working on dynamic facial expressions, custom character heads, and advanced animation tooling.
Example Place Files
To help you get started, we’ve prepared a couple of example places:
Example 1: Simple Skinned Logo Animation
Editable_Skinning_Logo_Recolor.rbxl (80.0 KB)
This example demonstrates how to take an existing skinned mesh (a Roblox logo cube) and use the new bone APIs to apply simple procedural animation, making it wiggle and deform at runtime. It’s a great starting point to understand bone manipulation.
Simply download and open up the attached RBXL file in Studio and hit play to see the logo dance.
Take a look at the Workspace > logo > AnimateLogo script to see how the new APIs are being used to set up and animate the logo. You will also notice that the script contains a bit of code to recolor the faces of the mesh just to prove that it is still an EditableMesh
Example 2: R15 Avatar skinning and FACS Demo
R15-EditableMeshSkinningFACSv2.rbxl (408.5 KB)
Starting with 15 separate, unskinned MeshParts, this demo shows how to programmatically generate a full bone hierarchy, apply skinning data to all vertices, and set up basic FACS poses for facial animation. The resulting avatar is structured to meet the technical requirements for UGC validation, providing a powerful example of procedural avatar assembly.
Note: This demo sometimes uses a pre-skinned/rigged avatar hidden in ReplicatedStorage to copy over positions or raw skinning weights but you are free to build your own weight painting UI or rigging UI to create everything from scratch!
Once you download and open the RBXL file in Studio, hit play and then use the buttons on the left to go through each step of the process in order:
- Orbit Camera: Sets the camera so it orbits around the new “avatar”
- Place attachments: Creates new
Attachmentinstances with the correct naming conventions to define the R15 rig - Show / Hide skeleton: Shows/Hides optional example UX to modify the locations of the Rig attachments
- Build R15 Rig: Adds the requisite R15 instances to the model (e.g.
Humanoid) and calls Humanoid:BuildRigFromAttachments to convert the Rig attachments to appropriate Motor6Ds. Note: At this point, you could play R15 animations on the avatar but the joints would look odd since they do not contain skinning data. - Set Bones: Uses the skeleton UI to create the correct bone hierarchies inside each of the 15
EditableMeshobjects. - Show/Hide Bones: Visualizes the actual bone structures created within the EditableMesh objects
- Skin Inv Distance: Uses a naive inverse distance algorithm to set skinning weights for each vertex based on its distance to the closest bones. (Note: This will not give great results and is meant to be illustrative)
- Avatar Inv Distance: Slightly improved inverse distance algorithm that only uses adjacent bones in the skeleton hierarchy to influence vertices. (Again, non-ideal weights but better than the previous algorithm)
- Authored Skinning: Transfers skinning weights from a pre-authored avatar vertex-by-vertex to the new avatar
- Show/Hide Skinning weights: Uses standard colors to visualize skinning weights for each vertex. Each color corresponds to a specific R15 bone to make it easier to compare results
- Animate Avatar: Plays a running animation on the avatar
- Apply FACS Poses: Transfers pre-authored FACS poses from an existing avatar over to the new avatar
- Animate Face: Cycles through a number of facial expressions to showcase the FACS pose data
- Switch to Avatar: Uses
ApplyMeshto transfer all 15 meshes to your own avatar so you can run around and test out the results - Run UGC Validation: Runs all the UGC validation steps to verify that the avatar could be successfully published using the
PromptCreateAvatarAsyncAPI
Each of the TextButton instances in the GUI have simple corresponding child scripts that you can use to follow along. Look under StarterGUI > ScreenGui > ScrollingFrame to find all the TextButtons
The scripts under each of the buttons call out to specific functions all housed within ReplicatedStorage > RigControl.
Known Issues
- Loading certain meshes with skinning data into an EditableMesh may briefly slow down the engine, as it can temporarily block the main thread. This will be addressed before the full release.
- When publishing and reloading meshes that include FACS data, there is a possibility of small skinning precision errors being introduced each time the data is saved and loaded. The level of detail should be sufficient for most uses. If you need to save and reload the same mesh many times, be aware that these minor changes could accumulate over time.
- If all the vertex weights for a given
EditableMeshvertex are zero, the vertex is placed at the origin
What’s Next?
The launch of these Skinning, Bones, and FACS APIs is a significant step, but we’re not stopping here! Our team is dedicated to continuously improving the EditableMesh feature set and the broader tools for mesh manipulation on Roblox.
- We are actively investigating solutions for key EditableMesh usability impediments, including Replication support, Permissions, Memory budget limits, and ID Verification requirements. While we don’t have a firm timeline to share at the moment, keep an eye out over the next few months for updates.
- We have a few quality of life API / workflow improvements, bug fixes and performance improvements to
EditableMeshthat will be ready in a few weeks. Keep an eye out for a separate Dev Forum post when these are available. - Once we are confident that the API surface for these Skinning / FACS APIs are final, we will push to let you publish experiences with these new APIs as soon as possible.
- We are actively working on EditableImage support for SurfaceAppearance as well as a host of WrapDeformer fixes. Keep an eye out for updates on those over the coming months as well.
We’re incredibly excited to see the innovative experiences you’ll build with these new EditableMesh capabilities. Dive in, experiment with the examples, and don’t forget to share your amazing creations and feedback with us! We are specifically looking for feedback on the API surface, naming, and common workflows.
Happy skinning and FACSing,
@L3Norm, @monsterjunjun, @ContextLost, @Penpen0u0, @lweoalawelu, @cyrian_sun, @c0de517e, @syntezoid, @portenio, @FGmm_r2 and @gelkros on behalf of the Geometry team.
