Thursday, 15 January 2015

Run DOS games in Retropie

In this tutorial, I will show how to add DOS games to Retropie. The games will launch automatically from emulationstation, then return when the game is exited. I will be using DOSBox as the emulator. rpix86 may be faster but DOSBox supports mapping game controllers, something I will cover in a future tutorial.

[Edit: If you are using RetroPie 3.0, then you can jump to the Add DOS Games section]

Update DOSBox binaries

First make sure your binaries are up to date as a faster version of DOSBox was compiled recently (January 2015) and included in Retropie. You can get more information, including how to compile from source, at the Raspberry Pi forum.

To update the binaries, you need to run the following commands in a terminal:

cd RetroPie-Setup
sudo ./

Choose option 6 UPDATE RetroPie Binaries. While here, it will be a good idea to update the RetroPie Setup script (option 5).

Add DOSBox to Emulationstation

DOSBox was not configured in my es_system.cfg file so didn't appear in emulationstation. I created an entry by running the following commands.

cd RetroPie-Setup
sudo ./ dosbox configure

(If the above script does not work, then update the RetroPie Setup script as described above.)

This generated the following entry for DOSBox in the default es_systems.cfg file in the /etc/emulationstation folder.

    <fullname>PC (x86)</fullname>
    <command>/opt/retropie/supplementary/runcommand/ 0 "%ROM%" "dosbox"</command>

ES on my Retropie build uses the customised es_systems.cfg in the /home/pi/.emulationstation folder so I copied and pasted the above lines into that file.


Add DOS Games to RetroPie

The <path> tag in the DOSBox entry in es_systems.cfg says that roms need to put in the ~/RetroPie/roms/pc folder.

The game I will show how to add to Retropie is the shareware version of Wolfenstein 3D from the DOS Games Archive.  At the terminal, type the following command to create a folder in our roms folders.

 mkdir ~/RetroPie/roms/pc/wolf3d

Change the working directory to wolf3d.

cd ~/RetroPie/roms/pc/wolf3d

Download and unzip the game from Dos Games Archive.


Check the contents of the zip file with the ls command to find a file called install.exe. Games in DOS generally needed to be installed first to extract the game data. They can be identified with file names such install.exe or setup.exe. You can refer to the DOSBox game wiki to check whether there is an installer file as well as finding what the executable is (see below).

Wolfenstein 3D shareware can only be installed in DOSBox so launch DOSBox by using the +Start DOSBox script from EmulationStation with the following commands from the terminal. This is the only occasion when you need to use the DOSBox interface.

cd /opt/retropie/emulators/dosbox/bin

DOS is a command line interface (CLI) like the terminal in Raspbian. To do this, type the following commands at the DOS prompt. An explanation of what these commands do is given below.

mount c /home/pi/RetroPie/roms/pc/wolf3d

Once the installation process begins, change the target directory from C:\WOLF3D to C:\ and press enter. Press C on your keyboard to complete the install. This will take a few minutes.

Run DOS Games in RetroPie

Like Raspbian, DOS games are launched by typing the name of the executable file which normally has an .EXE extension.

Type the command DIR at the DOS prompt in DOSBox to see that the executable we are looking for is WOLF3D.EXE. Type EXIT at the DOS prompt to exit DOSBox and return to the terminal on the pi.

Back to the DOSBox entry in es_systems.cfg, the <extension> tag says that ES will look for shell scripts (.sh) to launch games. Using shell scripts is a good way to auto launch a game without having to type commands at DOS prompt every time, useful if you are using only a game controller as input.

To create the shell script to launch Wolfenstein 3D, run the following commands.

cd ~/RetroPie/roms/pc
sudo nano

Copy and paste the code below.

/opt/retropie/emulators/dosbox/bin/dosbox -c "mount c /home/pi/RetroPie/roms/pc" -c "c:" -c "cd WOLF3D" -c "WOLF3D.EXE" -c "exit"

Save and exit. Next make the executable so it can be launched from emulationstation.

sudo chmod +x

Start up emulationstation and wolf3d will appear in the IBM emulator. If the game runs slowly, then overclock your pi to turbo.

Add More DOS Games

A quick explanation of the contents of the shell script so that you can amend it when you add more games.

/opt/retropie/emulators/dosbox/bin/dosbox launches the SVN version of DOSBox

The -c parameter in DOSBox runs the commands that would normally be typed at the DOS prompt.

-c "mount c /home/pi/RetroPie/roms/pc" maps roms folder to virtual C drive in DOSBox
-c "c:" changes the working directory in DOSBox to C:\ (the roms folder)
-c "cd WOLF3D" changes the working directory to C:\WOLF3D, the game data folder
-c "WOLF3D.EXE" runs the executable to start the game
-c “exit” exits DOSBox and returns to ES when game is closed

If you are adding more games, change the name of the folder containing game data and the name of the executable, the parts of the shell script in bold.