User Tools

Site Tools


Doomsday Engine


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 multiplayer, 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 to 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).


User interface:




  • 3D positional sound effects
  • Environmental echo and reverb effects
  • External music files in MP3 and other formats
  • Uses FMOD Ex 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


  • Supports up to 15 player games
  • Clients can join games in progress
  • Automatic 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 tool for server management (both local and remote)



  • At least one WAD file from the original Doom, Heretic, Hexen, or other supported game
  • Minimum OS version: macOS 10.8
  • Supported CPU architectures: 64-bit/32-bit Intel
  • GPU with OpenGL 2.1 hardware acceleration


Loading IWADs

Doomsday requires IWAD files to run games. You can use the following ways to let the engine know where your IWADs can be found:

  • The first time you launch Doomsday and it doesn't find any IWADs, it will show a tab titled “Data Files?” containing a single button. Clicking the button opens a file dialog where you can pick a folder where your IWAD files are located.
  • If you have Steam installed, Doomsday will automatically detect if you have purchased a compatible game and will access the IWAD files in the Steam games directories.
  • Using the -iwad command-line option. You can either provide the path to the IWAD to use, or the path of the directory under which IWADs are located. Doomsday will look through the specified location and use all the recognized IWADs automatically. In other words, you can have the IWADs for all games stored in a single directory; Doomsday will use the appropriate one for each launched game.

    -iwad will also accept multiple paths as parameters:
     -iwad path1 path2
  • The configuration variable Config.resource.iwadFolder. This is typically set automatically via the user interface, for instance when you first start Doomsday. Its value can also be manipulated in the Doomsday Script command prompt.
  • The configuration file ~/.doomsday/paths is checked for iwaddir (see Files).
  • Environment variables DOOMWADDIR and DOOMWADPATH (see Environment).

Doomsday tries to recognize IWAD files based on their contents. The identification criteria can be viewed in GitHub.

Supported games

One game plugin, such as the Doom Plugin, is able to run many different variants of the game. Each variant emulates a specific version of the original game and typically has its own IWAD file.

Below is a list of all the games supported by the game plugins distributed with Doomsday.

Plugin Game ID Description
Doom 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
Heretic heretic-share Shareware Heretic
heretic Registered Heretic
heretic-ext Heretic: Shadow of the Serpent Riders**
Hexen 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

Home Screen

The Home screen in Doomsday 2 is a full replacement for the separate front-end application that was used in earlier versions. In Home you can manage your game profiles, resource packs and other add-ons, and join multiplayer games.

Home consists of a number of scrollable tabs. There are several ways to switch to a different tab:

  • Click on the tab names in the top of the screen.
  • Left and right arrow keys move focus to an adjacent tab.
  • Shortcut keys: D, H, X, O, M, and P (while not entering text in a text field.)
  • Click on the left or right edge of the screen.

Game library

The game library tabs list all the available game profiles and saved games associated with them. Each game profile can be configured to use a set of additional packages (data files, resource packs).

The appearance of the game tabs can be changed in User Interface settings (see Configuration). You can hide the game library description texts, and choose whether unplayable game profiles are visible. You can also hide entire game tabs, if you are not interested in a particular family of games.

Starting a game with or without additional packages. Click on a profile to select it, or move the selection with the arrow keys. When selected, Package and Play buttons slide in. The Package button shows a number for how many additional packages have been configured. Click Play or double-click the profile to start the game.

Selecting packages. Click the profile's Package button to choose which additional packages are going to be loaded when the game is started. On the left side of the dialog, you have a list of the packages attached to the profile. On the right, you can browse the available packages. The package browser works similarly to the Packages tab, and it has a search field and Info buttons (see Packages). To add a package to the profile, click the Plus button or double-click the package.

Loading a saved game. All saved games are listed under the game profile they were created in. Click on a save to select it, and then press the profile's Play button. Clicking on an already selected save will unselect it.

Old savegames created with Doomsday 1.x do not contain information about which data files and packages were in use when the save was created, so Doomsday can't determine which profile they belong to. Such saves are listed under each profile of the game.

