Better Oblivion Sorting Software
User Rules Documentation


Contents
  1. Introduction
  2. Getting Started With The Userlist
  3. Rule Basics
  4. Rule Definition Syntax
  5. Enforcing Your Rules
  6. Further Notes On Rules
  7. The BOSS Message Format
  8. Compatibility With BOSS Masterlist Manager (BOMM)


Introduction

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.



Getting Started With The Userlist

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:

  1. Sort mods and groups. You can:
    • Sort plugins relative to other plugins. You can both override the positions of plugins BOSS recognises and sort plugins unrecognised by BOSS.
    • Sort groups of plugins relative to other groups of plugins. You can override the positions of the groups in the BOSS sorts mods into.
    • Insert plugins into groups. You can put plugins at the beginning or end of groups.
    Plugins may be .esp or .esm files. Groups are all pre-defined in the BOSS masterlist, marked out by the \BeginGroup\: Group Name and \EndGroup\\ lines.
  2. Edit BOSS messages. You can add to or replace the mod-specific messages that are displayed in the BOSSlog. See The BOSS Message Format below for more details on the message types and syntax.
The rule definition syntax is simple and concise, and is explained below.



Rule Basics

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 Mod

To 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
...

Changing A Recognised Mod's Position

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
...

Editing A Mod's BOSSlog Messages And Bash Tag Suggestions

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}}
      • ...


        • Rule Definition Syntax

          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.


          The Rule Line

          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.


          The Sort Line

          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.


          The Message Line

          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.


          Examples

          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.



          Enforcing Your Rules

          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:

          1. If the rule includes a sort line and uses the sort keywords BEFORE or AFTER, it will print a message of the form: "Mod/Group Name" sorted before/after "Mod/Group Name".
          2. If the rule includes a sort line and uses the sort keywords TOP or BOTTOM, it will print a message of the form: "Mod Name" inserted into the top/bottom of group "Group Name".
          3. If the rule includes one or more message lines, each message line will give a message of the form: "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:

          1. If the rule has the correct syntax, but adds a mod that is already in the masterlist, it will print a message of the form: "Mod Name" is already in the masterlist. Rule skipped.
          2. If the rule's sort mod is not installed, and is not in the masterlist, it will print a message of the form: "Mod Name" is not installed, and is not in the masterlist. Rule skipped.
          3. If the rule contains a keyword that is unrecognised (eg. written in lowercase, spelt wrong), it will print a message detailing the line with the error and will skip the last rule detected. If the line with the error is the first line of a new rule, that rule will also be skipped.
          4. If the rule has one or more other syntax errors, it will print a list of them under a line of the form: 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.



          Further Notes On Rules

          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:

          1. Blank lines or lines beginning with "//" (without quotes) 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 or disable specific rules as you desire.
          2. User rules are case-insensitive. The only exception is the message object, which will retain its case when displayed in the BOSSlog.

          3. If a rule's rule mod is not installed in your Data folder, the rule will be skipped.
          4. Mods ghosted by Wrye Bash are treated no differently from non-ghosted mods, and can be referenced with or without their ".ghost" extension.
          5. The group "ESMs" must always load first. You cannot sort this group or sort another group before it.
          6. The game's master .ESM file must always load first. You cannot sort it, sort another mod before it, or insert another mod into the top of the "ESMs" group.
          7. You cannot sort a mod relative to another mod that is not in the masterlist and has not been sorted by a previous rule.
          8. You must never sort a group more than once. When using multiple rules sorting groups, make sure none of the groups you are sorting are located inside any of the other groups you are sorting.
          9. 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: Mod1.esp
            BEFORE: LoadBeforeThis.esp

            OVERRIDE: xulAspenWood.esp
            AFTER: Mod1.esp

            ADD: Mod2.esp
            BEFORE: RTT.esp
            which will order the mods as:
            Mod2.esp
            RTT.esp
            Mod1.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.


          The BOSS Message Format

          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.


          Compatibility With BOSS Master List Manager (BOMM)

          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:

          1. All BOMM rules are applied.
          2. If BOMM and BOSS both add a mod, the BOSS rule will be ignored, since BOMM already added it.
          3. If BOMM and BOSS both override a mod position, the BOSS rule would override the changes made by the BOMM rule, and the mod would be moved to the BOSS position.
          4. If BOMM and BOSS both append message(s) to a mod, all the BOMM and BOSS messages are applied, but BOSS messages are only visible in BOSSlog (as usual), whereas BOMM messages are visible in the masterlist too (as usual).
          5. If BOMM and BOSS both override messages attached to a mod, the BOSS message overrides the BOMM message, though the BOMM message is still visible in the masterlist.