Merge pull request #1790 from rhtucker/master
Migrating necessary parts of Wiki over to RTD.pull/457/head
Bret Curtis
7 years ago
committed by
GitHub
commit
a3a002e008
@ -1,2 +1,2 @@
|
||||
parse_cmake
|
||||
sphinx
|
||||
sphinx>=1.7.0
|
||||
|
||||
@ -1,11 +1,9 @@
|
||||
Welcome to OpenMW's Documentation!
|
||||
==================================
|
||||
|
||||
Sections
|
||||
--------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:caption: Table of Contents
|
||||
:maxdepth: 3
|
||||
|
||||
manuals/index
|
||||
reference/index
|
||||
manuals/index
|
||||
reference/index
|
||||
|
||||
@ -0,0 +1,50 @@
|
||||
###############
|
||||
Common Problems
|
||||
###############
|
||||
|
||||
ERROR: Unknown fallback name: FontColor_color_header
|
||||
####################################################
|
||||
|
||||
:Symptoms:
|
||||
OpenMW crashes at startup with
|
||||
``ERROR: Unknown fallback name: FontColor_color_header``
|
||||
message at the end of ``openmw.log``, located `here </docs/source/reference/modding/paths>`_.
|
||||
|
||||
:Cause:
|
||||
The OpenMW `configuration file </docs/source/reference/modding/paths>`_ ``openmw.cfg``
|
||||
is severely lacking and missing fallback values
|
||||
because "Settings Importer" was not run correctly.
|
||||
|
||||
:Fix:
|
||||
Re-run "Settings Importer" from the OpenMW launcher.
|
||||
|
||||
Installing game files via Steam on macOS: DISK WRITE ERROR
|
||||
##########################################################
|
||||
|
||||
:Symptoms:
|
||||
Steam stages the download for Morrowind, but does not proceed.
|
||||
The download will read "Paused: DISK WRITE ERROR".
|
||||
|
||||
:Cause:
|
||||
The OpenMW `configuration file </docs/source/reference/modding/paths>`_ ``openmw.cfg``
|
||||
is severely lacking and missing fallback values
|
||||
because "Settings Importer" was not run correctly.
|
||||
|
||||
:Fix:
|
||||
Open appmanifest_22320.acf in your favorite text editor.
|
||||
Locate or create an entry under the "StateFlags" entry titled "installdir"
|
||||
and give it the value "Morrowind".
|
||||
Your file should now look something like this::
|
||||
|
||||
"AppState"
|
||||
{
|
||||
"appid" "22320"
|
||||
"Universe" "1"
|
||||
"name" "The Elder Scrolls III: Morrowind"
|
||||
"StateFlags" "4"
|
||||
"installdir" "Morrowind"
|
||||
|
||||
[other entries]
|
||||
}
|
||||
|
||||
Restart the Steam client. The download should now proceed.
|
||||
@ -1,5 +1,126 @@
|
||||
==================
|
||||
##################
|
||||
Install Game Files
|
||||
==================
|
||||
##################
|
||||
|
||||
OpenMW is a complete game engine that can either run `Morrowind`_
|
||||
or original projects created with OpenMW-CS, such as `Example Suite`_.
|
||||
|
||||
Morrowind
|
||||
#########
|
||||
|
||||
Running the Morrowind Installation Wizard
|
||||
=========================================
|
||||
|
||||
#. Launch the OpenMW Launcher
|
||||
#. Launch the Installation Wizard
|
||||
|
||||
.. note::
|
||||
If you are prompted with an error message stating
|
||||
"Could not find the Data Files location,"
|
||||
click the "Run Installation Wizard" button.
|
||||
.. note::
|
||||
If you arrive at the main screen, click the "Settings" tab,
|
||||
and then click the "Run Installation Wizard" button.
|
||||
|
||||
#. Follow further instructions below
|
||||
to install Morrowind from either a retail CD or an existing installation.
|
||||
|
||||
- **Morrowind (from retail CD)**
|
||||
|
||||
#. Make sure that the retail CD is in your computer's CD/DVD drive
|
||||
and the Installation Wizard is running.
|
||||
#. On the "Select Installation Method" screen of the Installation Wizard,
|
||||
choose "Install Morrowind to a New Location" and click the "Next" button.
|
||||
#. Choose a location to install Morrowind to your hard drive
|
||||
(or accept the suggested location) and click the "Next" button.
|
||||
#. Select your preferred language for the installation
|
||||
and click the "Next" button
|
||||
#. Select which official expansions (Tribunal or Bloodmoon) should be installed.
|
||||
For best results, it is recommended to have both expansions installed.
|
||||
#. Click the "Install" button.
|
||||
|
||||
- **Morrowind (from existing installation)**
|
||||
|
||||
#. On the "Select Installation Method" screen of the Installation Wizard,
|
||||
choose "Select an existing Morrowind installation" and click the "Next" button
|
||||
#. Select an installation. If nothing is detected, click browse.
|
||||
#. Navigate to the directory containing the file ``Morrowind.esm`` and select that file.
|
||||
|
||||
#. You will be asked if you wish to import settings from ``Morrowind.ini``.
|
||||
Select "Import", otherwise OpenMW will not work.
|
||||
(You do not need to check the box "Include selected masters and plugins").
|
||||
#. The OpenMW launcher window should now open.
|
||||
Switch to the "Data Files" tab and check the box to the left of ``Morrowind.esm``.
|
||||
#. You are now ready to play!
|
||||
|
||||
Installing Morrowind
|
||||
====================
|
||||
|
||||
-----------------
|
||||
Retail CD and GOG
|
||||
-----------------
|
||||
|
||||
Windows users can run the installer if they haven't already.
|
||||
By default, both Bethesda's official installer on the retail CD
|
||||
and the GOG installer install to ``C:\Program Files\Bethesda Softworks\Morrowind``.
|
||||
You will find ``Morrowind.esm`` there.
|
||||
|
||||
Users of other platforms running Wine, will find it at
|
||||
``~/.wine/drive_c/Program Files/Bethesda Softworks/Morrowind``
|
||||
|
||||
-----
|
||||
Steam
|
||||
-----
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
Windows users can download Morrowind through Steam.
|
||||
Afterwards, you can point OpenMW to the Steam install location at
|
||||
``C:\Program Files\Steam\SteamApps\common\Morrowind\Data Files\``
|
||||
and find ``Morrowind.esm`` there.
|
||||
|
||||
macOS
|
||||
-----
|
||||
|
||||
If you are running macOS, you can also download Morrowind through Steam:
|
||||
|
||||
#. Navigate to ``/Users/YOUR_USERNAME_HERE/Library/Application Support/Steam/steamapps/``
|
||||
#. Create a file called ``appmanifest_22320.acf``
|
||||
(the number is based on its `Steam App ID <https://steamdb.info/app/22320/>`_).
|
||||
If using TextEdit,
|
||||
make sure that your document is in plain text mode by going to the menu bar
|
||||
and choosing "Format" -> "Make Plain Text".
|
||||
Also, ensure that it's not named with the extension ``.acf.txt``.
|
||||
Add the following into that file::
|
||||
|
||||
"AppState"
|
||||
{
|
||||
"AppID" "22320"
|
||||
"Universe" "1"
|
||||
"StateFlags" "1026"
|
||||
"installdir" "The Elder Scrolls III - Morrowind"
|
||||
}
|
||||
|
||||
#. Launch the Steam client and let it download. You can then find ``Morrowind.esm`` at
|
||||
``~/Library/Application Support/Steam/steamapps/common/The Elder Scrolls III - Morrowind/Data Files/``
|
||||
|
||||
Wine
|
||||
----
|
||||
|
||||
Users of other platforms running Wine can run Steam within it
|
||||
and find ``Morrowind.esm`` at
|
||||
``~/.wine/drive_c/Program Files/Steam/SteamApps/common/Morrowind/Data Files/``.
|
||||
|
||||
Example Suite
|
||||
#############
|
||||
|
||||
Example Suite is a demo showing the capabilities of the OpenMW engine.
|
||||
At this time, it requires Morrowind to be installed to run,
|
||||
but does not use any assets from it.
|
||||
In the future, it will be possible to run without installing Morrowind first.
|
||||
|
||||
#. `Install Morrowind <Installing Morrowind_>`_
|
||||
#. `Download the latest version <https://github.com/OpenMW/example-suite/releases>`_
|
||||
#. Follow the platform-specific instructions in the zip file's ``Installation.md`` file.
|
||||
|
||||
Coming Soon...
|
||||
@ -1,8 +1,9 @@
|
||||
##################
|
||||
Reference Material
|
||||
==================
|
||||
##################
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 2
|
||||
|
||||
modding/index
|
||||
documentationHowTo
|
||||
modding/index
|
||||
documentationHowTo
|
||||
@ -0,0 +1,16 @@
|
||||
######################
|
||||
OpenMW Texture Modding
|
||||
######################
|
||||
|
||||
Although texture modding requires external tools not supported by the OpenMW team,
|
||||
adding and modifying textures is an important part of content creation.
|
||||
Therefore, we've included the following in hopes of helping modders transition
|
||||
to texture modding in OpenMW.
|
||||
|
||||
.. toctree::
|
||||
:caption: Table of Contents
|
||||
:maxdepth: 2
|
||||
|
||||
texture-basics
|
||||
convert-bump-mapped-mods
|
||||
native-mesh-format
|
||||
@ -0,0 +1,114 @@
|
||||
##################
|
||||
Native Mesh Format
|
||||
##################
|
||||
|
||||
This article explains how to export a model from Blender to OpenMW using the OSG model format.
|
||||
Starting with OpenMW version 0.38 we can utilize the OSG native model format.
|
||||
The OSG model format doesn't yet support all the features that NIF's support,
|
||||
but works for basic models. For more details on the format, refer to
|
||||
`this forum post <https://forum.openmw.org/viewtopic.php?f=20&t=2949&p=35514#p35514>`_.
|
||||
|
||||
Previously, NIF files were the only way to get models into the game.
|
||||
Unfortunately, the NIF format is proprietary, bloated,
|
||||
and the available exporters are not in great shape.
|
||||
For example, the Blender NIF exporter currently only works with the very old Blender 2.49.
|
||||
|
||||
Prerequisites
|
||||
#############
|
||||
|
||||
- OpenMW 0.38 or later
|
||||
- Blender 2.60 or later
|
||||
- OSG exporter add-on for Blender
|
||||
- A Blender model you would like to export
|
||||
|
||||
Installing the exporter
|
||||
#######################
|
||||
|
||||
#. Download the
|
||||
`OSG export script
|
||||
<https://github.com/openmw/osgexport/blob/release/blender-2.5/build/osgexport-0.14.2.zip?raw=true>`_
|
||||
#. Open Blender and go to File -> User Preferences
|
||||
#. Select Add-ons -> Install from File, then select the downloaded `.zip`
|
||||
#. Enter "osg" into the search bar, then tick the checkbox next to the add-on to enable it
|
||||
#. Now click Save user setting so the exporter stays enabled when you re-start Blender
|
||||
|
||||
You can now export your models using the OSG model (osgt) entry in the File -> Export menu.
|
||||
|
||||
Model's location
|
||||
################
|
||||
|
||||
The model needs to be at 0,0,0 coordinates in Blender,
|
||||
as this is where its origin will always be when exported.
|
||||
If the model is offset from 0,0,0 in Blender,
|
||||
it will be offset from its origin in the exported file as well.
|
||||
|
||||
Model's rotation
|
||||
################
|
||||
|
||||
- Blender's Z axis is up axis in OpenMW
|
||||
- Blender's Y axis is front axis in OpenMW
|
||||
- Blender's X axis is left-right axis in OpenMW
|
||||
- Visual rotation is taken into account when exporting
|
||||
|
||||
Model's scale
|
||||
#############
|
||||
|
||||
Blender:OpenMW model scale is 70:1,
|
||||
which means 70 Blender units (BU) translate into 1m in OpenMW.
|
||||
Using this scale, any models you make will fit with the existing ones.
|
||||
The scale does not need to be applied,
|
||||
the exporter will always use the visual scale of the model.
|
||||
However, 70 is an odd number to work with so here's an alternative workflow:
|
||||
|
||||
- In Blender, use a scale of 1BU = 1m which is a nice scale and ratio to work with.
|
||||
Have all models use this scale.
|
||||
- Before exporting a model, scale it up by a factor of 70.
|
||||
- After exporting, undo the model's scale change and continue working as normal
|
||||
(in the future a preferable way would be to apply the scale through the exporter)
|
||||
|
||||
Putting the model in-game
|
||||
#########################
|
||||
|
||||
Place the exported model in the Meshes sub-folder of a data folder recognized by the game,
|
||||
e.g. the Morrowind Data Files folder, or the local data folder.
|
||||
Place all required textures in the Textures sub-folder.
|
||||
Now start OpenMW-CS, create a new addon file
|
||||
and you should see your mesh in the Assets -> Meshes table.
|
||||
Go ahead and make some object use your mesh.
|
||||
You can now preview by right clicking on the object -> Preview to see what the mesh will look like.
|
||||
|
||||
Converting the model to binary
|
||||
##############################
|
||||
|
||||
When the model behaves to our liking,
|
||||
we can think about converting it from the "osgt" text format to the "osgb" binary format
|
||||
so that it's smaller in size - and thus faster to load.
|
||||
|
||||
To do this, simply invoke the osgconv tool.
|
||||
This tool should be included with your distribution of OpensceneGraph.
|
||||
|
||||
`osgconv -O WriteImageHint=UseExternal model.osgt model.osgb`
|
||||
|
||||
Of course, you can convert the binary model back to text format as well:
|
||||
|
||||
`osgconv -O WriteImageHint=UseExternal model.osgb model.osgt`
|
||||
|
||||
Note the use of `-O WriteHint=UseExternal` option.
|
||||
Enabling this option is desirable because it keeps the textures as external file references,
|
||||
rather than embedding the textures within the model file.
|
||||
Embedded textures have disadvantages such as being hard to inspect,
|
||||
and impossible to share between model files.
|
||||
|
||||
Using shaders/normal maps
|
||||
#########################
|
||||
|
||||
See :ref:`OSG Native Files`
|
||||
|
||||
Conclusion
|
||||
##########
|
||||
|
||||
These are the basics of getting a textured, static model from Blender into the game.
|
||||
In the future, we will want a way to add texture animations,
|
||||
skeletal animations, separate collision shapes,
|
||||
and some other features that are currently only available via NIF files.
|
||||
We will likely add these features to the native OSG format after OpenMW 1.0.
|
||||
@ -0,0 +1,171 @@
|
||||
autosectionlabel_prefix_document = True
|
||||
|
||||
######################
|
||||
Texture Modding Basics
|
||||
######################
|
||||
|
||||
OpenMW supports new texture mapping techniques
|
||||
that were not available in the vanilla Morrowind engine.
|
||||
|
||||
`Normal mapping`_ is a technique used to fake lighting of bumps,
|
||||
cracks and other small details.
|
||||
|
||||
`Specular mapping`_ is used to vary the shininess/specularity along the surface of an object.
|
||||
|
||||
The prerequisite to using these techniques are
|
||||
`shaders <https://en.wikipedia.org/wiki/Shader>`_.
|
||||
OpenMW automatically uses shaders for objects with these mapping techniques.
|
||||
|
||||
Normal Mapping
|
||||
##############
|
||||
|
||||
To plug in a normal map, you can edit the NIF mesh file(s) using NifSkope
|
||||
and assign the normal map texture to the BumpTexture slot in the NiTexturingProperty.
|
||||
|
||||
.. note::
|
||||
While the original Morrowind engine does support the BumpTexture slot,
|
||||
it uses a strange form of normal mapping that applies to an environment map.
|
||||
OpenMW uses standard normal mapping, which can achieve much better results.
|
||||
Unfortunately, this difference can result in incompatibilities.
|
||||
Some mods
|
||||
(e.g. `Redoran Bump Mapped <http://www.nexusmods.com/morrowind/mods/42406/?>`_)
|
||||
look much darker compared to the vanilla engine and will have to be recalibrated.
|
||||
|
||||
Specular Mapping
|
||||
################
|
||||
|
||||
The RGB channels of the specular map are used as the specular color.
|
||||
The alpha channel specifies shininess in range [0, 255].
|
||||
If a specular map is used, it will override the shininess and specular color
|
||||
set in the NiMaterialProperty / osg::Material.
|
||||
|
||||
NIF files do not support specular maps.
|
||||
In order to use them anyway, see the next section.
|
||||
|
||||
Automatic Use
|
||||
#############
|
||||
|
||||
In addition to editing mesh files,
|
||||
there is another way of plugging in these texture maps.
|
||||
Simply create the textures with appropriate naming convention
|
||||
(e.g. when the base texture is called foo.dds,
|
||||
the normal map would have to be called foo_n.dds).
|
||||
To enable this automatic use based on filename pattern,
|
||||
you will have to add the following to your
|
||||
`settings.cfg </source/reference/modding/paths>`_ file::
|
||||
|
||||
[Shaders]
|
||||
auto use object normal maps = true
|
||||
|
||||
auto use object specular maps = true
|
||||
|
||||
normal map pattern = _n
|
||||
normal height map pattern = _nh
|
||||
|
||||
specular map pattern = _spec
|
||||
|
||||
Additionally, a normal map with the `_nh` pattern enables
|
||||
the use of the normal map's alpha channel as height information.
|
||||
This can be used by a `parallax mapping <https://en.wikipedia.org/wiki/Parallax_mapping>`_
|
||||
shader to offset the texture depending on the viewing angle and height,
|
||||
creating a fake 3D effect.
|
||||
|
||||
The above settings are not enabled by default to prevent incompatibilities
|
||||
with mods that may be inadvertently using these naming schemes.
|
||||
|
||||
On the topic of shader settings,
|
||||
you may be interested in these three settings as well: :ref:`force shaders`,
|
||||
:ref:`force per pixel lighting`, and :ref:`clamp lighting`.
|
||||
In particular, `clamp lighting = false` makes normal maps look much better!
|
||||
|
||||
Terrain
|
||||
#######
|
||||
|
||||
The terrain shader also supports normal, normal-height and specular maps,
|
||||
with one difference compared to objects:
|
||||
the specular value must be packed into the layer texture's alpha channel.
|
||||
|
||||
For example, if you wanted to add specular mapping to a terrain layer called rock.dds,
|
||||
you would copy this texture to a new file called rock_diffusespec.dds,
|
||||
and then edit its alpha channel to set the specular intensity.
|
||||
|
||||
The relevant settings are::
|
||||
|
||||
[Shaders]
|
||||
auto use terrain normal maps = true
|
||||
|
||||
auto use terrain specular maps = true
|
||||
|
||||
terrain specular map pattern = _diffusespec
|
||||
|
||||
# Also used for terrain normal maps
|
||||
normal map pattern = _n
|
||||
normal height map pattern = _nh
|
||||
|
||||
OSG native files
|
||||
################
|
||||
|
||||
OpenMW supports all the above shader features for meshes in the Native Mesh Format.
|
||||
To have the shader generator recognize specific textures,
|
||||
the `osg::Texture2D` must be named appropriately.
|
||||
|
||||
Available texture types are the following (most of which also have NIF equivalents):
|
||||
|
||||
:diffuseMap: base texture
|
||||
:normalMap: normal map, as described earlier
|
||||
:normalHeightMap: same as normal map, but including height information in alpha channel to be used for parallax effects
|
||||
:emissiveMap: controls the material's emission, useful for objects that glow in the dark
|
||||
:darkMap: multiplied onto the base texture
|
||||
:detailMap: multiplied by 2 and then multiplied onto the base texture
|
||||
:envMap: spherical environment map
|
||||
:specularMap: specular map, as described earlier
|
||||
|
||||
The first texture unit automatically acts as diffuseMap if no recognized type is specified.
|
||||
|
||||
Example: `.osgt` file excerpt of a normal mapped mesh::
|
||||
|
||||
TextureModeList 2 {
|
||||
Data 1 {
|
||||
GL_TEXTURE_2D ON
|
||||
}
|
||||
Data 1 {
|
||||
GL_TEXTURE_2D ON
|
||||
}
|
||||
}
|
||||
TextureAttributeList 2 {
|
||||
Data 1 {
|
||||
osg::Texture2D {
|
||||
UniqueID 37
|
||||
Name "diffuseMap"
|
||||
WRAP_S REPEAT
|
||||
WRAP_T REPEAT
|
||||
WRAP_R REPEAT
|
||||
MIN_FILTER LINEAR_MIPMAP_LINEAR
|
||||
MAG_FILTER LINEAR
|
||||
Image TRUE {
|
||||
UniqueID 60
|
||||
FileName "textures/BuddhaStatue_Dif.jpg"
|
||||
WriteHint 2 2
|
||||
}
|
||||
}
|
||||
Value OFF
|
||||
}
|
||||
Data 1 {
|
||||
osg::Texture2D {
|
||||
UniqueID 38
|
||||
Name "normalMap"
|
||||
WRAP_S REPEAT
|
||||
WRAP_T REPEAT
|
||||
WRAP_R REPEAT
|
||||
MIN_FILTER LINEAR_MIPMAP_LINEAR
|
||||
MAG_FILTER LINEAR
|
||||
Image TRUE {
|
||||
UniqueID 61
|
||||
FileName "textures/BuddhaStatue_Nor.jpg"
|
||||
WriteHint 2 2
|
||||
}
|
||||
}
|
||||
Value OFF
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue