Custom Controller Configuration

Controller configuration is specified in configuration files bundled with FS-UAE. The folder share/input/ contains the bundled configuration files. There is one .ini file per controller type.

FS-UAE Launcher comes with a joystick / gamepad configuration tool (started from the settings dialog). This tool will create configuration files for you and it is highly recommended.

Custom configurations can be placed in the directory:

(My) Documents/FS-UAE/Controllers/

The name of the ini file is the system name of the controller, converted to lowercase, with an underscore between each work. Characters other than letters and numbers are also converted to underscore, and there is never more than one underscore between each word, and the name will not start nor end with underscore.

Example: Controller (Xbox 360 Wireless Receiver For Windows) becomes


This forum thread has some more information:

Universal configuration file (recommended)

If you have a general-purpose gamepad with button layout more or less like PlayStation/Xbox controllers (e.g. a hat, two analog sticks, 4 buttons to the right, start/select and shoulder/trigger buttons), you can create a config which maps the controller events to generic event names (which again is automatically mapped against amiga input events). In this way, the same configuration can be shared with other emulators using the same configuration file format without having to create an explicit configuration for amiga, super nintendo, c64, and so on.

Here is a complete example for this kind of configuration file:

include = common/gamepad
axis_0_neg = lstick_left
axis_0_pos = lstick_right
axis_1_neg = lstick_up
axis_1_pos = lstick_down
axis_2_neg = rstick_left
axis_2_pos = rstick_right
axis_3_neg = rstick_up
axis_3_pos = rstick_down
button_0 = west_button
button_1 = south_button
button_2 = east_button
button_3 = north_button
button_4 = left_shoulder
button_5 = right_shoulder
button_6 = left_trigger
button_7 = right_trigger
button_8 = select_button
button_9 = start_button
button_10 = lstick_button
button_11 = rstick_button
button_12 = menu_button
hat_0_left = dpad_left
hat_0_right = dpad_right
hat_0_up = dpad_up
hat_0_down = dpad_down

What you must to is to check (with a joystick test application) what button number each physical button on your gamepad has, and update the configuration accordingly.

Example: If you test a button labelled  “start” on your controller, and you want to map this to the generic event “start_button”, you press “start” in a joystick tester program. Let’s say the program indicates that this is button 5! In the config file, the first button is numbered 0, so if the joystick test program calls the first button “1”, you must subtract one from the number, and you get:

button_5 = start_button

This line is important to include:

include = common/gamepad

– since this imports the common gamepad configuration file which maps the generic button names to Amiga joysticks.

Additional information

Axes on your controller are identified as axis_x_neg/axis_x_pos where x is the zero-based index (the first axis is 0). Hat events are referred to with hat_x_left, hat_x_right, hat_x_up and hat_x_down (x is hat number – the first hat is 0). Button events are simply button_x (where button_0 is the first button on the controller).

Also, remember to check the log file to see whats going on when FS-UAE starts. You will probably get some hints to what’s wrong if it does not work.

If you create a configuration file to support your controller, I would very much like a copy of this file to include with FS-UAE in future releases.

Amiga-specific configuration file

If you have a controllers which looks nothing like a “standard” gamepad, if can be better to create a specific configuration file and map the Amiga joystick events directly.

If you created a universal configuration you do not have to add [menu] or [amiga] sections.

The ini file should contain a section [amiga] with a mapping between controller events and amiga joystick events. You should also create a [menu] section where you provide mapping for the menu navigation (if you want to navigate the menu).

Here is an example for a joystick with one stick and 4 buttons:

axis_0_neg = left
axis_0_pos = right
axis_1_neg = up
axis_1_pos = down
button_0 = primary
button_1 = back
button_2 = select
button_3 = start

axis_0_neg = left
axis_0_pos = right
axis_1_neg = up
axis_1_pos = down
button_0 = 1
button_1 = 2
button_2 = 3

Amiga events are named left, right, up, 1 (fire), 2 (secondary fire) and 3 (tertirary fire). (see common/gamepad.ini for Amiga CD32 controller mapping).

