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
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~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"&lt;/code&gt;
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
8 thoughts on “RetroPie: DOSBox Setup Guide”
Thank you! This is EXACTLY what I was looking for, in an easy to understand and follow format.
Glad to hear it helps.
I have a couple of recommendations after setting this up on my Raspberry Pi.
Set `aspect = true` in your `dosbox-SVN.conf` file so that it keeps the gameâ€™s aspect ratio correct, but stretches it to fit your screen, unless you want to have black borders around the game or have it look funky.
Good addition. Thank mate. Cheers
Attempting to setup this up on my RetroPie and am running into issues. I have over a thousand DOS games to do though I am focusing on just one for now. I am using DOSBox as compiled by EmulationStation/RetroPie.
The issue I am having is that after the script launches DOSBox, it fails to mount the drive and all subsequent commands give very similar errors.
Shell File Name: Blake Stone â€“ Aliens of Gold.sh
Shell File Location: ~/RetroPie/roms/pc/
/opt/retropie/emulators/dosbox/bin/dosbox -c â€œmount c ~/RetroPie/roms/pc/DOSâ€ -c â€œc:â€ -c â€œcd BStoneâ€ -c â€œcall BSTONE.BATâ€ -c â€œexitâ€
On the mount command, I get a few funky characters followed by mount and then an error. I also receive the same few funky characters followed by the first word of the command at each occurence of -c. After which I am presented with DOSBoxâ€™s default command line: Z:>.
I have verified the the mount path is correct as are the director and file names, accounting for case sensitivities. Also, the individual commands function properly when entered manually from within DOSBox without the -c.
Manual command chain: (Keeping in mind that once in the C drive, DOSBox is not case sensitive.)
mount c ~/RetroPie/roms/pc/DOS
The game loads just fine. There just seems to be an issue with the script. Am I overlooking something?
So I’ve done some experimenting with the commands contained in the script and managed to get it to work. Blake Stone: Aliens of Gold now launches when selected from within EmulationStation/RetroPie.
Seams the issue is that the shell file has to be created from within terminal on the RasPi and not within a windows environment. Not sure what the difference is other than conflicting OS languages and how Windows saves the file vs how Linux saves the identical file.
Interesting. Maybe it’s the editor and not the os?
Was using ms word but thought that might be the issue so I switched to notepad++