Installing openMSX

What is the easiest way to install openMSX?

openMSX used to be difficult to install, but it isn't difficult at all, nowadays! At least: it shouldn't be.

The easiest way to install openMSX is to use a ready-made package. Whether one is available depends on your operating system:

The easiest way to install openMSX is by running the installer. Download the installer from our website (check out the Download box), unpack the .zip file, and double-click on the resulting .msi file. After this, you should have a working openMSX and openMSX Catapult.

You can also download the Zip distribution which contains only the emulator files (no installer) and unpack it to the directory of your choice.
The easiest way is to get the .dmg file from our website (check the Download box). There is no Catapult for macOS yet, but NekoLauncher openMSX is a very good alternative. If this site gives you problems, check the mirror download site. And of course you can also use the built-in OSD menu, open it with Cmd+O or by clicking the tiny menu button in the top left corner.
Debian GNU/Linux
Install the openmsx, openmsx-data, cbios and openmsx-catapult packages. The simplest way is to run aptitude install openmsx-catapult, APT will install the other needed packages as well.
The Ubuntu packages are similar to the Debian ones. You can find them in the "universe" repository, so make sure you have that enabled in your /etc/apt/sources.list.
Fedora has packaged openMSX in the main archive since Fedora 7. You can just run yum install openmsx to install openMSX. Catapult does not seem to be packaged yet at the moment.
You can find an ebuild for openMSX in the "games-emulation" category. Catapult does not have an ebuild yet.
openSUSE 10.3 (and 11.x) seems to contain an openMSX package, but it seems to be somewhat outdated.
You can find binary packages for Pentium 2 and higher on the Linux Packages site, but they seem to be somewhat outdated.
There seem to appear at least source RPM's on the search for openMSX sometimes, but we don't know how to use them exactly or if they are also included in the official distribution.
There are packages for openMSX and Catapult in the ArchLinux User-community Respository (AUR).
It is possible that openMSX has been packaged for other Linux systems as well, but we are not able to keep track of them all. Search in your package management system for openMSX and there's a fair chance that openMSX will pop up. If it doesn't, see a few lines below at "other".
There is a port for openMSX in FreeBSD. It is called simply "openmsx". There is also a port for Catapult.
There is a port for openMSX in NetBSD, but it seems to be somewhat outdated. There is no port for Catapult yet.
You'll have to install openMSX from source. This is not as complicated as it sounds, because we have automated most of the process and documented the rest. Just read the Compilation Guide.

Note that in any case, there are no system ROMs installed, so only the C-BIOS machines work out-of-the-box. See also the next couple of questions.

If you still think openMSX is difficult to install, please tell us why!

Should I download the Zip or the Installer for Windows?

We strongly recommend to use the installer. It contains a straightforward Windows Installer package. With the installer, your openMSX experience is only about 3 clicks away. The Zip file is meant for experienced users and those familiar with openMSX and emulators in general.

Why doesn't openMSX come with system ROMs?

The MSX system ROMs are copyrighted. In other words: it's illegal to include them in our software package without a license. The Setup Guide contains a section about system ROMs.

Where do I install the system ROMs?

You can put all the system ROMs in share/systemroms. Please see the Setup Guide for the exact location for your operating system.

Using openMSX

Is openMSX easy to use?

Ever since openMSX comes with the optional GUI dubbed "openMSX Catapult", it is quite easy to use! The Windows installer installs it by default. For other systems, the same counts as for openMSX itself. Check out the Catapult manual for more information. For basic usage, you just select a machine to run and click on "Start"!

An alternative to Catapult, is the built in OSD menu. You can call it by pressing the MENU key (or Cmd+O on Mac) or by clicking the tiny menu button in the top left corner. This menu is also used on handhelds, like the Dingoo.

Catapult and the OSD menu don't give you access to all features of openMSX, though. You can do a lot more by using the openMSX built-in console. You can read a lot more about this in the User's Manual. It's not a GUI, but we did our best to make this console as easy to use as possible.

If you think openMSX is not easy to use, please tell us why! Contact info is in the manuals.

