LOOT LOOT
Masterlist Editing

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

General Hints

Notepad++

If you're using Notepad++, you can set it to use spaces instead of tabs when you press the tab key on your keyboard, avoiding YAML parsing errors. To do this, go to Settings > Preferences > Languages > Tab Settings > yaml > Replace by space. As the masterlists use two-space indentation, a "Tab size" of 2 is preferable.

Another good piece of advice is to make use of the keyboard shortcut "Alt+0" to collapse the main nodes of the masterlists ("common", "plugins", etc), which will make navigating the masterlists easier. The keyboard shortcut "Alt+Shift+0" will then reverse this action.

Notepad++

Vim

If you're using Vim, you can add this line to your Vim config

autocmd FileType yaml setlocal tabstop=2 softtabstop=2 shiftwidth=2 expandtab

to make it use 2 spaces for YAML files. And using the following plugin

Plug 'pedrohdz/vim-yaml-folds'

will add folds for YAML. For more information, please read this article by Arthur Koziel.

Vim

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'
url: [ 'https://www.nexusmods.com/oblivion/mods/15256' ]
req:
  - name: 'example.esp'
    display: '[Example Mod](https://www.example.com)'
    condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", "15.0", ==)'
tag:
  - name: -Relations
    condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")'
msg:
  - type: say
    content:
      - lang: en
        text: 'This is an "Example".'
      - lang: bg
        text: 'Това е "Образец".'
      - lang: de
        text: 'Dies ist ein "Beispiel".'
{name: Oscuro's_Oblivion_Overhaul.esm, url: [ https://www.nexusmods.com/oblivion/mods/15256 ], req: [{ name: example.esp, display: '[Example Mod](https://www.example.com)', condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", "15.0", ==)' }], tag: [{ name: -Relations, condition: file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm") }], msg: [{ type: say, content: [{ lang: en, text: This is an "Example".}, { lang: bg, text: Това е "Образец".}, {lang: de, text: Dies ist ein "Beispiel".}]}] }

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 do 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 starfield, morrowind, oblivion, skyrim, skyrimse, skyrimvr, fallout3, falloutnv, fallout4, fallout4vr or enderal. <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:
  - &alreadyInX
    type: error
    content:
      - lang: en
        text: 'Delete. Already included in {0}.'
      - lang: bg
        text: 'За изтриване. Включена е в {0}.'
      - lang: da
        text: 'Slet. Allerede inkluderet i {0}.'
      - lang: de
        text: 'Löschen. Bereits in {0} enthalten.'
      - lang: es
        text: 'Borrar. Esta incluido en {0}.'
      - lang: fi
        text: 'Poista. {0} sisältää jo tämän.'
      - lang: it
        text: 'Cancella. Già incluso in {0}.'
      - lang: ja
        text: '削除してください。既に{0}に含まれています。'
      - lang: ko
        text: '삭제하십시오. 이미 {0}에 포함되어 있습니다.'
      - lang: pl
        text: 'Usuń. Już zawarte w {0}'
      - lang: pt_BR
        text: 'Apague. Já incluído em {0}'
      - lang: pt_PT
        text: 'Apagar. Já incluído em {0}.'
      - lang: ru
        text: 'Удалите. Уже включено в {0}.'
      - lang: sv
        text: 'Ta bort. Redan inkluderat i {0}.'
      - lang: zh_CN
        text: '删除。已包含在{0}中。'
  - &useBashTweakInstead
    type: say
    content:
      - lang: en
        text: 'A Bashed Patch tweak can be used instead of this plugin. {0}'
      - lang: bg
        text: 'Може да използвате кръпка на Bash вместо тази приставка. {0}'
      - lang: de
        text: 'Ein Bashed Patch Tweak kann anstelle dieses Plugins verwendet werden. {0}'
      - lang: it
        text: 'Puoi usare una Bashed Patch modificata invece di questo plugin. {0}'
      - lang: ja
        text: 'このプラグインの代わりに、Bashed Patch の調整機能を使用できます。{0}'
      - lang: ko
        text: '이 플러그인 대신 Bashed Patch의 트윅을 사용할 수 있습니다. {0}'
      - lang: pt_BR
        text: 'Uma tweak do Bashed Patch pode ser utilizada no lugar deste plugin. {0}'
      - lang: pt_PT
        text: 'Um Bashed Patch modificado pode ser utilizado em vez deste plugin. {0}'
      - lang: sv
        text: 'En Bashed Patch Tweak kan användas istället för det här pluginet. {0}'
      - lang: zh_CN
        text: '可以使用一个Bashed Patch来代替这个插件。{0}'
    subs: [ '' ]
    condition: 'file("Bashed Patch.*\.esp")'
  - &OBSEv21
    name: '../obse_1_2_416.dll'
    display: '[OBSE](https://obse.silverlock.org) v21+'
    condition: 'version("../obse_1_2_416.dll", "0.21.0.0", <)'

plugins:
  - name: 'AnvilBayExpansion.esp'
    url: [ 'https://www.nexusmods.com/oblivion/mods/10080' ]
    inc:
      - 'Better Cities ANVIL.esp'
      - 'Better Cities Full.esp'
      - 'Open Cities Reborn.esp'
    msg:
      - <<: *alreadyInX
        subs: [ 'Better Cities - Anvil' ]
        condition: 'active("Better Cities ANVIL.esp")'
      - <<: *alreadyInX
        subs: [ 'Better Cities - Full' ]
        condition: 'active("Better Cities Full.esp")'
  - name: 'Footstep Sound Fix.esp'
    url: [ 'https://www.nexusmods.com/oblivion/mods/10969' ]
    msg:
      - <<: *useBashTweakInstead
        subs: [ 'Tweak Actors -> Quiet Feet' ]
  - name: 'Horse Management.esp'
    url: [ 'https://www.nexusmods.com/oblivion/mods/46021' ]
    req: [ *OBSEv21 ]

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 xEdit (TES4Edit, SSEEdit, FO4Edit, etc). Also make sure that xEdit's QAC (Quick Auto Clean) feature was used to generate the cleaning reports.

Intentional ITMs

Sometimes a mod author is of the opinion that the ITMs in a plugin are "Intentional". Since this topic is not viewed in the same way by everyone, we have a few options to handle this situation. For one, if the plugin in question also has "Deleted References" or "Deleted Navmeshes", we should continue to include the xEdit cleaning report within our masterlists. If the plugin in question only includes "Intentional" ITMs, we normally would still feature the xEdit cleaning report in our masterlists, but, if the mod author of that plugin would prefer that those ITMs weren't cleaned because of their intentional nature, we can remove the cleaning report from the masterlist and add a "#doNotClean" comment to the plugin. We will, however, not advise our users to not clean those plugins; not reporting these "Intentional" ITMs is the most we will offer mod authors in this situation.

It is, however, always best to double check those plugins with the latest version of xEdit.

Adding Bash Tags

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

  1. Check the mod in xEdit 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 docs on Bash Tags 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:

For the correct languages codes, see our documentation as well as ISO 639-1 and ISO 3166.

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.