openmw Documentation

Syntax: openmw <options>
Allowed options:
  --config arg                          additional config directories
  --replace arg                         settings where the values from the
                                        current source should replace those
                                        from lower-priority sources instead of
                                        being appended
  --user-data arg                       set user data directory (used for
                                        saves, screenshots, etc)
  --resources arg (=resources)          set resources directory
  --help                                print help message
  --version                             print version information and quit
  --data arg (=data)                    set data directories (later directories
                                        have higher priority)
  --data-local arg                      set local data directory (highest
                                        priority)
  --fallback-archive arg (=fallback-archive)
                                        set fallback BSA archives (later
                                        archives have higher priority)
  --start arg                           set initial cell
  --content arg                         content file(s): esm/esp, or
                                        omwgame/omwaddon/omwscripts
  --groundcover arg                     groundcover content file(s): esm/esp,
                                        or omwgame/omwaddon
  --no-sound [=arg(=1)] (=0)            disable all sounds
  --script-all [=arg(=1)] (=0)          compile all scripts (excluding dialogue
                                        scripts) at startup
  --script-all-dialogue [=arg(=1)] (=0) compile all dialogue scripts at startup
  --script-console [=arg(=1)] (=0)      enable console-only script
                                        functionality
  --script-run arg                      select a file containing a list of
                                        console commands that is executed on
                                        startup
  --script-warn [=arg(=1)] (=1)         handling of warnings when compiling
                                        scripts
                                        0 - ignore warnings
                                        1 - show warnings but consider script as
                                        correctly compiled anyway
                                        2 - treat warnings as errors
  --load-savegame arg                   load a save game file on game startup
                                        (specify an absolute filename or a
                                        filename relative to the current
                                        working directory)
  --skip-menu [=arg(=1)] (=0)           skip main menu on game startup
  --new-game [=arg(=1)] (=0)            run new game sequence (ignored if
                                        skip-menu=0)
  --encoding arg (=win1252)             Character encoding used in OpenMW game
                                        messages:

                                        win1250 - Central and Eastern European
                                        such as Polish, Czech, Slovak,
                                        Hungarian, Slovene, Bosnian, Croatian,
                                        Serbian (Latin script), Romanian and
                                        Albanian languages

                                        win1251 - Cyrillic alphabet such as
                                        Russian, Bulgarian, Serbian Cyrillic
                                        and other languages

                                        win1252 - Western European (Latin)
                                        alphabet, used by default
  --fallback arg                        fallback values
  --no-grab [=arg(=1)] (=0)             Don't grab mouse cursor
  --export-fonts [=arg(=1)] (=0)        Export Morrowind .fnt fonts to PNG
                                        image and XML file in current directory
  --activate-dist arg (=-1)             activation distance override
  --random-seed arg (=)   seed value for random number generator

actor["inventory"] = sol::overload([](const LObject& o) { return Inventory<LObject>{ o }; },
    [](const GObject& o) { return Inventory<GObject>{ o }; });

// We can always read the value because OSG Cull doesn't modify `RefData`.
auto isEnabled = [](const Object& o) { return o.ptr().getRefData().isEnabled(); };

// Changing the value must be queued because `World::enable`/`World::disable` aside of
// changing `RefData` also adds/removes the object to the scene graph.
auto setEnabled = [context](const Object& object, bool enable) {
    // It is important that the lambda state stores `object` and not the result of
    // `object.ptr()` because when delayed will be executed the old Ptr can potentially
    // be already invalidated.
    context.mLuaManager->addAction([object, enable] {
        if (enable)
            MWBase::Environment::get().getWorld()->enable(object.ptr());
        else
            MWBase::Environment::get().getWorld()->disable(object.ptr());
    });
};

// Local scripts can only view the value (because in multiplayer local scripts
// will be client-side and we want to avoid synchronization issues).
LObjectMetatable["enabled"] = sol::readonly_property(isEnabled);

// Global scripts can both read and modify the value.
GObjectMetatable["enabled"] = sol::property(isEnabled, setEnabled);

docker build -f Dockerfile.LINUX_VERSION -t openmw.LINUX_VERSION .

docker run -v /path/to/openmw:/openmw:Z -e NPROC=2 -it openmw.LINUX_VERSION

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

.. toctree::
    :maxdepth: 2

    install-openmw
    install-game-files
    common-problems

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

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

If you have purchased "The Elder Scrolls III: Morrowind" `from GOG <https://www.gog.com/en/game/the_elder_scrolls_iii_morrowind_goty_edition>`_ and wish to extract the game files on a Linux system without using Wine, or on macOS, you can do so using `innoextract <https://constexpr.org/innoextract/>`_. First install innoextract.

