RetroArch is the official front end for the libretro API. RetroArch and libretro provide a way to take an existing emulator and load that emulator as a library or 'core'. RetroArch then handles the input (controls) and output (graphics and audio) while the emulator core handles the emulation of the original system. With a few simple changes to the emulator source code, almost any existing emulator could become a libretro core.
In RetroPie, the libretro emulator cores are identified with a lr- in front of their name. For example, lr-snes9x2010 is the libretro core of the SNES emulator called snes9x2010.
RetroArch and libretro provide ability to configure controllers once for many emulators instead of having to configure each emulator individually. However, RetroArch also provides the freedom to configure specific emulators individually and even individual games differently if the user wants. This allows a specific setting or button mapping for a certain console or even just for a certain game.
For emulators which are not libretro cores, there are emulator-specific configurations under the respective system's wiki page.
The RetroPad concept
Play Columns (Neo Geo) Homebrew (Arcade) for free in your browser. Colors: 16 palettes per plane, 48 palettes. 146 colors on screen out of 4096. NEO GEO POCKET color mode, 20 colors out of 4096. Sprites: 64 sprites per frame, 4 colors per sprite. Scrolling: 2 scrolling planes, 8x8 character tiles, 4 colors each. Sound: PSG 6 tone simultaneous output. Since 4.0.2, Dolphin has the ability to passthrough USB HID devices designed for use with Wii software. 5.0-2352 enables USB passthrough for all devices. This gives emulated Wii software full control of a hardware device connected to your PC. SNK - Neo Geo CD emulators on Windows and other platforms, free SNK - Neo Geo CD emulator downloads, as well as savestates, hacks, cheats, utilities, and more.
When you configure your controller in EmulationStation, the RetroPie setup script automatically configures RetroArch with the same controls.
RetroArch controls map real-world controller buttons to a virtual controller called a 'RetroPad'. A RetroPad does not exist in real life, it's a concept only within RetroArch. A RetroPad has an ABXY layout like a SNES controller plus four shoulder buttons and dual analog sticks like a Sony DualShock.
You don't have to map all of the RetroPad buttons to a real world button. If your real controller has less buttons than a DualShock, then the virtual RetroPad also has less buttons, that's perfectly fine.
As RetroArch starts an emulator core, it maps the RetroPad configuration to the emulated system's original controls. The mapping for many consoles is represented by the pictures below and on each system's wiki page. If you wish, you can reconfigure this control mapping, either for all RetroArch, for a specific system, or even for a specific ROM.
Retroarch Controls
There are 3 main ways to configure input for RetroArch:
- Autoconfigurations - made in EmulationStation
- Hardcoded Configurations - made by editing
retroarch.cfgfile(s) - Core Input Remapping - an easy way to do specific control configurations for specific cores, made in the RetroArch RGUI
AutoConfigurations
RetroArch controls have been integrated into EmulationStation and will be the first thing you see when you boot from the RetroPie SD image the first time. You can also access it from the start menu within EmulationStation under the Configure Input option. Your joypad is automagically configured for libretro (RetroArch) emulators when you configure your controller in EmulationStation. You'll know if your controller has been automagically configured if you see a flash of yellow text on the bottom of the screen with your gamepad ID when you start a game.
The following diagrams are for the 3 most common controllers: Super Nintendo, Xbox 360, and PlayStation 3. They can be used as a reference when configuring your controllers. Each emulator page on the wiki has a diagram of the original controller for its respective console that will correspond to the same inputs listed below.
After you've configured your controller the autoconfig will be created here:
This is an example config for a USB SNES controller
As seen above in the config for the USB SNES controller, each input on the controller has an associated value. When setting up the controller in EmulationStation, these values are then assigned a respective action on RetroArch.
For example, suppose the 'A' button on a USB SNES controller has a value of '1.' When setting up the controller, EmulationStation would prompt you to press the 'A' button on your controller. Pressing the 'A' button would then record into the config file as input_a_btn = '1', so RetroArch will know that the 'A' button on your physical controller corresponds to the 'A' button on RetroArch's virtual controller, the RetroPad. Therefore, the next time you play a game such as Super Mario Bros. pressing the 'A' button will tell RetroArch to press the 'A' button on its RetroPad, causing Mario to jump. If you accidentally pressed the 'B' button with a value of '2' during setup when it prompted for 'A,' then it would be recorded into the config file as input_a_btn = '2', so if you want to jump in Super Mario Bros., you would have to press 'B' on your controller.
Hotkeys
Hotkeys are combinations of buttons you can press in order to access options such as saving, loading, and exiting games. The following defaults are set automatically the first time you set up your controller from EmulationStation (the numbers will vary depending the controller you use).
Default joypad hotkeys:
| Hotkeys | Action | Code Example |
|---|---|---|
| Select | Hotkey | input_enable_hotkey_btn = '6' |
| Select+Start | Exit | input_exit_emulator_btn = '7' |
| Select+Right Shoulder | Save | input_save_state_btn = '5' |
| Select+Left Shoulder | Load | input_load_state_btn = '4' |
| Select+Right | Input State Slot Increase | input_state_slot_increase_btn = 'h0right' |
| Select+Left | Input State Slot Decrease | input_state_slot_decrease_btn = 'h0left' |
| Select+X | RGUI Menu | input_menu_toggle_btn = '3' |
| Select+B | Reset | input_reset_btn = '0' |
Determining Button Values
If you want to edit the entries in the .cfg file for your controller, you will need to know the values corresponding to the buttons on your controller. Usually the relationship between the two can be deduced by looking at the file and noting the entries' names along with the values next to them, assuming that the values have not been jumbled from previous edits or been mixed up due to unknown issues. For example, the USB gamepad above has an entry for input_x_btn = '0', indicating that the 'X' button on the controller (or the button that you associated as 'X' during controller setup in EmulationStation) has a value of '0.'
On the other hand, maybe you are not sure if the values in the .cfg file is correct or the file is missing entries for buttons that are available on your own controller, such as a 'Home' button. You can run jstest (joystick test) in the terminal by selecting Quit EmulationStation (a keyboard will be required for the following steps).
In the terminal, type and enter jstest /dev/input/js0
Replace js0 with js1, js2, js3, etc. as needed if not detected.
A multitude of rows and columns should appear. Pressing buttons or moving analog sticks/joystick will cause various entries in the columns to swap between on and off and fluctuate through a range of numbers. The value next to an on/off entry corresponds to the button that you have pressed. The fluctuation of numbers from -32767 to 32767 correspond to the input on your controller that has a range of motion, such as analog sticks/triggers.
If you are interested in figuring out which is your 'Select' button, pressing and holding 'Select' on your controller will cause one column to switch from off to on. The value next to it corresponds to the 'Select' button. If you have a controller with a 'Home' button, pressing the 'Home' button will also cause one column to switch from off to on. To exit jstest, press Ctrl + c. To return to EmulationStation from the terminal, type and enter emulationstation.
Using these values, you can edit the .cfg file for that controller as needed. For example, if you were interested in switching the your Hotkey button to a 'Home' button available on your controller, you would edit input_enable_hotkey_btn = 'some number', replacing 'some number' with the value you found for your 'Home' button in jstest.
Video Tutorial
Hardcoded Configurations
These configurations are manual edits you can make that are locked to a specific libretro core and controller. Hardcoded controls can be configured either globally, specific to the emulator core, or specific to an individual game.
Config Hierarchy
All RetroArch based emulators can be configured in the following way:
Global settings - that are settings which should apply to all systems - are done in the file:
(example)
System-specific settings are done in the files:
(example)
Here, SYSTEMNAME is atari2600, snes, etc. All settings in these files will override the corresponding global setting as long as they are placed above the #includeconfig line.
ROM-specific settings can be created in the runcommand menu and show up as configuration files by ROM title:
(example)
The ROMNAME includes the original file extension before the .cfg, e.g. supermariobros.zip.cfg These configurations are used when starting this specific ROM.
Custom RetroArch Override Examples
Example Default Per-System retroarch.cfg
Example Per-System Control Override retroarch.cfg
Note the values below are for one person's controller, your values may differ. Make sure that these values are placed above the #includeconfig line:
Example Per-ROM Override retroarch.cfg
Core Input Remapping
Core Input Remapping differs from the other two methods as it remaps how the core receives input rather than how the gamepad is coded, for example you can tell the snes core to switch button A and B on the controller for gameplay, but you can still use 'A' to select in the RGUI and 'B' to go back where as hard-coding would make B select and A back. Core Remapping is much more practical than hard-coded mapping but is limited to the cores that support it.
- Start a game of the system you want to remap the buttons
- Invoke RGUI (Hotkey+X with player 1)
- Go to Quick Menu and then Controls
- Configure the buttons the way you want
- Select Save Core Remap File
- OR, if you want to save this remapping for the current game only, select Save Game Remap File
Remaps are saved as .rmp files in directory:
Retroarch Controls Cheat-Sheet
Video Tutorials
- Core input remapping: Remapping your controller by Floob
- Testing Joypad: Testing joystick by Floob
- Configuring USB Controllers With Retroarch, Controller not configured fix by Herb Fargus
- Configure a wireless PS3 controller with RetroPie 3 by Floob
- XBox 360 Wireless Controller Configuration by Herb Fargus