Ctrlr file

A ctrlr file is an additional method of changing Mame's inputs from the defaults, than the standard in-game UI method ("tab"). Like the standard method of changing inputs, ctrlr files can be used to change the inputs for all games or individual games, but unlike the standard method ctrlr can also change inputs for a parent and all it's clones, or for all games that share a driver in mame's source, or for all games that use the same bios. The official Mame binary comes with a few ctrlr files for a bunch of commercial control panels: hotrod, hotrodse, x-arcade, and slikstik.

However, its relative steep learning curve, limitations, format changes, and overlapping features with mame's standard input mapping method seem to have curbed the use of the ctrlr files.

Notes on nomenclature used in this page

Since this page is about changing inputs from mame's default values, referring to an input by which key or button to press can be wrong if it had been remapped to something else. Inputs will be referred to by the name shown in mame's in game UI instead of the key pressed. For example, the tab key is usually mapped to "Config Menu"; this input will be referred to as "Config Menu (usually tab)" instead of just the tab input. This is more technically correct and helps show every input in mame can be changed.

Why use Ctrlr file instead of the normal in game UI method?

The most common use of ctrlr files is probably with the commercial control panels: X-Arcade and HotRodSE for the most part. They have the seven button combination SF2 six button + NeoGeo four button layout, and Mame comes with ctrlr files specifically for these control panels. With these control panels and the matching ctrlr file, you do not need to do any remapping for most of the games in mame.

The most driving reason to make your own ctrlr file probably is also NeoGeo games and a control panel with a 7 button layout. The 7 button layout is a way to have the Street Fighter II 6 button rectangle physical layout & NeoGeo's 4 button in a (curved) line physical layout. However, to use the two different layouts, the buttons need to be reassigned depending on which game is being played. This can be done by making the changes once with the ctrlr file, or by making the changes many times (once for each NeoGeo game) with the standard method.

Other reasons include

• Mame rewrites the cfg files every time mame is run, while the ctrlr is not changed by mame ever. This prevents the ctrlr file from being accidentally changed.
• If you switch controllers that need different mapping, each controller can have it's own ctrlr file, and only change the -ctrlr option instead of remap every time you switch controllers.
• Ctrlr file has a slightly better record as being cross version compatible over the standard cfg files.
• Copying remaps within the ctrlr file to different games is much more reliable than it is with copying cfg files.

How to Use a Ctrlr file

It is easy to use an existing ctrlr file, such as those provided with mame or one you made your own. Currently, mameUI does not provide the ctrlr files included with the official mame, but you can download the vinalla mame binary and extract the ctrlr files to the mameUI ctrlr folder.

If the file is in the ctrlr subfolder, note the name (not including the ".cfg") of the ctrlr file you want to use, and edit mame.ini so "ctrlr ctrlrFileName". In mameUI, go into the defaut game properties, "Controllers" tab; the ctrlr files will be options in the "Default input layout" drop down list.

You can also put the ctrlr file in a different folder. Then you will also need to edit the ctrlrpath option to include the folder the ctrlr file is in. This can be used to share one ctrlr file between different versions of mame.

How to Create a Ctrlr file

There are a few ways to make ctrlr files. And since the ctrlr file format has changed a couple times, the methods have changed. The following sections will cover from mame 0.106 to current (0.128).

Basic Ctrlr file format

The ctrlr file is an XML file, and almost matches the cfg default.cfg file which mame uses to save the general input changes. A very simple example of a file that could either be a ctrlr file or the cfg default.cfg file:

<mameconfig version="10">
    <system name="default">
        <input>
            <port type="UI_LEFT">
                <newseq type="standard">
                    KEYCODE_LEFT OR KEYCODE_LCONTROL
                </newseq>
            </port>
           <port type="UI_RIGHT">
               <newseq type="standard">
                   KEYCODE_RIGHT OR KEYCODE_LALT
               </newseq>
           </port>
        </input>
    </system>

  <|-- ctrlr file only -->
    <system name="systemname">
        ....
    </system>
    ....
  <|-- end of ctrlr file only -->
</mameconfig>

As shown, there can be multiple port nodes within the input node. The only difference in format of the ctrlr file and the cfg default.cfg file is the ctrlr file can have multiple system nodes in the mameconfig node, while the cfg default.cfg file can only have one system node which has to be named "default". The additional system nodes can have the name of a specific game, a parent game, a bios name, a mame driver file name, or "default". The system name tells mame to which games to apply the changes within that system node.

FWIW, the example, if everything else is left at default, lets you press player1 button1 (usually LCtrl) then player1 button2 (usually LAlt) inaddition to "O" "K" or wiggling the joystick (left arrow then right arrow) assuming your control panel has p1b1 sending LCtrl, p1b2 sending LAtl, pl joy left sending left arrow, and p1 joy right sending right arrow.

