What this skill does
Open Animation Replacer (OAR) replaces Skyrim animations at runtime based on conditions. An
animation mod ships one or more replacer mods, each holding submods; every submod is one
config.json with a priority integer, a set of conditions, and the .hkx files it can swap in.
When a base animation plays on an actor, OAR finds the highest-priority submod whose conditions are
true for that actor and plays its animation instead. OAR is the successor to Dynamic Animation
Replacer (DAR) and reads DAR's legacy folders directly, so a load order mixes both.
Authoring here means: writing or editing config.json/user.json, building condition sets, setting
priorities, overriding an existing mod's conditions via user.json, and reading legacy DAR
_conditions.txt. Interpreting means answering "what does this do", "which submod wins", or "why
isn't this animation playing".
The exhaustive lookup tables — full config schema, the ~120 built-in conditions, the authoritative
IsEquippedType enum, value-component shapes, the DAR grammar — live in
references/oar-config-reference.md. Pull a value from there; do not reconstruct it from memory or a
web search — a web search usually surfaces the vanilla GetEquippedItemType enum, which OAR's
IsEquippedType deliberately differs from.
First step — orient before you touch a config
OAR is file-based, not record-based, so houseCARL's record tools don't see it. Work the files directly (Read / Glob / Grep / Write), and reach for houseCARL only to resolve the forms a condition needs.
- Locate the submod. OAR configs live at
…/meshes/actors/<project>/animations/OpenAnimationReplacer/<ModName>/<SubModName>/config.json. Legacy DAR lives under…/animations/DynamicAnimationReplacer/…. Glob for both. - Read what's already there. Read the submod
config.json(and anyuser.jsonbeside it —user.jsonwins). Read the parent<ModName>/config.jsonforconditionPresets. - Note required addons. If a condition name isn't a built-in (check the roster in the reference), it comes from an addon DLL (Math/RaySense/IED/Detection/Dialogue). Confirm that DLL is installed, or the condition is dead.
- Resolve forms with houseCARL. A condition that references a perk, keyword, race, faction, or
magic effect needs
{ "pluginName": …, "formID": <local hex> }or{ "editorID": … }. Usehousecarl_read_record/housecarl_cross_plugin_queryto get the defining plugin + local FormID (strip the load-order byte) or the EditorID.
The mental model — how OAR picks a winner
Internalize this before authoring; most "it doesn't work" reports trace back to it:
- Winners are decided per original animation, by sorting every targeting submod by
prioritydescending. Plugin/ESP load order is ignored entirely. - At runtime OAR walks that sorted list and takes the first submod whose
conditionsare true. If none pass, the base-game animation plays. - Higher priority wins. Equal priorities are ambiguous (no tiebreak) — keep them unique. Authors
spread large integers (
9007010,83030317) to slot cleanly between other mods.
So to make animation X beat animation Y, X's submod needs a higher priority and conditions that pass in the situation you care about. Load order is never the lever.
Authoring workflow
- Pick the target + project. The submod's
.hkxfiles must mirror the original animation's path; that path-match is what binds the submod to a base animation.<project>ischaracterfor humanoids. A submod with no.hkxis usingoverrideAnimationsFolderor is conditions-only — that's normal. - Choose a unique priority. Higher beats lower. To override an existing mod, read its submod priority and go above it.
- Build the condition set. Each entry is
{ "condition": "<Name>", "requiredVersion": "1.0.0.0", …params }. Add"negated": trueto invert. Combine withAND/OR/XOR— and note the nested child array is capital-CConditions, while the submod's top-level array is lowercaseconditions. Get param shapes (Form, Keyword, Numeric, Bool, Comparison, Multi) from the reference. For weapon gating, useIsEquippedTypewith the authoritative enum (battleaxe = 6, warhammer = 10 — they differ). - Pick the file:
config.jsonvsuser.json. If you're shipping/owning the mod, writeconfig.json. If you're overriding someone else's mod without editing it, write auser.jsonbeside theirconfig.json— OAR usesuser.jsoninstead ofconfig.jsonfor that submod (a full-document shadow, not a field merge, so include the complete config you want). In a modlist, keep alluser.jsonoverrides in one dedicated MO2 mod that loads after the originals; USVFS overlays them and they win, leaving originals untouched. (A modlist typically keeps these in one dedicated overrides mod that loads after the originals.) - Add variants / blend / loop behavior only if needed.
replacementAnimDatasdrives random variants (weight,playOnce,variantMode);interruptible,replaceOnLoop(default true), and theblendTime*fields tune transitions. PreferreplaceOnLoopover the deprecatedkeepRandomResultsOnLoop. - If you used an addon condition, state the dependency.
MathStatementneeds the Math plugin;IED_*needs IED Conditions; raycast conditions need RaySense; etc. Without the DLL the line becomes an INVALID no-op.
Reading / interpreting an existing config
The inverse job — answer precisely, and say "I can't tell without X" rather than guess:
- "What does this submod do?" Translate each condition using the reference (resolve enum values
and
editorID/FormID forms), then state the priority and what it competes against. - "Which submod wins?" Compare priorities of every submod targeting that animation; the highest with passing conditions wins. If you can't see all competing mods, say so.
- "Why isn't it playing?" Walk the checklist: is a higher-priority submod winning? Do the
conditions actually pass in that situation (weapon hand, enum value, missing perk)? Is a required
addon missing (condition shows INVALID)? Does the
.hkxpath mirror the original? Isuser.jsonshadowing theconfig.jsonyou're reading? Isdisabledset?
Common mistakes
- Lowercase
conditionsvs capitalConditions. Submod top level isconditions; the child array insideAND/OR/XOR/PRESET/PLAYER/TARGET/MOUNTisConditions. Swapping them yields an empty child set that silently passes/fails wrong. - Confusing OAR's
IsEquippedTypewith the vanilla equipped-type enum. Skyrim's vanillaGetEquippedItemType(what most web searches surface) says 9=spell / 10=shield / 11=torch; OAR deliberately differs — 9=crossbow, 10=warhammer, 11=shield, spells=12–16, torch=18. Use the reference table, not the vanilla enum. - Battleaxe vs warhammer. Both are engine
kTwoHandAxe; OAR splits by keyword (6 vs 10). A moveset meant for both must test6OR10. - Editing load order to fix a winner. Pointless — OAR only reads
priority. Change the integer. - Partial
user.json. It fully shadowsconfig.json; a half-writtenuser.jsondrops whatever it omits. Write the complete config (or let the in-game editor generate it). - Using an addon condition without its DLL. The line degrades to INVALID and never fires.
- Assuming a no-
.hkxsubmod is broken. It's usuallyoverrideAnimationsFolderor conditions-only.
Verification
- Re-scan: OAR parses configs on game load (and the in-game editor can reload a mod live).
- The editor's Detected Problems panel flags INVALID conditions (missing addon, bad form) and duplicate priorities — the fastest correctness check.
- Confirm the winner by listing priorities of all submods that target the same original animation.
- Confirm any addon condition's DLL is present under
…/SKSE/Plugins/.
Real example — overriding a mod's conditions via user.json
You want a mod's archery moveset to apply only after the player earns a specific perk, without
editing the mod. The original …/Bow Rapid Combo V3/Base/config.json is [IsActorBase player, IsEquippedType 7 (bow)] at priority 9901000. Put a user.json at the matching submod path — in a
separate, dedicated overrides mod that loads after the original — copying that and adds one
condition:
{ "priority": 9901000,
"conditions": [
{ "condition": "IsActorBase", "requiredVersion": "1.0.0.0",
"Actor base": { "pluginName": "Skyrim.esm", "formID": "7" } },
{ "condition": "IsEquippedType", "requiredVersion": "1.0.0.0",
"Type": { "value": 7.0 }, "Left hand": false },
{ "condition": "HasPerk", "requiredVersion": "1.0.0.0",
"Perk": { "pluginName": "<the perk-adding mod>.esp", "formID": "<local hex>" } } ] }
USVFS overlays the user.json beside the original config.json; OAR uses the user.json and the
moveset now only applies once the player has that perk. Resolve the HasPerk form (defining plugin +
local FormID) with houseCARL.
Notes
- DAR back-compat: OAR converts legacy
_CustomConditions/<priority>/(with_conditions.txt) and<Plugin.esp>/<FormID>/actor folders into in-memory submods that compete in the same priority space. The DAR grammar and the auto-synthesizedIsActorBaseform are in the reference. - The in-game editor is the live source of truth for which conditions exist in a given install
(core + whatever addons are present) and writes valid
config.json/user.jsonfor you. - houseCARL can't introspect OAR configs (it reads ESP records, not animation files) — read the files directly; use houseCARL only to resolve the forms/keywords/perks a condition references.