

                           The Doomsday Engine
                           -------------------
                              Version 1.7.8

                            by Jaakko Kernen
                        <skyjake@doomsdayhq.com>
                               03/16/2003

                       http://www.doomsdayhq.com/
                      http://deng.sourceforge.net/


CONTENTS:
  1. Introduction
       1.1 Features
       1.2 Requirements
  2. Documentation
  3. Details
       3.1 Paths and the command line
       3.2 The "-file" option
       3.3 Definitions and files in WADs
       3.4 High-resolution textures
       3.5 Detail textures
       3.6 Custom music and sound files
       3.7 Dehacked patches
  4. Known issues
  5. Acknowledgements

========================================================================
1. INTRODUCTION

The Doomsday Engine is an enhanced and extended Win32 version of the
DOOM engine. It was originally based on the Hexen source code but parts
of it have later been completely rewritten. Doomsday is only an engine:
you will also need a Game DLL. Three such DLLs are being developed
alongside the engine: jDoom, jHeretic and jHexen.

Doomsday is a direct descendant of JHexen. The first version of JHexen
was released in October 1999. Subsequently the first version of
Doomsday was released in February 2000.

The engine, jDoom, jHeretic and jHexen are being developed by Jaakko
Kernen. Of late an increasing number of people has been involved in
the project (see Acknowledgements).

........................................................................
1.1 Features

