Joymappings

For a long time the SDL port has had a joystick mappings file. There are 2 sample ones: data/C64/sdl_joymap_thec64.vjm and data/C64/sdl_joymap_ps3.vjm.

These files contain associations between host joystick actions and emulator actions. Possible actions include a corresponding emulated joystick action, a shortcut to an emulator menu action etc.

The branch branches/fabrizio/3.7-joystick-mapping-2 moves the joystick mappings file to the generic joystick code, therefore making it available to the Gtk3 port as well.

The file name has the form {sdl,gtk3,headless}-joymap-{C64,C64SC,...}.vjm. Its format is documented in a comment in the sample file itself.

In order to port the feature to the generic code, the event UI_FUNCTION (shortcuts to menu actions) got lost. It was implemented in a very SDL-specific way, and a cross-platform implementation that allows shortcuts from SDL and GTK3 should be written instead.

Mapping file

A line has 4 mandatory columns:

1. joystick number (zero-based index of the hardware joystick)
2. input type
   1. axis
   2. button
   3. hat
3. input index
   • for buttons, it is the zero-based index of the button
   • for axes
     • if the action is 6 (POT_AXIS), it is the zero-based index of the axis
     • otherwise, 0 and 1 are respectively the positive and negative directions of axis 0; 2 and 3 are respectively the positive and negative directions of axis 1 etc. In formulas: axis=inputindex/2 (integer division), direction = positive if inputindex % 2 ==0 , negative if inputindex % 2 ==1.
   • for hats, 0, 1, 2 and 3 are respectively up, down, left and right of hat 0; 4, 5, 6 and 7 are respectively up, down, left and right of hat 1, etc.
4. action (enum joystick_action_t in joystick.h)

0. NONE: none
1. JOYSTICK: emulated joystick action
2. KEYBOARD: emulated keyboard action
3. MAP: SDL-only. Only works while the SDL settings menu is active. If a joystick action mapped to this is performed, the user is asked to press a key, which will become a hotkey to select the currently-selected menu
4. UI_ACTIVATE: go to the settings menu (SDL) show the settings dialog (Gtk3)
5. UI_FUNCTION: shortcut to a specific UI function. UNSUPPORTED AT THE MOMENT
6. POT_AXIS: (only for axes of hardware joysticks) the analog value of the axis is the value of the emulated potentiometer

For some actions, more columns are present:

• JOYSTICK

5. emulated joystick pin. Same values as reading the corresponding CIA register.
1. up
2. down
4. left
8. right
16. fire
32. fire 2
64. fire 3

Blacky note: In vice we also emulate snes pads, these need to be able to be controlled as well, and so the emulated joystick pin needs to be renamed (more like emulated joystick input) and extended, some of the old pins/inputs can be reused, and in such a case we get the following:

1. joystick up / snes pad up
2. joystick down / snes pad down
4. joystick left / snes pad left
8. joystick right / snes pad right
16. joystick fire 1 / snes pad A button
32. joystick fire 2 / snes pad B button
64. joystick fire 3 / snes pad X button
128. snes pad Y button
256. snes pad left bumber
512. snes pad right bumber
1024. snes pad select button
2048. snes pad start button

And this can be extended if other joystick devices become available with more buttons than we currently map for.

• KEYBOARD

5. row in the keyboard matrix layout
6. column in the keyboard matrix layout

• POT_AXIS

5. which potentiometer is affected
1. Pot-X
2. Pot-Y

Technical

When a hardware joystick action is performed, the selected joystick driver (Gtk3) ui_dispatch_events() (SDL) call joy_axis_event() or joy_button_event() or joy_hat_event(). These functions read what that joystick action is mapped to, and perform the mapped action.

Mappings are stored in the static array joystick_devices, declared in joystick.c, that has one element per registered hardware joystick. Mappings are stored in each element's axis_mapping, button_mapping and hat_mapping, each an array with one element per axis/button/hat. The mappings are initialised from the joystick mappings file, or with default values if no joystick mappings file is present.

Example

Take this sample line from data/C64/sdl_joymap_ps3.vjm

# O -> Space
0 1 1 2 7 4

First column: HW joystick 0

Second column: input type is button (1)

Third column: input index 1, so button 1

Fourth column: action KEYBOARD (2)

Fifth and sixth columns: Space (7 and 4 in the matrix)