@chapter{ Resource files and containers }

Doomsday uses multiple kinds of resource files:
@list/thin{
    @item Plain data (e.g., @file{.png} image, @file{.lmp} file).
    @item Definition files (@file{.ded}).
    @item Containers (@file{.wad}, @file{.pk3}).
}

@link{WADs}{http://en.wikipedia.org/wiki/Doom_WAD} are the original Doom
engine data container format. By default all resources such as wall textures,
menu graphics and fonts, background music and sound effects are loaded from
WAD files. Doomsday has a mechanism that allows replacing these resources with
external resource files placed in specific directories.

External resource files are easy to use. They do not require making changes to
any configuration or definition files. As long as a resource file is placed in
the correct directory, Doomsday will load and use it automatically.

Resources are divided into a number of classes. Each class has its own
subdirectory under the @file{ data/<gamemode>/ } directory. The table below
lists the resource classes and gives a brief description of each.

@table{25 75}{
	@header{Resource Class} @tab @header{Description} @row{single}
	Textures @tab Textures for walls and flats (floors and ceilings) @row
	Flats @tab Textures just for flats (floors and ceilings) @row
	Patches @tab Graphics for menus, fonts and sprite frames @row
	LightMaps @tab Textures for dynamic lights @row
	Music @tab Background music @row
	Sfx @tab Sound effects
}

Another example: sound effects for Doom II would be placed in the directory 
@file{ data/doom2/sfx/ }.

$ TODO: Is the following correct?
The resource class directory can have a subdirectory for each game mode.
For example, textures meant only for Final Doom: Plutonia Experiment would be
placed in the directory @file{ data/jdoom/textures/doom2-plut/ }.

When Doomsday looks for an external resource, it first checks the current game
mode's subdirectory. If no suitable resource is found there, the class
directory is searched instead. 

$ TODO: What is this about? Move to a move appropriate place. -jk
$
$ In some cases two modes can have a resource with the same name. This is a
$ problem if the same resource file can't be used by both modes.



@section{ Automatic loading of resources }

All WAD, PK3, ZIP and LMP files placed in the @file{ data/<game>/auto/ }
directory will be automatically loaded at startup. The data files are loaded
in alphabetical order, including all the subdirectories of the @file{auto}
directory.

All DED files placed in the @file{ defs/<game>/auto/ } directory will be
automatically read at startup. The definition files are also loaded in
alphabetical order, including all the subdirectories of the @file{auto}
directory.

Virtual files (from inside a container) in the @file{auto} directories will
also be loaded.



@section{ Virtual directory mapping }

Virtual directory mapping allows you to make the contents of one directory
appear inside another directory at runtime. For example, you could have a
directory called @file{MyAuto} with a set of data files somewhere on your hard
drive. You could map this directory to @file{data/<game>/auto}, which would
cause @file{MyAuto} to behave as though it was an auto-loading directory.

A virtual directory mapping is defined using the @opt{-vdmap} option. It takes
the source and destination directories as parameters. For example:

@ifdef{WIN32}{
    @code{-vdmap "D:\Games\MyAuto" "C:\Doomsday\Data\jDoom\Auto"}
}
@else{
    @code{-vdmap /home/username/myauto /usr/share/doomsday/data/jdoom/auto}
}

You can define an unlimited number of virtual directory mappings using
multiple @opt{-vdmap} options.

Note, however, that @opt{-vdmap} only affects real files. It does not affect
virtual files in PK3s or anywhere else. The virtual directory mappings are
tried when all other methods of finding a file fail. So, all real files and
virtual files override @opt{-vdmap}.



@section{ PK3 files }

Doomsday supports the PK3 format. PK3 files are identical to ZIP archives,
with the exception of using @file{.pk3} instead of @file{.zip} as the file
extension. Encrypted archives are not allowed. If you try to load an encrypted
or password protected ZIP/PK3 file, you will get an error message. Wikipedia
has more information about
@link{PK3s}{http://en.wikipedia.org/wiki/PK3_(file_extension)}.

PK3 files are loaded using the @opt{-file} option, for example @opt{-file
some.pk3}. 

$will try loading @file{some.pk3} first from the runtime directory
$and then from the data directory.

A PK3 contains a set of files organized into directories. When a PK3 is
loaded, all of them become virtual files that Doomsday can access just like
the regular files on your hard drive. The end result is the same as if you had
unpacked the PK3 into your Doomsday base directory. (No actual unpacking is
done.) For example, the PK3 could have the file
@file{data/jdoom/auto/superb.wad}.

PK3 files can be created with just about any ZIP utility. Make sure all the
files inside the archive have the correct paths, or otherwise Doomsday may not
be able to find them.


@subsec{ Automatic remapping inside PK3 }

Files in the root of a PK3 are subject to automatic relocation based on file
name extension: PK3/ZIP/LMP/WAD are mapped to @file{data/<game>/auto/} and DED
goes to @file{defs/<game>/auto/}. For example, placing @file{test.ded} into
the root of a PK3 has the same end result as placing @file{test.ded} into
@file{defs/<game>/auto/}.

Since this automatic mapping only affects single files, it is also possible to
request mapping manually by adding a special prefix character to the name of a
directory in the root of a PK3. If the directory begins with @file{#}, it is
mapped into @file{data/<game>/auto/}; if it begins with @file{@@}, it is
mapped into @file{defs/<game>/auto/}.

@samp{@file{#CoolStuff/Some.pk3} => @file{data/<game>/auto/CoolStuff/Some.pk3}}



@section{ WAD files }

Doomsday has a number of advanced features for handling WAD files.


@subsec{ Definitions inside WAD }

After all DED files have been processed, the engine will check through all the
loaded WAD files for lumps named @file{DD_DEFNS}. All the lumps with that name
are processed just as if they were DED files, i.e. they should contain a DED
file in plain text format. The @file{DD_DEFNS} lumps are applied in the order
in which they have been loaded.


@subsec{ WAD as a virtual file container }

Another special lump used by Doomsday is @file{DD_DIREC}. It contains a table
that translates file paths to lump names. An example is shown below:

@samp{
@pre{FILE001  /Md2/jDoom/Some.md2
FILE002  Another.ded}
}

Each line in @file{DD_DIREC} contains a lump/path pair. The paths that begin
with a (back)slash are interpreted as paths that start from the Doomsday base
directory (set with @opt{-basedir}) and paths that don't begin with a
(back)slash are located in the runtime directory. The engine will first search
the @file{DD_DIREC}@nsp{s} before opening any file for reading. Note, however,
that all kinds of files are not loaded using the @file{DD_DIREC}@nsp{s}: for
instance demos (which are compressed with the LZSS library) must always be
loaded from real files.

skyjake has created a simple utility for automatically creating a WAD file
that contains the current directory and all its subdirectories plus a
@file{DD_DIREC} lump that has (with a high probability) a unique lump name for
each file. You can invoke the utility like this:

@code{ wadtool myfiles.wad /data/jdoom/textures/ }

This would create a WAD file that contains all the files from the current
directory. When writing the @file{DD_DIREC} table, the prefix
"/data/jdoom/textures/" would be added to each file name. @bin{wadtool} is
available in the Doomsday source repository under @file{/tools/wadtool}.



@section{ Lump assemblies instead of WADs }

The automatic loading of data files can be utilised to load directories that
contain individual data lumps. This kind of a directory is called a "lump
assembly" and it can be used instead of a WAD file. Note that a lump assembly
can only be loaded via the autoload mechanism (but it can be inside of a PK3
that is loaded manually).

By default the contents of a lump assembly are loaded in alphabetical order.
However, some kinds of data require that the lumps are in a specific order
(for instance map data). You have two options if you want to enforce a
specific order:

@list{

@item You can use name prefixes that are used to sort the lumps but are
ignored when the lump names are determined. The length of the prefix can be
1..9 characters long. You specify the length of the prefix by adding an
extension to the name of the directory that contains the lumps. An example
that uses a prefix with 3 characters:

@samp{@file{Data/Game/Auto/DirWithPrefix.3/01_LUMPNAME.lmp}}

The first three characters of the file name are ignored (@file{01_}) and
@file{LUMPNAME} becomes the name of the lump.

@item You can put a WAD inside the assembly.

}

The assembly can be built using a hierarchy of directories.  For
example the contents of the PK3 might be:

@samp{@pre{#assembly/
   data1.lmp
   data2.lmp
   powerplant.2/
      a-E2M3.lmp
      b-THINGS.lmp
   xyz.lmp}
}

@file{#assembly} would be mapped to @file{Data/<Game>/Auto/assembly/}.



@chapter{ Resource types }

@section{ Textures and flats }

Normal wall textures and flats can be replaced with PNG, JPG, TGA (Truevision
Targa), or PCX (Zsoft Paintbrush) images. The engine currently supports these
image formats:

@table{40 15 15 15 15}{
	@header{Pixel size} @tab @header{PCX} @tab @header{PNG} @tab @header{JPG} @tab @header{TGA}
	@row{single}
	8-bit (paletted)*      @tab Yes @tab Yes @tab -   @tab -     @row
	16-bit                 @tab -   @tab -   @tab -   @tab -     @row
	24-bit                 @tab -   @tab Yes @tab Yes @tab Yes** @row
	32-bit (alpha channel) @tab -   @tab Yes @tab -   @tab Yes**
}

@caption{* = the palette does not have to match the palette of the game @br
** = TGAs must be type 2 (uncompressed, unmapped RGB)}

@notice{32-bit images are just 24-bit images with an additional 8 bits per pixel
for the alpha channel.}

The recommended format for high-resolution textures is paletted PNG. It is the
easiest format in which to distribute the textures due to its small size.
Since the palette doesn't have to be the same as the game's, it should be
enough for many textures.

High-resolution textures can be of any size. The engine will render them
scaled so that they fit the size of the original texture. This means the
aspect ratio of the new texture doesn't have to be the same as of the original
texture. Note that the engine will have to resize all textures so that their
dimensions are powers of two (e.g. 32, 64, 128, 256). This means TGA/PNG
textures whose width and height are already powers of two can be loaded
faster.

Color keying allows having transparent pixels in an image format that has no
alpha channel. Color keying is applied if the file name of the image ends in
"-ck", for example @file{brnbigc-ck.png}. Both cyan (0,255,255) and purple
(255,0,255) are used as keys, and will be replaced with transparent pixels.

Examples:

@list{

@item To create a high-resolution texture for the wall texture STARTAN3 you'd
place a TGA file named @file{STARTAN3.tga} or a PNG file named
@file{STARTAN3.png} into the @file{Textures} directory.

@item In order to replace the flat FLOOR7_2, you'd to put @file{FLOOR7_2.png}
into the @file{Flats} directory. It is also possible to have flats in the
@file{Textures} directly if they are prefixed @file{Flat-}. For instance,
@file{Flat-FLOOR7_2.tga}.

}

@notice{ The file names of the high-resolution textures must match the
@em{texture} names, not the names of the patches that make up the textures.
For example: DOOR2_5 is a patch name, DOOR3 is the texture that uses DOOR2_5.
}

To disable high-resolution textures use the command line option
@opt{-nohightex}. The option @opt{-texdir} can be used to change the directory
from which the textures are searched.



@section{ Patches }

Patches are images that are commonly used in game menus and intermission
screens. Like textures, patches can be replaced with TGA, PNG or PCX images.
The @file{Patches} resource class directory is searched using the lump names
of the original patches. For example, to replace the Doom menu title, you
would place the file @file{m_doom.png} to the @file{Patches} directory.

The original data lumps are required even if an external resource is found,
because the original data includes information about offsets and the on-screen
size of the patch. This means the image from the external resource can be of
any arbitrary resolution: it will be scaled to match the original patch.

$ TODO: Is this correct information?
$
$ Currently external patch resources are not precached, which may cause slight
$ delays when the patches are first loaded.



@section{ Sprite frames }

Sprite frames are patches. They can be replaced with external resources just
like all other patches. The same restrictions apply, though: the dimensions of
the external resource do not affect the actual size of the sprite frame. This
means the external resources must really be @em{high-resolution} versions of
the original images. Otherwise the size and/or aspect ratio will not be right
for the resource.

For example, in order to replace the Doom medikit (lump name MEDIA0), one
would place the file @file{media0.png} into the @file{Patches} directory.

Doom uses color-mapping to change specific colors in some sprites, e.g., the
players, so that the same image can be displayed with different coloring
without having multiple copies of it in memory. Doomsday will not change
colors on the fly in external resources. However, color-mapped versions of
sprite frames can each have their own external resources. To indicate that a
resource is color-mapped, its name is formed like this:

@ind{@file{(patchName)-table(classNum)(tableNum).ext}}

@file{(patchName)} is the sprite frame lump name. @file{(classNum)} is the
number of the color translation class. This number is always zero in Doom and
Heretic. In Hexen, it's the player's class (0=Fighter, 1=Cleric, 2=Mage).
@file{tableNum} is the index number of the color translation table. Doom and
Heretic have 4 tables, Hexen has 8. For example: @file{playa1-table01-ck.png}
would be the Doom player sprite frame A1 with color table 1. The @file{-ck}
suffix makes the image color keyed (i.e. special colors indicate transparent
pixels).



@section { Raw screens }

Some background pictures are in the raw screen format, which is used to store
320 x 200 pixel paletted images. A lump containing a raw screen image (for
example Heretic's TITLEPIC) is exactly 320 x 200 = 64000 bytes long. Raw
screens can be replaced with external resources in the @file{Patches}
directory.



@section{ Light maps }

Light maps are monochrome images that can be used with dynamic lights. The
dimensions of a light map must be powers of two, for example 256 x 256. If the
map contains an alpha channel, the actual color values are ignored; only the
alpha values are significant. If the map doesn't have an alpha channel, one is
generated by averaging the color values of the image.

Example: If you assign the light map "Round" to a light source, images with
that file name are searched from the @file{LightMaps} directory. The accepted
image formats are PCX, TGA and PNG. If @file{Round.pcx}, @file{Round.tga} or
@file{Round.png} is found, it will be loaded.



@section{ Detail textures }

Detail textures are grayscale images that are rendered on top of normal
textures when walls and planes are viewed from close by. A signed-add blending
is used, which lets the detail texture either darken or brighten the
underlying texture: black => darker, gray => no change, white => brighter.

Detail textures can be assigned to specific wall textures and flats using
Detail definitions.

Detail textures can be loaded from external image resources (from the
@file{Textures} directory), or PCX images and raw image data stored inside a
WAD lump. When using the @opt{-file} option to load detail texture lumps, the
file names of the images become lump names.

If an external resource is used as the detail texture, its dimensions must be
powers of two (for example 128x64 or 256x256). The image file must be in one
of the supported image file formats.

PCX images used as detail textures must have a color depth of 8 bits and their
width and height must be powers of two. The palette should be a grayscale one.
It is possible to use other colors but the result can be weird due to the way
the blending of detail textures is done.

If the source data is a raw image, it must be either 64x64, 128x128 or 256x256
pixels in size. Raw images contain only the pixel values, (one byte per pixel)
and have only one color component per pixel (they're black and white images),
which means the lump or file that contains the detail texture can either be
4096, 16384 or 65536 bytes long.

Using the default scaling, the pixels of detail textures are four times
smaller than the pixels of regular textures.

The console variables @var{rend-tex-detail},
@var{rend-tex-detail-far}, @var{rend-tex-detail-strength} and
@var{rend-tex-detail-scale} control the rendering of detail textures.



@section{ 3D models as particles }

3D models can be used as particles in a particle generator. In the particle
generator definition, set the particle stage's type to one of the
@opt{pt_model} flags. The following would make the stage use particle model
number 13:

@code{Type = "pt_model13";}

In the particle stage definition, remember to set a color for the stage. If
the color is not specified, the default values will result in a completely
transparent particle model.

The model definition must have a matching ID. For example, particle model
number 13 uses the following ID:

@code{ID = "Particle13";}

For further details see the DED Reference.



@section{ Music }

Doomsday can play various external music files using the @link{FMOD
library}{http://www.fmod.org/}. FMOD supports many music file formats
including MP3, OGG, MOD and S3M (mods are a good choice due to their good
quality/size ratio). External music files can be played at any time using the
@cmd{playext} console command.

As an alternative to FMOD there is the SDL_mixer audio plugin. It is used
automatically in case the FMOD audio plugin is not installed or fails to load
for some reason. However, SDL_mixer's playback quality is not as high and it
does not support 3D sound effects.

$@notice{ On some systems, using FMOD with Doomsday has caused lock-ups or
$other unwanted behavior. If this appears to be the case for you, you should
$disable FMOD with the @opt{-nofmod} option. However, this will also make it
$impossible to play external music files such as MP3s. }

Like other external resources, placing a music file into the @file{Music}
resource class directory is enough. The file name must match the lump name of
the original music data lump. For example, to replace the music for Doom's
first episode's second map, the file @file{d_e1m2.mp3} would be placed in the
@file{Music} directory.

It is also possible to store music files into a WAD. Again, you must name the
lumps so that they match the lumps of the original songs, and are thus loaded
instead of them. Any music files supported by FMOD can be loaded from a WAD.

Another way to specify an external resource file is to use the @opt{Ext} key
of a Music definition (in Audio.ded). An example of editing the definitions:
You have a terrific song called @file{song.mp3} and you'd like to hear it
instead of Doom's regular "e1m2".

@list/enum{
    
@item The first thing to decide is whether you want to play the
song from where it's currently located, or do you want to move it under
the Doomsday directory. In the latter case it would be easy to
distribute the song and its definition file to others, since they
wouldn't have to worry about where the music file is. If you decide
to move the song, create a directory under the @file{ Doomsday/Data/jDoom/ } directory called @file{Music}. Another logical choice could be
@file{ Doomsday/Music/ }. Then copy the song into the created directory.

@item Open @file{Audio.ded} in a text editor. In it, you will find
a bunch of Music definitions, including:

@code{Music @{ ID = "e1m2"; Lump = "D_E1M2"; @} }

In order to make the change persist over version upgrades (each one will
overwrite @file{Audio.ded}) copy the definition to @file{User.ded} in the
@file{ Defs/jDoom/ } directory, or create a new DED file with any name you
like in the @file{ Defs/jDoom/Auto/ } directory. Everything in the @file{Auto}
directory will be read automatically. If @file{User.ded} doesn't exist, just
create a new file for it.

@item Now you have the new Music definition, and the only thing left is to let
the engine know which file it should load when the song "e1m2" is played. Edit
your definition by adding the @opt{Ext} key:

@ind{@pre{Music @{
  ID = "e1m2"; Lump = "D_E1M2";
  Ext = "Data/jDoom/Music/song.mp3";
@}}}

}

CD tracks can be associated with songs in a similar fashion, but
instead of using the @opt{Ext} key you should use a @opt{CD track}
key:

@code{CD track = 3;}


@section{ Sound effects }

Sound samples can be replaced with WAV files. The supported formats are 8-bit
and 16-bit mono PCM with no compression. The @file{Sfx} resource class
directory is searched using the lump names of the original samples. For
example, to replace the rocket launcher sound in @plugin{libdoom}, the file
@file{dsrlaunc.wav} would be placed in the @file{Sfx} directory.

Another way to specify an external resource file is to use the Sound
definition @opt{Ext} key.

Doomsday will automatically detect the format of a sample if it's loaded from
a WAD file, making it possible to compile a WAD out of WAV samples.
