LOOT LOOT
Masterlist Editing

The purpose of this page is to give a bit of information to help with editing a masterlist.

General Hints

Writing Style

For consistency and to make it easier for people to understand what others have written, it's best to use the following style points when editing the masterlist.

The above points are illustrated in the following example.

name: 'Oscuro''s_Oblivion_Overhaul.esm'
req:
  - 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.'
    lang: eng
url: [ 'http://oblivion.nexusmods.com/mods/15256' ]
{name: Oscuro's_Oblivion_Overhaul.esm, req: [{ 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., lang: eng }], url: [ http://oblivion.nexusmods.com/mods/15256 ]}

Although both are valid YAML, the first is using the correct style, and the second is not.

Note: Much of the masterlists' content is machine-generated, and as such does not follow the writing style given above. This isn't an issue, and it's not worth spending time systematically changing all the generated entries, but if you're editing a generated entry, you might as well correct its style while you're at it.

Adding New Entries

Before you add a new entry for a plugin, make sure that there isn't already an existing entry for it. LOOT will attempt to merge entries if there are more than one for a plugin, but some metadata may be lost in the process, so it's always safer to only have one entry per plugin.

Don't open the masterlist and to a Ctrl-F search for the plugin filename, or anything similar. Instead, use the online Masterlist Search page to perform a search of the masterlist. This search utility has the following features:

You can even pass search parameters in the URL, using the syntax

https://loot.github.io/search/?game=<game>&search=<search>

where <game> can be one of oblivion, skyrim, fallout3, falloutnv or fallout4. <search> is the string you want to search for.

Common Metadata

Often the same metadata is used for plugins throughout the masterlist, for example generic messages. Rather than having these messages copy/pasted, YAML's anchor/alias feature can be used to define (anchor) the metadata once somewhere, then reference (alias) it wherever else it needs to be used. This has the advantages of guaranteeing consistency, eliminating typos, cutting down the overall size of the masterlist, and improving readability.

In the masterlists, everything that gets anchored and aliased in this manner should go in the common node, which is a sibling of the plugins and globals nodes that are mentioned in the Metadata Syntax documentation. The common node is ignored by LOOT, but the YAML parser still reads it, and will therefore still substitute any aliases made. By putting all the anchors in one place, it makes it easy for other maintainers to take advantage of any existing anchors, and avoids any duplication of anchors.

An example demonstrating just how much of a difference anchors/aliases can make:

common:
  - &useBP
    type: say
    content:
      - str: 'Use Bashed Patch tweak instead.'
        lang: eng
      - str: 'Используйте вместо этого настройку башед патча.'
        lang: rus
    condition: 'regex("Bashed Patch.*\.esp")'
  - &dirtyDoNotClean
    type: 'say'
    content:
      - str: 'Do not clean. "Dirty" edits are intentional and required for the mod to function.'
        lang: eng
      - str: 'Не очищать. "Грязные" правки оставлены специально и требуются для функционирования мода.'
        lang: rus
  - &skse1.6.5
    name: '..\skse_loader.exe'
    display: 'Skyrim Script Extender v1.6.5+'
    condition: 'version("..\skse_loader.exe", "0.1.6.5", <)'

plugins:
  - name: 'BBLuxurySuite.esm'
    msg: [ *dirtyDoNotClean ]
  - name: 'Convenient Horses.esp'
    msg: [ *dirtyDoNotClean ]
  - name: '72HoursRespawn.esp'
    msg: [ *useBP ]
  - name: 'Respawn\w{3,5}Days{0,1}\.esp'
    msg: [ *useBP ]
  - name: 'Skyrim 120 Day Respawn.esp'
    msg: [ *useBP ]
  - name: 'kuerteeDisableLightsFarFromActors.esp'
    req: [ *skse1.6.5 ]
  - name: 'CUYC_CleanUpYourCorpses.esp'
    req: [ *skse1.6.5 ]

Notice how in the example above, the common node has two different types of data structure in the same list (message and file structures). If this was done anywhere in the globals or plugins nodes LOOT would complain, because it expects a certain format, but because LOOT doesn't look at the common node, this is OK.

Dirty Edit Metadata

If a user posts dirty counts for a plugin that already has a dirty message for the same CRC, and the counts are different to what's in the masterlist, just replace the existing counts with what the user gave if they used the latest version of TES5Edit. If they didn't give the TES5Edit version number, only replace the existing counts if the new counts are higher (which generally indicates a newer version).

Intentional ITMs

A very tiny minority of dirty edits (and only ever ITMs) are intentional and should not be removed - this is for cases where a mod will not function correctly unless certain data have their vanilla values, so the mod includes a copy of the vanilla data to override anything that might change it.

Mod authors who don't have a good understanding of dirty edits will often claim that their edits are required - you must download the mod in question and see for yourself if any such claim is made.

Adding Bash Tags

Before adding a tag to a mod, it is recommended that you:

  1. Check the mod in TES4Edit or equivalent to see if it does actually require that tag.
  2. Think about the nature of the mod, is it designed so that it is OK if things get overriden, or will it malfunction if that occurs?
  3. Read the mod documentation and the mod description field in Wrye Bash to check whether the mod author has supplied any tags with it, or recommended any to be added.

That should ensure you have the correct information, so you can start to add the necessary tags. Use the Wrye Bash/Flash/Flash NV readme as a reference.

Translating Messages

If you add a message, there are two ways to go about getting it translated into the other languages LOOT supports:

Message Substitutions

LOOT has support for metadata message string substitutions, but does not retain the pre-substitution message string and substituted strings, so a metadata file written by LOOT will not retain subs keys, or any specifiers in message content strings. This information is provided in the unlikely event of LOOT writing to a metadata file that you have manually added substitutions to.