Savegame information. Right-click on a saved game to see information about the save: which data files and packages were in use, the overall game parameteres, current map, and other status information.

Deleting a saved game. When a savegame is selected, a small X button appears next to it. Clicking the X lets you delete the save.

Creating a new profile. At the bottom of each profile list, there is a Plus button that creates a new, empty profile. In the profile parameters, you can choose which game will be used, and which packages are selected for loading. Note that game profiles cannot have a name that is identical to an already existing game profile name.

Duplicate, edit, and delete profiles. Any profile can be duplicated by right-clicking on it and selecting “Duplicate”. Profiles can also be edited to change their name and the set of selected packages.


The Packages tab is used to browse the available packages. With the exception of game IWAD files, the Packages tab shows all the data files that Doomsday can load. You can also quickly try out individual packages in one your existing game profiles.

Configuring the folders where packages are found. To let Doomsday know where your packages can be found, either select “Folders” in the Packages tab's actions menu (the “…” button under the tab title), or go to Data Files settings (see Configuration). The packages will not be copied or moved from wherever you keep them.

Searching for packages. The packages list may contains hundreds of items, so you may want to find the package you're looking for by entering some search terms. Enter the words to search in the search field at the top of the list. The search is limited to package metadata; the actual file contents are not accessed. When entering multiple words, only packages whose metadata contains all the words are shown.

Special search keywords. Some search words have a special meaning:

  • “hidden”: Only packages that are normally hidden will be shown. Packages that are hidden by default include, for example, packages inside other packages that will get automatically loaded.
  • “loaded”: Only show currently loaded packages. This is useful when browsing packages while playing a game.

Viewing information about a package. Right-click a package or click on the “…” button to view information about it. In the case of WAD files, all the maps in the WAD are listed so you'll know which map to start when playing. The info popup also shows the game title picture found in the package, and readme notes provided by the author. In some cases, Doomsday can make a guess about the game that the package is meant to be used with.

Quickly trying out a package. One of the most useful features of the Packages tab is quickly loading a package in one your games. This will make no changes to your profiles. Simply open the package info popup and click on “Play in…”. However, you should first check that the package actually is compatible with the game you are playing. Also be aware that if you are already in a game, it will be unloaded first and any unsaved progress will be lost.

Quickly adding a package to a profile. The “Add to…” button in the package info popup will add the package to one of your existing game profiles. The profiles that already have the package are labeled “ADDED” in the list.

Configuring optional contents. Some packages have optional subcomponents. For instance, add-ons that use the Snowberry Box format may include both opt-in and opt-out packages. When viewing information about this kind of collections, an additional “Options” button is shown in the package info popup. This will let you enable or disable individual contained sub-packages.


The Multiplayer tab lists multiplayer games that you can join. Servers on the local network are discovered automatically and are visible immediately in the Multiplayer games list. The master server is also automatically queried for any public servers.

Viewing server information. Right-click a server in the list to view status information about it. The same popup can be opened by clicking the small “…” button in the server description. The status information includes:

  • ping time
  • which game and map is currently running
  • outline of the current map
  • list of packages loaded on the server
  • list of connected players
  • server version

Joining a game. Join an open multiplayer game by clicking “Join” either in the server list or in the server information popup.

Player name and color. When a game is running (after joining a multiplayer game or also in single-player), go to the game's “Options” menu and select “Player Setup”. In this menu you can change your multiplayer name, player color, and (in Hexen) player class. Note that this is the game's own menu and not part of Doomsday's UI.

Connecting to a non-public server. To connect to a server that is not announced to the master server, select “Connect to Server…” in the Multiplayer tab's actions menu (“…” under the tab title), and enter the server's IP address or domain name.

Failure to connect? There are several reasons why you may not be able to join a multiplayer game. You will be notified if you don't have the same packages that the server is using. You can review the required packages in the server information popup. Connectivity problems can also be due to your firewall or network address translation (NAT).

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.

A server opens one TCP port for listening to incoming connections. The port must be open for incoming TCP traffic in the firewall. The port number is configured with the console variable net-ip-port. By default, a server uses TCP port 13209.

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.

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

 net info

