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. righ
16. fire
32. fire 2
64. fire 3

• 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 papped 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)