Commander X16 Emulator

This is an emulator for the Commander X16 computer system. It only depends on SDL2 and should compile on all modern operating systems.

Binaries & Compiling

Binary releases for macOS, Windows and x86_64 Linux are available on the releases page.

For all other systems, make sure the development version of SDL2 is installed and type make for build the source.

Starting

You can start x16emu/x16emu.exe either by double-clicking it, or from the command line. The latter allows you to specify additional arguments.

Run x16emu -h to see all command line options.

Keyboard Layout

The X16 uses a PS/2 keyboard, and the ROM currently supports several different layouts. The following table shows their names, and what keys produce different characters than expected:

Name Description Differences
en-us US [`] ⇒ [←], [~] ⇒ [π], [\] ⇒ [£]
en-gb United Kingdom [`] ⇒ [←], [~] ⇒ [π]
de German [§] ⇒ [£], [´] ⇒ [^], [^] ⇒ [←], [°] ⇒ [π]
nordic Nordic key left of [1] ⇒ [←],[π]
it Italian [\] ⇒ [←], [|] ⇒ [π]
pl Polish (Programmers) [`] ⇒ [←], [~] ⇒ [π], [\] ⇒ [£]
hu Hungarian [\] ⇒ [←], [|] ⇒ [π], [§] ⇒ [£]
es Spanish [|] ⇒ π, \ ⇒ [←], Alt + [<] ⇒ [£]
fr French [²] ⇒ [←], [§] ⇒ [£]
de-ch Swiss German [^] ⇒ [←], [°] ⇒ [π]
fr-be Belgian French [²] ⇒ [←], [³] ⇒ [π]
fi Finnish [§] ⇒ [←], [½] ⇒ [π]
pt-br Portuguese (Brazil ABNT) [\] ⇒ [←], [|] ⇒ [π]

Keys that produce international characters (like [ä] or [ç]) will not produce any character.

Since the emulator tells the computer the position of keys that are pressed, you need to configure the layout for the computer independently of the keyboard layout you have configured on the host.

Use the F9 key to cycle through the layouts, or set the keyboard layout at startup using the -keymap command line argument.

The following keys can be used for controlling games:

Keyboard Key NES Equivalent
Ctrl A
Alt B
Space SELECT
Enter START
Cursor Up UP
Cursor Down DOWN
Cursor Left LEFT
Cursor Right RIGHT

Functions while running

On the Mac, use the Cmd key instead.

Host Filesystem Interface

If the system ROM contains any version of the KERNAL, the LOAD ($FFD5) and SAVE ($FFD8) KERNAL calls are intercepted by the emulator if the device is 1 (which is the default). So the BASIC statements

  LOAD"$
  LOAD"FOO.PRG
  LOAD"IMAGE.PRG",1,1
  SAVE"BAR.PRG

will target the host computer's local filesystem.

The emulator will interpret filesnames relative to the directory it was started in. Note that on macOS, when double-clicking the executable, this is the home directory.

To avoid incompatibility problems between the PETSCII and ASCII encodings, use lower case filenames on the host side, and unshifted filenames on the X16 side.

Dealing with BASIC Programs

BASIC programs are encoded in a tokenized form, they are not simply ASCII files. If you want to edit BASIC programs on the host's text editor, you need to convert it between tokenized BASIC form and ASCII.

Using the KERNAL/BASIC environment

Please see the KERNAL/BASIC documentation.

Debugger

The debugger requires -debug to start. Without it it is effectively disabled.

There are 2 panels you can control. The code panel, the top left half, and the data panel, the bottom half of the screen. The displayed address can be changed using keys 0-9 and A-F, in a 'shift and roll' manner (easier to see than explain). To change the data panel address, press the shift key and type 0-9 A-F. The top write panel is fixed.

The debugger keys are similar to the Microsoft Debugger shortcut keys, and work as follows

Key Description
F1 resets the shown code position to the current PC
F2 resets the 65C02 CPU but not any of the hardware.
F5 is used to return to Run mode, the emulator should run as normal.
F9 sets the breakpoint to the currently code position.
F10 steps 'over' routines - if the next instruction is JSR it will break on return.
F11 steps 'into' routines.
F12 is used to break back into the debugger. This does not happen if you do not have -debug
TAB when stopped, or single stepping, hides the debug information when pressed

When -debug is selected the No-Operation $FF will break into the debugger automatically.

Effectively keyboard routines only work when the debugger is running normally. Single stepping through keyboard code will not work at present.

Features

Missing Features

License

Copyright (c) 2019 Michael Steil <mist64@mac.com>, www.pagetable.com. All rights reserved. License: 2-clause BSD

Release Notes

Release 30

Emulator:

Release 29

Release 28

Release 27

Release 26

Release 25

Release 24

Release 23

Release 22

SYS65375 (SWAPPER) now also clears the screen, avoid ing side effects.

Release 21

Release 20

Release 19

Release 18

Release 17

Release 16

Release 15

Release 14

Release 13

Release 12

Release 11

Release 10

updated KERNAL with proper power-on message

Release 9

Release 8

Release 7

Release 6

Release 5

Release 4

Release 3

Release 2

Release 1