On Face Prefabs

View as MarkdownOpen in ChatGPTOpen in Claude

GLTF

"faces": [
    {
        "gltf": {
            "@mesh": "path/to/gltf/model",
            "rotation": "0 0 0",
            "scale": "1.0 1.0 1.0",
            "translation": "0.0 0.0 0.0",
            "animation": {
                "name": "Animation 1",
                "mode": "loop",
                "seek_position": 100
            },
            "@use_physics": false,
            "gravity": "0.0 -1000.0 0.0",
            "bones": {
                "bone_1": 1.0,
                "bone_2": 0.0,
                "bone_3": 1.0,
                "bone_4": 0.0,
                "bone_5": 1.0
            },
            "colliders": [
                {
                    "center": "0. 0. 0.",
                    "radius": 100.0
                },
                {
                    "center": "10. 110. 420.",
                    "radius": 650.0
                },
                {
                    "center": "14. 300. 156.",
                    "radius": 10.0
                }
            ],
            "constraints": [
                {
                    "from": "bone_1",
                    "to": "bone_2",
                    "distance": 10.0
                },
                {
                    "from": "bone_2",
                    "to": "bone_3",
                    "distance": 50.0
                },
                {
                    "from": "bone_3",
                    "to": "bone_4",
                    "distance": 30.0
                },
                {
                    "from": "bone_4",
                    "to": "bone_5",
                    "distance": 60.0
                }
            ],
            "damping": 0.99
        }
        // ...
    }
    // ...
]

Place a 3D model in GLTF format on the face.

Parameter	Description	Optional	Default Value
@mesh	Path to a GLTF model. The leading @ in the parameter name is required. Supported formats are .glb and .gltf. The model and all associated files, such as shaders, textures, and sounds, must be located in the same folder.	+	+
rotation	Rotation angles, in degrees, around the X, Y, and Z axes. Note the default value.		"-90 0 0"
scale	Scale along the X, Y, and Z axes.		"1 1 1"
translation	Translates the model along the X, Y, and Z axes, in millimetres.		"0 0 0"
animation	Plays an animation from the GLTF file. All keys are optional; in most cases, an empty object is enough to play the default animation. Parameters: name - Selects an animation from the file by name. seek_position - Playback start position relative to the beginning of the animation, in milliseconds. mode - Determines how to play the animation selected by name. Possible values are off, loop, once, once_reversed, and fixed.		{}
@use_physics	Loads the GLTF model with physics simulation. The leading @ in the parameter name is required.		false
cut	Enables head occlusion geometry. Allowed values are head and head_with_ears; omit the parameter to disable cutting.		disabled
gravity	Sets the gravity vector along the X, Y, and Z axes.		"0 0 0"
bones	Sets bone inverse masses. The object keys are bone names and the values are inverse masses.		{}
colliders	Adds sphere colliders for physical bones. Each collider requires both center and radius. Parameters: center - X, Y, and Z coordinates of the center of the sphere. radius - Sphere radius.		[]
constraints	Adds constraints between bones. Each constraint requires from and to; the legacy-named distance value is optional. Parameters: from - Name of the from bone. to - Name of the destination bone. distance - Optional constraint strength (the actual length is calculated from the bones). Values below 1 create a flexible constraint; values greater than or equal to 1, or omission of this parameter, create a rigid constraint.		[]
bones_in_mv_space	Performs physical-bone calculations in model-view space.		false
damping	Controls damping for the physics simulation. Recommended values are in the range [0.9, 1.0].		0.99

note

When creating a 3D model in GLTF format for an effect, we recommend using our head geometry as a template. If you create the model without our head geometry, set its scale to 0.1 and rotate it -90 degrees around the X axis in the prefab.

Video Texture

"faces": [
    {
        "video_texture": {
            "@mesh": "path/to/gltf/model",
            "use_separate_alpha": true,
            "video": "path/to/video/texture",
            "alpha": "path/to/video/texture/alpha",
            "rotation": "0 0 0",
            "scale": "1.0 1.0 1.0",
            "translation": "0.0 0.0 0.0"
        }
        // ...
    }
    // ...
]

