DoomBroLauncher

A preconfigured launcher for Doom classic games, fully compatible with Xbox controllers for Windows PCs using GZDoom Source Port.

Our goal is to propose an organized way to execute Doom Classic games using GZDoom Source Engine. Taking advantage of its command line parameters we can set custom saves, screenshots and configuration paths in order to make it more portable and easy to update. Also, as part of an HTPC experience on Windows, we preconfigured a settings file to fully work with XInput devices, including Xbox 360 controllers, Xbox One controllers, or similar controllers.

First release is focused for Windows systems, a Linux version is planned for the future.

---

Table of Contents

1. Motivation
2. What makes this launcher different than others of the same kind?
3. Usage
4. Installation
   1. Prerequisites
      1. Doom I (Shareware)
      2. The Ultimate Doom
      3. Doom II
      4. Master Levels for Doom II
      5. Final Doom
      6. Officially released levels
         1. "Sewers" and "Betray" levels
         2. "No Rest for the Living" episode
      7. Semi-official levels
         1. "The Lost Episode"
         2. John Romero's levels
         3. John Romero's SIGIL
      8. Using WadSmoosh to create "Doom Complete" compilation
   2. Steps to install the DoomBroLauncher
5. Details of preconfigured settings
   1. Game Settings
   2. Controller Settings
   3. Preconfigured controller bindings for XInput devices (Xbox 360 or Xbox One controllers)
      1. Xbox 360 and Xbox One key bindings
6. Advanced Configuration
   1. Create more batch-scripts to run new Doom games or mods
      1. Create an script for an IWAD (complete games)
      2. Create an script for a PWAD
   2. Changing the Game Skill (difficulty)
   3. Integration with EmulationStation

---

1. Motivation

The original idea came when one of my best friends asked me for a good source port to run his old Doom games, he needed something easy to execute, so I created this launcher for him using scripts to call GZDoom, a source port that provides a very good compatibility with games and mods and can enhance the graphics without compromising the original look and feel experience.

So I ended up with a set of batch scripts and folders in certain order so they can be portable and easy to execute. Each Doom game will be represented by their own batch script created based on a template, so the user just need to double click the batch of the game to launch it. Since GZDoom puts the saves, configurations and screenshots files on its root folder (in order to be portable), it can be a problem for people that cannot recognize these files when they try to update the GZDoom software, they can override configurations or delete saves if they are not careful. So to reduce that risk there are different folders: A folder for configurations, a folder for saves, a folder for screenshots and a folder for port binaries. The batch scripts knows the location of these folders thanks to some special command line parameters. So, if you want to update GZDoom binaries, you just need to delete the contents of the Doom/.DoomBroLauncher/port folder, and then unzip the new ones on it.

I've been working with Kodi and EmulationStation configuring my own HTPC Windows machine and I noticed that the batch-scripts approach of having one script for each game fits very nice with the way how EmulationStation lists and executes roms. Originally to execute Doom games from EmulationStation you need to configure it to filter wads and build an execution line where you call the source port with the wad as parameter, the confusion starts when the wad you want to run is actually a mod (PWAD) so you need a way to define its respective IWAD, which means definitely another way to run the games, so relying this responsibility to batch scripts is the most portable and easy to maintain idea. This is similar to the solution provided for Retropie but a little less complex. Also since this works with EmulationStation, it was a good idea to preconfigure a settings file to work with XInput devices (Xbox controllers), so we can navigate in Kodi and EmulationStation and play Doom games with a controller from the couch.

2. What makes this launcher different than others of the same kind?

• Completely open source, hosted on GitHub and published under GPL v3 license
• A preconfigured settings file is provided which enables Xbox controllers with an intuitive layout and a display resolution of 1920x1080 (Full HD) in full screen, also including some tweaks on the map display (all of them detailed below in this documentation)
• The usage of Xbox controllers is optional, the game can still be played with keyboard and mouse
• Each Doom game is called by individual batch scripts that have a descriptive name and you don't need to enter additional prompts, just run the scripts by double clicking them or calling them from a command line
• Batch scripts are the native and fastest way to start a program and they are easy to maintain. Other launchers use another scripting languages which means you need an external runtime that not all users may have installed, or they use compiled executables which are harder to edit than a simple .bat file. At the end this is just a launcher, let's keep it simple
• Lightweight scripts, about 50 KB all of them!
• New batch scripts with more Doom games or mods are easy to add. They reuse common variables defined in a single file which means that any change is reflected on all scripts (for example addition of new parameters)
• Includes scripts to run the Master Levels for Doom II with 2 different orders (PC and PSN), without the need to edit TEETH.WAD levels
• Only open source code or programs are used by this project, including the source-port
• Easy to integrate with EmulationStation: Boxarts, metadata and documentation is provided below.

3. Usage

Use this launcher to start Doom Classic games and don't worry about complicated source ports configurations, just copy your games on the wads path and you are ready to play them by running the batch file with the name of your game.

Notes:
This project is a launcher, so the installation of a source port is required (in this case GZDoom), installation instructions are easy and provided below. Games (or .wad files) are not provided here, you need to provide them. If you don't own the games, read the prerequisites section to find where you can buy the commercially distributed ones, and where you can download the free ones.

4. Installation

4.1. Prerequisites

This release of the launcher is focused for Windows. You must know if your Windows system is 32 bits or 64 bits, check instructions here, you will need this later.

Also, you need Doom wads which have the game data, they are not included with DoomBroLauncher because some of them are commercially distributed and others are not compatible with DoomBroLauncher's GPL license, but we can list the places where you can buy or download them:

4.1.1. Doom I (Shareware)

This shareware contains the first episode of Doom I.
Latest version of the shareware is v1.9, download it from https://www.doomworld.com/idgames/idstuff/doom/doom19s.

Lower versions can be downloaded from doomworld.com or archive.org.

4.1.2. The Ultimate Doom

This is the complete version of Doom I and it is commercially distributed:

• You can buy the game directly from Steam or GOG.
• You can buy Doom 3: BFG Edition from Steam or GOG, it comes with copies of the classic Ultimate Doom and Doom II. These versions come with Steam/GOG Achievements, which is a nice feature to have if you plan to play them from the Doom 3: BFG Edition launcher, but keep in mind that these classic versions are modified: The red cross symbols on all types of medical kits where replaced by pills (due to an infringement complaint from the Red Cross), and Wolfenstein's secret levels were censored. So this can be an issue for people looking for the original experience. Besides that, the games remains the same and can be used to load mods as well.

4.1.3. Doom II

Doom II is commercially distributed:

• You can buy the game directly from Steam or GOG.
• You can buy Doom 3: BFG Edition from Steam or GOG, it comes with copies of the classic Ultimate Doom and Doom II. As previously mentioned, these are modified versions.

4.1.4. Master Levels for Doom II

Master Levels for Doom II is an expansion for Doom II, it is commercially distributed as a bundle with Doom II:

• You can buy the bundle from Steam or GOG.

4.1.5. Final Doom

Final Doom introduces TNT Evilution and Plutonia Experiment episodes as sequels of Doom II. They are not expansions, but stand alone games. They are commercially distributed:

• You can buy the game directly from Steam or GOG.

4.1.6. Officially released levels

Here we are going to list levels that don't belong to the original games, but they were officially added by id Software (or authorized publishers) on re-releases.

4.1.6.1. "Sewers" and "Betray" levels

Sewers for Ultimate Doom, and Betray for Doom II are exclusive levels of the Xbox ports of Doom 3 Limited Collector's Edition (first appearance) and later on Doom 3 Resurrection of Evil.

The levels were commercially distributed on Xbox only, but you can download a free bug-fixed PC version of these levels at http://www.classicdoom.com/xboxspec.htm.

4.1.6.2. "No Rest for the Living" episode

No Rest for the Living is an expansion for Doom II, adding a second episode. It was bundled with Doom II and sold on Xbox Live Arcade for the Xbox 360 (first appearance), and later on Doom 3 BFG Edition.

It is commercially distributed:

• You can buy it on the Xbox Live Arcade (now called Xbox Marketplace).
• You can buy Doom 3: BFG Edition from Steam or GOG. We recommend to buy it for PC since the wads files are easier to access than in consoles.

4.1.7. Semi-official levels

4.1.7.1. "The Lost Episode"

The Lost Episode is a mod for Ultimate Doom, adding a fifth episode including remastered versions of levels only seen on Doom Alphas, Jaguar's Doom, and PlayStation 1's Doom. The original levels were never released on PC, but the team behind this project did an excellent job by recreating the levels maintaining the original flow, look and feel and made them playable on PC. From our stand point, this episode should be considered as official, since original designs came from official releases from id Software, even when the port was made by an independent team.

Download it free at https://www.doomworld.com/idgames/levels/doom/Ports/j-l/lostepis

4.1.7.2. John Romero's levels

John Romero was one of the co-founder of id Software, and he was the designer of many of their games, including Doom I and Doom II.

Doom I Episode 1 has two levels not designed by John Romero, so he remake them because he wanted to create an episode consisting only of his own work.

The levels are:

• Phobos Mission Control (E1M4b): Download it free at https://twitter.com/romero/status/725032002244759552
• Tech Gone Bad (E1M8b): Download it free at https://twitter.com/romero/status/688054778790834176

We think these levels should be considered as official alternative scenarios, because even when id Software did not release them, they were released by John Romero himself, with ideas he wanted to implement at the time of designing the original games.

4.1.7.3. John Romero's SIGIL

SIGIL is a new 5th episode for the original Doom released by John Romero to celebrate the 25th Anniversary of Doom.
You can get Sigil by purchasing it at https://www.romerogames.ie/si6il, or you can download the free version from the same site. The difference between both versions is that purchased one includes the soundtrack by Buckethead, while the free version includes the MIDI soundtrack by James Paddock.

4.1.8. Using WadSmoosh to create "Doom Complete" compilation

WadSmoosh is an excellent tool for merging Ultimate Doom (including "Sewers" level), Doom II (including "Betray" level), No Rest for the Living episode for Doom II, Master Levels for Doom II, Final Doom and Sigil into one single IWAD file. It only works with strictly official releases and creates a .pk3 file.

We highly recommend to create this Doom Complete compilation as it provides a smooth experience, it organizes The Master Levels for Doom II as one single episode and it places the secret exit switches to go to Sewers and Betray levels. For more information, check the project's web page, and their forum thread.

---

4.2. Steps to install the DoomBroLauncher

1. Download DoomBroLauncher:
   To download the launcher, go to https://github.com/BrosMakingSoftware/DoomBroLauncher/releases and download the latest zip file available.

2. Unzip DoomBroLauncher:
   Unzip the DoomBroLauncher zip in a folder on your system. For example, I'm going to create a folder called Games under my home folder on Windows (C:\Users\diego\Games\, or %HOMEPATH%\Games) and I will unzip all the contents on that folder. Its root folder is called Doom, and it has a subfolder called Doom/.DoomBroLauncher, where you can find more folders where configuration files are stored.

   Check the folder structure in this image:

   Master Levels for Doom II has 2 folders with one set of scripts each one, one representing the PC Release order and another one with the PSN Release order.

3. Download GZDoom:
   To download GZDoom, go to https://zdoom.org/downloads and select the version that matches your Windows system (32 bits or 64 bits), this is important since the program will not start on the wrong system version.

   Pick the latest GZDoom version available, you will download a zip file with a name like gzdoom-bin-X-x-x.zip for 32 bits, or gzdoom-bin-X-x-x-x64.zip for 64 bits, where the X-x-x represents the current version of the program, for example 4.1.1.

   Open the zip file and copy its contents to the Doom/.DoomBroLauncher/port folder:

