Joypad Auto Configuration

How does matching work?

RetroArch is shipped with a set of configuration files for the most common joypads. When you plug a joypad for the first time, we try to find a matching profile in our set.

The matching algorithm considers three criteria:

Device name
Vendor ID
Product ID

We compute a matching score for each configuration file based on these three factors. The profile with the highest score is chosen to configure the pad.

Note

The Vendor ID and Product ID pair is often abbreviated as vid:pid.

Why is it needed?

RetroArch works many platforms. Each of these platforms has one or more input systems. These input systems in turn differ widely in the way they enumerate the pad buttons. For this reason, your joypad buttons may be mapped differently depending on if you are using Windows, Mac, or Linux.

Traditional emulators allow you map each button of your pad to the original pad of the emulated system. For example, this is how the Snes9x joypad configuration interface looks:

RetroArch also allows this kind of manual mapping. However, RetroArch tries to go further by detecting your joypad and automatically configuring it so manual configuration becomes obsolete.

Benefits

With RetroArch joypad auto-configuration system, your joypad will be recognized and will work out of the box.

This allows:

Use many different joypads and have them attributed to each players like it would work on a real game console.
Unplug the second joypad, and replace it by another one, even if it's of a different brand and model.

Having automatically configured joypads makes it a lot easier to navigate the RetroArch Menu with the joypad. This is very convenient when running RetroArch on a game console, where a keyboard and a mouse are not always available. It is also what makes RetroArch suitable to build your own game console using Lakka or a similar OS.

Installing or updating joypad profiles

downloading joypad profiles

The set of joypad profiles used by RetroArch can be downloaded and updated from the menu. Go to Main Menu -> Online Updater -> Update Autoconfig Profiles to get the latest version of the profile pack.

A message will appear at the bottom of the screen showing the download progress and the extraction of the archive.

Generating a joypad profile

If your joypad is not recognized by RetroArch even after updating the profiles, you can generate a profile from the menu.

    1. Unplug all the other joypads
    2. Use Settings -> Input -> User 1 Binds -> User 1 Bind All. Make sure that your mapping is perfect by testing every button in the menu and in some games.
    3. Use Settings -> Inputs -> User 1 Binds -> User 1 Save Autoconfig
    4. The new profile will be saved to your disk.
    5. Use Settings -> Inputs -> User 1 Binds -> User 1 Bind Default All to clear manual bindings and rely on the new profile
    6. Unplug your joypad an re-plug it. See if it is auto configured.

Clear manual bindings

It is important to to skip the step of clearing manual bindings after using the User 1 Save Autoconfig command. In order to avoid issues using your profile in the future, remember to go to Settings -> Inputs -> User 1 Binds -> User 1 Bind Default All to reset the manual settings before completing this process.

If you are happy with your profile, you can submit it to RetroArch so that other users benefit:

Edit the autoconfig file for your joypad manually to include the input descriptors (please see the Input Descriptors section below)
Submit your profile to our joypad profile repository.

Troubleshooting

If your joypad is not configured properly, you should generate a RetroArch log. Your log will show if a profile has been matched for your pad and the path of the corresponding profile.