ForceFeedback Joystick Driver for Java logo

ffjoystick4java logo

This driver was made as a practical project for the Department of Computational Perception at JKU Linz.


This document contains:

Install instructions

This is what you should do in general. Below you will find detailed instructions for Windows, Linux and MacOS X.

  1. Connect your joystick and make sure it works as an input device.

  2. If you have a force feedback joystick: make sure force feedback works. If necessary, install the correct driver from the device manufacturer.

  3. Install SDL 1.3 or higher:

  4. Install the joystick driver:

go to top

Installation on Windows

  1. Test input: Connect your controller. On Windows XP, go to 'Control Panel', 'Game Controllers'. On Windows 7, go to 'Control Panel', type 'game' in the search bar, below 'Devices and Printers' click 'Set up USB game controllers'. Your device should be listed. Mark it and click 'Properties'. Test the input. If necessary, calibrate the joystick.

  2. Install driver: Make sure you have DirectX installed. On current editions of Windows DirectX is included. To make sure, run 'dxdiag.exe' (type 'dxdiag' in the 'run' menu, or in a command prompt). Updates may be available via Windows Update. (For installation instructions see also How to Download and Install DirectX and

    Install your device specific driver from the website of the manufacturer. Be aware that some computers have a 32-bit Windows installed, even if they have a 64-bit CPU. In that case you will need the 32-bit version of the driver. If you have Windows 7 but you cannot find a driver, you may try a driver for Windows Vista instead.

    Test force feedback: If your joystick came with an extra power adapter, make sure it is plugged in correctly. On Windows XP, go to 'Control Panel', 'Game Controllers'. On Windows 7, go to 'Control Panel', type 'game' in the search bar, below 'Devices and Printers' click 'Set up USB game controllers'. Mark your device and click 'Properties'. You will probably see a different interface than before you installed the driver. Press some buttons on your controller to test force feedback. Usually buttons trigger force feedback effects to be played. Be aware that on some controllers force-feedback can be disabled using a button or switch.

    Test if your device is recognized by DirectX. Start 'dxdiag' once again. Your device should show up in the 'Input' tab.

    To test if your force feedback driver is installed correctly and works within DirectX, you can use the program 'FFConst.exe', which comes as a sample with the DirectX SDK (DirectX Developer Center). In case you do not want to download the whole DirectX SDK package and build FFConst, I uploaded an executable of it here: If FFConst does not start, make sure you followed the previous steps correctly and try again. ;)

  3. SDL for Windows is included with the joystick driver – there's nothing to do in this step.

  4. Be sure you have a Java Runtime Environment (JRE) or SDK installed. Download the joystick driver from (compiled SDL.dll for Windows is included). Unpack it and change to the subdirectory 'windows' (32-bit) or 'windows64' (64-bit). Run the file 'run.cmd' to start the testing GUI, or type

    java at.wisch.joystick.test.JoystickTest

    on the command line. Either the 'windows' or the 'windows64' version should work on any windows in some command prompt. (Note: To start a 64-bit command prompt run '%windir%\system32\cmd.exe'. To start a 32-bit command prompt run '%windir%\SysWoW64\cmd.exe'. I did not get confused. This is how it is...)

    If the ForceFeedback menu is inactive, your device was not recognized as force feedback device.

go to top