Parameter	Description	Optional	Default Value
@mesh	Path to a GLTF model. The leading @ in the parameter name is required. Supported formats are .glb and .gltf. A built-in plane is used by default.		built-in plane
use_separate_alpha	Set this parameter to false for a combined video with color on the left and alpha on the right. Set it to true when color and alpha are provided as separate videos.	+	+
video	Path to a video texture file. When use_separate_alpha is false, the video must be split in half, with color on the left and alpha on the right. For more information, see the supported video formats.	+	+
alpha	Path to the alpha video. This parameter is required when use_separate_alpha is true and ignored in combined mode. For more information, see the supported video formats.		``
rotation	Rotation angles, in degrees, around the X, Y, and Z axes.		"0 0 0"
scale	Scale along the X, Y, and Z axes.		"1 1 1"
translation	Translates the model along the X, Y, and Z axes, in millimetres.		"0 0 0"

use_separate_alpha is required because playback does not start until the alpha mode is selected. Set it to false for a side-by-side video (color on the left, alpha on the right), or to true and provide alpha as a second video. Videos loop automatically. If @mesh is omitted, the built-in plane is used.

Earrings

"faces": [
    {
        "earrings": {
            "@mesh_left": "path/to/left/gltf/model",
            "@mesh_right": "path/to/right/gltf/model",
            "@use_physics": true,
            "left": {
                "scale": "1 1 1",
                "rotation": "0 0 0",
                "translation": "0 0 0",
                "animation": {
                    "name": "static",
                    "mode": "fixed"
                },
                "gravity": "0.0 -1800.0 0.0",
                "damping": 0.99,
                "bones": {
                    "Bone_L_1": 0.0,
                    "Bone_L_2": 1.0,
                    "Bone_L_3": 1.0,
                    "Bone_L_4": 1.0,
                    "Bone_L_5": 1.0
                }
            },
            "right": {
                "scale": "1 1 1",
                "rotation": "0 0 0",
                "translation": "0 0 0",
                "animation": {
                    "name": "static",
                    "mode": "fixed"
                },
                "gravity": "0.0 -1800.0 0.0",
                "damping": 0.99,
                "bones": {
                    "Bone_R_1": 0.0,
                    "Bone_R_2": 1.0,
                    "Bone_R_3": 1.0,
                    "Bone_R_4": 1.0,
                    "Bone_R_5": 1.0
                }
            }
        }
        // ...
    }
    // ...
]

Place two GLTF earring models, one on each ear.

Parameter	Description	Optional	Default Value
@mesh_left	Path to the GLTF model for the left earring. The leading @ in the parameter name is required. Supported formats are .glb and .gltf. The model and all associated files, such as shaders, textures, and sounds, must be located in the same folder.	+	+
@mesh_right	Path to the GLTF model for the right earring. The leading @ in the parameter name is required. Supported formats are .glb and .gltf. The model and all associated files, such as shaders, textures, and sounds, must be located in the same folder.	+	+
@use_physics	Loads the GLTF models with physics simulation. The leading @ in the parameter name is required.		true
left	Settings for the left earring. All nested parameters are optional. Parameters: scale - Scale as X Y Z. Default: 1 1 1. rotation - Rotation in degrees as X Y Z. Default: 0 0 0. translation - Translation in millimetres as X Y Z. Default: 0 0 0. animation - Animation object with optional name, mode, and seek_position; mode is one of off, loop, once, once_reversed, or fixed. gravity - Gravity vector as X Y Z. Default: 0 0 0. damping - Physics damping. Default: 0.99. bones - Object mapping bone names to inverse masses. Default: {}.		{}
right	Settings for the right earring. All nested parameters are optional. Parameters: scale - Scale as X Y Z. Default: 1 1 1. rotation - Rotation in degrees as X Y Z. Default: 0 0 0. translation - Translation in millimetres as X Y Z. Default: 0 0 0. animation - Animation object with optional name, mode, and seek_position; mode is one of off, loop, once, once_reversed, or fixed. gravity - Gravity vector as X Y Z. Default: 0 0 0. damping - Physics damping. Default: 0.99. bones - Object mapping bone names to inverse masses. Default: {}.		{}

Transform, animation, and physics settings belong inside left or right; they are not top-level earring parameters.

Action Units

"faces": [
    {
        "action_units": {},
        // ...
    }
    // ...
]

Expose tracked facial action-unit values to GLTF models. This prefab has no parameters.

Eyes Whitening

Usage

"faces": [
    {
        "eyes_whitening": {
            "strength": 1.0
        }
        // ...
    }
    // ...
]

