This is a modern guide for making modern Lightgun devices work on Linux. Mainly focusing on DIY Arduino-based gun devices, specifically the closed-source GUN4IR and open-source SAMCO projects. For Aimtrak devices, refer to the MAME Documentation, of which this guide derives some information from.
- Mythbusting (and clarifications)
- The Main Part (Configurations)
- Special Thanks
When it comes to Arduino-based gun devices, you do not need to make any specific udev rules or X11 configurations. The udev rules propogated by the MAME documentation is only necessary for Aimtraks, which reveals more than two devices to the system. For Arduino-based setups, however, they only use two explicitly named devices; one for Pointer (i.e. Mouse) and one for Keyboard, which libinput is able to easily decipher as pointer and keyboard without any additional pointers.
Not using any X11 input definitions also has the side benefit of allowing the gun to be used as an X cursor, much like on Windows - be careful, as only one pointer can manipulate the X cursor at a time, so your gun may interfere with the mouse if it detects erroneous tracking!
Currently, MAME requires it to be compiled from source with the NO_USE_XINPUT=0 flag set, which implicitly requires X11 as a dependency.
Arch Linux users can simply install the mame package from the community repo. For those using the mame-git makepkg from the AUR, modify the PKGBUILD's build() function, as seen below:
make -C mame \
NOWERROR='1' \
OPTIMIZE='2' \
TOOLS='1' \
NO_USE_XINPUT='0' \
ARCHOPTS='-flifetime-dse=1'
Otherwise, the source can be obtained from GitHub and built using
make -j$(nproc) NO_USE_XINPUT=0
Once built, run it once to ensure it works and to generate its dotfiles in your home directory, i.e. ~/.mame.
After initializing, open mame.ini and edit the following under their respective sections:
#
# CORE INPUT OPTIONS
#
lightgun 1 # This enables Gun support, meaning MAME only uses pointer devices defined as lightguns.
#
# CORE INPUT AUTOMATIC ENABLE OPTIONS
#
lightgun_device lightgun # Setting this automatically maps Gun X/Y controls to the respective Lightgun devices.
#
# OSD INPUT OPTIONS
#
lightgunprovider x11 # Remember that implicit X11 requirement? xinput devices are how MAME enumerates guns that we map in the next section.
#
# SDL LIGHTGUN MAPPING
#
lightgun_index1 "Name of Lightgun Device1 Mouse" #( * )
lightgun_index2 "Name of Lightgun Device2 Mouse"
lightgun_index3 auto
lightgun_index4 auto
lightgun_index5 auto
lightgun_index6 auto
lightgun_index7 auto
lightgun_index8 auto
- ( * ) This correlates to the friendly name of your Lightgun device as closely as possible to the way it's listed in the list output of
xinput. Names don't need to be complete, but enough to narrow down the fuzzy search for said device. Follow the pattern for any subsequent gun controllers you may have connected, or wish to connect. MAME's lightgun support works by seeking specifically named USB devices as defined in the above section, matching the identifying string, i.e. name of device, and using it directly; bypassing the mouse cursor to support multiple pointer devices.
As an example, if your GUN4IR device is:
Arduino LLC GUN4IR Pro Micro P1 Mouse id=11 [slave pointer (2)]
Then you would set your index to:
lightgun_index1 "Arduino LLC GUN4IR Pro Micro P1 Mouse"
Similarly, if you're using the SAMCO system on an RP2040, and your device is:
Adafruit ItsyBitsy RP2040 Mouse id=15 [slave pointer (2)]
Then you would set your index to:
lightgun_index1 "Adafruit ItsyBitsy RP2040 Mouse"
After following this, your MAME setup should be ready for gun support. Cursors should be mapped automagically, but don't forget to bind your action buttons!
Currently, RetroArch has two methods of gun support correlating to Input Driver (input_driver)
x: (Default) Using the X11 X cursor to interact with the screen; similar to Windows'directinputudev: Interacts with udev devices directly, bypassing the display server; similar to Windows'rawinput
x works as one would expect: there is no independent mouse indices, so all that needs to be configured are the Gun mappings under Main Menu -> Settings -> Input -> Port 1 Controls. The disadvantage being that, because it uses the general X cursor, only one pointer device is supported at a time.
udev, as of libretro/RetroArch#13258, supports multiple independent mouse indices that are defined under the respective player's "Mouse Index" (Settings -> Input -> Port (playerno) Controls). The running user needs to be in the input group (sudo usermod -a -G input {user}) before using this, otherwise no keyboard or mouse input will be registered.
Regardless of which method is used, the running core needs to have the player's emulated controller be set to a Gun-adjacent profile (Examples: for FBNeo, Beetle-Saturn, and Flycast, this is simply Light Gun; for [Duck/Swan]Station, the only available option is Namco GunCon). It is recommended to set these emulated controller settings as a Game Remap File.
- RoboFleksnes from JayBee's Discord, for his device listing so I can come up with this epiphany.
- MAME devs, for their initial documentation regarding AimTrak and supporting Linux lightguns.
- RetroArch, for making this reference point for udev integration while not making enough of an effort to publicize this tidbit.
- Antonio Rojas, for
notmaking this easier by integrating the above build flag into the main Arch community repository. Apologies for the unrequited insults. :x - You, for reading! Hopefully you're well-informed; if not, or if I'm the wrong one here (likely), feel free to message me.