Package org.xjge.core

Class Input

java.lang.Object
org.xjge.core.Input
public final class Input
extends java.lang.Object
Provides a single point of access through which the state of peripheral input devices may be managed.
Since:
2.0.0

  • Field Summary

    Fields
    Modifier and Type Field Description
    static int AI_GAMEPAD_1  
    static int AI_GAMEPAD_10  
    static int AI_GAMEPAD_11  
    static int AI_GAMEPAD_12  
    static int AI_GAMEPAD_13  
    static int AI_GAMEPAD_14  
    static int AI_GAMEPAD_15  
    static int AI_GAMEPAD_16  
    static int AI_GAMEPAD_2  
    static int AI_GAMEPAD_3  
    static int AI_GAMEPAD_4  
    static int AI_GAMEPAD_5  
    static int AI_GAMEPAD_6  
    static int AI_GAMEPAD_7  
    static int AI_GAMEPAD_8  
    static int AI_GAMEPAD_9  
    static int KEY_MOUSE_COMBO
    Special case value associated with the KeyMouseCombo input device.
    static Widget missingGamepad
    A widget object provided by the engine that will be rendered anytime an input device is disconnected.

  • Constructor Summary

    Constructors
    Constructor Description
    Input()  

  • Method Summary

    Modifier and Type Method Description
    static void bindPreviousPuppet​(int deviceID)
    Reverts the binding of an input device to its previous puppet object if it had one.
    static java.util.Map<Control,​java.lang.Integer> getDeviceControls​(int deviceID)
    Obtains the current control configuration of an input device.
    static boolean getDeviceEnabled​(int deviceID)
    Checks whether or not an input device is currently allowing the engine to process its input actions.
    static java.lang.String getDeviceName​(int deviceID)
    Obtains the name of an input device.
    static boolean getDevicePresent​(int deviceID)
    Checks whether or not an input device is currently connected to the system.
    static Puppet getDevicePuppet​(int deviceID)
    Obtains the current puppet object an input device is using (if any).
    static float getDeviceSetting​(int deviceID, java.lang.String name)
    Obtains the value of some setting that an input device can use to adjust the responsiveness of input actions during gameplay.
    static java.lang.Character getKeyChar​(int key, int mods)
    Obtains the letter/symbol of a keyboard key.
    static int[] getKeyMouseAxisValues()
    Obtains an array of values denoting which GLFW keys will be used by the KeyMouseCombo input device to mimic the action of an analog stick.
    static int getNumDevices()
    Obtains the amount of input devices that are currently connected to the system.
    static void revertEnabledState​(int deviceID)
    Reverts the enabled state of an input device to its previous value.
    static void setDeviceControls​(int deviceID, java.util.Map<Control,​java.lang.Integer> config)
    Sets the current control configuration of an input device.
    static void setDeviceEnabled​(int deviceID, boolean enabled)
    Sets the current enabled state of an input device.
    static void setDevicePuppet​(int deviceID, Puppet puppet)
    Sets the current puppet object an input device will control.
    static void setDeviceSetting​(int deviceID, java.lang.String name, float value)
    Changes the setting value of the specified input device.
    static void setKeyMouseAxisValues​(int x1, int x2, int y1, int y2)
    Sets the GLFW keys the keyboard will use to mimic the action of an analog stick.
    static void setVirtualGamepadInput​(int deviceID, Control control, float inputValue)
    Changes the input value of a virtual gamepads control component.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • Input

      public Input()

  • Method Details

    • getNumDevices

      public static int getNumDevices()
      Obtains the amount of input devices that are currently connected to the system. The value provided by this method includes only peripheral devices such as gamepads.
      Returns:
      the number of connected input devices

    • getDevicePresent

      public static boolean getDevicePresent​(int deviceID)
      Checks whether or not an input device is currently connected to the system.

      NOTE: The keyboard/mouse along with virtual AI controlled gamepads are always connected by default.

      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      Returns:
      true if the input device is connected

    • getDeviceSetting

      public static float getDeviceSetting​(int deviceID, java.lang.String name)
      Obtains the value of some setting that an input device can use to adjust the responsiveness of input actions during gameplay.

      It's recommended that gameplay systems instead use Command.getDeviceSetting(String) and reserve this method for instances where the current value of the setting in question needs to be exposed to the user- such as an interface that allows the user to edit their devices preferences.

      NOTE: By default the engine provides deadzone settings for both the left and right analog sticks of each input device. These settings determine how much a stick will need to be moved before its input is recognized. The values of these settings can be queried with "leftDeadzone" and "rightDeadzone" respectively.

      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3
      GLFW_JOYSTICK_4 KEY_MOUSE_COMBO
      name - the name of the setting to parse a value from
      Returns:
      the value of the setting or NaN if the device and/or setting could not be found

    • getDeviceEnabled

      public static boolean getDeviceEnabled​(int deviceID)
      Checks whether or not an input device is currently allowing the engine to process its input actions.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16
      Returns:
      true if the input device is in an enabled state
      See Also:
      setDeviceEnabled(int,boolean)

    • getDeviceName

      public static java.lang.String getDeviceName​(int deviceID)
      Obtains the name of an input device.

      NOTE: Device names are not guaranteed to be unique and typically only reflect the model and/or manufacturer. This information can often help better identify a device, but shouldn't be used to refer to it.

      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16
      Returns:
      a human-readable description of the input device

    • getDeviceControls

      public static java.util.Map<Control,​java.lang.Integer> getDeviceControls​(int deviceID)
      Obtains the current control configuration of an input device.

      Control configurations are user-defined input preferences that will be retained between runtime sessions. These configurations dictate how controls on an input device will be mapped to actions in game.

      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3
      GLFW_JOYSTICK_4 KEY_MOUSE_COMBO
      Returns:
      an immutable collection containing the current control configuration of an input device
      See Also:
      setDeviceControls(int,java.util.Map<org.xjge.core.Control,java.lang.Integer>)

    • getKeyMouseAxisValues

      public static int[] getKeyMouseAxisValues()
      Obtains an array of values denoting which GLFW keys will be used by the KeyMouseCombo input device to mimic the action of an analog stick.
      Returns:
      an array containing the axis values corresponding to various GLFW keyboard keys
      See Also:
      setKeyMouseAxisValues(int,int,int,int)

    • getDevicePuppet

      public static Puppet getDevicePuppet​(int deviceID)
      Obtains the current puppet object an input device is using (if any).
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16
      Returns:
      the current puppet object of the specified input device or null if no puppet object is bound/the device cannot be found

    • getKeyChar

      public static java.lang.Character getKeyChar​(int key, int mods)
      Obtains the letter/symbol of a keyboard key.

      NOTE: This method assumes that the keyboard producing the input is an unmodified english model. As such, the letter/symbol of the key in question must correspond to an ASCII character between the ranges of 32-127, any characters outside of this range will return null.

      Parameters:
      key - the value supplied by GLFW of a single key on the keyboard
      mods - a value supplied by GLFW denoting whether any mod keys where held (such as shift or control)
      Returns:
      a character corresponding to the pressed key or null if one cannot be found

    • setDeviceSetting

      public static void setDeviceSetting​(int deviceID, java.lang.String name, float value)
      Changes the setting value of the specified input device.

      This method can also be used to provide additional settings the implementation may require from input devices. To achieve this, simply pass the value obtained from getDeviceSetting(int,java.lang.String) to the value argument of this method and it will be retained between runtime sessions.

      For example, you might do something like this: 

       XJGE.init()...
 
 float prevValue = Input.getDeviceSetting(KEY_MOUSE_COMBO, "settingName");
 Input.setDeviceSetting(KEY_MOUSE_COMBO, "settingName", prevValue);
 
 XJGE.start()...
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3
      GLFW_JOYSTICK_4 KEY_MOUSE_COMBO
      name - the name of the setting that will be changed
      value - the new value to change the setting to
      See Also:
      getDeviceSetting(int,java.lang.String)

    • setDeviceEnabled

      public static void setDeviceEnabled​(int deviceID, boolean enabled)
      Sets the current enabled state of an input device.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16
      enabled - if true, the device will allow the engine to process its input actions
      See Also:
      getDeviceEnabled(int)

    • revertEnabledState

      public static void revertEnabledState​(int deviceID)
      Reverts the enabled state of an input device to its previous value. This is useful in the case of an event or cutscene where the players input device may have been temporarily disabled.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16

    • setDeviceControls

      public static void setDeviceControls​(int deviceID, java.util.Map<Control,​java.lang.Integer> config)
      Sets the current control configuration of an input device.

      NOTE: When setting the configuration of controls LEFT_STICK_X and LEFT_STICK_Y for the KeyMouseCombo input device, a bitwise OR (symbolized as |) should be used to pass two values representing the GLFW keyboard keys that will be used to move the analog stick along a single axis.

      For example, you might do something like this: 

       var keyMouseConfig = new HashMap() {{
     ...
     put(LEFT_STICK_X,  GLFW_KEY_A | GLFW_KEY_D);
     put(LEFT_STICK_Y,  GLFW_KEY_W | GLFW_KEY_S);
     ...
 }};
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3
      GLFW_JOYSTICK_4 KEY_MOUSE_COMBO
      config - the collection containing the new control configuration to apply
      See Also:
      getDeviceControls(int)

    • setKeyMouseAxisValues

      public static void setKeyMouseAxisValues​(int x1, int x2, int y1, int y2)
      Sets the GLFW keys the keyboard will use to mimic the action of an analog stick. Typically you'd use this anytime the player wishes to use a key combination other than WASD to move (in first person for example).
      Parameters:
      x1 - the GLFW key used to move left along the x-axis
      x2 - the GLFW key used to move right along the x-axis
      y1 - the GLFW key used to move down along the y-axis
      y2 - the GLFW key that to move up along the y-axis
      See Also:
      getKeyMouseAxisValues()

    • setDevicePuppet

      public static void setDevicePuppet​(int deviceID, Puppet puppet)
      Sets the current puppet object an input device will control.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16
      puppet - the puppet object the input device will use
      See Also:
      getDevicePuppet(int)

    • bindPreviousPuppet

      public static void bindPreviousPuppet​(int deviceID)
      Reverts the binding of an input device to its previous puppet object if it had one. This is useful in instances such as vehicles where the player may assume control of a puppet temporarily before switching back to their main binding.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      GLFW_JOYSTICK_1 GLFW_JOYSTICK_2 GLFW_JOYSTICK_3 GLFW_JOYSTICK_4
      KEY_MOUSE_COMBOAI_GAMEPAD_1 AI_GAMEPAD_2AI_GAMEPAD_3
      AI_GAMEPAD_4AI_GAMEPAD_5 AI_GAMEPAD_6AI_GAMEPAD_7
      AI_GAMEPAD_8AI_GAMEPAD_9 AI_GAMEPAD_10AI_GAMEPAD_11
      AI_GAMEPAD_12AI_GAMEPAD_13 AI_GAMEPAD_14AI_GAMEPAD_15
      AI_GAMEPAD_16

    • setVirtualGamepadInput

      public static void setVirtualGamepadInput​(int deviceID, Control control, float inputValue)
      Changes the input value of a virtual gamepads control component. Use this if you'd like to hook up an AI to an existing puppet object.
      Parameters:
      deviceID - the number which corresponds to the input device in question. One of:
      AI_GAMEPAD_1AI_GAMEPAD_2 AI_GAMEPAD_3AI_GAMEPAD_4
      AI_GAMEPAD_5AI_GAMEPAD_6 AI_GAMEPAD_7AI_GAMEPAD_8
      AI_GAMEPAD_9AI_GAMEPAD_10 AI_GAMEPAD_11AI_GAMEPAD_12
      AI_GAMEPAD_13AI_GAMEPAD_14 AI_GAMEPAD_15AI_GAMEPAD_16
      control - a component such as a button whos input value will be changed
      inputValue - the input value denoting to what extent the control was manipulated or zero if not at all