Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts) Topic is solved

Share your ideas as to how the documentation can be improved.
neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 28 Mar 2023, 08:09

1. Use term 'Game controller' instead of 'Joystick'

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
Previously 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.
If suggestion 1 is deemed not worth the hassle then I have a smaller fallback suggestion

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"
Note: 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.
Also add such a green box in the "Important notes" section here
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
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 have experienced that need on multiple PCs with Windows 10 and several different Xbox controllers (newer than Xbox 360 controllers).
I suggest this new text
Note: 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.
and either add an example script like this

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() )
}
or add a link to the JoystickTest example script, which already has code that detects and adapts to the joystick number.
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
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.
Add that if a joystick with the specified number is not detected then GetKeyState returns an empty string (not integer or float).

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
Last edited by neogna2 on 25 May 2023, 02:44, edited 1 time in total.

lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by lexikos » 29 Mar 2023, 01:59

neogna2 wrote:
28 Mar 2023, 08:09
Tagging @lexikos in case this is a bug rather than a documentation gap.
Not a bug. v1 says:
If KeyName is invalid or the state of the key could not be determined, an empty string is returned.
I don't recall there being any change in the behaviour or any intention of change.

Side note, v2-changes currently says "GetKeyState now always returns 0 or 1.", which is obviously not accurate for game controllers. It was probably only in reference to the command returning U or D.

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 29 Mar 2023, 16:09

lexikos wrote:
29 Mar 2023, 01:59
Not a bug
Ok, good to know.

The GetKeyState doc page also doesn't mention the special return values for JoyName, JoyButtons, JoyAxes and JoyInfo.

By the way, those items feel a bit shoehorned into the GetKeyState function since they're not keys (as in keyboard keys) or buttons which GetKeyState mostly is used for, but instead names to use to return text information about different properties of a plugged in game controller. We could imagine an alternative inspired by DriveGetCapacity() and other Drive___() functions that replaced GetKeyState("2JoyName") with JoyGetName(2) and similarly for the other three.

edit: many of my suggestions in OP are small but suggestion number 1 (switch term 'joystick' to 'game controller' generally) is much broader and my hunch is that Ragnar won't go for a change like that unless you say you like it. Do you?

User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by Ragnar » 14 Apr 2023, 08:27

Issue #5 and #6 has been fixed.

For the other issues: @neogna2, please review PR #645 (Modernize docs regarding game controllers), and preferably test the examples as I lack the hardware to do so. This PR is for v1, which will later be merged into v2.

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 14 Apr 2023, 13:21

Ragnar wrote:
14 Apr 2023, 08:27
Issue #5 and #6 has been fixed.

For the other issues: @neogna2, please review PR #645 (Modernize docs regarding game controllers), and preferably test the examples as I lack the hardware to do so. This PR is for v1, which will later be merged into v2.
Thanks! I will review and test when I have more time, will report back here.

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 22 May 2023, 19:43

I have now reviewed the PR. Apologies for the delay.

Most of it looks great and I'll only comment where I think further changes would improve things.

My suggestions are in the same order as the files are listed in the GitHub PR's left pane.
I'll enumerate the suggestions N1 N2 ... for easy repeat reference.

