VICE SDL UK Keyboard Mapping File - cressie176/Load64 GitHub Wiki

1. Overview

A VICE keyboard mapping file (.kvm / .vkm) defines how host keyboard keysyms or scancodes map to the Commodore 64 keyboard matrix inside the VICE emulator. It is useful when mapping keys to controller events.

Each normal mapping line uses the format:

keysym row column shiftflag

Where:

  • keysym is the SDL keysym or scancode
  • row and column are C64 matrix coordinates
  • shiftflag is a bitmask controlling modifier behaviour

2. File Structure

2.1. Keyword Directives

Keyword Description
!CLEAR Clear entire mapping table
!INCLUDE filename Include another mapping file
!LSHIFT row col Define left shift position
!RSHIFT row col Define right shift position
!VSHIFT shiftkey Virtual shift key
!SHIFTL shiftkey Shift lock key
!LCTRL row col Left control key
!VCTRL ctrlkey Virtual control key
!LCBM row col Left CBM key
!VCBM cbmkey Virtual CBM key
!UNDEF keysym Remove keysym mapping

2.2 Shiftflag Bitmask Values

Hex Decimal Meaning
0x0000 0 No shift
0x0001 1 Combined with shift
0x0002 2 Left shift on emulated system
0x0004 4 Right shift on emulated system
0x0008 8 Key may be shifted or not
0x0010 16 Deshift key
0x0020 32 Another definition follows
0x0040 64 Shift lock
0x0080 128 Host shift required
0x0200 512 Host Alt-Gr required
0x0400 1024 Host Ctrl required
0x0800 2048 Combined with CBM
0x1000 4096 Combined with Ctrl
0x2000 8192 Left CBM on emulated system
0x4000 16384 Left Ctrl on emulated system

2.3 Negative Row Values

Row Meaning
-1 Joystick keymap A
-2 Joystick keymap B
-3 RESTORE key
-4 40/80 column or CAPS
-5 Joyport keypad

2.4 C64 Keyboard Matrix

This is the C64 keyboard matrix as referenced by row and column.

        Col0  Col1  Col2  Col3  Col4  Col5  Col6  Col7
Row0    DEL   RET   C_LR  F7    F1    F3    F5    C_UD
Row1    3#    W     A     4$    Z     S     E     SL
Row2    5%    R     D     6&    C     F     T     X
Row3    7'    Y     G     8(    B     H     U     V
Row4    9)    I     J     0     M     K     O     N
Row5    +     P     L     -     .>    :[    @     ,<
Row6    £     *     ;]    HOME  SR    =     ↑     /?
Row7    1!    ←     CTRL  2"    SPACE C=    Q     RUN/STOP

2.5 C64 Keyboard Layout

 arrow 1! 2" 3# 4$ 5% 6& 7' 8( 9) 0 + - £ clr del     f1/f2
 ctrl  q  w  e  r  t  y  u  i  o  p  @  *  ^ restore    f3/f4
 r/s   SL a  s  d  f  g  h  j  k  l  :  ;  = return     f5/f6
 CBM   LS z  x  c  v  b  n  m  ,  .  /  RS u/d l/r      f7/f8
                         space

2.6 Host to C64 Mapping Summary

C64 Key Modern Key VICE value
SPACE Space 7 4
RETURN Enter 0 1
RUN/STOP Esc 7 7
RESTORE Page Up -3 0
CTRL Tab 7 2
C= Left Ctrl 7 5
Left Shift Left Shift 1 7
Right Shift Right Shift 6 4
Shift Lock Caps Lock 1 7
DEL Backspace 0 0
CLR/HOME Home 6 3
CRSR Up Up Arrow 0 7 (shifted)
CRSR Down Down Arrow 0 7
CRSR Left Left Arrow 0 2 (shifted)
CRSR Right Right Arrow 0 2

2.7 Function Keys

C64 Key Modern Key VICE value
F1 F1 0 4
F2 F2 0 4 (shifted)
F3 F3 0 5
F4 F4 0 5 (shifted)
F5 F5 0 6
F6 F6 0 6 (shifted)
F7 F7 0 3
F8 F8 0 3 (shifted)

2.8 Joyport Keypad Mapping

Negative row -5 with index 0 to 19.

Host key VICE value Notes
NumLock -5 0 keypad x0
ScrollLock -5 5 keypad x1
SysReq -5 10 keypad x2
PrtScr -5 15 keypad x3
NumPad 7 -5 1
NumPad 8 -5 2
NumPad 9 -5 3
NumPad / -5 4
NumPad 4 -5 6
NumPad 5 -5 7
NumPad 6 -5 8
NumPad * -5 9
NumPad 1 -5 11
NumPad 2 -5 12
NumPad 3 -5 13
NumPad - -5 14
NumPad 0 -5 16
NumPad , -5 17 keypad .
NumPad Enter -5 18
NumPad + -5 19

2.9 Notes

  • SDL does not emit events for dead keys. A nodeadkeys layout must be used.
  • Switching host layout while VICE is running may corrupt keycodes.
  • For single shift emulated keyboards, both !LSHIFT and !RSHIFT must reference the same matrix position.
⚠️ **GitHub.com Fallback** ⚠️