103 thoughts on “Custom Controller Configuration

  1. hi there.

    within the launcher, i have set up a archon to use two joysticks (the database has it set to joystick and mouse). i start the game but it has switched back to joystick / mouse.

    i can hit f12 to bring up the side bar menu and make my changes there again to two joysticks and everything works fine. but it doesn’t seem to save the changes i made. back to square one when i restart.

    anyway to save the controller change? thanks!

    • Hi, when using the automatic database entries, there is no local save function for customizing it yet. It is possible to submit fixes to though.

      I’ve already fixed the Archon game entry to always use two joysticks (joystick_port_0_mode = joystick) 🙂

        • thanks man, i’ll give it a try.

          i did run the updates yesterday and i lost the list of games over to the left and i freaked out! i was able to select restore to default to bring the list back and realized i don’t have any of the official games downloaded.

          i run launch box and point to my amiga rom folder.

          tonight i’ll try dumping all those roms into the correct fsuae folder and see if they get recognized

  2. Hi. I have a 8BitDO SFC30 gamepad.

    I want to map the controller so that the pause-function is triggered when I press the right shoulder button. (I mean the pause that is triggered when you press Alt + P on the keyboard.) In the path “/home/pi/Documents/FS-UAE/Controllers/” I have found a file belonging to my controller. It has the name “8bitdo_sfc30_gamepad_16_6_1_0_linux.conf”.

    When I open this file there is a section [default] with several entries. The one that I was looking for is:

    button_7 = right_shoulder

    So I replaced “right_shoulder” with “action_pause” but it doesn’t work.
    I also tried adding “right_shoulder = action_pause” to the end of the file but this also doesn’t work.

    Please can you help me. Which file do I have to edit anyway? Can you tell me the exact path and file name. And what exactly do I have to add for my concern?

    • Hi, the config file you found is for describing the layout of the controller and you cannot assign arbitrary actions there.

      But you can add something like this to advanced settings in FS-UAE Launcher:
      joystick_0_right_shoulder = action_pause
      joystick_1_right_shoulder = action_pause

      The advantage of FS-UAE handling it this way, is that your preference will also work if you use another controller 🙂

      • I have added

        8bitdo_sfc30_gamepad_button_7 = action_pause

        to the big textbox in the advanced settings of the launcher. This works.
        But the way you described it is clearly better because it works with other controllers, too.

        Thank you very much for your help.

  3. Hi,

    I’m using FS-UAE in Ubuntu 18.04 LTS, it works great but my generic retro snes gamepad doesn’t show up as an USB device. I have tried following this article, added .ini-file in the controller folder (both in documents/FS-UAE/controllers and in snap/FS-UAE/Common/controllers/), made a copy of .ini for this type of controllers, but with no luck. In other threads I only find fixes for window users. The USB does simply not show up as a detectable device in the launcher. It works fine with Retropie that I also have installed on the same computer.

    Any help would be much appreciated.


    • Hi, you are using an unofficial (snap) version of FS-UAE. Other people have reported issue with this and controllers. Please uninstall the version you are using now, and install the official Ubuntu version from instead. I’m quite sure that will fix the problem!

  4. Hi,
    First, thanks for a great emulator!

    I’ve been struggling with getting my gamepad to trigger a certain key in a game. For some strange reason I can’t trigger the key “?” in a game.

    The custom configuration that is added are:
    joystick_0_left_shoulder = action_key_question
    joystick_0_right_shoulder = action_key_space

    I tested that both shoulder actually works by adding another key instead of “action_key_question” like _key_a etc. and that works fine. What could be wrong?
    The actual key I’m hitting on my os x keyboard to produce a “?” on Amiga is shift + “-” which is underscore on my keyboard, I also tried it in settings (action_key_underscore) but
    still no “?”.

    Any help appreciated, thanks!

    • Hi, you can see the available actions here: (action_key_question isn’t one of them). The available actions correspond to physical Amiga keys, and not symbols, and as you discovered, “?” isn’t really a key on the Amiga, but a combination of two keys. You can unfortunately not map two actions to the same joystick buttons, so if you want to be able to “type ?” via the gamepad, then you need to map one buttons to Amiga shift (action_key_shift_left), and the other to action_key_div (the “slash” button on Amiga US keyboards) and then press both joystick buttons at the same time.

      • ok, I mixed things up when reading about the keyboard events where keyboard_key_question exists, sorry about that.

        It finally worked out but I had to address my controller directly by the device name rather than using joystick_0_left_shoulder as they also was mapped
        to other default actions, removing the entries in controller config for the buttons needed and using events like playstation_r_3_controller_button_11 mapped to
        needed actions worked fantastic.

        Thanks for your help!


  5. Hi. I’m trying to set up the Speed-link competition pro so that button 3/Y is autofire rather than pause which is its current (annoying) function.

    tried the following lines in advanced settings but no luck, what am i missing?

    SPEED LINK Competition Pro_button_3 = action_joy_1_autofire_button
    joystick_button_3 = action_joy_1_autofire_button
    joystick_button_y = action_joy_1_autofire_button

    • Hi, you can try: speed_link_competition_pro_button_3 = action_joy_1_autofire_button (the joystick name is normalize by lowercasing it and collapsing spaces into underscore). You can also refer to the first device on the system with joystick_0_button_3 = action_joy_1_autofire_button. Notice the insertion of _0. Hope this works for you 🙂

  6. Hello,

    Trying to bind del key of amiga keyboard to button of xbox one gamepad.
    I tried this “button_4 = action_key_del” but it isnt working.
    For example “button_4 = 1” is successfully binding fire to buttton 4 of gamepad.
    Should i activate keyboard emulating or something?

    • Hi, in the controller config, you cannot generally use the “actions”, you can only use the controller config to map to joystick events for the ports, as well as a few special actions (such as menu). Being able to specify any action would indeed by use, but it isn’t possible right now.

      You can sort of make it work by using advanced settings in FS-UAE Launcher / config file in FS-UAE, for example:
      joystick_0_button_4 = action_key_del should work, if your xbox one gamepad is the first in the list of recognized joysticks on your system.

      • Finally make it work. I set first port for joystick and xbox controller and second port for PAD32 and Mac OS keyboard.

  7. Hi

    First up great emulator and I’m enjoying playing some of the old Amiga games I had and many that I bought from Amiga Forever..

    One issue I am having is with my wired xbox 360 controllers. They are not recognised by FS-UAE.

    I’ve booted the emulator up 4 times now and I only once have they worked. The joysticks are always plugged into the computer and directly into USBs, that is no USB hubs. Any help greatly appreciated

  8. Hi there,

    I figured it out by trial-and-error:
    For the PS1 Gamepad I had to enter the following into the advanced settings of the FS-UAE Launcher. The Arcade mode were taking then the right settings as well!
    hid_6666_0667_button_0 = action_joy_1_fire_button
    hid_6666_0667_button_1 = action_key_space
    hid_6666_0667_button_2 = action_joy_1_up
    hid_6666_0667_button_3 = action_joy_1_autofire_button

    And this one for the Competition Pro USB version:
    mosic_usb_2a4k_gamepad_button_0 = action_joy_1_autofire_button
    mosic_usb_2a4k_gamepad_button_1 = action_key_space
    mosic_usb_2a4k_gamepad_button_2 = action_joy_1_fire_button

  9. Hi there,

    I started now with a Gamepad configuration for Turrican II. Normally I would need these functions on the PS1-Gamepad: Fire, autofire and Space. Fire is no problem (north and south button have the same function here), but is it possible to create also a button with autofire instead of switching it on and of via the F12-menu?

    • hey Cmd.Keen, sorry for the late reply.. just happened to be browsing through this..

      the actions you need to set the mappings to are these:

      if you are using it as a CD32 use:
      joystick_port_1_mode=cd32 gamepad

      and map any of these inputs to the action you need

      if you are using it as a simple joystick (3 buttons max) use:

      and map any of these inputs to the action you need:

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.