User Guide
Quick Reference
Modding
Development
User Guide
Quick Reference
Modding
Development
This page summarizes the usage of resources in Doomsday version 1. Most of this still applies equally well to Doomsday 2, but the introduction of packages in version 2 means the high-level management of resources is different.
Doomsday uses multiple kinds of resource files:
WADs 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 data/<gamemode>/ directory. The table below lists the resource classes and gives a brief description of each.
Resource Class | Description |
---|---|
Textures | Textures for walls and flats (floors and ceilings) |
Flats | Textures just for flats (floors and ceilings) |
Patches | Graphics for menus, fonts and sprite frames |
LightMaps | Textures for dynamic lights |
Music | Background music |
Sfx | Sound effects |
Another example: sound effects for Doom II would be placed in the directory data/doom2/sfx/.
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 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.
All WAD, PK3, ZIP and LMP files placed in the data/<game>/auto/ directory will be automatically loaded at startup. The data files are loaded in alphabetical order, including all the subdirectories of the auto directory.
All DED files placed in the 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 auto directory.
Virtual files (from inside a container) in the auto directories will also be loaded.
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 MyAuto with a set of data files somewhere on your hard drive. You could map this directory to data/<game>/auto, which would cause MyAuto to behave as though it was an auto-loading directory.
A virtual directory mapping is defined using the -vdmap
option. It takes the source and destination directories as parameters. For example:
-vdmap “D:\Games\MyAuto” “C:\Doomsday\Data\jDoom\Auto”
You can define an unlimited number of virtual directory mappings using multiple -vdmap
options.
Note, however, that -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 -vdmap
.
Doomsday supports the PK3 format. PK3 files are identical to ZIP archives, with the exception of using .pk3 instead of .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 PK3s.
PK3 files are loaded using the -file
option, for example -file some.pk3
.
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 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.
Files in the root of a PK3 are subject to automatic relocation based on file name extension: PK3/ZIP/LMP/WAD are mapped to data/<game>/auto/ and DED goes to defs/<game>/auto/. For example, placing test.ded into the root of a PK3 has the same end result as placing test.ded into 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 #, it is mapped into data/<game>/auto/; if it begins with @, it is mapped into defs/<game>/auto/.
#CoolStuff/Some.pk3 ⇒ data/<game>/auto/CoolStuff/Some.pk3
Doomsday has a number of advanced features for handling WAD files.
After all DED files have been processed, the engine will check through all the loaded WAD files for lumps named 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 DD_DEFNS lumps are applied in the order in which they have been loaded.
Another special lump used by Doomsday is DD_DIREC. It contains a table that translates file paths to lump names. An example is shown below:
FILE001 /Md2/jDoom/Some.md2 FILE002 Another.ded
Each line in 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 -basedir
) and paths that don't begin with a (back)slash are located in the runtime directory. The engine will first search the DD_DIRECs before opening any file for reading. Note, however, that all kinds of files are not loaded using the DD_DIRECs: 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 DD_DIREC lump that has (with a high probability) a unique lump name for each file. You can invoke the utility like this:
wadtool myfiles.wad /data/jdoom/textures/
This would create a WAD file that contains all the files from the current directory. When writing the DD_DIREC table, the prefix “/data/jdoom/textures/” would be added to each file name. wadtool is available in the Doomsday source repository under /tools/wadtool.
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:
Data/Game/Auto/DirWithPrefix.3/01_LUMPNAME.lmp
The first three characters of the file name are ignored (01_) and LUMPNAME becomes the name of the lump.
The assembly can be built using a hierarchy of directories. For example the contents of the PK3 might be:
#assembly/
data1.lmp
data2.lmp
powerplant.2/
a-E2M3.lmp
b-THINGS.lmp
xyz.lmp
#assembly would be mapped to Data/<Game>/Auto/assembly/.
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:
Pixel size | PCX | PNG | JPG | TGA |
---|---|---|---|---|
8-bit (paletted) (A) | Yes | Yes | - | - |
16-bit | - | - | - | - |
24-bit | - | Yes | Yes | Yes (B) |
32-bit (alpha channel) | - | Yes | - | Yes (B) |
(A) = the palette does not have to match the palette of the game
(B) = TGAs must be type 2 (uncompressed, unmapped RGB)
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 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:
To disable high-resolution textures use the command line option -nohightex
. The option -texdir
can be used to change the directory from which the textures are searched.
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 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 m_doom.png to the 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.
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 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 media0.png into the 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:
(patchName)-table(classNum)(tableNum).ext
(patchName) is the sprite frame lump name. (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). tableNum is the index number of the color translation table. Doom and Heretic have 4 tables, Hexen has 8. For example: playa1-table01-ck.png would be the Doom player sprite frame A1 with color table 1. The -ck suffix makes the image color keyed (i.e. special colors indicate transparent pixels).
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 Patches directory.
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 LightMaps directory. The accepted image formats are PCX, TGA and PNG. If Round.pcx, Round.tga or Round.png is found, it will be loaded.
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 Textures directory), or PCX images and raw image data stored inside a WAD lump. When using the -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 128×64 or 256×256). 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 64×64, 128×128 or 256×256 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 rend-tex-detail, rend-tex-detail-far, rend-tex-detail-strength and rend-tex-detail-scale control the rendering of detail textures.
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 pt_model
flags. The following would make the stage use particle model number 13:
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:
ID = “Particle13”;
For further details see the DED Reference.
Doomsday can play various external music files using the FMOD library. 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 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.
Like other external resources, placing a music file into the 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 d_e1m2.mp3 would be placed in the 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 ext
key of a Music definition (in Audio.ded). An example of editing the definitions: You have a terrific song called song.mp3 and you'd like to hear it instead of Doom's regular “e1m2”.
Music {ID = “e1m2”; Lump = “D_E1M2”;}
In order to make the change persist over version upgrades (each one will overwrite Audio.ded) copy the definition to User.ded in the Defs/jDoom/ directory, or create a new DED file with any name you like in the Defs/jDoom/Auto/ directory. Everything in the Auto directory will be read automatically. If User.ded doesn't exist, just create a new file for it.
ext
key: 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 ext
key you should use a CD track
key:
CD track = 3;
Sound samples can be replaced with WAV files. The supported formats are 8-bit and 16-bit mono PCM with no compression. The Sfx resource class directory is searched using the lump names of the original samples. For example, to replace the rocket launcher sound in libdoom, the file dsrlaunc.wav would be placed in the Sfx directory.
Another way to specify an external resource file is to use the Sound definition 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.
Doomsday supports MAPINFO lumps in the Hexen format.
Source ports have extended MAPINFO with custom definitions. A handful of these are supported by Doomsday. By default, all unsupported definitions are reported as warnings in the log (Map category with Dev flag). These warnings are suppressed if the following comment line is found in the MAPINFO lump (since 2.2):
// Doomsday: Ignore errors!
Most features of Dehacked are supported by Doomsday's Dehacked reader. The loader will print a message during startup if an unsupported feature is used.
Let's say you have the Dehacked patch file.deh in your runtime directory. Then you can use the command line option -deh file.deh
to load it at startup.
If a lump named DEHACKED is found in a WAD, it will be automatically applied when the WAD is loaded. Normally only the last DEHACKED lump is used if a lump with that name is found in multiple WADs. Use the option -alldehs
to make the engine apply all found DEHACKED lumps.