Installation on Linux

  1. Connect your controller and make sure input works. (see also Type

    cat /dev/input/js0

    in a terminal. Press some buttons and move the sticks. If you see weird things, it should work. To test more specific use 'joystick'. On Debian/Ubuntu:

    sudo apt-get install joystick
    jscal /dev/input/js0
    jstest /dev/input/js0

    To calibrate you can use 'jscalibrator'. On Debian/Ubuntu:

    sudo apt-get install jscalibrator
  2. Since Ubuntu 9.04 (and kernel 2.6.28) Force Feedback is supported by default, so there is no need to compile a custom kernel. To test force feedback you can use the Linux Force Feedback Library, available from See for instructions.

  3. Install SDL 1.3.

    1. If you have an old version of SDL 1.3 installed you should uninstall it ('sudo make uninstall').

    2. Download SDL 1.3 and unpack it. ( - menu 'SDL SVN' - download the latest source snapshot for SDL 1.3)

    3. In the directory where you unzipped to: run '' and 'configure'.

    4. Run 'make'.

    5. Run 'sudo make install'.

  4. Install the joystick driver.

    1. Be sure you have a Java Development Kit (SDK) installed.

    2. Download the driver from

    3. Change to the 'linux' subdirectory and mark the files '' and '' as executable.

    4. If necessary, modify '' using your system dependent paths and directories. The paths in the parameters are:

    5. the Java include-directory (for JNI)
    6. the Java include/linux-directory (for JNI)
    7. the default system library-path (for SDL)
    8. for output: also the default system library-path
  5. Run ''.

  6. If necessary, modify '' using your default system library-path.

  7. Run '' to start the testing GUI. If the ForceFeedback menu is inactive, your device was not recognized as force feedback device.

go to top

Installation on MacOS X

Installation on MacOS X is quite similar to the installation on Linux. Unlike on Linux, 'make' and the Gnu C/C++ compilers are not installed by default on MacOS. To test if you have them: open a terminal, type 'make' and press enter. Do the same with 'gcc' and 'g++'. If you do not have these developer tools, download the XCode package from You will need to register for an Apple Developer account. Once you have registered, login and click 'Download Software' and then 'Developer Tools'. Find 'Xcode Tools'. Check the description for compatibility information. (Usually the latest versions of XCode do not work with older versions of MacOS X). Download the 'CD/DVD Image' and install it.

You will also need to use the 'sudo' command later. If your administrator account has no password (a blank password), you need to set up a password.

  1. Connect your controller and make sure input works.

    To see if it is connected correctly start the 'System Profiler' (“Hard drive” icon – 'Applications' – 'Utilities'). Click 'Devices and volumes”. In the USB tree your controller should be listed.

    To really test input you can use a freeware or shareware program like:

  2. You can skip this step on MacOS X. Or you can use the game 'Jammin' Racer' to test force feedback. But still, if force feedback works in that game it does not mean that it will work in Java. More on that issue later in the next section, 'Supported controllers and effects'. You can download the game from

  3. Install SDL 1.3.

    • If you have an old version of SDL 1.3 installed you should uninstall it ('sudo make uninstall').

    • Download SDL 1.3 and unpack it. ( - menu 'SDL SVN' - download the latest source snapshot for SDL 1.3)

    • In the directory where you unzipped to: run '' and 'configure'.

    • Run 'make'.

    • Run 'sudo make install'.

  4. Install the joystick driver.

    • Be sure you have a Java Development Kit (SDK) installed.

    • Download the driver from and unpack it.

    • Open a Terminal and change to the 'macos' subdirectory. Type

      g++ -o libffjoystick.jnilib FFJoystick.cpp `sdl-config --cflags --libs` -I/System/Library/Frameworks/JavaVM.framework/Versions/A/Headers/ -shared -arch x86_64

      to build the joystick library file. The directory '/System/Library/Frameworks/JavaVM.framework/Versions/A/Headers/' can vary depending on your system. It might also be '/System/Library/Frameworks/JavaVM.framework/Headers/'. You can also try to find the file 'jni.h' (use the command 'find / -name "jni.h"') and use the path where this file is located.

      Depending on your system architecture you might also have to use '-arch i386' or just drop that parameter.

    • Type the following command to start the testing GUI:

      java -Djava.library.path=. at.wisch.joystick.test.JoystickTest

      If the ForceFeedback menu is inactive, your device was not recognized as force feedback device.

      If you get an error like "no suitable image found. Did find: /.../libffjoystick.jnilib: mach-o, but wrong architecture" open 'Java-Preferences' and change the order of the Java Virtual Machines execution order, e.g. put the 64-bit Java VM above the 32-bit VM. If you do not know where to find 'Java-Preferences', use Finder (the search field in your menu bar).

go to top

Supported controllers and effects

All controllers that are supported by SDL are supported by this driver as well. For input I have not seen any controller that does not work on any OS, though on Windows the axis order is sometimes mixed up on some controllers. For force feedback see the following section.

On Windows basically every controller that supports DirectX will be supported by the driver. The problem is, that even if support for a device is given, it is not sure the device will play all the effects it is supposed to support. In my experience: Usually the device will tell you it supports all 12 types of effects that exist in DirectX, but for example: a rumbling gamepad will never be able to play a condition effect. Sometimes it does not even report an error. It just does not play a thing. Sometimes effects are not working because a “wrong” direction type is used. Edgar Simo wrote in the libSDL forums: “The problem with force feedback especially on windows is that the drivers tend to be loads of steaming crap. Windows on top of it all has a very "loose" force feedback driver model which makes it so you have to continuously check a billion of small minor things to see if they're supported to support all the possible cases. Not to mention the fact that not all devices actually support what they broadcast among other things.“ (

On Linux fewer devices seem to be supported. For a list of controllers that will most likely support FF on Linux see: Also the number of supported effects is less, compared to windows. But at least the device will support what it tells you. Quoting Edgar Simo on driver models again: “Linux probably takes the cake for cleanest, although it is missing some bells and whistles the mac os x and windows implementations have.”

On MacOS X I could not test much. On the newest Snow Leopard 10.6 64-bit none of my controllers supported FF. The problem seems to be that no there are no drivers for recent controllers. Hendrik Bartel, Sr. Product Manager, from wrote in an email that “unfortunately, the Mac driver was never really moved forward”. So though SDL uses the official force feedback library for MacOS X it is likely that it does not work with newer controllers or newer versions of MacOS. (see

So in general the problem is that for many controllers there are bad operating system drivers available, or none at all. Here is what I experienced with my controllers:

Custom effects did not work on any of my devices. Also Friction, Inertia and Damper felt like the same on my Logitech Force 3D Joystick.

Note: In some system drivers you can enable/disable a centering spring force and adjust its strength. On Linux it was always active with my Logitech Force 3D Joystick. In Windows it is adjustable in the control panel.

If you test the driver with any other ForceFeedback-gamepad, please send me a quick mail about your experiences. If you have any suggestions, or if you want to report a bug, please see or contact me via email:

go to top

Supported operating systems

As mentioned before, this driver is based on SDL 1.3. Therefore joystick input should work wherever SDL 1.3 works. Unfortunately force feedback does not always work, due to missing or bad operating system joystick drivers. I tested on:

go to top

Developing applications

Basically you need to use the static methods of class JoystickManager to obtain Joystick and FFJoystick objects. Then you can use these to obtain input data and play effects. Take a look at the javadoc to get to know how you should use the driver. Also the classes JoystickInputDemo and JoystickForceDemo should demonstrate how to use everything. The latest javadoc is included in the download from You can also read the javadoc online at

On windows for some controllers the axis order is reversed. I corrected that with a special precompiler variable setting in FFJoystick.cpp. Set INVERTAXISORDER to 1 when you compile the dll for Windows. This problem is known and exists on other driver implementations as well. This also applies to the order of FF axes.

I'm not sure if there is a bug or if just none of my controllers supports custom effects. Also I don't have a gamepad with a trackball, therefore I could not test the corresponding methods. Please inform me if you find a bug: You can also send feature requests and feedback of all kind.

go to top

Notes on SDL

Simple DirectMedia Layer is a cross-platform multimedia library designed to provide low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. It is used by MPEG playback software, emulators, and many popular games, including the award winning Linux port of "Civilization: Call To Power."” (from Since version 1.3 SDL has platform independent support for force feedback (haptic) effects.

The people working on SDL are doing great work As this driver is based on SDL, it will hopefully work on future OS versions as well. If you notice changes in the haptic interface of the newest versions of SDL, please inform me: I will try to update my driver as soon as possible.

go to top

Frequently Asked Questions (F.A.Q.)

go to top


go to top

Copyright (c) 2010, Martin Wischenbart
All rights reserved.

w3c html validation logo