JInput introduction

This posts gets longer and longer. Here is a short summary what it includes:

[]an introduction on how to setup and program with JInput
]a link to another tutorial with code examples and such
[]links to my jinput plugin for linux
]link to my JInputTester application (JNLP!)

By popular request and since I have been using JInput for some time now I decided to give the API a better reputation by providing some introductory information.

A couple of times I read that people were unable to get JInput running. They often missed the point of the so called plugins and wondered that there are no devices. My first post will handle these basics:


JInput consists of two parts. One part is JInput itself. It is a jar named jinput.jar containing all the public classes and interfaces needed to write an application. JInput depends on JUtils (jutils.jar) which can be found on java.net too. These 2 jars have to be in your application’s classpath. there are several ways to accomplish this and I hope you know at least one. If you feel unfamiliar with that read the tutorial at java.sun.com.

The other part is called the plugin. A plugin is automatically recognized by jinput when invoking a special method - the only thing you should care about a plugin is to put the files in the right folder. And here is how that goes …

Installation of the plugin(s):

Nearly all plugins consist of two files. One of them is the native library (e.g. dxinput.dll, libjinput.so) and the other one is the java part of the plugin (any official name for that?). There are multiple ways for installing a plugin:

  1. the easiest but most (system) polluting way:
    create a folder named ‘controller’ inside your ${jre.home}/lib/ext folder and copy the two files in.

  2. the application specific way:
    assume we have an application using jinput. the application’s jar is named foo.jar and is in a folder named foo-dir. for installing the plugin for this application only, create a folder named ‘controller’ inside foo-dir and copy the 2 files in. afterwards start the application from a console with ‘java -jar foo.jar’. be sure that you are inside foo-dir when doing this.

applicable to 1) and 2): it is better to put two 2 files making up a plugin in a subdirectory of its own. this particular topic was discussed here: http://www.java-gaming.org/cgi-bin/JGNetForums/YaBB.cgi?board=jinput;action=display;num=1084179275

  1. the system property - way of the JNLP app or the developer
    Since JNLP (popular as Java Webstart) has some restrictions on how native libaries are handled, JInput provides a simple way to access the plugin (and yes: only one plugin) through the classpath.
    at first make sure the plugin’s jar is in the classpath.
    second: make sure the native library is in ${java.library.path} (depending on platform and if you’re using JNLP - refer to java.sun.com they explain everything in detail there).

After that set the system property jinput.plugins to the name of the main plugin class. You can find out that name using your favorite zip tool, opening the plugin jar file and look for a file like XYZEnvironmentPlugin(.class). on the command-line you can set the system property using the -D parameter.

For convenience here is a list of known classes:

[td]Windows and DirectInput based plugin[/td]
[td]Linux and Kernel Event Interface based plugin by endolf[/td]
[td]Mac OS X and HID based Plugin[/td]
[td]Linux and Kernel Event Interface based plugin by theBohemian[/td]


  • do not program ‘by hand’. download a modern ide like netbeans or eclipse. they handle the classpath conveniently and you can set system properties through dialogs instead of the command-line (although way 2 may be difficult with an IDE).

  • I have not written JInput or JUtils. That means there may be mistakes in the stuff above.

I have to go to bed now but if people find my explanations above useful I will write another long post - containing more programming stuff.

Please comment on wrong points or stuff that was explained bad or such.

Another tutorial by me which includes some programming examples can be found here: [url]https://freefodder.dev.java.net/tutorial/jinputTutorialOne.html[/url]
My very own implementation of the linux based JInput plugin:



A long time ago (last year?) I have writen a Swing-based test application for JInput. It is now available via JNLP (eg. Java Webstart) again and should work on Windows and Linux for now. I am going to add MacOS support for it soon.

JNLP: http://www.inf.fu-berlin.de/~rschuste/java/jinputtester/jinputtester.jnlp

source code:

The application is Free software and licensed under the GPL.

– EDIT: highlighted the part which kaffiene mentioned
– EDIT: added link to the next tutorial
– EDIT: added link to my own plugin
– EDIT - 09.16.04: added content summary and links to JInputTester

