Provided by: doomsday_1.15.8-5build1_amd64 bug

NAME

     doomsday - Enhanced source port of Doom, Heretic and Hexen

SYNOPSIS

     doomsday [-iwad dir] [-game mode] [-wnd] [-wh w h] [-v] [-file file ...]

     Note that the command line is not interpreted according to GNU conventions. Everything
     following -- is ignored.  @ can be used to specify a response file whose contents are added
     to the command line.

OPTIONS

     -iwad     Specifies a directory where to look for IWAD files. Searches for IWADs from all
               known games and automatically loads them when needed.

     -game     Sets the game to load after startup. See GAME MODES for a list of available games.
               For example:

                     -game doom1-ultimate

               If -game is not specified, Doomsday will start in "ringzero" mode: a plain console
               with no game loaded.

     -wnd      Starts in windowed mode (also -window). The default is to start in fullscreen
               mode.

     -wh       Sets the size of the Doomsday window. In fullscreen mode specifies which display
               resolution to use.

     -v        Print verbose log messages (also -verbose). Specify more than once for extra
               verbosity.

     -file     Specify one or more resource files (WAD, LMP, PK3) to load at startup. More files
               can be loaded at runtime with the load command.

     More command line options are listed in the Options Reference
     (http://dengine.net/dew/index.php?title=Command_line_options_reference) in the Doomsday
     Engine Wiki.

TABLE OF CONTENTS

           1.   SYNOPSIS

           2.   OPTIONS

           3.   DESCRIPTION
                Features
                Requirements

           4.   GAME MODES

           5.   FILES

           6.   ENVIRONMENT

           7.   MULTIPLAYER
                Modes
                Online Games
                Hosting a Game
                Networking Details

           8.   RESOURCE FILES AND CONTAINERS
                Automatic Loading of Resources
                Virtual Directory Mapping
                PK3 Files
                WAD Files
                Lump Assemblies Instead of WADs

           9.   RESOURCE TYPES
                Textures and Flats
                Patches
                Sprite Frames
                Raw Screens
                Light Maps
                Detail Textures
                3D Models as Particles
                Music
                Sound Effects

           10.  PLUGINS
                Dehacked Patches

           11.  KNOWN ISSUES

           12.  SEE ALSO

           13.  AUTHOR

           14.  ACKNOWLEDGEMENTS

DESCRIPTION

     The Doomsday Engine is a "source port" of id Software's Doom and Raven Software's Heretic
     and Hexen, which were popular PC FPS games in the early-to-mid 1990s. Doomsday enhances
     these classic games with many features including 3D graphics, fully customizable controls
     and client/server networking, making them more accessible to modern gamers. However, the
     feel of the original games has been kept intact, ensuring sublime nostalgia or an exciting
     introduction into the pioneering games of the genre.

     Doomsday and the associated ports of Doom, Heretic and Hexen have been in development since
     1999; the first versions were released in late 1999 and early 2000. Several people have been
     involved in the project (see ACKNOWLEDGEMENTS).

   Features
     User interface:
           -   Overlaid task bar for easy access to engine features
           -   In-game command console
           -   Configuration menus and Renderer Appearance sidebar editor
           -   Game selection screen (http://dengine.net/dew/index.php?title=Ringzero_GUI) for
               runtime game changes (e.g., from DOOM to Heretic), browsing multiplayer games, and
               loading saved games
           -   On-the-fly add-on resource loading
           -   Flexible input control bindings system
           -   Built-in updater for easy upgrades

     Graphics:
           -   OpenGL based renderer
           -   Dynamic ambient occlusion (corner shadowing) for world surfaces
           -   Dynamic lights with halos and lens flares
           -   Dynamic shadowing effects for world objects
           -   Particle effects system
           -   3D models for world objects (with per-vertex lighting and multiple light sources),
               skies, skyboxes, and particles
           -   Automatical world surface (light) decorations
           -   Detail texturing, shine and glowing effects for world surfaces
           -   Fogging, bloom, and vignette effects
           -   Environmental mapping effects for 3D models and world surfaces
           -   World movement smoothing (actors, monsters, missiles, surfaces) to remove the
               original games' limitation of 35 FPS
           -   Smart texture filtering using a modified hq2x algorithm
           -   Stereoscopic rendering modes: anaglyph, side-by-side, cross-eye and parallel
               viewing
           -   Support for Oculus Rift

     Resources:
           -   Flexible containters: WAD, ZIP, native folder: any resource can be loaded from any
               container type
           -   High-resolution textures: PNG, JPG, TGA, PCX
           -   3D models: MD2, DMD with LOD support
           -   External music files in MP3 and other formats
           -   Plain text definitions that all share the same syntax
           -   Internal BSP builder (originally based on glBSP)

     Audio:
           -   Plugin based driver architecture
           -   Uses FMOD Ex (http://www.fmod.org/) for audio playback (sound effects, music, CD
               audio tracks)
           -   Supports the open source SDL_mixer for sound effects and music files
           -   FluidSynth for MIDI playback using SF2 soundfonts
           -   OpenAL
           -   External music files in MP3 and other formats
           -   3D positional sound effects
           -   Environmental echo and reverb effects
           -   Runtime sound effect resampling to 22/44 KHz with 8/16 bits

     Multiplayer:
           -   TCP-based client/server networking
               (http://dengine.net/dew/index.php?title=Multiplayer_(Readme))
           -   Automatical discovery of servers running on the local network
           -   Central master server for discovery of servers on the internet
           -   Standalone server running as a daemon/background process
           -   Standalone Doomsday Shell (http://dengine.net/dew/index.php?title=Shell) tool for
               server management (both local and remote)
           -   Supports up to 15 player games
           -   Clients can join games in progress
           -   In-game chat and server management (via a shell login)

     Other:
           -   Open source: software developers should visit the Getting Started page
               (http://dengine.net/dew/index.php?title=Getting_started)
           -   Cross platform (http://dengine.net/dew/index.php?title=Supported_platforms)
           -   Plugin based extensible architecture
           -   Snowberry: GUI frontend based on game profiles; for managing custom maps, resource
               packs, add-ons, and starting different game configurations easily (written in
               Python)

   Requirements
              At least one WAD file from the original Doom, Heretic, Hexen, or other supported
               game

              A display adapter capable of OpenGL 2.0 hardware acceleration

GAME MODES

     One game plugin, such as libdoom, is able to run in many different modes. Each mode emulates
     a specific version of the original game and typically has its own IWAD file.

     Below is a list of all the game modes supported by the game plugins distributed with
     Doomsday: libdoom (previously called jDoom), libheretic (jHeretic) and libhexen (jHexen).

                Plugin       Game Mode        Description
                libdoom      doom1-share      Shareware Doom v1.9
                             doom1            Registered Doom v1.9
                             doom1-ultimate   Ultimate Doom*
                             doom2            Doom 2
                             doom2-plut       Final Doom: Plutonia Experiment
                             doom2-tnt        Final Doom: TNT Evilution
                             chex             Chex Quest
                             hacx             HacX

                libheretic   heretic-share    Shareware Heretic
                             heretic          Registered Heretic
                             heretic-ext      Heretic: Shadow of the Serpent Riders**
                libhexen     hexen            Hexen v1.1
                             hexen-v10        Hexen v1.0
                             hexen-dk         Hexen: Death Kings of Dark Citadel
                             hexen-demo       The 4-level Hexen Demo

     * = has a 4th episode ** = has episodes 4 and 5

     To help libhexen recognize the IWAD of the 4-level Hexen (beta) demo, you should rename the
     IWAD to hexendemo.wad.

FILES

           /etc/doomsday/defaults
                           System-level default configuration. This is checked after
                           ~/.doomsday/defaults. For example:

                                 audio fluidsynth {
                                     driver: pulseaudio
                                 }

           /etc/doomsday/paths
                           System-level paths configuration (basedir, libdir, iwaddir). This is
                           checked after ~/.doomsday/paths. See the Doomsday Wiki for details
                           ("Configuration").

           /usr/share/doomsday/
                           Read-only files for the launcher, engine and game plugins.

           ~/.doomsday/    Location for the user-specific files.

           ~/.doomsday/defaults
                           User's own defaults (see above).

           ~/.doomsday/paths
                           User's paths configuration (basedir, libdir, iwaddir).

           ~/.doomsday/addons/
                           Directory where to put addons (WAD, PK3, Snowberry .addon, etc.) so
                           that they appear in the launcher's list.

           ~/.doomsday/runtime/
                           Doomsday's runtime files, e.g., message log (doomsday.out), savegames,
                           and screenshots.

           ~/.doomsday/runtime/client.id
                           Unique client identifier. Used to identify clients in a multiplayer
                           game. Delete this file to generate a new identifier, for instance if
                           you're getting a "duplicate ID" error.

           ~/.doomsday/runtime/configs/
                           Saved values for console variables and control bindings.

ENVIRONMENT

     The following environment variables are recognized by Doomsday.

           DOOMWADDIR      DOOM WAD directory. Doomsday looks for WAD files in this directory.

           DOOMWADPATH     Delimited set of DOOM WAD directories. Use colon (:) to separate
                           directories. Supported WAD files are searched for in each directory.

MULTIPLAYER

     Doomsday features client/server based multiplayer for up to 15 players.

     Multiplayer games can be joined using the in-game GUI (under the "New Game" main menu
     option) or using the console.

   Modes
     The following multiplayer modes are available in libdoom, libheretic and libhexen:

           -   Cooperative
           -   Deathmatch
           -   Team Deathmatch

     Deathmatch and Cooperative can be set directly in the GUI or console. For Team Deathmatch
     set "No Team Damage" to yes and in Player Setup make sure everybody on your team is the same
     color.

     Doom offers two variants of Deathmatch:

           Deathmatch 1    Ammo and powerups do not respawn. Non-dropped (i.e those from bad
                           guys) weapons remain, but can only be picked up once per life.

           Deathmatch 2    All non-dropped pickups, including weapons randomly respawn a short
                           while after being picked up. Respawned weapons can be picked up more
                           than once per life.

     Deathmatch in Heretic and Hexen is limited to the "Deathmatch 1" mode.

   Online Games
     When joining games on the internet, please note the following:

              The network code in this release has some limitations
               (http://dengine.net/multiplayer_issues) that we will work on in future versions.

              The connection should be able to sustain 100KB/s transfer rate (1 Mbps or better).

   Hosting a Game
     Use doomsday-shell or doomsday-shell-text to host a multiplayer game of your own. The Shell
     allows you to start, stop, and control Doomsday multiplayer servers. Using the Shell, you
     can connect both to local servers and remote servers over the internet.

     doomsday-server runs in a background process and has no UI of its own. You must use the
     Shell to view or manipulate it. Presently you must use the Shell's Console (text-mode
     command line interface) to configure the server.

     For instance, the following would set up a deathmatch without monsters in E1M5:

           server-game-deathmatch 1
           server-game-nomonsters 1
           setmap 1 5

     Note that you can set up a .cfg file where you can define the server configuration and
     automatically open the server (http://dengine.net/dew/index.php?title=Multiplayer_server).

     If your server is not public ( server-public), a client can connect to it using a custom
     address search:

              Server on the same computer or LAN: servers on the local network should be
               discovered automatically and are visible immediately in the Custom Search results
               list.

              Server somewhere on the internet: enter the server's IP address or domain name
               into the search address field.

   Networking Details
     Doomsday uses TCP network connections for multiplayer games. If you host a game and are
     behind a firewall or using NAT, you must make sure that other computers are able to open TCP
     connections to your computer. This entails opening the appropriate incoming TCP ports on
     your firewall and/or configuring the NAT so that the correct ports are routed to your
     computer.

     Additionally, UDP ports 13209-13224 are used for detecting servers running on the local
     network; if you are experiencing problems with autodetecting local servers, check that your
     firewall isn't blocking these UDP ports on either end.

     You can see information about the network subsystem status with the command:

           net info

   Server
     A server opens one TCP port for listening to incoming connections. The port number is
     configured with the console variable net-ip-port.

     By default a server uses TCP port 13209 (setting the port to zero will mean 13209 will be
     used). The configured port must be open for incoming TCP traffic in the firewall.

   Client
     Clients do not require any firewall configuration for incoming connections. A client only
     needs to be able to reach the server via the server's TCP port.

     A server running on the same computer can be connected to with the following command:

           connect localhost

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

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

   Automatic Loading of Resources
     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
     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 /home/username/myauto /usr/share/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.

   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 PK3s
     (http://en.wikipedia.org/wiki/PK3_(file_extension)).

     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.

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

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

   WAD as a Virtual File Container
     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_DIREC s before opening any file for reading. Note, however, that
     all kinds of files are not loaded using the DD_DIREC 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 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.

   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:

              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:

                     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.

              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/
              data1.lmp
              data2.lmp
              powerplant.2/
                 a-E2M3.lmp
                 b-THINGS.lmp
              xyz.lmp

     #assembly would be mapped to Data/<Game>/Auto/assembly/.

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)*        Yes   Yes   -     -
                           16-bit                   -     -     -     -
                           24-bit                   -     Yes   Yes   Yes**
                           32-bit (alpha channel)   -     Yes   -     Yes**

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

     NOTE!   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
     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 create a high-resolution texture for the wall texture STARTAN3 you'd place a
               TGA file named STARTAN3.tga or a PNG file named STARTAN3.png into the Textures
               directory.

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

     NOTE!   The file names of the high-resolution textures must match the 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 -nohightex. The option
     -texdir can be used to change the directory from which the textures are searched.

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

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

   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 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
     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 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 rend-tex-detail, rend-tex-detail-far, rend-tex-detail-strength and
     rend-tex-detail-scale control the rendering of detail textures.

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

   Music
     Doomsday can play various external music files using the 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 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".

           1.   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 Doomsday/Data/jDoom/
                directory called Music. Another logical choice could be Doomsday/Music/. Then
                copy the song into the created directory.

           2.   Open Audio.ded in a text editor. In it, you will find a bunch of Music
                definitions, including:

                      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.

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

PLUGINS

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

KNOWN ISSUES

     Doomsday is a work in progress, so there usually is a number of known issues that will be
     addressed in the future.

           Bugs and Features
                           The official place to report new bugs, submit feature requests and
                           browse the existing reports is the Deng Team's own Issue Tracker
                           (http://tracker.skyjake.fi/).

           Multiplayer Issues
                           There is a to-do list of known multiplayer issues and needed
                           enhancements (http://dengine.net/multiplayer_issues) maintained by
                           skyjake.

SEE ALSO

     Additional documentation is available online in the Doomsday Engine Wiki
     (http://dengine.net/dew/). Information in the wiki includes:

              User's Guide: collection of documentation to help play games with Doomsday
               (http://dengine.net/dew/index.php?title=Category:User%27s_Guide)

              Author's Guide: articles for map and resource pack/addon authors
               (http://dengine.net/dew/index.php?title=Category:Author%27s_Guide)

              Programmer's Guide: technical documentation for software developers and Deng Team
               members (http://dengine.net/dew/index.php?title=Category:Programmer%27s_Guide)

              Definitions Reference: DED and finale script syntax
               (http://dengine.net/dew/index.php?title=DED)

              Command Line Options Reference
               (http://dengine.net/dew/index.php?title=Command_line_options)

              Version history (http://dengine.net/dew/index.php?title=Category:Releases)

              Project roadmap and features in planning
               (http://tracker.skyjake.fi/projects/deng/roadmap)

AUTHOR

     This documentation has been written by Jaakko Keränen <jaakko.keranen@iki.fi> and Daniel
     Swanson <danij@dengine.net>.

ACKNOWLEDGEMENTS

     id Software created DOOM and then released its source code.

     Raven Software created Heretic and Hexen and released their source code.

     Jaakko Keränen started the Doomsday Engine project and is the lead developer of the Deng
     Team.

     Daniel Swanson is a developer and lead graphics artist in the Deng Team, author of the
     dengine.net (http://dengine.net) website implementation and former maintainer of the jDoom
     Resource Pack.

     Dave Gardner is a member of the Deng Team, maintainer of high-resolution texture packs, and
     contributor to the dengine.net (http://dengine.net) website implementation.

     Vermil regularly provides in-depth feedback and bug reports and is an expert in all things
     related to DOOM-based games.

     Kees Meijs packaged Doomsday for Debian and hosted an Apt repository of Debian packages.

     Andrew Apted wrote glBSP (http://glbsp.sourceforge.net/).

     Graham Jackson helped with the source code, fixed Doom bugs and did a lot of testing.

     David Jarvis did early network testing with jDoom and jHeretic and generously contributed
     essential computer hardware components.

     William Mull hosted the project's websites for many years.

     Finally, the resource pack community, particularly mentioning: Abbs maintained the jDoom
     model pack and did wonderful work on the models and particle effects; Anton Rzheshevski (aka
     Cheb) created player weapon 3D models and other MD2 modifications/enhancements, maintained
     the jDoom model pack and wrote KickStart version 2; Greg Fisk (Slyrr) authored many
     excellent 3D models for jHeretic; Daniel Norton created detail textures for jDoom.