LOOT Metadata Syntax

Contents

1. Introduction
2. Metadata File Contents
3. Data Structures
   1. Tag Data Structure
   2. File Data Structure
   3. Message Data Structure
   4. Location Data Structure
   5. Dirty Info Data Structure
   6. Plugin Data Structure
4. Condition Strings
   1. Functions
   2. The Negator & Junctors
   3. Order Of Evaluation
5. Language Codes
6. License
7. Feature Support

Introduction

The metadata syntax is what LOOT's masterlists and userlists are written in. If you know YAML, good news: the syntax is essentially just YAML 1.2. If you don't know YAML, then its Wikipedia page is a good introduction. All you really need to know is:

• How lists and associative arrays (key-value maps) are written.
• That whitespace is important, and that only normal spaces (ie. no non-breaking spaces or tabs) count as such.
• That data entries that are siblings must be indented by the same amount, and child data nodes must be indented further than their parents (see the example later in this document if you don't understand).
• That YAML files must be written in a Unicode encoding.
• That each key in a key-value map must only appear once per map object.

Some important points that are more specific to how LOOT uses YAML:

• LOOT's support for YAML syntax is incomplete. A list of known limitations can be found here. The only major missing piece is support for merge keys (<<:).
• Strings are case-sensitive, apart from file paths, regular expressions and checksums.

Some properties of file paths as used by LOOT:

• They are evaluated as paths relative to the game's Data folder.
• They cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring ../../.
• Regular expression file paths must be written in the EMCAScript syntax.
• Only the filename of a regex file path may contain non-literal regex syntax, ie. if the filename part of the regex file path is removed, the remainder must be an exact folder path (though with the regex syntax special characters escaped). For example, given the regex file path Meshes\\Resources(1|2)\\(upperclass)?table.nif, LOOT will look for a file named table.nif or upperclasstable.nif in the Meshes\Resources(1|2) folder, rather than looking in the Meshes\Resources1 and Meshes\Resources2 folders.

Please test any changes you make before uploading them. One way of doing this is to run LOOT, another is to copy/paste what you've changed into here, though it won't catch condition syntax errors and doesn't use the same parser as LOOT so may give different results.

Metadata File Contents

The root of a metadata file is a key-value map. LOOT will recognise the following keys, none of which are required:

Other keys may also be present, but are not processed by LOOT. The message and plugin data structures are detailed in the next section.

An example metadata file: globals: - type: say content: 'You are using the latest version of LOOT.' condition: 'version("LOOT", "0.5.0.0", ==)' plugins: - name: 'Armamentarium.esm' tag: - Relev - name: 'ArmamentariumFran.esm' tag: - Relev - name: 'Beautiful People 2ch-Ed.esm' tag: - Eyes - Graphics - Hair - R.Relations

Data Structures

LOOT expects metadata to be laid out using a certain set of data structures, described in this section.

Tag Data Structure

LOOT metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. It has two forms: the first is a simple string, and the second is a key-value map. All values in the map are strings.

The simple form: tag

where tag is the Bash Tag, preceded by a minus sign if it is suggested for removal.

The map form:

Examples: Relations or name: -Relations condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")'

File Data Structure

Not to be confused with the structure of the metadata file itself, this structure can be used to hold file paths. It has two forms: the first is a simple string, and the second is a key-value map. All values in the map are strings.

The simple form: filepath

where filepath is an exact (ie. not regex) file path relative to the game's Data folder.

The map form:

Examples: '../obse_loader.exe' or name: '../obse_loader.exe' condition: 'version("../obse_loader.exe", "0.0.18.0", >=)' display: 'OBSE v18+'

Message Data Structure

Messages are given as key-value maps.

There are three message types:

The localised content data structure is a key-value map, with all values being strings:

LOOT supports formatting of messages using GitHub Flavored Markdown. Support is provided by the Marked library (v0.3.2). Strings that get substituted into messages, such as file display names and dirty info utility strings, also support the same formatting options.

LOOT handles messages and languages as follows:

1. If a message's content value is a string, the message will use the string as its content if displayed.
2. If a message's content value is a list of localised content structures, then the first structure with a language that matches LOOT's current language will be used as the message's content if displayed. If there are no matches, then the first structure in English will be used.

Examples (translations by Google): type: say condition: 'file("foo.esp")' content: - lang: en str: 'An example link: <http://www.example.com>' - lang: ru str: 'Это пример ссылки: <http://www.example.com>' would be displayed as

отмечать: Это пример ссылки: http://www.example.com

отмечать: An alternative example link, with no translations.

Note: A newer version of this plugin is available.

Location Data Structure

This data structure is used to hold information on where a plugin is hosted online. It is not currently used by LOOT, but it was suggested that since the LOOT team receives a considerable number of plugin URLs, they should be recorded in a standard format, as there is no existing store of such information and it could prove useful in the future.

The data structure has two forms: the first is a simple string, and the second is a key-value map. The first form should be used for a URL without any associated version data, such as when it is not clear which version is found there, or when it is the only known hosting location for the plugin and as such hosts all available versions. The second form should be used when version data can be associated with the URL, such as when the URL only hosts a subset of the available versions of the plugin.

The simple form: URL

where URL is a URL at which the plugin may be found.

The map form:

Examples: 'http://skyrim.nexusmods.com/mods/19/' or link: 'http://steamcommunity.com/sharedfiles/filedetails/?id=87144366' ver: - '1.3.2c'

Dirty Info Data Structure

This structure holds information on which versions of a plugin are dirty, and how many identical-to-master records, deleted records and deleted navmeshes (if applicable) it contains. Dirty info is given as a key-value map.

Examples: crc: 0x3DF62ABC util: '[TES5Edit](http://www.creationkit.com/TES5Edit_Cleaning_Guide_-_TES5Edit)' itm: 4 udr: 160 nav: 0

Plugin Data Structure

This is the structure that brings all the others together, and forms the main component of a metadata file. It is a key-value map.

Each plugin must have only one matching non-regex entry. If multiple non-regex entries exist with the same name value, all but the first will be ignored. A plugin may match any number of regex entries though, and their metadata will be merged, with later entries being merged into earlier entries as detailed in the table below. Merging only takes place if both entries have their enabled value set to true (which is the default if unspecified).

Example: name: 'Oscuro''s_Oblivion_Overhaul.esm' req: - 'Oblivion.esm' # Don't do this, Oblivion.esm is a master of Oscuro's_Oblivion_Overhaul.esm, so LOOT already knows it's required. - name: 'example.esp' display: '[Example Mod](http://www.example.com)' condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", "15.0", ==)' tag: - Actors.Spells - Graphics - Invent - Relations - Scripts - Stats - name: -Relations condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")' msg: - type: say content: 'Do not clean. "Dirty" edits are intentional and required for the mod to function.'

Condition Strings

Condition strings can be used to ensure that data is only acted on by LOOT under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited. Their EBNF grammar is: [ negator ], function, { junctor, [ negator ], function } ;

The [ negator ], function grammar is referred to as a condition, and two conditions joined by an operator, ie. condition, operator, condition is referred to as a compound condition.

LOOT caches the results of condition evaluations, so performance is not really an issue. A regular expression check will still take longer than a file check though, so use the former only when appropriate to do so.

Functions

There are several conditions that can be tested for using the functions detailed in the table below.

The different types of variable used in the above functions are described in more detail below.

The Negator & Junctors

The negator, or logical negation operator, inverts the value of the function that follows it. Its inclusion is optional, and its syntax is simply: not

Below is a truth table for the negator.

There are two supported junctors, the logical conjunction (logical and operator) and the logical disjunction (logical or operator), that operate on the expressions to their left and right.

The following is a truth table for the junctors:

Order Of Evaluation

When a condition string is evaluated, its constituent parts are evaluated according to the standard precedence rules of operator logic, ie.

1. Function
2. Negator
3. Logical and
4. Logical or

Below is a table that lists some combinations of conditions, showing for each the order of evaluation by explicit bracketing. To make it easier to read, the negator function pair is shortened to C after the first example.

You can also explicitly enclose any condition in brackets to override the evaluation order, eg. C and ( C or C ) is evaluated as C and ( C or C ), in contrast to the unbracketed string above.

Language Codes

LOOT supports the following languages and language codes:

License

This document is part of the LOOT documentation.
Copyright (C) 2012—2014 WrinklyNinja
See the file LOOT ReadMe.html for copying conditions.

Feature Support

Different versions of LOOT may have varying levels of support for the syntax detailed in this document. Such variation in support is detailed in the table below. Unless otherwise noted, all syntax changes are backwards-compatible (ie. you can use the features without breaking the masterlist for users on older versions).