Just a wee addition - I followed these instructions and it didn’t work. I’ve got it going now, however. You needed to add that jutils.jar also needs to be in your classpath

(for newbies: it’s distributed in the pre-built jinput archive under the coreAPI/lib directory)

Maybe that is obvious to other people, but it wasn’t to me :wink:

I have problems too deploying in webstart when my game is running in an os other than windows. Here is the trace of the error I have:

Java Web Start 1.4.2_03 Console, started Wed Jul 21 09:35:37 EDT 2004
Java 2 Runtime Environment: Version 1.4.2_03 by Apple Computer, Inc.
Logging to file: /log.txt
Selecting best display mode for 640x480x32 max 85 hertz
found 640x480x32 59 hertz
found 640x480x32 66 hertz
found 640x480x32 72 hertz
found 640x480x32 75 hertz
found 640x480x32 85 hertz
Refresh rate selected: 85
Number of buffers used: 1
Available accelerated memory (in bytes): -1
[21-Jul-2004 09:36:05] INFO - loading map...
[21-Jul-2004 09:36:05] INFO - Found Chunk - MPHD, reading...
[21-Jul-2004 09:36:05] INFO -   loading map header.
[21-Jul-2004 09:36:05] INFO -   FMP version   : 1.0
[21-Jul-2004 09:36:05] INFO -   MapWidth      : 230
[21-Jul-2004 09:36:05] INFO -   MapHeight     : 80
[21-Jul-2004 09:36:05] INFO -   BlockWidth    : 32
[21-Jul-2004 09:36:05] INFO -   BlockHeight   : 32
[21-Jul-2004 09:36:05] INFO -   ColourDepth   : 32
[21-Jul-2004 09:36:05] INFO -   BlockByteSize : 32
[21-Jul-2004 09:36:05] INFO -   NoOfBlocks    : 1333
[21-Jul-2004 09:36:05] INFO -   NoOfImages    : 1338
[21-Jul-2004 09:36:05] INFO - Found Chunk - EDHD, skipping...
[21-Jul-2004 09:36:05] INFO - Found Chunk - CMAP, reading...
[21-Jul-2004 09:36:05] INFO -   loading 256 entries.
[21-Jul-2004 09:36:05] INFO - Found Chunk - BKDT, reading...
[21-Jul-2004 09:36:05] INFO -   loading 1333 blocks.
[21-Jul-2004 09:36:05] INFO - Found Chunk - BGFX, reading...
[21-Jul-2004 09:36:05] INFO -   loading 1338 images.
[21-Jul-2004 09:36:12] INFO - Found Chunk - BODY, reading...
[21-Jul-2004 09:36:12] INFO - Found Chunk - LYR1, reading...
[21-Jul-2004 09:36:12] INFO - Found Chunk - LYR2, reading...
[21-Jul-2004 09:36:13] INFO - Map loaded succesfully.
21-Jul-2004 09:36:20 mightybubbles.MightyBubbles <init>
SEVERE: net/java/games/input/DirectInputEnvironmentPlugin
java.lang.NoClassDefFoundError: net/java/games/input/DirectInputEnvironmentPlugin
      at mightybubbles.MightyBubbles.<init>(Unknown Source)
      at mightybubbles.MightyBubbles.main(Unknown Source)
      at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
      at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
      at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
      at java.lang.reflect.Method.invoke(Method.java:324)
      at com.sun.javaws.Launcher.executeApplication(Launcher.java:844)
      at com.sun.javaws.Launcher.executeMainClass(Launcher.java:804)
      at com.sun.javaws.Launcher.continueLaunch(Launcher.java:682)
      at com.sun.javaws.Launcher.handleApplicationDesc(Launcher.java:397)
      at com.sun.javaws.Launcher.handleLaunchFile(Launcher.java:199)
      at com.sun.javaws.Launcher.run(Launcher.java:167)
      at java.lang.Thread.run(Thread.java:552)

fps : 0.0
Game Duration: 1090416981 seconds