For Distributions Using `apt` (e.g., Ubuntu, Debian)
++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code:: console

    $ sudo apt update
    $ sudo apt install innoextract

For macOS using Homebrew
++++++++++++++++++++++++

.. code:: console

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

.. code:: console

    $ innoextract ./setup_tes_morrowind_goty_2.0.0.7.exe -d ~/Documents/Games/Morrowind/

Assuming you used the filepath above, your ``.esm`` files will be located in ``~/Documents/Games/Morrowind/app/Data Files/``.

You can now run the OpenMW launcher, and from there run the installation wizard. Point it to your ``Morrowind.esm`` in the folder you extracted it to, and follow the instructions.

---------------------
XBox Game Pass for PC
---------------------

Default Morrowind Game Pass files are in a restricted WindowsApps folder 
that OpenMW cannot scan for content files in the usual way.
However, in the Xbox App for PC, inside the Manage game settings
(three-dots menu-> Manage), there is an option to enable advanced
management options (or similar phrasing) for Morrowind. Choose this
option and the app will prompt you to move the Morrowind files to a
new folder. Once done you can find ``Morrowind.esm`` in the folder you 
chose.

-----
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/``. The ~/Library folder is hidden by default. To get to it from the Installation Wizard popup, you will need to go to Users/YOUR_USERNAME_HERE/ and do ``CMD+SHIFT+PERIOD`` to reveal it. 

Linux
^^^^^
Debian/Ubuntu - using "Steam Proton" & "OpenMW launcher".

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 <https://github.com/OpenMW/example-suite/releases>`_
#.	Follow the platform-specific instructions in the zip file's ``Installation.md`` file.

---

## File: docs/source/manuals/installation/install-openmw.rst

==============
Install OpenMW
==============

Direct Download
===============

If you're not sure what any of the different methods mean, you should probably stick to this one.
Simply download the latest version for your operating system from
`github.com/OpenMW/openmw/releases <https://github.com/OpenMW/openmw/releases>`_
and run the install package once downloaded. It's now installed!

.. note::
	There is no need to uninstall previous versions
	as OpenMW automatically installs into a separate directory for each new version.
	Your saves and configuration are compatible and accessible between versions.

From Source
===========

Visit the `Development Environment Setup <https://wiki.openmw.org/index.php?title=Development_Environment_Setup>`_
section of the Wiki for detailed instructions on how to build the engine.

Ubuntu
======

A `Launchpad PPA <https://launchpad.net/~openmw/+archive/openmw>`_ is available.
Add it and install OpenMW.

.. code-block:: console

	$ sudo add-apt-repository ppa:openmw/openmw
	$ sudo apt update
	$ sudo apt install openmw

Arch Linux
==========

The binary package is available in the official [community] Repositories.
To install, simply run the following as root (or in sudo).

.. code-block:: console

	$ pacman -S openmw

Void Linux
==========

The binary package is available in the official Repository
To install simply run the following as root (or in sudo).

.. code-block:: console

	$ xbps-install openmw

Debian
======

OpenMW is available from the unstable (sid) repository of Debian contrib
and can be easily installed if you are using testing or unstable.
However, it depends on several packages which are not in stable,
so it is not possible to install OpenMW in Wheezy without creating a FrankenDebian.
This is not recommended or supported.

Fedora
======

OpenMW is available in the official repository of Fedora for versions 41 and up.
To install simply run the following as root (or in sudo), depending on what packages
you want.

``openmw`` includes the launcher, install wizard, iniimporter and the engine itself.

``openmw-cs`` includes the construction set.

``openmw-tools`` includes ``bsatool``, ``esmtool`` and ``niftest``.

.. code-block:: console

	$ dnf install openmw
	$ dnf install openmw-cs
	$ dnf install openmw-tools

Flatpak
=======

OpenMW is available as a flatpak. With flatpak installed, run the command below. It should show up on your desktop.

.. code-block:: console

	$ flatpak install openmw

NixOS
=====
OpenMW is available as a Nix package. To install, add the following Nix code to your NixOS Configuration.

.. code-block:: nix

	environment.systemPackages = [
	    pkgs.openmw
	];

---

## File: docs/source/manuals/openmw-cs/cell-view.rst

Cell View
#########

This window deals with the manipulation of instances within one or more cells.


Grid Snapping
*************

When manipulating one or more instances within the cell view, whether it's position,
rotation, or scale, the instances can be snapped to specific values configured within
the Edit->Preferences->3D Scene editing menu.

To begin snapping an instance, hold down CTRL when transforming the instance, whether
it's with the gizmos or by dragging the mouse, and the instance will snap to the closest
value as you manipulate the instance.

