Merge pull request #1790 from rhtucker/master

Migrating necessary parts of Wiki over to RTD.

docs/requirements.txt

@@ -1,2 +1,2 @@
 parse_cmake
-sphinx
+sphinx>=1.7.0

docs/source/conf.py

@@ -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']
 

docs/source/index.rst

@@ -1,11 +1,9 @@
 Welcome to OpenMW's Documentation!
 ==================================
 
-Sections
---------
-
 .. toctree::
-    :maxdepth: 3
+	:caption: Table of Contents
+	:maxdepth: 3
 
-    manuals/index
+	manuals/index
-    reference/index
+	reference/index

docs/source/manuals/installation/common-problems.rst

@@ -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.

docs/source/manuals/installation/index.rst

@@ -1,3 +1,4 @@
+##################
 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

docs/source/manuals/installation/install-game-files.rst

@@ -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...

docs/source/reference/index.rst

@@ -1,8 +1,9 @@
+##################
 Reference Material
-==================
+##################
 
 .. toctree::
-    :maxdepth: 2
+	:maxdepth: 2
 
-    modding/index
+	modding/index
-    documentationHowTo
+	documentationHowTo

docs/source/reference/modding/index.rst

@@ -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
+	OpenMW is still software in development. This manual does not cover any
-    of its shortcomings. It is written as if everything was working as
+	of its shortcomings. It is written as if everything was working as
-    intended. Please report any software problems as bugs in the software,
+	intended. Please report any software problems as bugs in the software,
-    not errors in the manual.
+	not errors in the manual.
 
 .. toctree::
-    :caption: Table of Contents
+	:caption: Table of Contents
-    :maxdepth: 2
+	:maxdepth: 2
 
-    foreword
+	foreword
-    differences
+	differences
-    mod-install
+	mod-install
-    settings/index
+	settings/index
-    font
+	texture-modding/index
-    convert_bump_mapped_mods
+	font
-    paths
+	paths

docs/source/reference/modding/texture-modding/index.rst

@@ -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

docs/source/reference/modding/texture-modding/native-mesh-format.rst

@@ -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.

docs/source/reference/modding/texture-modding/texture-basics.rst

@@ -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
+		}
+	}
+