Oh, you might wonder: why don't you make a normal GUI like other emulators? One in which the emulation is inside the GUI? The reason is that we are currently not able to make that: the GUI toolkit we use does not support it and we want to keep the GUI optional, so we cannot make it part of the main application.

All I get is "No cartridge found." What's wrong?

You are probably talking about this:

No cartridge found.

openMSX doesn't come with any system ROMs, see Why doesn't openMSX come with system ROMs?. To have something to be able to run some software, openMSX comes with a free replacement of an MSX BIOS ROM called C-BIOS, written by BouKiChi, Reikan and nowadays the C-BIOS Association. This is also what you can see in the screen: C-BIOS 0.25.

So, the message is not from openMSX, but from C-BIOS, an MSX program which tries to start a cartridge that is inserted in the MSX that is being emulated by openMSX. And it seems you didn't insert any cartridge for it... So, either run openMSX with a ROM image or install real MSX system ROMs for a certain machine and run that one.

Note that the current version of C-BIOS can only run cartridges and does not support disk or tape usage. More information can be found in the Setup Guide.

I get "Fatal error: No drive named 'diska'." What's wrong?

You are probably using Catapult with C-BIOS and you're trying to run a program on a disk image.

Unfortunately, the C-BIOS machines that come with openMSX do not support disk or tape usage. Please see the Setup Guide.

The tricky thing is that the old (current) version of Catapult always shows the disk, tape and cartridge controls, independent whether the machine you're emulating actually supports them. This will be greatly improved in the new (upcoming, but not finished) Catapult.

If you want to use disks or tapes with your emulated MSX, you will have to install the system ROMs of a real MSX (one with a disk drive!) to emulate that one, until C-BIOS supports this as well. More about this in the Setup Guide.

It looks like only ROMs are supported. How can I run disk and tape software?

You probably are running the C-BIOS machines that came with openMSX and did not install any system ROMs of other machines (or did not choose to emulate another machine). The C-BIOS machines rely on the freely available C-BIOS ROMs and that's why we can ship them with openMSX. However, C-BIOS only supports ROM images for now. More information about that in the C-BIOS section of the Setup Guide.

If you want to run software from other media (disks, tapes, etc.), you will have to install other system ROMs, which are from real, existing MSX machines. Then you can run other MSX machines than the C-BIOS machines, which do support tape and/or disk software (depending on the emulated MSX model). More about this in the Setup Guide.

How do I save my game?

In General

You've been playing a game and want to continue another time, so you want to save your progress. You can either save your game as you would on a real MSX, or you can use the built in save state mechanism, which is explained in the manual.

If you consider that cheating, or are interested in how you could save your game on a real MSX, read on... How it works, depends on the game:

Game Disk
Some disk-based games save on one of the game disks. Make sure the disk is not write protected; in openMSX this means the disk image must be an ordinary DSK image (not compressed as ZIP or XSA) and not read-only.
Separate Disk
Some games save on a separate disk. You can create an empty disk for this purpose by opening the openMSX console with F10 (Cmd+L on Mac) and executing the command diskmanipulator create filename.dsk 720. Since many games save in fixed sector locations instead of files, it is best to reserve a separate save game disk for each game.
The PAC and FMPAC contain a bit of battery-powered memory that can be used for saving games. Make sure you insert the pac or fmpac extension when you start openMSX.
The SRAM is divided into 8 blocks and different games typically use different blocks. However, there are many games using the SRAM, so it is unavoidable that some games use the same block. If you play more than one game and want to be safe, copy the .pac file from "persistent/fmpac/untitled1" in your openMSX user directory (see this overview where it is for your platform) to a safe location.
Game Master 2
The Game Master 2 can be used to save many Konami games. Insert both the game cartridge and the Game Master 2 cartridge.
Embedded SRAM
Some cartridges games, for example the strategic games from Koei, have SRAM inside the cartridge. You don't have to do anything special to use this.
Saving to tape is a bit clumsy, but for some games it's the only way.
Note that the current version of C-BIOS does not have tape support, so if you want to save to tape, make sure you use a machine based on the original MSX system ROMs.
Some games show a password that you can enter to resume the game at the same point. You can write down the password of course, or type it into a text file, but if you're really lazy, just make a screenshot! (press PrtScr)

In Metal Gear

