Go to the first, previous, next, last section, table of contents.

# 3 System files

In order to work properly, the emulators need to load a few system files:

- the system ROMs, raw binary files containing copies of the original ROMs of the machine you are emulating;
- the keyboard maps, text files describing the keyboard layout;
- the palette files, text files describing the colors of the machine you are emulating.
- the romset files, text files describing the different ROMs to load.
- the hotkey files, text files with keyboard shortcuts.

The place where they will be searched for depends on the value of the `Directory` resource, which is a colon (`:`)-separated search path list, like the UNIX `PATH` environment variable. The default value is

    $HOME/.local/share/vice/EMU:PREFIX/share/vice/EMU:BOOTPATH/EMU

Where `PREFIX` is the installation prefix (usually ``/usr'`), `EMU` is the name of the emulated machine (`C64`, `C64DTV`, `C128`, `PET`, `PLUS4`, `CBM-II`, `SCPU64` or `VIC20`) and `BOOTPATH` is the directory where the executable resides. The disk drive ROMs are looked for in a directory with `EMU` set to `DRIVES`. `$HOME` is the user's home directory.

For example, if you have the C64 emulator installed in

    /usr/bin/x64

then the value will be

    $HOME/.local/share/vice/C64:/usr/share/vice/C64:/usr/bin/C64

And system files will be searched for under the following directories, in the specified order:

1. `$HOME/.local/share/vice/C64`
2. `/usr/share/vice/C64`
3. `/usr/bin/C64`

System files can still be installed in a different directory if you specify a complete path instead of just a file name. For example, if you specify ``./kernal'` as the kernal image name, the kernal image will be loaded from the current directory. This can be done by using command-line options or by modifying resource values (see section 5.1 Format of resource files).

## 3.1 ROM files

Every emulator requires its own ROM set. For the VIC20 and the C64, the ROM set consists of the following files:

- ``kernal'`, the Kernal ROM (8 KiB)
- ``basic'`, the Basic ROM (8 KiB)
- ``chargen'`, the character generator ROM (4 KiB)

The C128 needs the following files:

- ``kernal'`, the Kernal ROM (8 KiB)
- ``basic'`, the Basic + Editor ROM (32 KiB)
- ``chargen'`, the character generator ROM (4 KiB)

The C128, VIC20, SCPU64 and C64 emulators also need the following DOS ROMs for the hardware-level emulation of the 1540, 1541, 1571, 1581, 2000, and 4000 disk drives, as well as the CMD hard drive:

- ``dos1540-325302+3-01.bin'`, the 1540 drive ROM (16 KiB) (DOS 2.6 V170, Commodore ROM images 325302-01 and 325303-01)
- ``dos1541-325302-01+901229-05.bin'`, the 1541 drive ROM (16 KiB) (DOS 2.6, Commodore ROM images 325302-01 and 901229-05.bin)
- ``dos1541ii-251968-03.bin'`, the 1541-II drive ROM (16 KiB) (DOS 2.6, Commodore ROM image 251968-03)
- ``dos1551-318008-01.bin'`, the 1551 drive ROM (16 KiB) (DOS 2.6 TDISK, Commodore ROM image 318008-01)
- ``dos1570-315090-01.bin'`, the 1570 drive ROM (32 KiB) (DOS 3.0, Commodore ROM image 315090-01)
- ``dos1571-310654-05.bin'`, the 1571 drive ROM (32 KiB) (DOS 3.0, Commodore ROM image 310654-05)
- ``dos1571cr-318047-01.bin'`, the 1571CR drive ROM (32 KiB) (DOS 3.0, Commodore ROM image 318047-01)
- ``dos1581-318045-02.bin'`, the 1581 drive ROM (32 KiB) (DOS 10, Commodore ROM image 318045-02)
- ``dos2000-cs-33cc6f.bin'`, the CMD FD-2000 drive ROM (32 KiB) (CMD FD DOS 1.4, CMD ROM image cs-33cc6f)
- ``dos4000-fd-350022.bin'`, the CMD FD-4000 drive ROM (32 KiB) (CMD FD DOS 1.4, CMD ROM image fd-350022.bin)
- ``bootromCMDHD-v2-80.bin'`, the CMD HD boot ROM (16 KiB) (Boot ROM V2.80, CMD ROM image)

In addition to those all emulators can handle a parallel IEEE488 interface (the C64 and C128 via `$df**` extension, the VIC20 via VIC1112 emulation) so they also need the DOS ROM for the IEEE disk drives:

- ``dos2031-901484-03+05.bin'`, the 2031 drive ROM (16 KiB) (DOS 2.6, Commodore ROM images 901484-03 and 901484-05)
- ``dos2040-901468-06+07.bin'`, the 2040 drive ROM (8 KiB) (DOS 1, Commodore ROM images 901468-06, 901468-07)
- ``dos3040-901468-11-13.bin'`, the 3040 drive ROM (12 KiB) (DOS 2, Commodore ROM images 901468-11, 901468-12 and 901468-13)
- ``dos4040-901468-14-16.bin'`, the 4040 drive ROM (12 KiB) (DOS 2, Commodore ROM images 901468-14, 901468-15 and 901468-16)
- ``dos1001-901887+8-01.bin'`, the 1001/8050/8250 drive ROM (16 KiB) (DOS 2.7, Commodore ROM images 901887-01 and 901888-01)
- ``dos9000-300516+7-revC.bin'`, the D9090/60 drive ROM (16 KiB) (DOS 3.0, Commodore ROM images 300516-RevC and 300517-RevC)

Note that there are other DOS images on the internet. The DOS 2.5 images might be used with the 8050, but it cannot handle the double sided drives of the 1001 and 8250 and it is not supported by VICE.

The PET emulator uses an expanded setup, because there are three major versions of the Basic and the Kernal, and many versions of the Editor ROM. In addition there are cartridge ROM sockets.

The Kernal files contain the memory from range $F000-$FFFF, the Basic ROMs either the range $C000-$DFFF or $B000-$DFFF. To handle the different screen sizes and keyboards, different so-called "editor-ROMs" for the memory range $E000-$E800 are provided. The PET ROMs have the following names:

- ``kernal-1.901439-04-07.bin'`, the PET2001 Kernal ROM (4 KiB) (Commodore ROM images 901447-06 and 901447-07, same as 901439-04 and 901439-07)
- ``kernal-2.901465-03.bin'`, the PET3032 Kernal ROM (4 KiB) (Commodore ROM image 901465-03)
- ``kernal-4.901465-22.bin'`, the PET4032/8032 Kernal ROM (4 KiB) (Commodore ROM image 901465-22)
- ``basic-1.901439-09-05-02-06.bin'`, the PET2001 Basic 1 ROM (8 KiB) (Commodore ROM images 901447-09, 901447-02, 901447-03, 901447-04.bin. The -09 ROM is the revised -01 ROM. Same as images 901439-09, 901439-05, 901439-02, 901439-06. The -09 ROM is the revised -01 ROM)
- ``basic-2.901465-01-02.bin'`, the PET3032 Basic 2 ROM (8 KiB) (Commodore ROM images 901465-01 and 901465-01)
- ``basic-4.901465-23-20-21.bin'`, the PET4032/8032 Basic 4 ROM (12 KiB) (Commodore ROM images 901465-23, 901465-20 and 901465-21. The -23 ROM is a revised -19 ROM)
- ``edit-1-n.901439-03.bin'`, the PET2001 editor for graphics keyboards (2 KiB) (Commodore ROM image 901447-05, same as 901439-03)
- ``edit-2-b.901474-01.bin'`, the PET3032 editor for business keyboards (2 KiB) (Commodore ROM image 901474-01)
- ``edit-2-n.901447-24.bin'`, the PET3032 editor for graphics keyboards (2 KiB) (Commodore ROM image 901447-24)
- ``edit-4-40-n-50Hz.901498-01.bi'`, the PET4032 editor for graphics keyboards (2 KiB) (Commodore ROM image 901498-01)
- ``edit-4-40-b-50Hz.ts.bin'`, the PET4032 editor for business keyboards (2 KiB) (Said to be "901498-01 modified to use a business keyboard on a 50Hz 4032")
- ``edit-4-80-b-50Hz.901474-04_.bin'`, the PET8032 editor for business keyboards (2 KiB) (Commodore ROM image 901474-04-?)
- ``characters-1.901447-08.bin'`, the character generator ROM (2KiB) for the PET 2001. It has two sets with 128 chars each. The second (inverted) half of each set is computed from the first half by inverting it. This is a PET hardware feature. Compared to the character ROMs for later models, it has the upper case and lower case letters swapped: to get lower case letters, you need to use the shift key (so the basic abbreviation for "LIST" looks like "Li", instead of "lI" for "list". (Commodore ROM image 901447-08)
- ``characters-2.901447-10.bin'`, the character generator ROM (2KiB). It has two sets with 128 chars each. The second (inverted) half of each set is computed from the first half by inverting it. This is a PET hardware feature. (Commodore ROM image 901447-10)
- ``chargen.de'`, the character generator ROM (2KiB). This version is a patched German charset, with the characters [, \ and ] replaced by umlauts. It has been provided by U. Guettich and he reports that it is supported by some programs.
- ``characters.901640-01.bin'`, the SuperPET character generator ROM (4KiB). The first half is the same as ``characters-2.901447-10.bin'`, the second half contains, instead of an upper and lower case set, an ASCII character set and an APL character set. For these sets, the screen code is equal to the ASCII/APL code.
- ``waterloo-[abcdf]000.901898-0[1-5].bin'`, ``waterloo-e000.901897-01.bin'`. The Waterloo system ROMs for the 6809 CPU in the SuperPET.
- ``hre-9000.324992-02.bin'` HiRes Emulator (at $9000) and ``hre-a000.324993-02.bin'` HiRes BASIC (at $A000). These are the two roms for supporting the HRE on the 8296. The ROMs are initialized by the command `SYS 36864`.

The PETs also have sockets for extension ROMs for the addresses $9000-$9FFF, $A000-$AFFF and $B000-$BFFF (the last one for PET2001 and PET3032 only). You can specify ROM image files for those extensions command line options `-petrom9`, `-petromA` and `-petromB` resp.

An alternative would be to specify a long kernal ROM with the `-kernal` option that includes the extension ROM areas.

Also, you can specify replacements for the basic ROM at $B000-$DFFF with the `-petromBasic` option and for the editor ROM at $E000-$E7FF with the `-petromEditor` option.

The CBM-II emulator again uses another setup. For those models the kernal used is the same for all. However, for different amounts of memory exist different versions of the BASIC ROMs. The 128KiB RAM version (C610, C710, B128) uses one bank of 64KiB for the BASIC text and another one for all the variables. The 256KiB RAM version uses one bank for text, one for variables, one for arrays and one for strings.

Also the character generator ROMs have a format different from the above. The other character ROMs have 8 bytes of pixel data per character. Those ROMs have 16 bytes per character instead. The C6x0 only uses the first 8 of it, but the C7x0 uses 14 lines per character and needs those larger ROMs. Both ROMs hold, like the PET, two character sets with 128 characters each. Again the second half of the full (256 char) character set is computed by inverting.

- ``kernal'`, the KERNAL (8KiB) for the business machines (6xx/7xx)
- ``kernal.500'`, the KERNAL (8KiB) for the personal machine (510) (901234-02)
- ``basic.128'`, the CBM-II 128KiB BASIC (16KiB)
- ``basic.256'`, CBM-II 256KiB BASIC (16KiB)
- ``basic.500'`, C510 BASIC (16KiB) (901236-02 + 901235-02)
- ``chargen.500'`, character generator ROM for the C5x0 (4KiB) (901225-01)
- ``chargen.600'`, character generator ROM for the C6x0 (4KiB)
- ``chargen.700'`, character generator ROM for the C7x0 (4KiB)

The SCPU64 needs the following files:

- ``scpu64'`, the SCPU64 ROM (128 KiB)
- ``chargen'`, the character generator ROM (4 KiB)

## 3.2 Keymap files

Keymap files are used to define the keyboard layout, defining which key (or combination of keys) must be mapped to each keysym.

In other words, the keyboard emulation works like this: whenever the user presses or releases a key while the emulation window has the input focus, the emulator receives an event with a value that identifies that key. That value is called a keysym and is unique to that key. The emulator then looks up that keysym in an internal table that tells it which key(s) to press or release on the emulated keyboard.

VICE keymap files have the ``.vkm'` default extension, and every emulator comes with a default positional mapping and a default symbolic mapping, see section 1.2 The keyboard emulation.

To find out the keycodes to use, incase you want to edit the keymaps yourself, you can enable showing the keycodes in the status bar in the settings.

### 3.2.1 Comments

- Any line starting with the `#` sign, is completely ignored.
- Any characters in "C-style" comments is ignored (/* this is a comment */).

When creating new keymaps, please copy over the usual set of leading comments (have a look at the default US keymaps).

In particular each file at the very least should contain a line indicating what type of mapping it is supposed to be, for what host layout, what emulator, and which UI, like this:

    # Symbolic Mapping, US Layout, C64, GTK

### 3.2.2 Control commands

There are some special commands you can put into the keyboard file, these usually appear at the beginning of the file, before any actual keycode definitions; they are recognized because they start with an exclamation mark:

- `!CLEAR` clears the currently loaded keyboard map; it is necessary to put this at the beginning of the file if you want the keymap file to override all of the current internal settings;
- `!INCLUDE` followed by "filename" reads (inserts) file as mapping file. This is useful when adding local mappings to an otherwise generic file (so you dont have to copy the while file, but just add/modify a few keys).
- `!UNDEF` followed by keysym removes keysym from mapping table.

- `!LSHIFT`, `!RSHIFT`, followed by a row and a column value, specify where the left and right shift keys are located on the emulated keyboard; for example, C64 default keymaps will specify

      !LSHIFT 1 7
      !RSHIFT 6 4

- `!VSHIFT`, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will be used as a virtual shift key when the shift flag is set.
- `!SHIFTL`, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will be used as a virtual shift-lock key; for example, C64 default keymaps will specify

      !VSHIFT LSHIFT
      !SHIFTL LSHIFT

For emulated keyboards that have only one shift key, set both `!LSHIFT` and `!RSHIFT` to the same row/col and use RSHIFT for `!VSHIFT` and `!SHIFTL`.

- `!LCTRL`, followed by a row and a column value, specifiy where the left control key is located on the emulated keyboard.
- `!LCBM`, followed by a row and a column value, specifiy where the left CBM key is located on the emulated keyboard.
- `!VCTRL`, followed by a ctrlkey (LCTRL), specify what key will be used as a virtual control key.
- `!VCBM`, followed by a cbmkey (LCBM), specify what key will be used as a virtual CBM key.

For example, a C64 keymap would usually start with this block:

    !CLEAR
    !LSHIFT 1 7
    !RSHIFT 6 4
    !VSHIFT RSHIFT
    !SHIFTL LSHIFT
    !LCBM 7 5
    !VCBM LCBM
    !LCTRL 7 2
    !VCTRL LCTRL

When creating new keymaps, make sure to create the respective set of commands first and make sure the row/column values are correct.

Before you fix the rest of your mapping, make sure to create mappings for all modifier keys that relate to the used row/column pairs and update their `SHIFTFLAG` accordingly. Getting those right is the key to making more complex mappings possible later.

For a example a typical GTK C64 symbolic mapping would contain something like this:

    Shift_R         6 4 0x0004    /* right SHIFT -> right SHIFT */
    Shift_L         1 7 0x0002    /* left SHIFT  -> left SHIFT */
    Caps_Lock       1 7 0x0040    /* CAPS lock   -> SHIFT lock */
    Tab             7 5 0x2008    /* TAB         -> CBM (can be combined with SHIFT) */
    Control_L       7 2 0x4008    /* left CTRL   -> CTRL (can be combined with SHIFT) */

### 3.2.3 Key mappings

This table is described by the keymap file, which is made up of lines like the following:

    KEYSYM ROW COLUMN SHIFTFLAG /* COMMENT */

Where:

- `KEYSYM` identifying the keysym: In (GTK) it is a literal keyboard symbol as a string (for example "space"), in (SDL) it is a numeric keycode (for example "32"). You can use the "show keycodes in statusbar" feature to see what keysym is bound to any key.
- `ROW` and `COLUMN` refer to the row and column of the emulated key on the emulated keyboard - all existing keymaps have the respective keyboard matrix in them in comments, have a look.
- The `SHIFTFLAG` controls various aspects of how a host key is mapped to the emulated keyboard. For example you may want to artificially add or remove certain modifiers to/from the emulated keypress.

A keymap is parsed line by line. More complex mappings can be created by mapping the same key with different `SHIFTFLAG` to different emulated keys in multiple lines:

- A key mapping is found when the key symbol matches
- and when none of the following reject conditions apply:

  Value | Hex | Description | Action
  `0` | `0x0000` | The key is never shifted. | If any SHIFT modifiers pressed, then reject key.
  `8` | `0x0008` | The key can be (optionally) shifted by the user. | If any SHIFT modifiers pressed on the host, and this flag is not set, then reject key.
  `128` | `0x0080` | SHIFT modifier required on host. | If SHIFT modifier(s) not pressed on the host, and this flag is set, then reject key.
  `256` | `0x0100` | Key is used for an alternative keyboard mapping | if no alternative mapping is enabled (eg C64 mode in x128), reject key.
  `512` | `0x0200` | ALT-R (ALT-GR) modifier required on host. | If ALT-R modifier not pressed on the host, and this flag is set, then reject key.
  `1024` | `0x0400` | CTRL modifier required on host. | If CTRL modifier not pressed on the host, and this flag is set, then reject key.

- If no reject condition was true then we found a possible match. If no other mapping will be found, this is the one that will be used. We may or may not look for another match, depending on:

  Value | Hex | Description
  `32` | `0x0020` | Another definition for this keysym/scancode follows later in the file. If this flag is not set, stop looking for another match.

- Once a match was found, the virtual modifiers are applied:

  Value | Hex | Description | Action
  `1` | `0x0001` | The key is shifted on the emulated keyboard | virtual shift will be used when it is not shifted on the host keyboard.
  `16` | `0x0010` | Deshift key for this keysym/scancode. | When the key is pressed with shift on the host keyboard, shift will not be used on the emulated keyboard.
  `2048` | `0x0800` | Key is combined with CBM for this keysym/scancode | virtual CBM will be used when it is not combined with CBM via another mapped key.
  `4096` | `0x1000` | Key is combined with CTRL for this keysym/scancode | virtual CTRL will be used when it is not combined with CTRL via another mapped key.

- and last not least these are the flags left:

  Value | Hex | Description
  `32768` | `0x8000` | Do not emulate a "locked" switch for this key. This can be useful when your host keyboard provides physical locking by itself. (currently works only for the C128 40/80 and CAPS-lock keys)

For example this is is from the SDL C64 symbolic DE mapping:

    # 32+1 not shifted on host, shifted on c64
    60 5 7 0x0021          /*             < -> <            */
    # 32+128 shifted on host, shifted on c64
    60 5 4 0x00a0          /*             > -> >            */
    # 512+16 alt-gr on host, deshift for c64
    60 6 0 0x0210          /*        altr+< -> pound        */

#### 3.2.3.1 Special Rows

Besides the keyboard matrix of the emulated keyboard, there are a bunch of special keys available in the negative rows as below:

Row | Column | Description
`-1` | `n` | Joystick keymap A, direction n
`-2` | `n` | Joystick keymap B, direction n
`-3` | `0` | First RESTORE key
`-3` | `1` | Second RESTORE key
`-4` | `0` | 40/80 column key (x128)
`-4` | `1` | CAPS (ASCII/DIN) key (x128)
`-5` | `n` | Joyport keypad, key n (not supported in x128)

For example, a lot of (GTK) keymaps would map RESTORE like this:

    # Restore key mapping
    F12     -3 0
    Page_Up -3 1

Joystick keymap direction column values for rows -1 and -2:

6 (N/W) | 7 (North) | 8 (N/E)
4 (West) | 0 (Fire) | 5 (East)
1 (S/W) | 2 (South) | 3 (S/E)

Joyport keypad direction column values for row -5:

0 | 1 | 2 | 3 | 4
5 | 6 | 7 | 8 | 9
10 | 11 | 12 | 13 | 14
15 | 16 | 17 | 18 | 19

When a bigger spaced key is used, it uses the upper left most column value.

#### 3.2.3.2 Modifier Flags

The `SHIFTFLAG` can have one of the following values. Flags can be combined by simply ORing (or adding) them together:

Value | Hex | Description
`0` | `0x0000` | The key is never shifted.
`1` | `0x0001` | The key is shifted on the emulated keyboard, virtual shift will be used when it is not shifted on the host keyboard.
`2` | `0x0002` | The key is the left shift key.
`4` | `0x0004` | The key is the right shift key. Use only this flag for emulated keyboards that have only one shift key.
`8` | `0x0008` | The key can be (optionally) shifted by the user.
`16` | `0x0010` | Deshift key for this keysym/scancode. That means when the key is pressed with shift on the host keyboard, shift will not be used on the emulated keyboard.
`32` | `0x0020` | Another definition for this keysym/scancode follows later in the file
`64` | `0x0040` | Key is SHIFT-lock on the emulated machine. Usually you'd use this for the CAPS lock key on the host keyboard.
`128` | `0x0080` | SHIFT modifier required on host.
`256` | `0x0100` | Key is used for an alternative keyboard mapping (e.g. C64 mode in x128). Note that any alternative mappings must occur before the normal mappings for the same key/symbol in the file.
`512` | `0x0200` | ALT-R (ALT-GR) modifier required on host.
`1024` | `0x0400` | CTRL modifier required on host.
`2048` | `0x0800` | Key is combined with CBM for this keysym/scancode.
`4096` | `0x1000` | Key is combined with CTRL for this keysym/scancode.
`8192` | `0x2000` | Key is (left) CBM on emulated machine.
`16384` | `0x4000` | Key is (left) CTRL on emulated machine.
`32768` | `0x8000` | Do not emulate a "locked" switch for this key. This can be useful when your host keyboard provides physical locking by itself. (currently works only for the C128 40/80 and CAPS-lock keys)

The `SHIFTFLAG` can be used to control various aspects of how the host key will map to the emulated keyboard. For example it is useful if you want certain keys to be "artificially" shifted by the emulator, and not by the user. Or the other way around, a key can be "deshifted".

For example, `F2` is shifted on the C64 keyboard, but you might want it to be mapped to the unshifted `F2` key on the PC keyboard. For example, a typical C64 keymap would contain the following:

    F1 0 4 8        /* F1 -> F1 (+SHIFT allowed) */
    F2 0 4 1        /* F2 -> F1 + SHIFT */
    F3 0 5 8        /* F3 -> F3 (+SHIFT allowed) */
    F4 0 5 1        /* F4 -> F3 + SHIFT */
    F5 0 6 8        /* F5 -> F5 (+SHIFT allowed) */
    F6 0 6 1        /* F6 -> F5 + SHIFT */
    F7 0 3 8        /* F7 -> F7 (+SHIFT allowed) */
    F8 0 3 1        /* F8 -> F7 + SHIFT */

where `0` and `4` identify the key (row 0, column 4 on the keyboard matrix), and `1` specifies that every time the user presses `F2` the shift key on the C64 keyboard must be pressed.

## 3.3 Palette files

Palette files are used to specify the colors used in the emulators. They are made up of lines like the following:

    RED GREEN BLUE

where `RED`, `GREEN` and `BLUE` are hexadecimal values ranging from 0 to FF and specifying the amount of red, green and blue you want for each color.

You have to include as many lines as the number of colors the emulated machine has, and the order of the lines must respect the one used in the machine (so the N'th line must contain the specifications for color N - 1 in the emulated machine).

Lines starting with the `#` sign are completely ignored. This is useful for adding comments (such as color names) within the palette file. That said, it is not the whole truth - there are special comment lines, which the user interface uses to identify and refer to palettes:

    # NAME:<NAME>

with <NAME> being the name of the Palette, as shown in the menus.

    # TYPE:<CHIP>

with <CHIP> being one the following: "VIC, VICII, TED, VDC, Crtc"

These special comment lines must appear exactly as shown above, or they will be ignored.

For example, the default PET palette file (which has only two colors, 0 for background and 1 for foreground), looks like the following:

    #
    # VICE Palette file
    #
    # Syntax:
    # Red Green Blue
    #
    # NAME:Black/White
    # TYPE:Crtc

    # Background
    00 00 00

    # Foreground
    00 FF 00

## 3.4 Romset files

The Romset files are not used by default on all emulators. You might have recognized that the names of the ROM images are saved in resources. Loading a Romset file now just means a `shortcut' to changing all the resources with ROM image names and reloading the ROMs.

The PET and CBM-II emulators use this feature to change between the different ROM versions available for those machines. E.g. the Romset file for the PET 2001 is

    KernalName="pet2001"
    EditorName=
    ChargenName="chargen"
    RomModule9Name=
    RomModuleAName=
    RomModuleBName=

As you can see, the file even uses the same syntax as the resource file, it is just a bit stripped down.

While a Romset file is processed, the directory where the Romset file was found is temporarily prepended to the search path (`Directory` resource). This also means that if you have a setting for `Directory` in it, its effect is limited to the Romset file itself.

### 3.4.1 Romset command line options

`-romsetfile <File>`
  load the given romset file
`-romsetarchive <File>`
  load the given romset archive
`-romsetarchiveselect <Item number>`
  select the given item from the current romset archive

## 3.5 Hotkeys files

VICE allows setting custom keyboard shortcuts, which we refer to as hotkeys. These hotkeys can be set either through the user interface or by editing hotkeys files, which are stored in the VICE data directory, in the user's VICE configuration directory or at a custom location. Hotkeys files have the `.vhk` extension.

VICE's hotkeys files are read from VICE's data directory, which we'll refer to as `$VICEDIR` and the (optional) user's hotkeys will be in the user's VICE configuration directory, which we'll refer to as `$USERDIR`. When saving hotkeys without explicitly specifying a custom path, the name of the user's hotkeys file will be in the form `$UI-hotkeys-$MACHINE.vhk`, for example "gtk3-hotkeys-C64SC.vhk".

On Unix, `$VICEDIR` will point to `/usr/share/vice/`, when using the default install prefix, and `$USERDIR` will point to `$HOME/.config/vice/`. On Windows, `$VICEDIR` will point to the root directory of the bindist and `$USERDIR` will point to `%APPDATA%\vice`, which usually is `C:\Users\%USERNAME%\AppData\Roaming\vice`.

A custom path can be specified by using the command line interface: `x64sc -hotkeyfile <some-file>`, or by using the UI (TODO).

### 3.5.1 Hotkeys command line options

`-hotkeyfile <File>`
  Load the given hotkeys file

### 3.5.2 Syntax of the hotkeys files

The syntax of the hotkeys files is pretty straightforward, a file can contain mappings, directives and comments. Leading and trailing whitespace is ignored by the parser.

#### 3.5.2.1 Comments

Comments are started with either `;` or `#` and occupy the rest of the line, they can also appear inline after a directive or mapping.

For example:

    # This is a comment

    monitor-open    <Alt>h      # This is an inline comment

#### 3.5.2.2 Directives

Directives are special commands for the parser. They start with `!` and are case-insensitive.

!CLEAR

>     !clear

Clear all registered hotkeys. Best used as the first directive in the (main) hotkeys file.

!DEBUG

>     !debug <enable|disable|on|off>

Enable or disable debugging messages via VICE's log system. Messages will be prefixed with 'Hotkeys:'. Debugging is disabled by default.

!ELSE

>     !else

Take the false branch of an `!if` condition. See !IF for more on conditionals in hotkeys files.

!ENDIF

>     !endif

Close `!if` [`!else`] condition body. See !IF for more on condtionals in hotkeys.

!IF

>     !if <condition>

Conditionally execute hotkeys file contents. If condition is true, the lines following `!if` will be executed. May be followed by `!else` to specify lines that must be executed when condition is false. Must be followed by `!endif` to end the conditional execution of lines.

Conditions can contain boolean expressions: the boolean operators `!` (not), `||` (or) and `&&` (and) are supported, as well as parenthesis to change (or emphasize) precedence. Conditionals can be nested.

Only predefined boolean symbolic constants are available for use in the expressions, these are:

`true`
`false`
  Boolean literals, useful for commenting out multiple lines of a hotkeys file, akin to the `#if 0` construct in C.
`C64`
  The current emulator is x64
`C64SC`
  The current emulator is x64sc
`C64DTV`
  The current emulator is x64dtv
`SCPU64`
  The current emulator is xscpu64
`C128`
  The current emulator is x128
`PET`
  The current emulator is xpet
`PLUS4`
  The current emulator is xplus4
`CBM5X0`
  The current emulator is xcbm5x0
`CBM6X0`
  The current emulator is xcbm2
`VIC20`
  The current emulator is xvic
`SDL1`
`SDL2`
`GTK3`
  UI identifiers. The can be used to only assign certain hotkeys for certain UIs. Please note that to check for SDL regardless of library version the condition `SDL1 || SDL2` must be used.
`MACOS`
`UNIX`
`WINDOWS`
  Operation system identifiers. Since MacOS is genetically Unix, the `UNIX` identifier includes MacOS, while the `MACOS` identifier is only valid for MacOS. To register a hotkey for all Unix except MacOs use `UNIX && !MACOS`.

Some examples of using conditionals

    !if MACOS
        # map hotkey if the host OS is MacOS
        monitor-open    <Command>Escape
    !else
        # map hotkey if not MacOS
        monitor-open    <Alt>h
    !endif

!INCLUDE

>     !include <file>

Process `<file>` as if its contents were injected into the current file being processed. This can be used recursively. The `<file>` argument can be inside quotes (`"`) to be able to use paths or filenames with spaces in them, and quotes inside quotes can be used by escaping them with `\`, for example: `!include "foo \"bar\".vhk"`.

TODO: document search order/logic for included files

For example:

    !include "hotkeys-drive.vhk"

will include `/usr/share/vice/hotkeys/hotkeys-drive.vhk`, assuming the default install prefix for VICE was used.

!UNDEF

>     !undef [<modifier>..]<keyname>

Remove a hotkey from whatever action it is mapped to.

For example:

    !undef <Alt>r               # Unmap Alt+r from 'restore display'
    machine-reset-cpu   <Alt>r  # Map Alt+r to reset

#### 3.5.2.3 Hotkey mappings

Syntax

>     <action-name>   [<modifier>...]<keyname>

Create a mapping of a hotkey to an action, where `<action-name>` is a string refering to an operation triggered by a menu item -- such as toggling Warp Mode, or attaching a disk to a drive -- followed by a keyname, optionally prefixed with one or more modifiers.

For example:

    monitor-open    <Alt>m
    settings-open   KP_Divide       # map '/' on the keypad to the settings dialog
    edit-paste      <Control><Alt>Insert

The key names are case-sensitive and are taken from the key names X11 uses. See `src/arch/shared/hotkeys/vhkkeysyms.h` for a list of the symbolic constants for the keys, the names are the same as the symbolic constants, excluding the `VHK_KEY_` prefix.

In the above example the string 'Insert' would map to `VHK_KEY_Insert`.

### 3.5.3 List of modifiers

Windows/Unix | MacOS | GDK symbolic constant
`<Alt>` | `<Option>` | `GDK_MOD1_MASK`
`<Control>` | `<Command>` | `GDK_CONTROL_MASK`
`<Hyper>` |  | `GDK_HYPER_MASK`
`<Shift>` | `<Shift>` | `GDK_SHIFT_MASK`
`<Super>` | `<Super>` | `GDK_SUPER_MASK`

> Please be aware that some modifier+key combinations are either mapped to the emulated machine's keyboard -- such as `<Control>1` being mapped to CBM+1 when using a positional keymap -- or to the operating system/window manager. Mappings using `<Alt>` or `<Alt><Shift>` are usually fine.

### 3.5.4 List of action names

name | description
`advance-frame` | Advance emulation one frame
`border-mode-debug` | Set border mode to Debug
`border-mode-full` | Set border mode to Full
`border-mode-none` | Set border mode to None
`border-mode-normal` | Set border mode to Normal
`cart-attach` | Attach CRT cartridge image
`cart-attach-raw` | Attach raw cartridge image
`cart-attach-raw-1000` | Attach raw cartridge image at $1000
`cart-attach-raw-2000` | Attach raw cartridge image at $2000
`cart-attach-raw-4000` | Attach raw cartridge image at $4000
`cart-attach-raw-6000` | Attach raw cartridge image at $6000
`cart-attach-raw-a000` | Attach raw cartridge image at $A000
`cart-attach-raw-b000` | Attach raw cartridge image at $B000
`cart-attach-raw-behrbonz` | Attach Behr Bonz cartridge image
`cart-attach-raw-c1-full` | Attach full C1 cartridge image
`cart-attach-raw-c1-high` | Attach high C1 cartridge image
`cart-attach-raw-c1-low` | Attach low C1 cartridge image
`cart-attach-raw-c2-full` | Attach full C2 cartridge image
`cart-attach-raw-c2-high` | Attach high C2 cartridge image
`cart-attach-raw-c2-low` | Attach low C2 cartridge image
`cart-attach-raw-final` | Attach Final Expansion cartridge image
`cart-attach-raw-jacint1mb` | Attach 1MB Cartridge image
`cart-attach-raw-magic` | Attach c264 magic cart image
`cart-attach-raw-megacart` | Attach Mega-Cart image
`cart-attach-raw-multi` | Attach multi cart image
`cart-attach-raw-ultimem` | Attach UltiMem cartridge image
`cart-attach-raw-vicfp` | Attach Vic Flash Plugin cartridge image
`cart-detach` | Detach cartridge
`cart-detach-1000` | Detach cartridge image at $1000
`cart-detach-2000` | Detach cartridge image at $2000
`cart-detach-4000` | Detach cartridge image at $4000
`cart-detach-6000` | Detach cartridge image at $6000
`cart-freeze` | Press cartridge freeze button
`debug-autoplayback-frames` | Set autoplayback frames
`debug-blitter-log-toggle` | Toggle blitter logging
`debug-core-dump-toggle` | Toggle saving core dump
`debug-dma-log-toggle` | Toggle DMA logging
`debug-flash-log-toggle` | Toggle Flash logging
`debug-trace-cpu-toggle` | Toggle CPU trace
`debug-trace-drive-10-toggle` | Toggle drive 10 CPU trace
`debug-trace-drive-11-toggle` | Toggle drive 11 CPU trace
`debug-trace-drive-8-toggle` | Toggle drive 8 CPU trace
`debug-trace-drive-9-toggle` | Toggle drive 9 CPU trace
`debug-trace-iec-toggle` | Toggle IEC bus trace
`debug-trace-ieee488-toggle` | Toggle IEEE-488 bus trace
`debug-trace-mode` | Select machine/drive CPU trace mode
`diagnostic-pin-toggle` | Toggle PET userport diagnostic pin
`drive-attach-10:0` | Attach disk to unit 10, drive 0
`drive-attach-10:1` | Attach disk to unit 10, drive 1
`drive-attach-11:0` | Attach disk to unit 11, drive 0
`drive-attach-11:1` | Attach disk to unit 11, drive 1
`drive-attach-8:0` | Attach disk to unit 8, drive 0
`drive-attach-8:1` | Attach disk to unit 8, drive 1
`drive-attach-9:0` | Attach disk to unit 9, drive 0
`drive-attach-9:1` | Attach disk to unit 9, drive 1
`drive-create` | Create and attach empty disk image
`drive-detach-10:0` | Detach disk from unit 10, drive 0
`drive-detach-10:1` | Detach disk from unit 10, drive 1
`drive-detach-11:0` | Detach disk from unit 11, drive 0
`drive-detach-11:1` | Detach disk from unit 11, drive 1
`drive-detach-8:0` | Detach disk from unit 8, drive 0
`drive-detach-8:1` | Detach disk from unit 8, drive 1
`drive-detach-9:0` | Detach disk from unit 9, drive 0
`drive-detach-9:1` | Detach disk from unit 9, drive 1
`edit-copy` | Copy screen content to clipboard
`edit-paste` | Paste clipboard content into machine
`fliplist-add-10:0` | Add current disk in unit 10, drive 0 to fliplist
`fliplist-add-10:1` | Add current disk in unit 10, drive 1 to fliplist
`fliplist-add-11:0` | Add current disk in unit 11, drive 0 to fliplist
`fliplist-add-11:1` | Add current disk in unit 11, drive 1 to fliplist
`fliplist-add-8:0` | Add current disk in unit 8, drive 0 to fliplist
`fliplist-add-8:1` | Add current disk in unit 8, drive 1 to fliplist
`fliplist-add-9:0` | Add current disk in unit 9, drive 0 to fliplist
`fliplist-add-9:1` | Add current disk in unit 9, drive 1 to fliplist
`fliplist-clear-10:0` | Clear fliplist of unit 10, drive 0
`fliplist-clear-10:1` | Clear fliplist of unit 10, drive 1
`fliplist-clear-11:0` | Clear fliplist of unit 11, drive 0
`fliplist-clear-11:1` | Clear fliplist of unit 11, drive 1
`fliplist-clear-8:0` | Clear fliplist of unit 8, drive 0
`fliplist-clear-8:1` | Clear fliplist of unit 8, drive 1
`fliplist-clear-9:0` | Clear fliplist of unit 9, drive 0
`fliplist-clear-9:1` | Clear fliplist of unit 9, drive 1
`fliplist-load-10:0` | Load fliplist for unit 10, drive 0
`fliplist-load-10:1` | Load fliplist for unit 10, drive 1
`fliplist-load-11:0` | Load fliplist for unit 11, drive 0
`fliplist-load-11:1` | Load fliplist for unit 11, drive 1
`fliplist-load-8:0` | Load fliplist for unit 8, drive 0
`fliplist-load-8:1` | Load fliplist for unit 8, drive 1
`fliplist-load-9:0` | Load fliplist for unit 9, drive 0
`fliplist-load-9:1` | Load fliplist for unit 9, drive 1
`fliplist-next-10:0` | Attach next disk in fliplist to unit 10, drive 0
`fliplist-next-10:1` | Attach next disk in fliplist to unit 10, drive 1
`fliplist-next-11:0` | Attach next disk in fliplist to unit 11, drive 0
`fliplist-next-11:1` | Attach next disk in fliplist to unit 11, drive 1
`fliplist-next-8:0` | Attach next disk in fliplist to unit 8, drive 0
`fliplist-next-8:1` | Attach next disk in fliplist to unit 8, drive 1
`fliplist-next-9:0` | Attach next disk in fliplist to unit 9, drive 0
`fliplist-next-9:1` | Attach next disk in fliplist to unit 9, drive 1
`fliplist-previous-10:0` | Attach previous disk in fliplist to unit 10, drive 0
`fliplist-previous-10:1` | Attach previous disk in fliplist to unit 10, drive 1
`fliplist-previous-11:0` | Attach previous disk in fliplist to unit 11, drive 0
`fliplist-previous-11:1` | Attach previous disk in fliplist to unit 11, drive 1
`fliplist-previous-8:0` | Attach previous disk in fliplist to unit 8, drive 0
`fliplist-previous-8:1` | Attach previous disk in fliplist to unit 8, drive 1
`fliplist-previous-9:0` | Attach previous disk in fliplist to unit 9, drive 0
`fliplist-previous-9:1` | Attach previous disk in fliplist to unit 9, drive 1
`fliplist-remove-10:0` | Remove current disk in unit 10, drive 0 from fliplist
`fliplist-remove-10:1` | Remove current disk in unit 10, drive 1 from fliplist
`fliplist-remove-11:0` | Remove current disk in unit 11, drive 0 from fliplist
`fliplist-remove-11:1` | Remove current disk in unit 11, drive 1 from fliplist
`fliplist-remove-8:0` | Remove current disk in unit 8, drive 0 from fliplist
`fliplist-remove-8:1` | Remove current disk in unit 8, drive 1 from fliplist
`fliplist-remove-9:0` | Remove current disk in unit 9, drive 0 from fliplist
`fliplist-remove-9:1` | Remove current disk in unit 9, drive 1 from fliplist
`fliplist-save-10:0` | Save fliplist of unit 10, drive 0
`fliplist-save-10:1` | Save fliplist of unit 10, drive 1
`fliplist-save-11:0` | Save fliplist of unit 11, drive 0
`fliplist-save-11:1` | Save fliplist of unit 11, drive 1
`fliplist-save-8:0` | Save fliplist of unit 8, drive 0
`fliplist-save-8:1` | Save fliplist of unit 8, drive 1
`fliplist-save-9:0` | Save fliplist of unit 9, drive 0
`fliplist-save-9:1` | Save fliplist of unit 9, drive 1
`fullscreen-decorations-toggle` | Show menu/status in fullscreen
`fullscreen-toggle` | Toggle fullscreen
`help-about` | Show About dialog
`help-command-line` | Show command line options
`help-compile-time` | Show compile time features
`help-hotkeys` | Show hotkeys
`help-manual` | Browse VICE manual
`history-milestone-reset` | Return to recording milestone
`history-milestone-set` | Set recording milestone
`history-playback-start` | Start playing back events
`history-playback-stop` | Stop playing back events
`history-record-start` | Start recording events
`history-record-stop` | Stop recording events
`hotkeys-clear` | Clear all hotkeys
`hotkeys-default` | Load default hotkeys
`hotkeys-load` | Load hotkeys from current file
`hotkeys-load-from` | Load hotkeys from custom file
`hotkeys-save` | Save hotkeys to current file
`hotkeys-save-to` | Save hotkeys to custom file
`keyset-joystick-toggle` | Allow keyset joysticks
`machine-power-cycle` | Power cycle the machine
`machine-reset-cpu` | Reset the machine CPU
`media-record` | Start recording media
`media-record-audio` | Start recording audio
`media-record-screenshot` | Take screenshot
`media-record-video` | Start recording video
`media-stop` | Stop media recording
`monitor-open` | Open monitor
`mouse-grab-toggle` | Toggle Mouse Grab
`pause-toggle` | Toggle Pause
`printer-formfeed-4` | Send form feed to printer #4
`printer-formfeed-5` | Send form feed to printer #5
`printer-formfeed-6` | Send form feed to plotter #6
`printer-formfeed-userport` | Send form feed to userport printer
`psid-ffwd` | Fast forward
`psid-load` | Load PSID file
`psid-loop-toggle` | Toggle looping
`psid-override-toggle` | Override PSID settings
`psid-pause` | Pause playback
`psid-play` | Play
`psid-playlist-add` | Add files to the playlist
`psid-playlist-clear` | Clear the playlist
`psid-playlist-first` | Play first tune in the playlist
`psid-playlist-last` | Play last tune in the playlist
`psid-playlist-load` | Load a playlist
`psid-playlist-next` | Play next tune in the playlist
`psid-playlist-previous` | Play previous tune in the playlist
`psid-playlist-save` | Save the playlist
`psid-stop` | Stop playback
`psid-subtune-1` | Play subtune #1
`psid-subtune-10` | Play subtune #10
`psid-subtune-11` | Play subtune #11
`psid-subtune-12` | Play subtune #12
`psid-subtune-13` | Play subtune #13
`psid-subtune-14` | Play subtune #14
`psid-subtune-15` | Play subtune #15
`psid-subtune-16` | Play subtune #16
`psid-subtune-17` | Play subtune #17
`psid-subtune-18` | Play subtune #18
`psid-subtune-19` | Play subtune #19
`psid-subtune-2` | Play subtune #2
`psid-subtune-20` | Play subtune #20
`psid-subtune-21` | Play subtune #21
`psid-subtune-22` | Play subtune #22
`psid-subtune-23` | Play subtune #23
`psid-subtune-24` | Play subtune #24
`psid-subtune-25` | Play subtune #25
`psid-subtune-26` | Play subtune #26
`psid-subtune-27` | Play subtune #27
`psid-subtune-28` | Play subtune #28
`psid-subtune-29` | Play subtune #29
`psid-subtune-3` | Play subtune #3
`psid-subtune-30` | Play subtune #30
`psid-subtune-4` | Play subtune #4
`psid-subtune-5` | Play subtune #5
`psid-subtune-6` | Play subtune #6
`psid-subtune-7` | Play subtune #7
`psid-subtune-8` | Play subtune #8
`psid-subtune-9` | Play subtune #9
`psid-subtune-default` | Play default subtune
`psid-subtune-next` | Play next subtune
`psid-subtune-previous` | Play previous subtune
`quit` | Quit emulator
`reset-drive-10` | Reset drive 10
`reset-drive-10-config` | Reset drive 10 in configuration mode
`reset-drive-10-install` | Reset drive 10 in installation mode
`reset-drive-11` | Reset drive 11
`reset-drive-11-config` | Reset drive 11 in configuration mode
`reset-drive-11-install` | Reset drive 11 in installation mode
`reset-drive-8` | Reset drive 8
`reset-drive-8-config` | Reset drive 8 in configuration mode
`reset-drive-8-install` | Reset drive 8 in installation mode
`reset-drive-9` | Reset drive 9
`reset-drive-9-config` | Reset drive 9 in configuration mode
`reset-drive-9-install` | Reset drive 9 in installation mode
`restore-display` | Resize window to fit content
`scpu-jiffy-switch-toggle` | Toggle SCPU JiffyDOS switch
`scpu-speed-switch-toggle` | Toggle SCPU Speed switch
`screenshot-quicksave` | Quiksave screenshot
`settings-default` | Restore default settings
`settings-dialog` | Open settings
`settings-load` | Load settings
`settings-load-extra` | Load additional settings
`settings-load-from` | Load settings from custom file
`settings-save` | Save settings
`settings-save-to` | Save settings to custom file
`show-statusbar-secondary-toggle` | Show secondary status bar
`show-statusbar-toggle` | Show status bar
`smart-attach` | Smart-attach a medium to the emulator
`snapshot-load` | Load snapshot file
`snapshot-quickload` | Quickload snapshot
`snapshot-quicksave` | Quicksave snapshot
`snapshot-save` | Save snapshot file
`speed-cpu-10` | Set CPU speed to 10%
`speed-cpu-100` | Set CPU speed to 100%
`speed-cpu-200` | Set CPU speed to 200%
`speed-cpu-25` | Set CPU speed to 25%
`speed-cpu-50` | Set CPU speed to 50%
`speed-cpu-custom` | Set custom CPU speed
`speed-fps-50` | Set video clock to 50Hz
`speed-fps-60` | Set video clock to 60Hz
`speed-fps-custom` | Set custom video clock
`speed-fps-real` | Set real video clock
`swap-controlport-toggle` | Swap controlport joysticks
`tape-attach-1` | Attach tape to datasette 1
`tape-attach-2` | Attach tape to datasette 2
`tape-create-1` | Create tape and attach to datasette 1
`tape-create-2` | Create tape and attach to datasette 2
`tape-detach-1` | Detach tape from datasette 1
`tape-detach-2` | Detach tape from datasette 2
`tape-ffwd-1` | Press FFWD on datasette 1
`tape-ffwd-2` | Press FFWD on datasette 2
`tape-play-1` | Press PLAY on datasette 1
`tape-play-2` | Press PLAY on datasette 2
`tape-record-1` | Press RECORD on datasette 1
`tape-record-2` | Press RECORD on datasette 2
`tape-reset-1` | Reset datasette 1
`tape-reset-2` | Reset datasette 2
`tape-reset-counter-1` | Reset datasette 1 counter
`tape-reset-counter-2` | Reset datasette 2 counter
`tape-rewind-1` | Press REWIND on datasette 1
`tape-rewind-2` | Press REWIND on datasette 2
`tape-stop-1` | Press STOP on datasette 1
`tape-stop-2` | Press STOP on datasette 2
`virtual-keyboard` | Activate virtual keyboard
`warp-mode-toggle` | Toggle Warp Mode

To see which emulators support which actions please look at `src/arch/shared/uiactions.c` or use "Help" -> "Hotkeys" in an emulator.

### 3.5.5 Syntax highlighting

Vim syntax highlighting files can be found in doc/vim/. Currently there are two files: `syntax/vhk.vim` and `ftdetect/vhk.vim`, these can be copied to `$VIMFILES/` to enable hotkeys syntax highlighting in Vim.

Go to the first, previous, next, last section, table of contents.