Even tough I specify the system property for the plugin it seems it doen’t have any effect for an OS other than windows.

Here is my jnlp file:

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="file:///C:/games" href="mighty_bubbles.jnlp">
<jnlp spec="1.0+" codebase="http://www.myjavaserver.com/~theanalogkid/servlets/app" href="mighty_bubbles.jnlp">
            <title>Mighty Bubbles Demo</title>
            <vendor>Jerome Blouin</vendor>
            <description>Demo of Mighty Bubbles Game</description>
            <icon href="icon.gif"/>
            <icon kind="splash" href="splash.gif"/>
            <j2se href="http://java.sun.com/products/autodl/j2se" version="1.4+" initial-heap-size="32m"/>
            <jar href="lib/mighty_bubbles-demo.jar"/>
            <jar href="lib/dom4j.jar"/>
            <jar href="lib/gagetimer1_1.jar"/>
            <jar href="lib/jutils.jar"/>
            <jar href="lib/jinput.jar"/>
            <property name="sun.java2d.accthreshold" value="0"/>
      <resources os="Windows">
            <j2se href="http://java.sun.com/products/autodl/j2se" version="1.4+"/>
            <jar href="lib/windows/dxinput.jar"/>
            <nativelib href="lib/windows/gagetimer1_1-native.jar"/>
            <nativelib href="lib/windows/dxinput-native.jar"/>
            <property name="jinput.plugins" value="net.java.games.input.DirectInputEnvironmentPlugin"/>
      <resources os="Linux">
            <j2se href="http://java.sun.com/products/autodl/j2se" version="1.4+"/>
            <jar href="lib/linux/linux.jar"/>
            <nativelib href="lib/linux/libjinput-native.jar"/>
            <property name="jinput.plugins" value="net.java.games.input.LinuxEnvironmentPlugin"/>
      <resources os="MacOS">
            <j2se href="http://java.sun.com/products/autodl/j2se" version="1.4+"/>
            <jar href="lib/mac/HIDWrapper.jar"/>
            <nativelib href="lib/mac/libjinput-native.jar"/>
            <property name="jinput.plugins" value="net.java.games.input.OSXEnvironmentPlugin"/>
      <application-desc main-class="mightybubbles.MightyBubbles"/>

Thanks in advance for any help!

seems to work on this machine, which has no install of jinput on it.


I found the problem in my deployment. In fact it was not related to the deployment, the problem was the fact that I used the DirectInputEnvironmentPlugin class directly in the code. Don’t ask me why I did that. I think I didn’t relalized that it was specific to DX.

This bug fixed, I have now another one that occurs on Linux. I can initialize the plugin but no controller is found with the call ControllerEnvironment.getDefaultEnvironment().getControllers();

Any idea why it behaves like that?

For your information the OS is SUSE (version 8 I think) with KDE 3.1 running on a Pentium 3.

Thanks in advance.

[quote] I can initialize the plugin but no controller is found with the call ControllerEnvironment.getDefaultEnvironment().getControllers();

Any idea why it behaves like that?
Its a kernel 2.4 based system that why only USB-devices will show up and you even need to allow read & write access to the event devices.

Try this:
run ‘cat /dev/input/event’ as a user and play around on your controllers (mice, kbs, sticks etc). if garbage is displayed on your console everything is fine. if you run into problems with access rights change them. if it tells you that there are no devices (= device file exists but no physical device) complain on this board and ask someone (eg. endolf & me) to support the joystick & keyboard API on Linux which is the pre-2.6 way of accessing input hardware :slight_smile:

you may do cat on mouse and js to verify that it works without problems there.

In theory jinput on a 2.4 kernel will pick up the joysticks and any USB devices, it’s the keyboard and mouse (non usb) that are the only problem. That was one reason for proposing the AWT plugin for mice and keyboards (which is still on my todo list). The major problem is that there will be no axis names for a joystick, a standard joystick plugged into a game port (if it’s USB all will work fine anyway, i think) you can get no axis names. Thats why currently the first linux plugin tries to find an event device descriptor for each joystick. It uses the old joystick interface as I found the data comming from the event interface was a little more than dodgy, like my digital joystick reported axis values from -256 to 256 if I recal, yet the centre position was not 0 and the axis ranges were not even. That was after running the jscal program, and the joystick interface reported the whole range and a centre position of 0, and although it moved a fraction even when stationary, it was all within the null zone.


