Adds dedicated pages for joysticks.

docs/modules/core/nav.adoc

@@ -60,8 +60,11 @@
 ** xref:renderer/jme3_renderbuckets.adoc[Render Buckets]
 * User Interaction
 ** xref:input/input_handling.adoc[Input Handling]
+** xref:input/joysticks.adoc[Joysticks]
+** xref:input/touch.adoc[Touch]
 ** xref:input/combo_moves.adoc[Combo Moves]
 ** xref:input/mouse_picking.adoc[Mouse Picking]
+** xref:input/joystick_ref.adoc[Joystick Reference]
 * Graphical User Interface
 ** Nifty GUI
 *** xref:gui/nifty_gui.adoc[Integration Tutorial]

docs/modules/core/pages/input/input_handling.adoc

@@ -38,91 +38,77 @@ a| Trigger
 a| Code
 
 a| Mouse button: Left Click
-a| MouseButtonTrigger(MouseInput.BUTTON_LEFT)
+a| inputManager.addMapping(mapping, new MouseButtonTrigger(MouseInput.BUTTON_LEFT))
 
 a| Mouse button: Right Click
-a| MouseButtonTrigger(MouseInput.BUTTON_RIGHT)
+a| inputManager.addMapping(mapping, new MouseButtonTrigger(MouseInput.BUTTON_RIGHT))
 
 a| Mouse button: Middle Click
-a| MouseButtonTrigger(MouseInput.BUTTON_MIDDLE)
+a| inputManager.addMapping(mapping, new MouseButtonTrigger(MouseInput.BUTTON_MIDDLE))
 
 a| Mouse movement: Right
-a| MouseAxisTrigger(MouseInput.AXIS_X, true)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_X, true))
 
 a| Mouse movement: Left
-a| MouseAxisTrigger(MouseInput.AXIS_X, false)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_X, false))
 
 a| Mouse movement: Up
-a| MouseAxisTrigger(MouseInput.AXIS_Y, true)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_Y, true))
 
 a| Mouse movement: Down
-a| MouseAxisTrigger(MouseInput.AXIS_Y, false)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_Y, false))
 
 a| Mouse wheel: Up
-a| MouseAxisTrigger(MouseInput.AXIS_WHEEL,false)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_WHEEL,false))
 
 a| Mouse wheel: Down
-a| MouseAxisTrigger(MouseInput.AXIS_WHEEL,true)
+a| inputManager.addMapping(mapping, new MouseAxisTrigger(MouseInput.AXIS_WHEEL,true))
 
 a| NumPad: 1, 2, 3, …
-a| KeyTrigger(KeyInput.KEY_NUMPAD1) …
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_NUMPAD1)) …
 
 a| Keyboard: 1, 2 , 3, …
-a| KeyTrigger(KeyInput.KEY_1) …
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_1)) …
 
 a| Keyboard: A, B, C, …
-a| KeyTrigger(KeyInput.KEY_A) …
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_A)) …
 
 a| Keyboard: Spacebar
-a| KeyTrigger(KeyInput.KEY_SPACE)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_SPACE))
 
 a| Keyboard: Shift
-a| KeyTrigger(KeyInput.KEY_RSHIFT), +
-KeyTrigger(KeyInput.KEY_LSHIFT)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_RSHIFT)), +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_LSHIFT))
 
 a| Keyboard: F1, F2, …
-a| KeyTrigger(KeyInput.KEY_F1) …
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_F1)) …
 
 a| Keyboard: Return, Enter
-<a| KeyTrigger(KeyInput.KEY_RETURN), +
-KeyTrigger(KeyInput.KEY_NUMPADENTER)
+<a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_RETURN)), +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_NUMPADENTER))
 
 a| Keyboard: PageUp, PageDown
-a| KeyTrigger(KeyInput.KEY_PGUP), +
-KeyTrigger(KeyInput.KEY_PGDN)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_PGUP)), +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_PGDN))
 
 a| Keyboard: Delete, Backspace
-a| KeyTrigger(KeyInput.KEY_BACK), +
-KeyTrigger(KeyInput.KEY_DELETE)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_BACK)), +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_DELETE))
 
 a| Keyboard: Escape
-a| KeyTrigger(KeyInput.KEY_ESCAPE)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_ESCAPE))
 
 a| Keyboard: Arrows
-a| KeyTrigger(KeyInput.KEY_DOWN), +
-KeyTrigger(KeyInput.KEY_UP) +
-KeyTrigger(KeyInput.KEY_LEFT), KeyTrigger(KeyInput.KEY_RIGHT)
-
-a| Joystick Button:
-a| JoyButtonTrigger(0, JoyInput.AXIS_POV_X), +
-JoyButtonTrigger(0, JoyInput.AXIS_POV_Y) ?
-
-a| Joystick Movement: Right
-a| JoyAxisTrigger(0, JoyInput.AXIS_POV_X, true)
-
-a| Joystick Movement: Left
-a| JoyAxisTrigger(0, JoyInput.AXIS_POV_X, false)
-
-a| Joystick Movement: Forward
-a| JoyAxisTrigger(0, JoyInput.AXIS_POV_Z, true)
-
-a| Joystick Movement: Backward
-a| JoyAxisTrigger(0, JoyInput.AXIS_POV_Z, false)
+a| inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_DOWN)), +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_UP)) +
+inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_LEFT)), inputManager.addMapping(mapping, new KeyTrigger(KeyInput.KEY_RIGHT))
 
 |===
 
 In your IDE, use code completion to quickly look up Trigger literals. In the jMonkeyEngine SDK for example, press ctrl-space or ctrl-/ after `KeyInput.|` to choose from the list of all keys.
 
