hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-26 10:34:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

rules

Browse source
This commit is contained in:
Joe 2026-02-02 12:08:47 -06:00
parent a9b4f8e83b
commit e6efc04756
8494 changed files with 495610 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

130
.cursor/rules/roblox/art/characters/creating/blender-configurations.md Normal file
View file

@ -0,0 +1,130 @@
---
title: Blender configuration
description: Roblox avatar template projects have several helper configurations and settings to help expedite the character creation process.
next: /art/characters/creating/modeling-best-practices
prev: /art/characters/creating/head-objects
---
The Blender project files of each template include additional helper configurations that are not included in the raw `.fbx` template files. If you intend on using Blender for your character creation process, it's important to understand the additions included in the `.blend` versions of the template and what they do.
### Hierarchy
The following is a breakdown of what is included in each Blender template file:
<GridContainer numColumns="2">
<figure>
- **Cage**: Contains the character's 15 outer body cage meshes.
- **Joints**: The parent armature object that includes the following objects:
- The **bones** that make up the character's rigging armature.
- The **_Geo** mesh objects that make up the avatar appearance.
- The **_Att** attachment objects that define where accessories attach when equipped.
- The **animation data** for saving facial animation data and poses.
- **Fill** and **Sun**: These objects are used to provide lighting, allowing you to preview your characters in a neutral lighting similar to a Studio baseplate. These are not part of the avatar character.
</figure>
<figure><img
alt="Head-Related Meshes"
src="../../../assets/art/blender-ui/Blender-Project-Objects.png"
width="800" /><figcaption>Blender Project Hierarchy</figcaption></figure>
</GridContainer>
### Disabled objects
When using the template project files for Blender, you might notice some objects, like attachment objects, are permanently hidden in the Viewport even when toggling the **Hide In Viewport** icon <img src="../../../assets/art/blender-ui/Visibility-Icon.png" style={{marginBottom:"0px;"}} width="20px"/>. Since attachment objects are often not modified until the end of the character creation process, these objects have **Disable In Viewport** <img src="../../../assets/art/blender-ui/Disabled-Icon.png" style={{marginBottom:"0px;"}} width="20px"/> enabled to make the organization of your project more efficient, especially when bulk toggling object visibility.
If you need access to disabled objects, use the following instructions to access the **Disable In Viewport** toggle:
1. In your Outliner, click the **Filter** dropdown.
<img src="../../../assets/art/blender-ui/Outliner-Filter.png" />
2. Enable the **Disable In Viewport** filter.
<img src="../../../assets/art/blender-ui/Outliner-Menu.png" />
3. The **Disable In Viewport** icon <img src="../../../assets/art/blender-ui/Disabled-Icon.png" style={{marginBottom:"0px;"}}/> now appears next to every object in the Outliner. Toggle the icon to change the Disabled status for your objects.
<img src="../../../assets/art/blender-ui/Outliner-Disabled-Enabled.png" />
### Custom skin tones
The Blender project files include a shader configuration that allows you to preview custom skin tones, similar to how they display in Roblox if users customize their skin tones.
Textures with full or partial transparency allow the underlying `Class.Part.Color` to reveal through the applied texture, enabling a user to personalize their avatar character with custom skin tones.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Texture-Map.png" /> <figcaption>A texture map example that uses low opacity to reveal underlying skin color and full opacity to apply a fully-opaque color to the undergarments, eyebrows, mouth, and eyes.</figcaption></figure>
<figure><img src="../../../assets/art/avatar/templates/Custom-Skin-Tones.png" /><figcaption>The same avatar character using the same texture map. Each model has different underlying part colors except where the texture map applies a full color. </figcaption></figure>
</GridContainer>
#### Preview skin tones
<Alert severity = 'warning'>
You must use **Blender 3.4+** to ensure that the helper shader configurations render correctly. If you are using a previous version of Blender, textures may not render as expected.
</Alert>
The Blender project file includes shader configurations that allow you to preview custom skin tones similar to how they appear in Studio. These custom colors do not export with the model, but can provide you a quick visual reference for how a custom skin color and texture might look in Roblox.
For this Blender shader configuration, keep in mind the following requirements:
- You must switch to **Viewport Shading** mode for textures to render as expected.
<img src="../../../assets/art/blender-ui/Viewport-Shading-Setting.png" style={{marginBottom:"0px;"}}/>
- When swapping out textures, the normal map's colorspace reverts to **SRGB** instead of **NonColor**. If this occurs, you might need to change it back in order for the normal map to render correctly.
To preview your character's skin tone in Blender:
1. In **Layout**, select any geometry object, such as **Head_Geo**.
2. Go to the **Shading** tab.
3. In the Node panel, ensure **Object** is selected.
4. Find the **PartColor** node that is attached to the **Mix** node.
5. Pick a color and value on the node to apply a reference custom skin tone.
<video
controls
src="../../../assets/art/avatar/basic-creation/Color_Picker_01.mp4"
width="100%"></video>
#### Export setup
While the skin tone preview is a critical element to verifying your templates color and tone compatibility in Roblox, it prevents your color texture map from automatically being packaged with the final `.fbx` file. There are two ways to resolve this before exporting your model:
1. In the Shading tab, disconnect the **Mix** node and replace it with the **ColorMap** node.
2. Export your textures manually as separate image files and add them later in Studio.
For instructions on how to perform either export workflow, see [Export textures](../../../art/characters/creating/export-textures.md).
### Scene scale
<Alert severity = 'warning'>
You can skip this section if you are using the Blender downloadable templates. The `.blend` versions of the templates which already contain many of the project settings required when setting up a Blender project configuration.
</Alert>
When creating Roblox assets in a modeling application, it's important to ensure your `.fbx` exports scale correctly. The `.fbx` file type scales objects by `100`, meaning that you have to modify your working scale by `.01`. The template files already apply this scaling.
There are two ways to perform this scaling. You can modify your scene scale properties in your project with the following steps:
1. In the **Properties** window, navigate to the **Scene Properties** tab.
<img src="../../../assets/art/blender-ui/Scene-Options.png" width = "50%" />
2. In the Units section, change the **Unit Scale** to `0.01` and the **Length** to **Centimeters**.
Alternatively, you can modify your scaling when exporting your files:
1. Navigate to **File** > **Export** > **FBX (.fbx)**.
2. Set **Transform** > **Scale** to `.01`.
<img src="../../../assets/modeling/skinned-meshes/Blender-Export-Settings-2.png" width="320" />
### Animation range
<Alert severity = 'warning'>
You can skip this section if you are using the Blender downloadable templates. The `.blend` versions of the templates which already contain many of the project settings required when setting up a Blender project configuration.
</Alert>
For custom characters with facial animation, ensure that the timeline range is set between 0 and 330:
1. In the top right of the Animation Panel, click and set **Start** to `0`.
2. In the top right of the Animation Panel, click and set **End** to `330`.
<img src="../../../assets/art/blender-ui/Timeline-Frames.png" width = "65%"/>
<Alert severity = 'info'>
After you change your project settings, you can set these as your default Blender project settings by navigating to **File** > **Defaults** > **Save Startup File**.
</Alert>

60
.cursor/rules/roblox/art/characters/creating/caging.md Normal file
View file

