search

indigodarkwolf / box16

A fork of the official X16 emulator, converted to C++20 and with a bunch of features tweaked and added.
MIT License
41 stars 18 forks source link

readme

Box16

Build status
Release

This is an emulator for the Commander X16 computer system. Unlike the official emulator, this has a few more dependencies, see the build instructions below. It compiles on Windows, Debian Linux, and Raspbian, and probably other Linux-based platforms.

Don't expect official "releases" until the physical X16 is out. Until then, there will be "non-releases" of Box16. Since this is originally forked from the Official X16 emulator, the goal is to remain fully compatible with the Official X16 emulator, but with feature-adds such as ImGui displays, and performance improvements from OpenGL acceleration.

Some of the feature-adds will be prototype or preview in nature, as this is also my platform for fixing bugs and adding features to the official emulator.

Features

Missing Features

Binaries & Compiling

The emulator itself is dependent on SDL2 and OpenGL. However, to run the emulated system you will also need a compatible rom.bin ROM image. This will be loaded from the directory containing the emulator binary, or you can use the -rom .../path/to/rom.bin option.

WARNING: Older versions of the ROM might not work in newer versions of the emulator, and vice versa.

You can build a ROM image yourself using the build instructions in the x16-rom repo. The rom.bin included in the latest release of the emulator may also work with the HEAD of this repo, but this is not guaranteed.

Linux Build

Read resources/r41/README.box16 and build or acquire the necessary files.

The needed development packages are available as a distribution package with most major versions of Linux:

Type make to build the source. The output will be box16 in the output directory. Remember you will also need a rom.bin as described above.

Windows Build

Read resources/r41/README.box16 and build or acquire the necessary files.

Install Microsoft Visual Studio Community 2022, make sure to include the following modules:

Open build\vs2019\box16.sln with Visual Studio Community 2022. Select Build All from the Build menu.

The built .exe and associated files should be located in build\vs2022\out, plus a few more subdirectories based on the exact build generated.

Releases

As of 3 May 2022, the only release process is to package up the Windows builds. Creating these packages are meant as a convenience for Windows users who may not be willing to build Box16 for themselves.

Building release zips

Follow the instructions for making a Windows build, above.

Install the Windows Subsystem for Linux (WSL2). See the instructions at https://docs.microsoft.com/en-us/windows/wsl/install. As of 27 April 2022, most of this should be as simple as running "wsl --install" from a PowerShell or Windows Command Prompt with administrator permissions.

The needed development packages are available as a distribution package with most major versions of Linux, even for WSL2.

In the Linux shell, go to the build directory from your Box16 repository directory.

Type make release to create all the zip files.

Starting

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

Run box16 -help 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.

GIF Recording

With the argument -gif, followed by a filename, a screen recording will be saved into the given GIF file. Please exit the emulator before reading the GIF file.

If the option ,wait is specified after the filename, it will start recording on POKE $9FB5,2. It will capture a single frame on POKE $9FB5,1 and pause recording on POKE $9FB5,0.

PEEK($9FB5) returns a 0 if recording is disabled, 1 if recording is enabled but not active, 2 if snapshotting a single frame, and 3 if recording.

WAV Recording

With the argument -wav, followed by a filename, a audio recording will be saved into the given WAV file. Please exit the emulator before reading the WAV file.

If the option ,wait is specified after the filename, it will start recording on POKE $9FB6,1. If the option ,auto is specified after the filename, it will start recording on the first non-zero audio signal, or on POKE $9FB6,1. POKE $9FB6,0 will pause recording, and POKE $9FB6,2 will pause recording until the next non-zero audio signal.

PEEK($9FB6) returns 0 if recording is disabled, 1 if recording is enabled but not active, 2 if recording is paused waiting on a non-zero audio signal, and 3 if recording.

BASIC and the Screen Editor

On startup, the X16 presents direct mode of BASIC V2. You can enter BASIC statements, or line numbers with BASIC statements and RUN the program, just like on Commodore computers.

SD Card Images

The command line argument -sdcard lets you attach an image file for the emulated SD card. Using an emulated SD card makes filesystem operations go through the X16's DOS implementation, so it supports all filesystem operations (including directory listing though DOS"$ command channel commands using the DOS statement) and guarantees full compatibility with the real device.

Images must be greater than 32 MB in size and contain an MBR partition table and a FAT32 filesystem. The file sdcard.img.zip in this repository is an empty 100 MB image in this format.

On macOS, you can just double-click an image to mount it, or use the command line:

# hdiutil attach sdcard.img
/dev/disk2              FDisk_partition_scheme
/dev/disk2s1            Windows_FAT_32                  /Volumes/X16 DISK
# [do something with the filesystem]
# hdiutil detach /dev/disk[n] # [n] = number of device as printed above

On Linux, you can use the command line:

# sudo losetup -P /dev/loop21 disk.img
# sudo mount /dev/loop21p1 /mnt # pick a location to mount it to, like /mnt
# [do something with the filesystem]
# sudo umount /mnt
# sudo losetup -d /dev/loop21

On Windows, you can use the OSFMount tool.

Host Filesystem Interface

If the system ROM contains any version of the KERNAL, and there is no SD card image attached, the LOAD ($FFD5) and SAVE ($FFD8) KERNAL calls (and BASIC statements) are intercepted by the emulator for device 8 (the default). So the BASIC statements will target the host computer's local filesystem:

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

Note that this feature is very limited! Manually reading and writing files (e.g. OPEN in BASIC) is not supported by the host filesystem interface. Use SD card images for this.

The emulator will interpret filenames relative to the directory it was started in. On macOS, when double-clicking the executable, this is the home directory.

To avoid incompatibility problems between the PETSCII and ASCII encodings, you can

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

There are a number of debugging windows that can be displayed:

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.

The STP instruction (opcode $DB) 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.

Forum

https://www.commanderx16.com/forum/

Wiki

https://github.com/commanderx16/x16-emulator/wiki

License

Copyright (c) 2019-2023 Michael Steil <mist64@mac.com>, www.pagetable.com, et al.
Portions copyright (c) 2021-2023 Stephen Horn, et al.
All rights reserved. License: 2-clause BSD

Release Notes

Non-Release 41.1 ("Koutoubia Mosque")