Commit 380384ff authored by Ryan Tucker's avatar Ryan Tucker
Browse files

Migrated textures section of wiki.

parent f4146d00
parse_cmake
sphinx
sphinx>=1.7.0
......@@ -23,7 +23,7 @@ sys.path.insert(0, project_root)
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
needs_sphinx = '1.7'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
......@@ -34,8 +34,11 @@ extensions = [
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.autosectionlabel',
]
#autosectionlabel_prefix_document = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
......
Welcome to OpenMW's Documentation!
==================================
Sections
--------
.. toctree::
:maxdepth: 3
:caption: Table of Contents
:maxdepth: 3
manuals/index
reference/index
manuals/index
reference/index
###############
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.
\ No newline at end of file
##################
Installation Guide
##################
......@@ -8,4 +9,4 @@ In order to use OpenMW, you must install both the engine and the game files for
install-openmw
install-game-files
common-problems
\ No newline at end of file
==================
##################
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...
\ No newline at end of file
##################
Reference Material
==================
##################
.. toctree::
:maxdepth: 2
:maxdepth: 2
modding/index
documentationHowTo
\ No newline at end of file
modding/index
documentationHowTo
\ No newline at end of file
......@@ -8,19 +8,19 @@ about creating new content for OpenMW, please refer to
:doc:`/manuals/openmw-cs/index`.
.. warning::
OpenMW is still software in development. This manual does not cover any
of its shortcomings. It is written as if everything was working as
intended. Please report any software problems as bugs in the software,
not errors in the manual.
OpenMW is still software in development. This manual does not cover any
of its shortcomings. It is written as if everything was working as
intended. Please report any software problems as bugs in the software,
not errors in the manual.
.. toctree::
:caption: Table of Contents
:maxdepth: 2
:caption: Table of Contents
:maxdepth: 2
foreword
differences
mod-install
settings/index
font
convert_bump_mapped_mods
paths
foreword
differences
mod-install
settings/index
texture-modding/index
font
paths
######################
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
##################
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.
\ No newline at end of file
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
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment