This documentation is a complete record of all information on the masterlist syntax, including rules and guidelines on usage, detailed explanations of features and syntaxes, and examples of usage. It is intended for use by BOSS developers rather than as a document that should be read by users.
As BOSS has developed, so too has the masterlist format. This documentation covers all the functionality present in the latest masterlist format supported by the latest release of BOSS, and also details the next version of the masterlist format to be released.
The current release of BOSS is v2.1.0, which supports MF2.2 and MF2.3 (MF = Masterlist Format). The next release of BOSS will be v2.1.1, which will support only MF2.3. As MF2.4 has not yet been created, this documentation will only cover MF2.3 syntax.
The masterlist is a plain text file encoded in UTF-8 which lists mod plugins, which are files with .esp
or .esm
extensions, in the order in which they co-exist best in. Each plugin may optionally have one or more messages attached to it for display in the BOSS Log. To make managing the masterlist easier, mods are often placed in groups that are often themed. These groups are defined and named in the masterlist, and also provide some sorting functionality for BOSS's User Rules feature.
The masterlist is parsed by BOSS line-by-line, so it is most useful to analyse the structure by the different types of line present:
plugin line. In their most basic form, these lines only contain the plugin's filename.
message line. In their most basic form, message lines contain a
message keyword, which tells BOSS what type of message the line contains, and a string of characters which is the message itself. Message lines are positioned below the plugin line of the plugin they attach messages to.
group line.
A simple example of this structure is:
[group line (beginning)]
[plugin line]
[plugin line]
[message line]
[message line]
[plugin line]
[group line (end)]
The following are some rules and guidelines that should be followed when editing the masterlist.
,
and not just ,
. Eg. {{BASH:Graphics,NoMerge}} should be written {{BASH: Graphics, NoMerge}}. This improves readability in the BOSS Log and the masterlist itself.
This section details the syntaxes for functionality found at least partially in all masterlist formats.
Note that a colon :
must be put after the last keyword on a line, before the plugin or group name or message that follows it, to mark the boundary. While most of the syntax examples below include the colon with the keyword, they are not two parts of the same thing, and this should be kept in mind.
Some general features of MF2:
Silent comments are character strings that are skipped by the BOSS parser and so have no effect on BOSS's output. C++ style comments must start at the beginning of a line. C style comments must start and end at the beginning of lines. Comments may not be used inline. In the table below, [comment]
is the comment being made.
Type | Syntax | Description |
---|---|---|
C++ Style | // [comment] | Skips everything on the line after the type identifier. |
C Style | /* [comment... | Skips everything between the /* and */ delimiters.
|
As mentioned before, groups are used to provide some order in the masterlist and to allow bulk plugin sorting via User Rules. A group is defined by start and end lines which enclose the plugins to be contained in the group.
Type | Syntax |
---|---|
Start Group | BEGINGROUP: [name]
|
End Group | ENDGROUP: [name]
|
In the table above, [name]
is the name of the group. The name should be given at both the start and the end, although inclusion at the end is not an absolute requirement. If an ending line does not contain a group name, it does not require a colon.
Plugin lines have the simplest of syntaxes. The line should contain only the plugin filename:
[plugin]
Plugin lines also have a keyword associated with them, MOD
, which can be given before the plugin filename and the two separated by a colon. However, since BOSS assumes that lines with no recognised keywords are plugin lines, the inclusion of the keyword is unnecessary and for the purposes of readability should not be used unless a conditional is used in the plugin line. If the plugin line has a conditional, the MOD
keyword should be included between the conditional and the colon.
Message lines are listed under the plugin line of the plugin that they are to be attached to. There are several different types of message line. In the table below, [message]
is the message to be attached. Messages have no special syntax unless otherwise noted.
Type | Syntax | BOSS Log Prefix | Description |
---|---|---|---|
General | SAY: [message] | Note: | A general message. |
Bash Tag Suggestion ² | TAG: [message] | Bash Tag suggestion(s): | A Bash Tag suggestion or suggestions. |
Requirement | REQ: [message] | Requires: | An installation requirement or requirements. |
Incompatibility | INC: [message] | Incompatible with: | An incompatibility or incompatibilities. |
Dirty Plugin | DIRTY: [message] | Contains dirty edits: | A message about dirty edits. |
Warning | WARN: [message] | Warning: | A warning message. |
Error | ERROR: [message] | ERROR: | An error message. |
² Bash Tags suggested by BOSS are given in a specific syntax in order for Wrye Bash/Flash/Flash NV to recognise and automatically apply them. The syntax for adding Bash Tags is {{BASH: Tag1, Tag2}}
. The syntax for removing Bash Tags is [Tag1, Tag2]
. Any number of Bash Tags may be listed for addition or removal. Information on Bash Tags themselves is found in the Wrye Bash, Wrye Flash and Wrye Flash NV Readmes.
Variables may be set in the masterlist using the following syntax, where [name]
is the variable name:
SET: [name]
The name of a variable is a string that must not contain whitespace or a closing parenthesis )
. The existence of variables may be queried in conditionals. They are intended for use as shorthand for more complex conditionals that are repeated several times throughout the masterlist, not as a method to track some sort of status, which is why they can only be set, not unset.
Unlike message lines, variable lines exist independently of plugin lines. A variable line will therefore signal the termination of a set of attached message lines, much like a plugin line would, and any message lines after the variable line will be skipped, having no plugin to attach to. For example:
[plugin line]
[message line 1]
[message line 2]
[variable line]
[message line 3]
In the above structure, only message lines 1 and 2 will be parsed, and message line 3 will be ignored.
Variable lines are applied after the masterlist has been parsed, before the evaluation of other conditionals.
Regular expressions may be used in the masterlist for plugin names using the following syntax, where [regular expression]
is the plugin filename written in the POSIX Extended regular expression syntax:
REGEX: [regular expression]
BOSS will search the user's plugins and sort all the plugins that match the regular expression given in its location in the masterlist. If more than one plugin matches, the order in which the plugins will be placed at that position is random, so it should not be used to sort a set of similarly named plugins which require specific ordering within the set.
URLs in messages will be turned into hyperlinks in the HTML-format BOSS Log if they are enclosed in double quotes. The full URL, including protocol identifier, is required for the URL to be detected as such. URLs in messages can be given labels by including a space followed by the label within the quoted string after the URL itself. Recognised protocol identifiers are:
http
https
file
Examples:
"http://www.example.com"
becomes:
http://www.example.comin the HTML BOSS Log, and is unchanged in the plain text BOSS Log.
"http://www.example.com example link"
becomes:
example linkin the HTML BOSS Log, and
example link ("http://www.example.com")
in the plain text BOSS Log.
A global message may be displayed using the following syntax:
GLOBAL [message keyword]: [message]
Where the [message keyword]
and [message]
are as described in the above Message Lines section. Global messages are not attached to plugins, but are instead displayed in a separate section of the BOSS Log.
A line can be made to only be applied in certain circumstances by adding a conditional expression to the start of that line. Conditional expressions can be added to any line. The syntax for a conditional expression with only one condition is:
[condition keyword] [condition] [line]
If [line]
is a plugin line, then the conditional must be followed by the MOD
keyword, eg. IF FILE("Foo.esp") MOD: MyPlugin.esp
will place MyPlugin.esp
in that position if Foo.esp
is installed.
If [line]
is a group line, then the plugins and groups it contains will only be evaluated if the conditional expression evaluates to true, otherwise they will be skipped.
There are two condition keywords available:
Condition Keyword | Description |
---|---|
IF | If [condition] evaluates to true, the conditional will be true. Otherwise, the conditional will be false.
|
IFNOT | If [condition] evaluates to false, the conditional will be true. Otherwise, the conditional will be false.
|
There are several types of condition that can be tested for, detailed in the table below.
Condition Type | Syntax | Description |
---|---|---|
Variable | VAR([variable]) | Returns true if [variable] is defined, false otherwise. |
File | FILE("[file]") | Returns true if [file] is installed, false otherwise. |
Checksum | CHECKSUM("[file]", [checksum]) | Returns true if the calculated checksum of [file] matches [checksum], false otherwise. If [file] does not exist, returns false. |
Version | VERSION("[file]", "[version]", [comparator]) | Returns true if the expression [version] [comparator] [actual version of [file]] holds true, false otherwise. If [file] does not exist and [comparator] is = or > , returns false. If [file] does not exist and [comparator] is < , returns true.
|
Regular Expression | REGEX("[regex]") | Returns true if a file matching [regex] is installed, false otherwise. |
Plugin Active Status | ACTIVE("[file]") | Returns true if [file] is a .esp or .esm file that is both installed and active, false otherwise. If [file] does not exist, returns false.
|
BOSS Language | LANG("[language]") | Returns true if [language] is the language BOSS is currently running in, false otherwise. |
The syntaxes for the different types of condition variable are:
Variable Type | Syntax Description |
---|---|
[variable] | A masterlist variable as written where it is set, ie. a string of characters that does not include any whitespace or a closing bracket ) .
|
[file] | A string of characters representing a filename that does not contain a double quote character " (which is an invalid filename character on Windows anyway). The file may be any file, and may include other path components. The starting directory is the folder in which the game's plugins are stored (Data for all supported games but Morrowind, which uses Data Files ). The exception to this is that if a .dll file is given without any path components other than its filename, BOSS will look in the game's Script Extender plugin folder. Paths may use either forwardslashes or backslashes.
|
[checksum] | A string of hexadecimal digits representing an unsigned integer that is the data checksum of a file. BOSS can be run to display the data checksums of installed plugins. |
[version] | A string of characters representing the version of a plugin or executable. BOSS displays the versions of plugins and Script Extender executables. |
[comparator] | One of = , > or < , meaning "is equal to", "is greater than" and "is less than" respectively.
|
[regex] | The syntax is as for [file] , but the filename can contain POSIX Extended regular expression syntax. If a path is supplied, it may not contain any regular expression syntax other than the escaping of any backslashes present. I.e. Textures\\testtexture(_n)?\.dds is valid but Te[xX]tures\\testtexture(_n)?\.dds is not.
|
[language] | A language name, in the same form as required by the BOSS.ini's sLanguage setting.
|
Filenames, checksums, regular expressions and languages are case-insensitive. Version strings and masterlist variables are case-sensitive.
In addition to explicitly referencing files, there are some placeholders that can be used to reference certain files, given in the table below. These placeholders may be used as [file]
variables, but not as any other variable type, including [regex]
variables.
Placeholder | Path Referenced |
---|---|
BOSS | ..\BOSS\BOSS.exe |
OBSE | ..\obse_1_2_416.dll |
FOSE | ..\fose_loader.exe |
NVSE | ..\nvse_loader.exe |
SKSE | ..\skse_loader.exe |
MWSE | ..\MWSE.dll |
TES3 | ..\Morrowind.exe |
TES4 | ..\Oblivion.exe |
TES5 | ..\TESV.exe |
FO3 | ..\Fallout3.exe |
FONV | ..\FalloutNV.exe |
The paths referenced are given relative to the folder in which the game's plugins are stored. The game and script extender placeholders will only work if BOSS is running for the relevant game, even if the file they reference is present when running for another game, e.g. using the TES5 placeholder when not running for Skyrim will cause the condition to return false even if the executable is present.
Note: Morrowind's Script Extender is not required if the user has the Morrowind Graphics Extender installed, as the latter includes the former within its own library files (but not for all releases). As such, it is not possible to check conclusively for the existence or for the version of the Morrowind Script Extender.
The above conditional syntax is for when only one condition is present in the conditional. However, conditionals are not limited to only containing one condition. A conditional that contains more than one condition is known as a compound conditional.
Compound conditionals are formed by combining two or more conditionals using logical AND or OR operators, the syntax of which are given below.
Logical Operator | Syntax | Description |
---|---|---|
AND | && | Both sides must evaluate to true for the compound conditional to evaluate to true. If not, the compound conditional evaluates to false. |
OR | || | One side (or both sides) must evaluate to true for the compound conditional to evaluate to true. If neither side is true, then the compound conditional evaluates to false. |
The conditionals are evaluated incrementally in the order they are read. This means that the operators operate on everything to the left of them as a whole, and the first conditional on their right. This does not follow the standard order of precedence for logical operators.
A compound conditional composed of four conditions and attached to a line has the syntax:
A [operator] B [operator] C [operator] D [line]
where A
, B
, C
and D
all represent the syntax:
[condition keyword] [condition]
If the operators were such that the expression was A && B || C && D
, it would be evaluated as ((A && B) || C) && D
, not (A && B) || (C && D)
.
The else conditional expression can be used when a line should be conditional on the opposite of the conditional expression for the previous line of the same type. The syntax is:
ELSE [line]
The else conditional may not be used on group lines, the first line of each type in the masterlist, the first plugin line following a group start line, or the first message line following a plugin line.
The previous line of the same type does not have to contain a conditional: but in this case the else conditional will always evaluate to false. Else conditionals may not be used within compound conditionals.
Evaluation of conditionals attached to lines is defered until after the masterlist is parsed, for greater flexibility. Evaluation of conditionals does not occur wholey in the order in which they were parsed, but rather in the following order:
As such, a group's conditional expression does not affect any variable or global message lines contained within that group, and all variables that will be defined for a user's install will already be defined by the time that any non-variable lines get their conditionals evaluated. For example:
SET: Var1
IF VAR(Var2) MOD: Var2Mod.esm
IF VAR(Var1) SET: Var2
IF VAR(Var2) MOD: Var2Mod.esp
Var1 is set first, then Var2 is set, then the conditional for Var2Mod.esm is evaluated (to true), then the conditional for Var2Mod.esp is evaluated (to true).
The more conditional expressions that BOSS has to parse, the longer it will take to run. Evaluation of conditional expressions is typically the bottleneck that lengthens execution time. It is therefore important to consider performance when using conditionals. Here are some guidelines to improving performance when using conditionals, in the order of their effectiveness:
IF VERSION("Mod1.esp", "1.2", =) MOD: Mod2.esp
IF VERSION("Mod1.esp", "1.2", =) MOD: Mod3.esp
...
IF VERSION("Mod1.esp", "1.2", =) MOD: Mod4.esp
IF VERSION("Mod1.esp", "1.2", =) MOD: Mod5.esp
is better written as:
IF VERSION("Mod1.esp", "1.2", =) SET: Mod1
...
IF VAR(Mod1) MOD: Mod2.esp
IF VAR(Mod1) MOD: Mod3.esp
...
IF VAR(Mod1) MOD: Mod4.esp
IF VAR(Mod1) MOD: Mod5.esp
The different types of condition in order of decreasing speed are:
Below are some examples of the syntaxes covered in this documentation. The examples use some real plugins, but the content is purely exemplary and does not necessarily contain any valid information.
IF VERSION("BOSS", "2.1.1", <) GLOBAL ERROR: An update to BOSS is available. Please download BOSS v2.1.1.
//Make a variable for if OOO is installed.
//We can indent this comment because in MF2 whitespace doesn't matter, so it looks like it's at the start of the line.
IF FILE("Oscuro's Oblivion Overhaul.esm") && IF FILE("Oscuro's Oblivion Overhaul.esp") SET: OOO
//Also make a variable for FCOM:
IF FILE("FCOM_Convergence.esp") SET: FCOM
Mart's Monster Mod for OOO.esm
IFNOT VAR(OOO) WARN: Oscuro's Oblivion Overhaul.esm missing. Re-install OOO.
//The above line will only be shown in the BOSS Log if OOO is not installed correctly.
Unofficial Oblivion Patch.esp
IF VERSION("Unofficial Oblivion Patch.esp", "3.3", <) SAY: Upgrade to the latest version of the UOP Supplementals, found here: "http://oblivion.nexusmods.com/mods/27710"
TAG: {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you.
IF CHECKSUM("FastExit2.dll", CACF51FC) SAY: You have a legitimate copy of Fast Exit 2 installed. Good on you!
All Natural.esp
IF VERSION("OBSE", "0.0.20.0", >) WARN: You have the correct version of OBSE installed.
Unofficial Shivering Isles Patch.esp
IF CHECKSUM("Unofficial Oblivion Patch.esp", E0DDDD00) SAY: You are using version 3.3.5 of the UOP.
//The given checksum is the checksum of v3.3.5, as calculated by BOSS.
IF VERSION("sr_Oblivion_Stutter_Remover.dll", "4.1.0.0", =) SAY: You have Oblivion Stutter Remover v4.1 installed.
//Comment out the below section.
/*
PluginNotParsed.esp
TAG: {{BASH: Graphics}} You'll never see this in your BOSS Log.
*/
IF VAR(FCOM) MOD: Mart's Monster Mod - Fran's Leveled Quests.esp
IF VAR(FCOM) ERROR: Delete. Already integrated into FCOM.
Assuming that all version and plugin conditionals evaluate to true apart from the first, the above would have the following output.
- Mart's Monster Mod for OOO.esm
- Unofficial Oblivion Patch.esp
- Note: Upgrade to the latest version of the UOP Supplementals, found here: http://oblivion.nexusmods.com/mods/27710
- Bash Tag suggestion(s): {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you.
- Note: You have a legitimate copy of Fast Exit 2 installed. Good on you!
- All Natural.esp
- Warning: You have the correct version of OBSE installed.
- Unofficial Shivering Isles Patch.esp
- Note: You are using version 3.3.5 of the UOP.
- Note: You have Oblivion Stutter Remover v4.1 installed.
- Mart's Monster Mod - Fran's Leveled Quests.esp
- ERROR: Delete. Already integrated into FCOM.
This document is part of the BOSS documentation.
Copyright (C) 2011 BOSS Development Team.
See the file BOSS ReadMe.html
for copying conditions.