result = Gamepad(command [,arg1] [,arg2])
Gamepad reads the state of any USB game controller. Gamepad was
previously named “JoyStick”, the name has been changed to agree with the
USB Human Interface Device (HID) terminology.
Gamepad provides built-in help. For usage, enter “Gamepad” alone on the
As initialization of Gamepad takes significant time, you should call it
once at the beginning of your script before entering the trial loop.
After plugging/unplugging or replugging of any USB devices you *must*
call Gamepad(‘Unplug’) or clear all, so Gamepad can recognize the changed
hardware configuration at next invocation. Actually, a clear all is
recommended, as Gamepad(‘Unplug’) doesn’t work reliably on non-OSX systems.
The subfunctions for state queries of axis, button and hat state are
optimized for low execution time – suitable for time critical parts of
your trial loop. All other functions, e.g., for query of the number of
buttons etc. are not optimized, so they shouldn’t be called in time
critical parts of your loop.
If you need ultra-fast queries, check the help for ‘GetButtonRawMapping’,
‘GetAxisRawMapping’ and ‘GetHatRawMapping’ for a slightly inconvenient,
but superfast way to query device state.
On Linux/X11, Gamepad() uses the Screen() mex file and its mouse query functions.
On Linux, gamepads and joysticks are treated as a special type of mouse/pointing
device with multiple extra axes and buttons. You should install the optional
joystick driver, although the evdev driver may also work with suitable configuration.
This joystick driver has different names, depending on the version of the Ubuntu
distribution you are using, and if the hardware enablement stack (HWE) is installed.
You can usually find out if the HWE is installed by typing: system(‘hwe-support-status’),
unless your system is weirdly configured and only partially installed the HWE,
in which case it matters if your X-Server is the “factory default” or the HWE
variant. Check in your package manager.
On Ubuntu 20.04 LTS or 22.04 LTS original installs or upgrades, ie. without the
optional HWE for the X-Server installed, this should work:
“sudo apt-get install xserver-xorg-input-joystick”
If the HWE is installed, you will need one of the following instead:
Ubuntu 20.04-LTS: “sudo apt-get install xserver-xorg-input-joystick-hwe-20.04”.
Ubuntu 22.04-LTS: “sudo apt install xserver-xorg-input-joystick-hwe-22.04”.
You should also install a custom joystick configuration file to customize the
mapping and behaviour of buttons and axis, and if the Joystick also operates
as a mouse or not.
Gamepad is not yet supported on Windows. WinJoystickMex() in the
Psychtoolbox/PsychContributed subfolder may serve as a temporary
replacement of more limited functionality.