.. note::
    The key to enable snapping must be held before the transformation starts, otherwise snapping won't be enabled.


Snap to reference
=================

If you want to snap instances relative to another instance, you can select a snap target
with SHIFT + Middle Mouse Button to select a snap target. This will highlight the
instance in a yellow wireframe. Then, just with regular snapping, you hold down CTRL
when manipulating the instance(s) and the transformed values will be snapped to
the snap values relative to the snap target's world space.


Editing Instance Properties
===========================

In the 3D view, when you click with SHIFT + Left Mouse Button on an instance,
an Instances table view will open, if it's not open already. The clicked instance will
be highlighted in the Instances table.

---

## File: docs/source/manuals/openmw-cs/files-and-directories.rst

Files and Directories
#####################

In this chapter of the manual we will cover the usage of files and directories
by OpenMW CS. Files and directories are file system concepts of your operating
system, so we will not be going into specifics about that, we will only focus
on what is relevant to OpenMW CS.


Basics
******


Directories
===========

OpenMW and OpenMW CS use multiple directories on the file system. First of all
there is a *user directory* that holds configuration files and a number of
different sub-directories. The location of the user directory is hard-coded
into the CS and depends on your operating system.

================  =========================================
Operating System  User Directory
================  =========================================
GNU/Linux         ``~/.config/openmw/``
OS X              ``~/Library/Application Support/openmw/``
Windows           ``C:\Users\ *Username* \Documents\my games\OpenMW``
================  =========================================

In addition to to this single hard-coded directory both OpenMW and OpenMW CS
need a place to search for actual data files of the game: textures, 3D models,
sounds and record files that store objects in game; dialogues and so on. These
files are called *content files*. We support multiple such paths (we call them
*data paths*) as specified in the configuration. Usually one data path points
to the directory where the original Morrowind game is either installed or
unpacked to. You are free to specify as many data paths as you would like,
however, there is one special data path that, as described later, which is used
to store newly created content files.


Content files
=============

The original Morrowind engine by Bethesda Softworks uses two types of content
files: `ESM` (master) and `ESP` (plugin). The distinction between those two is
not clear, and often confusing. One would expect the `ESM` (master) file to be
used to specify one master, which is then modified by the `ESP` plugins. And
indeed: this is the basic idea. However, the official expansions were also made
as ESM files, even though they could essentially be described as really large
plugins, and therefore should have been `ESP` files. There were technical
reasons behind this decision – somewhat valid in the case of the original
engine, but clearly it is better to create a system that can be used in a more
sensible way.  OpenMW achieves this with our own content file types.

We support both ESM and ESP files, but in order to make use of new features in
OpenMW one should consider using new file types designed with our engine in
mind: *game* files and *addon* files, collectively called *content files*.


OpenMW content files
--------------------

The concepts of *Game* and *Addon* files are somewhat similar to the old
concept of *ESM* and *ESP*, but more strictly enforced. It is quite
straight-forward: If you want to make new game using OpenMW as the engine (a
so called *total conversion*) you should create a game file. If you want to
create an addon for an existing game file create an addon file. Nothing else
matters; the only distinction you should consider is if your project is about
changing another game or creating a new one. Simple as that.

Another simple thing about content files are the extensions: we are using
``.omwaddon`` for addon files and ``.omwgame`` for game files.


Morrowind content files
-----------------------