@ -0,0 +1,60 @@
---
title: Caging character head
description: Cage your avatar characters in Blender to support layerable accessories and clothing.
next: /art/characters/creating/combine-head-geometry
prev: /art/characters/creating/texturing-pbr
---
**Caging** is the process of updating the [cage mesh component](../../../art/characters/index.md#cage-meshes) of your avatar character. To allow your character to correctly wear layered clothing and accessories, you must update the default template cage mesh object to match the sculpting changes you made to your custom character.
Since this tutorial only applies modeling changes to the head, the caging instructions below only apply to the **Head_OuterCage** object. If you make geometry changes to other parts of the character, you must also adjust those specific **\_OuterCage** objects to match your sculpting changes.
<Alert severity ='error'>
Do not delete any vertices or faces of the provided cages. Destructive modification of the cages can cause import issues and prevent the character model from equipping clothing and cosmetics.
</Alert>
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Pre-Caging.png" /> <figcaption>Default head cage mesh no longer fits over sculpted head</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Caging.png" /><figcaption>Head cage mesh after adjustment</figcaption></figure>
</GridContainer>
<Alert severity = 'info'>
If your character body shape incorporates many changes with different body parts, it may be more efficient to use the [Blender Cage Template](../../../assets/modeling/meshes/reference-files/Body_Cage_Templates.zip). This Blender project file includes a helper full-body `std_cage_deformable` mesh to automatically apply vertex changes to the individual body-part cages at the same time.
</Alert>
To begin caging your character:
1. Starting from the Layout Tab, hide everything in the Outliner except the **Head_OuterCage** and the **Head_Geo** objects.
<img src="../../../assets/art/avatar/basic-creation/Caging-Outer-Cage-Objects.png" />
<video controls src="../../../assets/art/avatar/basic-creation/Caging_01.mp4" width="100%"></video>
2. With the **Head_OuterCage** selected, navigate to **Object Properties** > **Viewport Display** and set the **Display As** to **Wire**. Toggle this setting back to **Solid** when you are finished.
<video controls src="../../../assets/art/avatar/basic-creation/Caging_02.mp4" width="100%"></video>
3. Click on the **Head_OuterCage** object and switch to **Edit Mode**.
4. Enable **X-Axis symmetry** and **Topology Mirror** to ensure you are making symmetrical vertex changes to your cage.
<img src="../../../assets/art/avatar/basic-creation/Caging-Symmetry-Settings.png" />
5. Switch to **Edit Mode**.
6. Using the **Grab tool** (<kbd>G</kbd>), click and grab parts of the cage mesh and align it to fit tightly over the goblin head mesh. Keep the following in mind:
1. **Never delete any of the cage vertices.** Missing vertices can cause errors and issues with equipping clothing accessories.
2. If editing the base of your head cage, ensure that the base of the Head cage aligns with the top of the UpperTorso cage.
3. In different Select modes, hold <kbd>Shift</kbd> and click multiple vertices/edges/faces to select and edit the geometry.
4. You can verify a tight fit by grabbing vertices and moving them into the Head_Geo mesh to check where the meshes intersect and moving the cage vertices until the cage mesh just covers the head mesh.
<video controls src="../../../assets/art/avatar/basic-creation/Caging_03.mp4" width="100%"></video>
5. Toggle visibility on your different mesh objects to improve visibility and access to vertices.
6. After the wireframe is tightly fitted over the head mesh, set the **Display As** back to **Solid** and spot check and fix any intersecting vertices.
<video controls src="../../../assets/art/avatar/basic-creation/Caging_04.mp4" width="100%"></video>
Your final product should feature a cage mesh that sits directly over the head mesh without any of the Head_Geo geometry intersecting through the solid sections of the cage.
<img src="../../../assets/art/avatar/basic-creation/Post-Caging.png" />
<Alert severity = 'success'>
For a comparison reference, you can download [this version of the tutorial project with caging completed](../../../assets/art/reference-files/checkpoint/3_Goblin-caged.blend).
</Alert>

41
.cursor/rules/roblox/art/characters/creating/combine-head-geometry.md Normal file
View file

@ -0,0 +1,41 @@
---
title: Combine head geometry
description: When creating characters in Blender, you must combine the head geometry to a single object.
next: /art/characters/creating/remove-extra-bones
prev: /art/characters/creating/caging
---
Whenever you are ready to export your model, it's important to clean up your project to ensure that your model is ready to export. This includes the following tasks that ensure the customized template model and all of the avatar components can import into Studio successfully:
- Combining extra head geometry
- Removing extra head bones
- Verifying attachment points
- Final technical checks
<Alert severity = 'error'>
Failure to combine head geometry and [remove head bones](../../characters/creating/remove-extra-bones.md) will cause issues with validation, as the character will no longer adhere to the expected R15 geometry and joint hierarchy.
</Alert>
## Combine head geometry
At this point, you should also combine the separate head and face objects within the single Head_Geo object. Some templates don't include some face objects, like lashes. To combine the head and face meshes:
1. In the Outliner, hold <kbd>Ctrl</kbd>/<kbd>⌘</kbd> and click following objects, ending with the Head_Geo:
1. UpperTeeth_Geo
2. LowerTeeth_Geo
3. Tongue_Geo
4. RightLash_Geo
5. RightEye_Geo
6. LeftLash_Geo
7. LeftEye_Geo
8. Head_Geo
<img src="../../../assets/art/avatar/basic-creation/Template-Face-Objects.png" />
<Alert severity = 'error'>
When selecting multiple head objects, make sure that the **Head_Geo** is highlighted as yellow, indicating it as the main object that the others merge into. This correctly preserves the custom properties stored in the head mesh. You can achieve this by selecting the head last in the Outliner.
</Alert>
2. While in Object mode, right-click in the Viewport and select **Join**. The objects combine as a single **Head_Geo**.
<video controls src="../../../assets/art/avatar/basic-creation/Cleanup_01.mp4" width="100%"></video>

37
.cursor/rules/roblox/art/characters/creating/export-character.md Normal file
View file

@ -0,0 +1,37 @@
---
title: Export character model
description: Export your character model from Blender using the correct settings and processes.
prev: /art/characters/creating/export-textures
---
<Alert severity = 'warning'>
It's important to test your assets multiple times at every point of the asset creation process, whether it is within Blender or after importing into Studio. See [Test characters](../../../art/characters/testing/index.md) for more information.
</Alert>
Whether you are exporting your character for testing, or are performing a final export out of Blender, you must apply the appropriate export settings to ensure that Blender exports the proper character data.
To export your character:
1. In the topbar, click **File** > **Export** > **FBX (.fbx)**. The Blender file browser window displays.
2. Set **Path Mode** to **Copy** and enable the **Embed Textures** icon.
3. In the Include section, enable **Custom Properties**.
4. Expand the Armature section and uncheck **Add Leaf Bones**.
5. Enable **Bake Animation**.
6. Expand Bake Animation and **uncheck NLA Strips**, **All Actions**, and **Force Start/End Keyframes**.
7. In Bake Animation, set **Simplify** to **0.0**.
8. Click the **Export FBX** button. Save the `.fbx` to the directory of your choice.
<img src="../../../assets/art/avatar/basic-creation/Export-Settings.png" width = "60%" />
<Alert severity = 'warning'>
After exporting your .fbx file, see [Test characters](../../../art/characters/testing/index.md) for steps on importing your character model into a test place and verifying your avatar and related components.
</Alert>
<Alert severity = 'success'>
After importing the `Class.Model` character to Studio, you can now perform the following with this asset:
- [Upload the character](../../../art/accessories/creating-rigid/publishing.md) to the Marketplace.
- Use the humanoid character on an existing experience by applying a [HumanoidDescription](../../../characters/appearance.md#manually-modify-appearance)to the `Class.Model` object.
- Save the asset to your [Toolbox](../../../projects/assets/toolbox.md) to share or use within any of your experiences.
</Alert>

54
.cursor/rules/roblox/art/characters/creating/export-textures.md Normal file
View file

@ -0,0 +1,54 @@
---
title: Export textures
description: Export your character textures from Blender using the correct settings and processes.
next: /art/characters/creating/export-character
prev: /art/characters/creating/final-checks
---
<Alert severity = 'warning'>
It's important to test your assets multiple times at every point of the asset creation process, whether it is within Blender or after importing into Studio. See [Test characters](../../../art/characters/testing/index.md) for more information.
</Alert>
Whether you are exporting your character for testing, or are performing a final export out of Blender, you must apply the appropriate export settings to ensure that Blender exports the proper character data.
## Export textures
Including the default PBR textures, your template character includes four separate image maps that make up its surface appearance. Depending on your workflow, you can choose to embed the image maps to your export file or export the textures separately as image files. Both methods have advantages:
- [Embedding textures](#embed-textures) simplifies your export by packing all of your textures within the single `.fbx` file.
- [Exporting texture images](#export-textures) directly allows you direct access to the image textures, so you can test and swap them more quickly.
### Embed textures
Embedding the texture maps to your `.fbx` export can simplify the Blender export and Studio import process. When embedding your textures with Roblox's template files, you need to make a quick adjustment to custom skin tone shader nodes in the Blender file.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Cleanup
-Node-A.png" /> <figcaption>Default node configuration: Mix node connected to Base Color</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Cleanup-Node-B.png" /><figcaption>Exportable node configuration: Color node connected directly to Base Color</figcaption></figure>
</GridContainer>
To prepare your textures to embed with export:
1. In Object mode, select any part of the character.
2. Navigate to the **Shading** tab.
3. Ensure the **Type of Data** dropdown is set to **Object**.
<img src="../../../assets/art/avatar/basic-creation/Cleanup-Object-Select.png" width = "60%"/>
4. Find the node that connects to the **Principled BSDF's Base Color**.
<img src="../../../assets/art/avatar/basic-creation/Cleanup-Mix-Node.png" />
5. Click and drag the line from **Base Color** to disconnect the node.
<img src="../../../assets/art/avatar/basic-creation/Cleanup-Disconnect-Node.png" />
6. Find the **file26** node with the color texture map and click and drag the **Color** to **Principled BSDF's color** node.
<img src="../../../assets/art/avatar/basic-creation/Cleanup-Node-B.png" />
<video controls src="../../../assets/art/avatar/basic-creation/Exporting_01.mp4" width="100%"></video>
### Unpack image files
As an alternative to embedding textures, you can export your texture files as separate `.png` image files, which allows you to quickly access and swap image texture maps.
To export your texture image files:
1. Navigate to **File** > **External Data** > **Unpack Resources**.
2. Select **Use files in current directory** to save in the same directory as your project. Blender exports your image files to a textures directory in your project's parent directory.
<img src="../../../assets/art/avatar/basic-creation/Exporting-Pack-Resources.png" width = "55%"/>

12
.cursor/rules/roblox/art/characters/creating/final-checks.md Normal file
View file

@ -0,0 +1,12 @@
---
title: Final checks
description: Before exporting, verify that your model meets Studio's requirements.
next: /art/characters/creating/export-textures
prev: /art/characters/creating/verify-attachments
---
Depending on the types of customizations you made to your template project or model, the following are additional tasks to look out for when cleaning up your project:
- Ensure that your project doesn't contain additional mesh objects that aren't part of your character model geometry.
- Verify that there isn't additional animation data, such as additional keyframes or saved poses and orientations that are not related to the original facial animation data.
- Double-check that your geometry, rig, and texture adhere to the [avatar technical specifications](../../../art/characters/specifications.md).

52
.cursor/rules/roblox/art/characters/creating/head-objects.md Normal file
View file

@ -0,0 +1,52 @@
---
title: Template head structure
description: Each Roblox avatar template contains modular separate pieces that must later be combined or removed.
next: /art/characters/creating/blender-configurations
prev: /art/characters/creating/template-files
---
In each template file, each avatar body includes extra head mesh objects and face armature bones. Separating these objects within the templates allow you to make easier changes to each of these separate objects, as demonstrated during the texturing step.
To avoid validation errors, you must [join](../../../art/characters/creating/combine-head-geometry.md) and [remove](../../../art/characters/creating/remove-extra-bones.md) these extra objects during the cleanup process prior to exporting.
The extra head mesh objects are the following:
<GridContainer numColumns="2">
<figure>
- Head_Geo
- UpperTeeth_Geo
- LowerTeeth_Geo
- Tongue_Geo
- RightLash_Geo
- RightEye_Geo
- LeftLash_Geo
- LeftEye_Geo
</figure>
<figure><img
alt="Head-Related Meshes"
src="../../../assets/art/blender-ui/Face-Objects.png"
width="800" /><figcaption>Extra head-related meshes in Blender's Outliner</figcaption></figure>
</GridContainer>
<p />
The extra head bone children are the following and may differ between templates:
<GridContainer numColumns="2">
<figure>
- Tongue
- LowerTeeth
- UpperTeeth
- LeftEye
- RightEye
</figure>
<figure><img
alt="Head-Related Meshes"
src="../../../assets/art/blender-ui/Face-Bones.png"
width="800" /><figcaption>Extra head-related bones in Blender's Outliner</figcaption></figure>
</GridContainer>
While these extra objects exist to aid the creation and modification process, leaving them in your project on final export will cause validation issues when uploading these assets to the Marketplace.

28
.cursor/rules/roblox/art/characters/creating/index.md Normal file
View file

@ -0,0 +1,28 @@
---
title: Create with templates
description: Use Roblox's supplied template models to create your own unique avatar character in Blender.
next: /art/characters/creating/template-files
---
You can create your own custom avatar character using Blender and one of Roblox's downloadable template models. Using templates can save you a lot of time by skipping the complex processes of setting up your armature, rigging, skinning, and configuring your character for face animations.
This tutorial is intended for creators of all skill levels with moderate Blender experience to create a unique character by:
1. Selecting a base template that include time-saving Blender configurations.
2. Modeling using non-destructive sculpting workflows
3. Texturing using Blender's texture paint tools
4. Caging an asset by editing the template's cage mesh objects
5. Cleaning and prepping the project for export
6. Exporting your asset for use or testing in Studio
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Pre-Tutorial.png" /> <figcaption>Starting template model</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Tutorial.png" /><figcaption>Example model after modifications</figcaption></figure>
</GridContainer>
<Alert severity = 'info'>
This guide uses [Blender 3.4+](https://www.blender.org/download/releases/3-4/) as a practical example for customizing a character template. Before you begin, you should have a basic knowledge using Blender's interface, tools, and viewing controls.
If you are using another program, you can still apply the general workflow of this tutorial with your program's similar tools.
</Alert>

99
.cursor/rules/roblox/art/characters/creating/modeling-best-practices.md Normal file
View file

@ -0,0 +1,99 @@
---
title: Modeling best practices
description: Understand important modeling concepts to prevent major issues before any modeling steps.
next: /art/characters/creating/modeling-tips
prev: /art/characters/creating/blender-configurations
---
Modeling, sometimes known as **sculpting**, is the process of shaping the geometry of your model or mesh. This guide covers important concepts and tips you should review before creating your own unique character shape.
By understanding how to make non-destructive sculpting changes to the head, the character part that contains the most complex components, you can continue to apply these techniques and concepts to other parts of the character model body.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Pre-Sculpting.png" /> <figcaption>Starting template model</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Sculpting.png" /><figcaption>Model after custom sculpting</figcaption></figure>
</GridContainer>
<Alert severity = "error">
When editing templates, **don't delete or add vertices to your character body**. This ensures that your character's skinning and facial animation data remains unaltered and fully functional.
</Alert>
## Non-destructive modeling
Non-destructive modeling means using a process that doesn't alter the physical shape or construction of the base mesh object. When modifying a template model, don't use tools or functions that delete or add vertices to your meshes. Instead, use Blender's sculpting tools to alter the shape of your character by **only changing the position of existing vertices**. This ensures that vertices and faces that have skinning or animation data associated with them retain that important character data.
<Alert severity = 'warning'>
Extreme geometric changes, even if the vertices are not deleted, can still adversely affect your rigging and skinning. It's important to choose a starting template file close to your final design and to make consistent and proportional changes when sculpting.
</Alert>
## Edge flow
Edge flow is a common modeling concept of ensuring that the vertices of your model naturally follow the organic curvature of your model's shape. When making changes to your model's topography, you should maintain a natural edge flow by ensuring that your vertices remain a proportionate distance from each other and follow the common muscle groups and contours of your model.
Even when maintaining edge flow, you should avoid sculpting certain regions of the character model. The following are examples of important sections of the face that follow a natural edge flow and should be kept in a similar shape:
<table>
<thead>
<tr>
<th>Round head region</th>
<th>Edge flow notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<Tabs>
<TabItem label="Round">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Nasolabial-A.png" />
</TabItem>
<TabItem label = "Narrow">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Nasolabial-B.png" />
</TabItem></Tabs></td>
<td>**Forehead Wrinkles and Nasolabial Edges**: The edge lines for the forehead wrinkles and nasolabial edges are vital for various expressions involving the mouth, forehead furrowing, eyebrow movement and cheeks. If you modify these sections of your topography, ensure that you retain the original shape whenever possible, and that they maintain a similar relative relationship to each other. </td>
</tr>
<tr>
<td>
<Tabs>
<TabItem label="Round">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Mouth-A.png" />
</TabItem>
<TabItem label = "Narrow">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Mouth-B.png" />
</TabItem></Tabs></td>
<td>**Mouth and Lip Edges**: The topography surrounding the lips and mouth have circular mesh structures for the mouth to open and close. This structure can fold the mesh to shape the lips to naturally visualize *a*, *e*, *i*, *o*, and *u* vowel sounds. The neutral shape is a closed mouth, and the edge flows around the mouth in a continuous line to accurately fold and deform the expected mouth shapes.<br /><br />In this tutorial, we don't recommend modifying this area of the facial topography because of the risk of adversely affecting the underlying tongue, upper and lower jaw, and saved facial data. You can use a sculpting mask to ensure that this area is not affected by any modeling changes.</td>
</tr>
<tr>
<td>
<Tabs>
<TabItem label="Round">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Eyes-A.png" />
</TabItem>
<TabItem label = "Narrow">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Eyes-B.png" />
</TabItem></Tabs></td>
<td>**Eyes**: The eyelids have enough mesh lines on the eyelids to close the eyes. The continuous lines on the eyelids enable the eyelids to deform and fold as expected when blinking or widening. <br /><br />In this tutorial, it isn't recommended to modify this area of the facial topography because of the risk of adversely affecting the underlying eyeball meshes and saved facial data that contribute to accurate expressions. You can use a sculpting mask to ensure that this area is not affected by any modeling changes.</td>
</tr>
<tr>
<td>
<Tabs>
<TabItem label="Round">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Eyebrow-A.png" />
</TabItem>
<TabItem label = "Narrow">
<img src="../../../assets/art/avatar/basic-creation/Edge-Flow-Eyebrow-B.png" />
</TabItem></Tabs></td>
<td>**Eyelids and Eyebrows**: The eyelids and eyebrows require adequate space between the two regions.<br /><br />If modifying the topography above the eyes, keep in mind that the eyelids and eyebrows require a natural space between the two regions. Both the eyelids and eyebrows can shift and change positions with various facial expressions and, if improperly modeled, can clash into each other during a facial pose.</td>
</tr>
</tbody>
</table>
Not following edge flow concepts can result in the topology of your model conflicting with each other during animations, sometimes known as crashing.
<center>
<figure><img src="../../../assets/art/avatar/basic-creation/Sculpting-Crash-Example.png" width = "100%"/> <figcaption>In this example, the top of the eyelid and bottom eyelid travel past each other when closing causing jagged artifacts where the vertices collide and crash.</figcaption></figure>
</center>
By carefully sculpting your template mesh, you can avoid having to correct these topology collisions later, which can often require manually correcting rig, skinning, and/or facial animation data.

27
.cursor/rules/roblox/art/characters/creating/modeling-tips.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Modeling tips
description: Use these Blender modeling tips to expedite your character creation.
next: /art/characters/creating/sculpting
prev: /art/characters/creating/modeling-best-practices
---
There are many tips and tricks during the modeling process that can save you time and prevent major issues in your workflow. There are many resources online that can help you make your modeling process more efficient. The following are various beginner-friendly tips and settings in Blender that allow you to visualize and configure objects efficiently in your project.
### Hide inactive objects
In your Outliner, hide objects you aren't editing by enabling the **Hide In Viewport** icon <img src="../../../assets/art/blender-ui/Visibility-Icon.png" style={{marginBottom:"0px;"}} width="20px"/>. This cleans up your workspace and helps ensure you don't make unintentional changes to another object or collection.
You can quickly bulk hide and unhide any parent and child objects that are not [disabled](../../../art/characters/creating/index.md#disabled-objects). To bulk hide objects:
1. In the Outliner, navigate to a parent object, such as **Cage** or **Joints**.
2. Hold <kbd>Shift</kbd> and click the **Hide In Viewport** icon <img src="../../../assets/art/blender-ui/Visibility-Icon.png" style={{marginBottom:"0px;"}} width="20px"/> to toggle the object's visibility.
### Enable wireframe view
Whenever you use a modeling application, switch between different viewport options, like X-Ray and Wireframe, to gain a better perspective on your vertices and shapes. This tutorial uses a wireframe view over the mesh shape, and many examples use various material settings and viewport options.
Enable wireframes on your material view by setting the following:
1. Select the **Head_Geo**.
2. In the **Properties** panel, navigate to **Object Properties** <img src="../../../assets/art/blender-ui/Object-Select-Icon.png" style={{marginBottom:"0px;"}} width="20px"/>.
3. In Viewport Display, enable **Wireframe**.

26
.cursor/rules/roblox/art/characters/creating/remove-extra-bones.md Normal file
View file

@ -0,0 +1,26 @@
---
title: Remove extra bones
description: When creating characters in Blender, you must remove the extra head bones included in the template.
next: /art/characters/creating/verify-attachments
prev: /art/characters/creating/combine-head-geometry
---
The helper bones used to help place the head geometries also require removal to validate correctly. While these extra bones do not include any skinning data, do not delete any of the facial animation bones parented within DynamicHead, as these include important skinning data that drives facial animation.
<Alert severity = 'error'>
Failure to [combine head geometry](../../characters/creating/combine-head-geometry.md) and remove head bones will cause issues with validation, as the character will no longer adhere to the expected R15 geometry and joint hierarchy.
</Alert>
Remove the additional head bones by selecting them and deleting them in edit mode:
1. If required, toggle visibility on your **Armature** object. The bones display in the viewport.
2. In the Outliner, expand the character's armature object and find the **Joints** object that parents the bone structure of the character.
<img src="../../../assets/art/avatar/basic-creation/Select-Joint-Objects.png" />
3. Expand the Joints hierarchy by holding **shift** and clicking the expansion dropdown.
4. In the viewport, select any bone and switch to **Edit Mode**.
<img src="../../../assets/art/avatar/basic-creation/Select-Bone-Objects.png" />
5. Under the Head joint, hold **shift** and select all the head children joints except DynamicHead.
6. With the extra head bones selected, right click in the viewport and select **Delete Selected Bones**.
<video controls src="../../../assets/art/avatar/basic-creation/Cleanup_01-1.mp4" width="100%"></video>

57
.cursor/rules/roblox/art/characters/creating/sculpting.md Normal file
View file

@ -0,0 +1,57 @@
---
title: Sculpt the head
description: Use Blender's sculpting tools to make unique changes to the shape of your character.
next: /art/characters/creating/texturing-setup
prev: /art/characters/creating/modeling-tips
---
After reviewing the modeling best-practices and sculpting tips, you can begin sculpting your character. This tutorial demonstrates sculpting changes to the [RoundMale template](../../../assets/art/reference-files/RoundMale.zip), creating a goblin-like character.
The sculpting instructions utilize the following Sculpting tools:
- **Grab** - Selects and pulls a group of vertices.
- **Smooth** - Eliminates irregularities in the area of the brush's influence.
- **Flatten** - Averages out the vertices within the brush's influence on a common plane.
- **Elastic Deform** - Similar to Grab, but adds an organic stretch and elasticity to the neighboring vertices.
<Alert severity='info'>
You can use Blender's other sculpting tools, though it's important to use a tool that aligns with the [Non-Destructive Modeling](./modeling-best-practices.md#non-destructive-modeling) concepts to preserve the vertices of the model.
</Alert>
To begin sculpting the head:
1. With the template project opened, hide the other Geo objects to isolate the head mesh.
2. Select the **Head_Geo** mesh object and switch to **Sculpting** mode.
3. At the top right of the viewport, set the following options:
1. Enable **X-Axis Symmetry**.
2. Enable **Wireframe** view.
<video controls src="../../../assets/art/avatar/basic-creation/Sculpting_01.mp4" width="100%"></video>
4. Using the **Mask** tool, paint over the mouth and eyes where you do not want to sculpt unexpectedly.
<video controls muted src="../../../assets/art/avatar/basic-creation/Sculpting_02.mp4" width="100%"></video>
5. With the **Grab** and **Smooth** tools, make the following edits to your template head:
1. Reshape the head, flattening and enlarging the top.
2. Elongate the ears.
1. Expand the surface near the ear to broaden the base
2. Grab and extend each ear, ensuring it connects smoothly to the base and vertices remain proportionally spaced when possible.
3. Try the Flatten tool to straighten and align a region.
4. Use the Elastic Deform tool to stretch and pull multiple vertices.
<video controls muted src="../../../assets/art/avatar/basic-creation/Sculpting_03.mp4" width="100%"></video>
3. Extend the bridge of the nose and expand the size of the brow
<video controls src="../../../assets/art/avatar/basic-creation/Sculpting_04.mp4" width="100%" muted></video>
4. Broaden the chin so it prominently protrudes.
<video controls src="../../../assets/art/avatar/basic-creation/Sculpting_06.mp4" width="100%" muted></video>
6. Perform a refinement pass to add final details, polish, and accentuate your main features, such as:
- Adding details in the outer and inner ears
- Adding more detail to chin and cheeks
- Improving edge lines and spacing in areas with crowded vertices
<video controls src="../../../assets/art/avatar/basic-creation/Sculpting_07.mp4" width="100%"></video>
<Alert severity = 'success'>
For a comparison reference, you can download [this version of the tutorial project with sculpting completed](../../../assets/art/reference-files/checkpoint/1_Goblin-sculpted.blend).
</Alert>

109
.cursor/rules/roblox/art/characters/creating/template-files.md Normal file
View file

@ -0,0 +1,109 @@
---
title: Template files
description: Roblox provides template models to create your own unique avatar character in Blender.
next: /art/characters/creating/head-objects
prev: /art/characters/creating/
---
Each template comes pre-baked with the [necessary components of an avatar character](../../../art/characters/index.md#components-of-an-avatar) to save you time and effort in creating a custom avatar character. When creating characters from scratch, these individual components typically take a lot of time and a deep technical background in your modeling application. Templates allow you to skip several steps and work from a variety of base character shapes.
<table>
<thead>
<tr>
<th>Template prototype</th>
<th></th>
<th>Sample customizations</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<img src="../../../assets/art/avatar/templates/Muzzle-Prototype.png" /><br /><center>Muzzle head template</center>
</td>
<td>
</td>
<td>
<img src="../../../assets/art/avatar/templates/Muzzle-Concepts.png" /><br />
</td>
</tr>
<tr>
<td>
<img src="../../../assets/art/avatar/templates/Round-Prototype.png" /><br /><center>Round head template</center>
</td>
<td>
</td>
<td>
<img src="../../../assets/art/avatar/templates/Round-Concepts.png" /><br />
</td>
</tr>
</tbody>
</table>
You can choose from a variety of templates that best match your final design and save time on creating the technical components. The examples in the template tutorials utilize the [Round Blender template](../../../assets/art/reference-files/RoundMale.zip). Experiment with other templates to create your own unique character and final result.
Each `.zip` contains a `.blend`, `.fbx`, and PBR texture `.png` files for that template model. If using Blender or following the [template creation guides](../../../art/characters/creating/index.md), use the `.blend` project.
<Tabs>
<TabItem label="Head Shapes">
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Round-Head-Templates.png"/><figcaption><center>Round</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../../assets/art/reference-files/RoundFemale.zip">RoundFemale.zip</a> <br />
Male: <a href="../../../assets/art/reference-files/RoundMale.zip">RoundMale.zip</a>
</figure>
</GridContainer>
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Square-Head-Templates.png" /><figcaption><center>Square</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../../assets/art/reference-files/SquareFemale.zip">SquareFemale.zip</a> <br />
Male: <a href="../../../assets/art/reference-files/SquareMale.zip">SquareMale.zip</a>
</figure>
</GridContainer>
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Muzzle-Head-Templates.png" /><figcaption><center>Muzzle</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../../assets/art/reference-files/MuzzleFemale.zip">MuzzleFemale.zip</a> <br />
Male: <a href="../../../assets/art/reference-files/MuzzleMale.zip">MuzzleMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Realistic">
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/SemiRealistic-Templates.png"/><figcaption><center>Realistic</center></figcaption></figure>
<figure>
Female: <a href="../../../assets/art/reference-files/SemiRealisticFemale.zip">SemiRealisticFemale.zip</a> <br />
Male: <a href="../../../assets/art/reference-files/SemiRealisticMale.zip">SemiRealisticMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Anime">
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Anime-Templates.png"/><figcaption><center>Anime</center></figcaption></figure>
<figure>
Female: <a href="../../../assets/art/reference-files/AnimeFemale.zip">AnimeFemale.zip</a> <br />
Male: <a href="../../../assets/art/reference-files/AnimeMale.zip">AnimeMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Stylized">
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Stylized-Templates.png"/><figcaption><center>Stylized</center></figcaption></figure>
<figure>
Single body: <a href="../../../assets/art/reference-files/StylizedHuman.zip">Stylized.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Caricature">
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/templates/Caricature-Templates.png"/><figcaption><center>Caricature</center></figcaption></figure>
<figure>
Single body: <a href="../../../assets/art/reference-files/Caricature.zip">Caricature.zip</a>
</figure>
</GridContainer>
</TabItem>
</Tabs>
After downloading your template file, review the [unique head object structure](../../../art/characters/creating/head-objects.md) and [additional Blender settings](../../../art/characters/creating/blender-configurations.md) that require adjustment before exporting. It's crucial to understand these concepts prior to committing to any alterations as these can conflict with Roblox's avatar requirements if not addressed.

72
.cursor/rules/roblox/art/characters/creating/texturing-eyes.md Normal file
View file

@ -0,0 +1,72 @@
---
title: Texturing eyes
description: Use Blender's texture painting tools to apply a custom surface appearance on your character's eyes.
next: /art/characters/creating/texturing-face
prev: /art/characters/creating/texturing-setup
---
You can apply a fully opaque texture to the eyes to achieve a more non-human visual effect for your character. Before editing the eye textures, join the two eye objects to texture them both at the same time. Then texture paint the entire eye, starting with the outer eye, moving to the inner eye, and finishing with the pupil.
To texture your eye mesh objects:
1. Increase the texture image resolution.
2. In the Outliner, toggle the **Hide in Viewport** option for the **Head_Geo**, **LowerTeeth_Geo**, **Tongue_Geo**, and **UpperTeeth_Geo**. Leave the eye mesh objects visible.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_01.mp4" width="100%"></video>
3. In Object Mode, hold <kbd>Shift</kbd> and click on both the **LeftEye_Geo** and the **RightEye_Geo**. Then right-click and select **Join** (<kbd>Ctrl</kbd><kbd>J</kbd>; <kbd>⌘</kbd><kbd>J</kbd>) to join the objects. The two objects merge using the name of the last object selected.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_02.mp4" width="100%"></video>
4. Switch to **Texture Paint** mode.
5. With the Draw tool active, set the following brush settings for the outer eye shadow:
1. In Brush Settings, set **Radius** to **50px** and **Strength** to **1.0**.
2. In Color Picker, select **black**.
<img src="../../../assets/art/avatar/basic-creation/Texturing-Shadow-Settings.png" />
6. In the Texture Paint **3D view window**, completely paint the eye objects black. This serves as the basis for the outer-eye shadow.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_03.mp4" width="100%"></video>
7. With the Draw tool active, set the following brush settings for the outer eye shadow:
1. In Brush Settings, set **Radius** to **75px** and **Strength** to **1.0**.
2. In Color Picker, select a **deep yellow**.
<img src="../../../assets/art/avatar/basic-creation/Texturing-Outer-Brush-Settings.png" />
8. In the Texture Paint **2D view window**, line up your cursor to the center of the UV map that corresponds to the eye texture. Click 4-6 times on the center of each eye to create an outer eye color over the base shadow.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_04.mp4" width="100%"></video>
9. For visibility, enable Head_Geo visibility and reorient the camera to a front-facing view.
10. Paint the inner eye color using the following suggestions:
1. Click the **X Symmetry** button to enable symmetry. Toggle this off if creating asymmetrical assets.
<img src="../../../assets/art/avatar/basic-creation/Texturing-X-Symmetry.png" />
2. In the Overlay view options, **enable Wireframe geometry view**. You can toggle this overlay off when spot checking your visual elements.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_05.mp4" width="100%"></video>
<img src="../../../assets/art/avatar/basic-creation/Texturing-Wireframe-Toggle.png" />
3. Update your brush settings for the inner eye:
1. In Brush Settings, set **Radius** to **5px**. You can quickly change this radius as you paint by holding <kbd>F</kbd>.
2. In Color Picker, select a strong **red** shade for the inner eye.
<img src="../../../assets/art/avatar/basic-creation/Texturing-Inner-Eye.png" />
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_06.mp4" width="100%"></video>
4. Periodically make the head mesh visible to ensure your eye texture works with the rest of the model.
11. Update your brush settings for the pupil:
1. In Brush Settings, set Radius to **5px**. You can quickly change this radius as you paint by holding <kbd>F</kbd>.
2. In Color Picker, select a bright **red** shade for the pupils.
<img src="../../../assets/art/avatar/basic-creation/Texturing-Pupil-Brush-Settings.png" />
12. Using the Brush tool, paint the pupils of your model.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_07.mp4" width="100%"></video>
13. After completing your texture painting, switch back to **Edit Mode**.
14. Shift click both of your eye objects, and press <kbd>P</kbd> and select **By Loose Parts** to separate the two meshes.
15. Rename your remaining mesh to the original **RightEye_Geo** or **LeftEye_Geo** name.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_08.mp4" width="100%"></video>

48
.cursor/rules/roblox/art/characters/creating/texturing-face.md Normal file
View file

@ -0,0 +1,48 @@
---
title: Texturing face
description: Use Blender to apply a custom surface appearance on your character's face.
next: /art/characters/creating/texturing-pbr
prev: /art/characters/creating/texturing-eyes
---
After texturing the eyes, you can begin texturing the face. The concepts are similar to texturing the eyes, though you only use an opaque texture to ensure that the custom skin tone can remain visible.
To texture the face:
1. In the Texture Paint tab, resize your texture resolution to **2048** or **4098**:
1. In the left Paint window, select **Image** > **Resize**.
2. Set the texture size to **2048 x 2048**.
2. In the Tool sidebar, update your brush settings for the facial features.
1. In Brush Settings, start with the following Brush recommendations:
1. **Radius** to **5px**. You can change this radius as you paint.
2. **Strength** to **0.300**. Modify this value when applicable.
3. In Symmetry, enable **X Axis Mirroring**.
<img src="../../../assets/art/avatar/basic-creation/Texture-Symmetry-Tool-Setting.png" />
2. In Color Picker, select a neutral **dark** shade for the shadows.
3. Apply texture to your character's face features, such as the nostrils, wrinkles, ears, and chin. Keep in mind that the painted textures will look softer and blended with the surface once the texture resolution is resized.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_10.mp4" width="100%"></video>
4. When complete, resize your texture resolution back to **1024 x 1024**:
1. In the left Paint window, select **Image** > **Resize**.
2. Set the texture size back to **1024 x 1024**.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_11.mp4" width="100%"></video>
Your final result should include various facial textures that help accentuate the features of your character and work well with any custom skin tone. Try exploring various amounts of texturing and the types of surfaces you could expect on skin, such as wrinkles, scars, or dirt/grunge. You should also verify your textures between several skin tones to ensure that your texturing looks acceptable with various skin types.
<GridContainer numColumns="3">
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Texturing-A.png" /> <figcaption>Default Green</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Texturing-B.png" /><figcaption>Pink</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Texturing-C.png" /><figcaption>Blue</figcaption></figure>
</GridContainer>
<Alert severity = 'success'>
For a comparison reference, you can download [this version of the tutorial project with texturing completed](../../../assets/art/reference-files/checkpoint/2_Goblin-textured.blend).
</Alert>

16
.cursor/rules/roblox/art/characters/creating/texturing-pbr.md Normal file
View file

@ -0,0 +1,16 @@
---
title: PBR textures (optional)
description: PBR textures are high-definition texture maps that can elevate your custom characters.
next: /art/characters/creating/caging
prev: /art/characters/creating/texturing-face
---
Physically-based rendering (PBR) textures use multiple texture maps to define how a surface reacts under different lighting and environmental conditions. PBR textures can elevate the look and feel of your assets, including your avatar, accessories, and clothing. Typically, PBR textures are created in a texturing tool, such as [Substance 3D](https://www.adobe.com/products/substance3d-painter) or [ZBrush](https://www.maxon.net/en/zbrush). Many third-party 3D models available online include PBR textures.
<GridContainer numColumns="2">
<figure><img src="../../../assets/modeling/surface-appearance/Layered-Clothing-Example.png" /> <figcaption>Characters and accessories can make use of PBR textures to apply visual pop and material realism.</figcaption></figure>
<figure><img src="../../../assets/modeling/surface-appearance/Layered-Clothing-Example-2.jpg" /><figcaption>PBR textures allow for virtually any type of material surface, such as leather and denim.</figcaption></figure>
</GridContainer>
Although each template includes PBR textures, for the purpose of demonstrating the basic texturing process within Blender, this tutorial doesn't cover the PBR texturing process. For more information and references on advanced texturing, see [PBR textures](../../../art/modeling/surface-appearance.md).

44
.cursor/rules/roblox/art/characters/creating/texturing-setup.md Normal file
View file

@ -0,0 +1,44 @@
---
title: Texturing setup
description: Set up Blender to optimize your project for texturing the eyes and face of your template.
next: /art/characters/creating/texturing-eyes
prev: /art/characters/creating/sculpting
---
**Texturing** is the process of customizing the color, tone, and shading of your model's surface. Custom meshes and models use a 2D image, known as a texture map, to project various surface appearance elements onto your 3D object.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Pre-Texturing.png" /> <figcaption>Model after custom sculpting</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Texturing.png" /><figcaption>Model after texturing</figcaption></figure>
</GridContainer>
Each template comes with a color texture map, which you can alter and modify using Blender's texture editing tools. Since most Roblox avatars can take advantage of custom skin tones, it's important to understand how to [preview custom skin tones](../../../art/characters/creating/index.md#preview-skin-tones) in Blender to verify how your final asset will look in a Roblox experience.
For the purpose of demonstrating the basic texturing process, this tutorial goes over basic texture painting setup, applies a completely opaque texture over parts of the character eyes, and partially opaque details over the face. You can apply these same techniques to other parts of your character geometry.
<Alert severity = 'warning'>
When texturing parts of your character model's body, ensure that your character model includes a modesty layer over sensitive regions. See [Community Standards](../../../marketplace/marketplace-policy.md) for more information on Roblox's policies.
</Alert>
## Set texture resolution
Roblox Studio supports a texture resolution of **1024 x 1024** for albedo texture maps. When using applications like Blender or Maya to texture paint directly on a model, extremely fine details may not paint as expected due to the resolution and level of detail of the painting.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Texture-Resolution-A.png" /> <figcaption>Texture painting at 1024 x 1024 resolution</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Texture-Resolution-B.png" /><figcaption>Texture painting at 2048 x 2048 resolution</figcaption></figure>
</GridContainer>
When adding fine details to your texture, increase the image resolution of your texture map temporarily to **2048 x 2048** or **4096 x 4096**. After completing your texturing, change the image resolution back to **1024 x 1024** to bake in the changes.
To change your texture image resolution:
1. Starting from Layout mode, select the **Head_Geo**.
2. Switch to **Texture Paint** mode.
3. In the left Paint window, select **Image** > **Resize**.
4. Set the texture size:
1. Use **2048** or **4096** for a higher res for detailed texture work.
2. Use **1024** for the default Roblox-supported resolution.
<video controls src="../../../assets/art/avatar/basic-creation/Texturing_09.mp4" width="100%"></video>

30
.cursor/rules/roblox/art/characters/creating/verify-attachments.md Normal file
View file

@ -0,0 +1,30 @@
---
title: Verify attachment placement
description: When creating characters in Blender, the character model requires minor attachment adjustments to be Studio-ready.
next: /art/characters/creating/final-checks
prev: /art/characters/creating/remove-extra-bones
---
Attachment points are non-rendered objects of your avatar where rigid accessories attach to. Each template includes the required attachments at their expected locations ending with **\_Att**. Before exporting, it's important to verify the attachment position and, if necessary, adjust the location if you made any changes to the shape of your model.
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Pre-Attachment.png" /> <figcaption>Original template attachment positions</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Post-Attachment.png" /><figcaption>Attachments after adjustment</figcaption></figure>
</GridContainer>
Center attachment points at their respective locations. Each attachment should overlap approximately halfway with the character's mesh.
This tutorial only changes the head of your model, so you only need to adjust the **Hat**, **Hair** and **FaceFront** attachments. To enable visibility and verify your head attachment point:
1. If you haven't already, enable [disabled objects](../../../art/characters/creating/index.md#disabled-objects) in your Outliner.
2. In the Outliner, find the Joints parent object.
3. Hold <kbd>Shift</kbd> and click the **Hide** icon for the Joints object to hide everything.
4. Expand the Joints object and un-hide the Head_Geo and Hat_Att and Hair_Att.
1. If required, disable **Disable In Viewport** <img src="../../../assets/art/blender-ui/Disabled-Icon.png" style={{marginBottom:"0px;"}} width="20px"/> next to the \_Att objects.
5. Toggle Visibility for the **Hat_Att**, **Hair_Att**, and **FaceFront_Att**.
6. Verify the placement of the attachments. The goblin's head is shorter than the starting template, so the attachments require minor vertical adjustment.
7. Select the attachments
8. Switch to **Edit** Mode.
9. Using the Grab tool, position the attachments vertically along the y-axis until they are about halfway embedded in the head.
<video controls muted src="../../../assets/art/avatar/basic-creation/Cleanup_02.mp4" width="100%"></video>

152
.cursor/rules/roblox/art/characters/export-avatar-animations-from-maya.md Normal file
View file

@ -0,0 +1,152 @@
---
title: Export avatar animations from Maya
description: Explains the process for exporting avatar animations from Maya.
---
**Avatar animations** are animations that you can create and assign to play for any avatar action, such as walking, swimming, or dancing. In addition to using the [Animation Editor](../../animation/editor.md) or [Animation Capture](../../animation/capture.md) tools within Studio, you can create avatar animations through third-party modeling and animation tools like [Maya](https://www.autodesk.com/products/maya/overview), then import your avatar animations directly into Studio to apply to any avatar with Roblox. By using this guide as a checklist of the specific settings your rig and animation must meet for the export process, you can ensure that your animations import successfully.
<GridContainer numColumns="2">
<figure>
<img width="40%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Overview-Mannequin.jpg" alt="A humanoid mannequin in Maya with IK controls." />
<figcaption>R15 mannequin reference</figcaption>
</figure>
<figure>
<video controls src="../../assets/animation/exporting-avatar-animations-from-maya/Moving-Rig.mp4" alt="An angled side view of the same humanoid mannequin walking in place." width="40%"></video>
<figcaption>Example walking animation</figcaption>
</figure>
</GridContainer>
<Alert severity="info">
This guide uses a downloadable [R15-Mannequin-Rig.ma](../../assets/animation/exporting-avatar-animations-from-maya/R15-Mannequin-Rig.ma) file that contains an R15 mannequin that you can use as a reference to create and export animations. If you choose to animate on your own R15 rig, the same rig configuration and export settings apply.
</Alert>
## Configure the rig
Before you export your avatar animation from Maya, you must configure your rig to be compatible with Studio's import requirements, including making sure that the rig follows a specific hierarchy and naming conventions so that Studio is able to recognize the file as an avatar animation, and that the rig's translation channel is muted so that the root node doesn't move with the animation.
### Hierarchy and naming conventions
Studio requires a specific hierarchy and naming conventions for a humanoid rig's internal joint structure so that it can recognize what you're importing as an avatar animation. If you aren't using the downloadable R15 mannequin reference rig to create your animations, make sure your rig uses the following joint hierarchy and naming convention exactly as it is:
- Root
- HumanoidRootPart
- LowerTorso
- UpperTorso
- Head (representing the base of the neck)
- LeftUpperArm
- LeftLowerArm
- LeftHand
- RightUpperArm
- RightLowerArm
- RightHand
- LeftUpperLeg
- LeftLowerLeg
- LeftFoot
- RightUpperLeg
- RightLowerLeg
- RightFoot
### Mute the translation channel
Roblox avatar animations cannot move a character when they play; instead, avatar animations animate rigs at their world position. If your avatar animation is a locomotion-type of animation where the root node moves in space, such as a character that moves forward as their walk animation plays, you must mute the rig's translation channel so that the animation plays without moving the rig on export.
To mute the translation channel:
1. Open the **Graph Editor**.
1. In the menu bar, click **Windows**. A contextual menu displays.
1. Hover over **Workspaces**, then click **Animation**. The **Graph Editor** displays.
<img width="90%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Opening-GraphEditor-and-TimeSlider.jpg" alt="A close up view of the Windows dropdown menu in Maya. The Workspaces menu item is highlighted, as well as the Animation submenu." />
1. Move the **Time Marker** to frame 0.
<img width="50%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Time-Marker.jpg" alt="A close up view of the Graph Editor in Maya. The Time marker for a character's right hand is at frame 0, and is highlighted." />
1. In the **Outliner**, select the root node. If you are using the reference file, this is **TSM3_root**.
1. In the **Channel Box**, right-click on the **Translate Z** value. A contextual menu displays.
1. Select **Mute Selected**. The Translate Z value's channel box color changes to orange to confirm that it's muted.
<GridContainer numColumns="2">
<figure>
<img width="90%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Mute-Selected.jpg" alt="A close up view of the Channel Box in Maya. The Mute Selected menu item in the contextual menu from step 4 is highlighted." />
</figure>
<figure>
<img width="90%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Muted-TranslateZ.jpg" alt="A close up view of the Channel Box in Maya. The Translate Z property channel box color is orange to signify it is muted. The rest of the values are in cyan blue to signify that they remain unmuted." />
</figure>
</GridContainer>
When you play the animation, the character's root node doesn't move in space anymore, and the character animates in place at the origin of the scene.
## Export the animation
Now that your rig animates in place and has a hierarchy and naming data that is compatible with Studio, you can export the animation into a `.fbx` format. Maya doesn't load this capability by default, so you need to enable an FBX plugin to gain the additional settings necessary to export the file in a format Studio can recognize.
To export your avatar animation from Maya:
1. Install the FBX plugin.
1. In the menu bar, click **Windows**. A contextual menu displays.
1. Hover over **Settings/Preferences**, then click **Plug-in Manager**. The **Plug-in Manager** window displays.
<img width="80%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Plugin-Manager.jpg" alt="A close up view of the Windows dropdown menu in Maya. The Settings/Preferences menu item is highlighted, as well as the Plug-in Manager submenu." />
1. In the search field, input **fbxmaya**. The **fbxmaya.mll** plugin displays.
1. Enable the **Loaded** and **Auto load** options.
<img width="80%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Loaded-and-AutoLoad-Radio-Buttons.jpg" alt="The Plug-in Manager with a close up view of the fbxmaya file. Its Loaded and Auto load settings are highlighted." />
1. In the menu bar, click **File**. A contextual menu displays.
1. Select **Export All**. The **Export All** window displays.
<img width="40%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Export-All.png" alt="A close up view of the File dropdown menu in Maya. The Export All menu item is highlighted." />
1. At the bottom of the window,
1. In the **File name** field, input a name for your avatar animation.
1. Click the **Files of Type** dropdown menu, then select **FBX export**. The **Options pane** updates its settings.
1. In the **Options** pane, click the **Animation** dropdown for additional animation settings, then in the **Bake Animation** section,
1. Enable **Bake Animation**.
1. Verify that the **Start** and **End** fields correlate to the frames you want to export for your animation loop.
1. Set **Step** to **1**.
<img width="80%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Bake-Animation.jpg" alt="A close up view of the Options pane. The Bake Animation settings are highlighted." />
1. Click the **Advanced Options** dropdown for additional export settings, then in the **FBX File Format** section,
1. Set **Type** to **Binary**.
1. If required, set **Version** to **FBX 2020**.
<img width="80%" img src="../../assets/animation/exporting-avatar-animations-from-maya/FBX-File-Format.jpg" alt="A close up view of the Options pane. The FBX File Format settings are highlighted." />
1. In the bottom right corner, click the **Export All** button. After a moment, the avatar animation `.fbx` file displays in your file browser.
## Test the animation in Studio
Once you have your avatar animation `.fbx` file, you can test it within Studio to make sure that the animation plays without any errors.
To test the animation in Studio:
1. Open a pre-built character rig.
1. From the toolbar's **Avatar** tab, click **Character**.
1. Select any rig you want to use as a test. The rig displays within the viewport.
1. Connect the rig to the **Animation Editor**.
1. From the toolbar's **Avatar** tab, click **Animation**. The [Animation Editor](../../animation/editor.md) window displays.
1. In the viewport, click your rig. A dialog displays in the editor.
1. In the **Animation Name** field, enter a new animation name, then click the **Create** button. The editor window displays the media and playback controls, timeline, and track list.
1. Import your avatar animation into the rig.
1. Navigate to the **Media and Playback Controls** and click the **&ctdot;** button. A contextual menu displays.
1. Hover over **Import**, then select **From FBX Animation**. A file browser displays.
<img width="60%" img src="../../assets/animation/exporting-avatar-animations-from-maya/Importing-From-FBX-Animation.jpg" alt="A close up view of the Animation Editor window. The ellipsis contextual menu displays, and the From FBX Animation submenu item is highlighted." />
1. Select the FBX animation you just exported from Maya, then click **Open**. The animation's keyframes load into the **Animation Editor**.
1. Navigate to the **Media and Playback Controls** and click the **Play button** to play the avatar animation.

101
.cursor/rules/roblox/art/characters/export-settings.md Normal file
View file

@ -0,0 +1,101 @@
---
title: Character body export settings
description: Use the appropriate export settings in Maya and Blender to generate Studio-ready .fbx files.
---
<Alert severity = 'warning'>
It's important to test your assets multiple times at every point of the asset creation process, whether it is within your modeling application or after importing into Studio. See [Test characters](../../art/characters/testing/index.md) for more information.
</Alert>
Export your model as a `.fbx` or `.gltf` to take advantage of all of Studio's 3D import features. When rigging or skinning a layerable model, these file types contains all the mesh and texture data, including the rig and influence data, you need to later [import](../../art/modeling/3d-importer.md) into Studio.
Check that your model meets Roblox's [avatar character specifications](../../art/characters/specifications.md) before exporting to ensure Studio compatibility.
<Alert severity = 'warning'>
<AlertTitle>If creating other types of 3D models:</AlertTitle>
<ul>
<li>For generic meshes, see [general mesh specifications](../modeling/specifications.md) and [general export settings](../modeling/export-requirements.md).</li> <br />
<li>For rigid accessories, see [accessory specifications](../accessories/specifications.md) and [accessory export settings](../accessories/export-settings.md).</li> <br />
<li>For layered accessories, see [layered accessory specifications](../accessories/clothing-specifications.md) and [layered export settings](../accessories/clothing-export-settings.md).</li> <br />
</ul>
</Alert>
<Alert severity = 'error'>
If you are using Roblox's avatar template files, you must perform the [cleanup steps](../../art/characters/creating/combine-head-geometry.md) in order for the assets to properly validate.
</Alert>
## Before exporting
Before exporting, ensure that you are only exporting the Roblox supported objects related to your model. If you have any modifiers to your mesh or project objects, make sure to apply or delete them before export.
Use the following guidance before exporting:
- While your mesh objects must be parented within an armature object, you can also parent your outer cage objects to a single empty object to simplify your workspace.
<img src="../../assets/art/avatar/Character-Data-Model-Collapsed.png" width = "60%" alt="Screenshot of a Blender project Outliner with parent objects collapsed." />
- In the cage parent object, ensure you have an [outer cage](../characters/specifications.md#outer-cages) for each of your 15 body parts with appropriate naming affix.
<img src="../../assets/art/avatar/Character-Data-Model-Cages.png" width = "60%" alt="Screenshot of the 15 outer cage meshes that you must include with a character export."/>
- In the armature object, ensure that you include the all [15 mesh objects](../characters/specifications.md#body-parts) and [19 attachments](../characters/specifications.md#attachments) with the appropriate naming affix.
<img src="../../assets/art/avatar/Character-Data-Model-Joints.png" width = "60%" alt="Screenshot of 15 child objects parented within an Armature object."/>
<Alert severity = 'info'>
For more information on supported modeling objects and proper configuration, see [Character specifications](../characters/specifications.md).
</Alert>
- When exporting characters with animation or FACS animation, ensure that your animation timeline **Start** and **End** include the entire range of your animations.
<img src="../../assets/art/avatar/basic-creation/Blender-Animation-Start-End.png" width = "60%" alt="Zoom-in of Blender animation track indicating a Start value of 0 and End value of 308." />
## Blender
Blender allows you to export in `.fbx` or `.gltf` as well as other formats. If you are using `.fbx` export, familiarize yourself with [Blender's FBX scaling](../blender.md#adjust-scale-fbx) to ensure that you successfully import the model into Studio at the correct scale.
### Export settings
1. In the topbar, click **File** > **Export** > **FBX (.fbx)**. The Blender file browser window displays.
2. Set **Path Mode** to **Copy** and enable the **Embed Textures** icon.
3. In the Include section, enable **Custom Properties**.
4. If your project doesn't already have `.01` scene unit scaling, set the **Transform** > **Apply Scalings** to `FBX Unit Scale`. For more details, see [Blender FBX scaling](../blender.md#adjust-scale-fbx).
5. Expand the Armature section and uncheck **Add Leaf Bones**.
6. Enable **Bake Animation**.
7. Expand Bake Animation and **uncheck NLA Strips**, **All Actions**, and **Force Start/End Keyframes**.
1. Ensure your project animation timeline has the correct **Start** and **End** range of all your keyframes.
8. In Bake Animation, set **Simplify** to **0.0**.
9. Click the **Export FBX** button. Save the `.fbx` to the directory of your choice.
<img src="../../assets/art/avatar/basic-creation/Export-Settings.png" width = "50%" alt="Screenshot of Blender export settings" />
## Maya export settings
To export a mesh in Maya as a `.fbx` file:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Export All**. The **Export All** window displays.
3. Near the bottom of the window, click the **Files of type** dropdown, then select **FBX export**.
4. On the right-hand side of the window, navigate to the **Options...** section.
5. In the **Geometry** section, enable **Smooth Mesh** and **Referenced Asset Content**.
6. In the **Animation** section, enable **Animation**. Avatar characters with [facial animation data](../../art/characters/facial-animation/index.md) require animation data.
7. Enable **Bake Animation**.
8. If you need to import textures as a `.png`, in the **Embed Media** section, enable **Embed Media**.
9. In the **Advanced Options** section,
- Navigate to **Units**, then enable **Automatic**.
- Navigate to **Axis Conversion**, then set the **Up Axis** property to **Y**.
10. Click the **Export All** button.
<img src="../../assets/accessories/lc-requirements-maya-settings-with-animation.png" alt = "Screenshot of Maya export settings for exports with animation."/>
11. After exporting, use Studio's [3D importer](../../art/modeling/3d-importer.md) to import your model. See [Test characters in Studio](../../art/characters/testing/studio.md) for additional importing and testing information.
<Alert severity = 'success'>
After importing the `Class.Model` character to Studio, you can now perform the following with this asset:
- [Test your character model](../../art/characters/testing/index.md) in Studio using various tools and workflows.
- [Upload the character](../../art/accessories/creating-rigid/publishing.md) to the Marketplace.
- Use the humanoid character on an existing experience by applying a [HumanoidDescription](../../characters/appearance.md#manually-modify-appearance)to the `Class.Model` object.
- Save the asset to your [Toolbox](../../projects/assets/toolbox.md) to share or use within any of your experiences.
</Alert>

102
.cursor/rules/roblox/art/characters/facial-animation/animate-heads.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Animate heads
description: You can create facial animations for a character with live heads using the Animation Editor.
---
You can use the [Animation Editor](../../../animation/editor.md) to animate supported heads in the following ways:
- You can manually set values to each facial pose on separate [animation tracks](#use-animation-tracks).
- You can use the [Face Animation Editor](#use-the-face-animation-editor) to access facial sliders that let you quickly create and save unique expressions on the timeline.
- You can use the [Animation Capture for Faces](../../../animation/capture.md#face) extension to automatically track and record facial movements with a webcam that converts your movement into keyframes on the timeline.
In all methods, creating and combining multiple facial expressions over a duration of time results in a face animation. Since you cannot import face animations, these methods are the only ways to create and utilize them.
After you create and publish a head that supports facial animation to Roblox, you can play the animation from a script or replace a character's default animation with your new animation. These animations can make your characters feel more expressive and full of life, such as playing a silly expression when a character walks, or an annoyed expression when a character is idle.
<img src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/Overview.png" alt="A view of Studio where the Face Animation Editor, Animation Editor, and viewport are visible. The viewport shows a close up view of a blocky male avatar blinking with his left eye." width="80%" />
## Create animations
After you have [opened](../../../animation/editor.md#open-the-animation-editor) the **Animation Editor** and selected the character model with a head you want to create an animation for, you can either create a head animation by using animation tracks or the **Face Animation Editor**.
For details on using Animation Capture to track facial movement as keyframes, see [Animation Capture - Face](../../../animation/capture.md#face).
### Use animation tracks
Similar to inserting other objects like `Class.MeshPart|MeshParts` or `Class.Bone|Bones` as animation tracks, you can manually add one FACS value at a time to the track list to manipulate a single body part, such as the character's eyes, jaw, or tongue. The [Animation Editor](../../../animation/editor.md) represents FACS values as a percentage between 0 and 1, and these values map directly to `Class.FaceControls` values. While this process provides precise control over individual values, the [Face Animation Editor](#use-the-face-animation-editor) enhances this workflow and lets you quickly change values to multiple facial features at once on the animation timeline.
To create an animation by inserting individual FACS values:
1. In the **track list** of the **Animation Editor**, click the **plus icon**. A contextual menu displays additional tracks you can add to the track list.
2. Hover over **Brows**, **Eyes**, **Jaw**, **Mouth**, or **Tongue**. A contextual menu displays all mapped FACS poses for that region of the face.
<img src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/FACS-Popup.jpg" alt="A close up view of the Animation Editor with the contextual menu and its submenu expanded. The plus icon is highlighted to signify how to open the contextual menu." width="60%" />
3. Select a FACS pose. An animation track for that FACS pose displays in the track list.
4. In the values input, enter a number between **0** and **1** to manipulate the body part into a new position. For example, if you change `LeftEyeClosed` to 1, the character's left eye closes.
<img src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/Animation-Track-Values-Input.jpg" alt="A close up view of the track list in the Animation Editor. The values input is highlighted." width="60%" />
### Use the Face Animation Editor
The **Face Animation Editor** is an intuitive, visual way to automatically create keyframes as you adjust **sliders** to achieve your desired facial expression. For example, when you drag the thumb of the `LeftEyeClosed` slider all the way down, the character's left eye closes and a new animation track for `LeftEyeClosed` displays with a value of `1` within the track list.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/videos/1-Face-Controls-Example.mp4">
</video>
Some sliders affect multiple FACS values in the same region depending on the value of the slider you are adjusting. For example, when you adjust the thumb of the `LeftEyeClosed` slider all the way up to have a value of `0`, a new animation track for `LeftEyeUpperLidRaiser` displays in the track list with a value of `1`. This allows you to manipulate the eye from closed to open, while also raising the upper lid of the eye, all within a single slider.
You can set multiple sliders to create a complete face expression, then create multiple expressions at different frames of the timeline to create complex animations. For example, you can combine `LeftEyeClosed` and `RightEyeClosed` together to have the character slowly blink, or `LeftLipCornerPuller` or `RightLipCornerPuller` for a smile on one side of the face.
When you click and drag the thumb of the drag box between the eyes, you can control the direction the character's eyes look at. This creates several FACS property tracks in the track list depending on how you adjust the eyes.
At the bottom-left of the panel, the **Face Animation Editor** also includes the following controls:
<table>
<thead>
<tr>
<th>Control</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Symmetry Toggle</td>
<td>Lets you use a slider on one side of the face to also adjust the corresponding slider on the other side of the face to the same value. This is useful to create symmetric facial expressions, such as a full smile.</td>
</tr>
<tr>
<td>Focus Face Toggle</td>
<td>Focuses the viewport on the face of the avatar without having to manually adjust the camera. This is useful when your camera is either far away from the avatar you want to animate, or if you are navigating from animating one avatar to another.</td>
</tr>
<tr>
<td>Reset All Button</td>
<td>Resets all FACS pose values at your current frame position back to their default value of 0. This is useful when you want to quickly reanimate a single frame.</td>
</tr>
</tbody>
</table>
To create an animation for your head using the **Face Animation Editor**:
1. In the **track list** of the **Animation Editor**, click the **Face** button. The **Face Animation Editor** displays to the left of the track list.
<img src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/Face-Button.jpg" alt="A close up view of the track list in the Animation Editor. The Face button is highlighted." width="50%" />
2. In the **Face Animation Editor**, adjust sliders for the body parts you want to manipulate. Animation tracks for each facial part you manipulate automatically display in the track list along with keyframes for your current position in the timeline. The character's face also updates in the viewport.
- To undo a step on a slider, press <kbd>Ctrl</kbd><kbd>Z</kbd> (<kbd>⌘</kbd><kbd>Z</kbd>).
- To redo a step on a slider, press <kbd>Ctrl</kbd><kbd>Y</kbd> (<kbd>⌘</kbd><kbd>Y</kbd>).
- To reset a slider to its default value, right click on the slider. A contextual menu displays. Select **Reset Selected**.
3. (Optional) Adjust the scrubber to a new position further along the timeline, then navigate back to the **Face Animation Editor** and adjust sliders to create a new facial expression. When you play the animation, the first facial expression will ease into the second facial expression.
4. When you are finished creating your animation, navigate to the **Media and Playback Controls** and click the **…** button. A pop-up menu displays.
5. Select **Save** or **Save As** to save the animation. The animation displays in the **Explorer** window as a child of the **AnimSaves** object (itself a child of the rig).
## Export animations
When you export a head that supports animation to Studio, it becomes available for use in all of your experiences. This means that you only need to create a head animation once, then you can reuse it as many times for as many characters as you want as long as the character has an [animatable head](../../../art/characters/facial-animation/use-heads-in-studio.md).
You can export head animations using the same workflow outlined for [exporting animations](../../../animation/editor.md#export-an-animation).
## Script animations
Once you have created an animation, you need to use a script to play it in your experience. Like generic animations, you can either play animations for heads manually from your scripts or automatically by replacing default animations for player characters. For more information, see [Use animations](../../../animation/using.md).

463
.cursor/rules/roblox/art/characters/facial-animation/create-basic-heads.md Normal file
View file

@ -0,0 +1,463 @@
---
title: Create basic heads
description: The process of creating a basic animatable head in Blender.
---
<Alert severity="warning">
<b>This guide covers advanced topics.</b> Before you begin, you should have prior knowledge on modeling, UV mapping, rigging, animation, and how to set up a character in [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
</Alert>
You can create or modify an existing model to support animated heads in a third-party modeling software, such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview). When creating a head, your character model must meet the following requirements:
- The model follows standard [modeling requirements](#modeling-requirements), and includes head geometry, such as eyes, a mouth, and teeth.
- The model's head must include a [rig](#rigging), or internal bone structure. These bones drive the various deformation of vertices to create facial expressions. You can create a [control system](#add-controls) to simplify the posing process.
- The model has facial poses [saved to the animation timeline](#pose) and [mapped to the head mesh](#map). Typical animatable heads include [50 standard base poses](../../../art/characters/facial-animation/facs-poses-reference.md) that allow for a diverse range of expressions.
To meet these requirements, you can apply the steps in this guide when designing and posing your own head. This guide covers the basic processes of adding facial bones, posing, and mapping 5 basic FACS poses in Blender on a simplified reference character (Cubie), then exporting the model.
<Alert severity="info">
For reference, this guide uses <a href="https://www.blender.org/download/releases/3-0/">Blender version 3.0</a>. If you are using another version of Blender, there might be minor differences in UI and settings.
</Alert>
## Reference files
The following are head reference files, including all example files from this guide:
<Alert severity = 'warning'>
The reference character model provided is meant for educational purposes and does not meet the avatar character [technical specifications](../../../art/characters/specifications.md) for general use.
</Alert>
<table>
<thead>
<tr>
<th>Reference files</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[Cubie-Model-Only.blend](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Model-Only.blend)</td>
<td>A Blender project file containing a R15 Cubie character model without facial data. </td>
</tr>
<tr>
<td>[Cubie-Eye-Bones-Skinned.blend](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Eye-Bones-Skinned.blend)</td>
<td>A Blender project file containing the example Cubie character model with skinned eye bones without posing or mapping data.</td>
</tr>
<tr>
<td>[Cubie-Eye-Poses-Mapped.blend](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Eye-Poses-Mapped.blend)</td>
<td>A Blender project file containing the Cubie character model with the 5 example poses saved and mapped.</td>
</tr>
<tr>
<td>[Cubie-Complete.fbx](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.fbx)</td>
<td>A Cubie character model with a fully rigged face and over 50 poses saved and mapped. You can import this file into Studio, or open the file in your preferred 3D modeling software.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie_Head_ALB.png" download>Cubie-Texture_ALB.png</a></td>
<td>A Cubie texture image file. After you import the Cubie model into Studio, you can add this file as the head part's <b>TextureID</b>.</td>
</tr>
<tr>
<td>[Cubie-Complete.ma](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.ma)</td>
<td>A Cubie Maya project provided as additional reference. </td>
</tr>
</tbody>
</table>
## Modeling requirements
Many character models already include a head with distinct facial features, but they might require minor modeling adjustments for head compatibility. When modeling a character with a head, ensure the head mesh meets the [Avatar character specifications](../../../art/characters/specifications.md) for Studio import, as well as the following requirements:
- **Face parts** - Ensure that you include distinct face features, such as eyes, upper teeth, lower teeth, and a tongue.
- **Lip vertices** - If you want your character to use its mouth, separate the lip vertices so that the mouth can open.
- **Inner components** - If your character has inner mouth components, such as a tongue and teeth, model a mouth bag within the head mesh to contain these features. If your character uses eye sockets, model a similar eye bag to contain these features.
- **No extra data** - Ensure that all children face parts of the Head_Geo don't contain history or frozen transformations.
- **Outer cage** - Make sure the character model has an outer cage to support face accessories and layered clothing. For more information, see [Cage Mesh Requirements](../../../art/characters/specifications.md#inner-and-outer-cages).
You can follow along the rest of this head creation process using a [rigged Cubie character](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Model-Only.blend) that meets these modeling requirements. This version doesn't include any facial rigging or pose data so you can use it as reference in this guide.
## Rigging
Your character must have an internal bone structure to drive the vertices of the face geometry and make facial poses. Unlike [rigging a humanoid model](../../../art/modeling/rig-a-humanoid-model.md), Studio doesn't require a specific bone hierarchy for a head. However, in order for the facial rig to work properly, the rig must include a [RootFaceJoint](#rootfacejoint) bone and [additional face bones](#face-bones).
### RootFaceJoint
The **RootFaceJoint** is a bone that is parented under the standard R15 head bone. This root bone must parent all other face bones. In Blender, you can quickly add a bone by **extruding** a child bone from the head bone and then map the bone name as a property in the Head_Geo mesh. The RootFaceJoint bone object is commonly named "DynamicHead" in the reference templates and examples, but you can use any name as long as you [map the root bone](#map) in custom properties.
To add a RootFaceJoint bone:
1. In Blender, open the **Cubie-Model-Only.blend** project.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Open-Project.png" width="70%" />
2. Click on any bones to select the armature, then switch to **Edit Mode**.
3. In the **Outliner**, click on the **Head** bone.
4. In the **Viewport**, press <kbd>E</kbd> and drag your mouse up to extrude an additional child bone from the **Head** bone.
5. In the **Outliner**, rename this bone **DynamicHead**. You will reference this bone by name later in the [mapping](#map) section.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/1_Adding_RootFaceJoint.mp4">
</video>
<Alert severity="warning">
You must <a href="#map">map</a> the RootFaceJoint so Studio can properly locate that joint and hide all of the children joints and their bones within the `Class.FaceControls` instance on import.
</Alert>
### Face bones
Face bones drive the bending and deformation of the face geometry. Each poseable face feature of your head typically requires at least one bone. Complex features, such as eyes and mouth, might require several bones to make certain poses possible.
The rigging and skinning process depends on the character model and differs between tools and modelers. It's important to plan out the full range of facial poses your character requires to avoid additional adjustments to your head bones later.
The following instructions describe a basic process of [adding face bones](#add-face-bones) and [skinning](#skin-face-bones), or applying influences, to the reference model's **eyes** and **eyelids**. You can continue to apply this technique to the rest of the facial features that need articulation, such as the character's mouth, cheeks, and jaw. After adding your bones and applying influences, you can create [controls](#add-controls) that can help make the next posing process more efficient.
<Alert severity="info">
You can download a [reference Cubie model](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.fbx) with a completed rig with 30+ facial bones added and skinned. You can use this for a reference for unique bone placements not covered in this guide, such as cheeks, lips, and jaws.
See [Use heads in Studio](../../../art/characters/facial-animation/use-heads-in-studio.md) for download links of more complex characters.
</Alert>
#### Add face bones
The specific head bones your character requires depend on the poses you intend for it to use. The following examples cover the process for adding 1 bone for each eye and 4 bones for the eyelids to allow for blinking, winking, and gaze direction.
When creating a face rig, use less than 50 face bones where possible and keep the bones organized and specific for their associated facial features. In general, high numbers of vertices and joints can impact your experience's performance.
##### Eyes
Each eye requires one bone each, though you might opt to create a controller bone later that can control both eyes at the same time. To ensure that you position your bones symmetrically, you can enable **X-Axis Mirror** in the top-right of the Viewport. This moves bones that share the same name with opposing suffixes along the X-axis.
To add bones to the character eyes:
1. In **Object Mode**, select the **armature** and switch to **Edit Mode**.
2. Click **Add**, then **Single Bone**. Do this twice.
3. Rename one bone **LeftEye**, and rename the other **RightEye**.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/3_Adding_Eye_Bones.mp4">
</video>
4. Enable **X-Axis Mirror**.
5. Position the left or right bone centered at the model's eyes.
6. Adjust the bones horizontally and front-facing. A quick method for setting bones horizontally:
1. In the top right of the **Viewport**, extend the **Tool Panel** to the **Transform** section.
2. With the bones selected, copy the **Head Y** location to the **Tail Y** location.
3. Set the **Tail Z** to **0.2** centimeters. This sets the Tail Z coordinates 0.2 centimeters offset from the Head Z coordinates.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/4_Positioning_Eye_Bones.mp4">
</video>
7. Hold <kbd>Shift</kbd> and click both **Eye** bones.
8. While still holding <kbd>Shift</kbd>, click the **Face** bone.
9. Right-click in the viewport. A contextual menu displays.
10. Select **Parent**, **Make**, then **With Offset**.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/5_Parenting_Eye_Bones.mp4">
</video>
##### Eyelids
When adding bones, you can quickly create bones parented under the Face bone by selecting existing facial bones and duplicating them. This automatically creates bones parented under the Face bone.
To add bones to the character eyelids:
1. In **Edit Mode**, hold <kbd>Shift</kbd> and click both **eye bones** to select them.
2. Press <kbd>Shift</kbd><kbd>D</kbd> and click to duplicate the bones in the same position. Do this four times to create 8 total new bones.
3. With **X-Axis mirror enabled**, position each bone at the corners of the eyes.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/6_Adding_And_Positioning_Eyelids.mp4">
</video>
4. In the **Outliner**, rename all bones to reflect their specific position. Use the following names:
1. LeftUpperOuterEyelid
2. RightUpperOuterEyelid
3. LeftLowerOuterEyelid
4. RightLowerOuterEyelid
5. LeftUpperInnerEyelid
6. RightUpperInnerEyelid
7. LeftLowerInnerEyelid
8. RightLowerInnerEyelid
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Eyelid-Naming.png" width="70%" />
#### Skin face bones
You can apply [skinning](../../../art/modeling/rigging.md) to a character rig using several methods. The following example uses Blender's **Weight Paint** mode to paint which vertices a single bone can control. Skinning is typically a time consuming step for complex characters and a background in skinning and facial posing is recommended.
When applying detailed or shared influences for complex models, it's recommended to enable [Auto Normalize](../../../art/modeling/skin-a-simple-mesh.md#auto-normalize) to prevent influence conflicts between bones.
<Alert severity="info">
When parenting bones to the character using <b>Automatic Weights</b>, some of your vertices might already have influences applied. Always test your influences to make sure influence assignments are correct.
</Alert>
##### Eyes
Both eyes in the example project require full influences on the pupil within the eye geometry. Depending on the design of the eyes, you might need to adjust influences to create realistic eye poses.
To add influence to the LeftEye:
1. In **Object Mode**, click the head mesh, then hold <kbd>Shift</kbd> and click any bone to select the armature.
2. Switch to **Weight Paint Mode**.
3. Toggle to **X-Ray viewing mode** or **Material Preview Mode** to better visualize the vertices.
4. Hold <kbd>Shift</kbd> and click the **LeftEye** bone to select it. The name of the currently selected bone displays on the top left of the Viewport.
5. Paint influence on the vertices within the eye. For this example, ensure that the pupils are red, or fully influenced by the selected bone.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/7_Skinning_LeftEye.mp4">
</video>
6. Switch to **Object Mode**, then click on any bone to select the armature.
7. Switch to **Pose Mode** with the armature selected.
8. Test the influences of the eye bone by grabbing the bone and moving it. The mesh below should follow.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/8_Testing_LeftEye.mp4">
</video>
9. Repeat these steps for the right eye.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/9_Skinning_and_Testing_RightEye.mp4">
</video>
##### Eyelids
Eyelid bones require their own separate influences. While the example poses only manipulate the top eyelids, being able to control the bottom corners of the eyelids is important for other poses, such as `LeftCheekRaiser` and `RightCheekRaiser`.
To add influence to the left eyelid:
1. In **Object Mode**, click the head mesh, then hold <kbd>Shift</kbd> and click any bone.
2. Switch to **Weight Paint Mode**.
3. Switch to **X-Ray viewing mode** or **Material Preview Mode** to better visualize the vertices.
4. Paint influences on the closest vertices to the bone.
5. When complete, hold <kbd>Shift</kbd> and click another bone to begin applying influences to the closest vertices. Perform this step for each eyelid bone.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/10_Skinning_Eyelids.mp4">
</video>
6. Switch to **Object Mode**, select the character mesh, then switch to **Pose Mode** to test.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/11_Testing_Eyelids.mp4">
</video>
You can download [a version of this project](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Eye-Bones-Skinned.blend) with the bones skinned up to this point as reference.
#### Add controls
Since creating heads requires saving several poses consecutively, while not required, controls can help you pose your bones quickly and effectively. You can create controls by adding external controller bones that influence the internal ones, making it easier to access and pose as well as reset to a neutral transformation.
You can create controls in many different ways. The following example uses **Bone Constraints** and simple geometrical shapes included in the reference Blender project to quickly set up easy-to-access controller bones for the character's facial bones. For more information on rigging and constraints, see Blender's documentation for additional details on [character rigging](https://www.youtube.com/watch?v=-gIL6VZ-bkE) and [object constraints](https://www.youtube.com/watch?v=fx33sPEAZEk).
<Alert severity="info">
Some facial features, such as lips, jaws, and tongue, might require a single controller bone that controls several facial bones at once. See the complete reference file for an example of this type of implementation.
</Alert>
To start creating face bone controls:
1. In **Object Mode**, select the Joints armature and press <kbd>Shift</kbd><kbd>D</kbd> to duplicate the Joints armature object.
2. Rename the new armature to **Controller**.
3. In **Edit Mode**, select all non-face bones, right click and select **Delete Selected Bones**.
4. Rename the bones to include **\_Con**, to denote them as controller bones. You can batch rename them with the following process:
1. In the **Outliner**, hold <kbd>Shift</kbd> and click all the controller bones.
2. Navigate to **Edit** > **Batch Rename**. A rename modal displays.
3. Set to **Selected** and use the dropdown to set to **Bones**.
4. Set **Type** to **Set Name**.
5. Set **Method** to **Suffix**.
6. In **Name**, add **\_Con**.
7. Click the **OK** button.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/12_Creating_Controller_Bones.mp4">
</video>
5. Switch to **Object Mode** and select the original **Joints armature** object.
6. Switch to **Pose Mode**.
7. Click on the original joint bones, such as **LeftEye**, then navigate to the **Bone Constraints Property Panel**.
8. Add **Copy Location** and **Copy Rotation**, then set each original bone's constraint to target their corresponding Controller Bone, such as **LeftEye_Con**.
9. In the **Copy Rotation** constraint, set the following properties:
1. In **Axis**, disable the **X**, **Y**, and **Z**.
2. In **Inverted Axis**, enable the **X**, **Y**, and **Z**.
3. Set **Mix** to **Offset** (Legacy).
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/13_Creating_Bone_Constraints.mp4">
</video>
10. Perform steps 7-9 for each facial bone that requires a controller.
To create custom bone shapes for easier control bone access:
1. Switch to **Object Mode** and select the **Controller** armature object.
2. Switch to **Pose Mode**.
3. Select a controller bone, such as **LeftEye_Con**.
4. Switch to the **Bones Properties** panel and expand the **Viewport Display** section.
5. Select one of the custom shapes included in the project. In the reference project, the shape objects share similar names to the face bones.
6. Set the **X** rotation to **-90**. Set any additional scaling if required.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/14_Assigning_Custom_Shapes.mp4">
</video>
7. Perform steps 3-6 for all your controller bones. You can hide the original face bones at this point.
8. (Optional) Set up **Bone Groups** to assign colors to your controller bones:
1. Navigate to the **Object Data Properties** panel.
2. Create a new bone group.
3. Change **Color Set** to a color theme of your choice.
4. Click **Assign** to assign the currently selected controller that color. You can perform this step in batches.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/15_Coloring_Control_bones.mp4">
</video>
9. Test your controllers in **Pose Mode**.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/16_Testing_Controllers.mp4">
</video>
## Pose
**Posing** is the process of manipulating the bones of your head mesh into a specific position per animation frame. After the model's head has been rigged, you can begin the process of saving poses to the timeline. This data enables Studio to access each facial movement and animate or blend facial poses to create dynamic expressions.
When posing the bones of your character's head mesh to new positions, follow the [Facial Action Coding System](../../../art/characters/facial-animation/facs-poses-reference.md) (FACS) as a reference for your facial expression poses. FACS is a comprehensive, anatomically-based system for describing all visually discernible facial movement, and it allows for all facial animations to be shareable between characters. This means that once you create a facial animation, you can reuse it for any character with an [animatable head](../../../art/characters/facial-animation/use-heads-in-studio.md) with a `Class.FaceControls` instance.
Each frame within your modeling software's animation timeline can contain one unique FACS pose, so when you want to create multiple FACS poses, you must save each FACS pose to a different frame. You must also include a frame with your character having a neutral face with the face controllers and bones set to their default values. This ensures that Studio can calculate the bone position differences between your character's neutral expression and each FACS pose. For this reason, set Frame 0 as your character's neutral expression, and save FACS poses starting at Frame 1.
The following image is an example of Blender's animation timeline with 5 frames. Frame 0 has the character's neutral expression, and frames 1-4 have FACS pose data.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Animation-Timeline.png" width="70%" />
There are [50 base poses](./facs-poses-reference.md) that you can use in Roblox to portray a wide range of face emotions for your characters. When you are deciding which poses you need, remember that FACS pose names are always based on the orientation of the character, not the camera. For example, `LeftEyeClosed` closes the character's left eye, which is to the right of the camera view.
<Alert severity = 'warning'>
If you intend to sell your character head to the Marketplace, you must include the minimum 17 base [FACS poses](./facs-poses-reference.md).
</Alert>
You might not require all 50 base poses for your character. For example, a simple robot that opens its mouth and blinks can just have `JawDrop`, `LeftEyeClosed`, and `RightEyeClosed`. Therefore, the more expressive you want your character to be, the more FACS poses you need to include in your animation timeline. It's recommended to save the base poses that you intend to use with your head in alphabetical order, then use any frames afterwards for [combination poses](#combination-poses).
The following steps outline the process of posing 5 poses with the facial bones created in our reference, but you can apply these steps for any additional poses for a more expressive head. To pose your face bones in Blender:
1. Ensure that the animation timeline playhead is set to the correct frame.
1. If you are setting the character's **Neutral pose**, set it to **frame 0**.
2. If you are posing `EyesLookLeft`, set it to **frame 1**.
3. If you are posing `EyesLookRight`, set it to **frame 2**.
4. If you are posing `LeftEyeClosed`, set it to **frame 3.**
5. If you are posing `RightEyeClosed`, set it to **frame 4**.
2. In **Pose Mode**, set the pose to the maximum position you want your pose to realistically use:
1. If you are setting the character's `Neutral` pose, set the face controllers and bones to their default values,
2. If you are posing `EyesLookLeft`, select both eye controller bones and drag the eyes to the character's left.
3. If you are posing `EyesLookRight`, select both eye controller bones and drag the eyes to the character's right.
4. If you are posing `LeftEyeClosed`, select both eye controller bones and drag the left eyelids down to meet the bottom eyelids.
5. If you are posing `RightEyeClosed`, select both eye controller bones and drag the right eyelids down to meet the bottom eyelids.
3. In the **Viewport**, press <kbd>A</kbd> to select all bones.
4. Right-click and select **Insert Keyframe** > **Location and Rotation**. This ensures that each frame contains the positional and rotational information for all bones.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/17-Posing.mp4">
</video>
When all the poses are saved in your timeline, set the Start and End of the animation timeline to represent the number of frames with saved poses. Always set **Start** to **0** and, in this specific example, you can set the **End** to **4** if you are only mapping the 4 non-neutral example poses.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Animation-Frame-Range.png" width="70%" />
### Combination poses
You can combine 2-3 base FACS poses in a single animation frame to display complex facial expressions. However, when you combine FACS poses that control the **same** facial regions, the facial features might either collide or disfigure the character.
For example, both `LeftEyeClosed` and `LeftCheekRaiser` control movement around the character's left eye: `LeftEyeClosed` closes the eye, and `LeftCheekRaiser` lifts the cheek up and pushes the lower eyelid up, causing a squint-like effect. When you combine both poses with one or more at 100% of their values, the lower eyelid collides with the upper eyelid:
<GridContainer numColumns="3">
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example1.mp4"></video>
<figcaption>Both FACS poses concurrently ease to 100% of their default values.</figcaption>
</figure>
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example2.mp4"></video>
<figcaption>LeftEyeClosed eases to 100% of its default value, and LeftCheekRaiser starts at 100%.</figcaption>
</figure>
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example3.mp4"></video>
<figcaption>LeftCheekRaiser eases to 100% of its default value, and LeftEyeClosed starts at 100%.</figcaption>
</figure>
</GridContainer>
A **combination pose**, or **corrective**, is the combination of 2-3 FACS poses that control the same facial features in a single animation frame with a **corrective difference from 100% of their default values**. By defining and mapping a combination pose to your head, you can correct how you want the two or more FACS poses to combine. For example, if you add a corrective for each of the previous use cases, the lower and upper eyelids make contact with each other without colliding:
<GridContainer numColumns="3">
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example4.mp4"></video>
<figcaption>Using a corrective pose, both FACS poses concurrently ease to 100% of their default values.</figcaption>
</figure>
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example5.mp4"></video>
<figcaption>LeftEyeClosed eases to 100% of its default value, and LeftCheekRaiser starts at 100%.</figcaption>
</figure>
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/Combination_Example6.mp4"></video>
<figcaption>LeftCheekRaiser eases to 100% of its default value, and LeftEyeClosed starts at 100%.</figcaption>
</figure>
</GridContainer>
On import, Studio calculates and stores the corrective difference for combination poses in the head's `Class.FaceControls` instance, and the `Class.FaceControls` instance corrects the base poses values as they combine in the [Animation Editor](../../../animation/editor.md).
## Map
After you finish posing each FACS pose that your character needs, you must map, or link, **each animation frame that you pose** to its corresponding FACS base or combination pose name. Mapping stores the bone positions and translations within the head `Class.MeshPart`, and when you begin to animate your head within the **Animation Editor**, the `Class.FaceControls` instance uses this stored data to transform your character's facial features to the applicable FACS pose.
<Alert severity = 'warning'>
If you intend to sell your character head to the Marketplace, you must include the minimum 17 base [FACS poses](./facs-poses-reference.md).
</Alert>
Aside from mapping each pose to its proper pose name, you also need to map the [RootFaceJoint](#rootfacejoint) so that Studio can properly locate that joint and hide all of the children joints and their bones within the `Class.FaceControls` instance on import.
<Alert severity="info">
If you are using Maya, you can map the RootFaceJoint and facial pose data using the **Extra Attributes** in a similar format as Blender's Custom Properties. To add attributes:
1. Select the **Head_Geo** object and navigate to the Attribute Editor.
2. Under the Attributes dropdown, select **Add Attributes...**.
</Alert>
<Alert severity="error">
If you leave any empty strings, or try to import the head into Studio with multiple frames per FACS pose name, the head will fail the [import process](../../../art/characters/facial-animation/use-heads-in-studio.md#import-heads).
</Alert>
To map your saved poses and the RootFaceJoint:
1. Switch to **Object Mode**.
2. Select the **Head_Geo mesh**.
3. In the **Object Properties** tab of the **Properties Editor**, navigate to the **Custom Properties** section, then click the **New** button. A new custom property displays underneath the **New** button.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Mapping-New-Button.png" width="50%" />
4. To the right of the new custom property, click the **Gear Icon**. The **Edit Property** pop-up displays.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Mapping-Popup.png" width="50%" />
5. Click the **Type** dropdown, then select **String**.
6. In the **Property Name** field:
1. If you are mapping a pose, input the **frame number** you are mapping, **Frame0** for example.
2. If you are mapping the RootFaceJoint, input **RootFaceJoint**.
7. Leave the **Default Value** and **Description** fields empty.
8. Click the **OK** button. The new custom property updates with your new property name.
9. In the field to the right of the custom property name:
1. If you're mapping a base pose, input the corresponding [FACS base pose](./facs-poses-reference.md) or combination pose name exactly as it is spelled.
2. If you're mapping a combination pose, input each base pose you are combining separated by an underscore, such as **Funneler_JawDrop_Pucker**.
3. If you're mapping the RootFaceJoint, input the name of the face root bone, commonly **DynamicHead**.
10. Press **Enter**.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/18_Mapping.mp4"></video>
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/videos/2_Mapping_RootFaceJoint.mp4"></video>
As you repeat this process, every additional custom property you create displays in the **Custom Properties** section of the **Object Properties** tab within the **Properties Editor**.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Custom-Properties-Example.png" width="40%" />
You can download a [version of this project](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Eye-Poses-Mapped.blend) with the poses saved and mapped up to this point as reference. If importing a head `.fbx` with saved animation data into Blender, make sure to set the **Animation Offset** in the .FBX Import window to **0** to include the Frame 0 of the timeline.
<img src="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/Animation-Offset-Importing.png" width="30%" />
## Export
After you finish posing and mapping your head for your character, you can export the character model as a `.fbx` to import into Studio, allowing you to access the 4 eye poses using the `Class.FaceControls` instance in Studio. You can also reference the fully configured Cubie head `.fbx` to access all 50+ base poses.
The export settings for animatable heads differ slightly from [standard third-party modeling export settings](../../../art/modeling/export-requirements.md). To export the basic head model as a `.fbx`:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Export**, then **FBX (.fbx)**. The **Blender File View** window displays.
3. Expand **Include** and enable **Limit To > Active Collection**. Note that this step is optional if you do not have additional collections in your Blender project.
4. In the **Include** section, enable **Custom Properties**.
5. Expand the **Armature** section and uncheck **Add Leaf Bones**.
6. Enable **Bake Animation**.
7. Expand **Bake Animation** and uncheck **NLA Strips**, **All Actions**, and **Force Start/End Keyframes**.
8. Click the **Export FBX** button. Save the FBX to the directory of your choice.
At this point, you can now import the `.fbx` into Studio as a character with a supported animatable head. For model import and usage instructions, see [Use heads in Studio](../../../art/characters/facial-animation/use-heads-in-studio.md).
<Alert severity="warning">
When importing Cubie into Studio, make sure to also save the head texture <a href="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie_Head_ALB.png" download>Cubie-Texture_ALB.png</a> which you can apply to the head mesh of the imported character as a TextureID.
</Alert>

181
.cursor/rules/roblox/art/characters/facial-animation/create-face-accessories.md Normal file
View file

@ -0,0 +1,181 @@
---
title: Create face accessories
description: Face accessories are 3D accessories that move and animate with a live head.
---
<Alert severity="warning">
<b>This guide covers advanced topics.</b> Before you begin, you should have prior knowledge on modeling, UV mapping, rigging, animation, and how to set up a character in [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
</Alert>
A face accessory is a cosmetic `Class.Accessory` that attaches to the head and can include items such as hair, eyebrows, glasses, and facial hair. To create a face accessory that is compatible with animatable heads, you use a similar design process as [layered clothing](../../../art/accessories/index.md#creation-process) to allow your accessory model to deform and stretch on a head when the head is posed or animated.
To create a face accessory, use a third-party modeling tool, such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview), to create a 3D model with the following requirements:
- The accessory model must meet Studio's [mesh requirements](../../../art/characters/specifications.md).
- The model must be parented (Blender) or bound (Maya) to an R15 character rig.
- The model must include an inner and outer cage.
This guide covers the basic process in Blender for applying rigging and cage data to a basic reference model using the Cubie model referenced in [Create basic heads](../../../art/characters/facial-animation/create-basic-heads.md).
<Alert severity="info">
This guide uses <a href="https://www.blender.org/download/releases/3-0/">Blender version 3.0</a>. If you are using another version of Blender, there might be minor differences in UI and settings.
</Alert>
## Reference files
The following are face accessory reference files, including all example files from this guide:
<Alert severity = 'warning'>
The reference character model provided is meant for educational purposes and does not meet the avatar character [technical specifications](../../../art/characters/specifications.md) for general use.
</Alert>
<table>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.fbx">Cubie-Complete.fbx</a></td>
<td>The complete Cubie reference character, from <a href="../../characters/facial-animation/create-basic-heads.md">Creating Basic Heads</a>. This file is ready for import into Studio.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/Cubie-Cage-Only.fbx">Cubie-Cage-Only.fbx</a></td>
<td>The full body <a href="../../../art/accessories/project-files.md#caging-meshes">cage mesh</a> of the Cubie reference character. This includes the inner and outer cage meshes.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/CubieEyebrow_Geo.fbx">Cubie-Eyebrow-Geo.fbx</a></td>
<td>A standalone eyebrow model, designed for the Cubie model.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/Cubie-Eyebrow-Rigged-And-Caged.fbx">Cubie-Eyebrow-Rigged-And-Caged.fbx</a></td>
<td>The Cubie eyebrow model, correctly rigged and caged following the instructions in this guide. This file is ready for import into Studio.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/CubieHawkHair_Geo.fbx">Cubie-Hawk-Hair.fbx</a></td>
<td>A hair model reference, designed for the Cubie model.</td>
</tr>
<tr>
<td><a href="../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/Creating-Face-Accessories-Reference-Files.zip">Creating-Face-Accessories-Reference-Files.zip</a></td>
<td>A collection of all the provided reference files.</td>
</tr>
</tbody>
</table>
## Modeling
This guide uses a simple eyebrow reference as a demonstration for creating a face accessory. If rigging and caging a different model, ensure that your model meets the [character specifications](../../../art/characters/specifications.md) for Studio import.
<img src="../../../assets/avatar/dynamic-heads/creating-face-accessories/Importing-Eyebrows.png" width="70%" />
If creating your own model, consider the following guidelines:
- Model your accessory with your character model for best results and fit.
- When possible, try to match up the edges of your model geometry with the edges/vertices of the underlying head topology. This improves the deformation of the accessory with the underlying head model.
- Some accessories, like eyebrows, can extrude or slightly intersect the character model mesh to achieve a certain cosmetic look.
- When working with an accessory with multiple pieces, such as eyebrows, combine the meshes to a single mesh once the modeling and fitting is completed.
- Face accessory meshes do not require a **\_Geo** naming convention.
## Rigging
You must [rig](../../../art/modeling/rigging.md) your accessory to the character's bone structure so the accessory can bend and deform along with your character's facial poses. After rigging, you can skin your model in your modeling tool, or you can transfer skinning data from your character to the accessory at runtime by using [Automatic skinning transfer](../../../art/accessories/automatic-skinning-transfer.md).
### Project setup
As an example in this guide, we are using the completed [basic Head model](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.fbx) from [Create a basic head](../../../art/characters/facial-animation/create-basic-heads.md) and a [simple eyebrow model](../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/CubieEyebrow_Geo.fbx) in a new Blender project.
To set up your Blender project:
1. Open a new **General** project in Blender.
2. Select the default shape, camera, and lights, then press <kbd>Delete</kbd>.
3. In the left-hand navigation of the **Properties Editor**, navigate to **Scene Properties**.
<img src="../../../assets/modeling/skinned-meshes/Blender-Scene-Units-Icon.png" width="40%" />
4. In the Units section, change the **Unit Scale** to `0.01` and the **Length** to **Centimeters**.
<img src="../../../assets/modeling/skinned-meshes/Blender-Scene-Units-Settings.png" width="40%" />
5. Import the character rig you intend to parent the accessory to, in this example: [Cubie-Complete.fbx](../../../assets/avatar/dynamic-heads/creating-dynamic-heads/reference-files/Cubie-Complete.fbx).
<img src="../../../assets/avatar/dynamic-heads/creating-face-accessories/Importing-Cubie.png" width="80%" />
6. To simplify the workspace, you can delete the R15 inner and outer cage mesh objects since you will later import a full-body cage in the [Caging](#caging) step.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-face-accessories/videos/Removing-Character-Cage.mp4">
</video>
7. Import your accessory model, in this example: [CubieEyebrow_Geo.fbx](../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/CubieEyebrow_Geo.fbx).
1. If required, reposition the accessory model on the face.
2. You can hide the armature temporarily to verify model placement.
<img src="../../../assets/avatar/dynamic-heads/creating-face-accessories/Importing-Eyebrows.png" width="70%" />
### Parent armature
Connect the mesh object to the character's armature by parenting the armature to the mesh object. To parent the armature:
1. In Object Mode, hold <kbd>Shift</kbd> and **click** the accessory model and then any of the character bones.
2. Right click and select **Parent**, then select **With Automatic Weights**.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-face-accessories/videos/Parent-Armature.mp4">
</video>
<Alert severity="warning">
Parenting with Automatic Weights automatically applies some influences to your model which can save some time during the [optional skinning](#optional-skinning) step. You can alternatively **Parent** with **Empty Weights** to not apply any skinning influence to your accessory mesh. See Blender's documentation on [Automatic Weights](https://docs.blender.org/manual/en/latest/animation/armatures/skinning/parenting.html#with-automatic-weights) for more information.
</Alert>
### Optional skinning
In many cases, you can skip the [skinning](../../../art/modeling/rigging.md) process for your accessory and use Roblox's [automatic skinning transfer](../../../art/accessories/automatic-skinning-transfer.md) instead. You can still apply manual skinning through a modeling software and opt to use automatic skinning transfer later. With automatic skinning transfer, your end result and quality may vary.
If you do not intend to apply skinning manually, continue directly to [caging](#caging).
<Alert severity="info">
If you are skinning your accessory in your modeling software on a character model with a fully posed head, you can test the accessory on various FACS poses saved to the timeline within your modeling software before importing into Studio.
</Alert>
## Caging
The caging process for face accessories is similar to caging layered clothing accessories and shares the same modeling and caging requirements. After rigging, import a full-body inner and outer cage to your project, rename the cages, then stretch the vertices of the Outer Cage to cover the accessory model with minimal space.
To cage the eyebrow accessory:
1. With Blender's .fbx importer, import [`Cubie-Cage-Only.fbx`](../../../assets/avatar/dynamic-heads/creating-face-accessories/reference-files/Cubie-Cage-Only.fbx). This includes a single full-body inner and outer cage mesh for the Cubie model.
<img src="../../../assets/avatar/dynamic-heads/creating-face-accessories/Importing-Cage.png" width="80%" />
2. Rename cages to begin with "CubieEyebrow" before the **\_InnerCage** and **\_OuterCage** affix.
3. In Edit mode, extend the outer cage to fit over the accessory with minimal space. Use various material and viewing options to easily manipulate the correct vertices on the outer cage.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/creating-face-accessories/videos/Editing-Outer-Cage.mp4">
</video>
If you are using automatic skinning transfer, you can ensure that automatic skinning transfer only applies to specific parts of the accessory by removing unnecessary sections of the cage. For more information, see [Modifying Character Cages](../../../art/accessories/automatic-skinning-transfer.md#modify-character-cages).
## Export
Export your model when ready to test your accessory model in Studio or when setting up for final export. When exporting face accessories, keep in mind the following guidelines:
- Ensure that the final accessory model follows [Studio's Modeling Requirements](../../../art/characters/specifications.md), including properly named mesh and cage objects.
- Do not export any unnecessary data, such as animation data, or light and camera objects.
- If exporting PBR textures, follow [texture modeling requirements](../../../art/characters/specifications.md#surfaceappearance) when exporting texture images from your texture software.
To export:
1. Ensure only the **accessory mesh**, **armature object** and **cages meshes** are exported. Delete all other objects in the workspace.
1. You can quickly filter out **Geo** and **Att** named objects in your workspace to quickly delete them.
<video controls width="70%" src="../../../assets/avatar/dynamic-heads/creating-face-accessories/videos/Removing-Extra-Objects.mp4">
</video>
2. Follow Studio's [Export Requirements for Blender](../../../art/accessories/export-settings.md) and save the file to your preferred location. The final export of the eyebrow `.fbx` is available for reference.
## Test in Studio
To use your exported model into Studio as an `Class.Accessory`, use the [Accessory Fitting Tool](../../../art/accessories/accessory-fitting-tool.md) to test and generate the accessory object. At this point, you can equip the accessory to a humanoid character. If you intend to transfer skinning data from your character to the accessory model at runtime, you can enable [automatic skinning transfer](../../../art/accessories/automatic-skinning-transfer.md) for your accessory.
<Alert severity="info">
If following the references provided by this guide, only **EnabledOverride** applies the skinning transfer in Studio, since some skinning data will have been applied to the model during the [parenting](#parent-armature) process.
</Alert>

539
.cursor/rules/roblox/art/characters/facial-animation/facs-poses-reference.md Normal file
View file

@ -0,0 +1,539 @@
---
title: FACS poses reference
description: The Facial Action Coding System (FACS) ensures that all face animations have a common pose reference and can create similar face animations.
---
The [Facial Action Coding System](https://en.wikipedia.org/wiki/Facial_Action_Coding_System) (FACS) is a comprehensive, anatomically-based system for describing all visually discernible facial movement. This system breaks down all facial expressions into individual types of muscle movement, such as `LeftEyeClosed` or `MouthLeft`. You can [configure](../../../art/characters/facial-animation/create-basic-heads.md#pose) and store these muscle movements, or **poses**, within the head model through a third-party modeling software, such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview). When you import the head model into Studio, you can then access and [animate](../../../art/characters/facial-animation/animate-heads.md) these poses to create lively facial expressions.
The following is a list of 50 base poses that you can use in Roblox to portray a wide range of face emotions. Except for the first neutral pose, the order of poses you save to your character model doesn't matter since this information is set during the [mapping](../../../art/characters/facial-animation/create-basic-heads.md#map) process as a custom property.
<Alert severity = 'warning'>
If you intend to publish your avatar to the Marketplace, your avatar head must include the required [17 facial base poses](../../../art/characters/specifications.md#facial-animations). Marketplace validation rejects assets that do not include these 17 required base poses.
</Alert>
You can combine multiple FACS base poses together in one animation frame to create complex facial expressions. However, some combinations of poses might collide unless you also add a [corrective](../../../art/characters/facial-animation/create-basic-heads.md#combination-poses) to their full default values.
## EyesLookDown
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.EyesLookDown|EyesLookDown` makes the eyes gaze down.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookDownA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookDownB.mp4" width="70%"></video>
</GridContainer>
## EyesLookLeft
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.EyesLookLeft|EyesLookLeft` makes the eyes gaze left.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookLeftA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookLeftB.mp4" width="70%"></video>
</GridContainer>
## EyesLookRight
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.EyesLookRight|EyesLookRight` makes the eyes gaze right.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookRightA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookRightB.mp4" width="70%"></video>
</GridContainer>
## EyesLookUp
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.EyesLookUp|EyesLookUp` makes the eyes gaze up.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookUpA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/EyesLookUpB.mp4" width="70%"></video>
</GridContainer>
## JawDrop
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.JawDrop|JawDrop` lowers the jaw downward, opening the mouth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawDropA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawDropB.mp4" width="70%"></video>
</GridContainer>
## LeftEyeClosed
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LeftEyeClosed|LeftEyeClosed` closes the character's left eyelid.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftEyeClosedA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftEyeClosedB.mp4" width="70%"></video>
</GridContainer>
## LeftLipCornerPuller
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LeftLipCornerPuller|LeftLipCornerPuller` raises the corners of the mouth upwards in a smile.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipCornerPullerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipCornerPullerB.mp4" width="70%"></video>
</GridContainer>
## LeftLipStretcher
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LeftLipStretcher|LeftLipStretcher` stretches the corners of the mouth apart.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipStretcherA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipStretcherB.mp4" width="70%"></video>
</GridContainer>
## LeftLowerLipDepressor
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LeftLowerLipDepressor|LeftLowerLipDepressor` lowers the lower lip downwards away from the upper lip, revealing the lower teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLowerLipDepressorA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLowerLipDepressorB.mp4" width="70%"></video>
</GridContainer>
## LeftUpperLipRaiser
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LeftUpperLipRaiser|LeftUpperLipRaiser` raises the character's left upper lip away from the lower lip revealing the upper teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftUpperLipRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftUpperLipRaiserB.mp4" width="70%"></video>
</GridContainer>
## LipsTogether
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.LipsTogether|LipsTogether` brings the character's lips together. However, if the character's mouth is closed, their lips are already together and they collide.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherA-1.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherB-1.mp4" width="70%"></video>
</GridContainer>
This pose's main use case is in connection with the [`JawDrop`](#jawdrop) property. If you set [`JawDrop`](#jawdrop) and `Class.FaceControls.LipsTogether|LipsTogether` to 100% of their default values, the character's lips stay together as the jaw drops.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherA-2.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherB-2.mp4" width="70%"></video>
</GridContainer>
In addition, if you set [`JawDrop`](#jawdrop) to 100% of its default value, and ease `Class.FaceControls.LipsTogether|LipsTogether` in and out of 100% of its default value, the character's lips open and close.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherA-3.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipsTogetherB-3.mp4" width="70%"></video>
</GridContainer>
## Pucker
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.Pucker|Pucker` makes a kiss-like shape with the mouth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/PuckerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/PuckerB.mp4" width="70%"></video>
</GridContainer>
## RightEyeClosed
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.RightEyeClosed|RightEyeClosed` closes the character's right eyelid.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightEyeClosedA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightEyeClosedB.mp4" width="70%"></video>
</GridContainer>
## RightLipCornerPuller
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.RightLipCornerPuller|RightLipCornerPuller` raises the corners of the mouth upwards in a smile.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipCornerPullerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipCornerPullerB.mp4" width="70%"></video>
</GridContainer>
## RightLipStretcher
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.RightLipStretcher|RightLipStretcher` stretches the corners of the mouth apart.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipStretcherA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipStretcherB.mp4" width="70%"></video>
</GridContainer>
## RightLowerLipDepressor
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.RightLowerLipDepressor|RightLowerLipDepressor` lowers the lower lip down away from the upper lip revealing the lower teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLowerLipDepressorA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLowerLipDepressorB.mp4" width="70%"></video>
</GridContainer>
## RightUpperLipRaiser
<Alert severity = 'warning'>
If publishing to the Marketplace, your avatar asset must include this pose.
</Alert>
`Class.FaceControls.RightUpperLipRaiser|RightUpperLipRaiser` raises the right upper lip away from the lower lip, revealing the upper teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightUpperLipRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightUpperLipRaiserB.mp4" width="70%"></video>
</GridContainer>
## ChinRaiser
`Class.FaceControls.ChinRaiser|ChinRaiser` raises the chin up; moves the lower lip upwards.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/ChinRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/ChinRaiserB.mp4" width="70%"></video>
</GridContainer>
When you use `Class.FaceControls.ChinRaiser|ChinRaiser` and the character's mouth is closed, the character's lower lip collides with their upper lip. When you need to keep the mouth closed while raising the chin, use [`ChinRaiserUpperLip`](#chinraiserupperlip) and `Class.FaceControls.ChinRaiser|ChinRaiser` together to raise both the lower and upper lip, and avoid a collision. Note that if you use this method, you must set both `Class.FaceControls.ChinRaiser|ChinRaiser` and [`ChinRaiserUpperLip`](#chinraiserupperlip) to the same value so the lips move the same distance upwards.
## ChinRaiserUpperLip
`Class.FaceControls.ChinRaiserUpperLip|ChinRaiserUpperLip` raises the upper lip up when ChinRaiser is engaged and it is touching the upper lip.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/ChinRaiserUpperLipA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/ChinRaiserUpperLipB.mp4" width="70%"></video>
</GridContainer>
## FlatPucker
`Class.FaceControls.FlatPucker|FlatPucker` brings the corners of the mouth inward and presses the lips back against the teeth. This pose is also known as lip tightener.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/FlatPuckerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/FlatPuckerB.mp4" width="70%"></video>
</GridContainer>
## Funneler
`Class.FaceControls.Funneler|Funneler` makes an 'O' shape with the mouth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/FunnelerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/FunnelerB.mp4" width="70%"></video>
</GridContainer>
## LowerLipSuck
`Class.FaceControls.LowerLipSuck|LowerLipSuck` rolls the lower lip up over the teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LowerLipSuckA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LowerLipSuckB.mp4" width="70%"></video>
</GridContainer>
## LipPresser
`Class.FaceControls.LipPresser|LipPresser` presses the lips together.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipPresserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LipPresserB.mp4" width="70%"></video>
</GridContainer>
## MouthLeft
`Class.FaceControls.MouthLeft|MouthLeft` moves the mouth to the character's left. This property doesn't move the character's jaw, teeth, or tongue, only their mouth. If you want to move those additional facial features, use [`JawLeft`](#jawleft) instead.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/MouthLeftA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/MouthLeftB.mp4" width="70%"></video>
</GridContainer>
## MouthRight
`Class.FaceControls.MouthRight|MouthRight` moves the mouth to the character's right. This property doesn't move the character's jaw, teeth, or tongue to the right, only their mouth. If you want to move those additional facial features, use [`JawRight`](#jawright) instead.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/MouthRightA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/MouthRightB.mp4" width="70%"></video>
</GridContainer>
## UpperLipSuck
`Class.FaceControls.UpperLipSuck|UpperLipSuck` rolls the upper lip around the teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/UpperLipSuckA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/UpperLipSuckB.mp4" width="70%"></video>
</GridContainer>
## LeftCheekPuff
`Class.FaceControls.LeftCheekPuff|LeftCheekPuff` puffs up the character's left cheek.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftCheekPuffA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftCheekPuffB.mp4" width="70%"></video>
</GridContainer>
## LeftDimpler
`Class.FaceControls.LeftDimpler|LeftDimpler` moves the corners of the left side of the mouth back toward the teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftDimplerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftDimplerB.mp4" width="70%"></video>
</GridContainer>
## LeftLipCornerDown
`Class.FaceControls.LeftLipCornerDown|LeftLipCornerDown` lowers the corners of the mouth downwards in a frown.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipCornerDownA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftLipCornerDownB.mp4" width="70%"></video>
</GridContainer>
## RightCheekPuff
`Class.FaceControls.RightCheekPuff|RightCheekPuff` puffs up the character's right cheek.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightCheekPuffA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightCheekPuffB.mp4" width="70%"></video>
</GridContainer>
## RightDimpler
`Class.FaceControls.RightDimpler|RightDimpler` moves the corners of the right side of the mouth back toward the teeth.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightDimplerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightDimplerB.mp4" width="70%"></video>
</GridContainer>
## RightLipCornerDown
`Class.FaceControls.RightLipCornerDown|RightLipCornerDown` lowers the corners of the mouth downwards in a frown.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipCornerDownA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightLipCornerDownB.mp4" width="70%"></video>
</GridContainer>
## JawLeft
`Class.FaceControls.JawLeft|JawLeft` moves the character's jaw, teeth, tongue, and lower lip to their left. If you just want to move the character's mouth to their left, use [`MouthLeft`](#mouthleft) instead.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawLeftA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawLeftB.mp4" width="70%"></video>
</GridContainer>
## JawRight
`Class.FaceControls.JawRight|JawRight` moves the character's jaw, teeth, tongue, and lower lip to their right. If you just want to move the character's mouth to their right, use [`MouthRight`](#mouthright) instead.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawRightA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/JawRightB.mp4" width="70%"></video>
</GridContainer>
## Corrugator
`Class.FaceControls.Corrugator|Corrugator` brings the left and right brows inward together.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/CorrugatorA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/CorrugatorB.mp4" width="70%"></video>
</GridContainer>
## LeftBrowLowerer
`Class.FaceControls.LeftBrowLowerer|LeftBrowLowerer` lowers the character's left brow down.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftBrowLowererA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftBrowLowererB.mp4" width="70%"></video>
</GridContainer>
## LeftOuterBrowRaiser
`Class.FaceControls.LeftOuterBrowRaiser|LeftOuterBrowRaiser` raises the outer part of the character's left brow upwards.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftOuterBrowRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftOuterBrowRaiserB.mp4" width="70%"></video>
</GridContainer>
## LeftNoseWrinkler
`Class.FaceControls.LeftNoseWrinkler|LeftNoseWrinkler` raises the character's left nostril, pulls the brow down slightly, and wrinkles the left side of the nose.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftNoseWrinklerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftNoseWrinklerB.mp4" width="70%"></video>
</GridContainer>
## LeftInnerBrowRaiser
`Class.FaceControls.LeftInnerBrowRaiser|LeftInnerBrowRaiser` raises the interior half of the character's left brow upwards.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftInnerBrowRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftInnerBrowRaiserB.mp4" width="70%"></video>
</GridContainer>
## RightBrowLowerer
`Class.FaceControls.RightBrowLowerer|RightBrowLowerer` lowers the character's right brow down.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightBrowLowererA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightBrowLowererB.mp4" width="70%"></video>
</GridContainer>
## RightOuterBrowRaiser
`Class.FaceControls.RightOuterBrowRaiser|RightOuterBrowRaiser` raises the outer part of the character's right brow upwards.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightOuterBrowRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightOuterBrowRaiserB.mp4" width="70%"></video>
</GridContainer>
## RightInnerBrowRaiser
`Class.FaceControls.RightInnerBrowRaiser|RightInnerBrowRaiser` raises the interior half of the character's right brow upwards.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightInnerBrowRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightInnerBrowRaiserB.mp4" width="70%"></video>
</GridContainer>
## RightNoseWrinkler
`Class.FaceControls.RightNoseWrinkler|RightNoseWrinkler` raises the character's right nostril, pulls the brow down slightly, and wrinkles the right side of the nose.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightNoseWrinklerA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightNoseWrinklerB.mp4" width="70%"></video>
</GridContainer>
## LeftCheekRaiser
`Class.FaceControls.LeftCheekRaiser|LeftCheekRaiser` squints the character's left eye.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftCheekRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftCheekRaiserB.mp4" width="70%"></video>
</GridContainer>
## LeftEyeUpperLidRaiser
`Class.FaceControls.LeftEyeUpperLidRaiser|LeftEyeUpperLidRaiser` raises the character's left eyelid upwards to reveal more of the eye white above the iris.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftEyeUpperLidRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/LeftEyeUpperLidRaiserB.mp4" width="70%"></video>
</GridContainer>
## RightCheekRaiser
`Class.FaceControls.RightCheekRaiser|RightCheekRaiser` squints the character's right eye.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightCheekRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightCheekRaiserB.mp4" width="70%"></video>
</GridContainer>
## RightEyeUpperLidRaiser
`Class.FaceControls.RightEyeUpperLidRaiser|RightEyeUpperLidRaiser` raises the character's right eyelid upwards to reveal more of the eye white above the iris.
<GridContainer numColumns="2">
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightEyeUpperLidRaiserA.mp4" width="70%"></video>
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/RightEyeUpperLidRaiserB.mp4" width="70%"></video>
</GridContainer>
## TongueDown
`Class.FaceControls.TongueDown|TongueDown` bends the tongue down. This pose is only visible if you combine it with [`TongueOut`](#tongueout), otherwise the tongue only bends down within the character's mouth.
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/TongueDown.mp4" width="30%"></video>
## TongueOut
`Class.FaceControls.TongueOut|TongueOut` sticks the tip of the tongue out of the mouth.
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/TongueOut.mp4" width="30%"></video>
## TongueUp
`Class.FaceControls.TongueUp|TongueUp` bends the tongue up. This pose is only visible if you combine it with [`TongueOut`](#tongueout), otherwise the tongue only bends up within the character's mouth.
<video controls muted src="../../../assets/avatar/dynamic-heads/facs-pose-reference/TongueUp.mp4" width="30%"></video>

55
.cursor/rules/roblox/art/characters/facial-animation/index.md Normal file
View file

@ -0,0 +1,55 @@
---
title: Facial animation
description: Facial animations enable avatars to create dynamic facial expressions.
---
A head part that supports facial animation is a specialized skinned head `Class.MeshPart`. This type of body part allows you to:
- Set default custom facial expressions.
- Trigger emotes that combine both face and body animations.
- Equip face accessories that deform with your facial expressions. For example, facial hair moves accordingly when the character changes facial expressions.
<video controls width="90%" src="../../../assets/avatar/dynamic-heads/Blocky_And_Goblin_Dynamic_Heads.mp4">
</video>
An animatable head model contains an internal facial [rig](../../../art/modeling/rigging.md), or bone structure, that drives the deformation of the viewable geometry. When creating a dynamic head in a 3D modeling software, modelers save these bone deformations as individual **poses**.
When importing a head that supports facial animation into Studio, Studio creates a `Class.FaceControls` instance you can use to access and combine these individual poses to create expressions and animations. Unlike typical rigged models, you cannot access the facial `Class.Bone|Bones` of a head mesh directly in Studio.
For information on implementing heads in Studio, including information on how to import custom heads and face accessories in addition to a reference experience and example model files, see [Use heads in Studio](../../../art/characters/facial-animation/use-heads-in-studio.md).
<GridContainer numColumns="2">
<figure>
<img src="../../../assets/avatar/dynamic-heads/Goblin-Reference.jpg" width="75%" />
<figcaption>Goblin Reference</figcaption>
</figure>
<figure>
<img src="../../../assets/avatar/dynamic-heads/Blocky-Reference.jpg" width="94%" />
<figcaption>Blocky Reference</figcaption>
</figure>
</GridContainer>
## Animate heads
You can [animate any supported head](../../../art/characters/facial-animation/animate-heads.md) through the [Animation Editor](../../../animation/editor.md) by manually setting poses on the animation track, using the **Face Animation Editor** to quickly create complex expressions, or using the [Animation Capture Tool](../../../animation/capture.md) to automatically track facial movements from your webcam.
After you create, save, and publish a head animation to Roblox, you can play the animation from a script or replace a character's default animation with your new animation.
<video controls width="80%" src="../../../assets/avatar/dynamic-heads/animating-dynamic-heads/videos/2-Face-Controls-Example-Goblin.mp4">
</video>
## Create basic heads
Using third-party modeling tools, you can either modify a rigged character model to meet head requirements, or create a head from scratch. For step-by-step instructions on how to add face bones, apply skinning, posing, and mapping poses on a head model in Blender, see [Create basic heads](../../../art/characters/facial-animation/create-basic-heads.md). This guide includes several reference files you can use to compare and track your progress.
## Create face accessories
Similar to creating heads, you can design and model face accessories using a third-party modeling software and import the models as a cosmetic `Class.Accessory` in Studio. When created correctly, equipped accessories stretch and deform as the head animates and emotes.
See [Create face accessories](../../../art/characters/facial-animation/create-face-accessories.md) for step-by-step instructions on setting up a reference model as a face accessory. This guide includes several project files you can use for reference and covers details on time-saving steps, such as auto-skin transfer.
## FACS poses reference
Animatable heads use the Facial Action Coding System (FACS) as a universal system that allows modelers and animators to reference similar facial features and head mesh across different head models.
When creating your head in a third-party modeling software, see [FACS poses reference](../../../art/characters/facial-animation/facs-poses-reference.md) for a list of the base facial poses, their descriptions, and video examples.

130
.cursor/rules/roblox/art/characters/facial-animation/moods.md Normal file
View file

@ -0,0 +1,130 @@
---
title: Moods
description: Moods are a type of facial animation that loop indefinitely, allowing users to express persistent facial emotion.
---
A **mood** is a type of [facial animation](../../../art/characters/facial-animation/index.md) for animatable heads that loops indefinitely, allowing users to express themselves and react to others with a persistent facial emotion. Moods play simultaneously with other character [default animations](../../../animation/using.md#default-character-animations), such as walking, climbing, and swimming, and if the default animation has a facial animation, the default animation blends with the character's mood.
<GridContainer numColumns="2">
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/moods/Overview-Default-Mood.mp4" width="70%"></video>
<figcaption>Default mood</figcaption>
</figure>
<figure>
<video controls src="../../../assets/avatar/dynamic-heads/moods/Overview-Open-Mouth-Mood.mp4" width="70%"></video>
<figcaption>Open mouth mood</figcaption>
</figure>
</GridContainer>
<Alert severity="info">
A mood is a type of facial animation, but not all facial animations are moods. While a mood refers to a specific animation slot that belongs to each character, a facial animation refers to **any** animation that modifies the face channels.
</Alert>
## Create moods
If you have a character model with an animatable head, you can create any mood animation you can think of using the [Face Animation Editor](../../../art/characters/facial-animation/animate-heads.md#use-the-face-animation-editor). If you don't want to use the [Blocky](../../../assets/avatar/dynamic-heads/reference-files/BlockyCharacter.fbx) or [Goblin](../../../assets/avatar/dynamic-heads/reference-files/GoblinCharacter.zip) reference character models, you can create or modify an existing model to support animated heads in a third-party modeling software, such as Blender or Maya. For information on how to create an animatable head, see [Create basic heads](../../../art/characters/facial-animation/create-basic-heads.md).
To create a mood:
1. Add a character model with an animatable head to the viewport.
1. Open the **Face Animation Editor**.
1. From the toolbar's **Avatar** tab, click **Animation**. The [Animation Editor](../../../animation/editor.md) window displays.
1. In the viewport, select your character model with an animatable head. A dialog displays.
<img width="40%" img src="../../../assets/animation/animation-editor/Create-Animation-Dialog.png" />
1. In the **Animation Name** field, enter a new animation name, then click the **Create** button. The **Animation Editor** window displays the **media and playback controls**, **timeline**, and **track list**.
1. In the editor's **track list**, click the **Face** button. The **Face Animation Editor** displays to the left of the track list.
1. In the **Face Animation Editor**, adjust sliders for the facial parts you want to manipulate. Animation tracks for each facial part you manipulate automatically display in the track list along with keyframes for your current position in the timeline. The character's face also updates in the viewport.
- To undo a step on a slider, press <kbd>Ctrl</kbd><kbd>Z</kbd> (<kbd>⌘</kbd><kbd>Z</kbd>).
- To redo a step on a slider, press <kbd>Ctrl</kbd><kbd>Y</kbd> (<kbd>⌘</kbd><kbd>Y</kbd>).
- To reset a slider to its default value, right click on the slider. A contextual menu displays. Select **Reset Selected**.
1. When you are finished creating your animation, navigate to the **Media and Playback Controls** and click the **…** button. A pop-up menu displays.
<img width="60%" img src="../../../assets/animation/animation-editor/Controls-File-Menu.png" />
1. Select **Save** or **Save As** to save the mood animation. The animation displays in the **Explorer** window as a child of the **AnimSaves** object (itself a child of the rig).
<img width="20%" img src="../../../assets/avatar/dynamic-heads/moods/HappyMood.png" />
1. **(Optional)** To assign an asset ID to your mood animation and save it to the [Toolbox](../../../projects/assets/toolbox.md) to use across your experiences,
1. In the **Explorer** window, right-click on your new mood animation. A contextual menu displays.
1. Select **Save to Roblox**. The **Asset Configuration** window displays.
1. Fill in the following fields:
- **Title**: A name for your plugin.
- **Description**: A description that describes what a potential user should expect the plugin to do.
- **Creator**: The creator you'd like to attribute as the creator of the plugin.
1. Click the **Submit** button. After a moment, the Asset Configuration dialog displays your mood's `Class.Animation.AnimationID` that you can use to set the mood to characters within your experiences.
<img width="80%" img src="../../../assets/avatar/dynamic-heads/moods/Animation-ID.png" />
## Set moods
Every character with an animatable head has a child **Animate** `Class.LocalScript` with a child **mood** `Class.StringValue` that contains the mood animation that plays on the character's head. The mood animation's default `Class.Animation.AnimationID` plays a smiling animation, but you can change the character's mood to something else by either directly editing the `Class.Animation.AnimationID` within the mood `Class.StringValue`, or using the `Class.HumanoidDescription` system.
<img src="../../../assets/avatar/dynamic-heads/moods/animate-localscript-hierarchy.jpg" width="20%" />
<Alert severity="warning">
The code for playing moods doesn't occur in the **Animate** `Class.LocalScript`, but in a hidden, internal Roblox script. While you can't edit this internal script, the **mood** `Class.StringValue` allows you to interact with it in order to customize moods within your experiences.
</Alert>
### Edit AnimationIds
You can set a specific mood for each character within your experience by editing their mood's `Class.Animation.AnimationID` whenever a user triggers an event. For example, the following `Class.Script` edits any previously set mood to an animation that [opens the character's mouth](https://www.roblox.com/library/7715145252/moods-11-FaceAnimation) as soon as the user enters the experience:
```lua
local Players = game:GetService("Players")
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
local animateScript = character:WaitForChild("Animate")
animateScript.mood.Animation1.AnimationId = "rbxassetid://7715145252" -- Mood
end
local function onPlayerAdded(player)
player.CharacterAppearanceLoaded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)
```
### Use the HumanoidDescription
You can also use the `Class.HumanoidDescription` system to find user characters and edit their `Class.Animation.AnimationID|AnimationIDs` for any default animation. For example, the following `Class.Script` edits any previously set mood to an animation that gives the character a [half-smile](https://www.roblox.com/catalog/10725833199/Chiseled-Good-Looks-Mood) on the left-side of their face whenever their character is idling:
```lua
local humanoid = player.Character and player.Character:FindFirstChildWhichIsA("Humanoid")
if humanoid then
local descriptionClone = humanoid:GetAppliedDescription()
descriptionClone.IdleAnimation = 10725833199
-- Apply modified "descriptionClone" to humanoid
humanoid:ApplyDescription(descriptionClone)
end
```
## Disable moods
To disable moods from your experience, you can delete the mood object underneath the **Animate** `Class.LocalScript`. For example, the following `Class.Script` removes every character's **mood** `Class.StringValue` as soon as they join the experience:
```lua
local Players = game:GetService("Players")
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
local animateScript = character:WaitForChild("Animate")
animateScript.mood:Destroy()
end
local function onPlayerAdded(player)
player.CharacterAppearanceLoaded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)
```

218
.cursor/rules/roblox/art/characters/facial-animation/use-heads-in-studio.md Normal file
View file

@ -0,0 +1,218 @@
---
title: Use heads in Studio
description: If you have a model with a live head, you can import the model into Studio, equip face accessories, and create and save animations.
---
You can import character models with animatable heads into Studio and use the automatically generated `Class.FaceControls` instance to pose or animate the face.
To set up heads with facial animation in your experience:
1. [Import a model with an animatable head](../../../art/characters/testing/studio.md#import). You can either create your own or use one of the provided reference model files.
2. (Optional) [Import face accessories](#import-face-accessories) you want to deform with the facial expressions of your head. You can either create your own or use one of the provided reference accessory files.
3. [Animate the head](#animate-heads) in the **Animation Editor** by either adding in individual animation tracks, or by using the **Face Animation Editor**.
If you want to experiment with pre-made heads before [making your own](../../../art/characters/facial-animation/create-basic-heads.md), Roblox has a reference experience you can access to see how heads interact with Studio's interface, as well as two reference models and accessories you can import directly into your own experience:
<table>
<thead>
<tr>
<th>Reference files</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[Head Animation In-Experience Editor](../../../assets/avatar/dynamic-heads/reference-files/Dynamic-Head-Editor.rbxl)</td>
<td>A reference experience that allows you to preview a Goblin and Blocky head with various accessories using an editor.</td>
</tr>
<tr>
<td>[Head Schema Reference](../../../assets/avatar/dynamic-heads/reference-files/Dynamic-Head-Schema.rbxl)</td>
<td>A reference experience with a head Blocky model with `Class.FaceControls`.</td>
</tr>
<tr>
<td>[Goblin Character Model](../../../assets/avatar/dynamic-heads/reference-files/GoblinCharacter.zip)</td>
<td>A Goblin character model with an animatable head.</td>
</tr>
<tr>
<td>[Blocky Character Model](../../../assets/avatar/dynamic-heads/reference-files/BlockyCharacter.fbx)</td>
<td>A Blocky character model with an animatable head.</td>
</tr>
<tr>
<td>[Blocky Face Accessories and Clothing](../../../assets/avatar/dynamic-heads/reference-files/Blocky-Face-Accessories.zip)</td>
<td>A `.zip` file of Blocky-specific accessories, including:<ul><li>Angled Eyebrows</li><li>Round Eyebrows</li><li>Straight Eyebrows</li><li>Long Eyelashes</li><li>Short Eyelashes</li><li>Long Ducktail Beard</li><li>Mutton Chops Beard and Hair</li><li>Shirt and Pants</li></ul></td>
</tr>
</tbody>
</table>
## Import face accessories
You can import and equip face accessories that you want to deform with the facial expressions of your head. For example, when you import and equip eyebrows as a face accessory, you can animate the eyebrows to move with the character's eyes.
By default, when you import a face accessory, it imports as a `Class.MeshPart` object. Using the [Accessory Fitting Tool](../../../art/accessories/accessory-fitting-tool.md) (AFT), you can convert the `Class.MeshPart` into an `Class.Accessory` instance that is compatible with the head.
To import a face accessory:
1. From Studio's **File** menu, use the [3D Importer](../../../art/modeling/3d-importer.md) to import the custom model into the workspace.
<img src="../../../assets/avatar/dynamic-heads/using-dynamic-heads-in-studio/Importing-Facial-Accessory-Final-Result.jpg" width="80%" />
2. Using the AFT, convert the `Class.MeshPart` into an `Class.Accessory` instance.
1. In the toolbar's **Avatar** tab, click **Accessory** to open the AFT.
2. In the **Explorer** window, select the **MeshPart** you imported as a face accessory. Its name displays in the **Part** field.
3. Click the **Next** button.
4. In the **Clothing** category, select **Face**, then click the **Next** button.
5. (Optional) In the **Edit** panel, use the adjustment options to ensure the accessory fits your model.
6. In the **Preview** panel, preview the new facial accessory on your head, then click the **Next** button. The tool transforms the `Class.MeshPart` into an `Class.Accessory` instance, and it displays in the **Explorer** window.
You can preview the accessory on your imported model by making the `Class.Accessory` instance a child of your character `Class.Model`. You can only equip character-specific face accessories with their designed character.
<GridContainer numColumns="2">
<figure>
<img src="../../../assets/avatar/dynamic-heads/using-dynamic-heads-in-studio/Facial-Accessory-In-Viewport.jpg" />
<figcaption>Equipped accessory in viewport</figcaption>
</figure>
<figure>
<img src="../../../assets/avatar/dynamic-heads/using-dynamic-heads-in-studio/Facial-Accessory-In-Property-Panel.jpg" />
<figcaption>Equipped Accessory in Explorer</figcaption>
</figure>
</GridContainer>
You can also save the `Class.Accessory` instance to your toolbox and use the asset ID at any time in your experiences. For information on equipping accessories by applying a `Class.HumanoidDescription`, see [Customize characters with humanoid description](../../../characters/appearance.md#set-multiple-accessories).
### AutoSkin property
You can enable the `Class.WrapLayer.AutoSkin` property in the accessory's `Class.WrapLayer` instance to apply the skinning of the head to the face accessory. This allows a face accessory to fit and follow a character's expressions without having to apply any skinning influences to it during the 3D modeling process.
The following options are available for the `Class.WrapLayer.AutoSkin` property:
- **Disabled**: Disables the Automatic Skinning Transfer process. This is the default value.
- **EnabledOverride**: Enables the Auto-Skin Transfer process and allows Studio to override any existing skinning information found on the accessory. Choose this setting when you want to set or replace the existing skinning of an accessory using the Auto-Skin Transfer version.
- **EnabledPreserve**: Enables the Automatic Skinning Transfer process but **doesn't** allow it to override any existing skinning information found on the accessory. Choose this setting when you want to preserve and maintain any existing skinning of an accessory. If there isn't any skinning to maintain, the Auto-Skin Transfer creates new skinning automatically.
## Animate heads
Animatable head `Class.MeshPart|MeshParts` include a `Class.FaceControls` instance which allows you to access your facial pose properties.
<GridContainer numColumns="2">
<figure>
<img src="../../../assets/avatar/dynamic-heads/using-dynamic-heads-in-studio/FaceControls-In-Explorer.jpg" />
<figcaption>FaceControls in Explorer</figcaption>
</figure>
<figure>
<img src="../../../assets/avatar/dynamic-heads/using-dynamic-heads-in-studio/FaceControls-In-Property-Panel.jpg" />
<figcaption>FaceControls Property Panel</figcaption>
</figure>
</GridContainer>
You can adjust these properties in the **Animation Editor** to animate your head. For more information, see [Animate heads](../../../art/characters/facial-animation/animate-heads.md).
## Troubleshooting
When importing custom head models, the [Output window](../../../studio/output.md) displays an error or warning message if there were any issues during the configuration process.
### Error messages
Error messages indicate a failure to properly import a model with a head. Reference the following table for a summary of all head error messages and troubleshooting tips:
<table>
<thead>
<tr>
<th>Error message</th>
<th>Troubleshooting</th>
</tr>
</thead>
<tbody>
<tr>
<td>Failed importing head with facial animation.</td>
<td>The <kbd>.fbx</kbd> file is corrupted.</td>
</tr>
<tr>
<td>Found more than one joint named X. All joints must have unique names.</td>
<td>Ensure that every joint that you import has a unique name.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Correctives can be for at most 3 control names.</td>
<td>Studio found a corrective with more than 3 corrective poses. This isn't supported, so you need to delete the corrective.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Unrecognized FACS control name X.</td>
<td>X is an unrecognized FACS pose name. Ensure that X is renamed to one of the [standard FACS poses](../../../art/characters/facial-animation/facs-poses-reference.md).</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Invalid corrective name X: Neutral cannot be part of a corrective.</td>
<td>X is an invalid corrective name. Ensure you are following the correct naming format for correctives.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Found duplicate FACS control name X for corrective Y.</td>
<td>X is an invalid corrective name. You can only include a base pose that is listed as part of a corrective once in the corrective name.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Couldn't parse the frame number in Extra Attribute named X.</td>
<td>You must name any extra attributes "Frame0", "Frame1", etc.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Empty value found for Extra Attribute named X.</td>
<td>The extra attribute X has no value. Add a base pose name or corrective, or delete the extra attribute.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Duplicate control name found.</td>
<td>You set a FACS pose or corrective to multiple frames. Ensure that each FACS pose or corrective is set to only a single frame.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Head_Geo has no Extra Attributes that map FACS controls to animation frames.</td>
<td>The "Head_Geo" mesh in the FBX file must have extra attributes in order to animate facial expressions. The imported avatar will not animate facial expressions.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: No frame was set to "Neutral" in animation.</td>
<td>Must have one frame set to "Neutral" in the animation timeline.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: X has not been specified. This is needed for corrective Y.</td>
<td>All base poses for a corrective must be set in the extra attributes. For example, if the <kbd>Funneler_JawDrop</kbd> corrective is set, then there <b>must</b> be poses for <kbd>Funneler</kbd> and <kbd>JawDrop</kbd> alone.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: Missing key frame X for Y.</td>
<td>There is an extra attribute "FrameX" set to Y, but the animation timeline has no frame X.</td>
</tr>
<tr>
<td>Failed importing head with facial animation: No joints were found under DynamicHead.</td>
<td>The <kbd>.fbx</kbd> file doesn't have any joints under the RootFaceJoint joint.</td>
</tr>
<tr>
<td>Could not load FACS control data.</td>
<td>There are corrupted joint parameters in the <kbd>.fbx</kbd> file.</td>
</tr>
</tbody>
</table>
### Warning messages
Warning messages indicate a potential issue with an imported head model. Reference the following table for a summary of all head warning messages and troubleshooting tips:
<table>
<thead>
<tr>
<th>Error message</th>
<th>Troubleshooting</th>
</tr>
</thead>
<tbody>
<tr>
<td>You have corrective X, but missing corrective Y to support it. This may cause odd deformations.</td>
<td>You set a 3-corrective without setting the base 2-corrective. The imported head will animate, but there might be strange deformations.</td>
</tr>
<tr>
<td>Skipping attribute X: Y</td>
<td>Studio found an extra attribute named X, but since it didn't match the format of "Frame#", it was ignored.</td>
</tr>
<tr>
<td>Control X is nearly identical to Neutral.</td>
<td>The pose for X is very similar to Neutral. Studio reports this in case this was a mistake, but the import will be successful as long as there are no other failures.</td>
</tr>
<tr>
<td>Found only N base poses. Your character may not be able to express itself.</td>
<td>You only defined a subset of base poses in the <kbd>.fbx</kbd> file. The import will still be successful as long as there are no other failures.</td>
</tr>
</tbody>
</table>

88
.cursor/rules/roblox/art/characters/import.md Normal file
View file

@ -0,0 +1,88 @@
---
title: Import character bodies
description: Use the 3D Importer to add third-party models to Studio before testing, using, or uploading the character model.
---
Use the following instructions to import a full character body model into Studio as a `Model` object that you can save to use in your experience, share with others, or upload to the Marketplace.
<Alert severity ='info'>
If you are using a single-mesh character body for the Roblox Auto-Setup tool, see [Avatar auto-setup](../../avatar-setup/).
</Alert>
Studio's 3D Importer provides a quick and easy way to import third-party 3D assets into your projects. The importer provides object previews and error-checking to ensure that your asset meets Roblox's [general 3D requirements](../modeling/specifications.md).
Keep in mind, your character model must also follow Roblox's [avatar character specifications](../characters/specifications.md) to use or sell this asset as an avatar-ready character model, or you may experience errors later in the workflow.
To import your asset:
1. From Studio's **File** menu, select **3D Importer**.
2. In the file browser, select the `.fbx` or `.gltf` file saved locally. The 3D Importer loads a preview of the object.
<img src="../../assets/art/avatar/Avatar-3D-Importer.png" width = "60%"/>
- If textures don't load for your asset, you can manually import your textures later.
- See [3D importer](../../art/modeling/3d-importer.md) for additional information on import settings and troubleshooting.
3. To begin body validation after import, enable **Validate UGC Body**. This can save you time if you intend on uploading your body to the Marketplace.
4. Set the **Rig Scale** to the appropriate [Body Scale](../characters/specifications.md#body-scale) of your character.
<img src="../../assets/art/avatar/Avatar-Rig-Scale.png" width = "60%"/>
5. Select **Import**. The asset populates in your workspace as a `Class.Model` with the appropriate textures applied as a `Class.SurfaceAppearance` or `Class.MeshPart.TextureID`.
<BaseAccordion>
<AccordionSummary>Manually add textures</AccordionSummary>
<AccordionDetails>
If textures didn't load correctly, add them manually. You may need to save and publish your experience in order to access the [Asset Manager](../../projects/assets/manager.md).
1. In the **Asset Manager**, click the **Import** button.
2. Upload your image files.
3. After moderation clears for your image, select the `Class.MeshPart` parented within your imported `Class.Model`.
4. If you are using a single basic texture, set the `Class.MeshPart.TextureID` property to your uploaded texture image.
5. If you are using PBR textures:
1. Add a `Class.SurfaceAppearance` child to your `Class.MeshPart`.
<img src="../../assets/art/avatar/Avatar-Surface-Appearance.png" />
2. In the `Class.SurfaceAppearance` properties, click each property value and assign the appropriate texture image from the asset dropdown:
1. Set the **ColorMap** to the **\_ALB** texture image.
2. Set the **MetalnessMap** to the **\_MTL** texture image.
3. Set the **NormalMap** to the **\_NOR** texture image.
4. Set the **RoughnessMap** to the **\_RGH** texture image.
<img src="../../assets/art/avatar/Avatar-Roughness-Map.png" />
</AccordionDetails>
</BaseAccordion>
<Alert severity = 'success'>
After successful import, your model object should populate in your project as a `Class.Model` with the appropriate textures applied.
</Alert>
After successful fitting and converting, your 3D model should populate in your project as an `Class.Model`.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/art/avatar/Avatar-Studio-Example.png" />
<figcaption>Avatar-ready character model in Workspace</figcaption>
</figure>
<figure>
<img src="../../assets/art/avatar/Avatar-Data-Model.png" />
<figcaption>Avatar-ready character model in Explorer</figcaption>
</figure>
</GridContainer>
<Alert severity = 'warning'>
Character creation is a complex process that requires lots of testing and iteration. See [Test characters](../../art/characters/testing/index.md) for steps on importing your character model into a test place and verifying your avatar and related components.
</Alert>
With this new character `Class.Model`, you can perform any of the following:
- Begin the process of [uploading and publishing](../../marketplace/publish-to-marketplace.md#upload-an-asset) the character model to the Marketplace. This involves some additional validation and moderation steps.
- Use the model in your current experience and modify the model's appearance with [HumanoidDescription](../../characters/appearance.md#manually-modify-appearance).
- Playtest as the character by renaming the `Class.Model` to `StarterCharacter` and moving the `Class.Model` to the `Class.StarterPlayer` folder in the **Explorer** before play testing.
- Save the model to your [Toolbox](../../projects/assets/toolbox.md) or make it public on the [Creator Store](../../production/creator-store.md) to share or use within any of your experiences.

187
.cursor/rules/roblox/art/characters/index.md Normal file
View file

@ -0,0 +1,187 @@
---
title: Avatar characters
description: All Roblox users are represented by an avatar character which can be customized with body parts, accessories, and clothes from the Marketplace or within experiences.
---
<iframe width="800" height="450" src="https://www.youtube-nocookie.com/embed/2My8jE47clI" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<br /><br />
Every Roblox user is represented by a customizable character called an **avatar**. Avatars are character models with many specialized features that allow users to interact with the world and customize themselves with a wide range of clothing and accessories from the Marketplace.
Custom avatars are first created in 3D modeling programs, such as [Blender](https://www.blender.org/) or [Maya](https://www.autodesk.com/products/maya/overview), before importing into Studio. To create a custom Roblox avatar character for your own experience, it's important to start with the following:
- An advanced background with 3D modeling tools such as [Blender](https://www.blender.org/) or [Maya](https://www.autodesk.com/products/maya/overview).
- An understanding of the [components that make up an avatar character](#components-of-an-avatar).
- An understanding of the general [character creation process](#creation-process).
- Review the [basic character creation tutorial](../characters/creating/index.md) to get started on creating your first avatar character using Roblox's templates.
- [Various tools, resources, and guides](#resources) provided by Roblox to standardize and expedite the creation process.
## Components of an avatar
All avatar character models are made up of several fundamental components that provide users the functionality and flexibility to interact with their world. Many of these components are never made visible to the user, but they enable powerful avatar features that enhance social and environmental interactions. When creating avatar characters, all of these components are typically created first in your modeling software and then converted to their appropriate Roblox Studio instance on import.
Each avatar character is made up of the following rendered and non-rendered components:
<Tabs>
<TabItem label="Rendered">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Component-Body-Parts.png" /> <figcaption>15 body part meshes make up the physical aspects of the character model</figcaption></figure>
<figure><img src="../../assets/art/avatar/Component-Texture-Map.png" /><figcaption>Texture image maps apply a surface color and appearance. Transparency allows underlying part colors to be exposed, such as custom skin tones.</figcaption></figure>
</GridContainer>
</TabItem>
<TabItem label="Non-Rendered">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Component-Rigging.png" /> <figcaption>A rigging armature allows the body parts to properly connect with each other, driving movement, expressions, and animations</figcaption></figure>
<figure><img src="../../assets/art/avatar/Component-Facial-Animation-Data.png" /> <figcaption>Facial animation data allows avatars to express virtually all types of facial expressions for chatting and socializing</figcaption></figure>
</GridContainer>
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Component-Cage-Mesh.png" /> <figcaption>Cage meshes set the outer boundary of the character, defining the surface where clothing and other layerable items can wrap and stretch over.</figcaption></figure>
<figure><img src="../../assets/art/avatar/Component-Attachments.png" /> <figcaption>Attachment points define where rigid accessories attach to a character</figcaption></figure>
</GridContainer>
</TabItem>
</Tabs>
### Body parts
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Body-Parts-Visual.png" /> <figcaption>Each avatar character is made up of 15 separate mesh objects</figcaption></figure>
<figure><img src="../../assets/art/avatar/Body-Parts-Data-Model.png" width="80%"/><figcaption>These meshes must follow a standard naming convention</figcaption></figure>
</GridContainer>
Roblox avatar characters are made up of 15 body parts, pieces of geometry that define the shape and contours of your avatar character. In Studio, these geometries are represented as `Class.MeshPart` objects and are nested under a single `Class.Model`.
### Textures
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Textures-Brown.png" /> <figcaption>Textures apply color and surface details to your character model.</figcaption></figure>
<figure><img src="../../assets/art/avatar/Textures-Blue.png" /><figcaption>A texture image map's opacity can combine with the `Class.MeshPart.Color` to apply custom skin tones to characters.</figcaption></figure>
</GridContainer>
Textures are image files that define the surface appearance of your character. You can create textures using a texture painting program or a 3D modeling software. In Studio, you must import textures as image files and access them through the `Class.SurfaceAppearance` instance, or set as a `Class.MeshPart.TextureID` property.
<Alert severity = 'warning'>
When texturing parts of your character model's body, ensure that your character model includes a modesty layer over sensitive regions. See [Community Standards](https://en.help.roblox.com/hc/en-us/articles/203313410#safety) for more information on Roblox's policies.
</Alert>
### Rigging armature
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Rigging-Visual.png" /> <figcaption>The armature is made up of 16 bones, 1 for each body part geometry and a root bone</figcaption></figure>
<figure><img src="../../assets/art/avatar/Rigging-Data-Model.png" /><figcaption>Bones must follow a specific hierarchy and naming convention</figcaption></figure>
</GridContainer>
An armature allows each character to articulate its limbs and move naturally through the environment. Often referred to as bones or joints, this rigging character information includes skinning data which allows connected limbs, like the knees or elbows to bend organically. In Studio, each bone of the character armature is represented by `Class.Bone` objects that connect the character `Class.MeshPart` objects together.
### Face animation data
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Facial-Rig-Visual.png" /> <figcaption>Each avatar character face is rigged and skinned to create various expressions</figcaption></figure>
<figure><img src="../../assets/art/avatar/Facial-Properties.png" /><figcaption>Each pose is mapped to a pose name within the Custom Properties (Extra Attributes in Maya) of the Head_Geo object</figcaption></figure>
</GridContainer>
<figure><img src="../../assets/art/avatar/Facial-Animation-Timeline.png" /><figcaption>Each required face pose is saved as a keyframe in the animation timeline.</figcaption></figure>
Facial animation data allow each character to use global facial expressions. Each character includes facial bones and skinning, animation timeline data, and mapped pose data that allows it. In Studio, these facial animation elements are represented by a `Class.FaceControls` instance.
### Cage meshes
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Cage-Mesh-Visual.png" /> <figcaption>Head and Upper Torso cage mesh objects (wireframe)</figcaption></figure>
<figure><img src="../../assets/art/avatar/Cage-Mesh-Data-Model.png" width="80%"/><figcaption>Cage objects must exist for each of the 15 body parts</figcaption></figure>
</GridContainer>
This outer cage sets the invisible surface on which layerable accessories, such as clothing, will stretch and fit over the body. These cage meshes allow clothes to fit over models of different shapes and sizes without having to remodel the clothing item. In Studio, outer cage mesh objects are represented by a `Class.WrapTarget` instance.
If you are caging your own non-template character model, it's important to use one of Roblox's body cage [project files](../../avatar/resources.md#mannequin-models) to ensure you are using a Roblox standard cage mesh. Removing or adding vertices from this standard mesh can cause issues with clothing fit and import.
### Attachments
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/Attachments-Visual.png" /> <figcaption>Each character has common attachment points for equipping rigid cosmetics</figcaption></figure>
<figure><img src="../../assets/art/avatar/Attachments-Data-Model.png" width="70%"/><figcaption>Each avatar character must include their associated 19 attachment points</figcaption></figure>
</GridContainer>
Attachment points define where rigid 3D accessories and equipables attach to the character's body. These are not rendered to the end-user but are represented as sphere geometries in 3D modeling software and, when imported into Studio, these geometries are created as `Class.Attachment` instances using the standardized names.
When wearing layered clothing, the clothing isn't attached directly to the attachment, but it does reference the associated attachment point during ragdoll and dismemberment animations.
## Creation process
When designing an avatar model, you must export all of the avatar components in a single `.fbx` or `.gltf` for import into Studio. Since 3D creation isn't a linear process and always requires reiteration and testing, the process of creating an avatar character model can differ between individuals and various creation workflows.
In general, the creation process follows these typical workflows:
<GridContainer numColumns="2">
<figure><figcaption><center>Basic Creation with Templates</center></figcaption><img src="../../assets/art/avatar/Workflow-Bodies-Templates.png"/><figcaption>Customize a Roblox template character that already includes all the necessary components. See [Create with templates](../characters/creating/index.md) for guides and instructions.</figcaption></figure>
<figure><figcaption><center>Advanced Creation from Scratch</center></figcaption><img src="../../assets/art/avatar/Workflow-Bodies-Traditional.png"/><figcaption>Create characters from scratch, allowing full customization of the avatar character's components.</figcaption></figure>
</GridContainer>
<Alert severity = 'warning'>
Ensure that all assets you create follow any applicable [Marketplace policies](../../marketplace/marketplace-policy.md) and [Roblox Community Standards](https://en.help.roblox.com/hc/en-us/articles/203313410-Roblox-Community-Standards).
</Alert>
## Resources
There are a variety of resources available for creators of all backgrounds to get started with character creation.
If you are interested in specific avatar creation topics, use the following table to find guides and resources that best match your needs:
<table>
<thead>
<tr>
<th>Topic</th>
<th>Resources</th>
</tr>
</thead>
<tbody>
<tr>
<td>Tutorials</td>
<td>[Basic character creation tutorial](../accessories/creating/index.md)</td>
</tr>
<tr>
<td>Reference files</td>
<td>[Avatar references and project files](../characters/project-files.md)<br /><br />[Example mesh/model objects](../modeling/project-files.md)</td>
</tr>
<tr>
<td>Technical specs</td>
<td>[.FBX export settings](../characters/export-settings.md)<br /><br />[Avatar specifications](../characters/specifications.md)<br /><br />[General mesh specifications](../modeling/specifications.md)<br /><br />[Accessory specifications](../accessories/specifications.md)<br /><br />[Marketplace policy](../../marketplace/marketplace-policy.md)</td>
</tr>
<tr>
<td>Cosmetic creation</td>
<td>[Accessories overview](../accessories/index.md)<br /><br />[Creating face accessories](../characters/facial-animation/create-face-accessories.md)<br /><br />[Accessory Fitting Tool](../accessories/accessory-fitting-tool.md)<br /><br />[Accessory specifications](../accessories/specifications.md)<br /><br />[Marketplace requirements](../../marketplace/marketplace-policy.md)</td>
</tr>
<tr>
<td>Texturing</td>
<td>[Texturing requirements](../modeling/texture-specifications.md)<br /><br />[PBR textures](../modeling/surface-appearance.md)</td>
</tr>
<tr>
<td>Rigging and skinning</td>
<td>[Rigging and skinning overview](../modeling/rigging.md)<br /><br />[Humanoid rig requirements](../characters/specifications.md#rig)<br /><br />[Rigging facial bones](../characters/facial-animation/create-basic-heads.md#rig)<br /><br />[Automatic Skinning Transfer](../accessories/automatic-skinning-transfer.md)<br /><br />[Skinning facial bones](../characters/facial-animation/create-basic-heads.md#skin-face-bones)</td>
</tr>
<tr>
<td>Facial animation and live heads</td>
<td>[Basic head creation](../characters/facial-animation/create-basic-heads.md)<br /><br />[Face accessory creation](../characters/facial-animation/create-face-accessories.md)<br /><br />[FACS pose references](../characters/facial-animation/facs-poses-reference.md)</td>
</tr>
<tr>
<td>Testing and validation</td>
<td>[Calisthenics Tool](../modeling/calisthenics-tool.md)<br /><br />[Clothing Validation Tool](../accessories/validation-tool.md)</td>
</tr>
<tr>
<td>Publishing and Marketplace</td>
<td>[Uploading to Marketplace](../../marketplace/publish-to-marketplace.md)<br /><br />[Marketplace policy](../../marketplace/marketplace-policy.md)<br /><br />[Fees and commissions](../../marketplace/marketplace-fees-and-commissions.md)</td>
</tr>
</tbody>
</table>

216
.cursor/rules/roblox/art/characters/project-files.md Normal file
View file

@ -0,0 +1,216 @@
---
title: Avatar project files and references
description: Download various character-related project files and reference files.
---
<Alert severity = 'info'>
See [Resources](../../avatar/resources.md) for a complete list of avatar-related downloadable content.
</Alert>
## Project files
The following `.fbx`, `.blend`, and `.ma` project files are available to use as examples, boilerplate, or reference:
<Tabs>
<TabItem label="Models">
<table>
<thead>
<tr>
<th>Filename</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../../assets/modeling/skinned-meshes/Lola.fbx" download>Lola.fbx</a></td>
<td>A skinned R15 character created from the <a href="../../art/modeling/skin-a-humanoid-model.md">Skin a humanoid model</a> guide. Since this reference model doesn't yet have [inner and outer cage mesh data](../../art/characters/specifications.md#inner-and-outer-cages), this model can't equip layered clothing or accessories.</td>
</tr>
<tr>
<td><a href="../../assets/avatar/dynamic-heads/reference-files/Fish-Person.zip" download>Fish-Person.zip</a></td>
<td>A rigged and skinned humanoid character model with a full body cage, facial animation rig, and associated PBR texture maps.</td>
</tr>
<tr>
<td><a href="../../assets/avatar/dynamic-heads/reference-files/BlockyCharacter.fbx" download>BlockyCharacter.fbx</a></td>
<td>A Blocky character model with an [animatable head](../../art/characters/facial-animation/index.md) and a full body cage.</td>
</tr>
<tr>
<td><a href="../../assets/avatar/dynamic-heads/reference-files/GoblinCharacter.zip" download>GoblinCharacter.zip</a></td>
<td>A Goblin character model with an [animatable head](../../art/characters/facial-animation/index.md) and a full body cage.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/ClassicMannequin.fbx" download>ClassicMannequin.fbx</a></td>
<td>A [classic body](../../art/characters/specifications.md#classic) type blank mannequin to use in Studio or your modeling application.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/ClassicMannequin_With-Cages.fbx" download>ClassicMannequin_With-Cages</a></td>
<td>A [classic](../../art/characters/specifications.md#classic) body type blank mannequin with **body cages** to use in Studio or your modeling application for clothing design. Due to unconfigured cage objects, this file may not import correctly into Studio until modified.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/RthroMannequin.fbx" download>RthroMannequin.fbx</a></td>
<td>An [Rthro Normal](../../art/characters/specifications.md#normal) body type blank mannequin to use in Studio or your modeling application.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/RthroMannequin_With-Cages.fbx" download>RthroMannequin_With-Cages.fbx</a></td>
<td>An [Rthro Normal](../../art/characters/specifications.md#normal) body type blank mannequin with **body cages** to use in Studio or your modeling application for clothing design to use in Studio or your modeling application. Due to unconfigured cage objects, this file may not import correctly into Studio until modified.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/RthroSlenderMannequin.fbx" download>RthroSlenderMannequin.fbx</a></td>
<td>An [Rthro Slender](../../art/characters/specifications.md#slender) body type blank mannequin to use in Studio or your modeling application.</td>
</tr>
<tr>
<td><a href="../../assets/art/reference-files/RthroSlenderMannequin_With-Cages.fbx" download>RthroSlenderMannequin_With-Cages.fbx</a></td>
<td>An [Rthro Slender](../../art/characters/specifications.md#slender) body type blank mannequin with **body cages** to use in Studio or your modeling application to use in Studio or your modeling application for clothing design. Due to unconfigured cage objects, this file may not import correctly into Studio until modified.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Blender">
<table>
<thead>
<tr>
<th><b>File</b></th>
<th><b>Description</b></th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Rig_and_Attachments_Templates.zip" download>Rig_and_Attachments_Template.blend</a></td>
<td>Starting armature rig template for Blender. Contains an armature with correct R15 naming conventions and attachment points. Use this template for rigging bodies and clothing items.</td>
</tr>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Body_Cage_Templates.zip" download>Body_Cage_Template.blend</a></td>
<td>Starting template for Blender, includes individual body part cages for each 15 humanoid parts. Use this template for caging your avatar bodies. <br /> <br /> <Alert severity='info'>To save time, edit the full-body `std_cage_deformable` mesh to automatically apply vertex changes to the individual body-part meshes. When importing the `.fbx` into Studio, you can remove this helper mesh.</Alert></td>
</tr>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Combined_Templates.zip" download>Combined-Template.blend</a></td>
<td>Template file containing all content from previous templates, includes rig skeleton, body cages, attachment points. Use this template to rig and cage bodies and accessories.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Maya">
<table>
<thead>
<tr>
<th><b>File</b></th>
<th><b>Description</b></th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Rig_and_Attachments_Templates.zip" download>Rig_and_Attachments_Template.ma</a></td>
<td>Starting armature rig template for Maya. Contains an armature with correct R15 naming conventions and attachment points. Use this template for creating bodies and clothing items.</td>
</tr>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Body_Cage_Templates.zip" download>Body_Cage_Template.ma</a></td>
<td>Starting template for Maya, includes individual body part cages for each 15 humanoid parts. Use this template for caging your avatar bodies. <br /> <br /> <Alert severity='info'>To save time, edit the full-body `std_cage_deformable` mesh to automatically apply vertex changes to the individual body-part meshes. When importing the `.fbx` into Studio, you can remove this helper mesh.</Alert></td>
</tr>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Combined_Templates.zip" download>Combined-Template.ma</a></td>
<td>Template file containing all content from previous templates, includes rig skeleton, body cages, attachment points. Use this template to rig and cage bodies and accessories.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="General">
<Alert severity = 'warning'>
The following `.fbx` files were exported from Maya for use in modeling applications. If you are using Blender or Maya in your workflow, use the specific template files for those programs instead of the following files.
</Alert>
<table>
<thead>
<tr>
<th><b>File</b></th>
<th><b>Description</b></th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Rig_and_Attachments_Templates.zip" download>Rig_and_Attachments_Template.fbx</a></td>
<td>Starting armature rig template for general modeling software. Contains an armature with correct R15 naming conventions and attachment points. Use this template for creating bodies and clothing items.</td>
</tr>
<tr>
<td><a href="../../assets/modeling/meshes/reference-files/Body_Cage_Templates.zip" download>Body_Cage_Template.fbx</a></td>
<td>Starting template for general modeling software, includes individual body part cages for each 15 humanoid parts. Use this template for caging your avatar bodies. <br /> <br /> <Alert severity='info'>To save time, edit the full-body `std_cage_deformable` mesh to automatically apply vertex changes to the individual body-part meshes. When importing the `.fbx` into Studio, you can remove this helper mesh.</Alert></td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>
## Templates
If you are creating character models, you can choose from a variety of starting templates that best match your final design and save time on creating the [avatar components](../../art/characters/index.md#components-of-an-avatar). See [Create with templates](../../art/characters/creating/index.md#template-files) for important information on using these template files.
Each `.zip` contains a `.blend`, `.fbx`, and PBR texture `.png` files for that template model. If using Blender or following the [template creation guides](../../art/characters/creating/index.md), use the `.blend` project.
<Alert severity = 'warning'>
If you are using Roblox's avatar template files, you must perform the [cleanup steps](../../art/characters/creating/combine-head-geometry.md) in order for the assets to properly validate before publishing to the Marketplace.
</Alert>
<Tabs>
<TabItem label="Head Shapes">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Round-Head-Templates.png"/><figcaption><center>Round</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../assets/art/reference-files/RoundFemale.zip">RoundFemale.zip</a> <br />
Male: <a href="../../assets/art/reference-files/RoundMale.zip">RoundMale.zip</a>
</figure>
</GridContainer>
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Square-Head-Templates.png" /><figcaption><center>Square</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../assets/art/reference-files/SquareFemale.zip">SquareFemale.zip</a> <br />
Male: <a href="../../assets/art/reference-files/SquareMale.zip">SquareMale.zip</a>
</figure>
</GridContainer>
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Muzzle-Head-Templates.png" /><figcaption><center>Muzzle</center></figcaption></figure>
<figure>
<br /><br />
Female: <a href="../../assets/art/reference-files/MuzzleFemale.zip">MuzzleFemale.zip</a> <br />
Male: <a href="../../assets/art/reference-files/MuzzleMale.zip">MuzzleMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Realistic">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/SemiRealistic-Templates.png"/><figcaption><center>Realistic</center></figcaption></figure>
<figure>
Female: <a href="../../assets/art/reference-files/SemiRealisticFemale.zip">SemiRealisticFemale.zip</a> <br />
Male: <a href="../../assets/art/reference-files/SemiRealisticMale.zip">SemiRealisticMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Anime">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Anime-Templates.png"/><figcaption><center>Anime</center></figcaption></figure>
<figure>
Female: <a href="../../assets/art/reference-files/AnimeFemale.zip">AnimeFemale.zip</a> <br />
Male: <a href="../../assets/art/reference-files/AnimeMale.zip">AnimeMale.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Stylized">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Stylized-Templates.png"/><figcaption><center>Stylized</center></figcaption></figure>
<figure>
Single body: <a href="../../assets/art/reference-files/StylizedHuman.zip">Stylized.zip</a>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Caricature">
<GridContainer numColumns="2">
<figure><img src="../../assets/art/avatar/templates/Caricature-Templates.png"/><figcaption><center>Caricature</center></figcaption></figure>
<figure>
Single body: <a href="../../assets/art/reference-files/Caricature.zip">Caricature.zip</a>
</figure>
</GridContainer>
</TabItem>
</Tabs>

738
.cursor/rules/roblox/art/characters/specifications.md Normal file
View file

@ -0,0 +1,738 @@
---
title: Character specifications
description: Character specification lists the specific technical requirements for custom characters created outside of Studio.
---
Character models require a specific set of components and configuration standards to ensure all avatar features work as expected. Check that your model meets the following modeling specifications and guidelines before exporting to ensure Studio compatibility.
When ready to export, see the [export requirements](../../art/characters/export-settings.md) for mesh export settings for Blender and Maya.
<Alert severity = 'warning'>
<AlertTitle>If creating other types of 3D models:</AlertTitle>
<ul>
<li>For generic meshes, see [general mesh specifications](../modeling/specifications.md) and [general export settings](../modeling/export-requirements.md).</li> <br />
<li>For rigid accessories, see [accessory specifications](../accessories/specifications.md) and [accessory export settings](../accessories/export-settings.md).</li> <br />
<li>For layered accessories, see [layered accessory specifications](../accessories/clothing-specifications.md) and [layered export settings](../accessories/clothing-export-settings.md).</li> <br />
</ul>
</Alert>
## Geometry
Avatar character models are made up of 15 separate mesh objects and require additional geometry requirements to import into Studio and publish successfully. In addition to the body [types](#body-scale), [parts](#body-parts), and [budget](#triangle-budgets) specifications, ensure that your models also fulfill the following general requirements when modeling:
- **Watertight** - All geometry must be watertight without exposed holes or backfaces. Meshes used as outer cages do not need to be watertight.
- **No N-gons** - Model your assets in quads where possible.
- **Transformations** - All translation, rotation, and scale values must be frozen and pivots set to `0`, `0`, `0`.
- **Orientation** - Characters must face positive Z and stand up in positive Y.
- **Pose** - Before exporting, set your character to an I-Pose, A-Pose, or T-Pose when possible.
### Body scale
Roblox supports 3 standards of body scales: **Normal**, **Slender**, and **Classic**. These standards allow developers to create experiences and spaces with consistent body sizes for standardizing movement and interaction. You can select a body scale on import using [Rig Scale options](../modeling/3d-importer.md#rig-general), or modify the [body scale manually](../../art/accessories/body-scale.md). Body scale persists when the asset is [uploaded to the Marketplace](../../marketplace/publish-to-marketplace.md#upload-an-asset).
<center>
<figure>
<img src="../../assets/art/Body-Scale-Diagram.png" width = "60%"/>
<figcaption>
A visualization of how Roblox combines the 15 body parts into 6 distinct assets.
</figcaption>
</figure>
</center>
<Alert severity='warning'>
Since body assets partially overlap with each other, the total body dimensions do not represent the sum of the avatar's asset dimensions. The total body dimension is the most important factor of each body scale to ensure a standard avatar size and scale.
</Alert>
#### Normal
<center>
<figure>
<img src="../../assets/art/resources/Body-Scale-Rthro-Normal.png" width = "60%"/>
<figcaption>
A Rthro Normal body scale [downloadable mannequin](../../avatar/resources.md#references).
</figcaption>
</figure>
</center>
In the [3D importer](../../art/modeling/3d-importer.md#avatar-general), use **Rig Type** > **Rthro** to import your model as a Normal body scale.
<br />
<GridContainer numColumns="2">
<figure>
<figcaption><center>Minimum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>.5</td>
<td>.5</td>
<td>.5</td>
</tr>
<tr>
<td>Arm</td>
<td>.25</td>
<td>1.5</td>
<td>.25</td>
</tr>
<tr>
<td>Torso</td>
<td>.85</td>
<td>1.7</td>
<td>.7</td>
</tr>
<tr>
<td>Leg</td>
<td>.25</td>
<td>1.4</td>
<td>.5</td>
</tr>
<tr>
<td>**Total**</td>
<td>**1.35**</td>
<td>**3.6**</td>
<td>**.7**</td>
</tr>
</tbody>
</table>
</figure>
<figure>
<figcaption><center>Maximum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>3</td>
<td>2</td>
<td>2</td>
</tr>
<tr>
<td>Arm</td>
<td>2</td>
<td>4.5</td>
<td>2</td>
</tr>
<tr>
<td>Torso</td>
<td>4.6</td>
<td>3.5</td>
<td>2.25</td>
</tr>
<tr>
<td>Leg</td>
<td>1.5</td>
<td>4</td>
<td>2</td>
</tr>
<tr>
<td>**Total**</td>
<td>**8.6**</td>
<td>**9.5**</td>
<td>**2.25**</td>
</tr>
</tbody>
</table>
</figure>
</GridContainer>
#### Slender
<center>
<figure>
<img src="../../assets/art/resources/Body-Scale-Rthro-Slender.png" width = "60%"/>
<figcaption>
A Rthro Slender (Narrow) body scale [downloadable mannequin](../../avatar/resources.md#references).
</figcaption>
</figure>
</center>
In the [3D importer](../../art/modeling/3d-importer.md#avatar-general), use **Rig Type** > **Rthro Narrow** to import your model as a Slender body scale.
<br />
<GridContainer numColumns="2">
<figure>
<figcaption><center>Minimum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>.5</td>
<td>.5</td>
<td>.5</td>
</tr>
<tr>
<td>Arm</td>
<td>.25</td>
<td>1.5</td>
<td>.25</td>
</tr>
<tr>
<td>Torso</td>
<td>.85</td>
<td>1.7</td>
<td>.7</td>
</tr>
<tr>
<td>Leg</td>
<td>.25</td>
<td>1.4</td>
<td>.5</td>
</tr>
<tr>
<td>**Total**</td>
<td>**1.35**</td>
<td>**3.6**</td>
<td>**.7**</td>
</tr>
</tbody>
</table>
</figure>
<figure>
<figcaption><center>Maximum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>2</td>
<td>2</td>
<td>2</td>
</tr>
<tr>
<td>Arm</td>
<td>1.5</td>
<td>4</td>
<td>2</td>
</tr>
<tr>
<td>Torso</td>
<td>3</td>
<td>3.5</td>
<td>2</td>
</tr>
<tr>
<td>Leg</td>
<td>1.5</td>
<td>4</td>
<td>2</td>
</tr>
<tr>
<td>**Total**</td>
<td>**6**</td>
<td>**9.5**</td>
<td>**2**</td>
</tr>
</tbody>
</table>
</figure>
</GridContainer>
#### Classic
<center>
<figure>
<img src="../../assets/art/resources/Body-Scale-Classic.png" width = "60%"/>
<figcaption>
A Classic body scale [downloadable mannequin](../../avatar/resources.md#references).
</figcaption>
</figure>
</center>
In the [3D Importer](../../art/modeling/3d-importer.md#avatar-general), use **Rig Type** > **Default** to import your model as a Classic body scale.
<br />
<GridContainer numColumns="2">
<figure>
<figcaption><center>Minimum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>.5</td>
<td>.5</td>
<td>.5</td>
</tr>
<tr>
<td>Arm</td>
<td>.25</td>
<td>1.5</td>
<td>.25</td>
</tr>
<tr>
<td>Torso</td>
<td>.85</td>
<td>1.7</td>
<td>.7</td>
</tr>
<tr>
<td>Leg</td>
<td>.25</td>
<td>1.4</td>
<td>.5</td>
</tr>
<tr>
<td>**Total**</td>
<td>**1.35**</td>
<td>**3.6**</td>
<td>**.7**</td>
</tr>
</tbody>
</table>
</figure>
<figure>
<figcaption><center>Maximum (in studs)</center></figcaption>
<table>
<thead>
<tr>
<th>Part</th>
<th>X (width)</th>
<th>Y (height)</th>
<th>Z (depth)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>1.5</td>
<td>1.8</td>
<td>2</td>
</tr>
<tr>
<td>Arm</td>
<td>2</td>
<td>3</td>
<td>2</td>
</tr>
<tr>
<td>Torso</td>
<td>4</td>
<td>3.8</td>
<td>2</td>
</tr>
<tr>
<td>Leg</td>
<td>1.5</td>
<td>3.5</td>
<td>2</td>
</tr>
<tr>
<td>**Total**</td>
<td>**8**</td>
<td>**9.1**</td>
<td>**2**</td>
</tr>
</tbody>
</table>
</figure>
</GridContainer>
### Triangle budgets
Although model geometries are typically created using quads, the Roblox Engine converts imported assets into tris. Each asset of your character model must not exceed our maximum tri budget. To quickly get the number of expected tris in your third-party modeling application, you can double the number of quads in your model.
<Alert severity = 'info'>When character models are uploaded to Studio and created into assets for the Marketplace, the body is split into 6 individual assets: **DynamicHead**, **Torso**, **LeftArm**, **RightArm**, **LeftLeg**, **RightLeg**.</Alert>
<table>
<thead>
<tr>
<th>Asset type</th>
<th>Included mesh objects</th>
<th>Maximum triangles</th>
</tr>
</thead>
<tbody>
<tr>
<td>DynamicHead</td>
<td>Head</td>
<td>4000</td>
</tr>
<tr>
<td>Torso</td>
<td>UpperTorso, LowerTorso</td>
<td>1750</td>
</tr>
<tr>
<td>LeftArm </td>
<td>LeftUpperArm, LeftLowerArm, LeftHand</td>
<td>1248</td>
</tr>
<tr>
<td>Right Arm</td>
<td>RightUpperArm, RightLowerArm, RightHand</td>
<td>1248</td>
</tr>
<tr>
<td>LeftLeg </td>
<td>LeftUpperLeg, LeftLowerLeg, LeftFoot</td>
<td>1248</td>
</tr>
<tr>
<td>Right Leg</td>
<td>RightUpperLeg, RightLowerLeg, RightFoot</td>
<td>1248</td>
</tr>
<tr>
<td>Total</td>
<td>Head, UpperTorso, LowerTorso, LeftUpperArm, LeftLowerArm, LeftHand, RightUpperArm, RightLowerArm, RightHand, LeftUpperLeg, LeftLowerLeg, LeftFoot, RightUpperLeg, RightLowerLeg, RightFoot</td>
<td>10,742</td>
</tr>
</tbody>
</table>
### Body parts
See the following specifications for the individual mesh objects that make up a character model:
- **Naming Convention** - Limbs must all be specifically named:
- UpperTorso_Geo
- LowerTorso_Geo
- LeftUpperArm_Geo
- LeftLowerArm_Geo
- LeftHand_Geo
- RightUpperArm_Geo
- RightLowerArm_Geo
- RightHand_Geo
- LeftUpperLeg_Geo
- LeftLowerLeg_Geo
- LeftFoot_Geo
- RightUpperLeg_Geo
- RightLowerLeg_Geo
- RightFoot_Geo
- Head_Geo
- **Caps** - Limbs must be capped, so that they form a full watertight mesh when separated from the body. Caps can be rounded or flat depending on design.
<img src="../../assets/modeling/meshes/Modeling-Requirements-Caps.png" width="600" />
### Face accessories
Face accessories, such as hair, eyebrows, and eyelashes are unique accessories that you can bundle with an avatar body upload. At this time, eyebrows and eyelashes can not be uploaded as standalone accessories and must be bundled with an avatar body. See [Accessory specifications](../accessories/specifications.md#face-accessories) for additional information on face accessories.
### Visibility
To ensure that avatar sizes are visually consistent, you must standardize body part visibility with the following requirements:
- **Opacity** - Body parts must be fully opaque.
- **Bounding Boxes** - Body part assets must take up a significant visible portion of their bounding box in a front, side, and back view.
- Body parts, such as Torso, Left Arm, Right Leg, must take up at least 50% of body part's bounding box.
- The head part must take up at least 50% of the mesh's bounding box.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/art/avatar/Valid-Visibility.png" />
<figcaption>An acceptable head mesh example that takes up a majority of the bounding box in the front view</figcaption>
</figure>
<figure>
<img src="../../assets/art/avatar/Invalid-Visibility.png" />
<figcaption>A non-acceptable head mesh example that does not take up the appropriate amount of bounding box space in the front view</figcaption>
</figure>
</GridContainer>
## Attachments
Attachments are points on the humanoid model where rigid accessories attach. Like many [character components](./index.md#components-of-an-avatar), attachment points are set up in third-party modeling software and imported as `Class.Attachment` objects.
The 3D Importer automatically recognizes and converts mesh objects as attachment points if the objects include the affix `\_Att` and follow the naming conventions below. This only applies when importing meshes with caging data, such as bodies (accessory attachment points are created using the Accessory Fitting Tool). Check out examples of this implementation in any of the [downloadable reference models](../../avatar/resources.md#references).
Generally, when placing attachment points, position them so they overlap halfway with the character model's mesh part.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/Collar-Attachment-1.png" />
<figcaption>Incorrect placement of collar attachments</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/Collar-Attachment-2.png" />
<figcaption>Correct placement of collar attachments</figcaption>
</figure>
</GridContainer>
Attachments must follow a specific naming convention and positional consistency:
<table>
<thead>
<tr>
<th>Mesh part</th>
<th>Attachment name</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="4">Head</td>
<td>FaceCenter_Att</td>
<td>Anywhere within mesh bounding box</td>
</tr>
<tr>
<td>FaceFront_Att</td>
<td>Front half of mesh bounding box</td>
</tr>
<tr>
<td>Hat_Att</td>
<td>Top half of mesh bounding box, can overlap with Hair_Att</td>
</tr>
<tr>
<td>Hair_Att</td>
<td>Top half of mesh bounding box, can overlap with Hat_Att</td>
</tr>
<tr>
<td rowspan="5">UpperTorso</td>
<td>LeftCollar_Att</td>
<td>Left top half of mesh bounding box</td>
</tr>
<tr>
<td>RightCollar_Att</td>
<td>Right top half of mesh bounding box</td>
</tr>
<tr>
<td>Neck_Att</td>
<td>Top half of mesh bounding box</td>
</tr>
<tr>
<td>BodyBack_Att</td>
<td>Back half of mesh bounding box</td>
</tr>
<tr>
<td>BodyFront_Att</td>
<td>Front half of mesh bounding box</td>
</tr>
<tr>
<td rowspan="4">LowerTorso</td>
<td>Root_Att</td>
<td>Must set to `0`, `0`, `0` position</td>
</tr>
<tr>
<td>WaistFront_Att</td>
<td>Front half of mesh bounding box, can overlap with WaistCenter_Att</td>
</tr>
<tr>
<td>WaistBack_Att</td>
<td>Back half of mesh bounding box</td>
</tr>
<tr>
<td>WaistCenter_Att</td>
<td>Anywhere in mesh bounding box, can overlap with WaistFront_Att</td>
</tr>
<tr>
<td>RightUpperArm</td>
<td>RightShoulder_Att</td>
<td>Top half of mesh bounding box</td>
</tr>
<tr>
<td>RightHand</td>
<td>RightGrip_Att</td>
<td>Anywhere in mesh bounding box. <br/><br/>Orient grip attachments **perpendicular** to the lower arm bone. For example, for I-Pose (arms pointing down), set the grip attachment to `90`, `0`, `0` (grip attachment pointing forward).<br/><br/><img src="../../assets/modeling/meshes/Grip_Attachments.png" width="250" /></td>
</tr>
<tr>
<td>LeftUpperArm</td>
<td>LeftShoulder_Att</td>
<td>Top half of mesh bounding box</td>
</tr>
<tr>
<td>LeftHand</td>
<td>LeftGrip_Att</td>
<td>Anywhere in mesh bounding box. <br/><br/>Orient grip attachments **perpendicular** to the lower arm bone. For example, for I-Pose (arms pointing down), set the grip attachment to `90`, `0`, `0` (grip attachment pointing forward).<br/><br/><img src="../../assets/modeling/meshes/Grip_Attachments.png" width="250" /></td>
</tr>
<tr>
<td>RightFoot</td>
<td>RightFoot_Att</td>
<td>Anywhere in mesh bounding box</td>
</tr>
<tr>
<td>LeftFoot</td>
<td>LeftFoot_Att</td>
<td>Anywhere in mesh bounding box</td>
</tr>
</tbody>
</table>
## Rigging
Unlike generic rigs, humanoid models require a specific hierarchy and naming conventions for the internal bone or joint structure.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/animation/importing-custom-3d-rigs/Birdcaller-Imported.jpeg" />
<figcaption>Humanoid rig model</figcaption>
</figure>
<figure>
<img src="../../assets/animation/importing-custom-3d-rigs/Rig-Hierarchy-Birdcaller-Blender-Bones.png" width="75%" />
<figcaption>Humanoid rig bone structure (Blender)</figcaption>
</figure>
</GridContainer>
See the following requirements for humanoid rigging:
- **Rig Hierarchy** - Humanoid rigs require a specific bone hierarchy and naming convention:
- Root
- HumanoidRootNode
- LowerTorso
- UpperTorso
- Head (representing the base of the neck)
- LeftUpperArm
- LeftLowerArm
- LeftHand
- RightUpperArm
- RightLowerArm
- RightHand
- LeftUpperLeg
- LeftLowerLeg
- LeftFoot
- RightUpperLeg
- RightLowerLeg
- RightFoot
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/skinned-meshes/Rig-Hierarchy-Blender.png" />
<figcaption>Blender rig hierarchy</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/skinned-meshes/Rig-Hierarchy-Maya.png" />
<figcaption>Maya rig hierarchy</figcaption>
</figure>
</GridContainer>
- **LowerTorso and Root** - The LowerTorso and Root bone or joint position must be set to `0`, `0`, `0`.
- **Pose** - Export your character model in an I-Pose, A-Pose, or T-Pose for the best Studio compatibility. The LeftUpperArm and RightUpperArm bones can be exported with rotation values to meet this requirement.
## Skinning
Roblox supports skinning for rigged meshes. See [Rigging and Skinning](../../art/modeling/rigging.md) for more details on implementing skinned meshes in your experience.
See the following requirements for skinning:
- **Max Influences** - A vertex can not be influenced by more than 4 bones or joints.
- **No Root Influences** - Do not apply influences to the Root bone or joint.
- **Symmetry** - When possible, maintain symmetry when applying influences to a rig.
## Facial animations
Roblox supports facial animation on character heads and can support more than 50 base poses. If you are creating an avatar character, it must, at minimum, include the following 17 [FACS reference poses](../../art/characters/facial-animation/facs-poses-reference.md) to support avatar chat:
- EyesLookDown
- EyesLookLeft
- EyesLookRight
- EyesLookUp
- JawDrop
- LeftEyeClosed
- LeftLipCornerPuller
- LeftLipStretcher
- LeftLowerLipDepressor
- LeftUpperLipRaiser
- LipsTogether
- Pucker
- RightEyeClosed
- RightLipCornerPuller
- RightLipStretcher
- RightLowerLipDepressor
- RightUpperLipRaiser
While the 17 poses are a minimum requirement, it's recommended to include as many facial poses as possible in your asset to improve expressiveness and facial animation fidelity for facial animation and avatar chat.
## Textures
Avatar characters must follow Roblox's [texture specifications](../../art/modeling/texture-specifications.md). Characters created for the Marketplace can take advantage of [custom skin tones](#custom-skin-tone) which use alpha layers allow users to select their own base color.
### Custom skin tone
When texturing an avatar character model where the user can set their own skin tone, set the exposed skin areas as transparent so a default color or texture is not baked into the texture. When rendering, the Studio engine applies the transparent layer on top without any layer effects. This step applies mostly to human-like characters with exposed skin that you intend users to customize.
The following are examples of skin tone shading for the face, and you can apply this process with any part of an avatar with exposed skin:
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Face-Tone-Transparent.png" />
</figure>
<figure>
- Use 100% opacity for areas not related to a customized skin tone, such as eyes and brows.
- When applying shading, use black at low opacity and adjust opacity when needed.
- For areas that are partially translucent, such as shading contours or certain cosmetic features, leave some transparency for partial visibility of the skin tone.
- You should consistently test out how various colors layers can interact with your shading.
</figure>
</GridContainer>
<GridContainer numColumns="4">
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Face-Tone-Beige.png" />
<figcaption>Beige</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Face-Tone-Blue.png" />
<figcaption>Blue</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Face-Tone-Brown.png" />
<figcaption>Brown</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Face-Tone-Pink.png" />
<figcaption>Pink</figcaption>
</figure>
</GridContainer>
## Outer cages
Outer cages on your character model allow your character to wear layerable accessories, such as clothing. Models, such as an avatar character, that are the target of meshes that will stretch over it, only require an outer cage, but meshes that deform, like [layered clothing](../accessories/clothing-specifications.md#cage-meshes), require an inner and outer cage.
For general use, see the following requirements for adding outer cage meshes to your model:
- Use Roblox's [body cage templates](../../avatar/resources.md#project-files) to ensure naming convention and other configurations are correct.
- **Naming Conventions** - The outer cage of a body part must be named after the primary mesh object with **\_OuterCage** affixed, for example `LeftUpperArm_OuterCage`.
- **Vertices and UV Map** - Don't delete vertices or alter the UVs on the Outer Cages as this can cause errors when importing in Studio or when equipping onto a character. Use the Roblox provided templates for the cage meshes to ensure compatibility with other layered assets.
- **Symmetry and consistency** - Keep each face (the space between vertices) consistently sized and retain symmetry wherever possible. Use symmetry tools in your modeling software whenever possible.
## Marketplace requirements
Along with the other technical requirements listed, your items must meet the following additional specifications before uploading them to the Marketplace to sell:
- Ensure that your items adhere to the [Marketplace program guidelines](../../marketplace/marketplace-policy.md).
- Whenever possible, ensure that your items adhere to the following modeling requirements:
- [Custom mesh specifications](../../art/modeling/specifications.md)
- Any applicable [avatar specifications](../../art/characters/specifications.md)
- Object `Class.MeshPart.Material|Material` is set to `Plastic`.
- Object `Class.MeshPart.Transparency|Transparency` is set to `0`.
- Object `Class.MeshPart.VertexColor|VertexColor` is the default `1, 1, 1`.
- If your head includes separate eyelash and eyebrow assets, you must add them to your character model as `Class.Accessory` objects.
- See [accessory specifications](../../art/accessories/specifications.md) for additional technical requirements.
- Your `Class.Model` instance doesn't contain extraneous objects, like `Class.Script` or additional `Class.Part` instances.

80
.cursor/rules/roblox/art/characters/testing/blender.md Normal file
View file

@ -0,0 +1,80 @@
---
title: Test in Blender
comments:
description: Verify the important aspects of your character model in Blender before importing into Studio.
next: /art/characters/testing/studio
prev: /art/characters/testing/
---
You can quickly verify many of your components in Blender, allowing you to catch out problems that may cause issues later on. You can use a mix of Blender native tools and Roblox's helper plugins to check for many common issues in your character model.
## Facial animation data
Facial animation uses multiple modeling components to work effectively. If using a template, or making changes to a model with existing facial animation data, it's sometimes possible to make a change that affects the saved poses, either in the animation timeline, or in the custom property of the head mesh.
Use the following steps to help verify the integrity of your facial animation data:
1. With the Armature object selected, check the animation frame in the **timeline**:
1. The timeline typically ranges between **0–330**, though not all templates use the entire range, and there may be gaps between poses.
<img src="../../../assets/art/avatar/basic-creation/Testing-Animation-Timeline.png" />
2. The **neutral pose** should be on **frame 0**.
3. There shouldn't be any keyframe gaps between the frames with animation data.
2. Verify the **Object Properties** > **Custom Properties** panel for the Head_Geo object:
<img src="../../../assets/art/avatar/basic-creation/Testing-Custom-Properties.png" width = "80%" />
1. There should be a **RootFaceJoint** attribute set to the name of the first facial animation bone.
1. This bone should be a child of the **Head** bone, one of the 15 required bones in an avatar's armature.
2. In templates and some reference models, this bone is commonly named `DynamicHead` and indicates the beginning of the facial animation rig.
2. There should be about the same number of custom properties as unique animation frames, with each animation pose having its own mapped custom property.
3. The names for the mapped poses here should match the spelling and capitalization of the [FACS pose reference](../../../art/characters/facial-animation/facs-poses-reference.md).
<video controls src="../../../assets/art/avatar/basic-creation/Testing_01.mp4" width="100%"></video>
<Alert severity = 'error'>
If you discover issues with your face animation data, you may need to repeat the skinning, posing, or mapping processes for your character's head. See [Creating Heads](../../../art/characters/facial-animation/create-basic-heads.md) for a general overview of the avatar head creation process.
If you are using a template and run into issues, it's possible the facial data was overridden by a saved animation, or the rigging or mapped data was mistakenly deleted. If it's difficult to quickly identify and resolve the issue, it may be quicker to restart your character customization from the original template file.
</Alert>
## Body skin
Properly skinning your character models ensures natural joint movements and realistic poses and expressions. There are several ways to verify skinning data, like using Blender's Pose Mode to pose the joints and examine how certain orientations can affect the joint skinning.
Use the following steps in Blender to verify your joint skinning in Pose mode:
1. With the **Armature** object selected, navigate to the **Object Properties** > **Viewport Display** and enable **Show In Front**. This allows you to see and access bones within your character.
2. With the armature selected, and switch to **Pose Mode**.
3. Select all the face bones of your model and press <kbd>H</kbd> to hide. You can reveal these again later with <kbd>Alt</kbd><kbd>H</kbd> (<kbd>⌥</kbd><kbd>H</kbd>) in Pose mode.
4. Select any body bone and press <kbd>R</kbd> to rotate. Verify that your body bones correctly deform and bend the character mesh as expected in natural poses.
1. While actively rotating a bone, right-click to cancel the rotation and set the bone to its original position.
2. While actively rotating a bone, you can **click to confirm** the rotation and save the current position. You can combine this to make various poses of your character by changing the rotation of various limbs at once.
3. If you've saved a rotation, press <kbd>Alt</kbd><kbd>R</kbd> (<kbd>⌥</kbd><kbd>R</kbd>) to clear any rotation in Pose Mode. Make sure to reset your pose whenever you complete testing.
<video controls src="../../../assets/art/avatar/basic-creation/Testing_02.mp4" width="100%"></video>
You can also run through common poses and movements using Roblox's [Calisthenics Tool](../../../art/modeling/calisthenics-tool.md) add-on, which applies several common animations to an avatar armature that you can play back and review in Blender's animation timeline.
<Alert severity = 'warning'>
The [Calisthenics Tool](../../../art/modeling/calisthenics-tool.md) adds animations to your timeline to quickly preview body animations. Be careful when saving or exporting your character when using this tool, as it may conflict with saved facial animation data that uses the same timeline.
</Alert>
<video controls src="../../../assets/art/avatar/basic-creation/Testing_03.mp4" width="100%"></video>
<Alert severity = 'error'>
If you discover issues with your skinning, you may need to troubleshoot and reapply rigging and skinning steps to your humanoid. See [Rigging and skinning](../../../art/modeling/rigging.md) for an overview of the rigging and skinning processes.
If you are using a template, it's possible the skinning data was affected by a destructive modeling change. This may require reskinning, or starting over your character customization from the original template file.
</Alert>
## Technical specifications
Your avatar components should match the requirements provided in the [avatar specifications](../../../art/characters/specifications.md). When using templates and following appropriate non-destructive modeling practices, most of these components should not be touched, but you should still double-check that each component is compliant with the technical requirements.
<Alert severity = 'success'>
If you are using Roblox character templates and are ready to export into Studio, see [Exporting instructions](../../../art/characters/creating/export-textures.md) for specific export instructions for template files.
</Alert>

96
.cursor/rules/roblox/art/characters/testing/index.md Normal file
View file

@ -0,0 +1,96 @@
---
title: Testing characters
comments:
description: Verify the important aspects of your character model in Blender and in Studio.
next: /art/characters/testing/blender
---
It's important to constantly test your models during and after the creation process to ensure that your character can interact with various social and environmental elements in any experience.
Whether you are using a template character, or your own custom assets, use the information provided in [Test in Blender](../../../art/characters/testing/blender.md) and [Test in Studio](../../../art/characters/testing/studio.md) throughout your workflow to comprehensively test your assets and quality check your models.
Use the following table as an overview of common tests and resources to verify each component of your character model.
<Tabs>
<TabItem label="Blender">
<Alert severity = 'info'>
You can apply the following workflows with any modeling software, though certain interfaces and instructions may differ between platforms. See [Testing in Blender](../../../art/characters/testing/blender.md) for additional information.
</Alert>
<table>
<thead>
<tr>
<th style={{width:"25%"}}>Component</th>
<th>Testing recommendations</th>
</tr>
</thead>
<tbody>
<tr>
<td><img src="../../../assets/art/avatar/Component-Body-Parts.png" /> <br /><center>**Body Parts**</center></td>
<td>When modeling, confirm that your geometry follows [avatar geometry specifications](../../../art/characters/specifications.md#geometry).</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/Component-Texture-Map.png" /> <br /><center>**Textures**</center></td>
<td>When texturing, confirm that your geometry follows [avatar texture specifications](../../../art/characters/specifications.md#textures). </td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/Component-Rigging.png" /> <br /><center>**Rigging**</center></td>
<td>Use [Blender's posing tools](../../../art/characters/testing/blender.md#body-skinning) to check the rigging and skinning quality of your asset.<br /></td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/Component-Facial-Animation-Data.png" /> <br /><center>**Face Animation**</center></td>
<td>Confirm that [your FACS data](../../../art/characters/testing/blender.md#facial-animation-data) is present and correctly configured.</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/Component-Cage-Mesh.png" /> <br /><center>**Cage Mesh**</center></td>
<td>Manually verify that your cage mesh completely and tightly covers your character model and follows [avatar outer cage specifications](../../../art/characters/specifications.md#outer-cages).</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/Component-Attachments.png" /> <br /><center>**Attachments**</center></td>
<td>Manually verify that your attachment points are correctly positioned and follow [avatar attachment specifications](../../../art/characters/specifications.md#attachments).</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Studio">
<Alert severity = 'info'>
Roblox provides an uncopylocked testing place that includes quick access to various environments and testing features. See [Testing in Studio](../../../art/characters/testing/studio.md) for additional information.
</Alert>
<table>
<thead>
<tr>
<th style={{width:"25%"}}>Component</th>
<th>Testing recommendations</th>
</tr>
</thead>
<tbody>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Emotes.png" /> <br /><center>**Body Parts**</center></td>
<td>Verify your character's geometry while in [movement and animation](../../../art/characters/testing/studio.md#movement-and-animation).</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Skin-Tone.png" /> <br /><center>**Textures**</center></td>
<td>Test your character in [various lighting environments and skin tone colors](../../../art/characters/testing/studio.md#lighting-and-color).</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Outdoor-Environment.png" /> <br /><center>**Rigging**</center></td>
<td>Use [animations and testing environments](../../../art/characters/testing/studio.md#movement-and-animation) to verify your character's rigging, skinning, and movement.</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Face-Animation.png" /> <br /><center>**Face Animation**</center></td>
<td>[Cycle through various facial animations](../../../art/characters/testing/studio.md#movement-and-animation) to ensure your character can express common expressions.</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Clothing-Try-On.png" /> <br /><center>**Cage Mesh**</center></td>
<td>[Equip various clothing items](../../../art/characters/testing/studio.md#clothing-and-accessories) to check for fit and for any unexpected cosmetic issues.</td>
</tr>
<tr>
<td><img src="../../../assets/art/avatar/basic-creation/Testing-Clothing.png" /> <br /><center>**Attachments**</center></td>
<td>[Equip various accessory items](../../../art/characters/testing/studio.md#clothing-and-accessories) to verify rigid accessory placement and orientation.</td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>

272
.cursor/rules/roblox/art/characters/testing/studio.md Normal file
View file

@ -0,0 +1,272 @@
---
title: Test in Studio
comments:
description: Verify the important aspects of your character model in a custom Studio test experience.
---
Test your character model in Studio to understand how it looks and feels within a Roblox experience. To test your custom character in Studio, first [import the character model](../../characters/import.md) into your Studio project.
You can test in Studio using the [Avatar Setup](../../../avatar-setup/) tool to preview and test various components of your avatar character.
You can also playtest your character in the [Avatar Test experience](https://www.roblox.com/games/13176231501/Avatar-Test-Place). This experience provides a wide variety of environmental and clothing tests to ensure that your character model and related components work as expected.
## Set up test experience
The following is the general testing process setting up the Avatar Test experience:
1. Download and open the [Avatar Test experience](https://www.roblox.com/games/13176231501/Avatar-Test-Place) in Studio.
2. Import your avatar model into Studio.
3. Set your model as the starter character.
4. Launch a playtest of the experience.
### Open in Studio
In order to use the [Avatar Test experience](https://www.roblox.com/games/13176231501/Avatar-Test-Place), you must first download it from Roblox. You can save the experience locally and make any changes that may help your testing workflow. Roblox may update this experience periodically to add or improve features.
To download the Avatar Test experience:
1. Navigate to the [Avatar Test experience](https://www.roblox.com/games/13176231501/Avatar-Test-Place).
2. In the button next to the experience title, select **…** > **Edit**. The page navigates to the Studio launcher.
<img src="../../../assets/art/avatar/basic-creation/Testing-Avatar-Test-Place.png" />
<img src="../../../assets/art/avatar/basic-creation/Testing-Studio.png" />
### Import
After you open the test experience in Studio, import your custom character model.
1. From Studio's **File** menu, select **Import 3D**. A file browser displays.
<img src="../../../assets/art/avatar/basic-creation/Testing-3d-Importer.png" />
2. Select your custom character `.fbx` file.
3. Verify the following:
1. With the highest level object selected, ensure **Rig Type** is set to R15.
<img src="../../../assets/art/avatar/basic-creation/Testing-Rig-Type.png" />
2. If using the template files, set **Rig Scale** to **Rthro**. Otherwise, use the appropriate rig scale for your [character body type](../../../art/characters/specifications.md#body-scale).
3. Check for any red errors that may block import into Studio.
4. Verify any yellow warnings that may indicate a quality issue with your avatar components.
<Alert severity = 'warning'>
The 3D Importer may incorrectly report some cage meshes as not watertight. You can ignore these warnings for those cage objects.
</Alert>
4. Click **Import**. The character's model populates into the workspace.
<Alert severity = 'warning'>
If an error or warning message displays in the **Output** window, see [Troubleshooting](../../../art/characters/facial-animation/use-heads-in-studio.md#troubleshooting) for guidance on how to handle your specific error or warning message.
</Alert>
### Add SurfaceAppearance
If you exported your textures separately, or if the 3D Importer fails to pick up your PBR textures, you can add them manually.
To add individual image texture files:
1. Open the **Asset Manager**. You may need to publish your experience first.
2. **Bulk Upload** the image map assets.
<img src="../../../assets/art/avatar/basic-creation/Testing-Asset-Upload.png" />
3. In the **Explorer**, expand the **Head_Geo** and check if a `Class.SurfaceAppearance` object exists.
- If `Class.SurfaceAppearance` is present, continue to step 4.
- If `Class.SurfaceAppearance` is not present, select the ⊕ next to the Head_Geo and add a `Class.SurfaceAppearance` object.
4. Set each property to the corresponding uploaded image map
<img src="../../../assets/art/avatar/basic-creation/Testing-Surface-Appearance.png" />
5. Copy the `Class.SurfaceAppearance` with the populated image map with <kbd>Ctrl</kbd><kbd>C</kbd> (<kbd>⌘</kbd><kbd>C</kbd>).
6. Hold <kbd>Shift</kbd> and click all of your model's MeshParts to select all of your character's geometry.
7. Use <kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>V</kbd> (<kbd>⌘</kbd><kbd>Shift</kbd><kbd>V</kbd>) to paste into all of the head geometries. An updated `Class.SurfaceAppearance` populates in each `Class.MeshPart` object.
<img src="../../../assets/art/avatar/basic-creation/Testing-Surface-Appearance-Applied.png" />
### Set model as StarterPlayer
In order to play as the character during a playtest, rename and move the model instance:
1. In the **Explorer**, rename the character **model** as `StarterCharacter`.
2. In the **Explorer**, navigate to the `Class.StarterPlayer` directory. If a `StarterCharacter` model already exists, remove it.
3. Click and drag the model under the directory.
<img src="../../../assets/art/avatar/basic-creation/Testing-StarterPlayer.png" />
After you rename and add your model, [playtest](../../../studio/testing-modes.md#playtesting) the experience as the custom model.
## Use test experience
The Avatar Test experience includes several features in the interface and environment to quickly perform comprehensive tests of your avatar characters. You can use the [test checklist](#checklist) to ensure you are reviewing all the important aspects of your avatar character.
When playtesting the experience, use the following UI buttons on the right side to open various testing tools and options:
<table>
<thead>
<tr>
<th><center>Button</center></th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Face.png" width="57" height="60" /><br />Avatars and facial animation</center>
</td>
<td>Use this menu to swap between the custom avatar and control avatars. An additional button option allows you to loop through various facial animations to test your character's face expressions.</td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Emote.png" width="53" height="56" /><br />Emotes and animations</center></td>
<td>Use this menu to test various animations on your avatar character. </td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Skin-Tone.png" width="54" height="53"/><br />Skin tone color palette</center></td>
<td>Use this menu to select a new skin tone for your character. See <a href="../../../assets/art/avatar/basic-creation/Testing-UI-Emote.png">Custom Skin Tones</a> for more details on this implementation with template character models. </td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Clothing.png" width="53" height="53" /><br />Clothes and accessories</center></td>
<td>Use this menu to select various clothing items to try on. </td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Movement.png" width="48" height="53" /><br />Movement settings</center></td>
<td>Use this menu to change movement settings for your character model, such as **jump height** and **walk speed**. </td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Settings.png" width="48" height="59" /><br />Body proportion settings</center></td>
<td>Use this menu to change various aspects of your character's body proportions.</td>
</tr>
<tr>
<td><center><img src="../../../assets/art/avatar/basic-creation/Testing-UI-Lighting.png" width="51" height="51" /><br />Lighting presets</center></td>
<td>Use this menu to change the environment lighting to various presets, such as **Mountains - Sunset**, or **Indoor - Midday**.</td>
</tr>
</tbody>
</table>
### Checklist
Use the following checklists to ensure that you are comprehensively testing each component of your avatar. Use the Avatar menu to switch between your custom avatar and a control avatar to verify expected behavior.
#### Movement and animation
<GridContainer numColumns="3">
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Emotes.png" /> <figcaption>Testing guitar animation emote</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Water.png" /><figcaption>Testing water movement</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Ramps.png" /><figcaption>Testing ramp movement</figcaption></figure>
</GridContainer>
Check the following for any anomalies:
<table>
<thead>
<tr>
<th>Function</th>
<th>How to test</th>
</tr>
</thead>
<tbody>
<tr>
<td>Walking</td>
<td>Move the character around the environment, ramps, and platforms.</td>
</tr>
<tr>
<td>Sitting</td>
<td>Move to any of the seats in the environment and press <kbd>E</kbd> to sit.</td>
</tr>
<tr>
<td>Climbing</td>
<td>Move to any of the trusses and ladders. Your character automatically begins climbing when near.</td>
</tr>
<tr>
<td>Swimming</td>
<td>Use the pool of water at the top of the ramp area to verify your swimming animation.</td>
</tr>
<tr>
<td>Jumping</td>
<td>Press <kbd>Space</kbd> to jump.</td>
</tr>
<tr>
<td>Dying</td>
<td>Use any of the death cubes to set your character to a ragdoll state and respawn.</td>
</tr>
<tr>
<td>Facial Animation</td>
<td>Use the **Face UI menu** to toggle a face animation cycle.</td>
</tr>
<tr>
<td>Emotes and Animation</td>
<td>Use the **Emote UI menu** to access and play the available emotes. </td>
</tr>
</tbody>
</table>
If you see unexpected behavior with your character's movement, there may be some issues with the rigging or skinning of your character. It may require revisiting the rigging and armature components of your avatar model in your modeling application.
#### Lighting and color
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Skin-Tone.png" /> <figcaption>Testing skin tones</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Lighting.png" /><figcaption>Testing environmental lighting</figcaption></figure>
</GridContainer>
Check the following for any anomalies:
<table>
<thead>
<tr>
<th>Function</th>
<th>How to test</th>
</tr>
</thead>
<tbody>
<tr>
<td>Skin tone</td>
<td>Use the **Skin Tone UI** menu to test various skin tones for texturing and lighting compatibility.</td>
</tr>
<tr>
<td>Environmental lighting</td>
<td>Use the **Lighting UI menu** and the environment to check how your character's surface appearance displays in various conditions.</td>
</tr>
</tbody>
</table>
If you see unexpected behavior with your character's appearance in various lighting and color selections, there may be some issues with the texturing of your character. It may require re-adjusting the texturing components of your avatar model in your modeling application.
#### Clothing and accessories
<GridContainer numColumns="2">
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Clothing.png" /> <figcaption>Test a mix of clothing and accessories</figcaption></figure>
<figure><img src="../../../assets/art/avatar/basic-creation/Testing-Clothing-Try-On.png" /><figcaption>Use the UI menu or pedestals to equip or reset clothing and accessories</figcaption></figure>
</GridContainer>
Check the following for any anomalies:
<table>
<thead>
<tr>
<th>Function</th>
<th>How to test</th>
</tr>
</thead>
<tbody>
<tr>
<td>Equipping accessories</td>
<td>Use the **Clothes and Accessories UI menu** or environmental pedestals to equip rigid accessories to your character.</td>
</tr>
<tr>
<td>Equipping clothing</td>
<td>Use the **Clothes and Accessories UI menu** or environmental pedestals to equip rigid accessories to your character. Test your clothing in motion and in animations to verify the fit.</td>
</tr>
</tbody>
</table>
If you see unexpected behavior with your character wearing clothes or equipping rigid accessories, there may be issues with the caging or attachment points of your character. You may need to re-adjust the cage mesh shapes or attachment objects of your avatar model in your modeling application.
<Alert severity = 'warning'>
Clothes can layer in unconventional orders, such as a jacket worn below a tshirt. You can reset the equipped clothing and try various combinations of clothing options and ordering.
</Alert>

121
.cursor/rules/roblox/art/characters/validation-tool.md Normal file
View file

@ -0,0 +1,121 @@
---
title: Blender validation tool
description: The Avatar Validation Tool checks for common character model issues in Blender.
---
The **Avatar Validation Tool** is a supplemental Blender add-on you can use to quickly identify common issues with your character model. This tool checks that your model meets most of Roblox's avatar [technical specifications](../../art/characters/specifications.md) and, when possible, attempts to automatically resolve them.
<img src="../../assets/art/avatar/Validation-Tool-Preview.png" width="100%" />
This tool can save you time by checking for common validation specifications before you export your model, but it doesn't provide a comprehensive verification of all aspects of your character model. You should always continually test your character model, including testing your characters [in Studio](../../art/characters/testing/studio.md) and verifying on your own if your model meets Roblox's [character specifications](../../art/characters/specifications.md).
## Install
<Alert severity = 'warning'>
The Validation Tool plugin is compatible with Blender 3.5.1+. You may experience unexpected behavior if using earlier versions of Blender.
</Alert>
To install the Validation Tool in Blender:
1. Download [ValidationTool_Blender.zip](../../assets/art/ValidationTool_V2.zip) and save the .zip file locally. Do not open the .zip file.
2. In Blender, navigate to **Edit** > **Preferences**.
3. In Preferences, go to the **Add-Ons** section on the left sidebar.
<img src="../../assets/accessories/validation-tool/Blender-Add-On-Preferences.png" width="80%" />
4. Click the **Install...** button. A file browser displays.
5. Select the downloaded .zip file and click **Install Add-On**.
6. In the Add-Ons section, find the Validation Tool and **enable** the add-on.
<img src="../../assets/accessories/validation-tool/Blender-Add-On-Preferences.png" width="80%" />
7. Return to your workspace and expand the side toolbar in the Viewport to access the add-on.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/accessories/validation-tool/Blender-Add-On-Preferences.png" width="80%" />
<figcaption>Sidebar indicator</figcaption>
</figure>
<figure>
<img src="../../assets/art/avatar/Validation-Tool.png" width="80%" />
<figcaption>Expanded sidebar</figcaption>
</figure>
</GridContainer>
## Validate
After installing the plugin, you can begin validating your character models. When validating, results with issues display as red. In some cases, you can apply an automatic fix to checks that have issues. See [Checks and Troubleshooting Steps](#checks-and-troubleshooting) for details on each validation check.
To use the validation tool on your asset:
1. In the Target Armature field, select the **eyedropper**.
2. With the eyedropper active, select your character's **armature object**. This object is often named Joints or Armature.
3. Select **Run All Checks** to go through each individual check. Alternatively, you can click individual buttons to run a specific check.
4. Checks that detect issues display as red and an error output displays at the bottom of the tool.
<video controls src="../../assets/art/avatar/Validation-Tool-Test.mp4" width="100%"></video>
<Alert severity = 'info'>
This validation tool only checks for common validation issues. You should always continually test your character model, including testing your characters [in Studio](../../art/characters/testing/studio.md) and verifying on your own if your model meets Roblox's [character specifications](../../art/characters/specifications.md).
</Alert>
## Checks and troubleshooting
Each button on the validation tool performs a different check against the expected [character specifications](../../art/characters/specifications.md). The following are the specific types of verification each check performs, as well as general troubleshooting steps to resolve discovered issues:
<dl>
<dt>**Layers**</dt>
<dd>Checks for extra layers in the scene. Automatic fix attempts to remove extra layers. <p />If the automatic fix fails, manually remove extra layers.</dd><p />
<dt>**Transforms**</dt>
<dd>Checks that geometry location, rotation, and scale are frozen (`0`,`0`,`0`). Automatic fix button attempts to freeze the transforms. This may cause changes to your rig. <p />If the automatic fix fails, manually freeze your geometry.</dd><p />
<dt>**UV**</dt>
<dd>Checks if the body Geometry UVs are within `0`-`1`. You must resolve issues manually by setting your body object UVs within a `0`-`1` range.</dd><p />
<dt>**Cage UV Modifications**</dt>
<dd>Checks if cage object UVs have incorrect modifications. Automatic fix attempts to resolve UV coordinates. <p />If automatic fix fails, you may want to use a new template cage.</dd><p />
<dt>**Asset Size**</dt>
<dd>Checks if the character total size and individual parts are within expected bounds. You must resolve issues manually by resizing your character model or individual parts.</dd><p />
<dt>**Unused Data**</dt>
<dd>Checks for any unused data in the scene, such as orphan data, or unused materials. Automatic fix attempts to remove extra data. <p />If automatic fix fails, manually remove unnecessary data and objects.</dd><p />
<dt>**Keyframes**</dt>
<dd>Checks for any unnecessary keyframes. Keyframes related to facial expressions are expected and ignored. Automatic fix attempts to remove keyframes associated with non-face objects. <p /> If automatic fix fails, manually remove keyframe data from non-face objects. Do not delete keyframes that also contain facial data.</dd><p />
<dt>**Attachment Points**</dt>
<dd>Checks that attachment points are parented to the armature and use the correct naming convention. Automatic fix attempts to parent any unexpected attachment points.</dd><p />
<dt>**Joint Positions**</dt>
<dd> Checks for the following:
<ul><li>Root and HumanoidRootNode bones exist</li>
<li>Root bone is at `0`,`0`,`0` world space</li>
<li>Bones with Left/Right naming conventions are on correct axes.</li></ul> Refer to the output messages to manually resolve joint position issues.</dd><p />
<dt>**FACS Data**</dt>
<dd>Checks for the following FACs data:
<ul><li>`Neutral Pose` exists as a mapped pose</li>
<li>Mapped Custom Properties under the Head_Geo exists</li>
<li>Property name and values correctly set</li>
<li>Corrective poses must include existing base poses </li>
<li>Corrective poses do not use more than 3 base poses Refer to the output messages to manually resolve FACS data issues.</li></ul></dd><p />
<dt>**Head Joint Names**</dt>
<dd>Checks for duplicate head bone names, including duplicates with Blender's duplicate affixes .001, .002, .003, and such. Refer to the output messages to manually resolve face joint names.</dd><p />
<dt>**Intersection**</dt>
<dd>Checks for any intersection between character geometry and cage mesh geometry. The tool switches to Edit mode and highlights areas where potential intersections are detected.</dd><p />
<dt>**Polygon Data**</dt>
<dd>Checks for common polygon issues:<ul>
<li>Meshes are watertight</li>
<li>Meshes are within polycount budgets</li>
<li>Meshes don't use N-Gons Meshes</li>
<li>Meshes are non-manifold</li>
<li>Meshes don't have vertex color information</li></ul><p />Refer to the output messages to manually resolve any polygon data issues.</dd><p />
<dt>**Texture Format**</dt>
<dd>Checks that textures match texture requirements, such as resolution size. Users can also select an external image file. Refer to the output messages to manually resolve any texture related issues.</dd>
</dl>