Configure Game Controllers in DOSBox

In this tutorial, I will show how to use the DOSBox mapper to configure game controllers.

The DOSBox mapper (above) is the tool that allows you to remap the keyboard commands to a game controller.  You can read the DOSBox mapper wiki here.

To launch the mapper in DOSBox in Retropie, run the following commands in a terminal. (Run the second command only if not using Retropie.)

cd /opt/retropie/emulators/dosbox/bin

dosbox -startmapper

I have found that the mapper tool only seems to work on the pi in the LXDE desktop environment. If you launch the mapper from the console (using the commands above) or by pressing CTRL+F1 if you launched a game in DOSBox from Emulationstation (Retropie), then on exiting the mapper, you're likely to be met with no video output (a black screen) and a need to reboot. In addition, the outline of virtual keyboard and the mouse cursor is dark blue which contrasts poorly with the black background.

You can launch LXDE from the console with the command

startx

Start a LXterminal session and run the commands above to launch the mapper.

Alternatively, you can install DOSBox on your desktop and then, once you've created the mapper file, copy it from your desktop to your pi (see below for details).

Mapping Game Controller for Wolfenstein 3D

Following the tutorial on running DOS games in Retropie, we will continue to use the shareware version of Wolfenstein 3D as our example.

The keyboard controls can be found in the manual for Wolfenstein 3D. This is the mapping I decided to use with my PS3 controller.

Action	Key Command	PS3 Controller
Movement	Arrow Keys	Left analogue stick
Strafe (with left stick)	Alt	L1 (button 10)
Run/Fast Turn (with left stick)	R Shift	R1 (button 11)
Fire weapon	Ctrl	R2 (button 9)
Knife	1	D-pad Up (button 4)
Pistol	2	D-pad Right (button 5)
Machine Gun	3	D-pad Down (button 6)
Chain Gun	4	D-pad Left (button 7)
Open doors	Space bar	X button (button 14)
Options Menu (in game)	ESC	START (button 0)
End Game	F7	Triangle (button 12)
Quit Wolf3D	F10	SELECT (button 3)
Yes (to exit game)	Y	X button (button 14)

(If you need to find the buttons assignments for your controller, then you need to install the joystick app.)

You may have noticed that I have mapped the space bar and the Y key to the X button on my controller. DOSBox allows you to map multiple keys to one button on your game controller. This is useful if you wish to use one button in the menus and in-game even though you would use different keys on the keyboard.

In fact, a keyboard key can be mapped to multiple buttons. For example, I could have mapped the movement arrow keys to the corresponding buttons on the D-pad. This would not be a good idea here because there would be a conflict between movement and choosing weapon. Moving forward would arm me each time with a knife!

Once you have decided your mapping, plug in your game controller into your pi or desktop and launch the mapper with commands above. To map each key, do the following steps:

1. Select the key on the virtual keyboard.
2. Press Add
3. Press the button on your joystick.
4. Press Save
5. Repeat for each key until you have completed your mappings.
6. Press Exit to exit the mapper.

The video below shows the mappings being made for forward and backward movement, strafe, run and fire weapon actions.

Note, when you exit the mapper, DOSBox will start. Type EXIT at the prompt to return to the desktop.

Tip: If, at any time, you mess up, you can exit the mapper and delete the mapper file, mapper-SVN.map, which is located on the pi in the ~/.dosbox folder (for desktop locations, see below). DOSBox will generate a new default mapper file each time the mapper is launched if there is no mapper file present. You can now restart the DOSBox mapper and begin the mapping process again.

Now you can start Wolfenstein 3D to test that your mappings work.

Copy Mapper File from Desktop to the Pi

If you created the mapper file on your desktop, then, according to the DOSBox documentation, you can find the mapper file in same location as the DOSBox config file which are as follows:

Win7/8 :   {system drive}:\Users\{username}\AppData\Local\DOSBox\

Linux:     ~/.dosbox

Mac:      ~/Library/Preferences/DOSBox 0.73 Preferences

Rename the mapper file on your desktop from mapper-0.74.map to mapper-SVN.map and copy it to the ~./dosbox folder on pi.

If you did not have any joy, then you can download a working mapper file here.