Using our content files is recommended for projects that are intended to use
the OpenMW engine. However, some players might wish to still use the
original Morrowind engine. In addition thousands of *ESP*/*ESM* files were
created since 2002, some of them with really outstanding content. Because of
this OpenMW CS simply has no other choice but to support *ESP*/*ESM* files. If
you decide to choose *ESP*/*ESM* file instead of using our own content file
types you are most likely aiming at compatibility with the original engine. This
subject is covered in its own chapter of this manual.


.. TODO This paragraph sounds weird

The actual creation of new files is described in the next chapter. Here we are
going to focus only on the details you need to know in order to create your
first OpenMW CS file while fully understanding your needs. For now let’s just
remember that content files are created inside the user directory in the the
``data`` subdirectory (that is the one special data directory mentioned
earlier).


Dependencies
------------

Since an addon is supposed to change the game it follows that it also depends
on the said game to work. We can conceptualise this with an example: your
modification is changing the price of an iron sword, but what if there is no
iron sword in game? That's right: we get nonsense. What you want to do is tie
your addon to the files you are changing. Those can be either game files (for
example when making an expansion island for a game) or other addon files
(making a house on said island). Obviously It is a good idea to be dependent
only on files that are really changed in your addon, but sadly there is no
other way to achieve this than knowing what you want to do. Again, please
remember that this section of the manual does not cover creating the content
files – it is only a theoretical introduction to the subject. For now just keep
in mind that dependencies exist, and is up to you to decide whether your
content file should depend on other content files.

Game files are not intended to have any dependencies for a very simple reasons:
the player is using only one game file (excluding original and the dirty
ESP/ESM system) at a time and therefore no game file can depend on another game
file, and since a game file makes the base for addon files it can not depend on
addon files.


Project files
-------------

Project files act as containers for data not used by the OpenMW game engine
itself, but still useful for OpenMW CS. The shining examples of this data
category are without doubt record filters (described in a later chapter of the
manual). As a mod author you probably do not need or want to distribute project
files at all, they are meant to be used only by you and your team.

.. TODO "you and your team": is that correct?

As you would imagine, project files make sense only in combination with actual
content files. In fact, each time you start to work on new content file and a
project file was not found, one will be created. The extension of project files
is ``.project``. The whole name of the project file is the whole name of the
content file with appended extension. For instance a ``swords.omwaddon`` file
is associated with a ``swords.omwaddon.project`` file.

Project files are stored inside the user directory, in the ``projects``
subdirectory. This is the path location for both freshly created project files,
and a place where OpenMW CS looks for already existing files.


Resource files
==============

.. TODO  This paragraph sounds weird

Unless we are talking about a fully text based game, like Zork or Rogue, one
would expect that a video game is using some media files: 3D models with
textures, images acting as icons, sounds and anything else. Since content
files, no matter whether they are *ESP*, *ESM* or new OpenMW file type, do not
contain any of those, it is clear that they have to be delivered with a
different file. It is also clear that this, let’s call it “resources file“,
has to be supported by the engine. Without code handling those files it is
nothing more than a mathematical abstraction – something, that lacks meaning
for human beings.  Therefore this section must cover ways to add resources
files to your content file, and point out what is supported. We are going to do
just that.  Later, you will learn how to make use of those files in your
content.


Audio
-----

OpenMW uses FFmpeg_ for audio playback, and so we support every audio type
supported by that library. This makes a huge list. Below is only small portion
of the supported file types.

mp3 (MPEG-1 Part 3 Layer 3)
   A popular audio file format and de facto standard for storing audio. Used by
   the Morrowind game.

ogg
   An open source, multimedia container file using a high quality Vorbis_ audio
   codec. Recommended.


Video
-----

Video As in the case of audio files, we are using FFmepg to decode video files.
The list of supported files is long, we will cover only the most significant.

bik
   Videos used by the original Morrowind game.

mp4
   A multimedia container which use more advanced codecs (MPEG-4 Parts 2, 3 and
   10) with a better audio and video compression rate, but also requiring more
   CPU intensive decoding – this makes it probably less suited for storing
   sounds in computer games, but good for videos.

webm
   A new, shiny and open source video format with excellent compression. It
   needs quite a lot of processing power to be decoded, but since game logic is
   not running during cutscenes we can recommend it for use with OpenMW.

ogv
   Alternative, open source container using Theora_ codec for video and Vorbis for audio.



Textures and images
-------------------

The original Morrowind game uses *DDS* and *TGA* files for all kinds of two
dimensional images and textures alike. In addition, the engine supported *BMP*
files for some reason (*BMP* is a terrible format for a video game). We also
support an extended set of image files – including *JPEG* and *PNG*. *JPEG* and
*PNG* files can be useful in some cases, for instance a *JPEG* file is a valid
option for skybox texture and *PNG* can useful for masks. However, please keep
in mind that *JPEG* images can grow to large sizes quickly and are not the best
option with a DirectX rendering backend. You probably still want to use *DDS*
files for textures.



.. Hyperlink targets for the entire document

.. _FFmpeg: https://ffmpeg.org
.. _Vorbis: http://www.vorbis.com
.. _Theora: https://www.theora.org

---

## File: docs/source/manuals/openmw-cs/foreword.rst

Foreword
########

<Some introductory lines here, explain nomenclature and abbreviations>


How to read the manual
**********************

The manual can be roughly divided into two parts: a tutorial part consisting of
the first two (three) chapters and the reference manual. We recommend all
readers to work through the tutorials first, there you will be guided through
the creation of a fairly simple mod where you can familiarise yourself with the
record-based interface. The tutorials are very simple and teach you only what
is necessary for the task, each one can be completed in under half an hour. It
is strongly recommended to do the tutorials in order.

When you are familiar with the CS in general and want to write your own mods it
is time to move on to the reference part of the manual. The reference chapters
can be read out of order, each one covers only one topic.