Graphics:
* Supports both OpenGL and Direct3D
* Dynamic lights
* Lens flares
* High-resolution textures (PNG, TGA, PCX)
* Particle effects
* Detail textures
* 3D models (uses Quake II's MD2 format)
* Simple environmental mapping for 3D models (shiny effects)
* Actor (monster) movement smoothing
* Simple shadows for objects
* Fog

Sound:
* Plays music using standard Windows MIDI routines
* Supports DirectSound, DirectSound3D, EAX 2.0 and A3D 3.0
* Uses FMOD (http://www.fmod.org/) to play music files such as MP3
* 3D sound effects
* Environmental (reverb) effects
* Runtime sound effect resamping to 22/44 KHz with 8/16 bits

Networking:
* Client/server networking
* Uses DirectPlay: TCP/IP, IPX, modem and serial link support
* Up to 16 players
* Clients can join games in progress
* Dedicated mode for servers

Other:
* Console
* Control Panel
* Plain text definition files for game objects and other data
* Files can be loaded from WAD files (see wadtool)
* Doomsday KickStart: a launcher for games running on Doomsday

........................................................................
1.2 Requirements

* Pentium 166 (or equivalent) with 64Mb of RAM (3D models & special
  effects disabled)

* Windows 95 (or newer)

* DirectX 8 (or newer)

* A display adapter capable of 3D hardware acceleration

* At least one WAD file from the original Doom, Heretic, Hexen, etc.

========================================================================
2. DOCUMENTATION

Additional documentation is available in the Doc\ folder:

Beginner.txt
    A Beginner's Guide to Doomsday. Installation instructions and basic
    usage information for a first-time user.

CmdLine.txt
    Doomsday command line options. A quick reference listing all the
    command line options recognized by Doomsday, with a short
    explanation for each.

DEDDoc.txt
    Doomsday Engine Definition reference. An in-depth look into the
    syntax and uses of DED files.

InFine.txt
    InFine scripts reference. InFine scripts are used to define
    interludes and finale animations.

DHistory.txt
    Doomsday version history.

DSS.txt
    Doomsday directory structure standard. Mod-makers and other
    developers are encouraged to follow the structure described here.

Network.txt
    Multiplayer games with Doomsday. Some details about network games
    running on Doomsday.

Example.bat
    Example batch file for launching.

An up-to-date version history of the Doomsday engine should be
available at:

    http://www.doomsdayhq.com/changes.php

The Extended General Line And Sector Type Reference (XGRef) can be
downloaded from:

    http://www.students.tut.fi/~jotkeran/files/XGRef.pdf

========================================================================
3. DETAILS

........................................................................
3.1 Paths and the command line

There are a few things you should know about the handling of relative
paths. First of all, these are the directories that the engine is
working with:

* Doomsday root/base directory (for example C:\Doomsday\). Everything
  relating to the Doomsday engine is under this directory.

* Working/runtime directory (for example C:\Doomsday\Run\x\). This is
  the directory where the engine spends it time when a game is running.

The "-basedir" option tells the engine where the base directory is in
relation to the runtime directory (or it's the the absolute path of the
base directory, e.g. C:\Doomsday\).

The principle is that "-basedir" only affects built-in default paths
and relative paths in DED files. "-basedir" does not affect relative
paths in command line options. If a relative path is given on the
command line, it is interpreted in relation to the runtime directory.
For example, the option "-file doom.wad" will make the engine read the
file doom.wad, which is located in the runtime directory. In the
default configuration this is C:\Doomsday\Run\jDoom\. KickStart
automatically uses a "-basedir" of ..\.., which means the root
directory is the 'grandparent' of the runtime directory. The option
"-sbd" ("-stdbasedir") is the equivalent of "-basedir ..\..".

There is one exception, however: with the "-file" (and "-iwad") options
a relative path can begin with a greater-than character (>). When the
engine loads the WAD file in question the > character is replaced with
the path specified by "-basedir". For example, "-file >Data\Doom.wad"
would make the engine load a WAD named C:\Doomsday\Data\Doom.wad
(assuming the default Doomsday root C:\Doomsday\). Note that if you're
executing Doomsday.exe from the command line or from a DOS batch file,
you must enclose the file names that contain a > character in quotes or
otherwise DOS will think you're trying to redirect output. In response
files it doesn't matter if there are quotes or not. (If you really are
trying to redirect output, you should use the "-out" option.)

The default launch method (used by KickStart) is a runtime directory
oriented approach. KickStart will change the current working directory
to the Game's runtime folder and execute Doomsday.exe from there, with
the "-basedir ..\.." option. This way the engine will use the
appropriate runtime folder as the working directory, but will also know
where the Doomsday root directory is by prepending the base directory's
..\.. to default path names (like fonts and definitions files).

There is an alternative approach, which could be called an executable
oriented approach. Doomsday.exe is executed in the Bin directory, with
the options "-userdir <runtime-path> -basedir <path-to-root>".
<runtime-path> can be a relative or an absolute path to the correct
runtime directory. Again, "-basedir" tells the engine where the root
directory is, as an absolute path or in relation to <runtime-path>.
"-userdir" will make the engine run in the given directory, i.e. it
specifies the runtime directory.

Note that "-game" and "-gl" work a bit differently because their
arguments are directly passed on to the Win32 routine LoadLibrary. You
should either omit the path entirely (e.g. "-game jHeretic.dll") or use
a full path to the DLL (e.g. "-game C:\Doomsday\Bin\jHeretic.dll"), no
matter where you're executing Doomsday.exe.

The default place where you should put your IWADs is Data\<Game>\.
jDoom, jHeretic and jHexen will by default look for IWADs in
Data\<Game>\, Data\, the base directory and the runtime directory, in
that order.

........................................................................
3.2 The "-file" option

The "-file" option is used to load WAD files and other data files from
the command line. "-file" has two aliases: the abbreviation "-f" and
"-iwad". Both of these are just aliases; they are treated like they
were in fact "-file".

In addition to normal WAD files, the "-file" option can be used to load
any type of data files, for instance PCX images. An example:

    -file image.pcx

This would load the file image.pcx from the runtime directory. When
loading files in this manner, the engine will treat the file as if it
was a WAD file with a single data lump. The lump gets its name from the
base of the file name, which in the example's case would be IMAGE.
Anyone can then refer to the data lump using that name, just as if it
was included in a WAD file.

Any file loaded with the "-file" option can't be unloaded from memory
at runtime using the unload command. This is mainly a precaution, since
unloading the main WAD file of the game or any data related to it would
lead to fatal errors.

........................................................................
3.3 Definitions and files in WADs

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 to start from the Doomsday base
directory (set with "-basedir"; e.g. C:\Doomsday) and paths that don't
begin with a (back)slash are located in the runtime directory. The
engine will search the DD_DIRECs first before opening any file (but
only when 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.

I've written 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 could 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.

........................................................................
3.4 High-resolution textures

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

 Pixel size                  PCX           PNG           TGA
 ----------------------------------------------------------------------
 8-bit (paletted)*           Yes           Yes           -
 16-bit                      -             -             -
 24-bit                      -             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 that 32-bit images are just 24-bit images with an additional 8
bits per pixel for the alpha channel. Contact me if you feel that it's
necessary to add support for other formats.

The recommended format for high-resolution textures is paletted PNG. It
is the easiest format in which to distribute the textures (small).
Since the palette doesn't have to be the same as the game's, it should
be enough for just about any texture.

The high-resolution textures can be of any size. The engine will render
them scaled to 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 is done 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. An alternative way to have transparency is to use an
alpha channel. In it, white (255) means opaque and black (0) is fully
transparent. All values in between can be used, too, for partly
translucent pixels.

High-resolution textures are loaded from the Data\<Game>\Textures\
directory. For example jDoom uses the directory Data\jDoom\Textures\.
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. The filenames of images that replace flats
must begin with "flat-", e.g. to replace the flat FLOOR7_2 you'd need
to have a TGA file flat-floor7_2.tga in the Textures directory. If
there are both PNG and TGA versions of the same texture, the engine
will use the PNG version.

Note that the filenames 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.

Any textures found in the Textures directory are automatically used. 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.

Links to high-resolution texture sites:

    http://switch.to/doom2textures
    http://switch.to/heretictextures
    http://switch.to/hexentextures

........................................................................
3.5 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 => dark, gray => no change,
white => bright.

Detail textures can be assigned to specific wall textures and flats
using Detail definitions (Details.ded). The definition is described in
the Doomsday Engine Definitions Reference (DEDDoc.txt).

Detail textures can be loaded from PCX images or raw image data. Either
way, the image must be inside a WAD file or loaded using the "-file"
option. When using the "-file" option to load detail textures, the file
names of the images become lump names (see "-file" option).

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

........................................................................
3.6 Custom music and sound files

Doomsday can play various external music files using the FMOD library
(http://www.fmod.org/). FMOD supports a variety of music file formats
including MP3, MOD and S3M (modules are a good option due to their good
quality/size ratio). External music files can be played any time using
the playext console command.

NOTE! On some systems using FMOD has caused lock-ups or other unwanted
      behavior. If this appears to be the case for you, you should
      disable FMOD using the "-nofmod" option. However, this will also
      make it impossible to play external music files such as MP3s.

If you don't want to edit the Audio definitions you can store the
external music files into a WAD. In this case 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.

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. Anything in the Auto
   directory will be read. 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;

External WAV files can be used instead of samples stored in WAD files,
if you set the "Ext" key of the corresponding Sound definition. Also,
Doomsday will automatically detect the format of a sample when it's
loaded from a WAD file. In this case you don't need to edit any
definitions. Doomsday supports 8/16 bit *mono* PCM WAV files with no
compression.

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

========================================================================
4. KNOWN ISSUES

* The FMOD library has been known to cause problems on some systems. If
  you experience sudden crashes or lock-ups, try the "-nofmod" option.
  It may also be helpful to disable MIDI music entirely with the
  "-nomusic" option.

* Software gamma doesn't affect MD2 skins. Use hardware gamma
  correction (vid-gamma, vid-contrast, vid-bright) instead.

========================================================================
5. ACKNOWLEDGEMENTS

id Software, for creating DOOM and then releasing its source code.

Raven Software, for creating Heretic and Hexen and then releasing their
source code.

Graham Jackson, for helping me with the source code, fixing some Doom
bugs and doing a lot of testing.

Abbs, for maintaining the jDoom model pack and doing wonderful work on
the models and particle effects.

Anton Rzheshevski (aka Cheb), for player weapon 3D models and other MD2
modifications/enhancements and maintaining the jDoom model pack.

Greg Fisk (Slyrr), for many excellent 3D models for jHeretic.

All authors of the MD2 models and definition files (see the readme
files under Md2\ for more detailed info).

David Jarvis, for doing network testing with jDoom and jHeretic and
generously contributing essential computer hardware components! :-)

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

William Mull, for hosting the j-sites and bearing with me.

Patrick Farrell, for providing FTP space for the Doomsday project.

Darin Petersen, for the very useful MD2 export tool QTiP.

People who have sent bug reports. One can't expect me to keep coding
this thing and test every possible level in case something has broken
down... (Did you know that Doom, Heretic and Hexen combined have over
220 'official' levels?) By sending bug reports you can be sure I'll at
least try to fix it some day. :-)

People who have sent ideas for new features. My goal is not to create
the most feature-packed, super-customizable FPS extravaganza but to
have ports of Doom, Heretic and Hexen that play right and look nice, so
I might not think of something you'd very much like to see.

All DOOM / Heretic / Hexen fans, for keeping these excellent games
alive. Keep on playing!

Me, Jaakko Kernen, for writing this stuff! You rule! ;-D