Thanks for support TheBohemian and endolf. What I understand is that there is no easy way to use JInput on Linux for the keyboard if it is not a USB device?

I am thinking of implementing a fallback IO mode based on the AWT event model in case JInput is not working for the requested device. Is there a better way of doing this without AWT events?

If you arn’t using a 2.6 kernel that is correct, although like I said, I’m planning on an AWT plugin, that will hopefully solve your problems. I’m in the middle of moving house right now, so I’m stuck with a windows only laptop, which means I should be able to get some of the non linux jinput things done, and you never know, I might even get some of my own game done :slight_smile: (was that pig just fly past the window)


At first: Could some mod move the discussion started by TheAnalogKid in a separate thread?

And now:
Here is the link to my first JInput tutorial:

Have fun!

[quote]At first: Could some mod move the discussion started by TheAnalogKid in a separate thread?
Only by copying and pasting, and getting it all under the moderators name as if they’d said it :(. YaBB is too crappy to let mods simply “move” a chunk of a thread :(. Although maybe ChrisM can do this…

So you decided you didn’t want it on JGF then? If so, would help to know why (so hopefully we can improve it with version 3, coming soon)

[quote] So you decided you didn’t want it on JGF then? If so, would help to know why (so hopefully we can improve it with version 3, coming soon)
I just started coding and typing two days ago and did not think about how to publish it. I remembered that there are these JOAL tutorials and borrowed a bit of their look & feel.
Finally the tutorial is CCed: You can do nearly everything with the document even without asking me :slight_smile:

Just wanted to mention that I have updated the first post again and added links to JInputTester.

That first post should be part of the Wiki - is it?

I can build the oddlabs version fine, but when I test it with my own code (which worked earlier with this version of jinput: http://www.newdawnsoftware.com/resources/jinput/?C=M;O=D)
it is not finding a force feedback steering wheel I have connected. I have the latest version of the sources with the raw plugin commented out. I tried various combinations with dxinput.jar and the other dlls in the same folder or a “controller” folder. I tried various values for -Djinput.plugins.
It recognizes the directx plugin, but only lists the mouse and keyboard. It says “Failed to create rumblers: Failed to create effect (Ox80070057)”.

I was just wondering where are the right places to put all the jar files and dll files, if that is the problem. Thanks for any help.

hmm I can’t seem to follow the intro. I’m trying to get JInput set up but even with this intro I just don’t know what I’m doing (in terms of directories etc.) like how do i find the folder mentioned below to do this?

[quote]1) the easiest but most (system) polluting way:
create a folder named ‘controller’ inside your ${jre.home}/lib/ext folder and copy the two files in.
Also, I downloaded the Jinput thing and I’m not sure what files are supposed to go where,

I downloaded the file jinput_windows_2005-06-15.zip which has directories:

(folder) Jinput



are these all the files necessary to start using the API?
what exactly do I need to do next to get it running? I am on windows XP by the way.

Any help would be greatly appreciated!



Look in the jinput2 thread, and find the builds Elias posted there. They are of the newer jinput builds and should work.


Thanks, but which link do i use? The first link is loads of directories and stuff and the second link is a zip, i downloaded the zip and put all the files in a folder and tried to run the ControllerReadTest from that folder but it wouldn’t work…

So nobody can help me out any further?


Go to jinput.dev.java.net, On the left hand menu select ‘Documents & Files’, click on the ‘Combined’ folder and get the latest combined binaries file. This contains all the Java and all the native binaries.

Extract the zip somewhere.

The jar file needs adding to your classpath and you need to set -Djava.library.path to point to the folder with the .so, dll’s and jnilib in.

This layout will work on any of the supported platforms.

There are no tests included in the distribution currently, but I can upload the test jar if you want, and that would need adding you your classpath too.