rojo/.cursor/rules/roblox/reference/engine/classes/FaceControls.yaml
2026-02-02 12:08:47 -06:00

1119 lines
29 KiB
YAML

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
name: FaceControls
type: class
memory_category: Animation
summary: |
The `Class.FaceControls` object defines a set of properties for controlling
the facial expressions of a Dynamic Head.
description: |
The `Class.FaceControls` object defines a set of properties for controlling
the facial expressions of a character head capable of animation.
The FaceControls properties are based on the Facial Action Coding System
(FACS), a comprehensive system for describing all visually discernible facial
movement based on anatomy. `Class.FaceControls` properties can only be set
between 0 and 1. Different combinations of the `Class.FaceControls` property
values create different facial expressions. Recording multiple facial
expressions over time creates facial animation.
## What is an Animatable Head?
An animatable head is a `Class.MeshPart` that implements a facial rig and is
capable of playing facial animations and triggering facial expressions. A
`Class.FaceControls` object that is a child of a head `Class.MeshPart` can
change the facial expressions of the head.
A head consists of the following three components:
- Skinned MeshPart instance for the head geometry with an internal rig that
deforms this skinned MeshPart
- FaceControls instance that drives the internal rig when properties such as
FaceControls.JawDrop are changed.
- Cage `Class.WrapTarget` instance for tight fitting facial accessories
In a third-party modeling tool, such as Blender or Maya, an artist can create
a joint-driven facial rig, pose the joints to match each of the individual
FACS controls, and save as an FBX. When a head `.FBX` is imported in Studio, a
facs-to-joint mapping is created. This mapping deforms the mesh geometry when
FaceControls properties are changed. The mapping and the facial rig (including
`Class.Bone` instances) are not exposed to developers and can only be accessed
through the FaceControls instance. The `Class.MeshPart` for a Dynamic Head
looks and behaves the same as a regular `Class.MeshPart` except when a
FaceControls instance is a child of the MeshPart. Editing the properties of
the FaceControls deforms the MeshPart's geometry. These properties are
available to animate in the Animation Editor.
See [Facial Animation](../../../art/characters/facial-animation/index.md) for
more information on usage and creation of an animatable head.
## Animatable Heads in the Marketplace
If you are publishing your head to the Marketplace, your head asset must
include a minimum subset of face controls. Roblox's publishing validation
rejects assets without the following required poses:
- EyesLookDown
- EyesLookLeft
- EyesLookRight
- EyesLookUp
- JawDrop
- LeftEyeClosed
- LeftLipCornerPuller
- LeftLipStretcher
- LeftLowerLipDepressor
- LeftUpperLipRaiser
- LipsTogether
- Pucker
- RightEyeClosed
- RightLipCornerPuller
- RightLipStretcher
- RightLowerLipDepressor
- RightUpperLipRaiser
See
[FACS pose reference](../../../art/characters/facial-animation/facs-poses-reference.md)
for more information on usage and creation of an animatable head.
code_samples: []
inherits:
- Instance
descendants: []
tags: []
deprecation_message: ''
properties:
- name: FaceControls.ChinRaiser
summary: |
Raises the chin up; moves the lower lip upwards.
description: |
Raises the chin up; moves the lower lip upwards
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.ChinRaiserUpperLip
summary: |
Moves the upper lip when ChinRaiser is engaged and touching the upper lip.
description: |
Moves the upper lip when ChinRaiser is engaged and touching the upper lip
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.Corrugator
summary: |
Brings the left and right brows inward together.
description: |
Brings the left and right brows inward together
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.EyesLookDown
summary: |
Moves gaze down. This is a required pose for avatars.
description: |
Moves gaze down. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.EyesLookLeft
summary: |
Moves gaze left. This is a required pose for avatars.
description: |
Moves gaze left. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.EyesLookRight
summary: |
Moves gaze right. This is a required pose for avatars.
description: |
Moves gaze right. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.EyesLookUp
summary: |
Moves gaze up. This is a required pose for avatars.
description: |
Moves gaze up. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.FlatPucker
summary: |
Also known as lip tightener; brings the corners of the mouth inward and
pressing the lips back against the teeth.
description: |
Also known as lip tightener; brings the corners of the mouth inward and
pressing the lips back against the teeth
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.Funneler
summary: |
Makes a 'O' shape with the mouth.
description: |
Makes a 'O' shape with the mouth
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.JawDrop
summary: |
Lowers the jaw downward opening the mouth. This is a required pose for
avatars.
description: |
Lowers the jaw downward opening the mouth. This is a required pose for
avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Jaw
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.JawLeft
summary: |
Moves mouth and jaw to the left (character left).
description: ''
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Jaw
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.JawRight
summary: |
Moves mouth and jaw to the right (character right).
description: |
Moves mouth and jaw to the right (character right)
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Jaw
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftBrowLowerer
summary: |
Lowers the left brow down.
description: |
Lowers the left brow down
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftCheekPuff
summary: |
Puffs up the left cheek.
description: |
Puffs up the left cheek
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftCheekRaiser
summary: |
Squints the left eye.
description: |
Squints the left eye
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftDimpler
summary: |
Moves the corners of the mouth back in Z.
description: |
Moves the corners of the mouth back in Z
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftEyeClosed
summary: |
Closes the left eyelid. This is a required pose for avatars.
description: |
Closes the left eyelid. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftEyeUpperLidRaiser
summary: |
Raises the left eyelid upwards to reveal more of the eye white above the
iris.
description: |
Raises the left eyelid upwards to reveal more of the eye white above the
iris
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftInnerBrowRaiser
summary: |
Raises the interior half of the left brow upwards.
description: |
Raises the interior half of the left brow upwards
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftLipCornerDown
summary: |
Lowers the corners of the mouth downwards in a frown.
description: |
Lowers the corners of the mouth downwards in a frown
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftLipCornerPuller
summary: |
Raises the corners of the mouth upwards in a smile. This is a required
pose for avatars.
description: |
Raises the corners of the mouth upwards in a smile. This is a required
pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftLipStretcher
summary: |
Stretches the corners of the mouth apart. This is a required pose for
avatars.
description: |
Stretches the corners of the mouth apart. This is a required pose for
avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftLowerLipDepressor
summary: |
Lowers the lower lip down away from the upper lip revealing the lower
teeth. This is a required pose for avatars.
description: |
Lowers the lower lip down away from the upper lip revealing the lower
teeth. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftNoseWrinkler
summary: |
Raise the left nostril, pulls the brow down slightly, and wrinkles on the
side of the nose.
description: |
Raise the left nostril, pulls the brow down slightly, and wrinkles on the
side of the nose
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftOuterBrowRaiser
summary: |
Raises the outer part of the left brow upwards.
description: |
Raises the outer part of the left brow upwards
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LeftUpperLipRaiser
summary: |
Raises the left upper lip away from the lower lip revealing the upper
teeth. This is a required pose for avatars.
description: |
Raises the left upper lip away from the lower lip revealing the upper
teeth. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LipPresser
summary: |
Presses the lips together.
description: |
Presses the lips together
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LipsTogether
summary: |
Brings the lips together relative to JawDrop. This is a required pose for
avatars.
description: |
Brings the lips together relative to JawDrop. This is a required pose for
avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.LowerLipSuck
summary: |
Rolls the lower lip up over the teeth.
description: |
Rolls the lower lip up over the teeth
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.MouthLeft
summary: |
Moves the mouth left.
description: |
Moves the mouth left
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.MouthRight
summary: |
Moves the mouth right.
description: |
Moves the mouth right
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.Pucker
summary: |
Makes a kiss-like shape with the mouth. This is a required pose for
avatars.
description: |
Makes a kiss-like shape with the mouth. This is a required pose for
avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightBrowLowerer
summary: |
Lowers the right brow down.
description: |
Lowers the right brow down
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightCheekPuff
summary: |
Puffs up the right cheek.
description: |
Puffs up the right cheek
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightCheekRaiser
summary: |
Squints the right eye.
description: |
Squints the right eye
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightDimpler
summary: |
Moves the corners of the mouth back in Z.
description: |
Moves the corners of the mouth back in Z
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightEyeClosed
summary: |
Closes the right eyelid. This is a required pose for avatars.
description: |
Closes the right eyelid. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightEyeUpperLidRaiser
summary: |
Raises the right eyelid upwards to reveal more of the eye white above the
iris.
description: |
Raises the right eyelid upwards to reveal more of the eye white above the
iris
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Eyes
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightInnerBrowRaiser
summary: |
Raises the interior half of the right brow upwards.
description: |
Raises the interior half of the right brow upwards
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightLipCornerDown
summary: |
Lowers the corners of the mouth downwards in a frown.
description: |
Lowers the corners of the mouth downwards in a frown
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightLipCornerPuller
summary: |
Raises the corners of the mouth upwards in a smile. This is a required
pose for avatars.
description: |
Raises the corners of the mouth upwards in a smile. This is a required
pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightLipStretcher
summary: |
Stretches the corners of the mouth apart. This is a required pose for
avatars.
description: |
Stretches the corners of the mouth apart. This is a required pose for
avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightLowerLipDepressor
summary: |
Lowers the lower lip down away from the upper lip revealing the lower
teeth. This is a required pose for avatars.
description: |
Lowers the lower lip down away from the upper lip revealing the lower
teeth. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightNoseWrinkler
summary: |
Raises the right nostril, pulls the brow down slightly, and wrinkles on
the side of the nose.
description: |
Raises the right nostril, pulls the brow down slightly, and wrinkles on
the side of the nose
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightOuterBrowRaiser
summary: |
Raises the outer part of the right brow upwards.
description: |
Raises the outer part of the right brow upwards
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Brows
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.RightUpperLipRaiser
summary: |
Raises the right upper lip away from the lower lip revealing the upper
teeth. This is a required pose for avatars.
description: |
Raises the right upper lip away from the lower lip revealing the upper
teeth. This is a required pose for avatars.
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.TongueDown
summary: |
Bends the tongue down.
description: |
Bends the tongue down
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Tongue
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.TongueOut
summary: |
Extends the tip of the tongue out of the mouth.
description: |
Extends the tip of the tongue out of the mouth
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Tongue
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.TongueUp
summary: |
Bends the tongue up.
description: |
Bends the tongue up
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Tongue
serialization:
can_load: false
can_save: false
capabilities:
- Animation
- name: FaceControls.UpperLipSuck
summary: |
Rolls the upper lip around the teeth.
description: |
Rolls the upper lip around the teeth
code_samples: []
type: float
tags:
- NotReplicated
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Mouth
serialization:
can_load: false
can_save: false
capabilities:
- Animation
methods: []
events: []
callbacks: []