One of the coolest features of RetroArch , the reference frontend for the Libretro API , is the ability to automatically configure controllers using joypad autoconfiguration files.

This is an often overlooked feature, but when set up correctly, it allows for a true plug-and-play experience with gamepads, joysticks, and other input devices, eliminating the need for manual configurations and significantly improving usability.

What are Autoconfiguration Files?

Autoconfiguration files allow RetroArch to recognize an input device and map its buttons and axes to the RetroPad virtual controller, a standard layout that serves as a reference point for all emulation cores.

The RetroPad acts as a universal translator, converting signals from different controllers, such as a DualShock or a retro gamepad, into a format that RetroArch can understand.

Without these files, you would have to manually configure each button and stick, a task that could be complex and daunting.

RetroArch Joypad Autoconfig Files serves as a shared repository, where the community collects files for hundreds of devices. Each file includes essential information, such as the Vendor ID , Product ID , and Device Name , which RetroArch uses to identify the controller.

It also contains mappings that connect physical inputs to the RetroPad controls, and in some cases, input descriptors , which are labels that appear in the user interface (for example, “Cross” or “L2”) to make setup more intuitive.

How to create an autoconfiguration file

When a controller is not recognized by RetroArch , even after updating the profiles, the user can generate a new autoconfiguration file directly from the program interface.

To do this, simply go to the Settings menu, select the Input section , navigate to Port 1 Controls and choose Save Controller Profile . This process creates a file with the correct device name and input mappings, based on the connected controller.

Accuracy is key: RetroArch must correctly detect the device, and the generated file should not be manually modified without in-depth knowledge.

Experts recommend not creating files for controllers you don’t own, to avoid incorrect configurations that could confuse other users.

To verify that the file is working, the user can reset the controller mappings to default using the Reset Default Controls option , unplug and replug the device, then check that the mappings are correct in the Port 1 Controls menu .

If your controller includes a button to open the RetroArch menu , you may also want to check the Menu (Toggle) key binding in the Hotkey section .

Contribute to the Repository

If you generate an autoconfiguration file for a controller not yet in the repository , you can share it with the community, making it easier for other users to experience it .

Contributing means expanding a database that makes controllers immediately usable , but requires following some guidelines to avoid problems .

First, make sure that a file for your controller does not already exist by checking three key attributes: Vendor ID , Product ID , and Device Name , stored as input_vendor_id, input_product_idand input_device. A duplicate file with the same attributes may cause conflicts.

Additionally, mappings should be generic, reflecting the standard controller layout, rather than custom configurations. This approach ensures that the file will be useful to most users.

To improve the experience, it is recommended to add input descriptors, labels such as “Square” or “Triangle” that RetroArch displays in the interface. These descriptors are not automatically generated and require manual entry in the file, for example:

input_b_btn_label = " Cross "
 input_y_btn_label = " Square "
 input_a_btn_label = " Circle "
 input_x_btn_label = " Triangle "

To upload the file, simply create a Pull Request on GitHub, following the official documentation and making sure to place the file in the correct folder, corresponding to the input_drivercontroller attribute (for example, “udev” or “hid”).

Note: An error in choosing the folder could compromise the integration of the .

The File Structure

Autoconfiguration files are simple to understand, but they follow a strict format. Each file consists of a series of attributes and values, written as attribute_name = valuewith a naming convention snake_case. The attributes are divided into three categories:

Device Descriptors : Identify the controller, including the input driver ( input_driver), device name ( input_device), Vendor ID ( input_vendor_id), and Product ID ( input_product_id). An optional user interface name ( input_device_display_name) can be added.
Button and Axis Mappings : Specifies how the controller’s buttons and sticks correspond to the RetroPad. For example, input_b_btn = "0"it maps the RetroPad’s B button to the controller’s 0 button, while input_l_x_plus_axis = "+0"mapping right movement to the left analog stick. The RetroPad includes buttons such as A, B, X, Y, triggers, shoulders, and the D-Pad, in addition to the stick axes.
Input Descriptors : Define the labels displayed in the interface, such as input_l2_btn_label = "L2". It is essential that the descriptor name matches the mapping exactly, distinguishing between buttons and axes to avoid errors.

An error in the file structure, such as an incorrect descriptor, can prevent RetroArch from loading it, making accuracy a must.

The importance of this system

Autoconfiguration files are much more than a technical detail: they are a vital component that makes RetroArch accessible to players of all experience levels.

Setting up a controller manually can be a barrier for beginners or those unfamiliar with RetroArch ‘s menus .

Thanks to the repository and community contributions, thousands of devices are already supported, and each new file expands this compatibility network.

For more details, see the official GitHub repository or RetroArch’s automatic joypad setup guide .

Changelog

Android: A/B and X/Y buttons swapped on Xbox Series Wireless Controller thanks to @hunterk in pull request #1219
udev: added support for Mad Catz, Mayflash Wiimote and Thrustmaster FGT thanks to @AngeloScipione in pull request #1217
Android: Added support for Retroid Pocket 5 thanks to @patrickli in pull request #1216
Android: Updated Sony DualShock 4 v2 support thanks to @6lackmag3 in pull request #1215
dinput: added support for STK7039RG. xinput: added compatible Bluetooth device (Spanish version) thanks to @cjdg in pull request #1213
Android: Added support for DualSense Wireless controller (Google TV 12), disabled by default, thanks to @davidhedlund in pull request #1177
Capcom Home Arcade Controller: Fixed vendor identification (vendor_id CHA1) thanks to @cjom in pull request #1229
SDL2: Added a variant of the Xbox Elite Series 2 controller for LG WebOS TVs thanks to @Honest-n in pull request #1228
dinput/sdl2: added support for Horipad Steam thanks to @eVenent in pull request #1226
dinput: added support for 8BitDo Ultimate 2C Wireless controller via Bluetooth thanks to @JonSnow88 in pull request #1224
dinput: added support for 8BitDo Ultimate 2 Wireless controller via Bluetooth thanks to @JonSnow88 in pull request #1223
dinput: fixed menu activation function on 8BitDo M30 via USB thanks to @djleon83 in pull request #1222
dinput: fixed menu activation function on 8BitDo M30 via Bluetooth thanks to @djleon83 in pull request #1221
udev: Updated Nintendo Switch controllers after button remapping thanks to @nfp0 in pull request #1227
udev: added support for 8BitDo Ultimate 2 Wireless controller thanks to @CosmicHeron in pull request #1231
SDL2: Added support for PCEngine Mini controller thanks to @Ceotom in pull request #1230