Many people wonder how to save in Metal Gear. Here we will explain how that is done on a real MSX, which is also the way to work if you don't want to use the built in save state mechanism of openMSX.

Metal Gear has two ways of saving games:

  1. The usual way. This is the save option from the game itself:
    1. Press F1 and then F5 and you can save on tape.
      For this to work, you need to use an MSX machine with a cassetteport. (So, you cannot use C-BIOS machines, because they do not have a cassetteport (yet)!)
    2. Insert a tape with the console: F10 (to open the console) and then type cassetteplayer new filename.wav, where filename.wav is the (optional) name of the tape file that will be created to save the game to.
    3. Type the file name in the Metal Gear game (can be any name, but you need to remember it! Choose something easy.) and press enter.
      The game will now save to that filename.wav cassette image file, under the name you just entered.
    4. To verify: in the console type: cassetteplayer rewind and then press "Y" in the game to verify.
      You can also skip this step.

    Note that saving in this way is only useful after reaching the elevator. You will continue in the last elevator you were in.

  2. The special way. This is done with the Game Master 2 cartridge. You will have to start openMSX with both the Metal Gear cartridge and the Game Master 2 cartridge. The Game Master 2 cartridge should be in a lower slot than Metal Gear (mention it before Metal Gear on the command line, for example).
    1. After booting, select "GAME" to start Metal Gear.
    2. At any time during the game, press the MSX STOP key (F8 in openMSX).
      The CAPS LED will light, which means you are now in the Game Master mode.
    3. Press CTRL to open the save and load menu.
      For this to work, you need an MSX with a diskdrive (again: not C-BIOS yet!).
    4. Insert a (blank) disk in the openMSX diskdrive.
      This can be a disk image you created with some external tool, but you can also create one from within openMSX itself: in the console, type diskmanipulator create filename.dsk 720. Then insert the disk image in the drive: diska filename.dsk.
    5. Choose "DISK SAVE" in the game from the menu.
    6. Choose "GAME DATA" in the DISK-SAVE menu.
    7. Input a filename for your save game. This will be the name of the file that that will end up on your disk image called filename.dsk.
      The game will now be saved to disk.
    8. After saving, choose "END" and press the STOP key again (F8).
      The game will resume.

For loading back your game:

  1. The usual way:
    1. Press F1 and then F4 in the game and you can load from tape.
    2. Insert the tape image into the cassetteplayer by typing in the console: cassetteplayer insert filename.wav.
    3. Type the filename you choose for the save game in step 1c above. The game will now load the save game and start. If you want to retry, don't forget to rewind the cassette by typing cassetteplayer rewind in the console.
  2. The special way:
    1. Start Metal Gear as described in steps 2a to 2c above in the saving instructions.
    2. In the save and load menu, choose "DISK LOAD".
    3. Insert the disk image which you inserted in step 2d above, to save your game on: diska filename.dsk.
    4. Choose "GAME DATA".
    5. The game will list the files on the disk that are save game files. Select the one you want to load and it will be loaded.
    6. Choose "END" and press the STOP key (F8) to resume the game.

What is the openMSX harddisk support?

This is explained in the User's Manual.

It seems the MSX hangs when running GFX9000 software; what's wrong?

The real GFX9000 has an external video connector to which you can connect a second monitor. Because of limits of the SDL library we used to create openMSX, we cannot have more than one window for openMSX, so we cannot emulate a second monitor. To see the GFX9000 in action, you need to switch the videosource setting, which equals to a so-called SCART-switch in the real world: set videosource GFX9000. If you started openMSX without GFX9000 extension, this videosource is not available. To get your normal MSX screen back, you should type set videosource MSX. If you want to toggle with a hot key between them, it might be useful to bind a key for it. E.g.: bind F6 cycle videosource. cycle is a Tcl command that cycles through the options of the setting in the parameter.

Instead of using the GFX9000 extension, we recommend you use the Video9000 extension (also present in several Boosted MSX machine configurations). This makes the switching go automatically in case the software is Video 9000 aware (e.g. all TNI GFX9000 products). When using this extension, the default value for videosource is Video9000.

Note that GFX9000 emulation quality is not as good yet as the classical MSX video chips.

