                 Controller-Specific Input Port Mappings
                 ---------------------------------------

The main purpose of the controller-specific .ini files is to remap the
inputs.  This is handled via two mechanisms: key re-mapping and 
sequence re-mapping.

Key re-mapping occurs at the most basic level.  The specified keycode is
replaced where ever it occurs (in all sequences) with the specified 
replacement.  Only single keycodes can be used as a replacement (that is, a 
single key cannot be replaced with a key sequence).

Sequence mapping occurs at a higher level.  In this case, the entire
key sequence for the given input is replaced with the specified key
sequence.

Keycodes are specified as a single keyword.  Key sequences are specified
as a series of keycodes separated by spaces (the full sequence must be
enclosed in quotes if spaces exist).  Two special keywords are available
for defining key sequences, CODE_OR and CODE_NOT (which can abbreviated | 
and ! respectively).

When two keycodes are specified together (separated by only whitespace),
the default action is a logical AND, such that both keys must be pressed
at the same time for the action to occur.  Often it desired that either
key can be pressed for the action to occur (for example LEFT CTRL and 
Joystick Button 0), in which case the two keycodes need to be separated
by a CODE_OR (|) keyword.  Finally, certain combinations may be 
undesirable and warrant no action by MAME.  For these, the keywords should
be specified by a CODE_NOT (!) (for example, ALT-TAB on a windows machine).

Lines can be copied from this file to create a controller customization file.
When creating a file, keep the number of redefinitions to a minimum.
Any input not listed will default to the standard sequence.  Note that several
files may be parsed for any given controller/game combination, so an input may
be re-defined in multiple places.

For support of controller input customization, two new command-line
options were added:

-ctrlr_directory "name"

Specifies the directory that contains the controller customization .ini files.

-ctrlr "name"

Specifies a controller name for customization.  The .ini files for the 
controller are stored in either a directory or a .zip file with the same
name as the specified controller.  

The first file in the directory/zip to be scanned is the file default.ini.
From there, game-specific files are scanned starting with the top-most
parent file and continuing down to the specified game name.

Once the default.ini and all game-specific files are scanned, additional
files may be scanned depending on the game type.  The files to be scanned
are specified by the following custom keywords:

dial_ini                "name"
trackball_ini           "name"

Each of these keywords specify the name of an .ini file that will be
parsed if the game has one of these types of inputs.  For example,
Tempest, which  has a dial input, will automatically parse the file
specified by the dial_ini keyword.  Typically, all of the x_ini keywords
will point to the same file (e.g. mouse.ini) which enables mouse and/or
joystick support.  In this way, mouse and joystick support will only be
enabled on those games that require it.  If all games for this controller
require joystick and/or mouse support, those keywords can be placed in
the main default.ini file.

All of the options that can be specified on the command-line or in the 
main mame.ini file can be specified in the controller-specific ini files, 
though because of when these files are parsed, the specified options may 
have no effect.  The only two general options guaranteed to be supported
are mouse and joystick.  Note that command-line specification of these
options takes precedence.  Since most front-ends, including MAME32, 
specify these options through the command-line, the mouse and/or joystick
options specified in the .ini files will be ignored.

Another custom keyword is:

ctrlrname               "name"

This keyword defines a detailed name for the selected controller.  Names 
that include spaces must be enclosed in quotes.


Keywords:
---------

Keywords are separated into two categories, keycodes and input port
definitions.  To specify a key re-mapping, specify the keycode as the
keyword to re-define (that is, on the left-hand side) followed by the 
replacement code.  To specify a sequence re-map, specify the input port 
code to be re-defined on the left followed by the sequence.

In addition to the standard codes, additional OSD specific codes may be
generated.  The keycodes added are typically generated based on connected
hardware.  For example, in the windows port, direct input is polled to
determine what inputs are available and assign names.

With respect to the windows port, the generated keycodes are identical
to those displayed in the configuration menu with all spaces replaced by
underscores.  For example, the keycodes automatically generated for a
Wingman Warrior joystick are:

J1_X-axis_+        J1_X-axis_-        J1_Y-axis_+        J1_Y-axis_-
J1_Z-axis_+        J1_Z-axis_-        J1_Rz-axis_+       J1_Rz-axis_-
J1_Button_0        J1_Button_1        J1_Button_2        J1_Button_3
J1_POV_0_U         J1_POV_0_D         J1_POV_0_L         J1_POV_0_R

The names generated will vary with the port to which the joystick is
connected.  In the codes listed above, the Wingman Warrior was connected as
the first joystick (J1).  If it had been configured as a different input,
the generated codes would have a different Jx number.

All keyword matching including the standard keywords is case sensitive.  
Also, some of the automatically generated OSD codes may be redundant. 
For example, J1_Button_0 is the same as JOYCODE_1_BUTTON1.  Standard codes
are preferred over OSD codes.


The standard keycodes are:
--------------------------

