Wednesday, 12 August 2015

Mapping Keys to Game Controllers in ZEsarUX

In this tutorial, I will show you how to map keys to game controllers in ZEsarUX for keyboard only games and for games that use a Kempston joystick but reserve some actions to the keyboard.

ZEsarUX supports custom config files for every game you wish to include in your collection. From the emulator help on custom config files,

When you load a tape/snapshot, the emulator will search for a file, identical name of the file you load, but adding extension .config, and it will apply every parameter contained in the file.

So, if you load for example: game.tap, it will be searched a file game.tap.config
This config file is a text file you can edit; the format is like the .zesaruxrc main configuration file, but not every command line parameter allowed on main configuration file is allowed on a custom config file.

If you would like to know the allowed parameters in custom config files, then you can run the commands:

cd /opt/retropie/emulators/zesarux/bin
./zesarux --helpcustomconfig

Play Chuckie Egg

Chuckie Egg is a platform game that does not support the Kempston joystick. Although it is possible to remap keys in game, I found it more straightforward to create a custom config file.

First, download the TAP tape from the World of Spectrum and unzip it to your zxspectrum roms folder. The name of the tape is Chuckie Egg.tap so we need to create a custom config file, Chuckie Egg.tap.config, in the zxspectrum roms folder.

cd /home/pi/RetroPie/roms/zxspectrum
nano "Chuckie Egg.tap.config"

The parameter to use to map keys to gamepad buttons is --joystickkeybt but key where but is the joystick button you wish to map to and key is the key press you wish to map. The key press you desire must be included in quotes, for example 'q' (case is unimportant). You can also have ascii character numbers for key presses. This is useful if you wish map SPACE which has the ascii character number 32.

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

From the in-game instructions, the default controls in Chuckie Egg are: 2 to move up; W to move down; 9 to move left; 0 to move right and Z to jump. While in game, I notice that I would need to press S to start the game so we will need to map this too. For each key press, we will need a -- joystickkeybt parameter on a separate line. If you wish to use the analogue stick, then you can enter the following in the custom config file for Chuckie Egg.

--joystickkeybt -1 '2'
--joystickkeybt +1 'w'
--joystickkeybt -0 '9'
--joystickkeybt +0 '0'
--joystickkeybt 14 'z'
--joystickkeybt 3 's'

Save the custom config file. Now you are ready to play Chuckie Egg. Once the tape has launched, press Start once the intro music has ended. Enter the number of players using the NumSelect and NumAction keys described in the previous tutorial. With this custom config file, the left analogue stick on a PS3 controller is used for movement and X to jump.

I found movement too sensitive with the analogue stick so I decided to remap movement to the D-pad. The custom config file in this case was as below:

--joystickkeybt 4 '2'
--joystickkeybt 6 'w'
--joystickkeybt 7 '9'
--joystickkeybt 5 '0'
--joystickkeybt 14 'z'
--joystickkeybt 3 's'

Play Head Over Heels

Some games support the Kempston joystick but some actions are reserved for the keyboard. With ZEsarUX, it is possible to map these to the game controller. One such game is Head Over Heels which you can get from the World of Spectrum. According to the game instructions, the Kempston joystick can be used for movement, jump and carry (the Fire button does both). In addition,  the Z key will allow Head to fire doughnuts and the S key will swap control of Head or Heels.

We can map these in the same way as we did for Chuckie Egg. First create a custom config file which, if you are using the TAP version, would be called Head Over Heels.tap.config. Now add the following parameters:

--joystickkeybt 15 'z'
--joystickkeybt 13 's'

This will map fire to the Square button on a PS3 controller and swap to circle. Jump and carry is mapped to the X button by default.

To play Head over Heels, use Enter (button 8 or L2 on a PS3 controller) once the game has loaded to navigate the menus, making sure the Kempston joystick is selected in the first one. In game, when I press the circle button, I can now swop between the characters Head and Heels.

According to the World of Spectrum, Head over Heels can be played on the 128k Spectrum. We can emulate the 128k machine by adding the following parameter to the custom config file.

--machine 128k

While testing, I found that Head over Heels performs better with the 48k machine so I haven't included the --machine parameter. There are other games, for example Chase H.Q. and Rainbow Islands, where it is essential to include it to emulate the 128k machine. I suggest you experiment with both machines, particularly on the Raspberry Pi 1.


If you are having trouble getting custom config files to work, then first check that the file name is correct, particularly if you are using TZX tapes. The file name should be identical to the tape, so case sensitive and including any spaces, with .config at the end.

If the custom config file name is fine, then the next thing to do is check whether the custom config file is being loaded. To do this, you need to edit the global config file, .zesaruxrc, and comment out (with a semi-colon) the --disablefooter parameter. When you now launch your game you will get information given to you in the footer. If the custom config file has been loaded, then you should get a message Applied options for known game (see screenshot below). You can see the machine being emulated is the Spectrum 128k.

If you have any problems with your custom config files, feel free to post them below the line and I'll be happy to take a look at them.