See also the corresponding section in the User's Manual.

Great, those OSD LEDs! How do I get rid of them?

Open the console with F10 (Cmd+L on Mac) and type:

load_icons none

If you have save_settings_on_exit set to on, this change will be permanent, until you load another icon set. This gives you the default:

load_icons set1 bottom

Where is the full list of commands and settings?

The full list of commands and settings that are available in the console can be found in the Console Command Reference. Check it out, it's really useful!

How can I speed up openMSX? How hard is it to emulate an old MSX on a modern PC?

Actually, openMSX is quite fast, depending on what you ask it to do. If you have minimal hardware, you should use minimal settings as well, to get decent speed. This was proven by Karloch who ran openMSX 0.6.0 on a 206MHz HP Jornada 720, see this thread on MRC. On PC's, it really helps if your graphics card is not slow, or actually, the pipe between the CPU and the graphics card. Tips on how to performance tune openMSX can be found in the Setup Guide. The developers do their best to keep the performance of openMSX as good as possible, whilst still achieving the highest level of accuracy that we can.

In general people wonder why you need 200MHz+ machines to emulate a computer based on a 3.5MHz CPU. Well, you don't only have to emulate the CPU, you also have to emulate the VDP (21MHz), the monitor (writing at least 50 times per second at least 256×192 pixels to a window), the sound chips, etc. This is relatively simple hardware, but having that run in software with cycle accuracy is quite heavy. In general, it is a lot of work for a general purpose CPU to emulate functionality that was originally made in dedicated hardware. Rebuilding an MSX in general purpose hardware (using VHDL on FPGA) is already a lot less demanding. An example of this is the One Chip MSX.

How do I create perfect play videos, like Vampier's YouTube videos?

The trick is to use the reverse feature to correct any mistakes you make during game play. You just play, play, play, correcting all mistakes you make by going back in time a bit (using PageUp) when you (e.g.) die and doing it better.

As soon as you get to the end of the game, we recommend to save the whole replay (using the reverse savereplay), so that you can always load it and play it again (using reverse loadreplay).

Next step is to pause openMSX, load back the replay (if you saved it) or simply go back to the complete start (click at the start of the reverse bar, or use the command reverse goto 0). Now you're ready to record your heroic movie! (Note: if you want to record a video from a later point in time, just let it play until it reaches the right position, or click on another part of the reverse bar, or just search a bit with PageUp/PageDown.)

So finally, start recording and unpause openMSX. If you want it quickly, run in full throttle (F9 by default) to speed things up. The resulting movie will be the same. If you want to split up the recorded video in chunks that are accepted by YouTube, you probably want to look at the record_chunks command.

Easy! Now fill up YouTube with MSX material!

How do I use openMSX for TAS (Tool-Assisted Speedruns)?

If just creating perfect play videos isn't enough for you, you are probably going for Tool-Assisted Speedruns, of which you can find all information on The rest of this item gives you some hints to help you with this.

First of all, the basics are explained in the previous section, of course. But you can get extra tools if you enable the TAS mode, of which we won't repeat the explanation here. If you need also a live RAM watch, check out the ram_watch command. It enables you to add live views of values on multiple addresses with several view options, like titles, formats and data types.

For MSX TASing, we recommend to not use the (default) C-BIOS based machines, but real machines, because C-BIOS is still in development and this means your replay (in most other TASing emulators called "movie") won't be easy to get working again once a new version of C-BIOS has been released. Also, MSXturboR machines are not recommended, because it has a relatively large amount of timing inaccuracies. So which machines do we recommend? Here's a table with some very rough directions:

game type machine
Japanese/Korean (MSX/MSX2/MSX2+) Panasonic FS-A1WSX
European (MSX/MSX2) Philips NMS 8250 + FMPAC

This is mostly motivated by the fact that Japanese machines run at 60Hz interrupt frequency and the Japanese games are made for that. Besides, you will get proper Japanese characters with a Japanese machine, which are often used in such games. The mentioned machine can run practically all Japanese MSX/MSX2/MSX2+ games and has FM on board. For European games, the 50Hz (PAL) Philips NMS 8250 is recommended, just because it's very common and runs most European MSX and MSX2 software. The FMPAC extension is for better sound. There are no native European MSX2+ machines.

