While BOSS is able to sort the large number of mods listed in its masterlist without any user input, you may find that you wish to customise the sorting of your mods. This may be to include mods not listed in the masterlist (either mods not yet added or temporary plugins or private files not suitable for masterlist inclusion), or it could be to rearrange mods present in the masterlist that can be loaded in a different configuration for different results (eg. LAME and Supreme Magicka files). You may also wish to add extra messages to mods, or edit existing messages.
One possible solution is to edit your copy of the masterlist to include the desired changes. However, as updating your masterlist will remove these edits, this is not very suitable as a long term solution.
This is where user rules comes in. Using a separate userlist file, you can define rules for sorting specific mods or groups of mods as you like, as well as for adding or editing messages attached to mods, and these rules will not be lost when you update your masterlist.
NOTE: In this readme, the words 'mod' and 'plugin' are used interchangeably, meaning 'one individual file with a .esp or
.esm extension'. Unless explicitely stated, the 'name' of a 'mod' or 'plugin' refers to its filename, including the extension.
Also, while the examples in this ReadMe reference Oblivion and some of its mods, the functionality will work for all the games BOSS supports. When your game's master .ESM file is mentioned, this refers to Oblivion.esm, Nehrim.esm, Fallout3.esm or FalloutNV.esm for Oblivion, Nehrim, Fallout 3 or Fallout: New Vegas respectively.
The userlist is the file which contains your custom rules for sorting mods and editing mods' messages. It is found at Data\BOSS\userlist.txt
. If it
does not exist, simply create a new text file there with the same name. Make sure that the full filename is "userlist.txt" and not "userlist.txt.txt", as can sometimes occur if file extensions are hidden.
Within this file, which you can edit in Notepad or any other text editor, you list your rule definitions. Rules can make two types of changes:
\BeginGroup\: Group Name
and \EndGroup\\
lines.While it is strongly suggested that you read the Rule Definition Syntax section below to gain a proper understanding of user rules, here is a quick start guide for some simple rules.
Sorting An Unknown ModTo sort a mod that is not in the masterlist after another mod:
ADD: <RULE MOD>
AFTER: <SORT MOD>
To sort it before another mod:
ADD: <RULE MOD>
BEFORE: <SORT MOD>
The rule mod is the mod you want to add, and the sort mod is the mod you want to sort it relative to.
Some examples:
ADD: Mod1.esp
AFTER: AFK_Weye.esp
ADD: Mod2.esp
BEFORE: AFK_Weye.esp
This gives a load order of:
...
Mod2.esp
AFK_Weye.esp
Mod1.esp
...
To sort a mod that is already in the masterlist after another mod:
OVERRIDE: <RULE MOD>
AFTER: <SORT MOD>
To sort it before another mod:
OVERRIDE: <RULE MOD>
BEFORE: <SORT MOD>
The rule mod is the mod you want to sort, and the sort mod is the mod you want to sort it relative to.
An example:
OVERRIDE: bgBalancingEVCore.esp
AFTER: Unofficial Oblivion Patch.esp
This gives a load order of:
...
Unofficial Oblivion Patch.esp
bgBalancingEVCore.esp
...
To add a message to a mod for display in the BOSSlog:
FOR: <RULE MOD>
APPEND: <MESSAGE OBJECT>
To replace the messages attached to a mod for display in the BOSSlog:
FOR: <RULE MOD>
REPLACE: <MESSAGE OBJECT>
The rule mod is the mod you want to add the message to. The message object is the formatted BOSS message that you want to attach. See the The BOSS Message Format section later on in this readme if you are unfamiliar with BOSS message formatting.
An example:
FOR: Unofficial Oblivion Patch.esp
REPLACE: ? Overrided!
FOR: bgMagicEV.esp.esp
APPEND: % {{BASH:Names,Delev,Relev}}
This will print in the BOSSlog:
... Unofficial Oblivion Patch.esp
- Note: Overrided!
... bgMagicEV.esp.esp
- Bashed Patch tag suggestion: {{BASH:Names,Delev,Relev}}
...
User rules have a specific structure and syntax which your rules must follow to be applied. The information below provides the details on this structure and syntax.
Every rule begins with a rule line, which defines what basic type of rule it is and what plugin it is applied to. It has the structure:
<RULE KEYWORD>: <RULE OBJECT>
This is the rule line. The rule keyword can be one of:
The rule object is the mod or group that the rule is applied to. If the rule keyword is ADD or FOR, the rule object must be a mod.
When you define groups, the names of those groups are used as they appear in the masterlist. For example,
if you wanted to reference the group of mods that begins with \BeginGroup\: Supreme Magicka
, you would put it in the rule as
Supreme Magicka
.
If a rule's rule keyword is ADD or OVERRIDE, it can sort mods and should include a sort line. If the rule keyword is FOR, the rule must not include a sort line. The sort line has the structure:
<SORT KEYWORD>: <SORT OBJECT>
The sort keyword can be one of:
When using the BEFORE or AFTER sort keywords, the sort object is the plugin or group that you wish the rule object to be positioned relative to. Mods must be sorted relative to other mods, and groups must be sorted relative to groups. You cannot sort mods relative to groups, or vice versa. You also cannot sort your game's master .ESM, sort other mods before it, or sort groups before the "ESMs" group.
When using the TOP or BOTTOM sort keywords, the sort object is the group that you wish to insert the rule mod into. You cannot insert groups into anything, mods into mods, or insert anything into the top of the "ESMs" group.
If a rule's rule keyword is FOR, it should include at least one message line. A rule with a rule keyword of ADD or OVERRIDE can also include message lines, if they sort a mod. Message lines have the structure:
<MESSAGE KEYWORD>: <MESSAGE OBJECT>
The message keyword can be one of:
The message object is the message, complete with symbol code, that you wish to attach to the mod defined by the rule object. You cannot attach messages to groups.
You may have multiple message lines in a rule, to add multiple messages to a mod, or to override an existing set of messages with a new set.
Here is the contents of an example userlist:
ADD: MyModToAdd.esp
AFTER: LoadAfterThis.esm
APPEND: ? Adding a general comment.
APPEND: $ Incompatible with OOO!
OVERRIDE: MyModToOverride.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: L.A.M.E.
BEFORE: Supreme Magicka
FOR: bgBalancingEVOptionalNPCDiversity, Vanilla.esp
REPLACE: ? This is a replacement message.
APPEND: % {{BASH:NpcFaces,NoMerge}}
This is the equivalent of the masterlist having:
...
LoadAfterThis.esm
MyModToAdd.esp
? Adding a general comment.
$ Incompatible with OOO!
...
MyModToOverride.esp
LoadBeforeThis.esp
...
bgBalancingEVOptionalNPCDiversity, Vanilla.esp
? This is a replacement message.
% {{BASH:NpcFaces,NoMerge}}
...
The rule sorting the two groups L.A.M.E. and Supreme Magicka simply moves the L.A.M.E. group from its current position to before the Supreme Magicka group.
When BOSS is run, it will look for your userlist at Data\BOSS\userlist.txt
. If it is found, and the userlist contains at least one rule, BOSS will first check the syntax of the rules, and apply those with the correct syntax.
It will print error messages detailing the problems with any rules it skips, and success messages for the mods that are applied, into your BOSSlog.txt, in a section headed "Userlist Messages" near the top.
If a rule is successfully applied, it will print one or more messages depending on what the rule does:
"Mod/Group Name" sorted before/after "Mod/Group Name".
"Mod Name" inserted into the top/bottom of group "Group Name".
"Message" appended to/replaced messages attached to "Mod Name".
If a rule is found to have errors in its syntax or it is found to add a mod that is already in the masterlist, it will print one or more error messages depending on the type of error:
"Mod Name" is already in the masterlist. Rule skipped.
"Mod Name" is not installed, and is not in the masterlist. Rule skipped.
The rule beginning "First Line Of Rule" has been skipped as it has the following problem(s):
and then list below messages detailing the syntax errors.
Rule application does not alter your masterlist.txt or userlist.txt. This means that if you want to undo the application of a rule, all you need to do is remove it from your userlist.txt and re-run BOSS.
While the Rule Definition Syntax section gave you most of the rules of defining rules, here are some further general notes on defining rules that may not be evident:
ADD: LoadBeforeThis.esp
AFTER: RTT.esp
ADD: Mod1.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: xulAspenWood.esp
AFTER: Mod1.esp
ADD: Mod2.esp
BEFORE: RTT.esp
which will order the mods as:
Mod2.espTake care when writing such rules though, as a small difference in the order of the rules in your userlist can have a very large difference on the resulting load order.
RTT.esp
Mod1.esp
xulAspenWood.esp
LoadBeforeThis.esp
Understanding the BOSS message format is important if you wish to edit mods' messages. Each of the seven message types begins with a symbol code that signifies what type of message it is, and then the message itself follows it. The message is just a standard line of text. In addition, Bash Tag suggestion comments also have a special syntax for the suggestions they include. The symbol codes for the different message types are:
% Bash Tag Suggestion
? General Comment
* Critical FCOM Install Error
: Installation Requirement
" Specific Incompatibility
$ OOO specific comment. This will only be displayed if the user has OOO in their load order.
^ Better Cities specific comment. This will only be displayed if the user has Better Cities in their load order.
The syntax for a Bash Tag suggestion is:
% {{BASH:list suggested tags separated by commas here}} you may also have some text here.
For example:
% {{BASH:Names,Graphics}} to prevent changes being lost when using overhauls.
Since BOMM includes similar functionality, it would be advisable to only use one method of implementing user rules. If you decide to use both, due to BOMM rules altering the masterlist.txt and running before BOSS rules, the following occurs: