Difference between revisions of "Mod installation"

From OpenMW Wiki
Jump to navigation Jump to search
m (Tweak my tweak about ampersands)
(Noted that we moved to RTD)
 
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Morrowind mods (such as <samp>.esm</samp>/<samp>.esp</samp> plugins, texture replacers, mesh replacers, ...) can be installed and used just like in vanilla Morrowind. However, there is an interesting OpenMW-only feature that deserves explanation: ''multiple data folders''.
+
Our mod installation guide has moved to our official documentation on [https://openmw.readthedocs.io/en/latest/reference/modding/index.html ReadTheDocs]
 
{{Notice|float=right|width=25em|1=For a list of mods known to work (or to not work) with OpenMW, see: [[Mod status]].}}
 
{{Notice|float=right|width=25em|1=For a list of mods known to work (or to not work) with OpenMW, see: [[Mod status]].}}
 
==Multiple data folders==
 
 
OpenMW supports the use of multiple data folders. The first data folder is typically your Morrowind <code>Data Files</code> folder. Additional data folders can be added by editing <code>openmw.cfg</code> (see [[Paths]] for the location of this configuration file). This provides a very easy way to install and uninstall mods:
 
 
* To install the mod, create a data folder for the mod and add its path to <code>openmw.cfg</code>.
 
* To uninstall the mod, simply remove the folder from <code>openmw.cfg</code>.
 
 
The main advantage to this method is that mods coming with loose files are much easier to organize: if you had simply dumped such mods in your Morrowind <code>Data Files</code> folder, then file conflicts (e.g. the same mesh or texture file being overridden by multiple mods) are much more difficult to handle - files must be merged manually and uninstallation is extremely tedious.
 
 
When using multiple data folders, the ''priority'' of each mod can simply be changed by moving its <code>data=</code> line in  <code>openmw.cfg</code> to a different place. The <em>last</em> <code>data=</code> line has the highest priority (i.e. loads last, and may override material in earlier-loaded mods), and the first listed has the lowest priority.
 
[[category:Modding]]
 
 
===Detailed mod installation instructions===
 
* Your mod probably comes in some kind of archive, probably <samp>.zip</samp>, <samp>.rar</samp>, <samp>.7z</samp> or something along those lines. Unpack this archive into its own folder.
 
** First, ignore instructions in the mod description that say something like "extract the archive directly into your Morrowind 'Data Files' folder." You want to keep mods in their own folders, and not overwrite original game resources.
 
* Make sure the structure of the folder is correct. Some mod archives contain a single <code>Data Files</code> folder and some additional files, others put everything into where they are unpacked, still others put everything which belongs to the mod into a specially named folder and meta files (like readmes) into the folder where the mod is unpacked (plus a few have incorrectly created archives that start at the root level of the modder's hard drive). You need to normalize this:
 
** Put all ESPs into the top level of the folder in which you want to put the mod.
 
** Put all resource folders into the top level of your mod folder. The relevant folders are <code>BookArt</code>, <code>Fonts</code>, <code>Icons</code>, <code>Meshes</code>, <code>Music</code>, <code>Sound</code>, <code>Splash</code>, <code>Textures</code> and <code>Video</code>. Not every mod contains all of these folders (and actually most mods don't contain most or even any of them), but if they belong to the mod, they must be in its top level.
 
* Open your  <code>openmw.cfg</code> in your favorite text editor. The location of this file varies by operating system:
 
** Linux: <code>$HOME/.config/openmw/openmw.cfg</code>
 
** Windows: <code>C:\Users\<var>Username</var>\Documents\my games\openmw\openmw.cfg</code> (username will vary, as may drive and language)
 
** Mac: <code>/Users/<var>Username</var>/Library/Preferences/openmw/openmw.cfg</code> (username will vary, as may language)
 
* With your editor's search function, search for lines beginning with <code>data=</code> and go to the last one of these lines.
 
** If you didn't change the  <code>openmw.cfg</code> before, there should be only one such line.
 
** If you follow these instructions, all of these lines should end up in a single continuous block.
 
* Add a new line below the one you just sought out and make a new entry of the format <code>data="<var>/path/to/your/mod"</var></code>
 
** If your mod's folder is <code>~/MWMods/TamrielRebuilt</code> you add a line reading <code>data="~/MWMods/TamrielRebuilt"</code>
 
** <strong>Important:</strong> Libraries OpenMW depends on use ampersand (<code>&</code>) as an escape character. Therefore, this path cannot contain an individual ampersand character. If your path is something like <code>~/MWMods/Pirates & Parrots</code> either it must be changed (e.g. to <code>~/MWMods/Pirates and Parrots</code>), or you have to escape the <code>&</code> as <code>&&</code>, as in: <code>data="~/MWMods/Pirates && Parrots</code>. Other characters which may cause issues include the double quotation mark (<code>"</code>), which, while uncommon, is legal to use in paths in some operating systems. This can also be escaped with an ampersand: <code>~/MWMods/"Suspicious" Quotation Marks Mod</code> to <code>data="~/MWMods/&"Suspicious&" Quotation Marks Mod"</code>.
 
** Note that a trailing slash is not necessary.
 
** Note the double quotes around the path name. These are not optional in Windows!  Some users of Linux [https://forum.openmw.org/viewtopic.php?f=40&t=3936] and MacOS [https://forum.openmw.org/viewtopic.php?f=39&t=3939] report conflicting results (that quotes are required, that they must be left off, or that they don't matter). To be sure which will work on your system, add a very obvious mod (something you can see immediately and don't have to go look for) with quotes, open the game, and see if it worked.  Quotes are the <em>expected</em> behavior, and this inconsistency has been reported as a bug. The most common cause of quotes not working is trying to escape spaces and other characters in the path yourself. Use <code>data="~/MWMods/My Mod"</code>, not <code>data="~/MWMods/My\ Mod"</code>, or <code>data=~/MWMods/My\ Mod</code>.
 
** Do <em>not</em> add quotes around any mod filenames in the <code>content=</code> lines that follow the <code>data=</code> section. You don't need to manually edit anything in this later section.
 
* Save your  <code>openmw.cfg</code>.
 
 
===Load order of <samp>.esp</samp> files===
 
The following steps are only necessary if the mod relies on any <samp>.esp</samp> files. Simple texture/mesh/whatever replacers most often do not have any <samp>.esp</samp> files and in these cases the following steps are unnecessary. The readme of the mod often tells you whether <samp>.esp</samp> files are necessary.
 
* Open the OpenMW Launcher.
 
* Select a Current Content List, or (usually) accept the current one.
 
* Go to the "Data Files" tab.
 
* You'll now see a list of <samp>.esp</samp>/<samp>.esm</samp> files that OpenMW knows about. Seek out the <samp>.esp</samp> that belongs to your mod.
 
* Drag and drop the <samp>.esp</samp> to the desired load order position (lower in the list means later loading, thus higher priority).
 
** If a <samp>.esp</samp> has unsatisfied dependencies (because it is too far up in the load order or because the dependency is not installed or is not enabled in the list yet), a warning symbol will be shown to the left of its name.
 
* Activate it by turning on the checkbox to the left of the mod's entry.
 
** Activating a <samp>.esp</samp> that has one or more dependencies will activate the mod or mods on which it is dependent, if installed but not yet also activated.
 
** "Installed" in this sense means installed in the Current Content List's "Data Files" tab's list; OpenMW has no idea what you have laying around on your hard drive somewhere. This list is built from what you have added to <code>openmw.cfg</code>, plus what (if anything) you have installed the old way (see next section), plus what (if anything) you have created with OpenMW-CS, which saves to a subdirectory of [[Paths#OpenMW-CS mods|OpenWM's config folder]].
 
 
You now should be ready to start OpenMW with the newly installed mod.
 
 
To check whether your mods of choice work in OpenMW, see [[Mod status]].
 
 
== The old, hazardous way ==
 
If you only want one or two simple mods, or just want to quickly test one, the original way to use mods may be more expedient:
 
* Extract the mod archive to its own folder. <em>Ignore</em> instructions in the mod description or readme that say something like "extract the archive directly into your Morrowind 'Data Files' folder." You want to install this carefully, and not overwrite original game resources.
 
* Put the <samp>.esp</samp> file in your Morrowind <code>Data Files</code> folder.
 
* Put any supplied resources in the appropriate <code>Data Files</code> subdirectories:
 
** If the mod provides something like a <code>Textures/<var>Modname</var></code> directory, put <code><var>Modname</var></code> in the Morrowind <code>Data Files/Textures</code> folder; the mod is expecting them to remain inside that <code><var>Modname</var></code> wrapper.
 
** If the mod provides some files arranged like <code>Sound/Vo/n/f/<var>Modname_blah_blah1234</var>.mp3</code>, then the <code><var>Modname_blah_blah1234</var>.mp3</code> goes in Morrowind's <code>Data Files/Sound/Vo/n/f</code> folder.
 
 
If it wants you to overwrite any existing resources, you should probably be using the new OpenMW way to use mods, instead.  If you continue, <em>you must back up the original files first</em>, or you will not be able to uninstall the mod, other than by starting with a vanilla copy of Morrowind.  Another approach is copy Morrowind entirely, install the destructive mod into the copy, and playtest the copy.
 
 
Rarely, a mod may require you to adjust something in <code>Morrowind.conf</code> (not to be confused with <code>openmw.cfg</code>). <em>Make a back-up copy of both of these configuration files first.</em> You then need to re-run OpenMW's configuration import process (this generates a new "Current Content List" and will take settings from the modified <code>Morrowind.conf</code> and write a new <code>openmw.cfg</code> file. If you have made changes directly to other sections of <code>openmw.cfg</code>, you'll need to copy that material back into the new file from the backup you made. If the <code>Morrowind.conf</code> change needed by the mod is simple and obvious, you can simply manually add it to both config files.
 
 
== Leveled list merging ==
 
Sometimes, a mod's readme will say that a tool for merging leveled lists (e.g. Wrye Mash and various other Windows programs) must be used.  You cannot use such a mod safely, without work, as OpenMW has no leveled-list merging feature.  If you're hell-bent on trying it, there are some experimental approaches to merging leveled lists for OpenMW.
 
 
See the thread [https://www.reddit.com/r/Morrowind/comments/53bskz/if_anyone_wants_to_discuss_leveled_list_merging_i/ here] for how to attempt merging with John Moonsugar's Perl-based tool <samp>[http://forums.bethsoft.com/topic/1606866-relz-tes3cmd-v040-pre-release-1-preview-for-testing/ tes3cmd]</samp> v.0.40pre1 and later. This appears to be tested, but is complicated to use, and is not directly compatible with OpenMW's modern mod installation method of using multiple data directories. (A workaround for that problem – using symlinks in Linux and MacOS – has been discussed [https://forum.openmw.org/viewtopic.php?f=3&t=3852 here]. MacOS aliases do not work; Windows shortcuts are not tested, but probably do not either. However, [http://www.windows7home.net/how-to-create-symbolic-link-in-windows-7/ Windows supports symbolic links at the command line], though these have not been tested for this purpose, either.)
 
 
There is also an OpenMW-specific tool in development, J. Melesky's Python3-based [https://github.com/jmelesky/omwllf <samp>omwllf</samp>] (OpenMW Leveled List Fixer). It is in an alpha state and has no documentation.
 
  
 
[[Category:Modding]]
 
[[Category:Modding]]
 
[[Category:Installation]]
 
[[Category:Installation]]

Latest revision as of 03:01, 20 July 2018

Our mod installation guide has moved to our official documentation on ReadTheDocs

For a list of mods known to work (or to not work) with OpenMW, see: Mod status.