When doing MSX TASing, be aware that (unlike consoles), MSX machines have full keyboard attached, and touching them means input for the MSX. And that means you will interrupt the replay if it's playing. You can avoid this (when merely viewing a replay) by using the -viewonly option when using the reverse loadreplay command. The keyboard problem also means that it's a bit tricky to assign keyboard shortcuts (with the bind command) to (e.g. TAS) functions, without also blocking MSX keys. So, be careful which keyboard shortcuts you configure and which keys you press.

Now it's time to make a TAS and submit your entry on!

A final note: if you have problems replaying other people's TAS (or other openMSX replay), because openMSX can't find the required media (ROMs, disks, tapes, etc.), make sure you put the required media in the proper filepool; by default share/software.

How can I disable reverse or the reverse bar time line?

Using reverse in combination with large (hard disk or SD card) media can be slow at start-up, as openMSX needs to calculate a hash of the media to know whether it changed. Moreover, if you reverse and the hard disk image changed, openMSX will switch to read-only mode for the media. This is because currently, when reversing, openMSX does not revert changes to media, so replaying these may cause corruption on the media e.g. due to double writes.

So if you are using large media and you don't really need the reverse feature, you probably want to disable it: use the reverse stop command in the console. And if you don't want it to restart again anymore, set the auto_enable_reverse setting to off.

It can also be that you don't want to disable reverse necessarily, but that you're working with the mouse a lot and the reverse bar shown at the top is in the way. In such a case you can just get rid of the bar by issuing the toggle_reversebar command. (This will not turn off the reverse feature itself.) You can also prevent it from ever showing using the auto_enable_reverse setting.

More details about reverse are in the User's Manual.


What codec do you use to record videos and where do I get it (because I only get blackness in my videos)?

The ZMBV (Zip Motion Blocks Video) codec is used, which has been developed in the DosBox project. It enables openMSX to encode video in real time (on most systems), has a very good compression ratio and gives excellent video quality, because it is a lossless codec. Razor sharp movies! Also, because the encoder is built in, it doesn't make openMSX depend on an external codec to be installed for recording video.

A developer of DosBox built a Win32 binary of the codec for our users. It is included with openMSX 0.6.2 (and up) for Win32. Note that the installer does not install the codec by default, so you will need to enable this option when installing. You can also download the codec separately from our web site. After unzipping the file, use the .INF file to install the codec (zmbv.dll) by right-clicking on it and selecting Install. Note that other binaries of this codec that you can find on the internet may not work, as not all of them have support for more than 8 bits per pixel recordings. Also note that this is a 32-bit codec, so it will not run inside 64-bit Windows Media Player or Windows Media Center.

You only need this codec installer to be able to replay the videos on a Windows system. (Although a workaround could be to upload it to Google video, where it is re-encoded into a lossy MPEG-4 format.) Programs like Virtual Dub can use the codec and re-encode it in another way. On other operating systems, you can use any video player which supports this codec; e.g. mplayer. Re-encoding can be done with e.g. mencoder.

Why do I hear serious sound glitches and/or stuttering, especially when using Windows?

Not sure, but for some reason, especially on Windows, we can't find default settings that work for everyone. If you indeed have glitches like sound delay or stuttering, you can try the following.

Where can I find more technical info about openMSX?

Next to the openMSX manuals (which includes documentation on how you can control openMSX from an external application, so that you can make your own GUI, launcher or debugger), also check out the doc directory of your openMSX distribution.

My question is not listed here.

You can look in the following places for answers:

openMSX manuals
We have a nice set of manuals describing most of the functionality in openMSX.
Catapult manuals
The manuals of Catapult, the graphical interface to openMSX.
The Ultimate MSX FAQ
Look here if you have a question that is not specific to openMSX, but about the MSX system itself.
openMSX Forum on MRC
You can post your questions here.
openMSX IRC channel
The openMSX developers and testers hang out on this channel (chat room). If the link doesn't work, try the webchat or get an IRC client, go to server and join channel #openMSX. It is possible you will not get a reaction immediately, so please ask your question, stay logged in and check from time to time if someone is active.