This page covers the standalone DOSBox emulator, the one that works with .pc folders. If your games are .zip archives you launch directly, you are using DOSBox Pure instead and none of this applies — see the DOS guide.
DOS emulation is not plug-and-play: every game has its quirks. But the broad approach is always the same — and once a game is set up, you never touch it again.
/recalbox/share/roms/dos, extracted: they are folders, not archives..pc — that is how EmulationStation spots it as a game. The part before the dot must be 8 characters at most, with no spaces, accents or special characters.C: at launch. As far as DOSBox is concerned, nothing else exists.dosbox.bat file holds the DOS commands to run. Any plain text editor will do..bat ones first, then the .exe ones.CTRL + F9.After each change to dosbox.bat, refresh your games list if the game is not visible yet, then launch it again.
The simplest case. Take Alley Cat:
AlleyCat.pc in /recalbox/share/roms/dos.dosbox.bat file inside, containing:c:
CAT.EXE
If the game has a setup or install file used to configure sound, run that first. Temporarily write:
setup
pause
The pause instruction freezes the screen before returning to EmulationStation: that is your only chance to read error messages. In the configuration program, pick Sound Blaster 100% compatible for both music and effects, with automatic settings. Then replace setup with the game executable.
Create a source subfolder inside your .pc folder and put the original game files there, to avoid any confusion. Then:
cd source
install
pause
During installation, the program will ask for a destination path: enter c:\target (the name is up to you). Once installation and sound configuration are done, your final dosbox.bat becomes:
cd target
s2
pause
(replacing s2 with your game's executable.)
The
sourcefolder is often useless after installation — that kind of installer merely copied the floppies onto the hard disk. Test before deleting it.
Two differences from the previous case: the CD image must be mounted on a virtual drive, and usually kept mounted while playing (cutscenes, music).
Create a source_cd folder at the root of your .pc folder and put the CD image there. Then add the mount line at the very beginning of dosbox.bat, depending on the format:
| Format | Command |
|---|---|
| BIN/CUE | imgmount D "C:\source~1\settle~1.cue" -t iso -fs iso |
| ISO | imgmount D "C:\source~1\settle~1.iso" -t iso -fs iso |
| IMG | imgmount D "C:\source~1\settle~1.img" |
| Plain files | mount D "C:\source~1" |
The rest matches case 2: cd source_cd for the installation, then cd target to launch.
Filenames must follow the DOS convention: 8 characters at most, longer names being truncated with
~1,~2… The simplest approach is to rename your files with short names.
For mixed-mode CDs (data plus audio tracks), the image must fit in a single
.imgor.binfile: DOSBox does not handle images split across several.binfiles. Mounting must then go through the.cuefile so the audio tracks are loaded.
dosbox.cfg filePlaced next to dosbox.bat, a dosbox.cfg file lets you define a DOS configuration specific to that game. Start from the reference file at /recalbox/share/system/configs/dosbox/dosbox.conf.
In the game folder the extension must be
.cfg, not.conf.
The mapperfile=mapper.map line lets you map any keyboard key — or the mouse — to a controller button. The mapper.map file is generated in-game with CTRL + F1, and saved next to your dosbox.bat and dosbox.cfg.
Some dosbox.cfg settings can also be placed at the top of dosbox.bat. Everything display-related works; mapperfile, however, only works in the .cfg.
If you get hold of a game already prepared for DOSBox on a PC, do not copy its dosbox.cfg as-is: it causes bugs that are painful to diagnose. Start again from Recalbox's reference file, and salvage only what matters: the [autoexec] section of the original file.
Take Wacky Wheels. The original [autoexec]:
[autoexec]
cd ..
cd ..
mount c .\games\WackyWhe
imgmount d .\games\WackyWhe\cd\wackywheels.iso -t cdrom
c:
cd wacky
cls
@ww
exit
becomes, in your dosbox.bat:
imgmount d .\cd\wackyw~1.iso -t cdrom
c:
cd WACKY
pause
WW.EXE
What changed and why:
mount c is gone — C: is already mounted on the game folder;exit is gone — quitting is handled by Recalbox;imgmount path is shortened to the DOS format (wackyw~1.iso); renaming the file is better still;pause is added temporarily to check that the mount worked — remove it afterwards (never put it after the game call, or you will see nothing);@ww becomes WW.EXE, the executable call.If the game uses a .bat launcher, copy its instructions afterwards and adapt them the same way.
Long names are not accepted inside
.cuefiles either: you may have to rename the.binfiles and fix the reference in the.cue.
The virtual keyboard opens with CTRL + F2 by default. A dedicated button is also available in the mapper (CTRL + F1 > Virt Keyb) so you can bind it to another key, to the mouse or to the joystick.
Once open, pick keys with the mouse or the joystick:
That is how you compose combinations with Shift, Ctrl or Alt. The green V button closes the keyboard and sends the events to DOSBox; the red cross cancels.
If you use an existing mapping file, the default
CTRL+F2combination will not be configured in it. And if you leave the virtual keyboard with a key held down, it will keep being sent to DOSBox until you reopen the keyboard. Finally, joystick and mouse mappings are ignored while the virtual keyboard is open.
The picture is distorted — change aspect=false to aspect=true in dosbox.cfg for a 4:3 image. Careful: on more recent games this can cost a lot of performance.
The joystick drifts — try timed=false → timed=true. It may also come from the joystick dead zone, which DOSBox unfortunately cannot adjust.
The mapper wipes my file or scrambles my buttons — that is the buttonwrap setting. At true, it reassigns buttons whose identifier exceeds the emulated joystick's button count, wrapping back to zero. Set it to false.
CD Not Found / CD Driver not present — your CD files are badly named (or the .cue badly edited), or the names do not follow the DOS convention.
mount a or mount d does not work — unlike imgmount, the mount command does not understand paths internal to the DOSBox machine. It requires a real absolute path on the Recalbox filesystem.
The D-pad of an Xbox controller cannot be mapped — the DOSBox mapper lets you configure it, but it does not work in-game. Try changing the joystick type.
If you are still stuck, describe your problem on the Recalbox Discord, quoting the error messages you saw.