The manual for the latest openMSX release can be found on the openMSX home page:
This manual is about openMSX, the open source MSX emulator that tries to achieve near-perfect emulation by using a novel emulation model. You can find more information about openMSX on the openMSX home page. You can also download the emulator itself from there.
openMSX is not completed yet, which means that most things work but not all features are implemented yet. Many emulation features are implemented, but not all of them are represented yet in the built-in Graphical User Interface. To get the most out of openMSX, we have written this guide.
This manual tells you how you can use openMSX, once it has been installed and properly set up. You should be able to use most of the features of openMSX if you have read it. If you are only using the GUI menus of openMSX, you don't have to pay attention to the exact command and setting names. However it is still useful to read this document to find out how openMSX works and learn its terminology.
Disclaimer: We do not claim this guide is complete or even correct. What you do with the information in it is entirely at your own risk. We just hope it helps you enjoy openMSX more.
For the revision history, please refer to the commit log.
In this chapter we will tell you how to select MSX machines and how to use extension cartridges, when starting up openMSX.
If you start openMSX without any command line parameters, you will get the
default machine, which is stored in the default_machine setting, see
the Setup Guide. If you did
not change the default machine, the C-BIOS MSX2+ machine will be started.
To select machines from the GUI, click This will give a window in which you can see an overview of all available machines to select from and hovering on items in the list shows you the most important properties of these machines. You can also filter on type, region or any part of the machine names. You can replace the current machine, or run another machine along the existing running machines. An overview of the running machines is shown at the top of the machine selection window, where you can also change the default machine.
To select a different MSX machine from the command line, you can use the
-machine argument:
It is also possible to use the machine command to switch at run time
in the console, which is explained in
the next chapter.
The C-BIOS machines come with ROMs installed; for other machines you will have to install system ROMs yourself, see the Setup Guide for details. You can always use to verify which system ROMs have been (correctly) installed.
Extensions are simply MSX cartridges (extensions to the MSX system) that you can plug into the emulated MSX. openMSX ships with a lot of predefined extensions. Note that many of them require firmware ROMs (called system ROMs); see the Setup Guide for details.
Using the GUI, use the menu where you can either first select the MSX cartridge slot to put the extension into, or directly select the menu option to insert an extension in the first free slot or remove extensions from the slot they're in.
Let's now go into details using the FMPAC as an example. openMSX ships with a
definition (XML file) for the FMPAC extension, but you will have to add the
fmpac.rom firmware ROM yourself. When you have done so, you can
insert an FMPAC into the emulated MSX machine with the following command line:
Similar to machines, you can also use the ext command in the console to do it at run
time. You can also use something like -extb to explicitly specify
cartridge slot B.
If you look in the share/extensions directory (or when using the
console, type the TAB key with the ext command, see next chapter),
you will see all the extensions known to openMSX. For example -ext
mbstereo gives you the MoonBlaster stereo effect: FMPAC on the left
speaker and MSX-AUDIO on the right speaker.
Some of the most used command line options will be discussed later in this manual. For a complete list of them, type the following command:
Most functionality can nowadays be controlled via the built in GUI, using the main menu bar as a starting point. This will be sufficient for most users. Originally, this GUI wasn't available and most functionality had to be controlled differently. This way of control is still available (and will remain so); this section will tell you more about it. You don't need to care about any of these commands if the GUI is sufficient for you, but we still recommend having a look at the sections about "Settings" and "Plugging in devices in connectors".
openMSX has a built-in command interface called the console, which allows you to control almost all aspects of openMSX while it is running. To access the console, make sure to have the main emulator window selected, and then press F10 (with default key mapping; Cmd+L on Mac). This will open a window with a command line inside the main openMSX window.
Typing help
gives a list of commands. Using PageUp you can see all of them. If you type
help [command] you will get help for the specified command. This
manual describes a few important commands; a full list can be found in the Console Command Reference. The
console can be used to change disk
images, plug in joysticks or mice, change settings at run time and to change key bindings,
among others. It actually gives you full control of openMSX: if it can't be
done via the console, it's probably impossible!
One very practical feature of the console command line is that you can use "completion" features. Just try typing half a command and then press the TAB key; openMSX will then try to finish the word you were typing or show the possibilities in case of ambiguities. You can use it also for file names, connectors, pluggables and settings, and even for machine and extension names.
The console has very common keyboard controls, similar to most text editors. It also supports copy/paste. Some other controls may be less obvious:
| key(s) | function |
|---|---|
| Up | show previous command from history (starting with current command line) |
| Down | show next command from history (starting with current command line) |
| Tab | attempt completion of current command |
| Enter/Return | execute command line |
You can reset your MSX with the console command reset and exit openMSX with the command
exit. As
explained in the previous chapter, you can change machines with the machine command and
you can insert extensions with the ext command (use tab-completion to see the
list of possible extension names). Remove extensions with the remove_extension command or
get a list of the currently inserted extensions with the list_extensions command. Other
commands will be discussed later on in this manual.
There are many settings in openMSX for customization, changing preferences or enabling extras. The most important ones are in the menu in the GUI. There is also an Advanced item in that menu that will give a huge window with all possible settings. Usually, you can revert a setting to its default value via in the context-menu of that setting.
Using the console, you can use the command set to change any setting. E.g., you can
use it to set the current scaler. Issuing
set with only the setting name (like set scale_algorithm), queries
the current value of that setting.
Settings that have only two possible values can also be toggled with the
toggle
command (an example is the default key binding of F11 to toggle
fullscreen, see also below). A (hopefully) complete list of settings can
also be found in the Console Command
Reference. Note that using the "tab completion" feature can help you a lot
in getting an idea of what settings are possible, as it will only complete
possible options. Just try that.
Let's give a few examples of common settings and how to change them.
If the MSX goes too fast or too slow, adjust the emulation speed with the
speed setting,
which has the speed percentage as parameter. So, typing set
speed 120, will run the emulated MSX at 120% of normal MSX speed.
This is useful for debugging purposes (slow down) or when you want to skip
certain parts of a demo for example (speed up). The GUI has this setting under
.
Some MSX machines like the Panasonic FS-A1GT have built in software (called
firmware) which can be switched on and off via a switch on the machine itself.
In openMSX the internal software is switched off by default, but you can switch
it on with the following setting: set firmwareswitch on. If the
currently running machine has a firmware switch, a toggle option will show up in
the menu to control it.
If you're not really interested in how long a real MSX would take to load
from diskette, cassette or laserdisc, you could enable the full speed when
loading feature: set fullspeedwhenloading on,
or from the GUI at . It
runs openMSX at maximum speed whenever it thinks that the MSX is loading. The
drawbacks: it might detect a bit too late that the MSX isn't loading anymore,
so sometimes the first notes of music played right after loading might be
fast. Also, when loading openMSX will use all available CPU power to get
maximum speed; the feature has no influence on the state of the MSX, of course.
You can save all your current settings with the save_settings command. At start
up, alternative settings files can be loaded by using the -setting
command line option. You can also use the load_settings command to load
settings at run time. Settings that are not mentioned in the saved settings
file that you are loading will be untouched. By default, openMSX will
automatically save your settings on exit (whichever way they were changed).
The menu will show you all connectors of the currently running machine and which (pluggable) device is currently plugged in. You can easily plug in other devices there, e.g. a mouse in a joystick port.
Examples of connectors are the joystick ports, the printer port, the MIDI in and out connector, the cassette port, etc. Examples of pluggables are joysticks and mice, but also printers and MIDI equipment.
In the console, you can use the command plug to do this. The command
plug
without any parameters will show a list of connectors and what pluggables are
plugged into them. Using plug [connector] will only show what is
plugged into [connector]. It will come as no surprise that the command plug
[connector] [pluggable] will plug the [pluggable] into the [connector].
Note that using the "tab completion" feature can help you a lot in getting an idea of what plug commands are possible, as it will only complete possible connectors and their possible pluggables. Just give it a try.
The Graphical User Interface (GUI) in openMSX has been built with the Dear ImGui library. It allows the developers to relatively easily build and extend the GUI for all supported platforms. The price we have to pay is that it only works on systems with 3D hardware acceleration support and that it does not look (a lot) like the native GUIs of well-known desktop environments like Windows, macOS, GNOME or KDE.
General help on basic usage of the Dear ImGui features can be found in the menu option.
The current GUI is intended for mouse control. It can (at least partially) also be controlled with a keyboard, but so far this has not been a major focus of development, so this will definitely not be optimal. Control via a game controller is currently disabled, but that may change in future versions.
Although the current openMSX release already has a lot of functionality available via the GUI, it is still incomplete and the user experience could use some love. We appreciate feedback on the GUI a lot and we will try to improve it in later releases based on your input. Please see section 10. Contact Info for more information on how to provide feedback.
Almost all commands and settings available in the GUI have an underlying console command and setting accessible via the console. In several places these underlying commands are mentioned in this manual. Power users especially will appreciate all the ways they can manipulate openMSX with external programs, scripts, or other more advanced methods.
As already mentioned before in this manual, the GUI has a Main menu bar at the top of the openMSX main window. The menu bar fades out when the MSX screen has focus. To get it back, move the mouse cursor to the top of the openMSX window.
The Main menu bar contains the following top level menus:
If you like, you can even undock the main menu bar from the main openMSX window. This is especially useful if you want to stream the openMSX main window, without showing your interaction with the openMSX menus. Use the triangular icon on the left in the Main menu bar to undock or redock it.
Besides the Main menu bar, some other main GUI elements you are likely to see. Here is a small overview.
The GUI allows you to put any window inside the main openMSX window, or outside of it. But windows can also be docked together, at the (left/right/top/bottom) edge of any window except the main window, even in a tab bar.
The GUI also has specific settings, like shortcuts that can be used in the GUI only.
Also, you can save and load layouts of windows that are combined with each other. This is still a rather rough feature, as it also saves and loads other data, like the history information from some menus.
As an example of a layout, we created one with a debugger focus. The image below shows:
With this information, you can run most of the existing MSX software. If you use the GUI, refer to the menu.
For all supported media files, there is a list of filename extensions that are
recognized by openMSX. If you run openMSX from the command line, adding a file
name (with path if necessary) as a command line option, openMSX will insert the
file as the proper type of media. The list of supported extensions for each
media type can be easily retrieved with -h option on the command
line. For some media, examples of command line usage are given below.
If you drag and drop a file with one of these supported extensions into the main openMSX window, openMSX will try to handle it accordingly.
In the GUI you can choose which ROM software you want to run by selecting a Cartridge Slot from the menu. This will open a window where you can tell openMSX exactly what you want to put in the slot, like a ROM image, which mapper to use if the automatically selected one isn't correct, and whether the MSX should be reset after inserting.
And finally, you can also browse for and select (multiple) IPS patches to apply to the selected ROM image. IPS patches are files that describe a modification of the ROM you are applying it to, e.g. a translation or a cheat. This way you do not need to alter the original files.
Using the command line, suppose you want to run the ROM file
galious.rom. Then you simply type:
and the emulated MSX will run the game. (Of course,
in this case, the file galious.rom should be in the current directory.
You can also explicitly indicate that the thing is a ROM image like this:
This lets openMSX know that the file galious.gam is a ROM
cartridge and that openMSX should insert it in the first available free
cartridge slot. You can also use -carta to explicitly specify
cartridge slot A.
In the event openMSX doesn't have the ROM in the ROM database and fails auto
detection of the mapper type, you can specify the mapper to Konami
(for instance) like this:
Note that in practice you won't need this, because most ROM images are in the
database or auto detected if they are not. The -romtype option
should follow the ROM it applies to immediately on the command line.
To apply an IPS patch using the command line, provide the IPS filename like this:
As with the -romtype option, the -ips option on the
command line must follow the ROM file it applies to directly. You can also use
multiple -ips options if you want to apply multiple patches.
If you already have openMSX running and want to insert cartridges at runtime
(maybe even when the MSX is powered on), you can use the carta command in the console as well, which is just as
powerful.
Of course this can only be done if the running machine has one or more disk drives. From the GUI, simply select the Disk Drive you want to change the disk image for. This will open a Disk Drive window where you can specify what must be in the drive: a disk image (select a disk image file, or create a new disk image), a directory to be used as disk (see next section), a RAM disk (temporary disk image in RAM), or nothing at all. As with ROM images, IPS patches can be selected to be applied.
Disk images in compressed format ((g)zip, xsa) can be used as regular disk images, but do note that they are read-only. Note that in zipped disk images, the first file that is packed into the zip file will be used as disk image.
To specify disk images on the command line, you can type:
for example. Or, if you use a disk image with a filename extension that is unknown to openMSX:
You can also change disks at run-time of course. Just type
in the console to put the specified disk image in drive A. To eject the disk from drive A, use:
Note that inserting another disk image automatically ejects the previous one.
To apply an IPS patch, provide the IPS filename like this:
On the command line, the -ips option must immediately follow the disk image
it applies to. You can also use multiple -ips options if you
want to apply multiple patches.
You can also apply the patches when changing disks at run-time in the console. Just type something like
in the console to put the specified gzipped disk image SDSNAT1C.DSK.gz in drive A, with both IPS patches applied.
The DirAsDsk feature permits you to use a directory on your host computer's file system as a disk image for your emulated MSX. Note that this has nothing to do with harddisk emulation. It simply creates a virtual disk structure in memory from the files that are in the directory that you specified as if it were a disk image. So, on the command line:
will try to put all files of the current directory on a disk image in memory and start openMSX with it. The actual data is still read from/written to the files in your directory so that if you change the contents of the files, these changes are immediately visible in the emulated MSX. This way you can for instance edit source files with your favourite text editor but compile them immediately in the emulated MSX.
Using the default value of the setting DirAsDSKmode (full), all changes to the directory on the host system and on the MSX system are performed, so that they are immediately visible to the other side. If this is not the desired behaviour, please check the documentation of that setting.
Be careful when writing to files from your emulated MSX. In the default 'full' mode, you can change/overwrite/delete/corrupt files on your host system, if you made them accessible for the emulated MSX! Still, this is the behaviour what most people want/expect and it's very useful if you know what you are doing.
Note that MSX disks only have a limited capacity, typically 720kB. If the host directory contains more data, then some host files will be ignored and they will not appear in the virtual disk image.
We do not recommend using real disks (e.g. with a USB floppy drive) with openMSX. There is no specific support for this.
openMSX has a special command to perform file imports and exports, with support for normal disk images, Sunrise IDE harddisk images with partitions (FAT12 only), and Nextor harddisk images with partitions (FAT12 and FAT16).
In the GUI, you can find this tool under . This will open a big window, which has many powerful options. On the left side you select the emulated machine drive (any existing drive, or the "Virtual drive" which only exists in memory). On the right side, you see the host directories with their file content. Use the arrows in the middle to transfer files, the plus button on the left side to create a new (hard) disk image and the directory button to browse for a disk image to insert.
For the console commands that are behind this window, please see the separate manual called Using diskmanipulator.
First thing you need to be aware of: this can only be done on machines that have a cassette port. Most do, but the MSX turboR machines do not, so tape software cannot be used on these machines.
Cassette/tape image file formats that are supported are WAV files (raw digitized recordings of real tapes) and CAS files. Differences are explained below.
In the GUI select to open the virtual cassette player control window, which allows you to insert a cassette tape image.
To insert a tape image from the console, type:
Once inserted, in MSX Basic, type:
(or another command to load the program on 'tape'.)
The cassetteplayer related commands/settings that are controlled in the tape deck window are:
cassetteplayer rewind, to rewind the tapecassetteplayer eject, to eject the tapecassetteplayer new <filename>, to create a new WAV cassette image to record to; also sets the cassette player in record modecassetteplayer play, to set the cassette player in play mode (when you've just recorded to the cassette)cassetteplayer record, to set the cassette player in record mode, to append to existing cassette images (NOT IMPLEMENTED YET)set cassetteplayer_volume, to set the volume of the cassette player sound (yeah, the screeching tape sounds!)
As you can see in this list, appending to existing cassette images (or
(partially) overwriting them) is not supported (yet). If you want to save
again, just insert a blank tape by using the cassetteplayer new
command again (or the Record button with the circle icon in the Tape Deck
window).
You can also use the so-called CAS files. Use them exactly as you would use WAV files, described in the previous section.
We don't support using CAS files by patching a BIOS natively, because it is not really something we want: we prefer a more authentic emulation without hacks like this. So, the CAS files are automatically converted to WAV files, internally. Note that the loading time is drastically longer this way (but the setting will help a lot). On the other hand, you will be able to hear the cassette sounds now also with the CAS files... Admit it, using cassettes with an MSX without those characteristic sounds just wouldn't be the same.
To make it even more comfortable to run software from CAS images, check the try to enable the setting, that will attempt to type the loading instruction for you after the MSX has started up.
Note that saving to CAS files (new or existing ones) is not possible; you can only save to new cassette images in WAV format.
The Sunrise IDE interface was the first one to be emulated in openMSX, so by now it's thoroughly supported. Later support for two types of SCSI interfaces was added: the Gouda/Novaxis SCSI interface and the MEGA-SCSI, followed by support for the MegaFlashROM SCC+ SD, the Carnivore 2, and the Beer IDE interfaces.