+For further information on joysticks, go to <<core:input/joystick_ref.adoc#joystick-reference,Joystick Reference>>
+
 
 == 2. Remove Default Trigger Mappings
 

docs/modules/core/pages/input/joystick_ref.adoc

@@ -0,0 +1,150 @@
+= Joystick Reference
+:revnumber: 1.0
+:revdate: 2021/04/15
+:keywords: gamepad, joystick, controller, xbox, playstation, nintendo, steam, input, documentation, cheat, sheet, reference
+
+==== Buttons
+[cols="4", options="header"]
+|===
+a|Name
+a|Location
+a|Access Method
+a|Logical ID
+
+a|Top Action Button (Y/Triangle/X)
+a|image:input/BUTTON_0.png[BUTTON_0.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_0)
+a|0
+
+a|Right Action Button (B/Circle/A)
+a|image:input/BUTTON_1.png[BUTTON_1.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_1)
+a|1
+
+a|Bottom Action Button (A/Cross/B)
+a|image:input/BUTTON_2.png[BUTTON_2.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_2)
+a|2
+
+a|Left Action Button (X/Square/Y)
+a|image:input/BUTTON_3.png[BUTTON_3.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_3)
+a|3
+
+a|Left Bumper (L1)
+a|image:input/BUTTON_4.png[BUTTON_4.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_4)
+a|4
+
+a|Right Bumper (R1)
+a|image:input/BUTTON_5.png[BUTTON_5.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_5)
+a|5
+
+a|Left Trigger (L2) ^1^
+a|image:input/BUTTON_6.png[BUTTON_6.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_6)
+a|6
+
+a|Right Trigger (R2) ^1^
+a|image:input/BUTTON_7.png[BUTTON_7.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_7)
+a|7
+
+a|Select
+a|image:input/BUTTON_8.png[BUTTON_8.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_8)
+a|8
+
+a|Start
+a|image:input/BUTTON_9.png[BUTTON_9.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_9)
+a|9
+
+a|Left Analog Button (L3)
+a|image:input/BUTTON_10.png[BUTTON_10.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_10)
+a|10
+
+a|Right Analog Button (R3)
+a|image:input/BUTTON_11.png[BUTTON_11.png,width="",height=""]
+a|joystick.getButton(JoystickButton.BUTTON_11)
+a|11
+
+a|DPad Left ^2^
+a|image:input/BUTTON_12.png[BUTTON_12.png,width="",height=""]
+a|joystick.getButton("12")
+a|12
+
+a|Dpad Right ^2^
+a|image:input/BUTTON_13.png[BUTTON_13.png,width="",height=""]
+a|joystick.getButton("13")
+a|13
+
+a|Dpad Down ^2^
+a|image:input/BUTTON_14.png[BUTTON_14.png,width="",height=""]
+a|joystick.getButton("14")
+a|14
+
+a|Dpad Up ^2^
+a|image:input/BUTTON_15.png[BUTTON_15.png,width="",height=""]
+a|joystick.getButton("15")
+a|15
+|===
+
+==== Axes
+[cols="4", options="header"]
+|===
+a|Name
+a|Location
+a|Access Method
+a|Logical ID
+
+a|Left Analog Horizontal
+a|image:input/X_AXIS.png[X_AXIS.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.X_AXIS), joystick.getXAxis()
+a|x
+
+a|Left Analog Vertical
+a|image:input/Y_AXIS.png[Y_AXIS.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.Y_AXIS), joystick.getYAxis()
+a|y
+
+a|Right Analog Horizontal
+a|image:input/Z_AXIS.png[Z_AXIS.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.Z_AXIS)
+a|z
+
+a|Right Analog Vertical
+a|image:input/Z_ROTATION.png[Z_ROTATION.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.Z_ROTATION)
+a|rz
+
+a|Left Trigger ^1^,^3^
+a|image:input/BUTTON_6.png[LEFT_TRIGGER.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.LEFT_TRIGGER)
+a|rx
+
+a|Right Trigger ^1^,^3^
+a|image:input/BUTTON_7.png[RIGHT_TRIGGER.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.RIGHT_TRIGGER)
+a|ry
+
+a|Dpad Horizontal ^2^
+a|image:input/BUTTON_12.png[BUTTON_12.png,width="",height=""] image:input/BUTTON_13.png[BUTTON_13.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.POV_X)
+a|pov_x
+
+a|Dpad Vertical ^2^
+a|image:input/BUTTON_14.png[BUTTON_14.png,width="",height=""] image:input/BUTTON_15.png[BUTTON_15.png,width="",height=""]
+a|joystick.getAxis(JoystickAxis.POV_Y)
+a|pov_y
+|===
+
+====== Notes
+
+^1^ Some controllers (Xbox-type joysticks in particular) will often set the triggers as axes. In this case, the 6th and 7th buttons are skipped. In either case, it is wise to map both BUTTON_6/BUTTON_7 and LEFT_TRIGGER/RIGHT_TRIGGER, just to be safe.
+
+^2^ While the default handler is for this to be an axis, some controllers sees the DPAD as four buttons. There is no official mappings for this case, but Mark's calibrator sets it to be left, right, down, up, so we use that. In either case, it is wise to map both buttons and axes, just to be safe.
+
+^3^ On occasion, some joysticks will set the triggers to map to a single axis, with one trigger handling negative values and the other handling positive values (pressing both will cancel out and be 0). A partial workaround is to use the compatibility mappings to set this axis to its own logical ID and to assign actions to its positive and negative parts in addition to what is generally done in ^1^.