Writing Bgs Load Order

Writing a BGS load order (plugins.txt)

Harness status (2026-07-29): The local prototype harness was destroyed by an unattributed operation and will not be rebuilt. The historical .artifacts/mo2 example below is DEFUNCT. Testing now uses externally-configured Starfield or Fallout 4 MO2 instances; machine-specific details and the forensic record are private.

Sources for every claim in this skill: Ortham/libloadorder (the library behind LOOT), ModOrganizer2/modorganizer/src/profile.cpp, ModOrganizer2/modorganizer-basic_games/.../game_plugins.py, and xEdit's official docs Section 2.8.1.

Two file formats — know which one applies

This skill covers the asterisk format in depth. If your target is Skyrim LE / Oblivion / FO3 / FNV, the rules are different — see the "Legacy format" section at the bottom.

File location

Ownership in MO2 use: MO2 writes plugins.txt whenever the user toggles plugin checkboxes in the GUI. LOOT can also write it. If you mutate it under MO2, do it while MO2 is closed OR via mobase's IPluginList API — live edits while MO2 is open get overwritten on its next save.

Asterisk format reference

# This file was automatically generated by Mod Organizer.
*Unofficial Fallout 4 Patch.esp        ← * = ACTIVE; loads first among non-vanilla
ArmorKeywords.esm                       ← no * = present-but-INACTIVE; position preserved
*HUDFramework.esm
SomeDisabledMod.esp
*MyMod.esp                              ← bottom = loads LAST = wins conflicts

Verbatim parser rules (from libloadorder/src/load_order/asterisk_based.rs):

• Blank lines → ignored.
• Lines starting with # (column 0) → comment, ignored.
• Lines starting with * → plugin name follows; active.
• Lines starting with any other character → plugin name; inactive but tracked.
• No inline comments. # must be at column 0.
• Encoding: Windows-1252. Plugin names with non-Win1252 characters cannot be activated until renamed.
• Line endings: LF and CRLF both accepted on read. Prefer LF on write (libloadorder's default).
• Order: first line = lowest load-order index = loaded first. Last line = wins conflicts.

排序判断 / Ordering judgment

Ordering is not list housekeeping. It decides which plugin record or archive payload the game actually sees when two mods touch the same thing: later wins. For loose files, remember the separate asset layer: loose files can win over BA2/BSA archive contents even when their plugin loads earlier. Use ordering to choose whole-record / whole-archive winners; use a patch when you need one final record stitched from multiple mods.

Iron law: if the desired result cannot be expressed as "one later plugin wins over one earlier plugin," stop sorting and audit/patch the conflict.

The source-mined principle comes from BB84's Vortex-era sorting lesson and the later xEdit "终极奥义": order is theoretically replaceable by a final compatibility patch, but patching every conflicting FormID in a real pack is not realistic. A sane order reduces the patch surface; it does not eliminate patching.

digraph sort_or_patch {
  rankdir=TB;
  start [label="Conflict or ordering question", shape=doublecircle];
  exists [label="Do the involved plugins actually load and have valid masters?", shape=diamond];
  fixfile [label="Fix plugins.txt/loadorder.txt validity first", shape=box];
  author [label="Does the mod author specify order or patch requirement?", shape=diamond];
  obey [label="Follow author instruction; verify with xEdit/readback", shape=box];
  winner [label="Can one plugin/archive win wholesale without losing needed data?", shape=diamond];
  sort [label="Solve by order: later winner goes after earlier loser; mirror loadorder.txt in MO2", shape=box];
  stitch [label="Need fields/data from multiple plugins in one final state?", shape=diamond];
  patch [label="Hand off to xedit-conflict-audit / xedit-automation and build or inspect a patch", shape=box];
  group [label="Is this about a per-game group template (lighting/weather/major compatibility-fix style)?", shape=diamond];
  kb [label="Query KB domain=load-order for the target game; if silent, mark [GAP]", shape=box];
  done [label="Verify winning override / loaded file chain", shape=doublecircle];

  start -> exists;
  exists -> fixfile [label="no"];
  exists -> author [label="yes"];
  fixfile -> done;
  author -> obey [label="yes"];
  author -> winner [label="no"];
  obey -> done;
  winner -> sort [label="yes"];
  winner -> stitch [label="no"];
  sort -> done;
  stitch -> patch [label="yes"];
  stitch -> group [label="not sure"];
  patch -> done;
  group -> kb [label="yes"];
  group -> patch [label="no"];
  kb -> done;
}

Judgment rules

• Sort solves priority: which complete plugin record or BA2/BSA archive wins after a later-wins cascade.

• Patch solves composition: which fields from multiple plugins must be preserved together in one final winning record.

• Group ordering is a scale tool, not magic. Put mods into purpose-based groups so order can be reasoned about in batches; same-group conflicts still need a specific winner or a patch.

• Masters and official early-loading plugins are not discretionary. Infer them from the current runtime as described below; user-managed patches generally live late because they intentionally carry final stitched decisions.

• Prefer the later winner that expresses the pack's system rule over incidental edits from a content mod. Example principle: if one mod imposes the pack-wide equipment-slot rule and another content mod casually edits one vanilla slot, the system-rule mod usually belongs later. Verify the actual records.

• Do not inline per-game group templates here. For lighting, weather, major compatibility-fix placement, major overhauls, or game-specific community group layouts, query the KB first:

  bgs_kb_query({ query: "load order group template lighting weather patch", games: ["<Game>"], domains: ["load-order"] })

  If the KB is silent, mark [GAP] instead of inventing a generic position.

LOOT / automatic sort vs manual sort

Red flags

Rationalizations

If sorting does not produce the intended winning override, hand off to xedit-conflict-audit: inspect the record, name the winning override, decide whether the current winner is safe, and only then route to patch authoring.

Official / vanilla masters — infer them from the current game, do not hardcode

The engine loads each game's official plugins at fixed positions before reading the user-managed plugins.txt. The exact set depends on the target game, installed DLC, and any Creation Club / verified-content bundles.

Do not hardcode a per-game vanilla-master list in your workflow. Instead, derive the official masters from the user's actual MO2-managed runtime:

1. Read <MO2_Root>\ModOrganizer.ini to learn gameName and gamePath.
2. Once xEdit is ready, call xedit_call({ command: "files.list", args: {} }) and look at the earliest, auto-loaded official plugins. Treat those as the immutable official master set.
3. If xEdit is not ready yet, inspect the MO2-managed game root (<gamePath>\Data) and known official DLC/content files there. Do not add, remove, or reorder them in your generated plugins.txt.

libloadorder's writer skips these early-loading official plugins on save; MO2 re-injects them as active at read time. So whether they appear in the file or not, they load first.

Practical rule for agent-authored plugins.txt: omit the official masters you inferred from the actual target runtime. Start your file with user-managed plugins instead.

Six operations the agent does most often

1. Enable a currently-disabled plugin

Prefix the line with *. Position unchanged.

Before:

ArmorKeywords.esm

After:

*ArmorKeywords.esm

2. Disable without removing

Strip the leading *. Position preserved (the plugin stays in the file).

Before:

*HUDFramework.esm

After:

HUDFramework.esm

3. Remove a plugin entirely

Delete the whole line. Position is dropped. (MO2 will re-append it as inactive at the end of loadorder.txt on next read — plugins.txt itself stays clean.)

4. Reorder (move X to load AFTER Y)

Cut the line, paste it after Y. Mirror the change in loadorder.txt if it exists (MO2 maintains both files; out-of-sync state confuses MO2).