Options
Open games, save or load progress, manage disks, and change system settings.
iMSX2
User Guide
MSX · MSX2 · MSX2+
Your complete guide to iMSX2
Load games, customise the controller, use video filters, manage multi-disk titles, choose compatible sound hardware, save your progress, configure MSX BIOS and RAM settings, and play on Apple Watch.
01 · Controls
Everything is one tap away
The toolbar handles emulator features while the virtual pad can act as a joystick, cursor keys, or MSX keyboard keys.
Video filter
Choose None, CRT, Scanlines, or CRT + Scanlines.
Fast forward
Toggle higher emulation speed. The icon turns blue while it is active.
Edit controls
Move the virtual pad and buttons, then save a separate layout for each orientation.
Keyboard
Show or hide the software keyboard for games and MSX applications.
Full screen
Hide the toolbar and controller. Tap the screen to restore the interface.
What does Type mean?
A ROM mapper is the memory layout used by larger cartridge games to make different parts of the ROM available to the MSX. iMSX2 normally detects it automatically. If a game does not start or behaves incorrectly, use Type to try Normal, ASC8, ASC8 SRAM, ASC16, ASC16 SRAM, ASC16 SRAM8, Konami SCC, Konami, or ASCII16-X.
Virtual controller
Joystick or cursor keys
Open Options › Directional Control to switch the D-pad between the MSX joystick port and keyboard cursor keys.
Per-button keyboard mapping
Make controls fit the game
Use Options › Button Mapping to assign MSX keyboard keys, including Space, Enter, letters, cursor keys and function keys, to the virtual controls.
A layout for each screen
The default controls adapt to compact iPhones, larger phones, and iPads. A/B are centered beside the D-pad when space allows. In portrait, Select and Start stay centered at the bottom, with Auto A and Auto B on the lower right. Landscape uses the available space around the game screen.
If you already saved a custom layout, choose Reset to Defaults in the control editor to try the adaptive layout.
Tip
Moving the on-screen buttons
- Tap the controller icon in the toolbar.
- Drag the D-pad and buttons to comfortable positions.
- Tap the controller icon again.
- Choose Save, or restore the default layout.
Portrait and landscape positions are stored separately.
02 · Open a game
From file to first game
iMSX2 accepts ROM cartridges, disk images, and ZIP archives directly from the Files picker.
- 1
Open Options
Choose Options (☰) from the toolbar.
- 2
Select Open Game
Choose Open Game from the Game Management section.
- 3
Choose a supported file
Select a
.ROM,.MX1,.MX2,.DSK, or.ZIPfile. iMSX2 loads it and starts automatically.
ROMMX1MX2DSKZIP
03 · Display & speed
Choose the way your MSX looks
You can choose the way your MSX looks while a game is running.
None
A clean, unfiltered image.
CRT
Softens the image to resemble a display tube.
Scanlines
Adds distinct horizontal raster lines.
CRT + Scanlines
Combines the CRT treatment and scanlines.
Fast forward
Tap the forward icon to enable 4× fast forward during loading or graphics preparation. Tap it again to return to normal speed before playing. A blue icon and an on-screen message confirm the current state.
Full screen
Hides the toolbar, background, and virtual pad. Tap anywhere on the emulation screen to bring the interface back.
04 · Sound
One Music editor, automatic or manual
Open Options › Music before or after loading a program. Use Automatic for detected presets, or turn it off to connect individual sound devices together.
Automatic on
Preferred sound
Before loading a program, choose a default preference: Automatic, Original, MSX-MUSIC, MSX-AUDIO, the combined FM preset, SCC+, MoonSound, or a Yamaha variant. With a program loaded, Preferred sound lists its detected compatible presets. A saved per-program preference takes priority; an unavailable startup preference falls back to automatic detection.
Automatic off
Connect sound cartridges
Enable individual devices together, including MSX-MUSIC, MSX-AUDIO, SCC or SCC+, MoonSound and Yamaha hardware. This bypasses preset detection. Choose Automatic placement or a location for devices that occupy a slot. The base MSX PSG stays available.
- 1
Choose the scope
Open Music before loading a program to set defaults. Open it with a program loaded to save a choice for that program.
- 2
Choose a preset or devices
Keep Automatic on for Preferred sound, or turn it off for individual device switches and locations. A program-specific manual configuration takes priority over detection.
- 3
Apply deliberately
Tap Apply. A change for a loaded program asks for confirmation before restarting; Cancel preserves the current session. Applying unchanged settings resumes without restarting.
Available when detected
Original and expansions
Original keeps the base machine and cartridge sound. Depending on the program, the list can also offer MSX-MUSIC (YM2413/OPLL), MSX-AUDIO (Y8950), both FM devices in stereo, SCC+, MoonSound (OPL4), or a Yamaha expansion.
Program support matters
Check the game's own settings
Enabling a chip does not convert existing music into another format. Some programs require their own sound option to be selected. The combined FM preset sends MSX-MUSIC to the left channel and MSX-AUDIO to the right; the program must use both to play both.
Locations, combinations and Yamaha hardware
In Music, turn off Automatic to see all device switches. For slot-based devices, Location offers external slots 1/2 and their subslots. Automatic placement finds free space and can add a slot expander. MSX-MUSIC also offers Internal. Devices that use only I/O ports do not need a slot location.
SCC and SCC+ are alternatives. Combinations that share I/O ports are rejected, and slot conflicts are reported without replacing existing hardware. For example, software using PSG, MSX-MUSIC and SCC can use MSX-MUSIC in slot 2-0 and SCC in slot 2-1, with PSG built into the machine.
| Sound hardware | Chip or supported playback |
|---|---|
| Yamaha SFG-01 / SFG-05 | YM2151 / YM2164 FM |
| OPL / OPL2 / OPL3 | YM3526 / YM3812 / YMF262 |
| OPN / Makoto OPNA / Misato OPN3 | YM2203 / YM2608 / YMF288 |
| External PSG | YM2149 |
| Neotron / Neotron B | YM2610 / YM2610B, direct FM/SSG playback |
These modes support software with its own chip driver. SFG firmware services, external MIDI and Neotron SIOS are not included.
When a game's music is missing
Check the active option in Options › Music and the game's own sound settings. A saved per-program configuration takes priority over the startup default and new automatic detection. Choose the expansion required by your software and confirm the restart.
MoonSound samples and instrument ROMs
MoonSound can play samples uploaded by a game and can also use an installed YRW801 instrument ROM. A game may use either or both. Instrument-ROM import controls for MoonSound and Yamaha rhythm samples are temporarily hidden in Select BIOS; files already installed continue to be used.
FM BIOS compatibility
The built-in MSX-MUSIC identification ROM allows compatible software to detect the device and access the chip directly. It does not include FM-BASIC or full FM-BIOS routines. MSX-AUDIO sound support does not include all Music Module firmware functions. The automatic preset list reflects detected support; it is not a guarantee that every program or sound driver will work.
05 · Saving progress
Continue exactly where you left off
Save states capture the complete emulator state so you can resume from exactly the same moment.
1
Open Options
Tap the menu icon in the toolbar to access Save Data and Load Data.
2
Choose Save Data
iMSX2 stores one quick-save state for the current title.
3
Choose Load Data
The local state is loaded first; iCloud is checked when no local state exists.
06 · Disk games
Single disks, multi-disk sets, and writable media
iMSX2 has a simple compatibility path and a native floppy path for titles that need real drive behaviour.
Without a Disk BIOS
Compatibility mode
- Works with one DSK image
- Tablacus dsk2rom compatibility path
- No live disk swapping
- Limited hardware compatibility
With a recognised Disk BIOS
Native floppy mode
- Best hardware compatibility
- Multi-disk games
- Drives A and B
- Insert, replace, eject, and swap disks
A
Import disks together. Select multiple DSK files and confirm their order. The first image is inserted into drive A.
B
Change disks while playing. Open Options › Manage Disks and choose drive A or B.
C
Create a user disk. iMSX2 keeps this writable disk between sessions for games that save to floppy.
07 · Apple Watch
Your MSX on your wrist
Send a game from iPhone to the paired Apple Watch, then play on the watch independently. Watch transfers are started on iPhone; iPad saves can first reach iPhone through iCloud. The Watch edition is in development; these instructions describe the current build.
Start on iPhone
Send a game
- Install iMSX2 on the paired watch.
- Open the ROM or disk set on iPhone.
- Choose Options › Send to Apple Watch, at the end of Game Management.
- Follow the transfer progress and wait for the title to appear in the watch library.
A real watch can receive a queued transfer when connectivity returns. In the simulator, keep both apps open and the paired watch reachable.
Choose once on Watch
BIOS and RAM
In Select BIOS on iPhone, send a matching Main/Sub set and its RAM configuration. A configured Disk BIOS is included. BIOS are sent separately from games. On Watch, open BIOS and choose C-BIOS or the imported machine; the checkmark identifies the selection.
There is one imported set: sending another replaces it. Delete Imported BIOS removes it from the watch. The selected set applies to all games launched afterward.
ROM and DSK
Disk support
ROM games can use C-BIOS. Every DSK game needs imported Main/Sub BIOS. Without a Disk BIOS, a single DSK uses Tablacus dsk2rom compatibility mode. With a Disk BIOS, single and multidisk games use the native controller. Send every game disk together in the same order, then use … › Change Disk to insert a different disk in drive A.
A transferred native saved game also restores the saved drive A/B arrangement, full disk contents and an optional user disk. The watch’s disk picker changes drive A; it is not a two-drive manager like the iPhone interface.
Per-game profiles
Controls and Digital Crown
Open … › Controls for This Game. Choose joystick directions or cursor keys, map A/B to the joystick or MSX keyboard, and assign the Digital Crown to A, B or a key. MSX Keys provides quick Space, Enter, Esc and F1–F5 actions. Restore Default Controls resets that game’s profile.
Continue a saved game from iPhone
- Use Save Data on iPhone to create a saved state.
- Send the same game or complete disk set to the watch first, and select matching BIOS/RAM and disk mode.
- Choose Send Saved Game to Apple Watch, immediately after Send to Apple Watch in Game Management.
- On Watch, choose … › Load Game. Receiving a saved game replaces the saved slot without interrupting the currently running game.
There is one manual saved slot for the active game configuration. Sending or using Save Game overwrites that slot. Transfers go from iPhone to Watch; Watch progress is not synchronised back to iPhone or iCloud.
Pause, return and restart
Opening the game menu pauses play. Leaving the app stores a separate suspended session for returning later, including after the app is relaunched. This does not overwrite the manual Save Game slot. Restart Game asks for confirmation, starts again with Disk 1 in A for native disks and keeps your manual save and disk writes.
Delete a game and its progress
Use the library’s delete action and confirm. iMSX2 removes that game, its saved states for every BIOS configuration and its suspended session from the watch. Other games and the copies on iPhone remain available.
Optional · Custom BIOS
Configure a custom MSX BIOS
C-BIOS is included and remains the default for ROM cartridges. A custom machine BIOS is optional, while a recognised Disk BIOS unlocks native floppy support.
For a custom MSX2/MSX2+ setup, import a Main BIOS (32 KB) and matching Sub BIOS (16 KB). Add a matching Disk BIOS (16 KB) for native floppy support. These are separate images; do not concatenate them.
Choose one machine
Decide which MSX model you want to emulate. Do not mix files from related models or regional variants.
Select the BIOS files
Open Options › Select BIOS and choose Main and Sub BIOS, plus Disk BIOS when needed. File names do not matter; contents and sizes do.
Check detection
A recognised set shows the detected machine and floppy controller. If a warning appears, verify that all files belong together.
Load your game
ROM cartridges can continue using C-BIOS. DSK games will use native floppy mode when the Disk BIOS is valid.
Examples recognised by iMSX2
These model names are examples only. iMSX2 does not provide proprietary BIOS files or download links.
| Machine | Generation | Floppy controller |
|---|---|---|
| Philips NMS 8250 / VG 8235 | MSX2 | WD2793 |
| Sony HB-F700 | MSX2 | WD2793 |
| Panasonic FS-A1F | MSX2 | TC8566AF |
| Panasonic FS-A1WX | MSX2+ | TC8566AF |
| Sanyo PHC-70FD | MSX2+ | TC8566AF |
Optional · RAM expansion
Keep the machine's RAM or expand it
In Options › Select BIOS › RAM expansion, choose Use detected RAM, 128 KB, 256 KB, or 512 KB. Use detected RAM keeps the memory of the selected machine profile; it does not inspect a game's requirements.
A selected size is a minimum: it expands memory only if the machine has less RAM. The change applies when the next program starts. Use Options › Restart to apply pending RAM or BIOS settings to the current program; inserted disks and their changes are kept. Each explicit RAM selection uses separate emulator save states, so return to the same setting to resume them.
Some MSX2+ profiles have only 64 KB RAM. If your software requires more, select the required minimum under RAM expansion, then choose Options › Restart. Correct BIOS detection identifies the machine's actual memory; it does not add extra RAM to meet a program's requirements.
Available without a connection
A quick guide is built into iMSX2
Open Options › Help for a compact version of the essential instructions. It covers adaptive controls, automatic and manual sound, save states, disks, BIOS/RAM setup, and Apple Watch even when the device is offline. The built-in guide is translated into all 11 app languages.
Online when you need more detail
The Help screen also includes Open Full User Guide, which opens this page when an internet connection is available. The instructions inside the app remain available offline.
Troubleshooting
Common questions
Do I need a custom BIOS to play ROM cartridges?
No. iMSX2 uses C-BIOS by default. A custom BIOS is optional for ROM cartridges.
Why can I not swap disk images?
Disk swapping is available only in native floppy mode, which requires a recognised 16 KB Disk BIOS.
Why is my BIOS combination not recognised?
Check the required file sizes and make sure Main, Sub, and Disk BIOS files come from the same exact machine and region.
Why does a ROM fail to start?
Check the software's machine, RAM and sound requirements. The detected machine may have less RAM than the program needs. Choose the required RAM under Select BIOS and restart. If the mapper is wrong, use the Type menu.
Why does the sound list change after loading a game?
The same Music editor is used throughout. With Automatic on, Preferred sound shows all startup choices before loading a program and detected presets afterward. A per-program choice takes priority; an unavailable default falls back to detection. Turn Automatic off to select devices manually.
Why does Music show only Original?
The detector found no optional preset for the loaded program. Open Music and turn off Automatic if the software requires known hardware, then enable the device and choose its location if needed. Chip emulation does not supply every firmware service.
Why can I not send a saved game to Apple Watch?
Send the same game first. For disks, use the same complete ordered set and match native or Tablacus mode, BIOS and RAM. Export supports Original sound, MoonSound with matching instruments and native SCC-I; other sound expansions need a supported configuration and a new save. Older formats must be loaded and saved again on iPhone. Read the specific error on iPhone or Watch.
Does Watch progress return to iPhone?
No. Saved-game transfers currently go from iPhone to Watch and overwrite the Watch slot. Watch manual saves and suspended sessions stay on the watch.
Does Use detected RAM choose memory for each game?
No. It keeps the RAM of the machine profile. Select a larger minimum in Select BIOS if your program requires it, then use Options › Restart to apply the setting.
Why is a game taking a long time to load?
Some games spend time loading and preparing graphics before the title or level appears. Try 4× fast forward during that phase, then switch it off for normal play.
How do I restore the adaptive control layout?
Tap the controller icon, tap it again, and choose Reset to Defaults. Saved custom positions can otherwise take precedence over the default screen layout.