Let's take a simple example with the Alley Cat game:
AlleyCat.pc. The first part of the directory name before the '.' must be at most 8 characters long and must not contain any special characters;
AlleyCat.pc, create a
dosbox.batfile and modify it to call the game executable.
This gives us:
/recalbox/share/roms/dos/AlleyCat.pc). The same goes for '.
CTRL + F9on your keyboard.
dosbox.cfg' file to your game directory at the same level as dosbox.bat' allows you to define a specific DOS configuration for that game.
You can either copy the
dosbox.conf file from
recalbox\share\system\configs\dosbox\dosbox.conf or use this.
The extension in the game directory must be
In this file, the line
mapperfile=mapper.map allows you to use a
mapper.map file to map any keyboard key or even the mouse to your controller. This file can be created from within your game by pressing
CTRL + F1 at any time and will then be saved alongside your
Some of the parameters in the
dosbox.cfg file can also be put at the beginning of your
dosbox.bat file if you don't want to use a specific
dosbox.cfg file, but some of these parameters won't work in the
dosbox.bat; everything graphical seems to work, but the
mapperfile parameter doesn't work for example.
How to convert a game to use it on Recalbox ?
First of all, copy the content of the game directory (rename it correctly with .pc).
Then we have to adapt the content of the
dosbox.cfg and the bat file used to launch the game.
Example with the game Wacky Wheels:
Do not copy the
dosbox.cfg (or .conf) directly from the original directory as this can lead to bugs that are difficult to find. Instead, copy the standard file linked above, then check if the
dosbox.cfg had a special configuration and if so, use it in your
dosbox.cfg. This is in the
[autoexec] part of the file.
First move the contents of this part to the beginning of your
dosbox.bat file and adapt the paths. Here we have :
[autoexec] cd .. cd .. mount c .\games\WackyWhe imgmount d .\games\WackyWhe\cd\wackywheels.iso -t cdrom c: cd wacky cls @ww exit
and this will give us once converted to Recalbox:
imgmount d .\cd\wackyw~1.iso -t cdrom c: cd WACKY pause WW.EXE
imgmountis simplified and we have to convert the iso name to a standard DOS name (8 characters maximum with the last two changed to ~1, ~2, ~3 etc. if the path is longer and if you have several files with the same name). In this case it is better to change the file name to something simple anyway;
.cuefiles either, so you may have to rename the
.binfiles manually and edit the
.cuefile to reference the new
.binfile name. And DOSBox can be rather strict: no special characters, and sometimes no capital letters.
imgmountcommand works (don't use pause after calling the game executable or you won't see anything)
WW.EXE(this is just the call to the game executable).
And that's it! Some games may also use a
.bat launcher, copy its instructions to the end of your
dosbox.bat after the
[autoexec] part of
dosbox.cfg and adapt them.
This wiki aims to allow you to play DOS games via the DOSBox emulator made available by RecalBox.
You have to know that there is a multitude of possible contexts, each game has its specificity.
This is why it is impossible, at the moment, to have something "Plug&Play" on the DOS emulation.
However, in general terms and for the majority of games, it's more or less the same thing.
We will see 3 cases here: 1. the game requiring neither installation nor CD support; 2. the game requiring an installation, but no CD support; 3. the game requiring an installation and a CD support.
But before that, some generalities about the functioning of the DOSBox emulator made available by Recalbox.
**The different cases of figure **
We will explain below the different scenarios. Do not read only the case that interests you, but the whole: some points acquired in the first cases will not be repeated in the following ones.
The game does not require installation or CD support:
The simplest of all cases: you have a disk version of the game, which does not have an "install.bat" (or ".exe") file or which, failing that, does not require installation (the "install.bat" file is sometimes also used to configure the game, especially the sound).
Ideally, you have two key files in the game directory (either ".bat" or ".exe"): "setup" (sometimes the "install" file is used as "setup") and another one with either the name of the game (for example "wolf3d" for "Wolfenstein 3D" or "s2" for "settlers2" or simply "go" meaning "launch")
So create the file "dosbox.bat" if you haven't already done so, then edit it so that it contains the following lines:
pause instruction will allow us to ask DOSBox to wait before "closing its session" and thus to return to EmulationStation.
This will allow us to read the possible errors returned by the execution of such or such command.
Once the "dosbox.bat" file is edited and saved, return to EmulationStation, update the game list (if it hasn't already been done once since the dosbox.bat file was created), and start the game!
You arrive in the game configuration program. This one is especially interesting to configure the sound.
Each "setup" is different but in general you are offered a menu in English with "setup sound...".
You have to select (for the "midi" AND for the "sound effect" if the difference is made) the "Sound Blaster 100% compatible" input and the automatic setting (or failing that, all the default choices that you will be offered).
Sometimes, a test is proposed to you which will allow you to see that everything is OK.
Once this is done, you can quit the setup (there is an entry in the setup for this purpose, remember to save the changes if you are asked).
You will then get a "prompt" asking you to press a key to skip the pause instruction: execute it after having noticed a possible error message.
After returning to the EmulationStation interface, edit the "dosbox.bat" file as follows (here we take the example of the executable file mentioned above "s2.bat" for "Settlers 2", replace "s2" by the name of the ".bat" or ".exe" file corresponding to the game being processed):
Saved, then launched the game again. And normally everything works
If it's not the case, expose your problem on the forum or Discord, by specifying the error messages eventually caught.
The principle is the same as in the previous case, but with the installation step in addition.
If you were not satisfied with the previous case, it is probably because the game needs to be installed.
In order to avoid any file confusion, I advise you to create a "source" subdirectory in the ".pc" type directory and to place the game files/folders in it.
Make sure you have an "install" file (either ".bat" or ".exe" - sometimes the "setup" file also offers the installation option).
Then create/edit the "dosbox.bat" file as follows:
cd source install pause
Launch the game again from EmulationStation, this execution leads you to the installation program.
Sometimes similar to the presentation of the classic "setup", it has an additional option offering installation.
Just like the "setup", there is nothing universal or standard, so you have to adapt.
But the titles, although often in English, are generally clear.
During the installation process, you will be asked for a path.
Make sure it is filled in as follows:
The name "target" is an example (it must echo the name "source" previously used), you can replace it by what you wish, but in this documentation we will start on the principle that it is called "target".
Once the installation is finished, proceed to the sound configuration if it is proposed to you. Then, quit the installation program.
You arrive on the prompt caused by "pause", again this allows you to note any errors returned.
Press any key to return to EmulationStation.
Then, the process is similar to the previous one, except that you need to add access to the "target" directory as well.
So to configure the sound, if it hasn't already been done and with the example of a file named "setup", your "dosbox.bat" file should look like this:
cd target setup pause
Launch the input again, and proceed as described in the previous case.
Then, once all installation/configuration is OK, you can proceed to launch the game itself.
Your "dosbox.bat" file should then contain the following lines:
cd target s2 pause
And, normally, the trick is done .
The "source" directory is sometimes not useful anymore after installation, this kind of installation being made at the time to simply copy the content of the floppy disk to the hard disk to do without the removable media. To be tested.
This last case has many points in common with the previous one, with two major differences:
So, first of all, we will create a "source_cd" directory at the root of our ".pc" directory. This directory will receive the CD image files (bin, cue, iso, img, ...).
Compared to the previous case (a game on CD media still requires an installation), the major difference is the mounting of the CD image on a virtual CD drive. The command line used for this will vary slightly depending on the format of the CD image. Some examples (in the back, names longer than 6 or 7 characters - I have a doubt - are truncated with "~x"):
imgmount D "C:\source~1\settle~1.cue" -t iso -fs iso
imgmount D "C:\source~1\settle~1.iso" -t iso -fs iso
imgmount D "C:\source~1\settle~1.img"
mount D "C:\source~1"
Some game CDs are "mixed" CDs. This means that they contain the game data as well as the audio tracks that will be used to play the music in the game.
It is important for these CDs that the image is contained in a single .img or .bin file because DOSBOX does not support CD images split into several .bin files.
In this case, the editing must be done via the corresponding .cue file so that all the audio tracks are correctly loaded.
With the exception of this mount line, the rest is almost identical to the previous case.
You just have to add the line "mount ..." at the beginning of the file "dosbox.bat" in a systematic way then proceed to the installation, the configuration, then the launching of the game.
Be careful also to move to the right directory (command "cd") : thus you have to do
cd source_cd for the installation, then
cd target to access the game directory (as in the previous case).
Once a game is running, you can remove the "pause" instruction to avoid the timeout prompt each time the game is exited.
By default, the virtual keyboard is opened with Ctrl-F2.
But a new button is available in the mapper (Ctrl-F1 > Virt Keyb) to associate it with another event (keyboard, mouse or joystick).
Once opened, use the mouse or joystick to select and operate the keys:
Click again with any mouse or joystick button to release it.
This allows combinations with Shift, Ctrl or Alt.
Finally, press the green V button to close the virtual keyboard and send the events to DOSBox. It is also possible to press the red cross to cancel the events and close the virtual keyboard.
- If you are using an existing mapping file, the default Ctrl-F2 combination will not be configured.
- If you quit the virtual keyboard with a keystroke, this event will be constantly sent to DOSBox, until you open the virtual keyboard again!
- All the configured mappings of the joystick or the mouse will be ignored as long as the virtual keyboard is open
The image is distorted: For some older games, you may have to change the
aspect=false parameter to
aspect=true to get a 4/3 ratio image. Be careful on newer games, this could lead to a performance problem;
The joystick moves by itself: Try changing
timed=true. This may be due to the deadzone of the joysticks as well and unfortunately there is no way to configure this in DOSBox at the moment;
You can't map the D-pad of an xbox360 controller : Yes, the DOSBox mapper allows you to configure the D-PAD but it doesn't work in game, maybe you can try to change the joystick type;
How to configure the deadzone of a joystick : Unfortunately, this is not possible in DOSBox for the moment;
CD Not Found / CD Driver not present : You have problems renaming your cd files (io, cue, bin, cue edition) or using names that do not respect the DOS standard (see adv. rundown) ;
**I can't get
mount to or
mount from to work: Unlike
mount command cannot use 'virtual' paths from inside the DOSBox machine. For
mount to work, you can only use real paths local to the Recalbox file system. As '.' is set to the root / directory when DOSBox is launched, it is mandatory to use the full absolute path to the file or directory;
The mapper is buggy, it deletes my file or mixes my buttons : You are probably victim of the
buttonwrap parameter. When this is set to
true, it sets the buttons on your pad to an ID greater than the number of buttons on the emulated joystick, starting from scratch (5 will be remapped to 0, 6 to 1, etc.). Set this parameter to
false and everything should be fine.