Charles Keepax's Blog

I have been playing quite a few smaller indie games lately and have found that whilst the style of these games often lends itself to using a gamepad, joystick support under Linux on these games is often quite poor. So I wrote a small program to fake keyboard events based on joystick events, thus circumventing any poor joystick support.

The program is very simple we read events from the joysticks device file (/dev/input/js0 etc.) and then use the XTest extension to generate keypress events based on these. All configuration of the program is done statically in a header file called "config.h", this defines which joystick device file you will use and which keypresses will be generated in response to which joystick events. You will also need to have the X11 and XTest libraries installed to build the program; on Ubuntu these are the libx11-dev and libxtst-dev packages.

Using the program is pretty simple too, edit config.h to your desired settings, build using "make" and then run "joytokey". Then just leave joytokey running whilst you play your game.

Getting the Code

The code can be found on my Bitbucket here: joytokey

Configuration

The best way to work out what settings you need for your gamepad is to run:

jstest --event /dev/input/js0

This will print out all the events generated from your joystick (obviously substitue /dev/input/js0 for the joystick you want), simply push the buttons you want to map and observe the values generated. I believe this program is in the joystick package on Ubuntu, if you don't already have it. The output will look something like this:

1. Event: type 1, time 30798287, number 2, value 1
2. Event: type 1, time 30798447, number 2, value 0
3. Event: type 2, time 30806623, number 0, value 32767
4. Event: type 2, time 30806783, number 0, value 0
5. Event: type 2, time 30807503, number 1, value -32767
6. Event: type 2, time 30807663, number 0, value -32767

Type 1 events are button presses and type 2 events are direction controls. You should use the number field as the index into the respective configuration array and for direction controls you will need to select a suitable threshold for each direction. Here we show a suitable setup for the direction controls show above:

We map axis 0 to the left and right arrows and axis 1 to the p and l keys. The sym and the str field are interchangable and you should use whatever is simplest to define the key you want to map to. The sym field will be ignored if you specify both.

Similarly we setup the buttons mapping buttons 1,2,3,4 to keys q,w and the up and down arrow. Note the key setup is simpler and only requires you to specify the key:

That should be about it, enjoy.