> For the complete documentation index, see [llms.txt](https://wiki.retrobat.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.retrobat.org/controllers/controller-configuration.md).

# Controllers Configuration

RetroBat configures your controllers in two steps:

1. **In RetroBat (EmulationStation)**: your controller is recognised and its buttons are known. This is done once per controller model.
2. **At each game launch (autoconfiguration)**: RetroBat writes the configuration of your controllers in the emulator, so that you can play without configuring each emulator.

For most branded controllers (Xbox, PlayStation, Switch Pro, 8BitDo…), there is nothing to do: both steps are automatic.

## Configuring a controller in RetroBat

Known controllers are configured automatically. To configure a controller that is not recognised, or to change its configuration, go to **MAIN MENU > CONTROLLER SETTINGS > CONTROLLER MAPPING**, then **hold a button** of the controller to configure:

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2F58Q0dRRjpmaeihgamgN7%2Fimage.png?alt=media&amp;token=aeb96c23-6455-4ab9-8389-f57c6070bfeb" alt=""><figcaption></figcaption></figure></div>

The configuration screen asks for each input, one after the other:

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2F76iaWAud2Jg45fSGOT0O%2Fimage.png?alt=media&amp;token=f843ad2f-a649-4524-a6c2-646a53a58a48" alt=""><figcaption></figcaption></figure></div>

* **Map the buttons by their position**, not by their label: SOUTH is the bottom face button, EAST the right one, and so on (see the table below).
* **Skip** an input your controller does not have by **holding any button** for one second.
* Required inputs: **SOUTH**, **EAST**, the **D-pad** (if your controller has one) and **HOTKEY**. If your controller has no dedicated button for HOTKEY, use **SELECT**.
* At the end, press **SOUTH** to confirm.

| RetroBat input                                                                                                                                                                                                           | Xbox                                                                                                                                                                                                                            | PlayStation                           | Nintendo                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------- |
| SOUTH ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FDXNbFF9y0Devmoz9XPwo%2Fimage.png?alt=media\&token=43ffb192-3513-4863-bb27-d5cb4fd513c1) | A                                                                                                                                                                                                                               | ✕ (Cross)                             | B                         |
| EAST ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2F9QIyF03xS8UbyrwJLrrM%2Fimage.png?alt=media\&token=b0a1e94e-8929-448c-acc7-f02c26c259ff)  | B                                                                                                                                                                                                                               | ○ (Circle)                            | A                         |
| NORTH ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FkRYtJVFaRIlGqn8vsTma%2Fimage.png?alt=media\&token=41b5b261-ad7f-415c-9189-6d5c25653c53) | Y                                                                                                                                                                                                                               | △ (Triangle)                          | X                         |
| WEST ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FYgXgld9Yt8oMWZ6FTO07%2Fimage.png?alt=media\&token=9e21d6e6-afa0-4f31-a4b7-a22143d62c7e)  | X                                                                                                                                                                                                                               | □ (Square)                            | Y                         |
| START                                                                                                                                                                                                                    | Menu ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2Fw7q0AqhQfWDBPYICzHYo%2Fimage.png?alt=media\&token=4adb2fde-7db5-43ee-b784-d242dd49bd93) / Start | Options                               | +                         |
| SELECT                                                                                                                                                                                                                   | View ![](https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2Fo1Mwjjph1BOgF0Cy66B9%2Fimage.png?alt=media\&token=cd1c9bb7-9241-49db-a242-dd1822116c01) / Back  | Share / Create                        | −                         |
| D-PAD                                                                                                                                                                                                                    | D-pad                                                                                                                                                                                                                           | D-pad                                 | D-pad                     |
| LEFT SHOULDER / RIGHT SHOULDER                                                                                                                                                                                           | LB / RB                                                                                                                                                                                                                         | L1 / R1                               | L / R                     |
| LEFT TRIGGER / RIGHT TRIGGER                                                                                                                                                                                             | LT / RT                                                                                                                                                                                                                         | L2 / R2                               | ZL / ZR                   |
| LEFT ANALOG / RIGHT ANALOG                                                                                                                                                                                               | Left / right stick                                                                                                                                                                                                              | Left / right stick                    | Left / right stick        |
| LEFT STICK PRESS / RIGHT STICK PRESS                                                                                                                                                                                     | Left / right stick click (L3 / R3)                                                                                                                                                                                              | L3 / R3                               | Left / right stick click  |
| HOTKEY                                                                                                                                                                                                                   | SELECT (View), or a dedicated button                                                                                                                                                                                            | SELECT (Share), or a dedicated button | − , or a dedicated button |

