Using the Controllers

The controllers API in LWJGL is based on JInput and requires the JInput natives to be available. However, these are distributed as part of the LWJGL package. Note that while JInput provides access to controllers including keyboard and mouse that LWJGL does not support access to the keyboard and mouse via the controllers API.

Mouse and Keyboard can be accessed through their associated classes.

More information on JInput can be found here

The Controllers API assumes that you'll let your player choose the controller they want to use and configure the game controls. The code below shows how to access the list of controllers connected to the system and get a operating system name for each one. This name should be enough to identify a particular controller to your player.

Controllers.create();
int numberOfControllers = Controllers.getControllerCount();
 
String playerChosenController = "MyJoystick";
Controller playerControl; 
 
for (int i=0;i<numberOfControllers;i++)
{
   Controller c = Controllers.getController(i);
   if (c.getName().equals(playerChosenController))
   {
       playerControl = c;
   }
}

As with controllers themselfs it is assumed that the player will configure the use of each button. The controllers API assigns an index to each button on a specific controller. This index can be used to access the name given for a button and to check a button's state. However, the name given for a button is specified by the operating system/driver and often is as useful as “BUTTON_1”.

The code snippet below shows displaying some diagnostic information about the buttons and checking the state of a specific button.

int buttons = controller.getButtonCount();
 
for (int b = 0; b < buttons; b.size())
{
    System.out.println("Button " + b + " = " + controller.getButtonName(b));
}
 
int selectedIndex = 0; // the index of the button we're checking
 
while (gameLoop) {
   controller.poll(); // update the controller from the hardware
 
   if (controller.isButtonPressed(selectedIndex)) {
      // fire the huge gun!
   }
}

Note the use of the poll() method. This reads the controllers state. However, if you're calling the normal LWJGL Display.update() this will perform the poll() on all controllers for you.

Axis values can be accessed in two ways. The first is much like buttons, each axis is given an index and can be read using it:

int axisCount = controller.getAxisCount();
 
for (int i=0;i<axisCount;i++) {
    System.out.println("Axis "+i+" = "+controller.getAxisName());
}
 
int selectedAxis = 0; // the axis we're using to control the game
 
while (gameLoop) {
    if (controller.getAxisValue(selectedAxis) > 0) {
         // bank the ship right
    } else if (controller.getAxisValue(selectedAxis) < 0) {
         // bank the ship left
    }
}

Note that the value returned for an Axis will always be between -1.0 and +1.0. Also, each axis has a configurable “dead zone”. When the value returned from the axis is within in this dead zone a zero value will be returned. This helps to prevent non-zero values being returned when the joystick/wheel/pad is centered.

The dead zone can be configured with:

controller.setDeadZone(selectedAxis, 0.1f);

This would set the dead zone to a area -0.1 to +0.1f around zero.

The second way to access the axis values is via named accessor methods. These will return the values for specific axis if the controller has them. Otherwise a zero value will be returned. The named axes are:

    public float getXAxisValue();
 
    public float getYAxisValue();
 
    public float getZAxisValue();
 
    public float getRXAxisValue();
 
    public float getRYAxisValue();
 
    public float getRZAxisValue();

In many cases, player control configuration for instance, it would be nice to be able to be notified when any control has been pressed. This can be achieved using the event system (much like the Keyboard or Mouse classes).

Each frame calling the poll() method generates the event objects representing any controller presses or changes that have occurred. As mentioned above, if you're calling Display.update() the controllers will be polled auto-magically. Since event objects will be generated and added to a queue to be processed, if you choose not to use them the following method should be called each frame to clear out the queue.

Controllers.clearEvents();

Finally, the following code can be used to cycle through the events that have been processed. This might make sense in a player configuration loop.

while (Controllers.next())
{
    Controller source = Controllers.getEventSource();
 
    if (Controllers.isEventButton()) 
    {
        System.out.println("Event was from "+source.getName()+" and was from button "+Controllers.getEventControlIndex());
    }
    if (Controllers.isEventAxis())
    {        
        System.out.println("Event was from "+source.getName()+" and was from axis "+Controllers.getEventControlIndex());
    }
}