KEYCODE_A                KEYCODE_B                KEYCODE_C
KEYCODE_D                KEYCODE_E                KEYCODE_F
KEYCODE_G                KEYCODE_H                KEYCODE_I
KEYCODE_J                KEYCODE_K                KEYCODE_L
KEYCODE_M                KEYCODE_N                KEYCODE_O
KEYCODE_P                KEYCODE_Q                KEYCODE_R
KEYCODE_S                KEYCODE_T                KEYCODE_U
KEYCODE_V                KEYCODE_W                KEYCODE_X
KEYCODE_Y                KEYCODE_Z                KEYCODE_0
KEYCODE_1                KEYCODE_2                KEYCODE_3
KEYCODE_4                KEYCODE_5                KEYCODE_6
KEYCODE_7                KEYCODE_8                KEYCODE_9
KEYCODE_0_PAD            KEYCODE_1_PAD            KEYCODE_2_PAD
KEYCODE_3_PAD            KEYCODE_4_PAD            KEYCODE_5_PAD
KEYCODE_6_PAD            KEYCODE_7_PAD            KEYCODE_8_PAD
KEYCODE_9_PAD            KEYCODE_F1               KEYCODE_F2
KEYCODE_F3               KEYCODE_F4               KEYCODE_F5
KEYCODE_F6               KEYCODE_F7               KEYCODE_F8
KEYCODE_F9               KEYCODE_F10              KEYCODE_F11
KEYCODE_F12              KEYCODE_ESC              KEYCODE_TILDE
KEYCODE_MINUS            KEYCODE_EQUALS           KEYCODE_BACKSPACE
KEYCODE_TAB              KEYCODE_OPENBRACE        KEYCODE_CLOSEBRACE
KEYCODE_ENTER            KEYCODE_COLON            KEYCODE_QUOTE
KEYCODE_BACKSLASH        KEYCODE_BACKSLASH2       KEYCODE_COMMA
KEYCODE_STOP             KEYCODE_SLASH            KEYCODE_SPACE
KEYCODE_INSERT           KEYCODE_DEL              KEYCODE_HOME
KEYCODE_END              KEYCODE_PGUP             KEYCODE_PGDN
KEYCODE_LEFT             KEYCODE_RIGHT            KEYCODE_UP
KEYCODE_DOWN             KEYCODE_SLASH_PAD        KEYCODE_ASTERISK
KEYCODE_MINUS_PAD        KEYCODE_PLUS_PAD         KEYCODE_DEL_PAD
KEYCODE_ENTER_PAD        KEYCODE_PRTSCR           KEYCODE_PAUSE
KEYCODE_LSHIFT           KEYCODE_RSHIFT           KEYCODE_LCONTROL
KEYCODE_RCONTROL         KEYCODE_LALT             KEYCODE_RALT
KEYCODE_SCRLOCK          KEYCODE_NUMLOCK          KEYCODE_CAPSLOCK
KEYCODE_LWIN             KEYCODE_RWIN             KEYCODE_MENU

JOYCODE_1_LEFT           JOYCODE_1_RIGHT          JOYCODE_1_UP
JOYCODE_1_DOWN           JOYCODE_1_BUTTON1        JOYCODE_1_BUTTON2
JOYCODE_1_BUTTON3        JOYCODE_1_BUTTON4        JOYCODE_1_BUTTON5
JOYCODE_1_BUTTON6        JOYCODE_1_BUTTON7        JOYCODE_1_BUTTON8
JOYCODE_1_BUTTON9        JOYCODE_1_BUTTON10       JOYCODE_1_BUTTON11
JOYCODE_1_BUTTON12       JOYCODE_1_BUTTON13       JOYCODE_1_BUTTON14
JOYCODE_1_BUTTON15       JOYCODE_1_BUTTON16       JOYCODE_1_START
JOYCODE_1_SELECT         JOYCODE_2_LEFT           JOYCODE_2_RIGHT
JOYCODE_2_UP             JOYCODE_2_DOWN           JOYCODE_2_BUTTON1
JOYCODE_2_BUTTON2        JOYCODE_2_BUTTON3        JOYCODE_2_BUTTON4
JOYCODE_2_BUTTON5        JOYCODE_2_BUTTON6        JOYCODE_2_BUTTON7
JOYCODE_2_BUTTON8        JOYCODE_2_BUTTON9        JOYCODE_2_BUTTON10
JOYCODE_2_BUTTON11       JOYCODE_2_BUTTON12       JOYCODE_2_BUTTON13
JOYCODE_2_BUTTON14       JOYCODE_2_BUTTON15       JOYCODE_2_BUTTON16
JOYCODE_2_START          JOYCODE_2_SELECT         JOYCODE_3_LEFT
JOYCODE_3_RIGHT          JOYCODE_3_UP             JOYCODE_3_DOWN
JOYCODE_3_BUTTON1        JOYCODE_3_BUTTON2        JOYCODE_3_BUTTON3
JOYCODE_3_BUTTON4        JOYCODE_3_BUTTON5        JOYCODE_3_BUTTON6
JOYCODE_3_BUTTON7        JOYCODE_3_BUTTON8        JOYCODE_3_BUTTON9
JOYCODE_3_BUTTON10       JOYCODE_3_BUTTON11       JOYCODE_3_BUTTON12
JOYCODE_3_BUTTON13       JOYCODE_3_BUTTON14       JOYCODE_3_BUTTON15
JOYCODE_3_BUTTON16       JOYCODE_3_START          JOYCODE_3_SELECT
JOYCODE_4_LEFT           JOYCODE_4_RIGHT          JOYCODE_4_UP
JOYCODE_4_DOWN           JOYCODE_4_BUTTON1        JOYCODE_4_BUTTON2
JOYCODE_4_BUTTON3        JOYCODE_4_BUTTON4        JOYCODE_4_BUTTON5
JOYCODE_4_BUTTON6        JOYCODE_4_BUTTON7        JOYCODE_4_BUTTON8
JOYCODE_4_BUTTON9        JOYCODE_4_BUTTON10       JOYCODE_4_BUTTON11
JOYCODE_4_BUTTON12       JOYCODE_4_BUTTON13       JOYCODE_4_BUTTON14
JOYCODE_4_BUTTON15       JOYCODE_4_BUTTON16       JOYCODE_4_START
JOYCODE_4_SELECT

