Masterlist Syntax


  1. Introduction
  2. Structure
  3. Rules & Guidelines
  4. Syntax
    1. Silent Comments
    2. Group Lines
    3. Plugin Lines
    4. Message Lines
    5. Masterlist Variables & Variable Lines
    6. Regular Expression Plugin Lines
    7. Web Links
    8. Global Messages
    9. Conditional Expressions
      1. Compound Conditional Expressions
      2. Else Conditional Expressions
  5. Conditional Expression Evaluation
    1. Performance
  6. Examples


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

A simple example of this structure is: [group line (beginning)]
[plugin line]
[plugin line]
[message line]
[message line]
[plugin line]
[group line (end)]

Rules & Guidelines

The following are some rules and guidelines that should be followed when editing the masterlist.

  1. Always use the latest available version of the masterlist format.
  2. When including a web link in a message, be sure to use the Web Links syntax.
  3. Don't include any formatting in messages. This includes HTML, BBcode and Wiki syntax.
  4. Write the keywords in uppercase and indent message lines by two spaces.
  5. Use blank lines to separate plugins that are grouped together or where it helps readability.
  6. Use silent comments when something may need clarification to others reading the masterlist, such as when a plugin looks like it is misspelled, but is correct, or is put in a special position for compatibility reasons.
  7. Only make edits/additions you're confident about - otherwise discuss the issue on the official forum threads.
  8. If you're unsure on how to write something in the correct syntax, check this document and don't be afraid to ask other team members for help.
  9. When you list Bash Tags for a plugin, separate them using and not just ,. Eg. {{BASH:Graphics,NoMerge}} should be written {{BASH: Graphics, NoMerge}}. This improves readability in the BOSS Log and the masterlist itself.
  10. Put variable lines at the top of the masterlist, just under the header.
  11. Put global message lines at the top of the masterlist, just under any variable lines.


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

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.

Group Lines

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

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

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.

Masterlist Variables & Variable Lines

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 Expression Plugin Lines

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:

Examples: ""

in the HTML BOSS Log, and is unchanged in the plain text BOSS Log. " example link"


example link
in the HTML BOSS Log, and
example link ("")

in the plain text BOSS Log.

Global Messages

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.

Conditional Expressions

A line can be made to be applied only under 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
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.

Compound Conditional Expressions

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

Else Conditional Expressions

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.

Conditional Expression Evaluation

Evaluation of conditionals attached to lines is deferred until after the masterlist is parsed, for greater flexibility. Evaluation of conditionals does not occur wholly in the order in which they were parsed, but rather in the following order:

  1. Variable lines, in the order in which they were parsed.
  2. Global message lines, in the order in which they were parsed.
  3. Group, plugin, regular expression and message lines, in the order in which they were parsed.

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:

  1. Use conditional groups wherever you have more than at least four plugins in the same location of the masterlist that share at least one conditional. In practice, four is probably slightly too few plugins to justify a group, since it increases the length of the masterlist. Use your judgment, and ask if you are not sure.
  2. If multiple lines throughout the masterlist use the same conditional, and that conditional is not a single variable condition, use that conditional to define a masterlist variable, and change the rest of the lines that use that conditional to instead use a conditional that only contains a variable condition. For example: 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

  3. Use else conditional expressions wherever possible. Evaluating an IF/ELSE or IFNOT/ELSE pair of lines requires very nearly half the computation that an IF/IFNOT or IFNOT/IF pair of lines requires.
  4. Use file conditions instead of regular expression conditions wherever possible.
  5. Use version conditions instead of checksum conditions wherever possible. A version condition can often be used to check if a plugin came from a certain release of a mod, while a checksum condition can be used to check if that plugin was also modified by the user. If you do not require the extra precision, and the version information of the plugin changes consistently between releases, use a version condition and not a checksum condition.

The different types of condition in order of decreasing speed are:

  1. Variable conditions: These are very fast as BOSS stores defined masterlist variables in a hash set while running.
  2. Plugin active status conditions: The contents of plugins.txt is loaded whether or not there are any plugin active status conditions in the masterlist, and the contents are stored in a hashset after loading, so these conditions are of the same speed as variable conditions.
  3. File conditions: These are still fast, and should not impact performance. However, repeated usage may cause slowdown as file existence is not stored in memory and is re-checked for every condition.
  4. Regular expression conditions: These are of variable speed, but will always be slower than file checks. They need to scan a directory's contents for any files that match the given regex, so the processing time will vary with the number of files to be scanned. Directory contents is not cached, so repetition of a regex condition can impair performance significantly.
  5. Version conditions: These are of a medium speed. They need to read part of a file's contents to extract its version and so are slower than file conditions. Like file existence, version information is not stored in memory.
  6. Checksum conditions: These are very slow, though processing time varies with file size. They require a complete read of a file and calculate the CRC from its contents. Usage will result in noticeable slowdown. Calculated CRCs are cached while running so that a plugin's CRC is only calculated a maximum of once. Subsequent checks will be faster than file checks but still slower than variable checks.


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: "" 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", "", >) 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", "", =) 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.


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