AnarchistGamers/openmw
1
0
Fork 0
mirror of https://gitlab.com/OpenMW/openmw.git synced 2025-08-03 15:27:13 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs - improve styling in headers and code blocks

Browse Source
This commit is contained in:
Cody Glassman 2025-07-04 06:59:05 -07:00
parent 1a08565a20
commit a5b8db70a4
14 changed files with 178 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/source/_ext/omw-lexers.py Normal file
View File

@ -0,0 +1,19 @@
from pygments.lexer import RegexLexer, bygroups
from pygments.token import Comment, Name, Operator, String, Text
from sphinx.highlighting import lexers
class OMWConfigLexer(RegexLexer):
name = 'openmwcfg'
aliases = ['openmwcfg']
filenames = ['openmw.cfg']
tokens = {
'root': [
(r'(\s*)(#.*$)', bygroups(Text.Whitespace, Comment.Single)),
(r'(\s*)([a-zA-Z0-9_.+-]+)(\s*(\+)?=\s*)(.*)', bygroups(Text.Whitespace, Name.Attribute, Operator, Operator, String)),
(r'.+\n', Text),
],
}
def setup(_):
lexers["openmwcfg"] = OMWConfigLexer()

14
docs/source/_static/theme-override.css
View File

@ -138,3 +138,17 @@ tbody tr:hover {
#left-sidebar {
overflow-y: scroll;
}
#content div[class^=highlight], #content pre.literal-block, p, h4, h5, h6 {
margin-bottom: 1.5rem;
}
h5 {
font-size: 1.15rem;
font-weight: 600;
}
h6 {
font-size: 1.08rem;
font-weight: 600;
}

3
docs/source/conf.py
View File

@ -43,7 +43,8 @@ extensions = [
'sphinx.ext.viewcode',
'sphinx.ext.autosectionlabel',
'sphinx_design',
'omw-directives'
'omw-directives',
'omw-lexers',
]
#autosectionlabel_prefix_document = True

6
docs/source/manuals/installation/install-game-files.rst
View File

@ -81,15 +81,15 @@ For Distributions Using `apt` (e.g., Ubuntu, Debian)
.. code:: console
sudo apt update
sudo apt install innoextract
$ sudo apt update
$ sudo apt install innoextract
For macOS using Homebrew
++++++++++++++++++++++++
.. code:: console
brew install innoextract
$ brew install innoextract
Once innoextract is installed, download the game from GOG. The downloaded file should be called ``setup_tes_morrowind_goty_2.0.0.7.exe`` or something similar. When ``innoextract`` is run on it, it will extract the files directly into the folder the ``setup.exe`` file is located. If you have a specific folder where you want it to be extracted to, for example in ``~/Documents/Games/Morrowind`` You can specify it with the ``-d`` flag.

6
docs/source/reference/lua-scripting/overview.rst
View File

@ -126,10 +126,12 @@ The options are:
Enable it in ``openmw.cfg`` the same way as any other mod:
::
.. code-block:: openmwcfg
:caption: openmw.cfg
data=path/to/my_lua_mod
content=my_lua_mod.omwscripts # or content=my_lua_mod.omwaddon
# or content=my_lua_mod.omwaddon
content=my_lua_mod.omwscripts
Now every time the player presses "X" on a keyboard, a message is shown.

1
docs/source/reference/modding/custom-models/pipeline-blender-collada-animated-creature.rst
View File

@ -177,7 +177,6 @@ definitions and events. At a minimum it needs to include at least animation
runforward: stop 4.433333
attack1: start 4.466667
attack1: stop 5.433333
...
The textkeys file is placed in the same folder as the model and matches the model's name.

2
docs/source/reference/modding/custom-models/pipeline-blender-collada-static-models.rst
View File

@ -168,7 +168,7 @@ the file path to the texture is incorrect and OpenMW can't find it.
To fix this you can open the exported ``.dae`` file in a text editor and check
the texture's filepath. In the example of this barrel model it's found on lines 13-17.
.. code::
.. code-block:: xml
<library_images>
<image id="id-image-4" name="the_barrel">

6
docs/source/reference/modding/custom-shader-effects.rst
View File

