Recalbox's entire lightgun configuration lives in a single XML file: the list of compatible games per system, the emulator and core to use, and the RetroArch overrides (inputs, core options) applied from the global level down to the individual game.
When a game launches, Recalbox:
dolphinbar (Mayflash + Wiimote), guncon2 (Namco GunCon 2) or jvs (Recalbox JVS);With no gun detected, or if the game is unknown to the file, the launch stays strictly normal.
lightgun.xml fileThe file is not in your share: it ships with the system, read-only:
/recalbox/share_init/system/.emulationstation/lightgun.xml
To edit it (over SSH), you need to remount the system partition with write access. Your changes will be overwritten by the next Recalbox update — better submit your additions to the team on Discord so everyone benefits.
<?xml version="1.0"?>
<root>
<version>1.0.6 - 18-03-2024</version>
<!-- Common inputs, per gun type -->
<emulatorOptions filter="libretro" guntype="guncon2"> <option … /> </emulatorOptions>
<emulatorOptions filter="libretro" guntype="dolphinbar"> <option … /> </emulatorOptions>
<emulatorOptions filter="libretro" guntype="jvs"> <option … /> </emulatorOptions>
<coreOptions filter="*"> <option … /> </coreOptions>
<!-- One block per system (or group of systems) -->
<system name="atomiswave|naomi|naomigd">
<emulatorList>
<emulator priority="1" name="libretro" core="flycast-next" corename="Flycast Next" />
</emulatorList>
<emulatorOptions> <option … /> </emulatorOptions>
<coreOptions> <option … /> </coreOptions>
<gameList>
<emulatorOptions> <option … /> </emulatorOptions>
<game name="houseofthedead2" tested="true">
<emulatorOptions> <option … /> </emulatorOptions>
</game>
</gameList>
</system>
</root>
<emulatorOptions> overrides retroarchcustom.cfg (inputs), <coreOptions> overrides retroarch-core-options.cfg (core options). An <option> always has two attributes, name and value.guntype attribute (on a block or on an individual option) restricts a configuration to one gun type: dolphinbar, guncon2 or jvs. The filter attribute restricts it to an emulator (libretro) or a core.<system name="…"> accepts several systems separated by | (e.g. megadrive|segacd). Special case: the mame2003_plus block is picked not from the system but when the selected core is MAME 2003-Plus.<emulatorList> lists usable emulators, by ascending priority. This is where lightgun mode forces the emulator: for instance supermodel for Model 3, or flycast-next for Naomi.<gameList> groups games sharing the same override (a system can have several), <game> carries the configuration of one specific game.Options apply in cascade, each level able to override the previous one:
root (per guntype) → system → gameList → game
GUNP1, GUNP2, GUNP3 keywordsEach gun is seen as a mouse. To assign the right gun to the right game port (player 1 is sometimes on port 2!), the values GUNP1 to GUNP3 are replaced at launch by the real index of the matching mouse:
<option name="input_player2_mouse_index" value="GUNP1" />
A <game>'s name attribute is the flattened game name: lowercase, letters and digits only (! is also accepted, for Bang!), no spaces, no superfluous articles, no region or version:
Duck Hunt (World) v1.1 → Recalbox compares duckhuntworldv11 against the file's entries and finds duckhunt (substring search, the longest match wins).dhnes → no match, no lightgun mode.The name used is the one displayed in the game list (so the scraped name if you scraped); scraping your games is the best way to get recognizable names.
The tested attribute is either true (tested and working) or false (tested but not working — the game will not be configured for lightgun). Only tested="true" games appear in the LightGun virtual system.
Find the right system's <system> block and add inside its <gameList>:
<game name="mygame" tested="true" />
To check:
HOME button exits the game.Take inspiration from the file's existing games. It usually comes down to moving the primary/secondary fire or neutralizing an input (value="nul"):
<game name="ninjaassault" tested="true">
<emulatorOptions>
<option name="input_player1_gun_trigger_mbtn" value="nul" />
<option name="input_player1_gun_aux_a_mbtn" value="1" />
<option name="input_player1_gun_offscreen_shot_mbtn" value="nul" />
</emulatorOptions>
</game>
For tricky cases you will need the game's original manual and some quality time in RetroArch's menus — the art of the override!
You need to know the core to use, declare the core's lightgun "device" in <emulatorOptions> and its gun options in <coreOptions>:
<system name="megadrive|segacd">
<emulatorList>
<emulator priority="1" name="libretro" core="genesisplusgx" corename="Genesis Plus GX" />
</emulatorList>
<emulatorOptions>
<option name="input_player2_gun_trigger_mbtn" value="1" />
<option name="input_libretro_device_p1" value="1" />
</emulatorOptions>
<coreOptions>
<option name="genesis_plus_gx_gun_input" value="lightgun" />
<option name="genesis_plus_gx_gun_cursor" value="enabled" />
</coreOptions>
…
</system>
Good luck!