Adding a controller

Adding a controller

Any USB controller that shows up as a gamepad can be used. This page covers three levels, from "just make it work" to "ship it for everyone".

Controllers in the front ports can't be added this way: the console treats all of them as the same controller, and they only have the one shared mapping.

1. Make it work on your console

1. Plug the controller in, with the front controller already connected if you use one (see Using the remapper).
2. Open Gamepad Remapping and pick the controller on the first row. It is listed by the name it reports, for example FightStick.
3. Select Map all buttons and press each button when asked. Wait 5 seconds to skip one.
4. Select Save. It applies to the next game you start.

The mapping is kept in /etc/options_menu/inputs/pads/<vendor>_<product>.map (see Files and mapping format). Buttons without a name yet show up as Button 305, Axis 2 and so on.

If the controller isn't listed, check that the console sees it:

cat /proc/bus/input/devices

Look for an entry with Bus=0003 (USB) and an event number on its Handlers line.

2. Give it a ready-made profile

A profile is the same file, shipped with the add-on, so everyone with that controller gets it without mapping anything.

1. Map the controller as above and save.
2. Copy /etc/options_menu/inputs/pads/<vendor>_<product>.map to mod/etc/options_menu/inputs/profiles/ in the add-on's source, with the same name.
3. Build (./build.sh, needs Docker) and install the .hmod to try it. Delete your own file in pads/ first, otherwise it hides the profile.

3. Give its buttons names

Names come from a small table per controller model in src/pad_profiles.cpp. Without one, buttons show as Button 305.

1. Add a function that maps each event code to the name printed on the controller:

   const std::map<int, Name> & MyPadKeys()
   {
       static const std::map<int, Name> names = {
           { 304, { "Square", false } }, { 305, { "Cross", false } },
           // ...one entry per button
       };
       return names;
   }

   The codes are the numbers after k in the mapping file. The second field is true only for a name that comes from the language files.

2. Add one line to the models[] list in FindModel: vendor, product, the key names, the axis names, and whether the D-pad is analog.

   { 0x0e6f, 0x0180, MyPadKeys(), DualShock4Axes(), false },

   Reuse an existing axis table (DualShock4Axes(), Xbox360Axes()) if the sticks are laid out the same way. If the D-pad arrives as the first two axes instead of a hat, like on the PlayStation Classic controller, set the last field to true.

3. Build, install and open the remapper: the buttons should now show the new names.

What to check before sharing it

• Every button does what its name says, in a game and in the Home menu.
• The controller plays as the player you expect (player 2 with a controller in port 1, player 1 when it is empty).
• The Home combo works (Down+Select, or the controller's own Home button).
• The names match what is printed on the controller. If it prints two sets of labels, like the Krom Kumite, write both.

Send a pull request on the add-on's repository with the .map and the table, and say which controller and mode you tested (some controllers change their USB ID with a switch).