hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-25 04:54: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

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>