The Emulator

BitMagic emulates the Commander X16 for general use. The same core also drives the debugger.

Download

There are two ways to get the emulator, on Windows or Linux.

Install as a .NET tool

If you have the .NET SDK installed, this is the simplest route:

dotnet tool install -g BitMagic.X16E

This puts x16e on your PATH, so you can run it from any folder. For a development build, add --prerelease.

A .NET tool doesn’t auto-update. To pick up a newer version later, run dotnet tool update -g BitMagic.X16E.

Download a build

Alternatively, grab the latest build: Windows or Linux. There is no automatic update, so check back for newer builds.

You can also clone the repository and build the emulator project.

Prerequisites

Before you can run the emulator, you’ll need a copy of the ROM. The quickest way is to let the emulator fetch it:

x16e --fetch-rom

On Linux the emulator also needs SDL2, OpenGL and OpenAL, and --fetch-rom needs curl and unzip. On Debian or Ubuntu:

sudo apt install libsdl2-2.0-0 libgl1 libopenal1 curl unzip

If you downloaded a build, check-prerequisites.sh in its folder checks all of these for you.

Emulator state

The emulator is under active development. The CPU, VERA (including PSG, PCM and FX), the YM2151, the VIA, the SMC, the RTC, the SD card and the WiFi card (the serial modem, via ZiModem) are all emulated. It aims to match the official X16 emulator; it is close but not exact. Open gaps and differences are tracked on the issue tracker.

Known limitations:

• Tile rendering and its access to VRAM is not yet cycle accurate, which can lead to slight differences from hardware.
• The SMC module doesn’t support writing config to the PS/2, reading its state, or the echo functionality.
• Frame syncing is based on the host monitor’s refresh and isn’t exact.
• Mouse movement is generated by the host and can overwhelm the X16; a buffer is needed.

Command line

Argument	Description
-p --prg	.prg file to run. It’s copied to the root of the SD card with an AUTOBOOT.X16 that loads and runs it, so the X16 boots normally first. An existing AUTOBOOT.X16 on the card is left alone.
-r --rom	ROM file to load. Falls back to rom.bin in the current folder, then the BITMAGIC_ROM environment variable, then the folder --fetch-rom saves to.
--fetch-rom	Download the latest ROM into your BitMagic folder, then exit.
-c --code	Code file to compile. The result is loaded at 0x801 and run from 0x810.
-w --write	Write the result of the compilation. Requires --code.
--warp	Run as fast as possible.
--scale	Window scale, e.g. 2 for double size. Default 1.
--mute	Don’t play audio. Only the output is silenced, emulation is unaffected.
-s --sdcard	SD card to attach. Can be a .zip or .gz, in the form name.xxx.zip where xxx is BIN or VHD.
--sdcard-size	SD card size in MB, if the emulator is creating the card.
-d --sdcard-folder	Home folder for the SD card.
--sdcard-synctox16	Sync changes in the home directory to the SD card. Root directory only.
--sdcard-syncfromx16	Sync changes on the SD card to the home directory. Root directory only.
-y --sdcard-sync	Both of the above.
-f --sdcard-file	File to add to the SD card root. Repeatable; wildcards accepted.
--sdcard-write	SD card file to write at the end of emulation. .zip / .gz, name.xxx.zip, xxx is BIN or VHD.
--sdcard-overwrite	Allow --sdcard-write to overwrite an existing file.
-u --sdcard-update	Sets --sdcard-write to the --sdcard value and enables overwrite. Requires --sdcard.
--cart	Cartridge file to load as a plain binary. .zip / .gz, in the form name.cart.zip.
--wifi	Enable the WiFi card at $9fe0.
--dump	Start from the state in a dump file.
--dump-folder	Folder to write dump files to (Menu + Left Ctrl + S).
--help	Display the help screen.
--version	Display version information.

See SD Card for how the card options fit together.