Also see #Order Matters

Edit the Ctrlr files provided with mame

The easiest way to make your own ctrlr file might be by editing one of the ctrlr files supplied with mame binary (mameUI does not provide these ATM, but does have a sample ctrlr file). Editing a provided ctrlr file might be the way to go if you are changing the same inputs for the same games as already in the provided ctrlr file.

Remap and Test with the standard in game UI method and Convert to Ctrlr file

However, the most flexible way to make your own ctrlr file to match your own inputs is more in depth. You will need a text editor to edit the files, and will run mame many times. Since Order Matters it is best to start with mapping on the widest level and move down; start with the default (every game), than move to driver or bios wide changes, then to the driver's parent games, then to the parent's clone games.

Prep before starting

1. Delete (or move to a different folder for backup) cfg/default.cfg file and all game cfg files that you are going to put in the ctrlr file. (Alternative: remove all game specific remaps by either hand editing the cfg files or with mame's in-game UI, if you want to keep some of the other settings saved in the cfg files.)
2. If you have your OS to hide file type extensions, either disable that or ignore the ".cfg" in the following file names.

Start with general (every game) remapping

If you already have a ctrlr file and want to use it, skip to Add more systems.

1. Edit mame.ini so ctrlr is set to blank. <--- IMPORTANT
2. Start any game in mame.
3. Press Config Menu (usually tab) to start mame's in-game ui
4. Press UI Select (usually enter) "Input (general)"
5. Remap any and all inputs you want to be applied to all games, as normal.
6. Test remapping by playing the game. If you need to make any corrections, repeating from step #3.
7. Exit mame.
8. Move cfg/default.cfg to the ctrlr folder in mame.
9. Rename ctrlr/default.cfg to anything you want ctrlr/fillInNameHere.cfg
10. Edit mame.ini to point to whatever you named the file in the ctrlr folder (ctrlr fillInNameHere)
11. (If it still exists) delete cfg/default.cfg file.

Add more game specific systems

This is similar to, but not exactly the same, as the starting step. You can also start here if you started with a supplied mame ctrlr file and want to add a new system node (driver or game). Also look at #Shortcuts for other methods.

1. Edit mame.ini to point to your ctrlr file if you haven't already. <--- IMPORTANT
2. Decide if you want to remap on the driver, parent, or clone level. (Reminder, start with driver, then it's parents, then their clones.)
3. Find the name of the driver, parent or clone and note it down. Neogeo games bios is "neogeo"; to find the driver name for other games, "mame -ls gamename", or use MAWS or mame's listxml file.
4. Start that game (or a game in that driver). (You could start any game, but it's best to start the specific game for testing and reference to what input ports are used.)
5. Again, press Config Menu and select "Input (general)". <--- NOT "Input (this game)". You can look there to see what input ports are used by the game, but remap in the "Input (general)" location.
6. Again, remap any and all changes you want for this driver, parent or clone.
7. Test remapping. (make any needed corrections)
8. Exit mame.
9. Open cfg/default.cfg in a text editor.
10. Copy the whole system node, from (and including) <system name= to </system>.
11. Open your ctrlr file.
12. Paste the copied system node into the ctrlr file. If you have been working from the drivers down to the parents to the clone, you can paste as the last system, just before the closing </mameconfig>. If you have not been as careful on the order you're remapping, make sure you paste the new system node in a correct place read Order Matters.
13. Rename the system name to the driver, parent or clone you noted in step 2. Example if for neogeo, change to <system name="neogeo">.
14. Save (and exit) the ctrlr file.
15. Exit (without saving) the default cfg file.
16. Delete the cfg default.cfg file.
17. Test game(s) inputs.
18. Repeat as needed for all drivers/games you want to remap. Remember, if you remap a parent, you do not need to remap a clone unless you want the clone to be different (or the clone used different input ports).

Shortcuts

There are a few shortcuts that can be done in certain cases.

• If you have an input mapping that is common between games that do not share a parent or driver, you don't have to do all the steps for adding more systems for both games. For the second game, start at step #10 and rename to the new game. You can copy from within the ctrlr file itself, too.
• You can make other hand edits to the ctrlr file, as the XML is fairly human readable.

Limitations and their Workarounds

Games with "Hardcoded" Inputs

Some games remap an input port or two to inputs different than the default values. Even though these are much like other input ports and can be remapped with mame's in game UI menu, these are often called "hardcoded" as they are incorrectly thought as unable to be remappable through ctrlr files.

Games with hardcoded input, however, do need additional steps to use the ctrlr set inputs instead of the "hardcoded" values. You have to go into each of the offending game's cfg file and reset the "hardcoded" input ports to not use the hardcoded values. This is easiest done with mame's in game UI "Inputs (this game)". Note: There is a bug starting from 0.126 to current (0.128) that needs more steps, including hand editing the cfg files.

1. Start the game with hardcoded inputs you don't want to use.
2. Press Config Menu (usually tab) to enter mame's in game UI.
3. Select "Input (this game)", by pressing UI Select (usually enter).
4. Select the hardcoded input port you want to change (it will be reverse highlighted).
5. Press UI Cancel (usually esc).
6. Wait until mame shows "None". If mame 0.126 or later, skip to step 9 and see the extra steps.
7. Select, then UI Cancel, again.
8. Wait until mame shows the setting by the ctrlr file (it will not be reverse highlighted).
9. Repeat steps 4-8 for all hardcoded input ports that you want to use the ctrlr file.
10. Repeat steps 1-9 for the games with hardcoded input ports that you want to use the ctrlr file.

Extra Steps

1. Exit mame
2. Open the cfg files you just changed in a text editor.
3. Replace all "NONE" with "DEFAULT"
4. Save the files

The problem with these work arounds is you need to edit cfg files, while one of the main reasons to use a ctrlr file is to avoid doing this.

Other ways around the "hardcoded" hassle, including editing the source and recompiling, will not be described here.

Order Matters

Mame does not exactly enforce a specific order to the different system nodes within the ctrlr files. However the order does make a difference in the final mapping if different systems that are applied to a game with the same port type(s) differently in different system nodes that apply to the game. Mame reads the ctrlr file from top to bottom, and checks if each system node should be applied to the game, and applies the changes in the order the systems are in the ctrlr file overriding any mapping for all ports changed.

So to make sure all changes are correctly applied, (referred hereafter as the ctrlr rules of order):

• Clones should come after their parent,
• Parents (and clones) should come after their driver and bios, and
• Drivers and Bios (and parents & clones) should come after "default" system,

*Usually bios and drivers can be thought of as the "same level", as usually if a bios exists there is one and only one driver that has all games with that bios and only those games, but theoretically a bios can be across multiple drivers or a driver can hold bios and non-bios games.

Keeping the order can be done a couple ways, or a mix of them. The easiest rule is: default, then all drivers/bios, then all parents, then all clones. However this separates the clones from their parents and the parents from their drivers. It might be easier to upkeep if all of the parents come immediately after their driver, and all clones immediately after their parents. But neither these have to be exactly followed, as long as the ctrlr rules of order are followed.

Valid examples:

default->drivers->parents->clones	grouped by driver, parent, clone	"disorganized order"
default driver driverAAA driver driverBBB parent Aaa1 parent Bbb1 parent Bbb2 clone Aaa1c1 clone Bbb1c1 clone Bbb2c1 clone Ccc	default driver driverAAA parent Aaa1 clone Aaa1c1 driver driverBBB parent Bbb1 clone Bbb1c1 parent Bbb2 clone Bbb2c1 clone Ccc	default clone Ccc driver driverAAA parent Aaa1 driver driverBBB parent Bbb2 parent Bbb1 clone Bbb1c1 clone Aaa1c1 clone Bbb2c1

Ctrlr file does not do ...

You cannot use the Ctrlr file to:

• Set analog sensitivity, digital speed, center speed. - These are set in mame's in game UI "Analog Controls", and saved in the cfg files.
• Change volume, CPU speed or other On Screen Display (usually tilde unless remapped) settings

My ctrlr worked but doesn't anymore

The cause could be some minor error to something bigger.

• Check that the ctrlr file still exists in the right location, and is not corrupt.
• If you updated mame, check if mame.ini points at your ctrlr file.
• If you just edited the ctrlr file, check if the system nodes are in the correct order.
• Make sure no one remapped using mame's in-game UI (the normal remapping method). If you know everything you want remapped is in the ctrlr, you could delete everything in the cfg folder (warning: the game specific cfg files hold more than just input remaps).
• Mame might have changed the ctrlr and/or cfg file format. This might be able to be fixed with a simple find and replace, or in the worst case you might need to completely redo making the ctrlr file depending on what changed.

History of Ctrlr files

The ctrlr files inspiration came from the need to remove the hardcoding of special input maps for specific commercial arcade control panels from mame's source, but was designed to do more than be just a replacement. It has had two major revisions and many minor. It started in a different format with .ini file endings. When mame changed the cfg file format to xml, the old format was dropped, and a couple versions later, a new xml based ctrlr was re-added.

Technical Stuff

Some technical information

Differences between Ctrlr file and Cfg files

The ctrlr file and the default.cfg file only save input remaps. The game specific cfg file saves much more than just input remaps, including: analog settings, input location in the driver, dipswitch settings, sound and video settings, and other info.