RetroPie: DOSBox Setup Guide

This is a guide is intended to show you how to seamlessly setup and integrate DOSBos into your RetroPie or EmulationStation setup to run those old school DOS games you remember from your childhood in the ’80s or 90’s! There were so many great DOS games from that ERA and using DOSBox in combination with SCUMMVM is a fantastic way to integrate them into a foolproof 10 foot user interface front and and experience these games all over again and from the comfort of your own couch! I still have so much fun with all these games! This RetroPie: DOSBox Setup Guide will take you step by step through setting up the directories, the scripts, the DOSBox config and the CDROMs to play these all over again.

This is part of my series of articles on Retro Gaming.

Install DOSBox on RetroPie

We can start this RetroPie: DOSBox Setup Guide once you have RetroPie or an installation of EmulationStation up and running. Once you do, the first step is to install DOSBox through the RetroPie Setup menus. In EmulationStation navigate to the RetroPie menu and the select “RetroPie Setup” to launch the setup program. In the setup program (as of version 4.4.1) navigate to “Manage Packages > Manage Optional Packages > dosbox > Install from Source”. This will take a few minutes to complete, so grab a beer sit back and relax!

[READ MORE ON DIGIMOOT: Diablo for Linux through Devilution]

Create Directory Structure and Copy Games

This setup uses two directories to store the necessary files for DOS games. The

\roms\pc

folder is where we will create and store the shell files (.sh extension) used to execute DOSBox and the parameter needed to be passed to DOSBox to launch the game. The \roms\pc folder will also contain the gamelist.xml file. You will also need to create a separate folder to locate the program files for each game. I have used \roms\pcdata for this location.

First, take all of your DOS games and copy them into the \roms\pcdata directory. Each game should have its own folder containing all of the program files – as shown in the first image below. If there are CD files (ISOs, BIN/CUEs, etc) they should be placed in this location as well. You can put them right in the game’s directory or create a separate CD or CDROM folder if you’d like. I’ve shown an example in the second image below.

As a note, and unlike how I have named my folders in the images above, you should consider naming your folders no longer than 8 characters. This is because back in the day, DOS only supported file and directory names with up to 8 characters. Longer names would get truncated to 8 characters. For example Commander Keen would get truncated to COMMAND~1. This has become a problem for me in that I have 6 Commander Keen games and 2 Command and Conquer games which get truncated to COMMAND~1 to COMMAND~8. This becomes a real problem because each time you copy the files to a new installation, the numbers 1-8 get assigned differently. I’m sure it is based on something like creation date but its a pain when it different each time, because you will need your scripts (see below) to refer to these specific directories. So long story short, try and not have folder names longer than 8 characters for your DOS games.

If you’re looking to jog your memory regarding all the great DOS games that were around, the image below is pretty darn cool! You’ll need to click on it and zoom in to read it. It has almost all of my favourite DOS games, although a couple are missing…

[READ MORE ON DIGIMOOT: Comic Book Theme: Modify to Create Your Own System Text]

Create RetroPie Scripts for Each DOSBox Game

Once you have all your games copied into the folder setup noted above, we will need to create a shell script (with a .sh file extension) which will launch DOSbox and run DOS commands within DOSBox to launch your game. These script files do not have to be 8 characters or less and they will be located in the \roms\pc directory in which EmulationStation will look for files with a .sh extension. I’ve included a sample of a script I have created below.

#!/bin/bash
/opt/retropie/emulators/dosbox/bin/dosbox -c "mount c ~/RetroPie/roms/pcdata" -c "c:" -c "cd comman~7" -c "keen4e.exe" -c "exit"

In this script you start with #!/bin/bash on the first line. This tells the script to run using the bash shell. The second line is the command that launches DOSBox in the /opt/retropie/emulators/dosbox/bin directory. If you have DOSBox installed in an alternate location you will need to update this section to refer to that location. After the DOSBox command there are a series of -c followed by a command in double quotations. The “-c” is a DOS command that is executed automatically in DOSBox. You can string several of these together and they are executed one after another within DOSBox. In this case, we mount the retropie machine directory of “~/RetroPie/roms/pcdata” as the c drive (c:) in the emulated DOS environment. We then navigate to the directory of the game we wish to launch and then run the game’s executable file. This is followed by an “exit” command which will close DOSBox and return you to EmulationStation once you’ve quit the game.