docs/KeyList.htm
N1 Also rename file RemapJoystick.htm to RemapController.htm
N2 Also rename Joystick-to-Mouse to Controller-to-Mouse (and change HTML anchor from #JoystickMouse to #ControllerMouse)

lib/GetKeyState.htm
N1 N2

N3 the return value section does not mention the special return values for JoyName, JoyButtons, JoyAxes, JoyInfo.
Suggestion: When KeyName is JoyName, JoyButtons, JoyAxes or JoyInfo, this function returns information about a controller, see <a href="../KeyList.htm#Controller">Key List</a>
Or more fully reproduce the information for each of them from KeyList

N4 Example #3 ("Makes joystick button behavior depend ...") still uses the term 'joystick' in intro and code comments (and example #6 in v2 doc).

misc/Remap.htm
N1

misc/RemapJoystick.htm
N1 N2

N5 In the "For Xbox controller 2013 and newer ..." paragraph change from
for Joy1 to Joy32 and JoyX, JoyY, JoyZ, JoyR, JoyU (and possibly JoyV and JoyPOV), but not for JoyName, JoyButtons, JoyAxes and JoyInfo
to
for Joy1 to Joy32 and JoyX, JoyY, JoyZ, JoyR, JoyU, JoyPOV (and possibly JoyV), but not for JoyName, JoyButtons, JoyAxes and JoyInfo

I tested this today with an Xbox controller model 1914 (first released 2020, https://en.wikipedia.org/wiki/Xbox_Wireless_Controller) and JoyPOV reads the d-pad state on that controller. That controller has no JoyV axis (neither has the older Xbox 360 controllers) so I can't test JoyV. But your phrasing "(and possibly JoyV)" seems reasonable to put in the doc until someone with a JoyV capable controller can say more.

scripts/JoystickTest.ahk
Tested and working with an Xbox controller model 1914 and with an Xbox 360 controller.

N7 rename script from JoystickTest.ahk to ControllerTest.ahk

N8 Since the script can be reached directly from the script/index.htm ("AutoHotkey Script Showcase") doc page some users might find it without having read the PR's version of misc/RemapJoystick.htm and thus without having seen the "For Xbox controller 2013 and newer ..." limitation. They then have no clue why the test script tooltip is missing a lot of controller data for their current generation Xbox controller.
Suggestion: add a comment line and as a convenience have the script create a GUI by adding the following code above the ; Auto-detect line:

Code: Select all

; Note: For Xbox controllers from 2013 and newer (anything newer than the Xbox 360 controller) this script can only detect button, stick, d-pad and trigger presses/states when an AutoHotkey window is active.
Gui, Show, w300 h300
N9 for convenience change right-click the tray icon to exit to press Esc to exit and append this line to the script Esc:: ExitApp

scripts/index.htm
N10 The "joystick as a mouse" script (and its table of contents entry) still uses the term 'joystick' throughout (but that update might perhaps be saved for another PR?). Related to N2.



Let me add a new suggestion related to this topic. In KeyList.htm the bullet point descriptions of JoyZ JoyR JoyU and JoyPOV follows the language of the Microsoft joystick API talking about fourth axis, fifth axis and so on. That is correct, but it would still help users to also add an explanation of what it means for the Xbox Wireless Controller, since that's the currently most popular controller for Windows. Suggestion:
For <a href="https://en.wikipedia.org/wiki/Xbox_Wireless_Controller">Xbox Wireless Controllers</a> JoyX JoyY reads left stick position data, JoyR JoyU right stick, JoyZ right and left trigger, and JoyPOV directional pad (d-pad). The same is true for Xbox 360 controllers.

I'm using Microsoft's controller control terminology from https://support.xbox.com/en-US/help/hardware-network/controller/xbox-one-wireless-controller

User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by Ragnar » 24 May 2023, 06:57

Thanks for your detailed review. I have implemented your suggestions. Please review again.

Renaming RemapJoystick.htm, JoystickMouse.ahk and JoystickTest.ahk requires extra treatment (redirection) which needs to be done by someone with server permissions. I will ask joedf.

I slightly enhanced your idea of adding a GUI to the JoystickTest script to bypass the limitation. Rather than just showing an empty GUI, the data is now displayed in an Edit control instead of a tooltip. Please test this script again.

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 24 May 2023, 18:22

I reviewed again.
The added changes look good!
JoystickTest.ahk works and I like the new GUI with data in Edit control.
(Parts of JoystickTest.ahk are so old that they could be modernized to e.g. use GetKeyState() instead of the deprecated non-function GetKeyState, but that could be a task for a separate PR some other time.)



Important: I discovered that the limitation (for 2013 and newer Xbox controllers) is stronger than I said earlier.
I earlier said it only works when an AutoHotkey window is active.
But really it only works when a window from the same AutoHotkey script is active.

I tested this in v1 on the same script's MsgBox, GUI, and main window (the one that can be opened from the tray area icon's right click menu). All worked. In contrast it does not work when another script's GUI or MsgBox or main window is active. For example Script A's hotkey Joy1:: will not trigger when script B's GUI is active.

Suggested new changes because of that:
misc/RemapJoystick.htm
from will only work if an AutoHotkey window is active
to will only work if a window from the same AutoHotkey script is active

scripts/JoystickTest.ahk
from when an AutoHotkey window is active (like this one)
to when a window from the same AutoHotkey script is active (like this one).

Give me more time to also verify this behaviour on another PC, to rule out that it isn't specific to this PC in some way. I'll try to get that done tomorrow. I only have Windows 10 PCs to test on at the moment so ideally someone else with a Windows 11 PC and controllers would also jump in here and test these claims and scripts.



scripts/JoystickMouse.ahk
Also needs a GUI added to become usable with 2013 or newer Xbox Controllers.
Suggestion:

Code: Select all

Gui, +AlwaysOnTop
Gui, Add, Text, w300, Note: For Xbox controller 2013 and newer (anything newer than the Xbox 360 controller), controller-to-mouse actions only work when a window from the same AutoHotkey script is active (like this one).
Gui, Add, Button, w100 h100, Click me
Gui, Add, Edit, xp+150 yp R7 w100 h80, scroll`nme`n`n`n`n`n`n`n`n`nworld
Gui, Show,, ControllerMouse Test Script

User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by Ragnar » 25 May 2023, 01:25

Give me more time to also verify this behaviour on another PC, to rule out that it isn't specific to this PC in some way. I'll try to get that done tomorrow.
Okay, I'll wait. Have you already tried to run the script as administrator? Sometimes this helps, especially with user input. See https://www.autohotkey.com/docs/v1/FAQ.htm#uac

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 25 May 2023, 02:40

I have now tested on another Windows 10 PC and the behaviour is the same.

The limitation is the same also when running the controller hotkey script as administrator.

User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by Ragnar » 26 May 2023, 07:02

I have merged the changes from v1 and v2. Could you please test the v2 examples one last time?

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 26 May 2023, 15:16

I have reviewed the v2 changes and tested code examples and scripts there. Looks good to me except:

misc/RemapController.htm
The forum URL is for XInput.ahk is incorrect (I failed to notice this in the v1 review earlier)
In v1 docs at https://github.com/AutoHotkey/AutoHotkeyDocs/blob/v1/docs/misc/RemapController.htm#L41
change from viewtopic.php?f=83&t=1062 to viewtopic.php?f=6&t=29659
In v2 docs at https://github.com/AutoHotkey/AutoHotkeyDocs/blob/v2/docs/misc/RemapController.htm#L41
change from viewtopic.php?f=83&t=1062 to viewtopic.php?f=83&t=106254

scripts/ControllerMouse.ahk
Suggestion: To support 2013+ Xbox controllers also in this bundled script add this Gui code above line ClickButtonLeft(*)

Code: Select all

MyGui := Gui("+AlwaysOnTop", "ControllerMouse")
MyGui.Add("Text", "w300", "Note: For Xbox controller 2013 and newer (anything newer than the Xbox 360 controller), this script can only detect controller events if a window it owns is active (like this one).")
MyGui.Add("Button", "w100 h100", "Click me")
MyGui.Add("Edit", "xp+150 yp R7 w100 h80", "scroll`nme`n`n`n`n`n`n`n`n`nhello")
MyGui.Show()
MyGui.OnEvent("Close", (*) => ExitApp() )
ControllerMouse_gui.png
ControllerMouse_gui.png (11.61 KiB) Viewed 2959 times
lib/GetKeyState.htm and misc/RemapController.htm
All the small code examples on these pages are tested and working. (Of course those examples also require an active window owned by the script for 2013+ xbox controllers. But it seems ok to leave that for the user to add, since the need is now documented and also exemplified in the larger ControllerTest.ahk script. That's similar to how the user with these small examples has to themselves verify their joystick number and if needed change Joy1:: to 2Joy1:: and so on.)

User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)  Topic is solved

Post by Ragnar » 27 May 2023, 01:44

Thanks for reviewing and testing. I have fixed the links.

I did not add a GUI for ControllerMouse.ahk on purpose. Since the limitation does not apply to other controllers, a GUI would ruin the idea of running the script in the background. In this case, the limitation notes are sufficient.

neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Joystick documentation (terminology, Xbox controller limitations, XInput, example scripts)

Post by neogna2 » 27 May 2023, 15:44

Ragnar wrote:
27 May 2023, 01:44
a GUI would ruin the idea of running the script in the background.
Ok that makes sense.

Thank you for all your work on the documentation!

Post Reply

Return to “Suggestions on Documentation Improvements”