Hosting a game. Use Doomsday Shell to host a multiplayer game of your own. The Shell allows you to start, stop, and control Doomsday multiplayer servers. This includes both your own local servers and remote servers on the internet.

doomsday-server runs in a background process and has no UI of its own. The Shell provides a couple of basic game options that you can change via the GUI. For example, you can choose between Deatchmatch and Co-op mode, change the current map, and enable or disable monsters. The full set of console variables can be modified via the Console tab (text-mode command line interface).

If your server is not public (i.e., announced to the master server), a client can connect to it manually using the IP address or domain name.

For more information about the Shell, see Shell Help in the wiki.

Task bar

The task bar is a central element of Doomsday's UI. It is available at all times and provides access to key features of the engine. For example, you can modify configuration settings, show the Home screen, and unload the current game.

You can show the task bar by pressing Shift + Esc.

App menu

The rightmost button in the task bar (with the DE logo) opens the Doomsday app menu.

Tutorial. The first-run tutorial points out the basic features of Doomsday's UI. It is only shown once, but you can manually show it again by selecting “Help: Show Tutorial”.

Browsing and loading packages. “Browse Packages…” opens the package list in a sidebar where packages can be loaded and unloaded manually. You can also view information about packages like in the Home screen. The sidebar is only available when a game is loaded. You can use the “loaded” keyword to filter the list so that only the currently loaded packages are listed.

Data from newly loaded packages may not be used until a new map is started in the game. Use of external textures can be enabled and disabled in Renderer settings.

Checking for updates. Doomsday queries the website to see if there are newer builds and shows a notification when updates are available. You can always also do a manual update check by selecting “Check for Updates”.

Clearing the resource cache. Some resources and metadata get cached for later access. This allows Doomsday to load the resources faster and operate more efficiently. Usually it is unnecessary to clear the cache manually. See Files for the cache's location.


The task bar's Gear button opens the configuration menu. This is where the majority of Doomsday's settings can be viewed and changed. Some of the settings are only available when a game is loaded (“Input”, for instance).

Reset to defaults and advanced settings. Many settings dialogs have a “Reset to Defaults” button. This affects only the settings in that one particular dialog. Sometimes a Gauge button is also available. It is reserved for advanced settings that are useful for developers and modding.

Renderer settings. Most of the renderer settings are managed via appearance profiles. This makes it easy to select one of the presets, such as a vanilla look or more exaggerated effects. The dialog has a couple of general settings in addition to the active appearance profile. The “Pixel Density” slider is particularly useful as it allows improving rendering performance and achieving a more pixelated, 1990s VGA-style look. The selected appearance profile applies to all games.

Some resource packs with high-resolution textures are intended to be used with the unmodified original games. However, a PWAD file may replace some of the textures with custom ones. The “External Images” options allow you to control when external images are actually enabled if the resource packs in use aren't compatible with the loaded PWADs.

Renderer appearance sidebar. Click the Gear button next to the selected renderer appearance profile and select “Edit” or “View” to open the appearance sidebar. Alternatively you can open the sidebar with the rendedit console command. Individual settings groups can be folded and unfolded by clicking on the group titles. You can continue playing the game while the sidebar is visible. When you're done, dismiss the sidebar with the X button in the top right corner.

Video aspect ratios. In addition to basic game window parameters, the Video settings dialog has a set of aspect ratio options. These control the aspect ratios applied to specific elements in the game:

  • “Original 1:1”: The aspect ratio is exactly as in the original game.
  • “Smart”: The aspect ratio is dynamic but does not stretch too far away from the 1:1 ratio.
  • “Stretched”: The aspect ratio is unrestricted and adapts to window dimensions. Game elements may appear too wide or tall with this setting.

Audio backends. Some of the audio options are dependent on the active audio backend(s). For example, a MIDI sound font is supported by the FMOD and Fluidsynth plugins. 3D sound and reverb are supported by FMOD, OpenAL, and DirectSound. The audio backend can be reconfigured on the fly; any changes are applied when you close the popup.

