Friday, 6 February 2015

Default (Arcade) Mapping for DOSBox

Over the next two tutorials, I will show how I have used DOSBox config and mapper files for games in my Retropie build. In the first tutorial, I will share my default configuration that I use for most games which I would describe as arcade-style. In the second tutorial, I will share the configuration for games that require more complex mapper files.

Gravis pc gamepad

Other than a 1 or 2 button joystick, many DOS games supported the Gravis PC GamePad (above). It resembled a SNES controller without the shoulder buttons with the added featured of being able to screw a joystick into the D-pad. In this tutorial, I will show how to create a mapper file for DOSBox that emulates the 4-button Gravis gamepad.

First make sure there is no mapper file already in ./dosbox folder by either deleting them or moving them to another location. If you followed the last tutorial on using the DOSBox mapper, then you may wish to move the mapper file you created to a safe location.

To create a default mapper file, plug in your game controller and then run the following command.

cd /opt/retropie/emulators/dosbox/bin
dosbox -startmapper

Exit the mapper (and DOSBox) and the mapper file,, will be created in the ~/.dosbox folder. When you open the mapper file in an editor, you can find the code that emulates the Gravis gamepad at lines 119 to 126 (which appear after the main keyboard section). The code generated for a PS3 controller is reproduced below:

jbutton_0_0 "stick_0 button 0"
jbutton_0_1 "stick_0 button 1"
jaxis_0_1- "stick_0 axis 1 0"
jaxis_0_1+ "stick_0 axis 1 1"
jaxis_0_0- "stick_0 axis 0 0"
jaxis_0_0+- "stick_0 axis 0 1"
jbutton_0_2 "stick_0 button 2"
jbutton_0_3 "stick_0 button 3"

The lines beginning jaxis_ maps movement to the left analogue stick on a PS3 controller. This will remain untouched.

jbutton_0_0 refers to the yellow button on the Gravis gamepad, jbutton_0_1 refers to the red button and so on. It is best to remap these manually. For example, to remap the yellow button to the corresponding X button on the PS3 controller, then the line would become

jbutton_0_0 "stick_0 button 16"
All that remains is to remap jbutton_0_1, jbutton_0_2 and jbutton_0_3 to the remaining buttons on the PS3 controller in a similar fashion.

To play most arcade-style games, this mapping will be enough as most games used 1 or 2 buttons. All that remains is to map keys to navigate game menus. The keys that are worthwhile to map include some or all of the following:

  • Arrow keys (lines 98 to 101 in the mapper file)
  • ESC (line 17) 
  • SPACE (line 86) 
  • Enter/Return (line 116)
  • CTRL (line 84)
  • ALT (line 85) 
  • SHIFT (line 71)

Other keys to consider are Y (line 50) and N (line 78), which are often used to confirm exit to DOS.

You can do this either by using the DOSBox mapper as demonstrated in the last tutorial or by editing the mapper file in a text editor. You can download my mapper file for the PS3 controller here. Please check the readme file that lists the mapping.

This mapping works well for platformers and driving games and has been tested successfully in the following games:
It will also work for shooters like Wolfenstein 3D. You can run, strafe. open doors and fire your weapon but you cannot select weapon so some actions will be omitted.

In the next tutorial, I will show how to configure games such as Wolfenstein 3D in DOSBox to make sure game-specific mapper files are used.