Makes the eyes look more expressive by whitening them.

Parameter	Description	Optional	Default Value
strength	Eye-whitening strength as a floating-point number in the range [0.0, 1.0].	+	+

Preview

Drag

Eyes Flare

Usage

"faces": [
    {
        "eyes_flare": {
            "strength": 1.0
        }
        // ...
    }
    // ...
]

Apply flare to the eyes.

Parameter	Description	Optional	Default Value
strength	Flare brightness as a floating-point number in the range [0.0, 1.0].	+	+

Preview

Drag

Teeth Whitening

Usage

"faces": [
    {
        "teeth_whitening": {
            "strength": 1.0
        }
        // ...
    }
    // ...
]

Apply whitening to the teeth.

Parameter	Description	Optional	Default Value
strength	Teeth-whitening strength as a floating-point number in the range [0.0, 1.0].	+	+

Preview

Drag

Softlight

Usage

"faces": [
    {
        "softlight": {
            "strength": 1.0,
            "texture": "path/to/file"
        }
        // ...
    }
    // ...
]

Apply softlight to the face.

Parameter	Description	Optional	Default Value
strength	Softlight strength as a floating-point number in the range [0.0, 1.0].	+	+
texture	Path to a custom softlight texture.		built-in softlight texture

Preview

Drag

Morphing

Morph (i.e., deform) specific parts of the face.

Usage

"faces": [
    {
        "morphing": {
            "eyebrows": {
                "spacing": 0.6,
                "height": 0.1,
                "bend": 1.0
            },
            "eyes": {
                "rounding": 0.6,
                "enlargement": 0.3,
                "height": 0,
                "spacing": 0.3,
                "squint": 0.3,
                "lower_eyelid_pos": 0,
                "lower_eyelid_size": 0,
                "down": 0,
                "eyelid_upper": 0,
                "eyelid_lower": 0
            },
            "face": {
                "narrowing": 0,
                "v_shape": 0,
                "cheekbones_narrowing": 0,
                "cheeks_narrowing": 0,
                "jaw_narrowing": 0,
                "chin_shortening": 0.3,
                "chin_narrowing": 0,
                "sunken_cheeks": 0.0,
                "cheeks_jaw_narrowing": 0,
                "jaw_wide_thin": 0,
                "chin": 0,
                "forehead": 0.3
            },
            "nose": {
                "width": 0.3,
                "length": 0.2,
                "tip_width": 0.1,
                "down_up": 0.1,
                "sellion": 0.2
            },
            "lips": {
                "size": 0.4,
                "height": 1.0,
                "thickness": 0.1,
                "mouth_size": 0.2,
                "smile": 0.8,
                "shape": 0.4,
                "sharp": 0.6
            }
        }
        // ...
    }
    // ...
]

All settings are optional.

Each group also accepts a numeric shorthand that controls its primary parameter: eyebrows controls spacing, eyes controls rounding, face controls narrowing, nose controls width, and lips controls size.

For low-level control, weights accepts exactly 37 numbers in this order: eyebrow spacing, height, bend; eye enlargement, rounding, height, spacing, squint, lower-eyelid position, lower-eyelid size; nose length, width, tip width; lip height, size, thickness, mouth size, smile, shape; face narrowing, V-shape, cheekbone narrowing, cheek narrowing, jaw narrowing, chin shortening, chin narrowing, sunken cheeks, cheek-and-jaw narrowing, jaw wide/thin; nose down/up; eyes down, upper eyelid, lower eyelid; chin, forehead, nose sellion, and lip sharpness. The named groups are less error-prone and are preferred.

Eyebrows

Parameter	Description	Optional	Default Value
spacing	Adjusts the spacing between the eyebrows in the range [-1, 1].		0.0
height	Raises or lowers the eyebrows in the range [-1, 1].		0.0
bend	Adjusts the eyebrow bend in the range [-1, 1].		0.0

Eyes

Parameter	Description	Optional	Default Value
rounding	Adjusts eye roundness in the range [0, 1].		0.0
enlargement	Enlarges the eyes in the range [0, 1].		0.0
height	Raises or lowers the eyes in the range [-1, 1].		0.0
spacing	Adjusts the spacing between the eyes in the range [-1, 1].		0.0
squint	Adjusts the eyelids to make the person squint, in the range [-1, 1].		0.0
lower_eyelid_pos	Raises or lowers the lower eyelid in the range [-1, 1].		0.0
lower_eyelid_size	Enlarges or shrinks the lower eyelid in the range [-1, 1].		0.0
down	Moves the eyes downward in the range [0, 1].		0.0
eyelid_upper	Adjusts the upper eyelid in the range [0, 1].		0.0
eyelid_lower	Adjusts the lower eyelid in the range [0, 1].		0.0

