4
In this chapter of the manual we will cover the usage of files and directories
5
by OpenMW CS. Files and directories are file system concepts of your operating
6
system, so we will not be going into specifics about that, we will only focus
7
on what is relevant to OpenMW CS.
17
OpenMW and OpenMW CS us multiple directories on the file system. First of all
18
there is a *user directory* that holds configuration files and a number of
19
different sub-directories. The location of the user directory is hard-coded
20
into the CS and depends on your operating system.
22
================ =========================================
23
Operating System User Dircetory
24
================ =========================================
25
GNU/Linux ``<whatever>``
26
OS X ``~/Library/Application Support/openmw/``
27
Windows ``<whatever>``
28
================ =========================================
30
In addition to to this single hard-coded directory both OpenMW and OpenMW CS
31
need a place to seek for a actuals data files of the game: textures, 3D models,
32
sounds and record files that store objects in game; dialogues an so one. These
33
files are called *content files*. We support multiple such paths (we call them
34
*data paths*) as specified in the configuration. Usually one data path points
35
to the directory where the original Morrowind game is either installed or
36
unpacked to. You are free to specify as many data paths as you would like,
37
however, there is one special data path that, as described later, which is used
38
to store newly created content files.
44
The original Morrowind engine by Bethesda Softworks uses two types of content
45
files: `esm` (master) and `esp` (plugin). The distinction between those two is
46
not clear, and often confusing. One would expect the `esm` (master) file to be
47
used to specify one master, which is then modified by the `esp` plugins. And
48
indeed: this is the basic idea. However, the official expansions were also made
49
as ESM files, even though they could essentially be described as really large
50
plugins, and therefore would rather use `esp` files. There were technical
51
reasons behind this decision – somewhat valid in the case of the original
52
engine, but clearly it is better to create a system that can be used in a more
53
sensible way. OpenMW achieves this with our own content file types.
55
We support both ESM and ESP files, but in order to make use of new features in
56
OpenMW one should consider using new file types designed with our engine in
57
mind: *game* files and *addon* files, collectively called *content files*.
63
The concepts of *Game* and *Addon* files are somewhat similar to the old
64
concept of *ESM* and *ESP*, but more strictly enforced. It is quite
65
straight-formward: If you want to make new game using OpenMW as the engine (a
66
so called *total conversion*) you should create a game file. If you want to
67
create an addon for an existing game file create an addon file. Nothing else
68
matters; the only distinction you should consider is if your project is about
69
changing another game or creating a new one. Simple as that.
71
Another simple thing about content files are the extensions: we are using
72
``.omwaddon`` for addon files and ``.omwgame`` for game files.
75
Morrowind content files
76
-----------------------
78
Using our content files is recommended for projects that are intended to used
79
with the OpenMW engine. However, some players might wish to still use the
80
original Morrowind engine. In addition thousands of *ESP*/*ESM* files were
81
created since 2002, some of them with really outstanding content. Because of
82
this OpenMW CS simply has no other choice but to support *ESP*/*ESM* files. If
83
you decid to choose *ESP*/*ESM* file instead of using our own content file
84
types you are most likely aimng at compatibility with the original engine. This
85
subject is covered in it own chapter of this manual.
88
.. TODO This paragraph sounds weird
90
The actual creation of new files is described in the next chapter. Here we are
91
going to focus only on the details you need to know in order to create your
92
first OpenMW CS file while fully understanding your needs. For now let’s jut
93
remember that content files are created inside the user directory in the the
94
``data`` subdirectory (that is the one special data directory mentioned
101
Since an addon is supposed to change the game it follows that it also depends
102
on the said game to work. We can conceptualise this with an examples: your
103
modification is the changing prize of an iron sword, but what if there is no
104
iron sword in game? That's right: we get nonsense. What you want to do is tie
105
your addon to the files you are changing. Those can be either game files (for
106
example when making an expansion island for a game) or other addon files
107
(making a house on said island). Obviously It is a good idea to be dependent
108
only on files that are really changed in your addon, but sadly there is no
109
other way to achieve this than knowing what you want to do. Again, please
110
remember that this section of the manual does not cover creating the content
111
files – it is only a theoretical introduction to the subject. For now just keep
112
in mind that dependencies exist, and is up to you to decide whether your
113
content file should depend on other content files.
115
Game files are not intend to have any dependencies for a very simple reasons:
116
the player is using only one game file (excluding original and the dirty
117
ESP/ESM system) at a time and therefore no game file can depend on other game
118
file, and since a game file makes the base for addon files it can not depend on
125
Project files act as containers for data not used by the OpenMW game engine
126
itself, but still useful for OpenMW CS. The shining example of this data
127
category are without doubt record filters (described in a later chapter of the
128
manual). As a mod author you probably do not need or want to distribute project
129
files at all, they are meant to be used only by you and your team.
131
.. TODO "you and your team": is that correct?
133
As you would imagine, project files make sense only in combination with actual
134
content files. In fact, each time you start to work on new content file and a
135
project file was not found, one will be created. The extensio of project files
136
is ``.project``. The whole name of the project file is the whole name of the
137
content file with appended extension. For instance a ``swords.omwaddon`` file
138
is associated with a ``swords.omwaddon.project`` file.
140
Project files are stored inside the user directory, in the ``projects``
141
subdirectory. This is the path location for both freshly created project files,
142
and a place where OpenMW CS looks for already existing files.
148
.. TODO This paragraph sounds weird
150
Unless we are talking about a fully text based game, like Zork or Rogue, one
151
would expect that a video game is using some media files: 3D models with
152
textures, images acting as icons, sounds and anything else. Since content
153
files, no matter whether they are *ESP*, *ESM* or new OpenMW file type, do not
154
contain any of those, it is clear that they have to be delivered with a
155
different file. It is also clear that this, let’s call it “resources file“,
156
has to be supported by the engine. Without code handling those files it is
157
nothing more than a mathematical abstraction – something, that lacks meaning
158
for human beings. Therefore this section must cover ways to add resources
159
files to your content file, and point out what is supported. We are going to do
160
just that. Later, you will learn how to make use of those files in your
167
OpenMW uses FFmpeg_ for audio playback, and so we support every audio type
168
supported by that library. This makes a huge list. Below is only small portion
169
of the supported file types.
171
mp3 (MPEG-1 Part 3 Layer 3)
172
A popular audio file format and de facto standard for storing audio. Used by
176
An open source, multimedia container file using a high quality Vorbis_ audio
183
Video As in the case of audio files, we are using FFmepg to decode video files.
184
The list of supported files is long, we will cover only the most significant.
187
Videos used by the original Morrowind game.
190
A multimedia container which use more advanced codecs (MPEG-4 Parts 2, 3 and
191
10) with a better audio and video compression rate, but also requiring more
192
CPU intensive decoding – this makes it probably less suited for storing
193
sounds in computer games, but good for videos.
196
A new, shiny and open source video format with excellent compression. It
197
needs quite a lot of processing power to be decoded, but since game logic is
198
not running during cutscenes we can recommend it for use with OpenMW.
201
Alternative, open source container using Theora_ codec for video and Vorbis for audio.
208
The original Morrowind game uses *DDS* and *TGA* files for all kinds of two
209
dimensional images and textures alike. In addition, the engine supported *BMP*
210
files for some reason (*BMP* is a terrible format for a video game). We also
211
support an extended set of image files – including *JPEG* and *PNG*. *JPEG* and
212
*PNG* files can be useful in some cases, for instance a *JPEG* file is a valid
213
option for skybox texture and *PNG* can useful for masks. However, please keep
214
in mind that *JPEG* images can grow to large sizes quickly and are not the best
215
option with a DirectX rendering backend. You probably still want to use *DDS*
220
.. Hyperlink targets for the entire document
222
.. _FFmpeg: http://ffmpeg.org
223
.. _Vorbis: http://www.vorbis.com
224
.. _Theora: http://www.theora.org
added
removed
docs/cs-manual/source/files-and-directories.rst
