Wednesday, August 24, 2011

HowTo: Set up JInput API and Library for Java Development on Mac OS X or Linux Platform

Yod (August 24, 2011)

I came back from 2011 AUVSI convention (hosted in Washington DC) and found a lot of controllers for the unmanned vehicles to be very similar to the PC or console game controllers (read Real War Games: Video Game Controllers Hit the Battlefield). So, I decided to experiment with Logitech Dual Action Game Controller by using it as an optional controller to navigate my map/navigational tracking application that I wrote using Java on Mac OS X platform.

It took me couple of hours going through several game controller API for Java. After testing out 3 APIs, I decided to stick with JInput due to its stable development support (but poor documentation). It took me 20-30 minutes to figure out how to set JInput and write simple code to test my logitech controller, because the website provides very little information.

Setting up JInput API

First, download the nightly build API from

Then follow the 3 simple steps below:

1. set up classpath (e.g. /Users/Yod/Library)
2. move jinput.jar and jinput_test.jar into the directory pointed to by classpath
3. extract the jar file jinput.jar and jinput_test.jar
There should be a net/ directory inside the classpath (e.g. /Users/Yod/Library/net)

Note for developers using Eclipse IDE:
Add the API jar files (jinput and jinput_test) to your project
1. Click [project (top bar)] --> select [properties] --> click [Java Build Path]
2. Click [Add External JARs...] and browse to the directory containing the jar files
3. Select the jar file and click [Open]
4. Click [Ok], when you're done.

You should now be able to compile your java source code using Eclipse IDE. However, you still cannot run the application until you set up the link to the library. If you run the app, you will encounter a Link Error similar to the one below.

[JInput LinkError in Apple OSX development environment]
JInput version: 2.0.6-b1241
java.lang.UnsatisfiedLinkError: no jinput-osx in java.library.path
at java.lang.ClassLoader.loadLibrary(
at java.lang.Runtime.loadLibrary0(
at java.lang.System.loadLibrary(
at Method)
at java.lang.Class.forName0(Native Method)
at java.lang.Class.forName(
at USBControllerTest.main(
[Timestamp] log
INFO: is not supported

5. To set up the link, simply put "libjinput-osx.jnilib" file in the application working directory, which is the same location of your main app class file. This will allow you to run the code from CLI. However to run the code from Eclipse, you'll need to link the native jinput osx library to your Eclipse project.

Click [project (top bar)] -->select [properties]
In the middle of the window, "JARS and class folders on the build path:"
- Click [JRE System Library] --> click "Native Library Location" --> click "Edit..."
- Browse to the directory that contains "libjinput-osx.jnilib" file and click [Ok]

Source Code (To Test the USB Game Controller)


public class USBControllerTest {

public static void main(String[] args) {
System.out.println("JInput version: " + Version.getVersion());
ControllerEnvironment ce = ControllerEnvironment.getDefaultEnvironment();
Controller[] cs = ce.getControllers();
for (int i = 0; i < cs.length; i++)
System.out.println(i + ". " + cs[i].getName() + ", " + cs[i].getType() );



macOSX:bin yod$ java USBControllerTest

JInput version: 2.0.6-b1241
0. Apple Internal Keyboard / Trackpad, Keyboard
1. Apple Internal Keyboard / Trackpad, Mouse
2. Apple Internal Keyboard / Trackpad, Mouse
3. Logitech Dual Action, Stick
4. PS/2+USB Mouse, Mouse

1 comment: