AutoHotkey v2 documentation (just like v1) uses 'Joystick' as term for game input devices. But today joystick more commonly refer narrowly to input devices with a tall stick ( https://en.wikipedia.org/wiki/Joystick ) and the term 'game controller' or simply 'controller' is used for game input devices more broadly. The most common types of game controllers today are of the gamepad type which do not look like the tall joysticks of old.
For some evidence of this see
https://en.wikipedia.org/wiki/Game_controller
https://www.microsoft.com/en-us/store/collections/xboxcontrollers
https://www.nintendo.com/store/hardware/joy-con-and-controllers/
https://www.playstation.com/en-se/accessories/dualshock-4-wireless-controller/
Suggestion 1: change to 'Game controller' or 'controller' in (sub)headings and text that currently use 'Joystick'.
https://www.autohotkey.com/docs/v2/KeyList.htm#Joystick
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#button
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#context-sensitive-joystick-buttons
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#axis
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#joystick-axes
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#joystick-pov-hat
https://www.autohotkey.com/docs/v2/scripts/index.htm#JoystickMouse
https://www.autohotkey.com/docs/v2/scripts/index.htm#JoystickTest
https://www.autohotkey.com/docs/v2/lib/GetKeyState.htm
One complication is that built in hotkeys like Joy1 should not change, since that would break code backward compatibility. So if the term 'game controller' is adopted a short explanation of why the phrase 'Joy' is still used must also be added. I suggest
If suggestion 1 is deemed not worth the hassle then I have a smaller fallback suggestionPreviously AutoHotkey documentation used the name 'Joystick' for what is now called 'Game Controller'. Controller hotkeys and button names still use the phrase 'Joy' for code backwards compatibility reasons.
Suggestion 1B: In all documentation sections that currently use 'Joystick' add 'game controller' as a synonym word.
For example at https://www.autohotkey.com/docs/v2/KeyList.htm#Joystick the heading could change from 'Joystick' to 'Joystick (Game Controller)'.
Also add game controller to the help file index and point it to the Joystick page.
2. Add note about Xbox controller limitations
https://www.autohotkey.com/docs/v2/KeyList.htm#Joystick
Add something like this in a green box above "multiple joysticks"
Also add such a green box in the "Important notes" section hereNote: For Xbox controllers from 2013 or newer (anything newer than Xbox 360 controllers) hotkeys Joy1 to Joy32 only work when an AutoHotkey window is active. This limitation also applies to GetKeyState() for Joy1 to Joy32 and JoyX, JoyY, JoyZ, JoyR, JoyU [and, I guess, JoyV and JoyPOV?]. To detect those controller inputs for other active windows use the XInput.ahk library
GetKeyState can read JoyName, JoyButtons, JoyAxes and JoyInfo even when an AutoHotkey window is not active.
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#imp
I say "something like" above because ideally the new text should have an evidence-based and exact description of which game controllers this limitation does and does not apply to. At least for controllers from Microsoft and some other big names. I *think* the limitation applies to all of these https://en.wikipedia.org/wiki/Xbox_Wireless_Controller But I haven't actually tested with all controller variants there. I also haven't tested with various other controllers. Maybe a forum post with a small test script could crowd source testing reports from forum users who have different controllers?
@evilC maybe knows more about which controllers are affected?
For background on this limitation see this 2018 thread with evilC, Lexikos and others
viewtopic.php?style=2&t=55206
Some recent threads where the issue comes up
viewtopic.php?p=514479#p514479
viewtopic.php?f=82&p=510578
3. Update note about joystick numbers
https://www.autohotkey.com/docs/v2/KeyList.htm#Joystick
Currently the green box says
I have experienced that need on multiple PCs with Windows 10 and several different Xbox controllers (newer than Xbox 360 controllers).Note: If you have trouble getting a script to recognize your joystick, one person reported needing to specify a joystick number other than 1 even though only a single joystick was present. It is unclear how this situation arises or whether it is normal, but experimenting with the joystick number in the joystick test script can help determine if this applies to your system.
I suggest this new text
and either add an example script like thisNote: In some cases a single plugged in controller is recognized as a joystick number other than 1. To make a script handle that first detect the joystick number and then create controller hotkeys for it.
Code: Select all
Loop 16
if GetKeyState(A_Index "JoyName")
{
JoyNumber := A_Index
break
}
if IsSet(JoyNumber)
{
Hotkey(JoyNumber "Joy1", (*) => MsgBox("button pressed") )
MyGui := Gui(, "Joystick Test")
MyGui.Show("w500 h500")
MyGui.OnEvent("Close", (*) => ExitApp() )
}
https://www.autohotkey.com/docs/v2/scripts/index.htm#JoystickTest
4. Update JoystickTest script
https://www.autohotkey.com/docs/v2/scripts/index.htm#JoystickTest
The joystick button hotkeys generated by the script does not work with new Xbox controllers (see above). Add a note on that and/or add this to the script
Code: Select all
;For new Xbox controllers (newer than Xbox 360) joystick hotkeys only work when an AutoHotkey window is active
MyGui := Gui(, "Joystick Test Script")
MyGui.Show("w500 h500")
MyGui.OnEvent("Close", (*) => ExitApp() )
5. Fix and comment RemapJoystick script
https://www.autohotkey.com/docs/v2/misc/RemapJoystick.htm#joystick-axes
Errors because KeyToHoldDown is read before declared. To fix add this at the top of the function static KeyToHoldDown := ""
The script also assumes that the plugged in controller has joystick number 1. Add a comment about that and/or a link to the green box explainer (suggested above) for page https://www.autohotkey.com/docs/v2/KeyList.htm#Joystick
Recent thread where this issue was reported
viewtopic.php?f=82&t=115425
6. update GetKeyState() return value documentation
https://www.autohotkey.com/docs/v2/lib/GetKeyState.htm#Return_Value says
Add that if a joystick with the specified number is not detected then GetKeyState returns an empty string (not integer or float).Type: Integer (boolean), Float or Integer
[---]
When KeyName is a joystick axis such as JoyX, this function returns a floating-point number between 0 and 100 to indicate the joystick's position as a percentage of that axis's range of motion. This test script can be used to analyze your joystick(s).
When KeyName is JoyPOV, this function returns an integer between 0 and 35900.
To confirm that an empty string is returned run this oneliner script MsgBox Type(GetKeyState("Joy1")) with no joystick plugged in.
Tagging @lexikos in case this is a bug rather than a documentation gap.
Recent thread where this issue came up
viewtopic.php?p=514479#p514479