diff --git a/docs/requirements.txt b/docs/requirements.txt index 72c2aaa12..288d462d0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,2 @@ parse_cmake -sphinx +sphinx>=1.7.0 diff --git a/docs/source/conf.py b/docs/source/conf.py index 0ba8567c0..8905044dd 100644 --- a/docs/source/conf.py +++ b/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'] diff --git a/docs/source/index.rst b/docs/source/index.rst index 3781733cb..de3773ddb 100644 --- a/docs/source/index.rst +++ b/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 - reference/index + manuals/index + reference/index diff --git a/docs/source/manuals/installation/common-problems.rst b/docs/source/manuals/installation/common-problems.rst new file mode 100644 index 000000000..543b8ec9b --- /dev/null +++ b/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 `_. + +:Cause: + The OpenMW `configuration file `_ ``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 `_ ``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 diff --git a/docs/source/manuals/installation/index.rst b/docs/source/manuals/installation/index.rst index f22e77449..6e6f5034e 100644 --- a/docs/source/manuals/installation/index.rst +++ b/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 \ No newline at end of file diff --git a/docs/source/manuals/installation/install-game-files.rst b/docs/source/manuals/installation/install-game-files.rst index 11c746f44..ac3688e88 100644 --- a/docs/source/manuals/installation/install-game-files.rst +++ b/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 `_). + 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 `_ +#. `Download the latest version `_ +#. Follow the platform-specific instructions in the zip file's ``Installation.md`` file. -Coming Soon... \ No newline at end of file diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 3f2e2f560..cd947745e 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -1,8 +1,9 @@ +################## 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 diff --git a/docs/source/reference/modding/index.rst b/docs/source/reference/modding/index.rst index d2dd90850..30793504e 100644 --- a/docs/source/reference/modding/index.rst +++ b/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 - 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 diff --git a/docs/source/reference/modding/convert_bump_mapped_mods.rst b/docs/source/reference/modding/texture-modding/convert-bump-mapped-mods.rst similarity index 100% rename from docs/source/reference/modding/convert_bump_mapped_mods.rst rename to docs/source/reference/modding/texture-modding/convert-bump-mapped-mods.rst diff --git a/docs/source/reference/modding/texture-modding/index.rst b/docs/source/reference/modding/texture-modding/index.rst new file mode 100644 index 000000000..3e0b359ee --- /dev/null +++ b/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 diff --git a/docs/source/reference/modding/texture-modding/native-mesh-format.rst b/docs/source/reference/modding/texture-modding/native-mesh-format.rst new file mode 100644 index 000000000..c2ddd26ba --- /dev/null +++ b/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 `_. + +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 + `_ +#. 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 diff --git a/docs/source/reference/modding/texture-modding/texture-basics.rst b/docs/source/reference/modding/texture-modding/texture-basics.rst new file mode 100644 index 000000000..09bd9a7ec --- /dev/null +++ b/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 `_. +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 `_) + 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 `_ 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 `_ +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 + } + } +