Userlist Syntax

Contents

1. Introduction
2. Getting Started
3. Basic Rules
   1. Sorting An Unknown Plugin
   2. Changing A Recognised Plugin's Position
   3. Editing A Plugin's BOSS Log Messages & Bash Tag Suggestions
4. Rule Syntax
   1. The Rule Line
   2. The Sort Line
   3. The Message Line
   4. Examples
5. Further Notes
6. The BOSS Message Format
7. License

Introduction

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:

1. Sort plugins relative to other plugins. You can both override the positions of plugins BOSS recognises and sort plugins that are unrecognised.
2. Sort groups of plugins relative to other groups of plugins. BOSS's masterlist generally lists plugins in thematic groups, which you can override the relative positioning of. You can't create new groups though. Groups are marked out by the \BeginGroup\: Group Name and \EndGroup\\, or BEGINGROUP: Group Name and ENDGROUP, lines.
3. Insert plugins into the top or bottom of groups of plugins.
4. Edit the messages BOSS attaches to plugins. You can add to or replace messages with your own. See The BOSS Message Format below for more details on the message types and syntax.

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.

Getting Started

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.

Basic Rules

This section gives the syntax required to write some basic rules. A full description of the syntax is found in the Rule Syntax section.

Sorting An Unknown Plugin

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

Changing A Recognised Plugin's Position

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

Editing A Plugin's BOSS Log Messages & Bash Tag Suggestions

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

...

Rule 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:

• ADD: This tells BOSS that the rule sorts a plugin that is not in the masterlist. The rule may also add and/or edit messages attached to that plugin.
• OVERRIDE: This tells BOSS that the rule overrides the current position of a plugin or group in the masterlist with a new position. The rule may also add and/or edit messages attached to that plugin.
• FOR: This tells BOSS that the rule adds and/or edits the messages attached to a plugin, but does not sort it.

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.

The Sort Line

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:

• BEFORE: This states that the rule object is to load immediately before the sort object.
• AFTER: This states that the rule object is to load immediately after the sort object.
• TOP: This states that the rule plugin is to be inserted into the top of the sort group. The rule plugin will then load before everything else in the sort group.
• BOTTOM: This states that the rule plugin is to be inserted into the bottom of the sort group. The rule plugin will then load after everything else in the sort group.

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.

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 plugin. Message lines have the structure: [MESSAGE KEYWORD]: [MESSAGE OBJECT]

The message keyword can be one of:

• APPEND: This states that the message is to be appended to the list of messages attached to the rule plugin.
• REPLACE: This states that the message is to replace any existing message or messages attached to the rule plugin. You may only have up to one 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.

Examples

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.

Further Notes

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 // 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.
   • You can also begin lines with \ instead of // to have the same effect, and comment out multiple lines by enclosing them between /* and */.
   • It is better to use the 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.
2. User rules are case-insensitive. The only exception is the message object, which will retain its case when displayed in the BOSS Log.
3. If a rule's rule plugin is not installed in your Data folder, the rule will be skipped.
4. Plugins ghosted by Wrye Bash are treated no differently from non-ghosted plugins, but they must be referenced 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 file must always load first. You cannot sort it, sort another plugin before it, or insert another plugin into the top of the "ESMs" group.
7. You cannot sort a plugin relative to another plugin that is not in the masterlist and has not been sorted by a previous rule.
8. You cannot include conditionals in any messages added through user rules. While BOSS will not display any errors, the message will be added as if it were a note with no conditional.
9. You cannot sort mods or groups relative to themselves.
10. You cannot sort a non-master plugin before a master, or a master after a non-master plugin. Masters are commonly .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.

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

The BOSS Message Format

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:

License

This document is part of the BOSS documentation.
Copyright (C) 2009-2012 BOSS Development Team.
See the file BOSS ReadMe.html for copying conditions.