@ -8,9 +8,19 @@ Or a beginner's guide to writing docs without having to deal with more techie st
Intro
=====
The premise of this guide is that you would like to help out the OpenMW project beyond play-testing for bugs and such, buuuuut you're like me and don't really know how to code. This has the rather pesky side effect of you not really knowing about all the tools like GitHub and such. While many of these tools are super handy and great to know how to use, not everyone has the actual need and desire to learn the ins and outs of them. Since we would like as much help fleshing out the user documentation as possible, I wrote this guide to lower the barrier of entry into contributing to the project.
*However*, as much as I will try to guide you through all the tedious setup and day-to-day stuff, you will eventually have to learn to write using ReST (reStructuredText) formatting. Since you're probably like me when I started helping and don't know wtf ReST is, never fear. It's an incredibly simple language that is easy to read in plain text form that can then be converted automatically into different types of documents like PDFs and html for webpages.
The premise of this guide is that you would like to help out the OpenMW project beyond play-testing for bugs and such,
*buuuuut* you're like me and don't really know how to code.
This has the rather pesky side effect of you not really knowing about all the tools like GitHub and such.
While many of these tools are super handy and great to know how to use,
not everyone has the actual need and desire to learn the ins and outs of them.
Since we would like as much help fleshing out the user documentation as possible,
I wrote this guide to lower the barrier of entry into contributing to the project.
*However*, as much as I will try to guide you through all the tedious setup and day-to-day stuff,
you will eventually have to learn to write using ReST (reStructuredText) formatting.
Since you're probably like me when I started helping and don't know wtf ReST is, never fear.
It's an incredibly simple language that is easy to read in plain text form that can then be converted automatically
into different types of documents like PDFs and html for webpages.
Baby Steps
==========
@ -25,9 +35,11 @@ Choose Repository and Files in the menu on the left, then docs and source in the
Don’t overlook the tutorial-style-guide.txt there for some tips to get you started.
Open whichever file you want to tackle – probably within the manuals or reference directories.
There’s also a dropdown box to the right of edit, at the top of the left menu, which offers options such as new file or directory, or upload file, with “+” to close that dropdown box.
There’s also a dropdown box to the right of edit, at the top of the left menu,
which offers options such as new file or directory, or upload file, with “+” to close that dropdown box.
Click on "Edit" towards top right which will reveal the underlying version, rather than the version displayed to normal reaaders. Use "Write" and "Preview" to switch between the two views.
Click on "Edit" towards top right which will reveal the underlying version,
rather than the version displayed to normal readers. Use "Write" and "Preview" to switch between the two views.
When you have made the appropriate changes, and checked them in Preview mode, click the Green "Commit changes" button at the bottom.
This should add a branch, with a default name such as patch-1, to your own repository, and add a Merge Request to the main OpenMW Project.
@ -48,13 +60,24 @@ So here's what you're gonna be learning how to set up:
GitHub
======
GitHub is the website the OpenMW project is hosted on. It utilizes Git, which is a version control system, meaning it helps us all collaborate on the project without interfering with each others' work. The commands are a little annoying because there is a certain amount of undescriptive jargon, but for the most part, what you need to know is very simple and I'll walk you through it. There are three main parts that you should know:
GitHub is the website the OpenMW project is hosted on. It utilizes Git, which is a version control system,
meaning it helps us all collaborate on the project without interfering with each others' work.
The commands are a little annoying because there is a certain amount of undescriptive jargon,
but for the most part, what you need to know is very simple and I'll walk you through it.
There are three main parts that you should know:
1. The OpenMW repository
2. Your online repository
3. Your local repository
The master OpenMW respository is where all of our work comes together and where the most current version of the source code resides. A repository, also called repo, is a directory or the main folder that holds a project. You will need to create your own account on GitHub so you can *fork* the OpenMW repository. Forking is just when you clone a project into a repository on your own account so you can make changes however you like without accidentally messing up the original project. Now, you could add and edit files on GitHub.com directly through your online repository, however it's much easier to work on them on your own computer in your local repository. Local just refers to the fact that it's physically stored on your computer's hard drive. Here are the easy steps for doing all this:
The master OpenMW repository is where all of our work comes together and where the most current version of the source code resides.
A repository, also called repo, is a directory or the main folder that holds a project.
You will need to create your own account on GitHub so you can *fork* the OpenMW repository.
Forking is just when you clone a project into a repository on your own account so you can make changes however you like
without accidentally messing up the original project.
Now, you could add and edit files on GitHub.com directly through your online repository,
however it's much easier to work on them on your own computer in your local repository.
Local just refers to the fact that it's physically stored on your computer's hard drive. Here are the easy steps for doing all this:
1. Go to GitHub.com and sign up for a free account.
2. Navigate to the master OpenMW repo at: https://github.com/OpenMW/openmw
@ -67,7 +90,11 @@ If you want more info I recommend reading this guide: https://readwrite.com/2013
PyCharm
=======
PyCharm is what's known as an IDE, which stands for integrated development environment. All this means is that it's for writing code and has a bunch of built-in features that make it easier to do so. In this case, PyCharm is made for the language Python, which is what Sphinx is written in. We won't actually be touching any of the Python, but some of the built-in features are extremely useful. Let's start setting it up:
PyCharm is what's known as an IDE, which stands for integrated development environment.
All this means is that it's for writing code and has a bunch of built-in features that make it easier to do so.
In this case, PyCharm is made for the language Python, which is what Sphinx is written in.
We won't actually be touching any of the Python, but some of the built-in features are extremely useful.
Let's start setting it up:
1. Go to https://www.jetbrains.com/pycharm/download/
2. Select your OS, then download the free Community version.
@ -81,31 +108,61 @@ PyCharm is what's known as an IDE, which stands for integrated development envir
10. Back in the welcome window, click "Check out from version control" and select GitHub.
.. note::
After this step, it should log in to your GitHub. If not, you probably messed up the Token creation. If you're on Mac, you may come across and error complaining about XCode and admin priviledges. If this happens, open Terminal and type: ``sudo xcodebuild -license`` Read through the license and agree. This should fix the error and allow you to log in.
After this step, it should log in to your GitHub. If not, you probably messed up the Token creation.
If you're on Mac, you may come across and error complaining about XCode and admin priviledges. If this happens,
open Terminal and type: ``sudo xcodebuild -license`` Read through the license and agree.
This should fix the error and allow you to log in.
11. In Git Repository URL, select your OpenMW repository and click Clone
Congrats! You now have the OpenMW sourcecode on your computer and you can begin making changes and contributing. If you're reading this guide though, you probably won't have any idea how to do that, so let's go through setting up Sphinx, then I'll go through it.
Congrats! You now have the OpenMW source code on your computer and you can begin making changes and contributing.
If you're reading this guide though, you probably won't have any idea how to do that,
so let's go through setting up Sphinx, then I'll go through it.
Sphinx
======
So far I've mentioned ReST (reStructuredText) a couple times, but what is it, and what is Sphinx? The most basic explanation is that ReST is the markup language (like HTML is the markup language for webpages) and Sphinx is the program that goes through and builds the actual document so you can read it in a more visually pleasing way. For a much more detailed explanation, I recommend: https://coderwall.com/p/vemncg/what-is-the-difference-rest-docutils-sphinx-readthedocs
So far I've mentioned ReST (reStructuredText) a couple times, but what is it, and what is Sphinx?
The most basic explanation is that ReST is the markup language (like HTML is the markup language for webpages)
and Sphinx is the program that goes through and builds the actual document so you can read it in a more visually pleasing way.
For a much more detailed explanation, I recommend: https://coderwall.com/p/vemncg/what-is-the-difference-rest-docutils-sphinx-readthedocs
This will be the most technical section as we have to use the command prompt or terminal to install Python and Sphinx. I had intended to give you a universal explanation on how to install both, but it would drastically increase the length of this guide. The tutorial on the Sphinx website is really just going to be better than anything I write here, so please refer to their guide here: https://www.sphinx-doc.org/en/stable/install.html
This will be the most technical section as we have to use the command prompt or terminal to install Python and Sphinx.
I had intended to give you a universal explanation on how to install both,
but it would drastically increase the length of this guide.
The tutorial on the Sphinx website is really just going to be better than anything I write here,
so please refer to their guide here: https://www.sphinx-doc.org/en/stable/install.html
Hopefully you now have Python and Sphinx installed. ...
Now you should have everything installed and running so you can collaborate on documentation properly. Let's go through a few more brief GitHub basics. There are really only 4 things you will be using regularly:
Now you should have everything installed and running so you can collaborate on documentation properly.
Let's go through a few more brief GitHub basics. There are really only 4 things you will be using regularly:
1. Rebase
2. Commit
3. Push
4. Pull request (PR)
Rebasing means you're taking all changes in one branch and applying them directly on top of another branch. This is slightly different than a merge which compares the two branches and makes another state combining the two. The difference is slight, but we use the rebase because it keeps the history cleaner. You will always rebase your local repository from the OpenMW master repository. This ensures you have all the most up to date changes before working on stuff so there is less chance of conflicts that need to be resolved when your branch is merged back into the master. A commit is basically just stating which files you want to mark as ready to be "pushed" to your online repository. A push is just copying those "committed" changes to your online repo. (Commit and push can be combined in one step in PyCharm, so yay) Once you've pushed all the changes you need to contribute something to the project, you will then submit a pull request, so called because you are *requesting* that the project maintainers "pull" and merge the changes you've made into the project master repository. One of the project maintainers will probably ask you to make some corrections or clarifications. Go back and repeat this process to make those changes, and repeat until they're good enough to get merged.
So to go over all that again. You rebase *every* time you start working on something to ensure you're working on the most updated version (I do literally every time I open PyCharm). Then make your edits. You commit and push from your local repo to your online repo. Then you submit a pull request and people can review your changes before they get merged into the project master! Or in list form:
Rebasing means you're taking all changes in one branch and applying them directly on top of another branch.
This is slightly different than a merge which compares the two branches and makes another state combining the two.
The difference is slight, but we use the rebase because it keeps the history cleaner.
You will always rebase your local repository from the OpenMW master repository.
This ensures you have all the most up to date changes before working on stuff so there is less chance of conflicts that
need to be resolved when your branch is merged back into the master.
A commit is basically just stating which files you want to mark as ready to be "pushed" to your online repository.
A push is just copying those "committed" changes to your online repo.
(Commit and push can be combined in one step in PyCharm, so yay)
Once you've pushed all the changes you need to contribute something to the project, you will then submit a pull request,
so called because you are *requesting* that the project maintainers "pull"
and merge the changes you've made into the project master repository. One of the project maintainers will probably ask
you to make some corrections or clarifications. Go back and repeat this process to make those changes,
and repeat until they're good enough to get merged.
So to go over all that again. You rebase *every* time you start working on something to ensure you're working on the most
updated version (I do literally every time I open PyCharm). Then make your edits.
You commit and push from your local repo to your online repo.
Then you submit a pull request and people can review your changes before they get merged into the project master!
Or in list form:
1. Rebase local repo from OpenMW master
2. Make your edits
@ -116,7 +173,9 @@ So to go over all that again. You rebase *every* time you start working on somet
Preview Documentation
*********************
You will probably find it helpful to be able to preview any documentation you've made. I often forget necessary syntax and this allows me to double check my work before submitting a PR. Luckily, PyCharm has a handy built-in feature that allows you to easily generate the docs.
You will probably find it helpful to be able to preview any documentation you've made.
I often forget necessary syntax and this allows me to double check my work before submitting a PR.
Luckily, PyCharm has a handy built-in feature that allows you to easily generate the docs.
1. In the top right corner of the PyCharm window, select the drop-down menu and select `Edit Configurations`.
2. In the `Run/Debug Configurations` dialogue, click the green plus button in the top left and select `Python Docs > Sphinx Tasks`.
@ -127,16 +186,21 @@ You will probably find it helpful to be able to preview any documentation you've
:Output: <wherever you want the build files to be>
4. Click `Apply`, then `OK`.
Now in order to generate the documentation on your computer to preview them, just click the green play button in the top right, next to the drop down menu with the name you chose above selected. Sphinx will run and you can view the resulting documentation wherever you chose Output to be, above. The window that Sphinx runs in will also show any errors that occur during the build in red, which should help you find typos and missing/incorrect syntax.
Now in order to generate the documentation on your computer to preview them,
just click the green play button in the top right, next to the drop down menu with the name you chose above selected.
Sphinx will run and you can view the resulting documentation wherever you chose Output to be, above.
The window that Sphinx runs in will also show any errors that occur during the build in red,
which should help you find typos and missing/incorrect syntax.
GitLab integration in PyCharm
=============================
As most of the hosting of OpenMW has moved to Gitlab, we should encourage the use of GitLab, though GitHub will continue to be supported.
As most of the hosting of OpenMW has moved to Gitlab, we should encourage the use of GitLab,
though GitHub will continue to be supported.
Add a couple of plugins to Pycharm - see general instructions at https://www.jetbrains.com/help/pycharm/installing-updating-and-uninstalling-repository-plugins.html
Add a couple of plugins to PyCharm - see general instructions at https://www.jetbrains.com/help/pycharm/installing-updating-and-uninstalling-repository-plugins.html
OpenMW is designed to be able to use all the normal Morrowind mod files such as ESM/ESP plugins, texture replacers, mesh replacers, etc.
OpenMW is designed to be able to use all the normal Morrowind mod files such as ESM/ESP plugins, texture replacers,
mesh replacers, etc.
..warning::
All external programs and libraries that depend on ``morrowind.exe`` cannot function with OpenMW. This means you should assume mods dependent on Morrowind Graphics Extender, Morrowind Code Patch, Morrowind Script Extender, etc, will *not* work correctly, nor will the tools themselves.
All external programs and libraries that depend on ``morrowind.exe`` cannot function with OpenMW.
This means you should assume mods dependent on Morrowind Graphics Extender, Morrowind Code Patch,
Morrowind Script Extender, etc, will *not* work correctly, nor will the tools themselves.
Multiple Data Folders
---------------------
The largest difference between OpenMW and Morrowind in terms of data structure is OpenMW's support of multiple data folders. This has many advantages, especially when it comes to uninstalling mods and preventing unintentional overwrites of files.
The largest difference between OpenMW and Morrowind in terms of data structure is OpenMW's support of multiple data folders.
This has many advantages, especially when it comes to uninstalling mods and preventing unintentional overwrites of files.
..warning::
Most mods can still be installed into the root OpenMW data folder, but this is not recommended.
@ -34,25 +38,33 @@ To uninstall these mods simply delete that mod's respective ``data=`` entry.
The mods are loaded in the order of these entries, with the top being overwritten by mods added towards the bottom.
..note::
Mods that depend on ESM/ESP plugins can be rearranged within the OpenMW Launcher, but mesh/texture replacer mods can only be reordered by moving their ``data=`` entry.
Mods that depend on ESM/ESP plugins can be rearranged within the OpenMW Launcher,
but mesh/texture replacer mods can only be reordered by moving their ``data=`` entry.
OpenMW Launcher
---------------
The launcher included with OpenMW is similar to the original Morrowind Launcher. Go to the Data Files tab to enable and disable plugins. You can also drag list items to modify the load order. Content lists can be created at the bottom by clicking the New Content List button, creating a list name, then setting up a new modlist. This is helpful for different player profiles and testing out different load orders.
The launcher included with OpenMW is similar to the original Morrowind Launcher.
Go to the Data Files tab to enable and disable plugins. You can also drag list items to modify the load order.
Content lists can be created at the bottom by clicking the New Content List button, creating a list name,
then setting up a new modlist. This is helpful for different player profiles and testing out different load orders.
.. TODO use a substitution image for the New Content List button.
Settings.cfg
------------
The ``settings.cfg`` file is essentially the same as the INI files for Morrowind. It is located in the same directory as ``openmw.cfg``. This is where many video, audio, GUI, input, etc. settings can be modified. Some are available in-game, but many are only available in this configuration file. Please see https://wiki.openmw.org/index.php?title=Settings for the complete listing.
The ``settings.cfg`` file is essentially the same as the INI files for Morrowind.
It is located in the same directory as ``openmw.cfg``. This is where many video, audio, GUI, input, etc.
settings can be modified. Some are available in-game, but many are only available in this configuration file.
Please see https://wiki.openmw.org/index.php?title=Settings for the complete listing.
.. TODO Create a proper ReST document tree for all the settings rather than Wiki.
Open Source Resources Support
-----------------------------
While OpenMW supports all of the original files that Morrowind supported, we've expanded support to many open source file formats. These are summarized below:
While OpenMW supports all of the original files that Morrowind supported,
we've expanded support to many open source file formats. These are summarized below:
<this will be a table of the type of file, the morrowind supported file, and the OpenMW supported file formats>
Morrowind uses a custom ``.fnt`` file format. It is not compatible with the Windows Font File ``.fnt`` format, nor compatible with ``.fnt`` formats from any other Bethesda games. To our knowledge, the format is undocumented and no tools for viewing or editing these fonts exist.
Morrowind uses a custom ``.fnt`` file format. It is not compatible with the Windows Font File ``.fnt`` format,
nor compatible with ``.fnt`` formats from any other Bethesda games. To our knowledge,
the format is undocumented and no tools for viewing or editing these fonts exist.
OpenMW can load this format and convert it on the fly into something usable (see font loader `source code <https://github.com/OpenMW/openmw/blob/master/components/fontloader/fontloader.cpp#L210>`_). In OpenMW 0.32, an --export-fonts command line option was added to write the converted font (a PNG image and an XML file describing the position of each glyph in the image) to the current directory.
OpenMW can load this format and convert it on the fly into something usable
(see font loader `source code <https://github.com/OpenMW/openmw/blob/master/components/fontloader/fontloader.cpp#L210>`_).
In OpenMW 0.32, an --export-fonts command line option was added to write the converted font
(a PNG image and an XML file describing the position of each glyph in the image) to the current directory.
TrueType fonts
--------------
Unlike vanilla Morrowind, OpenMW directly supports TrueType (``.ttf``) fonts. This is the recommended way to create new fonts.
Morrowind ``.fnt`` files are essentially a bitmap font, but using them is discouraged because of no Unicode support. MyGUI has its own format for bitmap fonts. An example can be seen by using the --export-fonts command line option (see above), which converts Morrowind ``.fnt`` to a MyGUI bitmap font. This is the recommended format to use if you wish to edit Morrowind's bitmap font or create a new bitmap font.
Morrowind ``.fnt`` files are essentially a bitmap font, but using them is discouraged because of no Unicode support.
MyGUI has its own format for bitmap fonts. An example can be seen by using the --export-fonts command line option (see above),
which converts Morrowind ``.fnt`` to a MyGUI bitmap font.
This is the recommended format to use if you wish to edit Morrowind's bitmap font or create a new bitmap font.
OpenMW is a complete game engine built to be content agnostic. The majority of this guide is applicable to any non-Morrowind project using its engine. That being said, it was designed with the extensive modding community of Morrowind in mind. Therefore, if you are already familiar with modding in Morrowind, you will likely be able to start modding in OpenMW with little to no instruction. We do recommend you at least refer to :doc:`differences` to find out about what's different between OpenMW and the original Morrowind engine. For everyone else, or just a good refresher, read on!
OpenMW is a complete game engine built to be content agnostic.
The majority of this guide is applicable to any non-Morrowind project using its engine.
That being said, it was designed with the extensive modding community of Morrowind in mind.
Therefore, if you are already familiar with modding in Morrowind,
you will likely be able to start modding in OpenMW with little to no instruction.
We do recommend you at least refer to :doc:`differences` to find out about what's different between OpenMW and the
original Morrowind engine. For everyone else, or just a good refresher, read on!
#. If your mod contains resources in a ``.bsa`` file, go to near the top of the file, locate the entries like ''fallback-archive=Morrowind.bsa'' and create a new line underneath and type: ``fallback-archive=<name of your bsa>.bsa''``.
..note::
Some text editors, such as TextEdit on Mac, will autocorrect your double quotes to typographical "curly" quotes instead of leaving them as the proper neutral vertical quotes ``""``.
Some text editors, such as TextEdit on Mac, will auto-correct your double quotes to typographical "curly"
quotes instead of leaving them as the proper neutral vertical quotes ``""``.
#. Save your ``openmw.cfg`` file.
You have now installed your mod. Any simple replacer mods that only contain resource files such as meshes or textures will now automatically be loaded in the order of their ``data=*`` entry. This is important to note because replacer mods that replace the same resource will overwrite previous ones as you go down the list.
You have now installed your mod. Any simple replacer mods that only contain resource files such as meshes or
textures will now automatically be loaded in the order of their ``data=*`` entry.
This is important to note because replacer mods that replace the same resource will overwrite previous ones as you go down the list.
Enable
------
Any mods that have plugin files must be enabled to work. Master game files and plugin files can only be enabled if they have been properly installed within a *data folder* as described above.
Any mods that have plugin files must be enabled to work.
Master game files and plugin files can only be enabled if they have been properly installed within a *data folder* as described above.
This setting determines whether the crosshair or reticle is displayed. Enabling the crosshair provides more immediate feedback about which object is currently the focus of actions.
This setting determines whether the crosshair or reticle is displayed.
Enabling the crosshair provides more immediate feedback about which object is currently the focus of actions.
Some players perceive that disabling the crosshair provides a more immersive experience.
Another common use is to disable the crosshair for screen shots.
This setting determines the number of exterior cells adjacent to the character that will be loaded for rendering.
..Warning::
Values greater than 1 will significantly affect the frame rate and loading times. This setting is mainly intended for making screenshots of scenic vistas and not for real-time gameplay. Loading more cells can break certain scripts or quests in the game that expect cells to not be loaded until the player is there. These limitations will be addressed in a future version with a separate technique for rendering distant cells.
Values greater than 1 will significantly affect the frame rate and loading times.
This setting is mainly intended for making screenshots of scenic vistas and not for real-time gameplay.
Loading more cells can break certain scripts or quests in the game that expect cells to not be loaded until the player is there.
These limitations will be addressed in a future version with a separate technique for rendering distant cells.
This setting interacts with viewing distance and field of view settings.
@ -163,11 +166,13 @@ prediction time
:Range:>=0
:Default:1
The amount of time (in seconds) in the future to predict the player position for. This predicted position is used to preload any cells and/or distant terrain required at that position.
The amount of time (in seconds) in the future to predict the player position for.
This predicted position is used to preload any cells and/or distant terrain required at that position.
This setting will only have an effect if 'preload enabled' is set or the 'distant terrain' in the Terrain section is set.
Increasing this setting from its default may help if your computer/hard disk is too slow to preload in time and you see loading screens and/or lag spikes.
Increasing this setting from its default may help if your computer/hard disk is too slow to preload in time and you see
loading screens and/or lag spikes.
cache expiry delay
------------------
@ -185,7 +190,10 @@ target framerate
:Range:>0
:Default:60
Affects the time to be set aside each frame for graphics preloading operations. The game will distribute the preloading over several frames so as to not go under the specified framerate. For best results, set this value to the monitor's refresh rate. If you still experience stutters on turning around, you can try a lower value, although the framerate during loading will suffer a bit in that case.
Affects the time to be set aside each frame for graphics preloading operations.
The game will distribute the preloading over several frames so as to not go under the specified framerate.
For best results, set this value to the monitor's refresh rate. If you still experience stutters on turning around,
you can try a lower value, although the framerate during loading will suffer a bit in that case.
pointers cache size
-------------------
@ -194,4 +202,6 @@ pointers cache size
:Range:>0
:Default:40
The count of object pointers that will be saved for a faster search by object ID. This is a temporary setting that can be used to mitigate scripting performance issues with certain game files. If your profiler (press F3 twice) displays a large overhead for the Scripting section, try increasing this setting.
The count of object pointers that will be saved for a faster search by object ID.
This is a temporary setting that can be used to mitigate scripting performance issues with certain game files.
If your profiler (press F3 twice) displays a large overhead for the Scripting section, try increasing this setting.
Enable visual clues for items owned by NPCs when the crosshair is on the object.
If the setting is 0, no clues are provided which is the default Morrowind behavior.
If the setting is 0, no clues are provided which is the default Morrowind behaviour.
If the setting is 1, the background of the tool tip for the object is highlighted
in the color specified by the color background owned setting in the GUI Settings Section.
If the setting is 2, the crosshair is the color of the color crosshair owned setting in the GUI Settings section.
If the setting is 3, both the tool tip background and the crosshair are colored.
in the colour specified by the colour background owned setting in the GUI Settings Section.
If the setting is 2, the crosshair is the colour of the colour crosshair owned setting in the GUI Settings section.
If the setting is 3, both the tool tip background and the crosshair are coloured.
The crosshair is not visible if crosshair is false.
This setting can be configured in Advanced tab of the launcher.
@ -71,12 +71,14 @@ can loot during death animation
:Range:True/False
:Default:True
If this setting is true, the player is allowed to loot actors (e.g. summoned creatures) during death animation, if they are not in combat.
However disposing corpses during death animation is not recommended - death counter may not be incremented, and this behaviour can break quests.
If this setting is true, the player is allowed to loot actors (e.g. summoned creatures) during death animation,
if they are not in combat. However disposing corpses during death animation is not recommended -
death counter may not be incremented, and this behaviour can break quests.
This is how Morrowind behaves.
If this setting is false, player has to wait until end of death animation in all cases.
This case is more safe, but makes using of summoned creatures exploit (looting summoned Dremoras and Golden Saints for expensive weapons) a lot harder.
This case is more safe, but makes using of summoned creatures exploit
(looting summoned Dremoras and Golden Saints for expensive weapons) a lot harder.
Conflicts with mannequin mods, which use SkipAnim to prevent end of death animation.
This setting can be toggled in Advanced tab of the launcher.
@ -179,10 +181,11 @@ use additional anim sources
:Range:True/False
:Default:False
Allow to load additional animation sources when enabled.
For example, if the main animation mesh has name Meshes/x.nif, an engine will load all KF-files from Animations/x folder and its child folders.
Can be useful if you want to use several animation replacers without merging them.
Attention: animations from AnimKit have own format and are not supposed to be directly loaded in-game!
Allow the engine to load additional animation sources when enabled.
For example, if the main animation mesh has name Meshes/x.nif,
the engine will load all KF-files from Animations/x folder and its child folders.
This can be useful if you want to use several animation replacers without merging them.
Attention: animations from AnimKit have their own format and are not supposed to be directly loaded in-game!
This setting can only be configured by editing the settings configuration file.
barter disposition change is permanent
@ -192,7 +195,8 @@ barter disposition change is permanent
:Range:True/False
:Default:False
If this setting is true, disposition change of merchants caused by trading will be permanent and won't be discarded upon exiting dialogue with them.
This imitates the option Morrowind Code Patch offers.
If this setting is true,
disposition change of merchants caused by trading will be permanent and won't be discarded upon exiting dialogue with them.
This imitates the option that Morrowind Code Patch offers.
This setting can be toggled in Advanced tab of the launcher.
If this value is true, the map window will display the world map, otherwise the local map. The setting updates automatically when pressing the local/world map switch button on the map window.
If this value is true, the map window will display the world map, otherwise the local map.
The setting updates automatically when pressing the local/world map switch button on the map window.
global map cell size
--------------------
@ -110,4 +111,6 @@ local map cell distance
:Range:>= 1
:Default:1
Similar to "exterior cell load distance" in the Cells section, controls how many cells are rendered on the local map. Values higher than the default may result in longer loading times. Please note that only loaded cells can be rendered, so this setting must be lower or equal to "exterior cell load distance" to work properly.
Similar to "exterior cell load distance" in the Cells section, controls how many cells are rendered on the local map.
Values higher than the default may result in longer loading times. Please note that only loaded cells can be rendered,
so this setting must be lower or equal to "exterior cell load distance" to work properly.
This setting determines whether the amount of the time the player has spent playing will be displayed
for each saved game in the Load menu. Currently, the counter includes time spent in menus, including the pause menu, but does not include time spent with the game window minimized.
for each saved game in the Load menu. Currently, the counter includes time spent in menus, including the pause menu,
but does not include time spent with the game window minimized.
This setting can only be configured by editing the settings configuration file.
@ -40,6 +41,8 @@ max quicksaves
:Range:>0
:Default:1
This setting determines how many quicksave and autosave slots you can have at a time. If greater than 1, quicksaves will be sequentially created each time you quicksave. Once the maximum number of quicksaves has been reached, the oldest quicksave will be recycled the next time you perform a quicksave.
This setting determines how many quicksave and autosave slots you can have at a time. If greater than 1,
quicksaves will be sequentially created each time you quicksave. Once the maximum number of quicksaves has been reached,
the oldest quicksave will be recycled the next time you perform a quicksave.
This setting can only be configured by editing the settings configuration file.
@ -12,7 +12,8 @@ Controls whether the engine will use paging and LOD algorithms to load the terra
Otherwise, only the terrain of the surrounding cells is loaded.
..note::
When enabling distant terrain, make sure the 'viewing distance' in the camera section is set to a larger value so that you can actually see the additional terrain.
When enabling distant terrain, make sure the 'viewing distance' in the camera section is set to a larger value so
that you can actually see the additional terrain.
To avoid frame drops as the player moves around, nearby terrain pages are always preloaded in the background,
regardless of the preloading settings in the 'Cells' section,
@ -20,29 +20,43 @@ General introduction to normal map conversion
:Authors:Joakim (Lysol) Berg
:Updated:2016-11-11
This page has general information and tutorials on how normal mapping works in OpenMW and how you can make mods using the old fake normal mapping technique (such as `Netch Bump mapped`_ and `Hlaalu Bump mapped`_, and maybe the most (in)famous one to give shiny rocks in OpenMW, the mod `On the Rocks`_!, featured in MGSO and Morrowind Rebirth) work in OpenMW.
This page has general information and tutorials on how normal mapping works in OpenMW and how you can make mods using
the old fake normal mapping technique (such as `Netch Bump mapped`_ and `Hlaalu Bump mapped`_, and maybe the most
(in)famous one to give shiny rocks in OpenMW, the mod `On the Rocks`_!, featured in MGSO and Morrowind Rebirth) work in OpenMW.
*Note:* The conversion made in the `Converting Apel's Various Things - Sacks`_-part of this tutorial require the use of the application NifSkope_.
*Another note:* I will use the terms bump mapping and normal mapping simultaneously. Normal mapping is one form of bump mapping. In other words, normal mapping is bump mapping, but bump mapping isn't necessarily normal mapping. There are several techniques for bump mapping, and normal mapping is the most common one today.
*Another note:* I will use the terms bump mapping and normal mapping simultaneously.
Normal mapping is one form of bump mapping. In other words, normal mapping is bump mapping,
but bump mapping isn't necessarily normal mapping.
There are several techniques for bump mapping, and normal mapping is the most common one today.
So let's get on with it.
Normal Mapping in OpenMW
************************
Normal mapping in OpenMW works in a very simple way: The engine just looks for a texture with a *_n.dds* suffix, and you're done.
Normal mapping in OpenMW works in a very simple way: The engine just looks for a texture with a *_n.dds* suffix,
and you're done.
So to expand on this a bit, let's take a look at how a model seeks for textures.
Let us assume we have the model *example.nif*. In this model file, there should be a tag (NiSourceTexture) that states what texture it should use and where to find it. Typically, it will point to something like *exampletexture_01.dds*. This texture is supposed to be located directly in the Textures folder since it does not state anything else. If the model is a custom made one, modders tend to group their textures in separate folders, just to easily keep track of them. It might be something like *./Textures/moddername/exampletexture_02.dds*.
Let us assume we have the model *example.nif*. In this model file,
there should be a tag (NiSourceTexture) that states what texture it should use and where to find it. Typically,
it will point to something like *exampletexture_01.dds*. This texture is supposed to be located directly in the
Textures folder since it does not state anything else. If the model is a custom made one, modders tend to group
their textures in separate folders, just to easily keep track of them.
It might be something like *./Textures/moddername/exampletexture_02.dds*.
When OpenMW finally adds normal mapping, it simply takes the NiSourceTexture file path, e.g., *exampletexture_01.dds*, and looks for a *exampletexture_01_n.dds*. If it can't find this file, no normal mapping is added. If it *does* find this file, the model will use this texture as a normal map. Simple.
When OpenMW finally adds normal mapping, it simply takes the NiSourceTexture file path, e.g.,
*exampletexture_01.dds*, and looks for a *exampletexture_01_n.dds*. If it can't find this file, no normal mapping is added.
If it *does* find this file, the model will use this texture as a normal map. Simple.
Activating normal mapping shaders in OpenMW
*******************************************
Before normal (and specular and parallax) maps will show up in OpenMW, you'll need to activate them in the settings.cfg_-file. Add these rows where it would make sense:
Before normal (and specular and parallax) maps will show up in OpenMW, you'll need to activate them in the
settings.cfg_-file. Add these rows where it would make sense:
::
@ -72,13 +86,26 @@ Normal mapping in Morrowind with Morrowind Code Patch
**Conversion difficulty:**
*Varies. Sometimes quick and easy, sometimes time-consuming and hard.*
You might have bumped (pun intended) on a few bump-mapped texture packs for Morrowind that require the Morrowind Code Patch (MCP). You might even be thinking: Why doesn't OpenMW just support these instead of reinventing the wheel? I know it sounds strange, but it will make sense. Here's how MCP handles normal maps:
You might have bumped (pun intended) on a few bump-mapped texture packs for Morrowind that require the
Morrowind Code Patch (MCP). You might even be thinking: Why doesn't OpenMW just support these instead of reinventing
the wheel? I know it sounds strange, but it will make sense. Here's how MCP handles normal maps:
Morrowind does not recognize normal maps (they weren't really a "thing" yet in 2002), so even if you have a normal map, Morrowind will not load and display it. MCP has a clever way to solve this issue, by using something Morrowind *does* support, namely environment maps. You could add a tag for an environment map and then add a normal map as the environment map, but you'd end up with a shiny ugly model in the game. MCP solves this by turning down the brightness of the environment maps, making the model look *kind of* as if it had a normal map applied to it. I say kind of because it does not really look as good as normal mapping usually does. It was a hacky way to do it, but it was the only way at the time, and therefore the best way.
Morrowind does not recognize normal maps (they weren't really a "thing" yet in 2002), so even if you have a normal map,
Morrowind will not load and display it. MCP has a clever way to solve this issue, by using something Morrowind *does* support,
namely environment maps. You could add a tag for an environment map and then add a normal map as the environment map,
but you'd end up with a shiny ugly model in the game. MCP solves this by turning down the brightness of the environment maps,
making the model look *kind of* as if it had a normal map applied to it.
I say kind of because it does not really look as good as normal mapping usually does. It was a hacky way to do it,
but it was the only way at the time, and therefore the best way.
The biggest problem with this is not that it doesn't look as good as it could – no, the biggest problem in my opinion is that it requires you to state the file paths for your normal map textures *in the models*! For buildings, which often use several textures for one single model file, it could take *ages* to do this, and you had to do it for dozens of model files too. You also had to ship your texture pack with model files, making your mod bigger in file size.
The biggest problem with this is not that it doesn't look as good as it could – no,
the biggest problem in my opinion is that it requires you to state the file paths for your normal map textures *in the models*!
For buildings, which often use several textures for one single model file, it could take *ages* to do this,
and you had to do it for dozens of model files too. You also had to ship your texture pack with model files,
making your mod bigger in file size.
These are basically the reasons why OpenMW does not support fake bump maps like MCP does. It is just a really bad way to enhance your models, all the more when you have the possibility to do it in a better way.
These are basically the reasons why OpenMW does not support fake bump maps like MCP does.
It is just a really bad way to enhance your models, all the more when you have the possibility to do it in a better way.
Normal mapping in Morrowind with MGE XE
***************************************
@ -86,9 +113,18 @@ Normal mapping in Morrowind with MGE XE
**Conversion difficulty:**
*Easy*
The most recent feature on this topic is that the Morrowind Graphics Extender (MGE) finally started to support real normal mapping in an experimental version available here: `MGE XE`_ (you can't use MGE with OpenMW!). Not only this but it also adds full support for physically based rendering (PBR), making it one step ahead of OpenMW in terms of texturing techniques. However, OpenMW will probably have this feature in the future too – and let's hope that OpenMW and MGE will handle PBR in a similar fashion in the future so that mods can be used for both MGE and OpenMW without any hassle.
The most recent feature on this topic is that the Morrowind Graphics Extender (MGE) finally started to support real
normal mapping in an experimental version available here: `MGE XE`_ (you can't use MGE with OpenMW!).
Not only this but it also adds full support for physically based rendering (PBR),
making it one step ahead of OpenMW in terms of texturing techniques. However,
OpenMW will probably have this feature in the future too – and let's hope that OpenMW and MGE will handle PBR in a
similar fashion in the future so that mods can be used for both MGE and OpenMW without any hassle.
I haven't researched that much on the MGE variant yet but it does support real implementation of normal mapping, making it really easy to convert mods made for MGE into OpenMW (I'm only talking about the normal map textures though). There's some kind of text file if I understood it correctly that MGE uses to find the normal map. OpenMW does not need this, you just have to make sure the normal map has the same name as the diffuse texture but with the correct suffix after.
I haven't researched that much on the MGE variant yet but it does support real implementation of normal mapping,
making it really easy to convert mods made for MGE into OpenMW (I'm only talking about the normal map textures though).
There's some kind of text file if I understood it correctly that MGE uses to find the normal map.
OpenMW does not need this, you just have to make sure the normal map has the same name as the diffuse texture but with
So, let's say you've found out that PeterBitt_ makes awesome models and textures featuring physically based rendering (PBR) and normal maps. Let's say that you tried to run his `PBR Scamp Replacer`_ in OpenMW and that you were greatly disappointed when the normal map didn't seem to work. Lastly, let's say you came here, looking for some answers. Am I right? Great. Because you've come to the right place!
So, let's say you've found out that PeterBitt_ makes awesome models and textures featuring physically based rendering
(PBR) and normal maps. Let's say that you tried to run his `PBR Scamp Replacer`_ in OpenMW and that you were greatly
disappointed when the normal map didn't seem to work. Lastly, let's say you came here, looking for some answers.
Am I right? Great. Because you've come to the right place!
*A quick note before we begin*: Please note that you can only use the normal map texture and not the rest of the materials, since PBR isn't implemented in OpenMW yet. Sometimes PBR textures can look dull without all of the texture files, so have that in mind.
*A quick note before we begin*: Please note that you can only use the normal map texture and not the rest of the materials,
since PBR isn't implemented in OpenMW yet. Sometimes PBR textures can look dull without all of the texture files,
so have that in mind.
Tutorial - MGE
**************
In this tutorial, I will use PeterBitt's `PBR Scamp Replacer`_ as an example, but any mod featuring PBR that requires the PBR version of MGE will do, provided it also includes a normal map (which it probably does).
In this tutorial, I will use PeterBitt's `PBR Scamp Replacer`_ as an example,
but any mod featuring PBR that requires the PBR version of MGE will do,
provided it also includes a normal map (which it probably does).
So, follow these steps:
@ -120,11 +163,14 @@ So, follow these steps:
#. Rename your newly extracted file (``tx_Scamp_normals.dds``) to ``tx_Scamp_n.dds`` (which is exactly the same name as the diffuse texture file, except for the added *_n* suffix before the filename extention).
#. You're actually done!
So as you might notice, converting these mods is very simple and takes just a couple of minutes. It's more or less just a matter of renaming and moving a few files.
So as you might notice, converting these mods is very simple and takes just a couple of minutes.
It's more or less just a matter of renaming and moving a few files.
I totally recommend you to also try this on PeterBitt's Nix Hound replacer and Flash3113's various replacers. It should be the same principle to get those to work.
I totally recommend you to also try this on PeterBitt's Nix Hound replacer and Flash3113's various replacers.
It should be the same principle to get those to work.
And let's hope that some one implements PBR shaders to OpenMW too, so that we can use all the material files of these mods in the future.
And let's hope that some one implements PBR shaders to OpenMW too,
so that we can use all the material files of these mods in the future.
Converting textures made for the Morrowind Code Patch (MCP) fake bump mapping can be really easy or a real pain, depending on a few circumstances. In this tutorial, we will look at a very easy, although in some cases a bit time-consuming, example.
Converting textures made for the Morrowind Code Patch (MCP) fake bump mapping can be really easy or a real pain,
depending on a few circumstances. In this tutorial, we will look at a very easy,
although in some cases a bit time-consuming, example.
Tutorial - MCP, Part 1
**********************
We will be converting a quite popular texture replacer of the Hlaalu architecture, namely Lougian's `Hlaalu Bump mapped`_. Since this is just a texture pack and not a model replacer, we can convert the mod in a few minutes by just renaming a few dozen files and by *not* extracting the included model (``.nif``) files when installing the mod.
We will be converting a quite popular texture replacer of the Hlaalu architecture, namely Lougian's `Hlaalu Bump mapped`_.
Since this is just a texture pack and not a model replacer,
we can convert the mod in a few minutes by just renaming a few dozen files and by *not* extracting the included model
(``.nif``) files when installing the mod.
#. Download Lougian's `Hlaalu Bump mapped`_.
#. Install the mod by extracting the ``./Textures`` folder to a data folder the way you usually install mods (**Pro tip**: Install using OpenMW's `Multiple data folders`_ function!).
@ -149,7 +200,8 @@ We will be converting a quite popular texture replacer of the Hlaalu architectur
- As a nice bonus to this tutorial, this pack actually included one specularity texture too. We should use it of course. It's the one called "``tx_glass_amber_02_reflection.dds``". For OpenMW to recognize this file and use it as a specular map, you need to change the *_reflection.dds* part to *_spec.dds*, resulting in the name ``tx_glass_amber_01_spec.dds``.
#. That should be it. Really simple, but I do know that it takes a few minutes to rename all those files.
Now – if the mod you want to change includes custom made models it gets a bit more complicated I'm afraid. But that is for the next tutorial.
Now – if the mod you want to change includes custom made models it gets a bit more complicated I'm afraid.
But that is for the next tutorial.
Converting Apel's Various Things - Sacks
----------------------------------------
@ -158,12 +210,16 @@ Converting Apel's Various Things - Sacks
:Authors:Joakim (Lysol) Berg
:Updated:2016-11-09
In part one of this tutorial, we converted a mod that only included modified Morrowind model (``.nif``) files so that the normal maps could be loaded in Morrowind with MCP. We ignored those model files since they are not needed with OpenMW. In this tutorial however, we will convert a mod that includes new, custom made models. In other words, we cannot just ignore those files this time.
In part one of this tutorial, we converted a mod that only included modified Morrowind model (``.nif``)
files so that the normal maps could be loaded in Morrowind with MCP.
We ignored those model files since they are not needed with OpenMW. In this tutorial however,
we will convert a mod that includes new, custom made models. In other words, we cannot just ignore those files this time.
Tutorial - MCP, Part 2
**********************
The sacks included in Apel's `Various Things - Sacks`_ come in two versions – Without bump mapping, and with bump mapping. Since we want the glory of normal mapping in our OpenMW setup, we will go with the bump-mapped version.
The sacks included in Apel's `Various Things - Sacks`_ come in two versions – Without bump mapping, and with bump mapping.
Since we want the glory of normal mapping in our OpenMW setup, we will go with the bump-mapped version.
#. Start by downloading Apel's `Various Things - Sacks`_ from Nexus.
#. Once downloaded, install it the way you'd normally install your mods (**Pro tip**: Install using OpenMW's `Multiple data folders`_ function!).
@ -181,7 +237,9 @@ The sacks included in Apel's `Various Things - Sacks`_ come in two versions –
#. OpenMW detects normal maps if they have the same name as the base diffuse texture, but with a *_n.dds* suffix. In this mod, the normal maps has a suffix of *_nm.dds*. Change all the files that ends with *_nm.dds* to instead end with *_n.dds*.
#. Finally, `we are done`_!
Since these models have one or two textures applied to them, the fix was not that time-consuming. It gets worse when you have to fix a model that uses loads of textures. The principle is the same, it just requires more manual work which is annoying and takes time.
Since these models have one or two textures applied to them, the fix was not that time-consuming.
It gets worse when you have to fix a model that uses loads of textures. The principle is the same,
it just requires more manual work which is annoying and takes time.
@ -19,10 +19,16 @@ OpenMW automatically uses shaders for objects with these mapping techniques.
Normal Mapping
##############
To plug in a normal map, you name the normal map as the diffuse texture but with a specified suffix after. OpenMW will then recognise the file and load it as a normal map, provided you have set up your settings file correctly. See the section `Automatic use`_ further down below for detailed information.
To plug in a normal map, you name the normal map as the diffuse texture but with a specified suffix after.
OpenMW will then recognise the file and load it as a normal map, provided you have set up your settings file correctly.
See the section `Automatic use`_ further down below for detailed information.
..note::
While the original Morrowind engine does support the loading of a BumpTexture slot in the NIF, it will not display it as a normal map. Morrowind Code Patch (MCP) added a way to hack normal maps into the engine by first enabling the engine to load the BumpTexture slot as an environment map and then turn down the brightness of the environment map. This will imitate how a real normal map shader would display a normal map, but it will not look exactly the same.
While the original Morrowind engine does support the loading of a BumpTexture slot in the NIF,
it will not display it as a normal map. Morrowind Code Patch (MCP)
added a way to hack normal maps into the engine by first enabling the engine to load the BumpTexture slot as an
environment map and then turn down the brightness of the environment map.
This will imitate how a real normal map shader would display a normal map, but it will not look exactly the same.
OpenMW uses standard normal mapping, which achieves much better results.
Unfortunately, this difference can result in incompatibilities.
Bret Curtis
6 years ago
committed by
GitHub