@ -23,7 +23,8 @@ dungeons.
To use this feature the :ref:`soft particles` setting must be enabled.
This setting can either be activated in the OpenMW launcher or changed in `settings.cfg`:
::
.. code-block:: ini
:caption: settings.cfg
[Shaders]
soft particles = true
@ -64,7 +65,8 @@ Blue and alpha channels are ignored.
To use this feature the :ref:`post processing <Post Processing>` setting must be enabled.
This setting can either be activated in the OpenMW launcher, in-game, or changed in `settings.cfg`:
::
.. code-block:: ini
:caption: settings.cfg
[Post Processing]
enabled = true

21
docs/source/reference/modding/extended.rst
View File

@ -91,7 +91,8 @@ The behavior of such a model:
The actual state toggling time depends on the sunrise/sunset time settings in `openmw.cfg`:
::
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback=Weather_Sunrise_Time,6
fallback=Weather_Sunset_Time,18
@ -102,7 +103,8 @@ These settings lead to the "night" starting at 20:00 and ending at 6:00.
The engine checks if the weather is bright enough to support the "interior day" mode using the Glare_View setting. If it is >= 0.5, the engine considers the weather bright.
::
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback=Weather_Clear_Glare_View,1
fallback=Weather_Foggy_Glare_View,0.25
@ -138,7 +140,8 @@ If you want to override walking animations, you should override ``xbase_anim_fem
To enable this feature, you should have this line in your settings.cfg:
::
.. code-block:: ini
:caption: settings.cfg
[Game]
use additional anim sources = true
@ -157,7 +160,8 @@ This feature conflicts with old mods which use scripted scabbards, arrows with p
The minimum you need is the ``xbase_anim_sh.nif`` file from the `Weapon Sheathing`_ mod and this line in your settings.cfg:
::
.. code-block:: ini
:caption: settings.cfg
[Game]
weapon sheathing = true
@ -205,7 +209,8 @@ Skeleton extensions
It is possible to inject custom bones into actor skeletons:
::
.. code-block:: ini
:caption: settings.cfg
[Game]
use additional anim sources = true
@ -323,14 +328,16 @@ General advices to create assets for this feature:
Groundcover mods can be registered in the openmw.cfg via "groundcover" entries instead of "content" ones:
::
.. code-block:: openmwcfg
:caption: openmw.cfg
groundcover=my_grass_mod.esp
Every static from such mod is treated as a groundcover object.
Also groundcover detection should be enabled via settings.cfg:
::
.. code-block:: ini
:caption: settings.cfg
[Groundcover]
enabled = true

30
docs/source/reference/modding/font.rst
View File

@ -3,8 +3,11 @@ Fonts
Default UI font and font used in magic scrolls are defined in ``openmw.cfg``:
fallback=Fonts_Font_0,MysticCards
fallback=Fonts_Font_2,DemonicLetters
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback=Fonts_Font_0,MysticCards
fallback=Fonts_Font_2,DemonicLetters
When there are no ``Fonts_Font_*`` lines in user's ``openmw.cfg``, built-in TrueType fonts are used.
Font used by console and another debug windows is not configurable (so ``Fonts_Font_1`` is unused).
@ -20,8 +23,11 @@ You can use --export-fonts command line option to write the converted font
They can be used instead of TrueType fonts if needed by specifying their ``.fnt`` files names in the ``openmw.cfg``. For example:
fallback=Fonts_Font_0,magic_cards_regular
fallback=Fonts_Font_2,daedric_font
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback=Fonts_Font_0,magic_cards_regular
fallback=Fonts_Font_2,daedric_font
In this example OpenMW will search for ``magic_cards_regular.fnt`` and ``daedric_font.fnt`` in the ``Fonts`` folder in data directories.
If they are not found, built-in TrueType fonts will be used as a fallback.
@ -35,16 +41,22 @@ Unlike vanilla Morrowind, OpenMW directly supports TrueType (``.ttf``) fonts. Th
OpenMW has build-in TrueType fonts: MysticCards, DemonicLetters and DejaVuLGCSansMono, which are used by default.
TrueType fonts are configured via ``openmw.cfg`` too:
fallback=Fonts_Font_0,MysticCards
fallback=Fonts_Font_2,DemonicLetters
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback=Fonts_Font_0,MysticCards
fallback=Fonts_Font_2,DemonicLetters
In this example, OpenMW will scan ``Fonts`` folder in data directories for ``.omwfont`` files.
These files are XML files with schema provided by MyGUI. OpenMW uses ``.omwfont`` files which name (without extension) matches ``openmw.cfg`` entries.
It is also possible to adjust the font size via ``settings.cfg`` file::
It is also possible to adjust the font size via ``settings.cfg`` file
[GUI]
font size = 16
.. code-block:: ini
:caption: settings.cfg
[GUI]
font size = 16
The ``font size`` setting accepts clamped values in range from 12 to 18.