Game controllers. Doomsday comes with a few preset bindings for different gamepads. To use one of the presets, click on the “Game Controller Preset” button and select a suitable one. Then click “Apply” to erase all your existing game controller bindings and activate the ones in the preset. You can still manually edit the bindings in the game's “Options” menu.

Mouse input settings. The “Sync Axis Sensitivities” option will ensure that mouse sensitivity is the same in both the horizontal and vertical directions.

Minimizing mouse latency. The default input settings try to replicate the feel of the original 35 Hz input events of Doom. However, when the screen is actually refreshed at a higher rate, this may feel distractingly laggy. The 35 Hz limiter can be disabled in the advanced input settings (click the Gauge button). This will minimize mouse input latency as much as possible. You may additionally want to disable mouse filtering by toggling the “Filter X Axis” and “Filter Y Axis” options.

Local multiplayer packages. By default, clients are not allowed to load packages in addition to what the server is using. This avoids any potential compatibility issues with the client's packages overriding some of the game's definitions. However, you can manually enable local packages in Network settings. You can then select additional local packages for multiplayer games in the server information popup before joining the game.

User Interface settings. The “Scale” setting applies to the Doomsday UI only, and adjusts the overall size of UI elements and fonts. Lowering the UI scaling may be helpful for example when using a very low display resolution. In the Home screen there will be more tabs visible at the same time when using a smaller UI scale.

Updater settings. The Updater settings determine when Doomsday will check for available updates. When an update is downloaded, it is saved to ~/Library/Caches/Deng Team/Doomsday Engine/ .

Log history and log options menu

The log message history panel slides in from the left edge of the view. When visible, you can drag its right edge to resize it.

The leftmost button in the task bar opens the log options menu:

Show Full Log
Expands the log history panel to its full size. When the task bar is open, pressing PageUp will also expand the panel size.
Close Log
Dismisses the log history panel.
Go to Latest
Scrolls the log history to the latest message.
Copy Path to Clipboard
Copies the doomsday.out file path to the system clipboard to make it easier to find the output file.
Clear Log
Deletes all log messages from memory. The doomsday.out file is unaffected.
Snap to Latest Entry
When this setting is enabled, new log entries will cause the history panel to scroll to the latest entry (bottom of the list).
Entry Metadata
When this setting is enabled, log entries will be prefixed with a timestamp and categorization symbols.
Log Filter & Alerts
Settings for filtering which log messages get printed. You can choose filtering options individually for each engine subsystem. Developer messages (“Dev”) are primarily intended for developers and debugging, so they are disabled by default. The “Alert” toggles cause warnings and errors to pop up in the notification area.

Command prompt

The middle of the task bar is occupied by a command prompt text field. Here you can enter console commands and modify console variables manually. This is typically most useful for developers, modders, and other advanced users.

Console basics. Type help to get started. This prints some basic information about how to use the console, and commands for listing all the available console commands and variables. At any time, press Tab to autocomplete the word being typed. This will pop up a list of all possible completions, including the current values for any variables. You can change console variable values as follows:

 sound-info 1

Shortcut key. You should set up a console shortcut key if you find yourself going to the console often. The shortcut defaults to Tilde (U.S. keyboard) but you can choose your own shortcut key by clicking the “>” button next to the command prompt.

Interactive Doomsday Script prompt. Doomsday Script is a fully-fledged Python/Ruby-like scripting language built into Doomsday 2. While it doesn't yet allow full access to all engine features, it is being improved in each release. The command prompt can be switched to Doomsday Script mode by right-clicking the “>” prompt menu button. Everything entered into the command prompt is then run as Doomsday Script. This mode is intended only for developers.

Command line usage

It is possible to launch Doomsday directly from the command line. If all data files can be found under the default directories, the engine should be able to launch itself without further assistance. If not, command line options must be used to configure data file locations and other settings. [options]

Everything following is ignored. @ can be used to specify a response file whose contents are added to the command line.

