As mentioned in The User Rules Manager, user rules can be used to customise BOSS's sorting of plugins and the messages attached to them. To recap, user rules can do the following:
\BeginGroup\: Group Name
and \EndGroup\\
, or BEGINGROUP: Group Name
and ENDGROUP
, lines.
Note: This section contains some examples of user rules written for Oblivion mod plugins, but user rules will work for any of the games BOSS supports, not just Oblivion. In addition, when your game's master file
is mentioned, this refers to Morrowind.esm, Oblivion.esm, Nehrim.esm, Skyrim.esm, Fallout3.esm or FalloutNV.esm for Morrowind, Oblivion, Nehrim, Skyrim, Fallout 3 or Fallout: New Vegas respectively.
The userlist is the file which contains your user rules for sorting plugins and editing plugins' messages. It is found at BOSS\[GAME]\userlist.txt
, where [GAME]
is one of Morrowind
, Oblivion
, Nehrim
, Skyrim
, Fallout 3
or Fallout New Vegas
, depending on the game the userlist is for. A blank userlist is automatically created for a game when BOSS is first run for that game.
Within this file, which you can edit in Notepad or any other text editor, you list your rule definitions. The rule definition syntax is simple and concise, and is explained in the Rule Syntax section below.
When BOSS is run, it will read your userlist, checking the syntax of the rules it finds, and then attempt to apply the rules found if no syntax errors were encountered. It will display the rules it finds in the User Rules
section of your BOSS Log, along with whether they were applied or not, and if not, why.
If the parser finds a syntax error in your userlist, either grammatical or contextual, it will stop parsing and discard any rules it has found before printing an error message detailing what was expected and where. For some grammatical errors, the expected item may not provide much useful meaning - in these cases look at where the error was found and determine the exact cause of the problem yourself. See the Error Messages section in the main readme for a full list of possible contextuaal 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 disable it and re-run BOSS.
This section gives the syntax required to write some basic rules. A full description of the syntax is found in the Rule Syntax section.
To sort a plugin that is not in the masterlist after another plugin:
ADD: [RULE PLUGIN]
AFTER: [SORT PLUGIN]
To sort it before another plugin:
ADD: [RULE PLUGIN]
BEFORE: [SORT PLUGIN]
The rule plugin is the plugin you want to add, and the sort plugin is the plugin you want to sort it relative to.
Examples:
ADD: Plugin1.esp
AFTER: AFK_Weye.esp
ADD: Plugin2.esp
BEFORE: AFK_Weye.esp
This gives a load order of:
...
Plugin2.esp
AFK_Weye.esp
Plugin1.esp
...
To sort a plugin that is already in the masterlist after another plugin:
OVERRIDE: [RULE PLUGIN]
AFTER: [SORT PLUGIN]
To sort it before another plugin:
OVERRIDE: [RULE PLUGIN]
BEFORE: [SORT PLUGIN]
The rule plugin is the plugin you want to sort, and the sort plugin is the plugin you want to sort it relative to.
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 plugin for display in the BOSS Log:
FOR: [RULE PLUGIN]
APPEND: [MESSAGE OBJECT]
To replace the messages attached to a plugin for display in the BOSS Log:
FOR: [RULE PLUGIN]
REPLACE: [MESSAGE OBJECT]
The rule plugin is the plugin 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: SAY: Replaced!
FOR: bgMagicEV.esp
APPEND: TAG: {{BASH: Names, Delev, Relev}}
This will print in the BOSS Log:
...
Unofficial Oblivion Patch.esp...
- Note: Replaced!
bgMagicEV.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 plugin or group that the rule is applied to. If the rule keyword is ADD or FOR, the rule object must be a plugin.
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 plugins that begins with \BeginGroup\: Supreme Magicka
, you would put it in the rule as Supreme Magicka
.
There is one more keyword that can be used on the rule line. DISABLE
can be put before the rule keyword to prevent the rule from being applied. For example:
DISABLE ADD: MyMod.esp
AFTER: Unofficial Oblivion Patch.esp
Would result in MyMod.esp not being sorted after Unofficial Oblivon Patch.esp. The DISABLE
keyword should be used instead of silent comments to stop a rule being applied because the latter makes the rule invisible to the GUI's User Rule Manager whereas the former does not.
If a rule's rule keyword is ADD or OVERRIDE, it can sort plugins and should include a sort line directly below the rule line. If the rule keyword is FOR, the rule must not include a sort line. A rule may only contain one 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. Plugins must be sorted relative to other plugins, and groups must be sorted relative to groups. You cannot sort plugins relative to groups, or vice versa. You also cannot sort your game's master file, sort other plugins 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 plugin into. You cannot insert groups into anything, plugins into plugins, 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 plugin. Message lines have the structure:
[MESSAGE KEYWORD]: [MESSAGE OBJECT]
The message keyword can be one of:
REPLACE
message line per rule, and if used it must be the first message line.
The message object is the message, complete with keyword, that you wish to attach to the plugin defined by the rule object. You cannot attach messages to groups.
You may have multiple message lines in a rule (but only the first may use the REPLACE
message keyword), to add multiple messages to a plugin, or to override an existing set of messages with a new set.
Here is the contents of an example userlist:
ADD: MyPluginToAdd.esp
AFTER: LoadAfterThis.esm
APPEND: SAY: Adding a general message.
APPEND: REQ: OOO
OVERRIDE: MyPluginToOverride.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: L.A.M.E.
BEFORE: Supreme Magicka
FOR: bgBalancingEVOptionalNPCDiversity, Vanilla.esp
REPLACE: SAY: This is a replacement message.
APPEND: TAG: {{BASH:NpcFaces,NoMerge}}
This is the equivalent of the masterlist having:
...
LoadAfterThis.esm
MyPluginToAdd.esp
SAY: Adding a general message.
REQ: OOO
...
MyPluginToOverride.esp
LoadBeforeThis.esp
...
bgBalancingEVOptionalNPCDiversity, Vanilla.esp
SAY: This is a replacement message.
TAG: {{BASH:NpcFaces,NoMerge}}
...
Which would give in the BOSS Log:
...
LoadAfterThis.esm
MyPluginToAdd.esp...
- Note: Adding a general message.
- Requires: OOO
MyPluginToOverride.esp
LoadBeforeThis.esp
...
bgBalancingEVOptionalNPCDiversity, Vanilla.esp...
- Note: This is a replacement message.
- Bash Tag Suggestion(s): {{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.
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:
//
in your userlist will be ignored by BOSS. You can use blank lines to improve the formatting of your userlist, and use the //
line start to provide comments. Using the GUI's User Rules Manager strips all comments from your userlist.
\
instead of //
to have the same effect, and comment out multiple lines by enclosing them between /*
and */
.
DISABLE
keyword to disable rules, as this means that they are still visible to the GUI's User Rule Manager without being applied, though their syntax is still checked.
.esm
files, and non-master plugins are commonly .esp
files, but whether a plugin is a master or not is actually decided by a variable in the file, not the file extension. See False-Flagged Plugins of the main readme for more information.
Rules are applied in the order they are listed. This means you can have several rules sorting different rule objects relative to the same sort object, or have rules sorting rule objects relative to sort objects that were sorted in previous rules.
For example:
ADD: LoadBeforeThis.esp
AFTER: RTT.esp
ADD: Plugin1.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: xulAspenWood.esp
AFTER: Plugin1.esp
ADD: Plugin2.esp
BEFORE: RTT.esp
which will order the plugins as:
Plugin2.esp
RTT.esp
Plugin1.esp
xulAspenWood.esp
LoadBeforeThis.esp
Take 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.
Each of the four message types that can be added via the userlist begins with a message keyword. The keyword is then followed by the message itself. The message is just a standard line of text. In addition, Bash Tag suggestion messages must include the suggested Bash Tags in a comma-separated list beginning with {{BASH:
and ending with }}
.
The message types and keywords are listed in the table below:
Message Type | Keyword | Example |
---|---|---|
Bash Tag Suggestion | TAG: | TAG: {{BASH: Names, Graphics}} to prevent changes being lost when using overhauls.
|
General Message | SAY: | SAY: This message was added in a user rule.
|
Installation Requirement | REQ: | REQ: This mod requires another.
|
Specific Incompatibility | INC: | INC: This mod is incompatible with other mods that do the same thing.
|
This document is part of the BOSS documentation.
Copyright (C) 2009-2012 BOSS Development Team.
See the file BOSS ReadMe.html
for copying conditions.