Face

Parameter	Description	Optional	Default Value
narrowing	Narrows the face in the range [0, 1].		0.0
v_shape	Shrinks the chin and narrows the cheeks in the range [0, 1].		0.0
cheekbones_narrowing	Narrows the cheekbones in the range [-1, 1].		0.0
cheeks_narrowing	Narrows the cheeks in the range [0, 1].		0.0
jaw_narrowing	Narrows the jaw in the range [0, 1].		0.0
chin_shortening	Shortens the chin in the range [0, 1].		0.0
chin_narrowing	Narrows the chin in the range [0, 1].		0.0
sunken_cheeks	Sinks the cheeks and emphasizes the cheekbones in the range [0, 1].		0.0
cheeks_jaw_narrowing	Narrows the cheeks and jaw in the range [0, 1].		0.0
jaw_wide_thin	Adjusts the jaw between wide and thin in the range [0, 1].		0.0
chin	Adjusts the chin in the range [0, 1].		0.0
forehead	Adjusts the forehead in the range [0, 1].		0.0

Nose

Parameter	Description	Optional	Default Value
width	Adjusts nose width in the range [-1, 1].		0.0
length	Adjusts nose length in the range [-1, 1].		0.0
tip_width	Adjusts nose-tip width in the range [0, 1].		0.0
down_up	Moves the nose down or up in the range [0, 1].		0.0
sellion	Adjusts the nose sellion in the range [0, 1].		0.0

Lips

Parameter	Description	Optional	Default Value
size	Adjusts the width and vertical size of the lips in the range [-1, 1].		0.0
height	Raises or lowers the lips in the range [-1, 1].		0.0
thickness	Adjusts lip thickness in the range [-1, 1].		0.0
mouth_size	Adjusts mouth size in the range [-1, 1].		0.0
smile	Adjusts the smile in the range [0, 1].		0.0
shape	Adjusts lip shape in the range [-1, 1].		0.0
sharp	Adjusts lip sharpness in the range [0, 1].		0.0

Preview

Drag

Eyes

Recolors the eyes.

Usage

"faces": [
    {
        "eyes": {
            "eyes": "0 0.2 0.8 0.64",
            "corneosclera": "1 1 1 1",
            "pupil": "0 0 0 1"
        }
        // ...
    }
    // ...
]

Parameter	Description	Optional	Default Value
eyes	Iris color. See the color-format note in the prefabs overview.		"0 0 0 0"
corneosclera	Corneosclera color, commonly called the sclera.		"0 0 0 0"
pupil	Pupil color. See the color-format note in the prefabs overview.		"0 0 0 0"

Preview

Drag

Hair

Recolors the hair. A single color is typically used to set the hair color:

"faces": [
    {
        "hair": {
            "color": [
                "0.19 0.06 0.25 1.0"
            ]
        }
        // ...
    }
    // ...
]

Hair recoloring also supports two to five colors to create a vertical gradient. The following example uses two colors:

"faces": [
    {
        "hair": {
            "color": [
                "0.19 0.06 0.25 1.0",
                "0.09 0.25 0.38 1.0"
            ]
        }
        // ...
    }
    // ...
]

Parameter	Description	Optional	Default Value
color	A single color string applies a solid color. An array of one to five colors is also accepted: one element applies a solid color, while two to five create a vertical gradient.		"0 0 0"

Preview

Drag

Hair Strands

Recolors individual hair strands. This prefab supports one to five colors for recoloring different strands.

"faces": [
    {
        "hair_strands": {
            "color": [
                "0.80 0.40 0.40 1.0",
                "0.83 0.40 0.40 1.0",
                "0.85 0.75 0.75 1.0",
                "0.87 0.60 0.60 1.0",
                "0.99 0.65 0.65 1.0"
            ]
        }
        // ...
    }
    // ...
]

Parameter	Description	Optional	Default Value
color	Applies one to five colors to hair strands. Provide a single color string or an array containing up to five colors.		"0 0 0 0"

Preview

Drag