MOUSECODE_1_BUTTON1      MOUSECODE_1_BUTTON2      MOUSECODE_1_BUTTON3

KEYCODE_NONE             CODE_NONE                CODE_OTHER
CODE_DEFAULT             CODE_PREVIOUS            CODE_NOT
CODE_OR                  !                        |



The input port codes are:
-------------------------

UI_CONFIGURE             UI_ON_SCREEN_DISPLAY     UI_PAUSE
UI_SINGLE_STEP           UI_RESET_MACHINE         UI_SHOW_GFX
UI_FRAMESKIP_DEC         UI_FRAMESKIP_INC         UI_THROTTLE
UI_SHOW_FPS              UI_SHOW_PROFILER         UI_SNAPSHOT
UI_TOGGLE_CHEAT          UI_UP                    UI_DOWN
UI_LEFT                  UI_RIGHT                 UI_SELECT
UI_CANCEL                UI_CLOSE                 UI_SAVE_STATE
UI_LOAD_STATE            UI_ADD_CHEAT             UI_DELETE_CHEAT
UI_SAVE_CHEAT            UI_WATCH_VALUE           UI_EDIT_CHEAT
UI_TOGGLE_DISPLAY        UI_TOGGLE_AUTOFIRE       UI_TOGGLE_LOGWAVE
UI_SHOW_INPUT_LOG        UI_OPERATION_OBJ         UI_COMMAND
UI_CHEAT                 UI_TIME                  START1
START2                   START3                   START4
COIN1                    COIN2                    COIN3
COIN4                    SERVICE1                 SELECT1
SELECT2                  

P1_JOYSTICK_UP           P1_JOYSTICK_DOWN         P1_JOYSTICK_LEFT
P1_JOYSTICK_RIGHT        P1_BUTTON1               P1_BUTTON2
P1_BUTTON3               P1_BUTTON4               P1_BUTTON5
P1_BUTTON6               P1_CUSTOM1               P1_CUSTOM2
P1_CUSTOM3               P1_CUSTOM4               

P2_JOYSTICK_UP           P2_JOYSTICK_DOWN         P2_JOYSTICK_LEFT
P2_JOYSTICK_RIGHT        P2_BUTTON1               P2_BUTTON2
P2_BUTTON3               P2_BUTTON4               P2_BUTTON5
P2_BUTTON6               P2_CUSTOM1               P2_CUSTOM2
P2_CUSTOM3               P2_CUSTOM4               

P3_JOYSTICK_UP           P3_JOYSTICK_DOWN         P3_JOYSTICK_LEFT
P3_JOYSTICK_RIGHT        P3_BUTTON1               P3_BUTTON2
P3_BUTTON3               P3_BUTTON4               

P4_JOYSTICK_UP           P4_JOYSTICK_DOWN         P4_JOYSTICK_LEFT
P4_JOYSTICK_RIGHT        P4_BUTTON1               P4_BUTTON2
P4_BUTTON3               P4_BUTTON4               

P1_DIAL                  P1_DIAL_EXT              P2_DIAL
P2_DIAL_EXT              

P1_TRACKBALL_X           P1_TRACKBALL_X_EXT       P2_TRACKBALL_X
P2_TRACKBALL_X_EXT       

P1_TRACKBALL_Y           P1_TRACKBALL_Y_EXT       P2_TRACKBALL_Y
P2_TRACKBALL_Y_EXT       