The configuration is saved for this controller model in `emulationstation\.emulationstation\es_input.cfg`.

### Player order

The order of the controllers (player 1, player 2…) is set in **MAIN MENU > CONTROLLER SETTINGS > CONTROLLERS PRIORITY**, with **P1'S CONTROLLER**, **P2'S CONTROLLER**…

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FQcgZVuVnWootodUJanDu%2Fimage.png?alt=media&amp;token=e0e80a68-e2e1-493b-9925-a5aff74ed2be" alt=""><figcaption></figcaption></figure></div>

## Autoconfiguration in the emulators

At each game launch, RetroBat writes the configuration of the connected controllers in the emulator (RetroArch and most standalone emulators): buttons, hotkeys, player order.

{% hint style="warning" %}
While autoconfiguration is enabled, the controller configuration of the emulator is **rewritten at each launch**: a mapping you make by hand in the emulator is lost at the next launch. To keep your own configuration, disable autoconfiguration (see below).
{% endhint %}

### Disabling autoconfiguration

Autoconfiguration can be disabled globally, for a system or for a game, with the **AUTOCONFIGURE CONTROLLERS** option:

* **Globally**: **MAIN MENU > GAME SETTINGS > AUTOCONFIGURE CONTROLLERS**: **OFF**.

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FMCfJRgqqKEH85bbcshFB%2Fimage.png?alt=media&amp;token=f4016afd-bb80-4e7e-afff-0969ef7c6f74" alt=""><figcaption></figcaption></figure></div>

* **For a system**: open the [View Options](/navigation/view-options.md) of the system, **ADVANCED SYSTEM OPTIONS > AUTOCONFIGURE CONTROLLERS**: **OFF**.

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FqxNwtptARhL2puNfC0Kj%2Fimage.png?alt=media&amp;token=c7d618a9-6196-4862-bda2-9fd9d7e8a239" alt=""><figcaption></figcaption></figure></div>

* **For a game**: open the [Game Options](/navigation/game-options.md), **ADVANCED GAME OPTIONS > AUTOCONFIGURE CONTROLLERS**: **OFF**.

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2F9VIM65A0ElVjXBwTm3mS%2Fimage.png?alt=media&amp;token=b6daeb17-5bc8-4c33-b5b7-6907e402f52c" alt=""><figcaption></figcaption></figure></div>

Set **AUTOCONFIGURE CONTROLLERS** to **OFF**

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2F9WNUOixsP7cj9DdvsMYD%2Fimage.png?alt=media&amp;token=a085687b-7756-453c-aa98-a2750c999dff" alt=""><figcaption></figcaption></figure></div>

Then configure your controllers **directly in the emulator**:

* the standalone emulators can be opened from the **RETROBAT** system in the System View;
* in RetroArch, open the menu during the game (**HOTKEY + SOUTH** or **F1**) and go to **Controls**.

{% hint style="warning" %}
**Lightguns**: disabling **AUTOCONFIGURE CONTROLLERS** does not stop RetroBat from configuring the guns. To keep your own gun configuration, also set **ENABLE GUN** (advanced options > **GUNS**) to **OFF** for the same system or game.
{% endhint %}

## Adapting the controls without disabling autoconfiguration

RetroBat offers several ways to adapt the controls while keeping autoconfiguration:

