Override Configuration System
Create custom physics configurations for different races, creature types, and actors with specific characteristics using simple TOML override files.
Overview
The override system lets you customize physics behavior on a per-race or per-actor basis. Instead of one global config for everyone, you can define separate settings for specific races (like custom creature mods) or actors matching certain conditions (like having specific bones).
When the mod needs a config for an actor, it follows this lookup order:
1 Race-specific overrides — checks if the actor's race has a dedicated override (fast hash lookup).
2 Global predicate-based overrides — falls back to overrides with matching predicates (evaluated at runtime).
3 Default config — uses the settings from accurate-penetration.toml if nothing else matches.
All overrides inherit from the defaults, so you only need to specify the settings you want to change.
File Location & Load Order
Override files are loaded from:
Data/SKSE/Plugins/ppa-override-configs/
Place your .toml files in this folder. Files are loaded in reverse alphabetical order, meaning 00_humans.toml loads last and has the highest priority. Use numbered prefixes to control the load order.
A good naming convention is to prefix files with numbers: 99_fallback.toml loads first (lowest priority), 00_important.toml loads last (highest priority). Within a single file, overrides defined later in [[Override]] arrays also have higher priority than earlier ones.
If multiple overrides match the same race, the one with the highest priority wins. If an override has predicates, they must all pass for it to apply. The first matching override is used — the system does not merge multiple overrides together.
File Structure
Each override file uses TOML format. You can define a single override at the root level, or use [[Override]] arrays for multiple configs in one file.
Single Override — Root Level
The entire file is one override. Settings are placed directly at the root:
Races = ["Skyrim.esm|013745"] [Vagina] Scale = 3.0
Multiple Overrides — Array Format
Use [[Override]] tables to pack multiple configs into one file. Note that sub-tables are prefixed with Override.:
[[Override]] Races = ["Skyrim.esm|013745"] [Override.Vagina] Scale = 3.0 [[Override]] Races = ["Skyrim.esm|013746"] [Override.Anus] Scale = 2.5
Use single-override files for simple cases (one race, one creature) and [[Override]] arrays when grouping related creatures together (e.g. all canines in one file, all bears in another).
FormID Formats
You can specify race FormIDs in several ways. The Races array accepts any of the following formats.
Plugin|LocalID — Recommended
The most portable format. The local ID is the last 6 hex digits of the FormID as shown in xEdit. The mod handles load order index automatically.
Races = [ "Skyrim.esm|013745", "Dawnguard.esm|00283A", ]
Light Plugin Format
Works the same way. The mod detects light plugins (ESL-flagged files) automatically:
Races = [ "SomeCreatureMod.esl|000800", ]
Raw FormID Format
If you know the exact runtime FormID including the load order prefix, you can use it directly. This is less portable between load orders:
Races = [ "0200C5F0", "020122B7", ]
The 0x prefix is optional — both 0x0200C5F0 and 0200C5F0 work.
If your hex string is 7 or more characters long and you don't specify a plugin name, the mod treats it as a full runtime FormID and uses it as-is. Shorter strings without a plugin name default to Skyrim.esm.
Predicates
Predicates let you create conditional overrides that apply based on actor properties at runtime, not just race. They're defined under a [Predicates] table. When multiple predicates are present, all of them must pass for the override to apply.
IsSex
Match actors by biological sex. Values: 0 = Male, 1 = Female.
[Predicates] IsSex = [0, 1] [Vagina] Scale = 2.5
HasAllBones
Only match actors that have every single specified bone present in their skeleton:
[Predicates] HasAllBones = ["TailBone01", "TailBone02", "TailBone03"] [Anus.Position] Anchor = "TailBone01" Offset = [0.0, -2.0, 0.0] [[Anus.Position.DepthWaypoints]] Offset = [0.0, 0.0, 5.0]
HasOneBone
Match actors that have at least one of the specified bones:
[Predicates] HasOneBone = ["CreaturePenis01", "MonsterSchlong01"] [Penis] Bones = ["CreaturePenis01", "CreaturePenis02", "CreaturePenis03"]
Combining Predicates
You can use multiple predicates together, and you can combine them with a Races array. All conditions must pass:
Races = ["Skyrim.esm|013745"] [Predicates] IsSex = [1] HasAllBones = ["VaginaB1", "Clitoral1"] [Vagina] Scale = 2.0
Predicates are evaluated at runtime against each actor. IsSex checks the actor base's sex, while HasAllBones and HasOneBone search the actor's 3D skeleton for named nodes. This means bone-based predicates only work when the actor's 3D model is loaded.
Global vs Race-Scoped Overrides
Overrides come in two flavors depending on whether you include a Races array.
Race-Scoped
If you include a Races array, the override only applies to actors of those specific races. Race lookups are fast (hash map) and are checked first.
Races = ["Skyrim.esm|013746"] [Vagina] Scale = 2.0
Global
Without a Races array, the override is "global" and is checked against all actors — but only if it has predicates. A global override with no predicates would match everything and is ignored.
[Predicates] HasAllBones = ["CustomPenis01"] [Penis] Bones = ["CustomPenis01", "CustomPenis02"]
Race-scoped overrides are a fast O(1) hash lookup. Global predicate overrides are checked sequentially for every actor that doesn't match a race override. Keep the number of global overrides reasonable.
Orifice Positions
Each orifice (vagina, anus, mouth) has an anchor bone, an offset from that bone, and depth waypoints that define the internal path the penetrator follows.
For fine-tuning orifice positions, use the in-game editor: press the SelectActor hotkey, then choose Change Hole Positions. This opens an interactive editor that's much easier than manually tweaking offset values in config files.
| Property | Type | Description |
|---|---|---|
| Anchor | string | The skeleton bone to attach the orifice entry point to. |
| Offset | float[3] | Position offset from the anchor bone (X, Y, Z). |
| CollisionCylinderRadius | float | How wide the collision detection cylinder is. Used to determine which orifice the penis should target. |
| CollisionCylinderHeightModifier | float | Scales the cylinder height for detection tolerance. |
Depth Waypoints
Waypoints define the internal path (tunnel) that the penetrator follows during penetration. The penis bends to follow this curved path. You can define unlimited waypoints per orifice.
| Property | Type | Description |
|---|---|---|
| Anchor | string | Optional Bone to attach this waypoint to. If omitted, the offset is relative to the previous waypoint's anchor. |
| Offset | float[3] | Position offset from the anchor bone (X, Y, Z). |
| CornerSmoothing | float | Smooths the transition between waypoints. Range: 0.0–1.9. Default: 0.5. |
| CollisionRadius | float | Collision radius at this waypoint. Default: 4.0. |
Don't exceed a CornerSmoothing value of 1.9 on sharp angles, or the path calculation will produce unexpected results.
[Vagina.Position] Anchor = "NPC Pelvis [Pelv]" Offset = [0.0, -1.0, -4.32] CollisionCylinderRadius = 1.0 CollisionCylinderHeightModifier = 0.7 [[Vagina.Position.DepthWaypoints]] Offset = [0.0, -1.0, 6.0] CornerSmoothing = 1.0 [[Vagina.Position.DepthWaypoints]] Anchor = "NPC Spine1 [Spn1]" Offset = [0.0, 6.0, 0.0] CornerSmoothing = 0.5
Orifice Bone Names
Override which skeleton bones are used for orifice opening (gape) animations. The vagina uses 4 directional nodes, and the anus uses 4 corner nodes.
Vagina Nodes
| Property | Default | Description |
|---|---|---|
| NodeL | "NPC L Pussy02" | Left side bone |
| NodeR | "NPC R Pussy02" | Right side bone |
| NodeBack | "VaginaB1" | Back/bottom bone |
| NodeTop | "Clitoral1" | Top bone |
Anus Nodes
| Property | Default | Description |
|---|---|---|
| NodeLB | "NPC LB Anus2" | Left-bottom corner |
| NodeRB | "NPC RB Anus2" | Right-bottom corner |
| NodeRT | "NPC RT Anus2" | Right-top corner |
| NodeLT | "NPC LT Anus2" | Left-top corner |
[Vagina] NodeL = "NPC L Pussy02" NodeR = "NPC R Pussy02" NodeBack = "VaginaB1" NodeTop = "Clitoral1" [Anus] NodeLB = "NPC LB Anus2" NodeRB = "NPC RB Anus2" NodeRT = "NPC RT Anus2" NodeLT = "NPC LT Anus2"
Penis Configuration
Configure the penetrator bone chain and its physical properties. This is essential for creature overrides, since each creature type typically has different bone names and orientations.
| Property | Type | Description |
|---|---|---|
| Bones | string[] | Ordered list of bones forming the penis chain, from base to tip. The mod bends these bones to follow the orifice path. |
| ActivationRange | float | How close the penis tip needs to be to an orifice to start tracking. Default: 3.5. |
| Girth | float | Average width/radius of the penis shaft. Affects collision and orifice opening. Default: 0.9. |
| TipExtension | float | Virtual extension past the last bone for the tip. Default: 2.9. |
| LocalForwardAxis | float[3] | The forward direction of the penis bones. Default: [0, 1, 0] for humanoids. Creatures often use [1, 0, 0]. |
| BaseOffset | float[3] | Offset for curve projection casting. Slightly lower than the base reduces initial bend. Use NifSkope to find correct values for creatures. |
| RotateBase | bool | Rotate the base bone along with the rest for smoother appearance. Default: true. |
| MinProjectionDistance | float | Minimum distance from penis base to orifice entry. Simulates "bottoming out". 0 = no limit. Default: 0. |
[Penis] Bones = [ "NPC GenitalsBase [GenBase]", "NPC Genitals01 [Gen01]", "NPC Genitals02 [Gen02]", "NPC Genitals03 [Gen03]", "NPC Genitals04 [Gen04]", "NPC Genitals05 [Gen05]", "NPC Genitals06 [Gen06]", ] ActivationRange = 3.5 Girth = 0.9 TipExtension = 2.9 LocalForwardAxis = [0.0, 1.0, 0.0] BaseOffset = [0.0, 1.206299, 1.206299] RotateBase = true
Penis Behavior Flags
Additional flags that control how the penis interacts with the physics solver.
| Property | Type | Description |
|---|---|---|
| PreserveHavokState | bool | Preserves original bone lengths from Havok animations. Useful for schlongs that animate their bone spacing (common with creature rigs). Default: false. |
| ClipFix | bool | Shrinks bones that extend past the orifice tunnel to prevent clipping through the body. Default: false. |
| HideDepthOffset | float | How far past the tunnel end before the shrinking kicks in. Only used when ClipFix is true. Default: 2.0. |
[Penis] PreserveHavokState = false ClipFix = false HideDepthOffset = 2.0
Opening Physics
Controls how orifices visually respond during penetration — gaping, gripping, and friction effects.
| Property | Type | Description |
|---|---|---|
| Scale | float | Base opening distance during penetration. Higher = wider gape. |
| ScaleMax | float | Maximum opening distance. Caps how wide the orifice can stretch. |
| GripStrength | float | How much the orifice "grips" and follows the penetrator's movement. |
| GripClampForward | float | Clamps how far forward (into the body) the grip animation can pull the mesh. |
| GripClampBackward | float | Clamps how far backward (out of the body) the grip animation can pull the mesh. |
| RubIntensity | float | Intensity of the rubbing/friction animation effect. |
These properties go under the [Vagina] or [Anus] table for the respective orifice:
[Vagina] Scale = 1.5 ScaleMax = 3.0 GripStrength = 5.0 GripClampForward = 5.0 GripClampBackward = 5.0 RubIntensity = 2.5 [Anus] Scale = 2.0 ScaleMax = 4.5 GripStrength = 2.0 GripClampForward = 4.0 GripClampBackward = 4.0 RubIntensity = 1.5
Animation
Global animation response settings that control how physics react to movement speed.
| Property | Type | Description |
|---|---|---|
| SpeedSensitivity | float | How responsive the physics are to movement speed. Default: 1.0. |
| SmoothStrength | float | Smoothing window for speed calculations. Higher = smoother but laggier response. Default: 0.5. |
[Animation] SpeedSensitivity = 1.0 SmoothStrength = 0.5
Hands
Configure handjob detection and grip behavior for each hand independently.
| Property | Type | Description |
|---|---|---|
| Enabled | bool | Whether this hand is active for detection. Default: true. |
| DetectionRadius | float | How close the hand must be to the penis to activate. Default: 15.0. |
| GripLength | float | Effective hand length for grip calculations. Default: 2.0. |
| GripOffsetAdjustment | float[3] | Fine-tune the grip position (X, Y, Z). Default: [0, 0, 1]. |
[Hands.Left] Enabled = true DetectionRadius = 15.0 GripLength = 2.0 GripOffsetAdjustment = [0.0, 0.0, 1.0] [Hands.Right] Enabled = true DetectionRadius = 15.0 GripLength = 2.0 GripOffsetAdjustment = [0.0, 0.0, 1.0]
Facial Expressions
Override files can include facial expression presets that apply to actors of the overridden race. These use the same [[FacialPreset]] system documented in the full facial expression tutorial.
For the complete guide on facial presets, effects, depth scaling, morph references, and MFEE integration, see the Facial Expression System Tutorial.
In an override file using the array format, facial presets go under [[Override.FacialPreset]] instead of [[FacialPreset]]:
[[Override]] Races = ["SomeRaceMod.esp|001234"] [[Override.FacialPreset]] Targets = ["Mouth"] Priority = 10 OverridePhonemes = true [[Override.FacialPreset.Effects]] Type = "Phoneme" Index = 1 TargetValue = 0.8
Example: Single Override File
A complete example for a custom race, saved as a standalone file like 50_custom_race.toml. This overrides vagina physics and positions for a set of race variants.
Targets four race variants from the same mod. Increases vagina scale and grip, adjusts the entry position, and defines a two-waypoint internal path where the second waypoint is anchored to the spine for natural movement during animation.
Races = [ "UBE_AllRace.esp|005734", "UBE_AllRace.esp|005735", "UBE_AllRace.esp|05A179", "UBE_AllRace.esp|05A17A", ] [Vagina] Scale = 2.5 GripStrength = 4 RubIntensity = 5.3 [Vagina.Position] Anchor = "NPC Pelvis [Pelv]" Offset = [0, -1, -4.32] CollisionCylinderRadius = 1.2 CollisionCylinderHeightModifier = 1 [[Vagina.Position.DepthWaypoints]] Offset = [0, 0.7, 6] CornerSmoothing = 1 [[Vagina.Position.DepthWaypoints]] Anchor = "NPC Spine1 [Spn1]" Offset = [0, 6, 0] CornerSmoothing = 1
Example: Multiple Creature Overrides
A single file defining penis configurations for several creature types using the [[Override]] array format. Each creature type has its own bone chain, forward axis, and behavior flags.
Notice that all creatures use LocalForwardAxis = [1, 0, 0] instead of the humanoid default [0, 1, 0], because creature skeletons are typically oriented differently. PreserveHavokState is enabled for all of them since creature animations often use variable bone spacing. The canine entry mixes both Plugin|LocalID and raw FormID formats.
[[Override]] Races = ["Skyrim.esm|131E8", "Skyrim.esm|131E7", "Skyrim.esm|131E9"] [Override.Penis] Bones = ["BearD 4", "BearD 5", "BearD 6", "BearD 7", "BearD 8", "BearD 9"] Girth = 0.5 TipExtension = 0.1 PreserveHavokState = true ClipFix = false LocalForwardAxis = [1, 0, 0] BaseOffset = [0, 0, 0] [[Override]] Races = ["040179CF", "04024038"] [Override.Penis] Bones = ["BoarDick01", "BoarDick02", "BoarDick03", "BoarDick04", "BoarDick05", "BoarDick06"] Girth = 0.5 TipExtension = 0.1 PreserveHavokState = true ClipFix = false LocalForwardAxis = [1, 0, 0] BaseOffset = [0, 0, 0] [[Override]] Races = [ "Skyrim.esm|0131EE", "Skyrim.esm|01320A", "Skyrim.esm|109C7C", "0200C5F0", "020122B7", ] [Override.Penis] Bones = ["CDmiddle 3", "CDPenis 1", "CDPenis 2", "CDPenis 3", "CDPenis 4", "CDPenis 5", "CDPenis 6", "CDPenis 7"] RotateBase = false Girth = 0.5 TipExtension = 0.1 PreserveHavokState = true ClipFix = false LocalForwardAxis = [1, 0, 0] BaseOffset = [0, 0.5, 0]
Example: Predicate-Based Overrides
These examples show overrides that use predicates instead of (or in addition to) race FormIDs.
A global override (no Races array) that matches any actor with a CreaturePenis01 bone. Because it has no race restriction, it's checked against every actor that doesn't match a race-specific override.
[Predicates] HasOneBone = ["CreaturePenis01"] [Penis] Bones = ["CreaturePenis01", "CreaturePenis02", "CreaturePenis03"] LocalForwardAxis = [1, 0, 0] PreserveHavokState = true
Targets a specific race but only female actors of that race. The IsSex predicate ensures this only applies when the actor's sex is female (1). A separate override without the predicate could handle males of the same race.
Races = ["Skyrim.esm|013745"] [Predicates] IsSex = [1] HasAllBones = ["VaginaB1", "Clitoral1"] [Vagina] Scale = 2.0 GripStrength = 3.5 [Vagina.Position] Anchor = "NPC Pelvis [Pelv]" Offset = [0.0, -1.5, -4.0]
Debugging
Enable debug logging in your main accurate-penetration.toml config to see which overrides are loading and which config each actor receives.
[Debug] Logging = true
The log will show which override files are loaded, their priority order, total override count, the breakdown between race-scoped and global overrides, and any parsing errors.
For visual debugging when tweaking positions and bone chains, enable these additional flags:
[Debug] Logging = true Bones = true Collision = true Penis = true
| Flag | Type | Description |
|---|---|---|
| Logging | bool | Verbose text logging of config loading, override matching, and errors. |
| Bones | bool | Visualizes bone positions and names in-game. |
| Collision | bool | Draws collision cylinders for orifice detection zones. |
| Penis | bool | Visualizes the penis bone chain and curve projection. |
Turn on all three visual debug flags when setting up a new creature override. This lets you see the bone chain, collision zones, and orifice positions in real-time so you can quickly identify if bones are in the wrong order, offsets are off, or the forward axis needs adjusting.