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/local'), 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/local/bin/x64

then the value will be

$HOME/.local/share/vice/C64:/usr/local/share/vice/C64:/usr/local/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/local/share/vice/C64
3. /usr/local/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:

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:

Joyport keypad direction column values for row -5:

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:

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/local/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/local/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

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

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.