Programmable follower behaviour for Skyrim SE. Every follower carries ordered
lists of Gambits — [Condition] -> [Action] rules, first match wins —
authored live, in game, per follower. Final Fantasy XII's gambit system
rebuilt on the engine's own actor primitives.
Status: v2.0.0, released (see VERSION and the
GitHub releases; the exact point
release is in VERSION). As of 2.0.0 MFO runs on Harbinger (APMF),
a required control-layer framework of mine that lets several mods drive the same
follower without clobbering each other. MFO routes a follower's casting, combat
target, packages, and gear through it, so a follower another mod keeps parked
still loots, casts, and retreats cleanly. Without Harbinger MFO falls back to its
older paths and reminds you it is missing. Gambits execute in both tables and the
mod is playable end to end. Follower detection, Rapport, the in-game board, and combat and
logistics actuation are built and field-tested. Followers cast (their own AI,
animated, at chosen targets), attack, drink, restock, loot, and walk to loot,
up to four followers sweeping a battlefield at once, and fall back to your
side on their own when badly outmatched. They run their own economy, selling
their junk and buying, wearing, and managing their own gear out of their own
gold. A follower's class shapes its Health, Magicka and Stamina growth on
level up (a mage gains Magicka, an archer gains Stamina), fixed-stat unique
followers included. The progression system is a self-contained add-on over a
general follower API, so MFO is also the worked example for building your own
follower add-on. Build order and what's deferred are in
ROADMAP.md; the per-version history is in
CHANGELOG.md.
A follower carries two independent rule lists with separate slots. They never interleave: combat runs in combat, logistics runs out of it.
1. Ally: HP below 40% -> Cast Fast Healing
2. Foe: Weak to fire -> Cast Flames
3. Self: Magicka below 20% -> Drink magicka potion
4. Foe: Lowest HP -> Attack
Top-down, first match wins, one action per tick. A follower cannot heal and attack in the same cycle — the cost of a heal is the attack not made.
Upkeep, so a follower who runs dry of arrows or is still wearing their recruitment armour isn't something you have to micromanage.
1. Health potions < 3 -> Loot health potions
2. Out of arrows -> Loot arrows
3. Always -> Loot better equipment
4. Always -> Loot gold
The vocabulary: drink and loot health/stamina/magicka potions (or any potion — low-power restore potions below your load order's own weakest useful tier are ignored, strongest looted first), loot arrows and bolts (separate gambits), loot gold, and loot better equipment. Equipment generalises by category and metric, never by item — a weapon upgrade is judged within the follower's dominant weapon-skill class (a two-hander takes the greatsword over a dagger, an archer won't swap to a mace), armour by rating on the slot within the class they can use — a light-armour follower won't pick up plate they have no skill in. Modded gear works with no patch, and a caster won't hoover up a random sword.
Magic users dress like mages. A follower with cast gambits loots school-appropriate apparel: enchanted robes, hoods, gloves and boots that boost his most-cast school (weighted across his cast gambits' spells, read from the enchantment itself at loot time) beat raw armour rating on those slots — a destruction mage upgrades into Destruction robes; among matches the finer piece wins. He also stocks one melee backup (daggers by default, any one-hander via MCM) so the vanilla AI has something to draw when his magicka runs dry. Both behaviours are MCM toggles under Logistics, on by default.
Followers loot like people, not vacuums:
- They walk to it. A follower paths to the loot and picks it up — they don't teleport-grab from across the room. How far they'll range is the confidence leash below.
- They can pick locks they're skilled enough for — a Novice lock at any Lockpicking skill, an Expert lock only near mastery; Master and key-locked are out of reach.
- First dibs are yours. Arrows and potions a follower restocks at once, but it leaves gear and gold on a fresh corpse for a few seconds first — your pick. It never takes owned goods, and holds off entirely while you're sneaking so they don't blow your stealth. Once you've taken from a source the wait collapses; you've had your look.
- Not in your house. Followers never loot inside a player home (any cell the game flags as one) unless you opt in.
Followers trade at merchants. Stand a follower next to a vendor and they sell their unworn junk — highest value first, capped by the vendor's own gold — and buy the supplies they've run short on, chosen from what that vendor actually stocks: the best they can afford, up to the number they need, from their own purse. Off by default; enable Follower economy in the MCM. The merchant reads and the transaction run through Papyrus (the path the barter menu itself uses), so it is crash-safe where a raw engine read is not, and it is hardened against a mid-trade save.
Gambits layer on top of vanilla AI; they never replace it. A follower with no matching rule behaves byte-identically to one without MFO installed — no no-op package, no neutral command, no engine call at all.
Confidence, on an invisible string. How far a follower operates from you isn't a fixed follow distance — it's a live readout of how confident they are to survive on their own right now. Healthy in an easy zone, they push ahead and range out to loot; hurt, or in a hard fight, they pull back and fight at your side. You never see a number. You just feel a companion get bold clearing a bandit camp and wary in a dragon's lair. Taken to its conclusion, a follower who is badly outmatched and far from you auto-retreats to your side (on by default; a combat-sense rule can override it). It tunes on the Behaviour Layer config page, and it's the model for how MFO adds realism: hidden variables you read through behaviour, not sliders.
Reactions are human, not robotic. A gambit decision is a choice reaction, which in people runs 300–600 ms, so responses are drawn from a right-skewed distribution rather than firing on a metronome. Followers occasionally miss a beat. A companion that reacts at reflex speed to a tactical situation reads as a machine.
Competence is not permission. Teaching a follower a spell doesn't mean they can cast it — if they lack the magicka or the skill, the rule simply fails and the next one is tried. The board tells you why, so a list that doesn't work is legible rather than mysterious.
The list is yours. MFO executes it as written: no reordering, no deduplication, no coordination between followers, no penalty for filling every slot. Two followers both healing the same ally is your authoring, and the fix is yours to make.
Rule slots are earned through Rapport, built by fighting alongside that specific follower. It's never pooled or transferable, and it survives dismissal — leave someone in Breezehome for two hundred hours and they're exactly as you left them. (Gating the vocabulary by rank — not just slot count — is designed but deferred; see the roadmap.)
| Rank | Combat slots | Logistics slots | Reactions |
|---|---|---|---|
| I | 3 | 4 | visibly hesitant |
| III | 7 | 6 | ↓ |
| V | 12 | 8 | anticipates |
What a follower can be told to do depends on their own skills and spellbook — a battlemage opens cast actions a pure warrior never will, and the board shows each follower only what they could actually perform.
Rules are authored in game, per follower, on the Field Orders power — because reading a log after the fact is a hopeless way to develop a behaviour mod.
- A passive HUD that takes no input, so it stays readable while fighting: per-follower rank, rapport, live health/magicka/stamina, distance.
- The Field Orders board: a Followers roster and the Gambits editor — cycle each rule's condition, action, and value, with a full-width plain- language summary of every rule so a whole gambit is legible even on a Steam Deck. Styled after MEO, in four skins.
Full controller parity throughout — gamepad navigation is a standing requirement across these mods, not an afterthought. Settings live in an MCM (MCM Helper), including the Behaviour Layer page for the confidence leash and walk-to-loot.
- Skyrim Anniversary Edition 1.6.1170 or Special Edition 1.5.97. VR is not supported. Both versions get the full feature set: walking to loot, Flee to player, Auto-retreat and cast control have worked on 1.5.97 since v2.0.9. At startup MFO checks every game address it uses against a table made by hand for these two versions. On any other version its hooks stay off and the log says so.
- Harbinger (APMF) — the control-layer framework MFO drives followers through. Install it for the full feature set. This version wants Harbinger 0.9.10 (lockpicking, museum drop-offs, the fight leash and the retreat's combat hold need it). MFO still runs with Harbinger 0.9.5 or newer, and without it MFO degrades to its older paths and says so in the log.
- SKSE64
- Address Library for SKSE Plugins
- SkyUI and MCM Helper (version 9 or newer) — the settings menu
- powerofthree's Papyrus Extender (
po3_papyrusextender.dll) — required only for the optional follower economy (selling/buying); everything else runs without it. If it is absent, the economy stays off and MFO logs one line saying so. - Synthesis — MFO reads an item catalog (
mfo_items.json) that its Synthesis patcher (added from this repo — seeinstaller/README.md) generates from your load order so gambit categories (potions, ammo, gear classes) cover modded items with no per-mod patch. MFO runs without it, falling back to a shipped catalog; run the patcher for full modded-item coverage.
- Install the requirements above with your mod manager (Mod Organizer 2 or Vortex), each per its own instructions.
- Install MFO's archive as a normal mod and enable
MFO.esp. - Run the MFO Synthesis patcher as part of your Synthesis build (optional but recommended — see above).
- Launch through SKSE. Open the MCM (Mod Configuration → marth's Follower Overhaul) to configure; every behaviour ships off or conservative by default.
Load order is not sensitive — MFO drives followers through runtime AI, not record edits, so it does not conflict with follower mods, AI overhauls, or combat mods. Updating mid-playthrough is safe: all state lives in the co-save and reverts cleanly on load. (Saves that ran versions ≤ 1.0.24 are additionally swept clean of a furniture-breaking alias latch on their first load under ≥ 1.0.26 — automatic, one load, nothing to do.)
Start at CLAUDE.md, then MAP.md.
Docs/INDEX.md sets the full read order and marks which
documents are current and which are historical.
CLAUDE.md— the working rules and the engineering principlesMAP.md— the architecture and change-impact map, byfile:lineINVARIANTS.md— read before any code changeSTATUS.md— the living handoffCAST-DELIVERY.md— before touching any cast pathENGINE_NOTES.md— what is proven vs merely researchedANTI_PATTERNS.md— the portable "never again" listGAMBIT-GUIDE.md— the condition→action vocabularyBALANCE.md— the Rapport ladder and its content budgetCHANGELOG.md— per-version history
Historical, kept for the reasoning trail and banner-marked as such:
DESIGN.md (the July 2026 spec),
ARCHITECTURE.md (superseded by MAP.md),
ROADMAP.md, and the three GAMBIT_* design docs.
C++ lives in native/. The DLL is built by GitHub Actions on
windows-latest — CommonLibSSE-NG needs the MSVC linker and there is no Linux
cross-build, so CI is the only compiler that ever sees this code. git push is the build button.
Releases are cut with ./release.sh: ./release.sh X.Y.Z stamps and pushes,
then ./release.sh --run <run-id> packages the DLL from exactly that green
native CI run (a bare ./release.sh lists the recent green runs with branch
and sha; --dry-run runs the checks only). It refuses a dirty tree, refuses a
run that is not green or whose native/ tree differs from HEAD's, and records
commit, run id and artifact hashes in a manifest. vcpkg registry baselines are pinned
deliberately — bump them on purpose, never float them.
MFO's own code is MIT — see LICENSE. All of it lives in native/;
no third-party source is vendored here. The shipped DLL statically links
CommonLibSSE-NG (MIT, © 2018 Ryan-rsm-McKenzie), Dear ImGui, nlohmann/json,
spdlog and fmt (all MIT); their notices are in
THIRD-PARTY-NOTICES.md. The three board fonts —
Cinzel, EB Garamond and the Noto Sans JP fallback — are licensed
under the SIL Open Font License 1.1, reproduced in OFL.txt. Both files ship with every release.