This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
modding:overview_of_resources_doomsday_1.x [2018-10-19 11:36] – skyjake | modding:overview_of_resources_doomsday_1.x [2019-12-31 13:30] (current) – [Textures and flats] skyjake | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Resources (version 1) ====== | ||
+ | |||
+ | 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 [[: | ||
+ | |||
+ | |||
+ | ===== Resource files and containers ===== | ||
+ | |||
+ | |||
+ | Doomsday uses multiple kinds of resource files: | ||
+ | |||
+ | * Plain data (e.g., //.png// image, //.lmp// file). | ||
+ | * Definition files (//.ded//). | ||
+ | * Containers (//.wad//, //.pk3//). | ||
+ | |||
+ | |||
+ | [[http:// | ||
+ | |||
+ | 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 // | ||
+ | |||
+ | ^ 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 // | ||
+ | |||
+ | 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 // | ||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | ===== Automatic loading of resources ===== | ||
+ | |||
+ | |||
+ | All WAD, PK3, ZIP and LMP files placed in the // | ||
+ | |||
+ | All DED files placed in the // | ||
+ | |||
+ | Virtual files (from inside a container) in the //auto// directories will also be loaded. | ||
+ | |||
+ | |||
+ | ===== 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 //MyAuto// with a set of data files somewhere on your hard drive. You could map this directory to // | ||
+ | |||
+ | A virtual directory mapping is defined using the '' | ||
+ | |||
+ | '' | ||
+ | |||
+ | You can define an unlimited number of virtual directory mappings using multiple '' | ||
+ | |||
+ | Note, however, that '' | ||
+ | |||
+ | |||
+ | ===== PK3 files ===== | ||
+ | |||
+ | |||
+ | 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 [[http:// | ||
+ | |||
+ | PK3 files are loaded using the '' | ||
+ | |||
+ | 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 // | ||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | ==== Automatic remapping inside PK3 ==== | ||
+ | |||
+ | |||
+ | Files in the root of a PK3 are subject to automatic relocation based on file name extension: PK3/ | ||
+ | |||
+ | 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 // | ||
+ | |||
+ | //# | ||
+ | |||
+ | |||
+ | ===== WAD files ===== | ||
+ | |||
+ | |||
+ | Doomsday has a number of advanced features for handling WAD files. | ||
+ | |||
+ | |||
+ | ==== Definitions inside WAD ==== | ||
+ | |||
+ | |||
+ | After all DED files have been processed, the engine will check through all the loaded WAD files for lumps named // | ||
+ | |||
+ | |||
+ | ==== WAD as a virtual file container ==== | ||
+ | |||
+ | |||
+ | Another special lump used by Doomsday is // | ||
+ | |||
+ | < | ||
+ | FILE001 | ||
+ | FILE002 | ||
+ | |||
+ | Each line in // | ||
+ | |||
+ | skyjake has created a simple utility for automatically creating a WAD file that contains the current directory and all its subdirectories plus a // | ||
+ | |||
+ | '' | ||
+ | |||
+ | This would create a WAD file that contains all the files from the current directory. When writing the // | ||
+ | |||
+ | |||
+ | ===== 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" | ||
+ | |||
+ | 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: | ||
+ | |||
+ | * 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: | ||
+ | |||
+ | // | ||
+ | |||
+ | The first three characters of the file name are ignored (//01_//) and // | ||
+ | * 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: | ||
+ | |||
+ | < | ||
+ | #assembly/ | ||
+ | | ||
+ | | ||
+ | | ||
+ | a-E2M3.lmp | ||
+ | b-THINGS.lmp | ||
+ | | ||
+ | |||
+ | //# | ||
+ | |||
+ | |||
+ | ====== Resource types ====== | ||
+ | |||
+ | |||
+ | |||
+ | ===== 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: | ||
+ | |||
+ | ^ 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, | ||
+ | |||
+ | < | ||
+ | |||
+ | 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' | ||
+ | |||
+ | 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' | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | Examples: | ||
+ | |||
+ | * To create a high-resolution texture for the wall texture STARTAN3 you'd place a TGA file named // | ||
+ | * In order to replace the flat FLOOR7_2, you'd to put // | ||
+ | |||
+ | |||
+ | < | ||
+ | |||
+ | To disable high-resolution textures use the command line option '' | ||
+ | |||
+ | |||
+ | ===== 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 //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 // | ||
+ | |||
+ | 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 ===== | ||
+ | |||
+ | |||
+ | 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 // | ||
+ | |||
+ | For example, in order to replace the Doom medikit (lump name MEDIA0), one would place the file // | ||
+ | |||
+ | 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, | ||
+ | |||
+ | // | ||
+ | |||
+ | // | ||
+ | |||
+ | |||
+ | ===== 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' | ||
+ | |||
+ | |||
+ | ===== 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' | ||
+ | |||
+ | Example: If you assign the light map " | ||
+ | |||
+ | |||
+ | ===== 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 // | ||
+ | |||
+ | 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' | ||
+ | |||
+ | 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}}, | ||
+ | |||
+ | |||
+ | ===== 3D models as particles ===== | ||
+ | |||
+ | |||
+ | 3D models can be used as particles in a particle generator. In the particle generator definition, set the particle stage' | ||
+ | |||
+ | '' | ||
+ | |||
+ | 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: | ||
+ | |||
+ | '' | ||
+ | |||
+ | For further details see the DED Reference. | ||
+ | |||
+ | |||
+ | ===== Music ===== | ||
+ | |||
+ | |||
+ | Doomsday can play various external music files using the [[http:// | ||
+ | |||
+ | 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' | ||
+ | |||
+ | 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' | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | - 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' | ||
+ | - Open // | ||
+ | |||
+ | '' | ||
+ | |||
+ | In order to make the change persist over version upgrades (each one will overwrite // | ||
+ | - 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 " | ||
+ | |||
+ | < | ||
+ | Music { | ||
+ | ID = " | ||
+ | Ext = " | ||
+ | }</ | ||
+ | |||
+ | |||
+ | CD tracks can be associated with songs in a similar fashion, but instead of using the '' | ||
+ | |||
+ | '' | ||
+ | |||
+ | |||
+ | ===== 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 //Sfx// resource class directory is searched using the lump names of the original samples. For example, to replace the rocket launcher sound in [[libdoom]], | ||
+ | |||
+ | Another way to specify an external resource file is to use the Sound definition '' | ||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | ===== MAPINFO lumps ===== | ||
+ | |||
+ | 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 [[version: | ||
+ | |||
+ | // Doomsday: Ignore errors! | ||
+ | ====== Plugins ====== | ||
+ | |||
+ | |||
+ | |||
+ | ===== Dehacked patches ===== | ||
+ | |||
+ | |||
+ | Most features of Dehacked are supported by Doomsday' | ||
+ | |||
+ | Let's say you have the Dehacked patch // | ||
+ | |||
+ | If a lump named // | ||
+ | |||
+ | |||
+ | |||