-file | -f
Specify one or more data files or packages (.pack , PK3, WAD, LMP) to load at startup. When used together with the -game option, the specified files will be loaded at startup. Without -game they are just registered as available files and can then be added into game profiles in the Home screen. It is also possible to load data files at runtime by opening the Packages sidebar (see Task Bar) or with the load console command.
-game | -g
Sets the game to load after startup. If omitted, the Home screen will be shown after startup. See Games for a list of available games. For example: -game doom1-ultimate
-h | -? | –help
Prints a brief list of the command line options.
Specifies a directory where to look for IWAD files. Searches for IWADs from all known games and automatically loads them when needed.
Show version information.
-wnd | -window
Starts in windowed mode. The default is to start in fullscreen mode.
Sets the size of the Doomsday window. In fullscreen mode specifies which display resolution to use.

Additional options

Center the window (when not in fullscreen mode).
-devlog | -nodevlog
Enables or disables developer log entries. These are useful for debugging and/or troubleshooting, but are too verbose or technical for everyday use.
Set the name of the error output file. The file is written to the runtime folder. This output file is created in addition to the usual doomsday.out . For example: -errors errors.out
-fullscreen | -nofullscreen
Enable or disable fullscreen mode.
-icd | -imusic | -isfx
Set the audio backend for CD playback, music, and sound effects. The following audio backends are available:
  • dummy
  • fmod
  • fluidsynth
  • sdlmixer
  • openal
Set a scaling factor for UI fonts. For example: -fontsize 1.5
Set the log output level. The levels are: XVerbose, Verbose, Message, Note, Warning, Error, Critical.
-maximize | -nomaximize
Maximize the window, or set the window to non-maximized mode.
Disable antialiasing.
Disable gamepads and other game controllers.
Disable mouse input.
Disable vsync.
Set the name of the log output file. The file is always written to the runtime folder. This option overrides the default doomsday.out .
Set additional folders where to find packages. Works similar to -iwad.
Reset the engine configuration to default values. In practice, this just erases the contents of the persist.pack file that stores configuration variables and UI state. The affected variables include, for example, game window size and position, and log filter settings.
-speaker51 | -speaker71 | -speakerprologic
Overrides the FMOD backend's speaker mode (surround 5.1, 7.1, or SRS 5.1/Prologic/Prologic2). This option can also be changed in Audio Settings (see Configuration).
-verbose | -v
Print verbose log messages. Specify more than once for extra verbosity.
Enables all log messages (normal and developer, all levels).
When starting directly into a game using -game, automatically also jump to a specific map. The map can be specified either as the map number, a pair of numbers (episode and map), or the map identifier (e.g., “MAP12”).


Your runtime files (savegames, screenshots) are inside a folder called ~/Library/Application Support/Doomsday Engine/ .

Console commands to execute after loading the game with the -game option.
Cached data that helps Doomsday run faster. You can delete the contents of this folder; Doomsday will recreate them automatically as needed.
Game profiles and saved values for console variables and control bindings.
Log message output file.
Folder containing all saved games. Each game has its own subfolder for saves. Note that the subfolders are game-specific rather than profile-specific; if you create custom game profiles, their saves will be written in the same subfolder as saves from the default game profile.

Additional files:

Customized file path configuration (basedir, libdir, iwaddir). The syntax of the file is documented in the wiki.


The following environment variables are recognized by Doomsday.

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

Bugs and known issues

Doomsday remains a work in progress so there usually is a number of bugs and known issues.

Bugs and Features
The official place to report new bugs, comment on existing ones, and submit feature requests is the Tracker.
Multiplayer Issues
The bug tracker has a list of known multiplayer issues and needed enhancements.

See also


id Software created DOOM and then released its source code.

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

Andrew Apted wrote glBSP.

Christopher Bruns contributed code for supporting VR rendering with Oculus Rift.

Dave Gardner maintains of high-resolution texture packs and creates 3D models.

Roman Hargrave has been cleaning up the Doom64 Plugin.

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.

Jaakko Keränen created the Doomsday Engine and is the lead developer of the project.

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

Daniel Swanson is a developer in the Deng Team, original author of the website backend, and former maintainer of the jDoom Resource Pack.

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

guide/2.0/readme_macos.txt · Last modified: 2017-03-24 10:57 by wikidocs