12
docs/source/reference/modding/openmw-game-template.rst
View File

@ -36,7 +36,8 @@ and ``data=`` tells OpenMW what folders to look for meshes, textures, audio,
and other assets. The required lines would look like this, but with the paths
of course different on your system.
.. code::
.. code-block:: openmwcfg
:caption: openmw.cfg
content=template.omwgame
data="/home/someuser/example-suite/data"
@ -51,7 +52,8 @@ you need to remove or comment out the following lines from ``openmw.cfg``.
Not doing so will either produce errors or load Morrowind content, which you
probably do not want when you are making your own game.
.. code::
.. code-block:: openmwcfg
:caption: openmw.cfg
fallback-archive=Morrowind.bsa
fallback-archive=Tribunal.bsa
@ -70,8 +72,10 @@ are instead assigned through ``settings.cfg``. These models are player and NPC
animations, and meshes for the sky. In ``settings.cfg`` used by your OpenMW
install, add the following lines under the ``[Models]`` section.
.. code::
.. code-block:: ini
:caption: settings.cfg
[Models]
xbaseanim = meshes/BasicPlayer.dae
baseanim = meshes/BasicPlayer.dae
xbaseanim1st = meshes/BasicPlayer.dae
@ -103,7 +107,7 @@ need to be copied to ``resources/mygui`` folder found in your OpenMW installatio
folder. Overwrite any files aready in this folder. These files provide the
UI font, its definition, and some minor UI tweaks.
.. code::
.. code-block:: none
openmw_box.skin.xml
openmw_button.skin.xml

80
docs/source/reference/modding/paths.rst
View File