If the game is run via a batch file you will need to call the batch file by adding the command before the batch file name. If you do not do this, script will not exit DOSBox after the game has finished running and you will be left at the DOSBox command prompt. I’ve included an example of this below.

#!/bin/bash
/opt/retropie/emulators/dosbox/bin/dosbox -c "mount c ~/RetroPie/roms/pcdata" -c "c:" -c "cd x-comu~1" -c "call xcom.bat" -c "exit"

You will undoubtedly come across games which need to mount a CDROM in order to be played. You will need to mount the CDROM in much the same way you mount the C drive (c:) buy using this command to mount CDROM file as the D drive (d:): imgmount d CDFILENAME.EXT -t iso where CDFILENAME.EXT is the name of the CDROM image file to be mounted. CDROM image files typically are .iso or .bin files. I’ve included an example of a script mounting a CDROM image before launching the game.

#!/bin/bash
/opt/retropie/emulators/dosbox/bin/dosbox -c "mount c ~/RetroPie/roms/pcdata" -c "c:" -c "cd x-wing~1\cddrive" -c "imgmount d xwing.iso -t iso" -c "cd .." -c "call XWINGCD.BAT" -c "exit"

There are also situations where there a games with multiple CDs. You can use one command to mount all CDs as follows:

#!/bin/bash
/opt/retropie/emulators/dosbox/bin/dosbox -c "mount c ~/RetroPie/roms/pcdata" -c "c:" -c "cd wingco~5" -c "cd cddrive" -c "imgmount d wc3disk1.iso wc3disk2.iso wc3disk3.iso wc3disk4.iso -t iso" -c "d:" -c "wc3.exe" -c "exit"</code>

To swap CDs while running within DOSBox use “Ctlr-F4”.

Adding DOSBox Snaps, Boxart and Marquees to RetroPie

Like any other system, you can use the gamelist.xml file with the \roms\pc directory to add DOSBox snaps, DOSBox boxart and DosBox wheels (marquees). I’ve put together a guide on where to obtain boxart, snaps and wheels (although they’re much harder to find for old DOS games) and how to set them up to work with RetroPie and EmulationStation. You can find out how to do this in my RetroPie: Mass Renaming of ROMs and Media Files, Generate a gamelist.xml and Modify it to Include Snaps, Boxart and Wheels guide.

DOSBox Settings for Full Screen

If you’ve followed this guide all the way through so far, you will undoubtedly be annoyed by the fact that DOSBox is not running at full screen. In order to set it fullscreen you will need to update the dosbox-SVN.conf file. This file is located in the /home/[user]/.dosbox/ directory. Depending on what you are running RetroPie / EmulationStation on, you may need to tweak some of the settings.

Update the lines as follows and it should work well for fullscreen DosBOX on a PC running something like Ubuntu or Linux Mint. The important lines are: fullscreen, fullresolution and overlay.

fullscreen=true
fulldouble=false
fullresolution=desktop
windowsresolution=original
output=overlay
autolock=true
sensitivity=100

On a RetroPie setup on a Raspberry Pi, the following lines may work better better for you.

fullscreen=true
fulldouble=false
fullresolution=1024x768
windowsresolution=original
output=overlay
autolock=true
sensitivity=100

[READ MORE ON DIGIMOOT: RetroPie: Mass Renaming of ROMs and Media Files, Generate a gamelist.xml and Modify it to Include Snaps, Boxart and Wheels]

That’s it! You have made it through the RetroPie: DOSBox Setup Guide and everything should be up and running for you to enjoy some of the best games ever made!

Happy retro PC gaming

~digiMoot

Liked it? Take a second to support digiMoot on Patreon!