DoomRunner Documentation version 1.0. Current for DoomRunner version 1.0.3.
This document was last updated June 23, 2011.
DoomRunner is a cross-platform, graphical, easy-to-use frontend for the Doom computer game. It is intended for single player, although not restricted to single player games (multiplayer games could be configured by adding the specific command line parameters, explained later in this document). DoomRunner is written in C++, and uses the Qt Graphical Library. It is released under the GNU GPL 3.0. It is written by Nick Virag "sirthunder516". It supports a variety of ports.
The main menu has several components: a row of tab-like buttons across the top, a list of games, a picture, another row of buttons, and a text box. The "tabbed" buttons across the top of the window serve the same purpose as the buttons across the bottom, although across the top, there are two more options ("Settings" and "About") that are not present in the bottom row. The functions of these buttons will be described step-by-step following this section. As for the other elements of the main window, they should all be straightforward- the list selects a game "profile". The term "profile" is explained in the next section. Each "profile" can be represented by not just a name, but also an image and a small notes window. The image and notes are to the right of the list.
DoomRunner has a special "profile" system. Each "profile" is essentially a custom configuration file; they contain information about what Doom source port to use, what Iwads and Pwads to use, among other things. The list of games in the main window/menu is actually the list of profiles: DoomRunner comes with two pre-configured profiles by default for both FreeDoom and Doom Shareware. To play either of these games, press the "Play" button. This will run whatever Doom source port has been selected, with all of the settings in the profile.
Nearly every screen in DoomRunner has a small, functional "Help" button somewhere near the lower right corner. This button opens up a small window that describes all of the current window's functions.
A new game profile can be created very easily, by pressing the "New" button in the main menu. The "New" button will prompt you for a name and for a description of the profile. A description, i.e. "Game Notes" is not required, but a name is. It is helpful to name a profile either after the type of game that it will hold (for example, naming a profile "Alien Vendetta" or "Plutonia"). When "OK" is pressed, the "Edit" menu is opened. Most other settings are copied from the previously created profile by default.
Select "Edit" in the main menu to edit the selected game profile. This opens up the Edit window. The Edit window contains a row of tabs surrounding various controls used for changing settings, with a row of buttons on the bottom. On the bottom, there is a "Help" button, an "OK" button, and a "Cancel" button. Depending on which tab is selected, there may also be either an "Auto" or an "Erase Iwad" button visible.
The "General" Tab is the first visible tab of the Edit window. This tab contains a few basic settings, and some of which do not affect gameplay. The only settings in the "General" tab that affect gameplay are the "No mouse" checkbox and the "No joystick" checkbox. This is because the other settings are for DoomRunner only and are not seen by the Doom source port that is being used. The settings "Game Name" and "Game Notes" are for changing the current profile's name and description respectively. The configuration for both is visble in DoomRunner's main menu. The picture displays the current preview image for the profile being edited. This image is automatically set to a default (which can be re-set by clicking on "Use default image"), but it can be changed by clicking on "Set custom image", and then clicking on the button with three dots on it to select an image. Many formats are supported.
The "Levels" Tab is where Iwads, Pwads, and Dehacked files are added and configured. Click the "Add a file" button to select an Iwad, Pwad, or Dehacked file. Files are sorted automatically based on name. Files with any of the following names are added to the "Select main wad:" menu: "Doom1.wad", "Doom.wad", "Doom2.wad", "Freedoom.wad", "Tnt.wad", "Plutonia.wad", "Chex.wad", "Chex2.wad", "Chex3.wad", "Doomu.wad", "Heretic.wad", "Hexdd.wad", "Hexen.wad", and "Strife1.wad". Names are not case sensitive. Iwads are copied to a specific folder for use with DoomRunner. Pwads and Dehacked files retain their original location. When a Pwad or Dehacked file is added, it becomes a part of the "Select addon files:" menu. Entries in this menu can be reordered, unchecked, and removed. When an item on the menu is not checked, it is not run when Doom is played. "Removing" an entry from the "Select addon files:" menu does not delete the file, it only removes it from use with that profile. At the bottom of the screen, there is a special button called "Erase Iwad". This deletes the selected Iwad (main wad) from DoomRunner's Iwad folder. It is not removed from it's original location.
The "Audio/Video" Tab allows changing the current graphics and sound settings. "Enable Music" and "Enable Sound" are for allowing music and sound, respectively. "8-bit Graphics" and "OpenGL Graphics" allow switching between Doom's original 8-bit graphics engine, and a modern OpenGL render. OpenGL is recommended if the host computer supports it. The "Aspect Ratio:" menu is for setting Doom's graphics according to the host monitor; 4:3 applies to the traditional, older, less rectangular monitors. 16:9 applies to widescreen monitors. 16:10, sometimes referred to as 8:5, is also widescreen, however, it is slightly differently shaped. "Display Resolution:" is for configuring your monitor's specific display resolution. The menu's contents change based on the selected aspect ratio. It is best to press "Auto" at the base of the window, to automatically set Doom's graphics according to the host computer. This eliminates the need to know the host computer's monitor's aspect ratio and resolution. The image to the right of the buttons displays how the Doom game would look with the current settings.
The "Advanced" Tab is for changing more advanced settings. The "Additional commands" box is where commands are typed for features that aren't accessable directly by DoomRunner, such as commands for multiplayer. The "Select source port:" menu is for changing the source port that will be used. Some ports such as PrBoom have multiple options. This is because many ports have separate executables for OpenGL, and it is the user's choice to set up DoomRunner with these additional executables or not. So, for example, for just 8-bit graphics support in the ZDoom engine, one would select only "ZDoom", and then configure the path to the ZDoom executable by clicking the button labeled "...". If one wanted only OpenGL support in ZDoom, they would select "GZDoom" and press the "GL" button to select the path to the GZDoom executable. To easily have both 8-bit and OpenGL support in DoomRunner, one would select "ZDoom + GZDoom", and then use the "..." and "GL" buttons to set the paths to ZDoom and GZDoom respectively.
Select the "Erase" button to remove the selectted game profile in the main menu. No save files, wads, or Dehacked files are deleted.
Select "Settings" in the top right corner of the main menu to access the general settings. These are settings that are universal across all of DoomRunner, and not specific to any profile. The "Select style:" menu allows changing the way DoomRunner visually appears. The different styles do things such as change the colors of DoomRunner and change the font size. On Linux-based systems, in some cases "Native Style" may be identical to one of the other styles. This is because some Linux computers use one of the other styles by default. "Window Slide Effect" is a feature that centers the DoomRunner window and slides new windows to the center from the left of the screen. This feature does not work on Microsoft Windows, or work well on some Linux distributions. There is another feature- "Native Style Menu Bar (Mac Only)" that, if enabled on a Mac OS X machine, will merge the top row of buttons in the program with the top bar of the screen. This creates a more "native" look.
There are some special, hidden settings for DoomRunner. These are accessable only by editing configuration files directly with a text editor, and are not configurable using any button or menu within DoomRunner itself. If the host computer is a Windows or Linux machine, go to the directory with DoomRunner, then open the "profiles" directory and open "profile0.txt" in a text editor. On a Mac OS X computer, right-click the executable and select "Show Package Contents", double-click on "Contents", double-click on "MacOS", double-click on "profiles", then double-click "profile0.txt". Ignore the first four lines. Line number five, if containing a "1", will use OpenGL ES mode with Doom Legacy instead of OpenGL. The next line, if containing a "1", will alert the user before running a profile, open a dialog containing the command to be run, and when finished, display the source port's output on the screen. The final line, if containing a "1", will use local paths instead of global paths on a Linux machine (the command to intialize PrBoom will be "./prboom" instead of "prboom") for running the default source port. The configuration of the last three numbers on Microsoft Windows and Mac OS X machines is "000", on the Pandora is "101", and on other Linux machines is "010", with each number on a separate line.
Iwads from other games such as Ultimate Doom, TNT, and Chex Quest can be installed easily. Create a new profile via the "New" button, then in the "Edit" menu, select "Levels", then select "Add a file". The user will be prompted to select a file. DoomRunner will sort the file automatically. If the user has selected an Iwad, it will be added to the "Select main wad" menu. The Iwad must then be selected from that menu.
Iwads from other games such as Ultimate Doom, TNT, and Chex Quest can be installed easily. Create a new profile via the "New" button, then in the "Edit" menu, select "Levels", then select "Add a file". The user will be prompted to select a file. DoomRunner will sort the file automatically. If the user has selected a Pwad or Dehacked file, it will be added to the "Select addon files:" list. It can then be moved up/down (giving it a lower or higher priority respectively), removed from the list, or unchecked. If it is unchecked, it is disabled temporarily. The list of Pwads and Dehacked files can store up to 64 entries.
Select the profile in the main menu that will have optimized graphics. Press the "Edit" button, then navigate to the "Audio/Video" section. There is a button at the base of the window titled "Auto". Press it. It will automatically configure the graphics for that profile.
Iwads, unlike Pwads or Dehacked files, are copied to a special directory for DoomRunner. On Mac OS X machines, they are stored in [doomrunnerdirectory]/wads/iwads and on all other machines, they are stored in [doomrunnerdirectory]/DoomRunner.app/Contents/MacOS/wads/iwads, however, deleting Iwads directly is not recommended. Because of this, DoomRunner has a built-in feature to remove Iwads. To delete an Iwad, in the main menu, press "Edit", then select "Levels", and in the "Select main wad:" menu, select the Iwad that you want to delete. At the base of the window, there is a button labeled "Erase Iwad". Press it to remove the Iwad that you selected. The Iwad would not be removed from it's original directory, but it would be removed from it's location in the DoomRunner directory.
Pwads and Dehacked files, unlike Iwads, are not copied to any directory of DoomRunner. Only their path is saved. To remove a Pwad or Dehacked file from a profile's configuration, select that profile in the main menu, press "Edit", go to "Levels", select the Pwad or Dehacked file that should be removed, and press the "Remove" button.
The "Select source port:" menu is for changing the source port that will be used. Some ports such as PrBoom have multiple options. This is because many ports have separate executables for OpenGL, and it is the user's choice to set up DoomRunner with these additional executables or not. So, for example, for just 8-bit graphics support in the ZDoom engine, one would select only "ZDoom", and then configure the path to the ZDoom executable by clicking the button labeled "...". If one wanted only OpenGL support in ZDoom, they would select "GZDoom" and press the "GL" button to select the path to the GZDoom executable. To easily have both 8-bit and OpenGL support in DoomRunner, one would select "ZDoom + GZDoom", and then use the "..." and "GL" buttons to set the paths to ZDoom and GZDoom respectively. See below sections for platform-specific differences.
On Mac OS X, Microsoft Windows, or most Linux distros, no changes to the above process are necessary. However, if a source port is being used and doesn't seem to work, while "Prboom (Onboard)" works, copy the source port executable to to the "[doomrunnerdirectory]/wads/iwads" directory (or "[doomrunnerdirectory]/DoomRunner.app/Contents/MacOS/wads/iwads" on Mac OS X)
On the OpenPandora, the source port executable must be in the directory with the iwads. Source Ports that use OpenGL ES also require a special library to be added to the system. This can be demonstrated with the "Doom Legacy" source port configured specifically for use with DoomRunner, downloadable at http://www.retronuggetdev.com/doomrunner
Some Iwads, such as "Action Doom 2" (action2.wad) don't have a standard name and therefore are not recognized as Iwads. However, a user can add non-standard Iwads to DoomRunner manually. The instructions for doing this are in the following two panels.
On Mac OS X, the folder containing the Iwads is located at "[doomrunnerdirectory]/DoomRunner.app/Contents/MacOS/wads/iwads". The directories inside DoomRunner can be accessed by right-clicking "DoomRunner.app" and selecting "Show Package Contents".
For all other operating systems, the Iwads directory can be accessed at "[doomrunnerdirectory]/wads/iwads".
DoomRunner is open-source and is released under the GPL license. It is free to share and distribute. However, someone who shares DoomRunner must include this file (documentation.html) as well as the GPL license (gpl-3.0.txt) and the readme file (readme.txt).
Modifying DoomRunner's source is legal as long as the changes follow the GPL 3.0 guidelines and follows the guidelines in the "Copying and Sharing DoomRunner" section in this document.
Nick Virag- Programmer and Designer of DoomRunner
PrBoom Authors- PrBoom
FreeDoom Authors- FreeDoom Iwad
iD Software- Doom Shareware Iwad
Pickle- OpenPandora version of PrBoom
Selling DoomRunner, in any way, shape or form, would be violating the GNU GPL 3.0. Therefore, selling DoomRunner would be illegal. Don't do it.
DoomRunner 1.0.3 Copyright 2011 Nick Virag. Email: nick@win31.net.
Official DoomRunner webpage