@ -133,8 +133,9 @@ This can't change until computers are able to read minds.
Lines with options have an option name, then an equals sign (``=``), then an option value.
Option names and values have leading and trailing whitespace trimmed, but whitespace within an option value is preserved - it's only removed if it's at the ends.
This means that these are all equivalent:
::
This means that these are all equivalent
.. code-block:: openmwcfg
data=some/dir
data=some/dir
@ -226,7 +227,10 @@ Navigate to the OpenMW installation directory, and open the ``openmw.cfg`` file
By default, this contains a warning at the top telling you that this is the local ``openmw.cfg`` and not to modify it.
However, for this kind of install, it's okay to do so, so you can remove this warning.
Change the start of the file from::
Change the start of the file from
.. code-block:: openmwcfg
:caption: openmw.cfg
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
@ -243,7 +247,10 @@ Change the start of the file from::
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
to::
to
.. code-block:: openmwcfg
:caption: openmw.cfg
data-local=userdata/data
user-data=userdata
@ -274,7 +281,10 @@ Navigate to the OpenMW installation directory, and open the ``openmw.cfg`` file
By default, this contains a warning at the top telling you that this is the local ``openmw.cfg`` and not to modify it.
However, you'll need to make a small change to create this kind of install.
Change the start of the file from::
Change the start of the file from
.. code-block:: openmwcfg
:caption: openmw.cfg
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
@ -291,7 +301,10 @@ Change the start of the file from::
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
to::
to
.. code-block:: openmwcfg
:caption: openmw.cfg
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
@ -330,7 +343,10 @@ From scratch
Start by installing OpenMW in the usual way.
Don't bother with first-time setup (i.e. telling it the location of an existing *Morrowind* installation).
In the default configuration directory (see `Configuration files and log files`_), create a file called ``openmw.cfg`` containing just::
In the default configuration directory (see `Configuration files and log files`_), create a file called ``openmw.cfg`` containing just
.. code-block:: openmwcfg
:caption: openmw.cfg
# select the game profile
config=Morrowind
@ -340,7 +356,10 @@ This will put the basic setup required to play *Morrowind* into a new ``Morrowin
Next, come up with a name for the subprofile you'll create for your mod list.
If you're following a modding guide, they've probably already given it a name, e.g. *Total Overhaul*, so that's the example we'll use.
Add a line to the ``Morrowind/openmw.cfg`` with the profile name, e.g.::
Add a line to the ``Morrowind/openmw.cfg`` with the profile name, e.g.
.. code-block:: openmwcfg
:caption: Morrowind/openmw.cfg
# select the mod list profile
config=Total Overhaul
@ -356,7 +375,10 @@ The ones in the ``Morrowind`` directory are used for all profiles for *Morrowind
The ones in the ``Morrowind/Total Overhaul`` directory are only used for the *Total Overhaul* profile, so you can set up that mod list and any settings it requires here, and they won't affect any other profiles you set up later.
Making changes within the launcher will affect these files and leave all the others alone.
If you want the *Total Overhaul* profile to keep its saved games etc. in a dedicated location instead of mixing them in with ones from another profile, you can add a ``user-data=…`` line to your ``Morrowind/Total Overhaul/openmw.cfg``, e.g.::
If you want the *Total Overhaul* profile to keep its saved games etc. in a dedicated location instead of mixing them in with ones from another profile, you can add a ``user-data=…`` line to your ``Morrowind/Total Overhaul/openmw.cfg``, e.g.
.. code-block:: openmwcfg
:caption: Morrowind/Total Overhaul/openmw.cfg
# put saved games in a saves directory next to this file
user-data=.
@ -377,12 +399,18 @@ You'll now have an empty directory e.g. at ``Documents\My Games\OpenMW\Original`
Next, move all the files that were already in the default configuration directory to the profile directory you just made.
Afterwards, the default configuration directory should only contain the profile directory you made.
Create a new ``openmw.cfg`` file in the default configuration directory containing::
Create a new ``openmw.cfg`` file in the default configuration directory containing
.. code-block:: openmwcfg
:caption: openmw.cfg
# select the profile
config=Original
In the ``openmw.cfg`` in the profile directory, add these lines::
In the ``openmw.cfg`` in the profile directory, add these lines
.. code-block:: openmwcfg
:caption: openmw.cfg
data-local=data
user-data=.
@ -402,9 +430,11 @@ Passing arguments on the command line lets you avoid this.
The basic idea is that you need to pass ``--replace config`` to ignore the configuration directories that the engine would have loaded because they were specified in ``openmw.cfg`` files, and pass each one you want to use instead with ``--config <directory path here>``.
E.g. if you've got a profile called *Morrowind* in your default configuration directory, and it's got a *Total Overhaul* subprofile, you could load it by running::
E.g. if you've got a profile called *Morrowind* in your default configuration directory, and it's got a *Total Overhaul* subprofile, you could load it by running
openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
.. code-block:: console
$ openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
You can put this command into a script or shortcut and use it to easily launch OpenMW with that profile.
@ -422,15 +452,17 @@ On Windows, you can create a desktop shortcut to run this command with these ste
* At the end of that field, add the arguments for the profile you want, e.g. ``--replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"``.
* Press *Apply* or *OK* to save the changes, and test the shortcut by double-clicking it.
On most Linux distros, you can create a ``.desktop`` file like this::
On most Linux distros, you can create a ``.desktop`` file like this
[Desktop Entry]
Type=Application
Name=OpenMW - Total Overhaul
GenericName=Role Playing Game
Comment=OpenMW with the Total Overhaul profile
Keywords=Morrowind;Reimplementation Mods;esm;bsa;
TryExec=openmw
Exec=openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
Icon=openmw
Categories=Game;RolePlaying;
.. code-block:: desktop
[Desktop Entry]
Type=Application
Name=OpenMW - Total Overhaul
GenericName=Role Playing Game
Comment=OpenMW with the Total Overhaul profile
Keywords=Morrowind;Reimplementation Mods;esm;bsa;
TryExec=openmw
Exec=openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
Icon=openmw
Categories=Game;RolePlaying;

44
docs/source/reference/modding/texture-modding/convert-bump-mapped-mods.rst
View File