<table><thead><tr><th width="264.5">Need</th><th width="264.5">Solution</th><th>Page</th></tr></thead><tbody><tr><td>Change a hotkey</td><td>Hotkey files <code>kb_hotkeys.yml</code> / <code>controller_hotkeys.yml</code></td><td><a href="/navigation/hotkeys.md">Hotkeys</a></td></tr><tr><td>Play arcade games with an arcade stick</td><td><strong>CONTROLLER LAYOUT</strong> option</td><td><a href="/controllers/supported-controllers/arcade-sticks.md">Arcade Sticks</a></td></tr><tr><td>Choose another button layout for a console</td><td>Layout options of the system (e.g. Saturn <strong>BUTTON LAYOUT</strong>)</td><td>Page of the system in <a href="/systems-and-emulators/supported-game-systems.md">Supported Game Systems</a></td></tr><tr><td>Change the mapping of a game or a core</td><td>Mapping files in <code>user\inputmapping</code></td><td><a href="/controllers/specific_mapping.md">Emulator specific controls mapping</a>, <a href="/systems-and-emulators/arcade-guide.md">Arcade Guide</a></td></tr><tr><td>Use an N64, Genesis, Saturn, GameCube controller or adapter</td><td>Special controllers</td><td><a href="/controllers/supported-controllers/gamepads/special-controllers.md">Special controllers</a></td></tr><tr><td>Play computer games with a controller</td><td>PadToKey</td><td><a href="/controllers/supported-controllers/keyboard.md">Keyboard</a></td></tr></tbody></table>

### How a mapping file works: two examples

#### Flycast (standalone)

The `flycast_Arcade.yml` file contains the mapping of many Naomi, Naomi 2 and Atomiswave games. Each block is a game (arcade games always have the same rom name, so the mapping is always applied):

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2Fy2edpnMHWqk7WrsPGEG0%2Fimage.png?alt=media&amp;token=bf85f0a3-72c8-453a-bd66-03e7616ffa0b" alt=""><figcaption></figcaption></figure></div>

For example, `l2: btn_trigger_left` means that the left trigger of your controller is assigned to the `btn_trigger_left` input of Flycast. RetroBat converts L2 into what your controller actually uses (axis or button):

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FUYy4K9J4jQNkzAB5y5Ft%2Fimage.png?alt=media&amp;token=e4d86acf-23a2-41b1-8c02-f5d5098f325a" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FaEfmX4vKIu0erKISVHy9%2Fimage.png?alt=media&amp;token=5c1fdf1c-b513-478e-929a-4d3e091752e9" alt=""><figcaption></figcaption></figure></div>

#### RetroArch (Flycast core)

The `libretro_flycast_naomi.yml` file contains, for each Naomi game, the remapping of the RetroArch RetroPad buttons to the inputs of the core:

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FDclZ8jTg3jSMpcnqB9UX%2Fimage.png?alt=media&amp;token=e17edead-7f2b-4556-89d5-93ad107fb09f" alt=""><figcaption></figcaption></figure></div>

For example, `btn_b: 4` means that the SOUTH button of the RetroPad sends the input with ID 4 of the core (here, DRIVE GEAR):

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FtNsBU3qghmYqzyWuBvT7%2Fimage.png?alt=media&amp;token=36dd4bc1-02cc-4d2b-9d11-7ff609dbb045" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://990680527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FexdzL60ZuqPLldz2AYta%2Fuploads%2FIoIyYylcJpey64n6PhoN%2Fimage.png?alt=media&amp;token=79efb5be-9e97-482e-9dab-97ad0dfbbc43" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For RetroArch, these files do not change the mapping between your controller and the RetroPad: RetroBat creates a **core remap file** in `emulators\retroarch\config\remaps\<core name>`.
{% endhint %}

## Fixing controller issues

1. **Map your controller again** in **CONTROLLER SETTINGS > CONTROLLER MAPPING**, by position.
2. **Check the player order** in **CONTROLLERS PRIORITY**.
3. **Check that AUTOCONFIGURE CONTROLLERS is not set to OFF** (globally, for the system or for the game).
4. Launch the game and open `emulationstation\emulatorLauncher.log`: it shows the controllers detected and the configuration written.
5. If it still does not work, disable autoconfiguration, configure the controller directly in the emulator, and save the configuration file it creates.
6. Contact the RetroBat team (Discord or GitHub) with `es_input.cfg`, `emulatorLauncher.log` and the emulator configuration files from steps 4 and 5.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.retrobat.org/controllers/controller-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.