Facial Expression System

Define facial presets that react to active penetration targets, scene contexts, penetrator size and girth, and penetration depth.

Overview

A facial preset is a group of morph effects. The resolver chooses one winning preset per actor, then applies its effects to phonemes, expressions, modifiers, and optional MFEE morphs.

Presets are part of RaceConfig. That means default-inheriting override files keep inherited presets and append their own. The list is sorted by priority after loading.

Placement

Place root defaults in accurate-penetration.toml or place race-specific entries in ppa-override-configs.

# Root config or single override file
[[FacialPreset]]
Targets = ["Mouth"]
Priority = 10

# Inside an array-style RaceConfig override
[[Override]]
Races = ["Skyrim.esm|013745"]

[[Override.FacialPreset]]
Targets = ["Mouth"]
Priority = 10

Inheritance

Because presets are appended to the inherited list, use Inherits = "" on a RaceConfig override when you need the actor to start with no inherited facial presets.

Structure

[[FacialPreset]]
Targets = ["Mouth"]
Priority = 50
Smoothing = 8.0
OverridePhonemes = true

[[FacialPreset.Effects]]
Type = "Phoneme"
Index = 1
TargetValue = 0.8

[[FacialPreset.Effects]]
Type = "Modifier"
Index = 12
TargetValue = 0.5

Preset Fields

Property	Type	Description
Targets	string or string[]	Optional active targets. Accepted values are `Mouth`, `Vagina`, `Anus`, and `Hands`. If omitted, the preset can match any active target.
Contexts	string or string[]	Optional scene context flags. All listed contexts must be present.
PenisSizeMin	float	Minimum penetrator size. `0` disables the minimum.
PenisSizeMax	float	Maximum penetrator size. `0` disables the maximum.
PenisGirthMin	float	Minimum penetrator girth. `0` disables the minimum.
PenisGirthMax	float	Maximum penetrator girth. `0` disables the maximum.
Priority	int	Higher priority wins among matching presets.
Smoothing	float	How quickly morph values approach the target. Default is `8.0`.
OverridePhonemes	bool	Zeros phonemes not driven by the winning preset. Legacy alias `OverridePhoneme` is still accepted.
OverrideExpressions	bool	Zeros expressions not driven by the winning preset.
OverrideModifiers	bool	Zeros modifiers not driven by the winning preset.

Targets Are Optional

The loader does not require Targets. A targetless preset can match any active target and uses the strongest active target input for size, girth, and depth calculations.

Effect Fields

Property	Type	Description
Type	string	`Phoneme`, `Expression`, `Modifier`, or `MFEE`. Defaults to `Phoneme` if omitted or invalid.
Index	int	Numeric morph index for phoneme, expression, and modifier effects.
MorphCategory	string	MFEE category name.
MorphName	string	MFEE morph name.
TargetValue	float	Value reached at full effect strength. Default is `1.0`.
MinTargetValue	float	Starting value when depth scaling is active. Default is `0.0`.
MinPenetrationDepth	float	Depth where scaling starts. Negative values are clamped to `0.0`.
MaxPenetrationDepth	float	Depth where scaling reaches `TargetValue`. Negative values are clamped to `0.0`.

If MinPenetrationDepth is greater than MaxPenetrationDepth and max is above zero, the loader swaps them.

Depth Scaling

An effect uses depth scaling when MaxPenetrationDepth is greater than MinPenetrationDepth. The value interpolates from MinTargetValue to TargetValue across that depth range.

[[FacialPreset.Effects]]
Type = "Expression"
Index = 15
MinTargetValue = 0.2
TargetValue = 1.0
MinPenetrationDepth = 2.0
MaxPenetrationDepth = 10.0

Scene Contexts

These strings are accepted by the settings loader. A preset with multiple contexts requires all of them.

Context	Description	Notes
Vaginal	Vaginal scene context.	Can be combined with tone tags.
Anal	Anal scene context.
Oral	Oral scene context.
Aggressive	Aggressive scene context.
FemDom	Female-dominant scene context.
Loving	Loving scene context.
Dirty	Dirty scene context.
Boobjob	Boobjob context.
Handjob	Handjob context.
Footjob	Footjob context.
Masturbation	Masturbation context.

[[FacialPreset]]
Targets = ["Vagina"]
Contexts = ["Vaginal", "Aggressive"]
Priority = 20

Selection

The update loop chooses one active preset per actor.

The preset must match at least one active target, or have no targets.

Context, size, and girth conditions must pass.

The highest priority matching preset wins.

When a preset has multiple targets, size, girth, and depth calculations use the maximum values among the relevant active target inputs.

MFEE

MFEE effects use MorphCategory and MorphName instead of a numeric index.

[[FacialPreset.Effects]]
Type = "MFEE"
MorphCategory = "Misc"
MorphName = "Biting_lips"
TargetValue = 100.0

Scale

Standard Skyrim phoneme, expression, and modifier effects normally use a 0.0 to 1.0 scale. MFEE morphs commonly use a 0 to 100 scale.

Morph Reference

Phonemes 0-15

0 Aah
1 BigAah
2 BMP
3 ChJSh
4 DST
5 Eee
6 Eh
7 FV
8 I
9 K
10 N
11 Oh
12 OohQ
13 R
14 Th
15 W

Expressions 0-16

0 Dialogue Anger
1 Dialogue Fear
2 Dialogue Happy
3 Dialogue Sad
4 Dialogue Surprise
5 Dialogue Puzzled
6 Dialogue Disgusted
7 Mood Neutral
8 Mood Anger
9 Mood Fear
10 Mood Happy
11 Mood Sad
12 Mood Surprise
13 Mood Puzzled
14 Mood Disgusted
15 Combat Shout
16 Combat Anger

Modifiers 0-13

0 Blink Left
1 Blink Right
2 Brow Down Left
3 Brow Down Right
4 Brow In Left
5 Brow In Right
6 Brow Up Left
7 Brow Up Right
8 Look Down
9 Look Left
10 Look Right
11 Look Up
12 Squint Left
13 Squint Right

Example: Basic Mouth

Default-style oral preset

Drives a blended open-mouth shape and zeroes other phonemes while active.

[[FacialPreset]]
Targets = ["Mouth"]
Priority = 99999
OverridePhonemes = true
Smoothing = 8.0

[[FacialPreset.Effects]]
Type = "Phoneme"
Index = 0
TargetValue = 0.75

[[FacialPreset.Effects]]
Type = "Phoneme"
Index = 1
TargetValue = 0.75

[[FacialPreset.Effects]]
Type = "Phoneme"
Index = 5
TargetValue = 1.0

Example: Context Variant

[[FacialPreset]]
Targets = ["Vagina"]
Contexts = ["Aggressive"]
Priority = 25
OverrideExpressions = true
OverrideModifiers = true

[[FacialPreset.Effects]]
Type = "Expression"
Index = 15
MinTargetValue = 0.2
TargetValue = 1.0
MinPenetrationDepth = 2.0
MaxPenetrationDepth = 12.0

Example: Override File

This override starts from a blank RaceConfig, defines its own race predicate, and adds only the facial presets shown here.

Inherits = ""
Races = ["SomeRaceMod.esp|001234"]

[[FacialPreset]]
Targets = ["Mouth"]
Priority = 10

[[FacialPreset.Effects]]
Type = "MFEE"
MorphCategory = "Misc"
MorphName = "EXPR2_Mouth_Open_Wide"
TargetValue = 90.0