@ -2,24 +2,9 @@
Normal maps from Morrowind to OpenMW
====================================
- `General introduction to normal map conversion`_
- `OpenMW normal-mapping`_
- `Activating normal-mapping shaders in OpenMW`_
- `Morrowind bump-mapping`_
- `MGE XE normal-mapping`_
- `Converting PeterBitt's Scamp Replacer`_ (Mod made for the MGE XE PBR prototype)
- `Tutorial - MGE`_
- `Converting Lougian's Hlaalu Bump mapped`_ (Morrowind's bump-mapping, part 1: *without* custom models)
- `Tutorial - Morrowind, Part 1`_
- `Converting Apel's Various Things - Sacks`_ (Morrowind's bump-mapping, part 2: *with* custom models)
- `Tutorial - Morrowind, Part 2`_
General introduction to normal map conversion
---------------------------------------------
:Authors: Joakim (Lysol) Berg, Alexei (Capo) Dobrohotov
:Updated: 2020-03-03
This page has general information and tutorials on how normal-mapping works in OpenMW and how you can make mods using
the old environment-mapped bump-mapping technique (such as `Netch Bump mapped`_ and `Hlaalu Bump mapped`_, and maybe the most
(in)famous one to previously give shiny rocks in OpenMW, the mod `On the Rocks`_!, featured in MGSO and Morrowind Rebirth) work better in OpenMW.
@ -58,14 +43,15 @@ Activating normal-mapping shaders in OpenMW
Before normal (and specular and parallax) maps can show up in OpenMW, their auto-detection needs to be turned on in
settings.cfg_-file. Add these rows where it would make sense:
::
.. code-block:: ini
:caption: settings.cfg
[Shaders]
auto use object normal maps = true
auto use terrain normal maps = true
[Shaders]
auto use object normal maps = true
auto use terrain normal maps = true
auto use object specular maps = true
auto use terrain specular maps = true
auto use object specular maps = true
auto use terrain specular maps = true
See OpenMW's wiki page about `texture modding`_ to read more about it.
@ -81,10 +67,11 @@ are processed which makes bump-mapped models look a bit better,
can make use of the gloss map channel in the bump map and can apply bump-mapping to skinned models.
Add this to settings.cfg_-file:
::
.. code-block:: ini
:caption: settings.cfg
[Shaders]
apply lighting to environment maps = true
[Shaders]
apply lighting to environment maps = true
But sometimes you may want them to look a bit better than in vanilla.
Technically you aren't supposed to convert bump maps because they shouldn't be normal maps that are supported by OpenMW as well,
@ -117,9 +104,6 @@ Converting PeterBitt's Scamp Replacer
-------------------------------------
**Mod made for the MGE XE PBR prototype**
:Authors: Joakim (Lysol) Berg
:Updated: 2016-11-11
So, let's say you've found out that PeterBitt_ makes awesome models and textures featuring physically based rendering
(PBR) and normal maps. Let's say that you tried to run his `PBR Scamp Replacer`_ in OpenMW and that you were greatly
disappointed when the normal map didn't seem to work. Lastly, let's say you came here, looking for some answers.
@ -161,9 +145,6 @@ Converting Lougian's Hlaalu Bump mapped
---------------------------------------
**Mod made for Morrowind's bump-mapping, without custom models**
:Authors: Joakim (Lysol) Berg, Alexei (Capo) Dobrohotov
:Updated: 2020-03-03
Converting normal maps made for the Morrowind's bump-mapping can be really easy or a real pain,
depending on a few circumstances. In this tutorial, we will look at a very easy,
although in some cases a bit time-consuming, example.
@ -192,9 +173,6 @@ Converting Apel's Various Things - Sacks
----------------------------------------
**Mod made for Morrowind bump-mapping, with custom models**
:Authors: Joakim (Lysol) Berg, Alexei (Capostrophic) Dobrohotov
:Updated: 2020-03-03
In part one of this tutorial, we converted a mod that only included modified Morrowind model (``.nif``)
files so that the bump maps could be loaded as normal maps.
We ignored those model files since they are not needed with OpenMW. In this tutorial however,

36
docs/source/reference/modding/texture-modding/texture-basics.rst
View File

@ -55,17 +55,20 @@ Simply create the textures with appropriate naming convention
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::
`settings.cfg </source/reference/modding/paths>`_ file
[Shaders]
auto use object normal maps = true
.. code-block:: ini
:caption: settings.cfg
auto use object specular maps = true
[Shaders]
auto use object normal maps = true
normal map pattern = _n
normal height map pattern = _nh
auto use object specular maps = true
specular map pattern = _spec
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.
@ -92,18 +95,21 @@ For example, if you wanted to add specular mapping to a terrain layer called roc
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::
The relevant settings are
[Shaders]
auto use terrain normal maps = true
.. code-block:: ini
:caption: settings.cfg
auto use terrain specular maps = true
[Shaders]
auto use terrain normal maps = true
terrain specular map pattern = _diffusespec
auto use terrain specular maps = true
# Also used for terrain normal maps
normal map pattern = _n
normal height map pattern = _nh
terrain specular map pattern = _diffusespec
# Also used for terrain normal maps
normal map pattern = _n
normal height map pattern = _nh
OSG native files
################