Emulators

Support

MSXgl's Build tool can automatically launch the emulator of your choice with a configuration that match your project options. Not all emulators support all available options.

Here's a list of supported options for each emulator.

Specific setting

openMSX

To enable MSX turbo R, FM-PAC or OPL4 emulation, you need to get proprietary system ROMs not included in openMSX for copyright reason. You can find them on the Internet (here or here for example).

You also need those system ROMs to launch MSX-DOS or BASIC binaries application from a disk. Once you have installed the system ROMs, you need to select a machine that contains a disk: for example the Philips VG-8235 (PAL) or Sony HB-F1XD (NTSC). Set the machine as the default one in openMSX and set EmulMachine to false in your project configuration (to prevent the Build tool to reset the machine a launch).

Check the openMSX documentation for more information: https://openmsx.org/docs.html

Emulicious

Here is some tips to test your MSXgl program using Emulicious.

How to run a MSX-DOS or BASIC program

Emulicious contains only the basic C-BIOS free BIOS, which can only run programs in ROM format. By changing a few options in "Options" > "Emulation" > "MSX" menu, you can run programs on disk using proprietary BIOSes.

First, change BIOS:

• MSX 1: Set "MSX1 BIOSes" option to MSX.ROM,
• MSX 2: Set "MSX2 BIOSes" option to MSX2.ROM and MSX2EXT.ROM.

For MSX-DOS 1 or BASIC:

• Set "Disk ROM" option to DISK.ROM.

For MSX-DOS 2:

• Set "Disk ROM" option to DISK.ROM.
• Set "MSXDOS2 ROMs" option to MSXDOS2.ROM.

Now you can auto-launch your disk program from Build tool or load your .DSK file directly from Emulicious.

How to enable MSX-Music

Set "FM PAC ROMs" option in "Options" > "Emulation" > "MSX" menu to FMPAC.ROM.

How to debug using VS Code

Here are the steps for debugging your program with Emulicious from VS Code:

1. Install Emulicious VS Code extension.

2. Setup "Emulicious Path" in Emulicious extension's settings.

3. Create a launch.json from the "Run and Debug" panel. Configuration section should look like:

"configurations": [
        {
            "type": "emulicious-debugger",
            "request": "attach",
            "name": "Attach to Emulicious",
            "port": 58870
        },
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/emul/rom/mygame.rom",
            "port": 58870,
            "stopOnEntry": true
        }
    ]

Replace ${command:AskForProgramName} by emul/rom/mygame.rom (where "mygame" is your own game name). If you already have a launch.json, select the "Add configuration" option and select one of the 2 Emulicious configuration.

4. Enable remote debugging in Emulicious. Launch Emulicious and set "Enabled" in "Tools" > "Remote Debugging" menu.

5. Now you are ready to debug your application from VS Code. Go to "Run and Debug" panel and select Attach (to attach to a currently running game on Emulicious) or Launch (to launch your game in Emulicious). If "stopOnEntry" is set to true in your launch.json, the VS Code debugger should break at the beginning of your main() function.

You can found more information about the VS Code debugger on Internet. For example: https://code.visualstudio.com/docs/editor/debugging

blueMSX

To setup the emulation of the ObsoNET cartridge, please follow this tutorial: https://www.msx.org/forum/msx-talk/emulation/bluemsx-emulating-obsonet-and-tcp-ip-unapi

VRAM access timing emulation

VRAM access timing limitations are supported by few emulators.

openMSX

openMSX (18.0) supports VRAM access time emulation with the following limitations:

• In the default mode (display and sprites enable), it is a little too optimistic, i.e. within about 1~2 t-states, accesses that will work on openMSX will not work on a real machine. For example, on a Philips NMS 8250, an access with an interval of 19 t-states will work on openMSX but may fail on a real machine.
• With display disabled, it does not emulate at all the access time limitations of the non-bitmap display modes on V9938/58. This can be a major source of error, as this limitation doesn't exists on TMS9918 and don't seem to be documented.
• With sprites disabled, it still emulates too optimistically, sometimes with a 3 t-state gap between valid intervals in openMSX and those observed on a real machine. For example, while an access in graphics mode 1 with an interval of 12 t-states is valid in openMSX, it requires at least 15 t-states on a real machine.

Note: openMSX emulates quite faithfully write failures linked to a VDP command active on the same VRAM zone.

Emulicious

Emulicious (2023-04-22) has a limited emulation of VRAM access time:

• On TMS9918, a limitation exists for the default mode (display enabled) but it does not correspond to the value observed on a real machine. All screen modes seem to have an access limit of 25 t-states, whereas valid intervals are supposed to be 12 t-states for Text 1 mode and 29 for the others.
• On the other hand, with the screen off, access times are correct.
• On V9938/58, no limitation seems to be emulated at all.

Note: A forthcoming version of Emulicious should enable more precise emulation of VDP access timing.

Others

Other emulators do not emulate VDP access timing constraints at all: fMSX (6.0), blueMSX (2.8.2), MEISEI (1.3.2), RuMSX (0.83) and WebMSX (6.0.4).