Commit 89f4ad18 authored by Alec Nunn's avatar Alec Nunn
Browse files

Worked with formatting the documentation source to conform to standards...

Worked with formatting the documentation source to conform to standards desired. Also corrected numerous spelling errors and inconsistencies.
parent 354447cc
......@@ -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
For Linux/Windows - (Macos is a little different)
For Linux/Windows - (MacOS is a little different)
1. File/Settings/Plugins
2. Browse Repositories
......
......@@ -4,15 +4,19 @@ Modding OpenMW vs Morrowind
A brief overview of the differences between the two engines.
============================================================
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>
......@@ -4,14 +4,20 @@ Fonts
Morrowind .fnt fonts
--------------------
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.
Unlike vanilla Morrowind, OpenMW directly supports TrueType (``.ttf``) fonts.
This is the recommended way to create new fonts.
- To replace the primary "Magic Cards" font:
......@@ -74,4 +80,7 @@ Unlike vanilla Morrowind, OpenMW directly supports TrueType (``.ttf``) fonts. Th
Bitmap 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.
Foreword
########
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!
\ No newline at end of file
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!
\ No newline at end of file
......@@ -21,16 +21,20 @@ Install
#. 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.
#. Open the OpenMW Launcher.
#. Click on the Data Files tab.
......
......@@ -8,7 +8,8 @@ crosshair
:Range: True/False
:Default: True
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.
......
......@@ -11,7 +11,10 @@ exterior cell load distance
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.
......@@ -9,11 +9,11 @@ show owned
:Default: 0
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.
......@@ -167,7 +169,8 @@ use additional anim sources
: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.
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!
This setting can only be configured by editing the settings configuration file.
......@@ -179,7 +182,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.
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.
This setting can be toggled in Advanced tab of the launcher.
......@@ -8,7 +8,8 @@ global
:Range: True/False
:Default: False
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.
......@@ -29,7 +29,8 @@ timeplayed
:Default: False
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.
......@@ -39,7 +39,8 @@ Only affects objects that render with shaders (see 'force shaders' option).
Always affects terrain.
Leaving this option at its default makes the lighting compatible with Morrowind's fixed-function method,
but the lighting may appear dull and there might be color shifts. Setting this option to 'false' results in more dynamic lighting.
but the lighting may appear dull and there might be colour shifts.
Setting this option to 'false' results in more dynamic lighting.
auto use object normal maps
---------------------------
......@@ -83,7 +84,7 @@ auto use terrain specular maps
:Default: False
If a file with pattern 'terrain specular map pattern' exists, use that file as a 'diffuse specular' map.
The texture must contain the layer color in the RGB channel (as usual), and a specular multiplier in the alpha channel.
The texture must contain the layer colour in the RGB channel (as usual), and a specular multiplier in the alpha channel.
normal map pattern
------------------
......
......@@ -67,7 +67,7 @@ voice volume
:Range: 0.0 (silent) to 1.0 (maximum volume)
:Default: 0.8
This setting controls the volume for spoken dialog from NPCs.
This setting controls the volume for spoken dialogue from NPCs.
This setting can be changed in game using the Voice slider from the Audio panel of the Options menu.
......@@ -122,7 +122,7 @@ hrtf
This setting specifies which HRTF profile to use when HRTF is enabled. Blank means use the default.
This setting has no effect if HRTF is not enabled based on the hrtf enable setting.
Allowed values for this field are enumerated in openmw.log file is an HRTF enabled ausio system is installed.
Allowed values for this field are enumerated in openmw.log file is an HRTF enabled audio system is installed.
The default value is empty, which uses the default profile.
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,
......
......@@ -170,7 +170,8 @@ contrast
This setting controls the contrast correction for all video in the game.
This setting can only be configured by editing the settings configuration file. It has been reported to not work on some Linux systems.
This setting can only be configured by editing the settings configuration file.
It has been reported to not work on some Linux systems.
gamma
-----
......@@ -183,4 +184,5 @@ This setting controls the gamma correction for all video in the game.
Gamma is an exponent that makes colors brighter if greater than 1.0 and darker if less than 1.0.
This setting can be changed in the Detail tab of the Video panel of the Options menu.
It has been reported to not work on some Linux systems, and therefore the in-game setting in the Options menu has been disabled on Linux systems.
It has been reported to not work on some Linux systems,
and therefore the in-game setting in the Options menu has been disabled on Linux systems.
......@@ -25,7 +25,8 @@ Hand editing the configuration file might result in some fine tuning for alignme
but the settings will be overwritten if a window is moved.
.. note::
To scale the windows, making the widgets proportionally larger, see the scaling factor setting in the GUI section instead.
To scale the windows, making the widgets proportionally larger,
see the scaling factor setting in the GUI section instead.
:Type: boolean
:Range: True/False
......@@ -210,7 +211,7 @@ dialogue
w = 0.45
The dialog window, for talking with NPCs.
The dialogue window, for talking with NPCs.
Activated by clicking on a NPC.
alchemy
......
......@@ -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*!