Open Animation Replacer (OAR) is an F4SE plugin that swaps Havok animation clips (.hkx) at runtime when configurable conditions are met. It is a Fallout 4 port of Open Animation Replacer for Skyrim.
Use it to replace weapon reloads, idles, sprints, and other gameplay animations without editing the behavior graph, while still driving sounds and game events through Havok annotations.
- Overview
- How it works
- Installation
- Content authoring
- Configuration reference
- Variant animations
- Replacement modes
- Conditions
- In-game UI
- Plugin API (for developers)
- Project layout (developers)
- Building from source
- Troubleshooting
- Documentation
- Credits
| Concept | Meaning |
|---|---|
| Replacer Mod | Pack folder under OpenAnimationReplacer/ |
| SubMod | One rule set: conditions + settings + .hkx files |
| Suffix | Match key = path after Animations\ without .hkx (e.g. scar\wpnreload) |
| Direct path matching | Default. Match the clip's real on-disk path exactly |
| Leaf fallback | Match by filename only when the real path is unknown (or when legacy mode is on) |
| Variant | Several .hkx files (base, base_1, …) picked randomly or in sequence |
| Conditions | Rules for when a SubMod applies (weapon drawn, in combat, …) |
| Priority | Higher number wins when several SubMods match the same clip |
OAR hooks Havok clip generators at runtime and swaps in your .hkx when a SubMod wins.
flowchart TB
subgraph load ["Startup kPostLoad"]
A[Scan OpenAnimationReplacer folders] --> B[Parse config and user JSON]
B --> C[Group variant N files]
C --> D[Preload hkx into AnimationCache]
D --> E[Build suffix lookup table and leaf index]
end
subgraph runtime ["Per-frame Update hook"]
F[Resolve clip's real on-disk path] --> F2{Path resolved}
F2 -->|Yes| G{Registered replacements exist for exact path suffix}
F2 -->|No| F3[Heuristic suffix from authored name] --> G
G -->|No, path resolved| H[Play vanilla]
G -->|No, heuristic| G2{Leaf fallback: match on filename}
G2 -->|No| H
G2 -->|Yes| I
G -->|Yes| I[Evaluate SubMod conditions by priority]
I --> J{Winner found}
J -->|No| H
J -->|Yes| K{Track filter enabled}
K -->|No| L[Full-body swap animation pointer]
K -->|Yes| M[Partial sample per bone in Generate]
L --> N[Fire annotations and custom events]
M --> N
end
load --> runtime
Default mode is direct path matching (bDirectPathMatching=1 in the INI or Settings).
Leaf matching is only a fallback.
Path after Animations\, extension removed:
| File in your SubMod | Suffix |
|---|---|
SCAR\WPNReload.hkx |
scar\wpnreload |
MT_Idle.hkx |
mt_idle |
OAR finds the clip's real on-disk path, then builds the same suffix.
| Game plays | Suffix |
|---|---|
...\Animations\SCAR\WPNReload.hkx |
scar\wpnreload |
Those two suffixes must match exactly. A SCAR reload mod will not apply to a
different weapon's reload just because both files are named WPNReload.hkx.
OAR tries other clues (weapon folder, behavior name, etc.). If that still doesn't
match a registered path, it falls back to the filename only (wpnreload).
- One SubMod with that leaf → it matches.
- Several → conditions and priority decide.
Turn on legacy mode with bDirectPathMatching=0 to use leaf matching for every clip.
Candidates are tried highest priority first. First SubMod whose conditions all pass wins.
Each SubMod keeps its own cached .hkx and annotations, so the winner plays its file.
flowchart LR
RM[Replacer Mod folder]
SM1[SubMod A]
SM2[SubMod B]
RA1[Replacement wpnreload]
RA2[Replacement wpnsprint]
V1[Variants v1 v2 v3]
HKX[.hkx on disk]
RM --> SM1
RM --> SM2
SM1 --> RA1
SM1 --> RA2
RA1 --> V1
V1 --> HKX
SM2 --> HKX
sequenceDiagram
participant Game as Fallout4_Havok
participant Clip as hkbClipGenerator
participant OAR as OAR_Update_hook
participant Cache as AnimationCache
Game->>Clip: Activate vanilla hkx
Clip->>OAR: Update each frame
OAR->>OAR: Resolve real path (subgraph walk / player poll)
OAR->>OAR: Exact path suffix match, or leaf fallback for unresolved clips
OAR->>OAR: Pick winning SubMod by priority + conditions
alt Full-body replacement
OAR->>Cache: GetOrBuildRuntimeAnim
Cache-->>OAR: Return runtime clone
OAR->>Clip: Swap animSlot to replacement
OAR->>Clip: Filter annotation triggers keep behavior triggers
else Track filter path
OAR->>Cache: Register replacement for Generate
OAR->>Clip: Keep vanilla slot blend bones in Generate
end
OAR->>OAR: Fire replacement annotations if needed
Game->>Clip: Deactivate
OAR->>OAR: Cleanup state and variant cache
- Install F4SE for your game version.
- Place in
Fallout 4/Data/F4SE/Plugins/:OpenAnimationReplacer.dllOpenAnimationReplacer.ini(optional; defaults apply if missing)
- Install animation packs under
Data/Meshes/.../Animations/OpenAnimationReplacer/(see Content authoring). - Launch via
f4se_loader.exe.
| Log | Location |
|---|---|
| OAR plugin | Documents/My Games/Fallout4/F4SE/OpenAnimationReplacer.log |
| F4SE | Documents/My Games/Fallout4/F4SE/f4se.log |
Mirror the path after Animations\. Use the Animation Log to see the real path.
| Game path | Put your file at |
|---|---|
...\Animations\SCAR\WPNReload.hkx |
<SubMod>\SCAR\WPNReload.hkx |
...\Animations\MT_Idle.hkx |
<SubMod>\MT_Idle.hkx |
- Path = which animation is replaced
- Conditions = when it is replaced
- Priority = who wins if several SubMods match
A flat WPNReload.hkx in the SubMod root only matches clips directly under
Animations\, or via leaf fallback / legacy mode (bDirectPathMatching=0).
OAR looks for folders named OpenAnimationReplacer under Data/Meshes/.
The structure is always exactly four levels — no more, no less:
OpenAnimationReplacer / <Replacer Mod> / <SubMod> / <mirrored path to .hkx>
Data/Meshes/Actors/Character/_1stPerson/Animations/ ← note the underscore
└── OpenAnimationReplacer/
└── SCAR OAR Test/ ← Replacer Mod (any name)
├── config.json ← optional pack metadata: name/author/description ONLY
└── SCAR Reload Test/ ← SubMod (any name)
├── config.json ← ALL behavior lives here: conditions, priority, …
├── user.json ← optional player overrides
└── SCAR/ ← mirrors ...\Animations\SCAR\
├── WPNReload.hkx
├── WPNReload_1.hkx
└── …
Both of these load without any error and simply don't work. Check for them first whenever a SubMod "does nothing".
Mistake 1 — one level too shallow. If your .hkx sits directly in the
SubMod folder but the game's animation lives in a subfolder, the file registers
under the wrong path and never matches:
WRONG (3 levels) RIGHT (4 levels)
OpenAnimationReplacer/ OpenAnimationReplacer/
└── My Pack/ ← parsed as MOD └── My Pack/ ← Replacer Mod
├── config.json ← read as MOD └── My SubMod/ ← SubMod
│ config: behavior ├── config.json
│ settings IGNORED └── F4Parkour/ ← mirrors path
└── F4Parkour/ ← parsed as SUBMOD └── Vault.hkx
└── Vault.hkx ← registers as
"vault", not
"f4parkour\vault"
In the WRONG tree, Vault.hkx's path relative to its SubMod is just
Vault.hkx — so it targets ...\Animations\Vault.hkx (which doesn't exist)
instead of ...\Animations\F4Parkour\Vault.hkx.
Mistake 2 — behavior config at the Mod level. The Replacer Mod
config.json is read for name, author, description — nothing else.
Conditions, priority, trackFilter, and every other setting placed there are
silently discarded. All behavior belongs in the SubMod's config.json.
How to verify your structure loaded correctly: set bVerboseLogging=1 in
OpenAnimationReplacer.ini and check the log for your suffix:
[OAR] NameLookup: suffix='f4parkour\vault' -> 'Animations\F4Parkour\Vault.hkx' (1 candidates)
Wrong suffix (e.g. suffix='vault') means your files are at the wrong depth.
No line at all means the folder was never discovered (name must be exactly
OpenAnimationReplacer, placed inside an Animations tree).
Direct path matching (default)
| Situation | Result |
|---|---|
Paths match (scar\wpnreload ↔ SCAR\WPNReload.hkx) |
SubMod is evaluated |
| Real path known, but no SubMod for that exact suffix | No replacement (no leaf fallback) |
| Real path unknown | Leaf fallback (filename only) |
| Several SubMods share the suffix | Conditions + priority pick one |
"conditions": [] |
Always matches that animation |
Legacy leaf matching (bDirectPathMatching=0): match by filename everywhere;
subfolders are optional; conditions + priority still break ties.
- Open the Animation Log, play the animation, copy the path after
Animations\. - Create that same folder layout under your SubMod and drop in your
.hkx. - Add conditions in
config.json(empty = always on for that path). - Optional: variants (
WPNReload_1.hkx, …) and a higherpriorityif other packs compete.
Put OpenAnimationReplacer/ inside the animation tree you are targeting:
| Target | Typical path |
|---|---|
| 1st person | Data/Meshes/Actors/Character/_1stPerson/Animations/OpenAnimationReplacer/ |
| 3rd person | Data/Meshes/Actors/Character/Animations/OpenAnimationReplacer/ |
OAR also scans Actors/<race>/Character/Animations/ and, if needed, all of Data/Meshes/.
{
"name": "SCAR OAR Test",
"author": "YourName",
"description": "Custom SCAR reload and idle animations."
}{
"name": "SCAR Reload Test",
"description": "Reload when magazine not empty.",
"priority": 1000,
"disabled": false,
"interruptible": true,
"replaceOnLoop": true,
"replaceOnEcho": true,
"replaceAnnotations": true,
"conditions": [
{
"condition": "IsForm",
"Form": { "pluginName": "Fallout4.esm", "formID": "0x14" }
},
{
"condition": "CurrentMagazineAmmo",
"comparison": 1,
"numericValue": { "type": "Static", "value": 0.0 }
},
{ "condition": "IsEquipped", "Form": { "pluginName": "SCAR-H.esp", "formID": "0x2E1F" } }
],
"variants": {
"enabled": true,
"mode": "random",
"rerollPolicy": "onEachPlay",
"weights": {
"WPNReload_1.hkx": 1.0,
"WPNReload_2.hkx": 2.0,
"WPNReload_3.hkx": 1.0
}
},
"trackFilter": {
"enabled": false,
"mode": "override",
"weight": 1.0,
"blendInTime": 0.15,
"blendOutTime": 0.15,
"bones": ["LArm_Collarbone", "RArm_Collarbone"],
"excludeBones": [],
"freezeBones": ["Weapon"]
},
"eventsOnStart": [],
"eventsOnEnd": ["ReloadComplete"]
}| Field | Type | Default | Description |
|---|---|---|---|
name |
string | folder name | Display name in UI |
priority |
int | 0 | Higher value wins when multiple SubMods match |
disabled |
bool | false | Skip entirely |
interruptible |
bool | false | Re-evaluate conditions every frame |
replaceOnLoop |
bool | true | Re-evaluate when clip loops |
replaceOnEcho |
bool | true | Re-evaluate on echo / blend |
replaceAnnotations |
bool | true | Use the replacement .hkx's annotations (sounds, WeaponFire, CullBone, etc.). Behavior-authored triggers (weapon attach on equip, state-machine transitions) stay installed and fire natively; only annotation-derived triggers are filtered out. OAR then fires the replacement's annotations manually |
preserveExtractedMotion |
bool | false | Keep the replacement .hkx's root-motion reference frame (hkaDefaultAnimatedReferenceFrame) when building the runtime clone, after the packfile identifies it and the object validates. Enable only for donors authored with root motion; pose-only replacements should leave it off. Reload configs after changing it |
suppressAnnotations |
bool or string[] | -- | true mutes ALL of the replacement file's annotations; an array (e.g. ["WeaponFire", "SoundPlay.WPNRifleFire"]) mutes only those, case-insensitive. Needs replaceAnnotations: true. Use for dry-fire/silent replacements whose source .hkx still carries annotations |
playOnceFullBody |
bool | false | Keep vanilla triggers until anim completes (state machine exit). Prefer this for clips whose behavior graph needs its own exit signal |
leafMatching |
bool | false | Match by filename alone, ignoring the folder path — and outrank exact-path submods whenever this submod's conditions pass. One wpnmelee.hkx here covers every weapon's WPNMelee clip, so a single conditioned submod replaces what would otherwise need a mirrored submod per weapon folder. When conditions fail, normal path matching applies untouched. Gate it with conditions: unconditioned, it claims every clip sharing the filename |
deactivationDelay |
float | 0 | Seconds to hold replacement after conditions fail |
conditions |
array | [] |
AND list; empty = always match |
variants |
object | -- | Variant selection settings (see below) |
trackFilter |
object | disabled | Partial-body bone override |
eventsOnStart / eventsOnEnd |
string[] | [] |
Custom behavior graph events |
Players can override author settings without editing config.json. The in-game UI writes user.json in the same SubMod folder; any field present overrides the author file.
{
"disabled": false,
"priority": 500,
"variants": { "enabled": true, "mode": "sequential" }
}This file is the mod-provided defaults layer. Settings changed from the OAR
Settings page are saved to the separate
Data/F4SE/Plugins/OpenAnimationReplacer.user.ini file and take precedence
over these defaults. The user file is created at runtime and should not be
included in a mod release package.
| Section | Key | Default | Description |
|---|---|---|---|
| General | bEnabled |
1 |
Master enable |
bEnableUI |
1 |
ImGui overlay | |
bAsyncParsing |
1 |
Background parse at load | |
bDisablePreloading |
0 |
Skip upfront .hkx preload |
|
bFilterOutDuplicateAnimations |
1 |
Dedupe registration | |
bDirectPathMatching |
1 |
Exact path matching (default). 0 = leaf matching everywhere. Also in Settings |
|
iAutoReloadMode |
0 |
0 = auto-reload on last round (default), 1 = auto-reload on fire when empty, 2 = suppress auto-reload (reload key only). Engine auto-reloads are always suppressed so OAR can issue full-length reload-key reloads. Also in Settings |
|
bPlayDryFireSound |
1 |
Play a dry-fire click when firing on empty (weapon Attack Fail sound, or vanilla 10mm dry click). Also in Settings | |
| UI | iToggleKey |
60 (0x3C) |
DIK scan code for UI toggle (default F2; rebind in Settings) |
bRequireShift |
0 |
Require Shift + toggle key | |
| AnimationLog | bLogReplace |
1 |
Log replacements in overlay |
iMaxLogEntries |
100 |
Log buffer size | |
| Limits | iAnimationLimit |
16384 |
Max registered replacements |
iHavokHeapMultiplier |
2 |
Havok heap scaling hint | |
| Debug | bVerboseLogging |
0 |
Extra plugin logging |
Variants let one replacement target (wpnreload) draw from several .hkx files with different motion, length, and annotations.
| File | Role |
|---|---|
WPNReload.hkx |
Base animation (always included as variant index 0) |
WPNReload_1.hkx |
Variant 1 (_ + digits after stem) |
WPNReload_2.hkx |
Variant 2 |
WPNReload_10.hkx |
Variant 10 |
Requirements:
- A base file (no
_Nsuffix) must exist for_Nfiles to be grouped as variants. - Orphan
_Nfiles without a base are registered as standalone replacements.
At parse time, variants receive synthetic cache suffixes so each file loads independently:
| Disk file | Cache suffix (example) |
|---|---|
scar\wpnreload.hkx |
scar\wpnreload |
scar\wpnreload_1.hkx |
scar\wpnreload__v1 |
scar\wpnreload_2.hkx |
scar\wpnreload__v2 |
flowchart TD
Start[Clip needs replacement] --> Enabled{variants enabled}
Enabled -->|No| Base[Always use base hkx]
Enabled -->|Yes| Mode{mode}
Mode -->|random| R[Weighted random index]
Mode -->|sequential| S[Round-robin per actor]
R --> Policy{rerollPolicy}
S --> Policy
Policy -->|onEachPlay| E[New pick each new clip instance]
Policy -->|whileActive| F[Same pick until conditions false]
variants.mode |
Behavior |
|---|---|
random |
Weighted roll; optional weights per filename |
sequential |
Cycles 0, 1, 2, ... per actor |
variants.rerollPolicy |
Behavior |
|---|---|
onEachPlay |
New selection when a new clip generator starts (each reload press) |
whileActive |
Same selection while SubMod conditions stay true |
| UI / future JSON | shareRandomResults | All actors share one roll (random mode only) |
"variants": {
"enabled": true,
"mode": "random",
"rerollPolicy": "onEachPlay",
"weights": {
"WPNReload_1.hkx": 1.0,
"WPNReload_2.hkx": 3.0
}
}Each variant loads its own .hkx into AnimationCache with its own duration, tracks, and annotations. Full-body replacement patches the cloned hkaAnimation duration so the engine loops at the replacement length.
With replaceAnnotations: true (default):
- Annotation-derived triggers from the original clip (sounds,
WeaponFire, bone cull, etc.) are filtered out so the vanilla soundtrack does not play. - Behavior-authored triggers stay installed — these drive engine actions the annotation list does not cover (weapon attach/draw on equip, some state-machine exits). Replacing
wpnequip/wpnequipfastwith an identical file still needs these; NULLing the whole trigger array made weapons disappear and fall through to fast-equip. - OAR fires the replacement file's annotations manually from the clip's
localTimetracker. Ghost activations during nested graph events (brief Update of a clip that is not really playing) are suppressed so their SoundPlays do not dump out of context.
Use suppressAnnotations when the replacement .hkx itself still carries events you do not want (e.g. dry-fire keeping WeaponFire).
flowchart LR
subgraph before ["Before"]
A1[animSlot] --> B1[Vanilla hkaAnimation]
end
subgraph after ["After conditions pass"]
A2[animSlot] --> B2[OAR runtime clone]
B2 --> C2[Replacement spline data]
end
- Swaps the pointer at
animationControl -> binding -> animation. - Replacement duration and spline metadata are patched on the clone.
- Best for complete reload / idle / locomotion overrides.
Caveats:
- Hardcoded behavior graph transitions (e.g. "exit reload at 2.5s") still follow the
.hkbgraph, not your clip length. UseplayOnceFullBodyoreventsOnEndwhere needed. - Equip / draw clips rely on behavior triggers for weapon attach. OAR keeps those when replacing annotations; you normally do not need a special config for
wpnequipbeyond a correct path and conditions.
flowchart TB
subgraph slot ["Animation slot"]
V[Vanilla hkaAnimation unchanged]
end
subgraph generate ["hkbClipGenerator_Generate"]
V --> P[Vanilla pose]
R[Replacement sampled at localTime] --> B[Blend per bone]
P --> B
B --> O[Output pose]
end
- Does not swap
animSlot; samples the replacement per filtered bone. trackFilter.bones: bones to override or additively blend.trackFilter.excludeBones: removed from the filtered set; the underlying animation keeps driving them.trackFilter.freezeBones: driven by neither the replacement nor the underlying animation. Each (with its children) holds the pose it had when the overlay started and releases through the normal blend-out. Use for a weapon gripped by replacement-driven hands: excluding it would let each weapon's own animation keep swinging it, freezing pins the grip.blendInTime/blendOutTime: alpha ramp when conditions toggle.localTimeis wrapped to the replacement duration when sampling (different-length clips).
trackFilter.mode |
Effect |
|---|---|
override |
Replace bone transform with replacement |
additive |
Add replacement on top of base pose |
trackFilter.nativeIdlePlayback (with triggerOnlySpecialIdle): the engine's full-body idle plays natively, so the 3rd-person body performs the animation with its annotations, and the overlay applies only to first-person clips as raw replacement locals so the 1st-person arms mirror the motion. Use for 3rd-person-authored idles that must also read correctly in first person. Default off.
Override timing guarantee: on one-shot plays the replacement runs on OAR's own clock from the moment the play starts, so it looks identical on the selected bones no matter which weapon's clip hosts it, how fast that clip plays, or where it parks. The host clip only starts, restarts, and ends the overlay. Additive mode follows the host animation's time (its deltas belong to that animation), and looping sources stay loop-synced in both modes so cycle-authored overlays track the host cycle. Fixed-frame sampling (sampleFrame) is time-independent already.
SubMod conditions use AND logic at the root. Use OR / AND / XOR nodes and negated for complex logic.
Evaluation order: All SubMods matching the clip suffix are sorted by priority (descending); the first whose condition set passes wins.
| Category | Examples |
|---|---|
| Actor / combat | IsWeaponDrawn, IsInCombat, IsSprinting, IsADS, IsReloading, IsFiring, IsAttacking, IsBlocking |
| Movement | IsInAir, IsSneaking, IsRunning, IsSwimming, IsMovementDirection, MovementSpeed |
| Forms | IsForm, IsActorBase, IsEquipped, IsEquippedType, IsEquippedHasKeyword, HasKeyword |
| Ammo / equipment | CurrentMagazineAmmo, InventoryCount, IsWorn, IsWornHasKeyword |
| World | IsWorldSpace, IsParentCell, IsInLocation, IsInInterior, CurrentWeather, LightLevel |
| Animation | IsPlayingIdleAnimation, AnimProgress, AnimTimeElapsed, AnimTimeRemaining |
| Logic | OR, AND, XOR, Random, TARGET, PLAYER |
| Comparison | Level, CompareActorValue, Scale, FactionRank, etc. |
Full parameter reference: docs/QuickStart.md.
The built-in condition names, descriptions, stub reasons, and editor labels
are translated through the selected locale without changing the condition IDs
stored in JSON. The condition value remains the exact runtime registration
name, so existing configs and third-party APIs remain compatible.
Third-party conditions use the same string-key fallback: OAR displays the original name or description when no translation is present. A plugin author or translation add-on can provide an optional language extension pack at:
Data/F4SE/Plugins/OpenAnimationReplacer/locales/<language>.d/<unique-name>.json
The file is a flat JSON object whose keys are the exact strings returned by
GetName() and GetDescription(). OAR loads the base <language>.json first,
then extension files in filename order; later entries override earlier ones.
Use a unique filename per add-on and keep runtime IDs, JSON field names, and
condition evaluation code untranslated. Missing or invalid extension entries
fall back to the original source text.
{
"condition": "CurrentMagazineAmmo",
"comparison": 1,
"numericValue": { "type": "Static", "value": 0.0 }
}comparison: 1 = Not Equal -- passes when ammo is not 0.
{
"condition": "IsPlayingIdleAnimation",
"Form": { "pluginName": "SomeMod.esp", "formID": "0x12345" }
}| Input | Action |
|---|---|
| F2 (default) | Toggle main overlay (iToggleKey=0x3C, bRequireShift=0). Rebind in Settings → Activation Key. |
| Mode | Capabilities |
|---|---|
| Inspect | View mods, conditions, live pass/fail |
| User | Enable/disable SubMods, priorities -- saves user.json |
| Author | Edit conditions, variants, track filter -- saves config.json |
- Replacer tree -- mods, submods, replacement list (variant count shown).
- Condition editor -- add/remove/negate; form pickers for idle/weapon records.
- Variant settings -- enable, random/sequential, reroll policy, weight sliders.
- Active Replacements -- debug view of current swaps (includes variant suffix).
- Animation Log -- real-time activate/replace/loop events.
A folder placed in the OAR structure with animations but no config.json still
loads: it matches unconditionally and shows under its raw folder name. Such
folders are marked (no config) in the tree, dimmed for mod folders. You can
formalize one without editing files by hand:
- Right-click the (no config) entry in the Replacer tree.
- Choose Create config.json....
- Fill in the fields:
- SubMod: name (prefilled from the folder), description, priority.
- Mod folder: name, author, description.
- Click Create. A
config.jsonis written into that folder and the live entry updates in place; the (no config) marker clears. - Edit it like any other submod (conditions, track filter, variants). A
freshly created submod config starts with an empty conditions list, so it
still matches everything until you add conditions. Switch to Author mode
and use the save button to write your edits back to
config.json.
The starter file is minimal (name, description, priority, and an empty
conditions array for a submod; name, author, description for a mod), so
nothing about the folder's current behavior changes until you edit it.
OAR exposes two C++ APIs for other F4SE plugins:
- Conditions API (
RequestPluginAPI_Conditions) — register custom condition types at runtime, adding entirely new conditions without modifying OAR's source code. - Clips API (
RequestPluginAPI_Clips) — query live data about the animation clips OAR handles: names, resolved file paths, durations, playback state, perspective, replacement attribution, annotations — plus the animation graphs themselves: skeleton bone hierarchies, registered animation paths, and behavior event names. Version 3 lets a plugin opt its own animation graph out of OAR's vanilla annotation backup. See Clips API below.
sequenceDiagram
participant YourPlugin as Your F4SE Plugin
participant OAR as OpenAnimationReplacer.dll
participant Factory as ConditionFactory
participant Runtime as Animation Runtime
YourPlugin->>OAR: GetModuleHandle + GetProcAddress
OAR-->>YourPlugin: IConditionsAPI pointer
YourPlugin->>OAR: RegisterCondition name and factory
OAR->>Factory: Register factory function
Note over Runtime: Game loads SubMod JSON with your condition name
Runtime->>Factory: Create condition by name
Factory-->>Runtime: Your condition instance
Runtime->>Runtime: Calls EvaluateImpl on your condition
-
Copy two SDK headers into your project (from OAR's
src/API/folder):OpenAnimationReplacerAPI-Conditions.h— API interface +GetAPI()helperOpenAnimationReplacer-ConditionTypes.h—ConditionBase, components, utilities
-
Create your condition class (inherit
OAR::ConditionBase):
#include "OAR/OpenAnimationReplacerAPI-Conditions.h"
class IsNearWaterCondition : public OAR::ConditionBase
{
public:
std::string GetName() const override { return "IsNearWater"; }
std::string GetDescription() const override {
return "True when actor is within range of a water surface.";
}
protected:
bool EvaluateImpl(RE::TESObjectREFR* a_refr, RE::hkbClipGenerator*,
const OAR::SubMod*) const override
{
if (!a_refr) return false;
// Your custom logic here
float waterLevel = /* ... */;
float actorZ = a_refr->data.location.z;
float diff = actorZ - waterLevel;
return OAR::CompareValues(diff, comparison, numericValue.GetValue(a_refr));
}
void InitializeImpl(const nlohmann::json& j) override {
if (j.contains("comparison"))
comparison = static_cast<OAR::ComparisonOperator>(j["comparison"].get<int>());
if (j.contains("numericValue"))
numericValue.Initialize(j["numericValue"]);
}
void SerializeImpl(nlohmann::json& j) const override {
j["comparison"] = static_cast<int>(comparison);
nlohmann::json nv;
numericValue.Serialize(nv);
j["numericValue"] = nv;
}
private:
OAR::ComparisonOperator comparison{ OAR::ComparisonOperator::kLess };
OAR::NumericComponent numericValue;
};- Register during
kPostLoad:
#include "OAR/OpenAnimationReplacerAPI-Conditions.h"
void OnMessage(F4SE::MessagingInterface::Message* msg)
{
if (msg->type == F4SE::MessagingInterface::kPostLoad) {
auto* api = OAR::Conditions::GetAPI();
if (!api) {
logger::error("OAR not found!");
return;
}
auto result = api->RegisterCondition("IsNearWater",
[] { return std::make_unique<IsNearWaterCondition>(); });
if (result == OAR::Conditions::APIResult::OK)
logger::info("IsNearWater condition registered!");
}
}- Use in JSON configs — content authors can now reference your condition:
{
"condition": "IsNearWater",
"comparison": 4,
"numericValue": { "type": "Static", "value": 200.0 }
}By inheriting OAR::ConditionBase, your condition automatically has:
- Negation — users can set
"negated": truein JSON to invert your result - Disable —
"disabled": truemakes the condition always pass - JSON envelope — OAR handles the
"condition"key,"negated","disabled"fields - UI integration — your condition appears in OAR's in-game ImGui editor
- Evaluation caching —
lastEvalResultis tracked for debug overlay display - Error handling — exceptions during Initialize are caught and logged
The SDK headers provide these reusable building blocks:
| Component | Purpose | Example |
|---|---|---|
OAR::ComparisonOperator |
Enum for ==, !=, >, >=, <, <= | CompareValues(a, op, b) |
OAR::NumericComponent |
Value from static/global/actor-value | numericValue.GetValue(refr) |
OAR::FormComponent |
Resolve a form by plugin+localID | form.ResolveForm(); form.cachedForm |
OAR::ConditionSet |
Embed child conditions (composite) | childConditions.EvaluateAll(...) |
namespace OAR::Conditions {
// Get the API (returns nullptr if OAR not loaded)
IConditionsAPI* GetAPI();
class IConditionsAPI {
// API version (currently 2)
uint32_t GetAPIVersion() const;
// Register a new condition type
// Returns: OK, AlreadyRegistered, Invalid, or Failed
APIResult RegisterCondition(const char* name, ConditionFactoryFn factory);
// Remove a previously registered condition
bool UnregisterCondition(const char* name);
// Total registered condition count (built-in + custom)
uint32_t GetRegisteredConditionCount() const;
};
// Factory function signature
using ConditionFactoryFn = std::unique_ptr<OAR::ICondition>(*)();
}- Call
GetAPI()duringkPostLoadorkPostPostLoadmessaging - OAR loads SubMod configs after all plugins have loaded, so your conditions will be available
- Do NOT call
GetAPI()duringF4SEPlugin_Load(OAR may not be loaded yet)
For conditions that contain child conditions (like DetectedBy / Detects):
class MyCompositeCondition : public OAR::ConditionBase
{
protected:
bool EvaluateImpl(RE::TESObjectREFR* a_refr, RE::hkbClipGenerator* a_clip,
const OAR::SubMod* a_sub) const override
{
// Evaluate children against a different target
RE::TESObjectREFR* otherRefr = /* get alternate target */;
return childConditions.EvaluateAll(otherRefr, a_clip, a_sub);
}
void InitializeImpl(const nlohmann::json& j) override {
if (j.contains("conditions") && j["conditions"].is_array()) {
for (const auto& cj : j["conditions"]) {
// Use OAR's factory to create child conditions
// (requires forward-declaring CreateConditionFromJson)
}
}
}
private:
OAR::ConditionSet childConditions;
};Override DrawEditWidgets for custom ImGui controls in the OAR editor:
void DrawEditWidgets(bool& a_dirty) override {
static const char* ops[] = { "==", "!=", ">", ">=", "<", "<=" };
int idx = static_cast<int>(comparison);
if (ImGui::Combo("Operator", &idx, ops, 6)) {
comparison = static_cast<OAR::ComparisonOperator>(idx);
a_dirty = true;
}
if (ImGui::InputFloat("Threshold", &numericValue.staticValue)) {
a_dirty = true;
}
}Besides registering conditions, plugins can query everything OAR knows about the animation clips playing on an actor: authored names, resolved on-disk paths, playback state, perspective, replacement attribution, annotations, plus the active-replacement list and global stats. Version 2 adds graph-level queries: per-graph info (character name, project paths, 1st-person flag, active node/clip counts), the full skeleton bone hierarchy, registered animation paths, and behavior event names.
Setup: copy src/API/OpenAnimationReplacerAPI-Clips.h into your project. It is fully self-contained — no CommonLibF4 or nlohmann-json required.
#include "OAR/OpenAnimationReplacerAPI-Clips.h"
// MAIN THREAD ONLY — the queries walk live Havok graphs.
void DumpPlayerClips()
{
auto* api = OAR::Clips::GetAPI(); // nullptr if OAR isn't loaded
if (!api) return;
OAR::Clips::ClipInfo clips[64];
uint32_t total = api->GetActorClips(0 /* 0 = player */, clips, 64);
for (uint32_t i = 0; i < std::min<uint32_t>(total, 64); ++i) {
auto& c = clips[i];
// c.animationName — authored clip path (may be a template until resolved)
// c.resolvedPath — real on-disk path ("" until the engine data resolves)
// c.duration — length (s) of the animation currently playing
// c.localTime — current playback position (s)
// c.playbackMode — single-play / looping / user / ping-pong
// c.perspective — first person / third person / unknown
// c.replacementKind — none / full-body swap / track filter
// c.subModName, c.modName, c.subModPriority, c.replacementPath
}
}Interface (OAR::Clips::IClipsAPI, version 2):
| Method | Purpose |
|---|---|
GetActorClips(formID, buf, max) |
Enumerate active clips on an actor (0/0x14 = player). Returns the TOTAL count, fills up to max. |
FindClip(formID, nameOrLeaf, out) |
Find one clip by file-name leaf (case-insensitive, .hkx optional), matched against suffix, authored name, and resolved path. |
GetClipAnnotations(clipHandle, buf, max) |
Annotations (time, text) of the animation the clip is currently playing — the replacement's when replaced. |
GetActiveReplacements(formID, buf, max) |
Snapshot of applied replacements (0 = all actors) with submod, paths, actor name. |
GetStats(&stats) |
Loaded mod/submod/animation counts, runtime cache size, active replacement count. |
GetActorGraphs(formID, buf, max) (v2) |
Enumerate the actor's animation graphs — see GraphInfo below. |
GetGraphBones(formID, graphIdx, start, buf, max) (v2) |
Skeleton bones of one graph: name + parent index (-1 = root). Paged via start; returns the TOTAL bone count. |
GetGraphAnimationNames(formID, graphIdx, start, buf, max) (v2) |
Animation paths registered on the graph's character — the list replacement candidates are validated against. Paged. |
GetGraphEventNames(formID, graphIdx, start, buf, max) (v2) |
Behavior event names of the graph's project (events you can send to the graph, e.g. ReloadEnd, SprintStop). Paged. |
| Field | Type | Meaning |
|---|---|---|
clipHandle |
uint64_t |
Opaque clip generator id. Valid only within the frame it was returned — pass it to GetClipAnnotations the same frame, never store it. |
actorFormID |
uint32_t |
Owning actor's form ID (0x14 = player). |
graphIndex |
uint8_t |
Which of the actor's animation graphs the clip lives in (the player has separate 1st/3rd-person graphs). |
perspective |
uint8_t |
kPerspectiveFirstPerson, kPerspectiveThirdPerson, or kPerspectiveUnknown. |
playbackMode |
uint8_t |
kModeSinglePlay, kModeLooping, kModeUserControlled, kModePingPong. |
replacementKind |
uint8_t |
kReplacementNone, kReplacementFullBody (OAR swapped the slot animation), or kReplacementTrackFilter (OAR overlays specific bones; slot holds the original). |
duration |
float |
Length in seconds of the animation currently playing (the replacement's length when replaced). |
localTime |
float |
Current playback position in seconds. localTime / duration gives normalized progress. |
playbackSpeed |
float |
Clip playback rate multiplier. |
originalDuration |
float |
The original animation's length. Equals duration when unreplaced; 0 when unknown. |
subModPriority |
int32_t |
Priority of the active submod (0 when none). |
animationName |
char[128] |
Authored clip animation path. May be a template (e.g. 44pistol\wpnfire.hkx) until the engine's real path resolves. |
resolvedPath |
char[260] |
Real on-disk path resolved from the engine's subgraph data. Empty until resolution succeeds (player weapon clips resolve within a few frames of activation). |
suffix |
char[128] |
OAR's matching suffix: the path after Animations\, no extension. This is the key OAR matches replacement folders against. |
subModName / modName |
char[128] |
Active replacement's submod and its parent replacer mod. Empty when no replacement is active. |
replacementPath |
char[260] |
The replacement .hkx path being played. Empty when none. |
All strings are null-terminated and truncated to the buffer size when longer. Empty string means "not known / not applicable", never garbage.
| Field | Type | Meaning |
|---|---|---|
actorFormID |
uint32_t |
Owning actor. |
graphIndex |
uint8_t |
Pass this to GetGraphBones / GetGraphAnimationNames / GetGraphEventNames. The player has separate 1st- and 3rd-person graphs; most actors have one. |
isFirstPerson |
uint8_t |
1 when this is the player's learned 1st-person graph (always 0 for NPCs — the engine gives them no 1st-person graph). |
isRebuilding |
uint8_t |
1 while the engine rebuilds the graph's node list (e.g. during weapon swaps); clip data may be briefly unavailable. |
activeNodeCount |
uint32_t |
Behavior nodes active right now. |
activeClipCount |
uint32_t |
Clip generators among the active nodes (what GetActorClips returns for this graph). |
boneCount |
uint32_t |
Animation skeleton bone count (total for GetGraphBones). |
animationNameCount |
uint32_t |
Registered animation paths (total for GetGraphAnimationNames). |
eventNameCount |
uint32_t |
Behavior event names (total for GetGraphEventNames). |
characterName |
char[64] |
Havok character name. |
projectAnimationPath |
char[260] |
Project's animation root. Often empty in FO4 — resolved clip paths are the reliable path source. |
behaviorPath |
char[260] |
Project's behavior root. |
Walk the player's graphs and dump the skeleton of the 1st-person one — for example to discover the exact bone names a track filter (trackFilter.boneNames in a submod config) should target:
OAR::Clips::GraphInfo graphs[4];
uint32_t graphCount = api->GetActorGraphs(0, graphs, 4);
for (uint32_t g = 0; g < std::min<uint32_t>(graphCount, 4); ++g) {
if (!graphs[g].isFirstPerson) continue;
// Page through the bones (returns TOTAL; page with the start index)
OAR::Clips::BoneInfo bones[64];
uint32_t total = graphs[g].boneCount;
for (uint32_t start = 0; start < total; start += 64) {
uint32_t got = std::min<uint32_t>(64, total - start);
api->GetGraphBones(0, graphs[g].graphIndex, start, bones, got);
for (uint32_t i = 0; i < got; ++i) {
// bones[i].name, bones[i].index, bones[i].parentIndex (-1 = root)
}
}
}Discover which behavior events a graph understands (useful before sending events like ReloadEnd or SprintStop from your own plugin):
OAR::Clips::NameEntry events[128];
uint32_t total = api->GetGraphEventNames(0, 0 /* graph index */, 0, events, 128);React to the annotations of whatever animation is actually playing (replacement annotations included):
OAR::Clips::ClipInfo clip;
if (api->FindClip(0, "wpnfiresingleready", &clip)) {
OAR::Clips::ClipAnnotation annots[32];
uint32_t n = api->GetClipAnnotations(clip.clipHandle, annots, 32);
for (uint32_t i = 0; i < std::min<uint32_t>(n, 32); ++i) {
// annots[i].time (seconds from clip start), annots[i].text ("WeaponFire", ...)
// e.g. schedule something for when playback reaches the annotation:
float secondsUntil = (annots[i].time - clip.localTime) / std::max(clip.playbackSpeed, 0.001f);
}
}Check whether OAR is currently replacing anything on an actor (e.g. to avoid conflicting with it):
uint32_t count = api->GetActiveReplacements(someActorFormID, nullptr, 0); // count only
if (count > 0) {
std::vector<OAR::Clips::ActiveReplacementInfo> reps(count);
api->GetActiveReplacements(someActorFormID, reps.data(), count);
// reps[i].subModName, reps[i].replacementPath, reps[i].clipSuffix, ...
}Two-call pattern for buffers of unknown size (works for all enumeration methods — they return the TOTAL count regardless of how much was written):
uint32_t total = api->GetActorClips(0, nullptr, 0); // 1st call: count
std::vector<OAR::Clips::ClipInfo> clips(total);
api->GetActorClips(0, clips.data(), total); // 2nd call: fillGlobal stats (e.g. for a diagnostics overlay):
OAR::Clips::Stats stats{};
if (api->GetStats(&stats)) {
// stats.replacerModCount, stats.subModCount, stats.replacementAnimCount,
// stats.cachedAnimFileCount, stats.activeReplacementCount
}Rules:
- Call every method from the game's main thread (e.g. an F4SE task or your own update hook). The clip queries walk live Havok graph structures; calling from another thread races the engine.
clipHandlevalues are only valid within the frame they were returned — don't store them.GetAPI()works atkPostLoador later; the returned pointer may be cached for the session.- Queries are on-demand walks, not cached — cheap enough per frame for one actor, but don't enumerate every loaded actor every frame.
- Check
GetAPIVersion()once afterGetAPI()if you depend on methods added in later versions (current: 3).
Once per play, OAR checks that an un-replaced clip's engine trigger array still carries every annotation authored in its animation. The engine sometimes builds that array wrong, so OAR fires the missing annotations itself: SoundPlay.* directly, everything else (FootLeft, FootRight, weapon events) through the owning actor's animation graph and event sinks. Replacements are untouched by this; it only runs on plays OAR is not replacing.
If your plugin runs its own animation graph and removes events from it on purpose, that repair re-fires exactly what you removed. Typical case: a display-only clone of the player's body whose footsteps you have silenced. Register the graph and OAR leaves its events alone:
auto* api = OAR::Clips::GetAPI();
if (api && api->GetAPIVersion() >= 3) {
// myGraph is the BShkbAnimationGraph* you own (your manager's graph[i],
// or the graph you created). Call once the graph exists.
api->SetAnnotationBackupEnabled(myGraph, false);
}
// Before destroying the graph, restore the default so a later graph
// allocated at the same address does not inherit the opt-out:
api->SetAnnotationBackupEnabled(myGraph, true);Disabling returns false (and stores nothing) when the pointer is null, unreadable, or not a BShkbAnimationGraph; OAR logs the reason. Re-enabling removes the registration by address without touching the pointer, so it also works after the graph has been destroyed. IsAnnotationBackupEnabled(graph) reads the current state. Call these from the game's main thread like the other Clips API methods. Animation replacements on the registered graph keep working; only the backup firing stops.
- Visual Studio 2022 (MSVC, x64)
- CommonLibF4 (same version OAR links against; not needed for the Clips API header)
- nlohmann-json (header-only, same version; not needed for the Clips API header)
- C++23 standard
x64-windows-static-mdvcpkg triplet (matching OAR)
OpenAnimationReplacer/
|-- CMakeLists.txt # Build + CommonLibF4 link
|-- CMakePresets.json # msvc-release / msvc-debug
|-- OpenAnimationReplacer.ini
|-- README.md
|-- extern/commonlibf4/ # Vendored multi-runtime CommonLibF4 (OG/NG/AE)
|-- docs/
| |-- QuickStart.md # Authoring + conditions (detailed)
| |-- HavokReference.md
| +-- HavokReference2.md
|-- src/
| |-- main.cpp # F4SE entry, messaging
| |-- LogSetup.cpp # spdlog init (separate TU for ShlObj)
| |-- Hooks.cpp # hkbClipGenerator hooks, track filter, variants
| |-- Parsing.cpp # Disk scan, variant grouping, JSON
| |-- AnimationCache.cpp # .hkx load, runtime clone, annotations
| |-- Variants.cpp # Random/sequential selection
| |-- Conditions.cpp # Condition implementations
| |-- ReplacerMods.h # SubMod, TrackFilter, variant settings
| |-- OpenAnimationReplacer.cpp # Path map, DB injection
| +-- UI/ # ImGui (UIManager, UIMain, debug overlay)
+-- Compile/F4SE/Plugins/ # Build output (OpenAnimationReplacer.dll)
| Component | Responsibility |
|---|---|
Parsing |
Discover .hkx, group variants, read JSON |
OpenAnimationReplacer |
animPathToReplacementsMap, bundle injection |
AnimationCache |
Load packfile/tagfile, build runtime clones |
Hooks |
Condition eval, swap or track-filter, annotation firing |
Variants |
Per-actor / per-clip selection state |
ActiveReplacementTracker |
Debug overlay entries |
| Tool | Notes |
|---|---|
| Visual Studio 2022 | x64, Desktop development with C++ |
| CMake | >= 3.21 |
| vcpkg | VCPKG_ROOT set; triplet x64-windows-static-md |
| CommonLibF4 | Vendored multi-runtime fork at extern/commonlibf4 (OG / NG / AE) |
| Fallout4Path | Environment variable -- game root |
cd OpenAnimationReplacer
cmake --preset msvc-release
cmake --build build/release --config ReleaseOutput: Compile/F4SE/Plugins/OpenAnimationReplacer.dll
Copy the DLL and OpenAnimationReplacer.ini to Data/F4SE/Plugins/.
Dependencies are declared in vcpkg.json (e.g. spdlog, nlohmann-json, imgui).
| Symptom | Things to check |
|---|---|
| SubMod loads silently but never applies (nothing in log) | Structure is one level too shallow, or behavior config is at the Mod level — see The two silent structure mistakes. Verify with bVerboseLogging=1 and look for NameLookup: suffix='...' — the suffix must match the path after Animations\ |
| No replacement in game | bEnabled=1; conditions in log (OpenAnimationReplacer.log); priority vs other SubMods; correct _1stPerson path; with direct path matching, mirror the path after Animations\ (use the Animation Log) |
| Only one variant plays | variants.enabled; rerollPolicy; ensure multiple _N files + base exist |
| Reload anim cancels mid-play | Often interruptible SubMod or competing priority; check transition logs |
| Ammo updates but no visible anim | Conditions pass but clip swap failed -- check cache load errors in log |
| No sound / reload events | replaceAnnotations; annotation times in replacement .hkx; eventsOnEnd; confirm [OAR-Annot] Fired / Nested Update — suppressed in the log |
| Weapon vanishes / jumps to fast equip when replacing draw | Usually fixed in current builds (behavior triggers kept). Confirm you are on a build after the equip trigger-filter fix; check [OAR-TrigFilter] KEEP lines for non-annotation triggers |
| Dry-fire / silent replace still fires WeaponFire | Set suppressAnnotations: true or ["WeaponFire"]; looping fire clips must not restore original triggers mid-loop (current builds skip that) |
| Phantom equip / draw sounds during melee or other actions | Ghost clip Updates during nested graph events — current builds suppress all annot emission (including SoundPlay) while nested and seek on large localTime jumps. Look for [OAR-Annot] Nested Update / Seek (no fire) |
| Crash at startup in ReadBoundAnimDataBinary | Usually corrupt/unrelated .hkx in load order -- not OAR hook code; test without animation packs |
| Track filter looks wrong / drops during hitches | Bone names must match skeleton; try override vs additive; check blend times. Concurrent filters per actor and wall-clock staleness are supported in current builds |
Enable bVerboseLogging=1 and inspect [OAR-Transition], [OAR-Variant], [OAR-Cache], [OAR-TrigFilter], [OAR-Annot] lines.
| Document | Contents |
|---|---|
| docs/ConditionReference.md | Complete list of all 97 conditions with parameters and examples |
| docs/QuickStart.md | Step-by-step authoring, full condition list, examples |
| docs/HavokReference.md | Struct offsets and Havok notes |
| docs/HavokReference2.md | Additional Havok / clip generator notes |
Parent workspace (if present): F4SE_Plugin_Development_Reference.md for F4SE plugin conventions.
- Original Skyrim mod: Open Animation Replacer -- Andrealphus-Mods
- Fallout 4 port: DCC Studios / contributors
- CommonLibF4: Ryan-rsm-McKenzie and contributors
See repository license when published. The Skyrim original remains under its upstream license.