4. Now it's time to copy your Doom games:
   Find your .wad files from your copies of Doom (depending of your game, it can be in one place or another, check this for more info), and copy them to the Doom/.DoomBroLauncher/wads folder. In the case of Master Levels for Doom II, copy all the levels in Doom/.DoomBroLauncher/wads/master_levels.

   The existing scripts will expect the following .wad names:

   Game / Mod	`.wad` name
   Doom Complete (WadSmoosh pack)	doom_complete.pk3
   Doom 1 - Shareware	DOOM1.WAD
   Doom 1 - The Ultimate Doom	DOOMU.WAD (you may need to rename this file if its original name is DOOM.WAD)
   Doom 2 - Hell on Earth	DOOM2.WAD
   Final Doom (1st Episode) - TNT Evilution	TNT.WAD
   Final Doom (2nd Episode) - Plutonia Experiment	PLUTONIA.WAD
   Master Levels for Doom II Note #1: There is no need to modify TEETH.WAD, this launcher works with the original file. Note #2: These levels are referenced by 2 sets of scripts divided in folders, one representing the _PC Release order_ (alphabetical order) and _PSN Release order_.	ATTACK.WAD BLACKTWR.WAD BLOODSEA.WAD CANYON.WAD CATWALK.WAD COMBINE.WAD FISTULA.WAD GARRISON.WAD GERYON.WAD MANOR.WAD MEPHISTO.WAD MINOS.WAD NESSUS.WAD PARADOX.WAD SUBSPACE.WAD SUBTERRA.WAD TEETH.WAD TTRAP.WAD VESPERAS.WAD VIRGIL.WAD
   Mod for Doom 1 - Sewers (Xbox Level) [E3M1]	SEWERS.WAD
   Mod for Doom 1 - Sigil (John Romero's 5th Episode) [E5M1 to E5M9] Note #1: There are 4 ways to play Sigil: Free or Purchased versions, and for each of them: Normal or Compatible versions. The priority of loading is determined by the script depending of the files it finds, check the groups listed (from 1 to 4) on the next column. Note #2: Purchased versions are defined by the existence of the "SHREDS" files (`SIGIL_SHREDS.wad` for normal version, `SIGIL_SHREDS_COMPAT.wad` for the compatible version). Note #3: Compatible versions are focused to not overload the vanilla engines limitations. They are defined by the existence of the "COMPAT" files (`SIGIL_SHREDS_COMPAT.wad` for purchased version, `SIGIL_COMPAT.wad` for the free version). GZDoom is not a vanilla engine since it actually add enhancements to the games and it is able to overpass the original limitations, so it doesn't require these versions.	All the following combinations of wads are supported: 1. Purchased Sigil: SIGIL.wad SIGIL_SHREDS.wad 2. Purchased Compatible Sigil: SIGIL_COMPAT.wad SIGIL_SHREDS_COMPAT.wad 3. Free Sigil: SIGIL.wad 4. Free Compatible Sigil SIGIL_COMPAT.wad
   Mod for Doom 1 - Tech Gone Bad (John Romero) [E1M8]	e1m8b.wad
   Mod for Doom 1 - Phobos Mission Control (John Romero) [E1M4]]	e1m4b.wad
   Mod for Doom 1 - The Lost Episode (5th Episode) [E5M1 to E5M9]	lostepis.wad
   Mod for Doom 2 - Betray (Xbox Level) [MAP01]	BETRAY.WAD
   Mod for Doom 2 - No Rest for the Living (XBLA 2nd Episode) [LEVEL01 to LEVEL09]	NERVE.WAD

   This is how the folder should look like with ALL the wads:

   And the master_levels folder:

   5. You are ready to go to the Doom folder to select and start the scripts that correspond to the games you copied from the previous step.

   5. Details of preconfigured settings

   5.1. Game Settings

   • Always Run is enabled
   • Automap → Map Color Set is set to Traditional Doom
   • Automap → Rotate Automap is enabled
   • Automap → Enable Textured Display is enabled
   • Automap → Show Item Counts is enabled
   • Automap → Show Monster Counts is enabled
   • Automap → Show Secrets Counts is enabled
   • Screen Size is set to max (Ctrl - or Ctrl + on keyboard can change this)
   • Display Resolution is set to 1920x1080p and full screen

   5.2. Controller Settings

   Joystick usage is enabled for DirectInput, XInput and Raw-PlayStation-2-Adapter controllers. The property used was use_joystick=true. This will enable the already mentioned Input controllers and loads the default settings for XInputs, in this case joysticks and triggers moves and their deadzones.

   5.3. Preconfigured controller bindings for XInput devices (Xbox 360 or Xbox One controllers)

   START button on controller brings the Main Menu (the same menu displayed using ESC key on keyboard). This binding for some reason is not visible at all on the Customize Controls menu, so it needed to be written on the properties file directly. The property used was joy8=menu_main. To exit the Main Menu press B button.

   Right Trigger is bind to Attack/Fire, it can be set on Customize Controls menu, but the key name is not displayed on the list of keys. It should be displayed as axis5minus. The property used was axis5minus=+attack.

   5.3.1. Xbox 360 and Xbox One key bindings

   Menu Bindings

   START/MENU Button → Main Menu

   Left Stick (LS) and Directional Pad (D-Pad)

   [LS / D-Pad] Up → Move Up
   [LS / D-Pad] Down → Move Down
   [LS / D-Pad] Left → Move Left
   [LS / D-Pad] Right → Move Right

   Buttons (A, B, X, Y)

   A → Select or Enter
   B → Go Back or Cancel
   X → Delete

   In-Game Bindings

   Left Stick (LS)

   LS Up → Move Forward
   LS Down → Move Backguards
   LS Left → Left Strafing
   LS Right → Right Strafing
   LS Button → Turn 180

   Right Stick (RS)

   RS Up → Look Up
   RS Down → Look Down
   RS Left → Look Left
   RS Right → Look Right
   RS Button → Center Look

   Buttons (A, B, X, Y)

   A Button → Use
   B Button → Crouch
   X Button → (Unbinded)
   Y Button → Jump

   Bumpers and Triggers

   LB (Left Bumper) → Previous Weapon
   LT (Left Trigger) → (Unbinded)
   RB (Right Bumper) → Next Weapon
   RT (Right Trigger) → Fire/Attack

   Directional Pad (D-Pad)

   D-Pad Up → Display Map
   D-Pad Down → (Unbinded)
   D-Pad Left → Previous Weapon
   D-Pad Right → Next Weapon

   Back, Start, Guide (Xbox 360) and View, Menu Xbox (Xbox One) buttons

   BACK / VIEW → Take Screenshots
   START / MENU → Main Menu
   GUIDE / XBOX → (Unbinded: Cannot be binded)

   6. Advanced Configuration (optional)

   In this section we are going to explain how you can customize DoomBroLauncher based on your needs.

   6.1. Create more batch-scripts to run new Doom games or mods

   DoomBroLauncher provides batch-scripts to run some Doom games, but not all of them, we try to cover the official id Software releases for now.

   We know that everyday a new Doom mod is released, so we wanted DoomBroLauncher to be open to customization to anyone that wants to run a mod that is not covered with the initial batch-scripts, so here are the steps to create a new batch-script for new mods.

   6.1.1. Create an script for an IWAD (complete games)

   As example, we are going to add an script for The Ultimate Doom:

   1. Copy your IWAD file into Doom/.DoomBroLauncher/wads folder, for example DOOMU.WAD

   2. Navigate to Doom/.DoomBroLauncher/config folder

   3. Copy the file called IWAD-Template.bat and paste it in Doom folder.
      The template file looks like this:

   4. Rename the bat file using a descriptive name, for example Doom 1 (The Ultimate Doom).bat, do not remove its .bat extension

   5. Open the bat file with any text editor

   6. Check its last line and notice the name YOUR-IWAD.WAD, you need to replace that with the actual name of your IWAD, for example DOOMU.WAD

   7. Save the bat file and you are ready to run your game

   The final result should look like this:

   6.1.2. Create an script for a PWAD (a mod for a game)

   As example, we are going to add an script for The Lost Episode:

   1. Copy your PWAD file into Doom/.DoomBroLauncher/wads folder, for example lostepis.wad

   2. Navigate to Doom/.DoomBroLauncher/config folder

   3. Copy the file called PWAD-Template.bat and paste it in Doom folder.
      The template file looks like this:

   4. Rename the bat file using a descriptive name, for example The Lost Episode (Evil Unleashed).bat, do not remove its .bat extension

   5. Open the bat file with any text editor

   6. Check its last line and notice the name YOUR-IWAD.WAD, you need to replace that with the actual name of the IWAD needed by the mod, in this case DOOMU.WAD and the name YOUR-PWAD.WAD needs to be replaced by the name of the mod, in this case lostepis.wad

   7. Use the -warp or +map parameters to start the game on the specific episode and map (or just map, or just level, depending of the wad format) where the mod starts

   8. Save the bat file and you are ready to run your game

   The final result should look like this:

   6.2. Changing the Game Skill (difficulty)

   By default, all levels are loaded with the normal skill, but you can change this value.
   Go to Doom/.DoomBroLauncher/config and open the port-parameters.bat file, find the line SET SKILL_DEFAULT=-skill 2 and change the number value with another value from 0 to 4. Check this documentation to know more about these values. Please notice that you need to investigate if the skill you want is supported by the game first.

   6.3. Integration with EmulationStation

   First, you should be familiar with EmulationStation configuration, for more details about it, check http://emulationstation.org/gettingstarted.html#config.

   For this guide, I'm going to use my personal Windows HTPC configuration with its original paths, you don't need to use the same paths or names, they are used here as an example.

   The first thing to do, is to define a path where the Doom games are going be stored, for this case I'm going to use the same path I used before to install DoomBroLauncher: C:\Users\diego\Games\Doom as the full path, or %HOMEPATH%\Games\Doom with Windows variables, but EmulationStation will understand it as ~/Games/Doom, so we should use this last one in order to be more portable.

   Now, you need to add the PC system on your EmulationStation settings file, for that go to your home folder, look for the EmulationStation folder (%HOMEPATH%\.emulationstation for Windows), open the file called es_systems.cfg and add the following code at the end of the file, but before the closure of the </systemList> element:

   <system>
     <name>pc</name>
     <fullname>PC</fullname>
     <path>~/Games/Doom</path>
     <extension>.bat</extension>
     <command>%ROM%</command>
     <platform>pc</platform>
     <theme>pc</theme>
   </system>

   This code basically tells EmulationStation to go to the path, scan and display the .bat files, and when you select one, it would be executed as a command.

   I like to use the pc theme for these games, but you can also use ports as well.

   Most of the times, command is used to call RetroArch or other emulators, but in this case we are delegating this logic to the DoomBroLauncher scripts, because we just want our scripts to be executed, without parameters.

   At this point you are able to play your Doom games, but there is one detail that EmulationStation can't handle, and it is the scrape of images and metadata for each game in our specific case. The checksum of the roms (in this case the .bat files) will not help to find the game on the DB, and actually the DB doesn't have good information about these games, at least for their PC version, and dates are wrong. So as part of DoomBroLauncher we provide the metadata and pictures needed to display your Doom games the best way possible.

   To update the images and metadata, follow these steps:

   1. Go to %HOMEPATH%\.emulationstation\gamelists\pc path (create it if it doesn't exist)

   2. Download the latest EmulationStation-Metadata.zip from https://github.com/BrosMakingSoftware/DoomBroLauncher/releases. Extract the gamelist.xml file and copy it on the path of the previous step, but if you already have a file like this with other games, you should open your existing file and append the contents of all game XML elements from gamelist.xml.

   3. From the EmulationStation-Metadata.zip file, extract all the images inside the boxart folder.

   4. Go to %HOMEPATH%\.emulationstation\downloaded_images\pc path (create it if it doesn't exist), and copy all the extracted images.

   And everything is done!

   Next time you start EmulationStation, you will see the Doom games listed with metadata and box arts. Here are some examples about how some of them look like on EmulationStation with the eudora theme:

   This is a retouched box art used as image for The Ultimate Doom:

   This is a screenshot of John Romero's "Tech Gone Bad" level with a Doom logo:

   This is a screenshot of the first "No Rest for the Living" level with a Doom II logo:

   This is a screenshot of "The Black Tower" level with the "Master Levels for Doom II" logo:

   Starting with DoomBroLauncher v1.2, John Romero's SIGIL episode is supported:

   Note: There is a bug on EmulationStation when it tries to display the metadata for folders, in this case Master Levels for Doom II, Alphabetical Order and PSN Release Order. Instead of displaying the correct metadata, EmulationStation displays some of the metadata of the previous game selected.