Skip to content

libretro/fmsx-libretro

Repository files navigation

fmsx

This is a port of Marat Fayzullin's fMSX 6.0 (21-Feb-2021) to the libretro API.

Source : http://fms.komkon.org/fMSX/

Recognized file extensions

  • .rom .mx1 .mx2 .ROM .MX1 .MX2 - for ROM images
  • .dsk .DSK .fdi .FDI - for FAT12 360/720kB disk images
  • .cas .CAS - for fMSX tape files
  • .m3u .M3U - for multidisk software

The supplied location must exist and must be a readable file with one of the listed extensions. If, e.g., it points to a directory or non-existent file, no image is loaded and this core will boot into MSX-BASIC. It is not possible to insert a disk into a running core.

Saving state

Some state is automatically persisted to these files at shutdown:

  • RTC (real time clock, screen settings, etc.): to CMOS.ROM (system directory, 52B)
  • SRAM in ASCII8 & ASCII16 mapper ROMs: to <Game>.sav (working directory, 8 or 2KiB)
  • FM-PAC SRAM: to FMPAC.sav (working directory, 8KiB)
  • Konami Game Master 2 SRAM: to GMASTER2.sav (working directory, 8KiB)

These files will only be created when the RTC resp. SRAM data is actually changed during gameplay.

SRAM only applies when the respective support ROM (FMPAC, GMASTER2) is loaded, and when the selected content supports that type of SRAM. Consult a game's manual to verify if SRAM saving is supported, and if so, what type. The FMPAC.ROM and/or GMASTER2.ROM must be present in the RetroArch system directory and are to be provided by the user.

Many disk-based games, especially multi-disk games, support saving to disk. To persist disk saves, set option "Save disk changes" (fmsx_flush_disk) to "Immediate" or "On close".

Alternatively, set option "Save disk changes" (fmsx_flush_disk) to "To/From SRAM". This will leave your content files intact and save updated disk data into RetroArch SRAM file <Game>.srm in the configured savefile_directory when exiting RetroArch or unloading the content. For multidisk, only changed disks (usually your User Disk) will be persisted into SRAM.

Note: this usage of RetroArch SRAM has nothing to do with MSX SRAM. This core currently does not support saving MSX game SRAM into RetroArch SRAM <Game>.srm files, nor saving RTC data into RetroArch RTC <Game>.rtc.

If persisting whole disks to RetroArch SRAM is not preferred, opt instead for persisting state; by default Save State button is F2 and Load State is F4. RetroArch will save state (compressed) to <Game>.state in the configured savestate_directory.

For the state to be properly restored after a restart, this core must be started with exactly the same settings (MSX type, RAM size, etc.) & loaded files (ROMs, DSKs, CMOS, SRAM, etc).

Tape (cassette) software

Tapes are automatically started based on their detected type (binary, ASCII or BASIC).

Press F6 to rewind the tape, if that's needed.

Multidisk software

Create a textfile with extension .m3u and list one .dsk filename per line. The file will be resolved relative to the directory location of the .m3u-file. Absolute files are also supported; start the full path with <drive>: on Windows or / on other OSes.

Navigate through the disk images using RetroArch hotkeys; configure these settings:

# keyboard settings
input_disk_eject_toggle = ".."
input_disk_prev = ".."
input_disk_next = ".."

and/or

# RetroPad settings
input_disk_eject_toggle_btn = ".."
input_disk_prev_btn = ".."
input_disk_next_btn = ".."

Note:

  • these hotkeys are by default unmapped in RetroArch
  • images can only be swapped in the 'eject' state

Creating empty disk images

An MSX computer will boot into an MSX-BASIC prompt when no cartridge or executable disk is inserted. By default, attempts to do disk I/O will then result in 'Disk offline' errors.

To create an empty disk image, which can be written to from MSX-BASIC, set both of these options:

  • "Create empty disk image when none loaded": Yes (option fmsx_phantom_disk)
  • "Save changes to .dsk": Immediate or On close (option fmsx_flush_disk) Without the latter setting, changes to the created disk will be lost.

This option can also be used to create User Disks for multi-disk games.

The following situations can arise:

  • no content selected when starting core: changes will be lost; no filename is known
  • non-existent .cas, .rom, .m3u or .fdi selected: changes will be lost
  • non-existent .dsk image selected: .dsk image created on host filesystem
  • non-existent file listed in .m3u: .dsk image created on host filesystem
  • RGUI > Quick Menu > Disk Control > Disk Image Append: RGUI enforces an existing file to be chosen. However, this can, e.g., be a zero-byte file. As long as it has a .dsk file extension, a valid .dsk image file will be created & saved.

Cheats

"To make cheat codes for Game.rom, create Game.cht containing codes in 00AAAAAA-DD and 00AAAAAA-DDDD formats, one per line. Where AAAAAA is the ROM address and DD is the value to write there. For 16bit values, use DDDD. The cheat file will be loaded automatically." (fMSX site, section "New in fMSX 4.0") Press F7 to activate cheats; press F7 again to deactivate.

Note: this .cht format is specific to fMSX and differs from RetroArch's CHT files! This core does not (yet) support RetroArch cheat codes. Neither Emulator Handled (lr-db for MSX does not even contain any that would apply; no code values) nor RetroArch Handled (would probably require support for loading content from memory and/or memory mapping).

A BlueMSX MCF named Game.mcf will also be loaded automatically. Press F7 repeatedly to active cheats one by one, or disable cheats.

Cheevos / RetroAchievements

This core supports RetroAchievements.

There are currently 16 MSX games with achievements. Most are verified to work in this core. Note: this list is just for reference; will not be updated.

Take note of the following to ensure your achievements are registered:

Game-specific remarks:

  • SD-Snatcher is only registered at RetroAchievements for the Melancholia English translation. There are instructions for applying that patch, and creating a four-disk .m3u (multi-disk) including the user save disk. The intermediate files with hashes are listed for convenience. ❗ Although saving to disk will immediately break the hash, this only applies to game disks. To save progress in SD-Snatcher, you'll have to set fmsx_flush_disk to 'Immediate' or 'On close' to enable writing to the fourth (User) disk. This user disk is not part of the set of hashes that RetroAchievements verifies.
  • Penguin-Kun Wars 2: the English translation is not listed in CARTS.SHA. Manually set fmsx_mapper_type_mode to 'ASCII 16kB'.
  • Metal Gear: RetroAchievements operates with MD5 hashes. Since the openMSX database and fMSX CARTS.SHA use SHA1 hashes, those are listed here where available. When running a patched ROM with unlisted SHA1, manually set fmsx_mapper_type_mode to 'Konami4 8kB'.
  • Metal Gear 2: same, but set 'Konami5 8kB'
Game RA topic & gen-MSX Verified lr-fmsx Common filename Type Platform MD5 SHA1 CRC32 Remarks
Aleste Topic GenMSX ✓ * Aleste (Japan).rom ROM MSX2 7087b51f3ccfdf314ce60d5d8aaf644a 12f6f31f495bfb384c9ca9067bfbf8f98af6adf9
Aleste (Japan).dsk Disk 28427cfe955f65c6ec8ef2bdd35ff6a7 655989b36f291d7ad2e8a1bb7711ec32287363c8
alesteen.dsk Disk 2ebb5484e112b0c41fa0d392da9a9bf1 English Patch
Knightmare Topic GenMSX Knightmare - Majou Densetsu (Japan).rom ROM MSX1 ebfcaba358d7ceca95c7385276321f78 c8ff858d239c62a859f15c2f1bf44e1d657cec13 0DB84205
SD-Snatcher (Melancholia English Translation) Topic GenMSX n/a Super Deform Snatcher (1990)(Konami)(ja)(Disk 1 of 3)[a][SCC+].dsk original MSX2 SCC+ 4cef12ae13334ed4f3f890311b641c1ad2bdc408 74DF1878 filename variant 1
n/a Super Deform Snatcher (1990)(Konami)(ja)(Disk 2 of 3)[SCC+].dsk original 1156f6c4d9332fdc6cda05558ac3e3102a2764fe 930E06B3
n/a Super Deform Snatcher (1990)(Konami)(ja)(Disk 3 of 3)[SCC+].dsk original e4b1b5f8b7ea4532551c103164860c8802151131 0547BB3A
n/a SD Snatcher Japanese for SCC+ Disk 1.DSK original 74DF1878 filename variant 2
n/a SD Snatcher Japanese for SCC+ Disk 2.DSK original 930E06B3
n/a SD Snatcher Japanese for SCC+ Disk 3.DSK original 0547BB3A
n/a SD092M1E.IPS Patch 9f09878023f0ce424cc3200e9ad6870c9d3325a2 F5A3D165
n/a SD092M2E.IPS Patch 7eeab38f97064aaa0158826dbb181126b9344a87 FD1B05CE
n/a SD092M3E.IPS Patch 45f5c4db226fc177b3e797cc3a7d95b61c10ebee D30D8D7E
SD Snatcher (Melancholia Translation - Any SCC Cartridge) Disk 1.dsk Multi-Disk 3bcf74b40f15eef5aab22a49781f9f1a 9d12c20f71c4049f8a8b65cc4f13fd7b54affadc 1B3D3C89
SD Snatcher (Melancholia Translation - Any SCC Cartridge) Disk 2.dsk Multi-Disk 6d1990d36783caf8b6e4d73ae22c98b1 4983041e918acd599e65c70de3101011c43b059a AC407E31
SD Snatcher (Melancholia Translation - Any SCC Cartridge) Disk 3.dsk Multi-Disk e4d3e483964c62ade5f07afdd81dd64b 0c4c993758e69a8f8fd79fbc4eef4cecdc156f32 F626F02E
Metal Gear Topic GenMSX ✓ * Metal Gear (J).mx2 ROM MSX2 12e302954fa9b23c11ce7c8f5770b82a a52021f1b257c7c35d626d5d642134091c45e4f4
Metal Gear [RC-750](JP).rom ROM 439ea985617135d70858f0e6f88ba0f9
Metal Gear (T-Eng).mx2 ROM 56a32f310765e54101a10001d28344b6 Nekura_Heko Patch - version 1995c (English translation)
Metal Gear [RC-750](T-Eng).rom ROM 3da994910180808cc03bbe3df973b55c
Metal Gear (T-Eng).mx2 ROM 6e5144f5c8e50fb2f8f00852cbf3d2ca TyrannoRanger/Mr. Dude Patch - version 1.0 (English translation)
Metal Gear [RC-750](T-Eng).rom ROM 8473c150867394a0f0de6e8d29c9a50a
Metal Gear 2: Solid Snake Topic GenMSX ✓ * Metal Gear 2 - Solid Snake (J).mx2 ROM MSX2 SCC 9f50d92d35e19d5de37d75a36a410588 af567ea6e27912d6d5bf1c8e9bc18e9b393fd1ab
Metal Gear 2 - Solid Snake (J) [Turbo Fix].mx2 ROM 72e813494dcacde3029a07db1ecca934
✓ * Metal Gear 2 - Solid Snake [T-Eng].mx2 ROM 668217f475619500c87f136949267b6d a7b196f7e934faa76602c8c00bd2f6e6d2d70787 English
Metal Gear 2 - Solid Snake [T-Eng+Turbo Fix].mx2 ROM 8fe72857b748852cec910345ce7a2b73 English
Metal Gear 2 - Solid Snake [T-Eng+Addendum].mx2 ROM c54d3657e78b1ecc7cfe4f641158fbff English
Metal Gear 2 - Solid Snake [T-Eng+Addendum+Turbo Fix].mx2 ROM a501ffaf9fb30c3a68c0c4c803fba341 English
Metal Gear 2 - Solid Snake [Addendum Only].mx2 ROM 01ec86d19248514baf263f0b60df4d0c English
Metal Gear 2 - Solid Snake [Addendum Only+Turbo Fix].mx2 ROM da8047597419d24897d8a43c0056876e English
Metal Gear 2 - Solid Snake [T-Por].mx2 ROM 614c03a00bfee70c581f759e96cdc099 Portuguese
Metal Gear 2 - Solid Snake [T-Por+Turbo Fix].mx2 ROM 70e3d3dd66a97aeef6a87db23fadfc32 Portuguese
Oh Shit! Topic GenMSX ? Oh_Shit.rom ROM MSX1 1721862f3f033e74607af9e26688403d 1d34e4e0
Picture Puzzle (HAL Laboratory, 1983) Topic GenMSX Picture Puzzle (Japan).rom ROM MSX1 9383ba8643fd1000b5cc099cf9d46822 336a7c451a03c9a55726d171603b54628ad832c8
Picture Puzzle (Japan) (Alt 1).rom ROM ac0bc988775b9c65c92cfb200f9b1beb
Picture Puzzle (Karoshi Corporation, 2004) Topic GenMSX Picture Puzzle v2 (2004)(Karoshi)[RK706].rom ROM MSX1 6ee570b6fa73fe9a147846078cddc11c 27e56fbec7fa39ce19d045b0dbc4217d290f92e2
Sudoku MSXdev '06 Topic GenMSX sudoku.rom ROM MSX1 2df142939c9e1147f814099856fd6361 120d477cd28b48b8a63efb34920ac331b54e66e5
The Treasure of Usas Topic GenMSX ✓ * Treasure of Usas, The (Japan, Europe).rom ROM MSX2 9aab75984b06c21ed8e6214474d3a68e 4ff2aad8371e382e203c7f29b665612a8c9d937c 30396650
Vampire Killer Topic GenMSX ✓ * Vampire Killer (Japan, Europe).rom ROM MSX2 92ba9dab3c7a4ac6c8a130f6ccbac91c 5ef7d03b138a2023f6def241b671c666f97ed83b 5953D084
Homebrew Prototype Super Mario World Topic MSX games world Super Mario World - Daemos et al. (2016)[Advanced Prototype][original] [3392].rom ROM MSX2(+) da28da0bb524bd0072e10b2799a88a75 77b37d7028d5f657239eb24f0c16097a6e183f8d 9d90c0a6
Mappy Topic GenMSX Mappy (Japan).rom / Mappy (1984) (Namcot) (J).rom ROM MSX1 134f8a060bb879a343afcae975e45adf e7d06c0a5c7f256c061e5b8173fdcc145d2fc4d6
Mappy (Japan) (Alt 1).rom ROM 1c8f344249b311b13ad4bade12ca49d3 a8313b0dce35faa80b399a220f19b04333fdec1d
Mappy (Japan) (Alt 2).rom ROM ac32e186da2c5cedc5abbdcabe7575ff
Penguin-kun Wars 2 Topic GenMSX ✓ * Penguin-kun Wars 2 (Japan).rom ROM 3db77573e81184156486fe743b828e58 b7104477c8801fe54d1ba91f3a77ac6e4f399f52
✓❗ Penguin-kun Wars 2 (Japan) + English Patch .rom ROM MSX2 d4f8d8a7e052a0d6246ac2b5afdc729e 9f476f544d1cd5f87d4ca19665ccdbf6ac0f68a0
Zoom 909 Topic GenMSX Zoom 909 (Japan).rom ROM MSX1 d8e09f622af52e07a83f19ca58aee194 07db3e3ffb16c138f9da12cacde48bf7522a188c 64283863
Space Manbow Topic GenMSX ✓ * Space Manbow (1989) (Konami) (J) ROM MSX2(+) SCC f78b9f4ea885cf072e5b41dce9f15436 f6199f48ff994fc9a8e33a8581bb3bb16dd301ab

Configuration options

Specify these in your RetroArch core options, either manually or via the RetroArch GUI.

A restart is required after changing most of these options.

setting meaning choices
(*) indicates the default setting
fmsx_mode MSX model MSX2+*|MSX1|MSX2
fmsx_video_mode select 60Hz or 50Hz NTSC*|PAL|Dynamic
fmsx_hires Support high resolution Off*|Interlaced|Progressive
fmsx_overscan Support overscan *No|Yes
fmsx_mapper_type_mode ROM mapper - use if a ROM does not load Guess*|Generic 8kB|Generic 16kB|Konami5 8kB|Konami4 8kB|ASCII 8kB|ASCII 16kB|GameMaster2|FMPAC
fmsx_ram_pages RAM size Auto*|64KB|128KB|256KB|512KB|4MB
fmsx_vram_pages Video-RAM size Auto*|32KB|64KB|128KB|192KB
fmsx_scci_megaram Enable SCC-I 128kB MegaRAM Yes*|No
fmsx_ym2413_core YM2413 (FM-PAC / MSX-MUSIC) core fMSX*|NukeYKT (no restart required)
fmsx_load_game_master Load GMASTER(2).ROM when present (will start Game Master before the game) No*|Yes
fmsx_simbdos Simulate BDOS DiskROM access calls (faster, but does not support CALL FORMAT) No*|Yes
fmsx_dos2 Load MSXDOS2.ROM when found No*|Yes
fmsx_autospace Autofire the spacebar No*|Yes
fmsx_allsprites Show all sprites - do not emulate VDP hardware limitation No*|Yes
fmsx_font load a fixed text font from RetroArch's system_directory standard*|DEFAULT.FNT|ITALIC.FNT|INTERNAT.FNT|CYRILLIC.FNT|KOREAN.FNT|JAPANESE.FNT
fmsx_flush_disk Save changes to .dsk image or SRAM Never*|Immediate|On close|To/From SRAM
fmsx_phantom_disk Create empty disk image when none loaded No*|Yes
fmsx_custom_keyboard_XXX
where XXX is up,down,left,right,a,b,y,x,start,select,l,r,l2,r2,l3,r3
For User 1 Device Type 'Custom Keyboard', map RetroPad button to selected MSX keyboard key left|up|right|down|
shift|ctrl|graph|
backspace|tab|escape|space|capslock|select|home|enter|del|insert|country|dead|stop|
f1|f2|f3|f4|f5|
keypad0~9|kp_multiply|kp_plus|kp_divide|kp_minus|kp_comma|kp_period|
backquote|minus|equals|leftbracket|rightbracket|backslash|semicolon|quote|comma|period|slash|
0-9|a-z|
fmsx_log_level Configure the amount of fMSX logging Off*|Info|Debug|Spam

PAL vs. NTSC

Selecting fmsx_video_mode 'PAL' or 'NTSC', as stated in the fMSX manual, will "set PAL/NTSC HBlank/VBlank periods" at startup. Also, the RetroArch framerate will be set to 50 resp. 60Hz. The RetroArch region is synchronized with the framerate.

However, those two settings do not take into account the internal VDP (Video Display Processor) behaviour related to the maximum number of scanlines and the line coincidence threshold. Also, some games may request to switch the mode.

To synchronize that, select 'Dynamic'. Models MSX1 and MSX2+ will then start up at 60Hz and adapt when a game switches to 50Hz. MSX2 by default starts up at 50Hz and likewise will switch to 60Hz.

In 'Dynamic' mode, press F8 to toggle between 50/PAL and 60/NTSC.

When switching modes, a notification will be shown.

The displayed number of scanlines (192 or 212) remains the same for PAL or NTSC.

BIOS

BIOS ROMs are loaded from RetroArch's system_directory. The screen will remain black if required ROMs are missing.

These BIOS ROMs are required for execution:

  • MSX1: MSX.ROM
  • MSX2: MSX2.ROM, MSX2EXT.ROM
  • MSX2+: MSX2P.ROM, MSX2PEXT.ROM

Optional; loaded when found:

  • DISK.ROM - required to be able to run .dsk and .m3u images. A notification will be shown for 10s when loading such an image without a proper DISK.ROM in place.
  • FMPAC.ROM
  • KANJI.ROM
  • MSXDOS2.ROM (MSX2/2+) - requires DISK.ROM too. When present, activates Disk BASIC 2.01.
  • PAINTER.ROM (MSX2/2+) - press space during boot to start
  • RS232.ROM - although serial COM I/O is removed in this core
  • CMOS.ROM - not a real ROM; a dump of the RTC contents (Real Time Clock; 52 Bytes)
  • GMASTER2.ROM, GMASTER.ROM - Konami's Game Master 2 & 1 (only one ROM is loaded; GM2 attempted first)

Mapping of controls

User 1:

  • "Joystick": map RetroPad to MSX joystick A
RetroPad MSX
LEFT Stick Left
UP Stick Up
DOWN Stick Down
RIGHT Stick Right
A Fire A
B Fire B
  • "Joystick + Emulated Keyboard": map RetroPad to MSX joystick A, plus to a few MSX keyboard keys useful for gaming
RetroPad MSX
LEFT Stick Left
UP Stick Up
DOWN Stick Down
RIGHT Stick Right
A Fire A
B Fire B
X F3
Y Space
START F1
SELECT F2
L F4
R F5
L2 Graph
R2 Ctrl
L3 Enter
R3 Escape
  • "Emulated Keyboard": map RetroPad to MSX keyboard cursor, plus to a few other MSX keyboard keys useful for gaming - where * indicates a difference with "Joystick + Emulated Keyboard"
RetroPad MSX
LEFT Arrow Left
UP Arrow Up
DOWN Arrow Down
RIGHT Arrow Right
A Space *
B Enter *
X N *
Y M *
START F1
SELECT F4 *
L F2 *
R F3 *
L2 Graph
R2 Ctrl
L3 F5 *
R3 Escape
  • "Custom Keyboard": maps 16 RetroPad buttons to any of the 88 keys of the MSX keyboard. Configure this in the Options.
  • "Keyboard": maps host keyboard to 88-key MSX keyboard. Only on (RetroArch) platforms with a real keyboard (Linux, Windows, etc). Don't forget to press Scroll Lock to enter Game Focus Mode!
    • MSX1 & 2: US/European keyboard map, cursors, numeric pad, F1-F5
    • MSX2+: Japanese JIS keyboard map - see below
    • with these special keys:
Host MSX
ctrl CONTROL
shift SHIFT
left alt GRAPH
ins INSERT
del DELETE
home HOME/CLS
end SELECT
pause STOP/BREAK
pagedown CODE/COUNTRY
pageup International: DEAD-key; accents `, ´, ^ and ¨
JIS: _ (underscore) and ろ
numpad enter numpad comma

User 2:

  • "Joystick": map RetroPad to MSX joystick B

MSX1/2 US/European keyboard map

Enter accented characters (like é) by holding CODE/COUNTRY (page down) together with a key or by preceding a key with DEAD (page up). Enter graphical symbols by holding GRAPH (left alt) together with a key.

There is more information about the MSX keymap.

MSX2+ Japanese keyboard map

This is a typical MSX2+ with Japanese (JIS) keyboard layout: Japanese keyboard

How to use this:

  • normal: bottomleft Roman letter/symbol
  • shift: topleft symbol
  • left alt ('GRAPH'): topright symbol (without the box)
  • KANA LOCK active: bottomright Japanese character
  • KANA LOCK active with shift: middleright Japanese character

To (de)activate KANA LOCK, press page down (COUNTRY). It works just like caps lock: press and release to enable.

Best enable SCREEN 1 to appreciate the full 8px width of the Japanese characters; in screen 0 characters are only 6px wide.

Sound & music

fmsx-libretro emulates:

  • PSG based on AY-3-8910: 3 channels with either tone or noise
  • MSX-MUSIC (a.k.a. FM-PAC) based on YM2413
    • 2 cores are available:
      • standard fMSX emulation is very poor: no drums, and all 6 (or 9) channel voices are rendered as triangle waves. It's also very loud; 16-32 times louder than PSG. Which is funny because some actual MSX hardware also had volume 'tuning' issues ;)
      • NukeYKT OPLL. Great sound, but a little more taxing on your hardware. For example, on a raspberry pi 3b, retroarch with lr-fmsx increases from approx. 25% to 60% CPU usage when enabling NukeYKT. Which is why it is disabled by default. The setting is effective immediately; no restart required. If your hardware is powerful enough, this mode is highly recommended. You will notice a difference in volume when switching back and forth. The NukeYKT core is actually balanced much better against the PSG, volume-wise.
    • the FM-PAC 8kB SRAM is supported - see section 'Saving state'
  • SCC and SCC-I including 128kB MegaRAM (a.k.a. SCC+): 5 channels of 32-Byte wavetable sound
    • SCC/SCC-I is emulated in both cartridge slots 1 and 2 - see section 'Memory layout'
    • Support for SCC/SCC-I detection and SCC-I MegaRAM was added to this libretro core; fMSX itself does not support either
    • SCC-I MegaRAM is enabled by default, and can be disabled using core option fmsx_scci_megaram for tight memory situations and backwards compatibility with previous save states.
    • The MegaRAM size is 128kB for compatibility with both SD-Snatcher as well as Snatcher and the various Konami Game Collections.

MSX-AUDIO, Moonblaster, MIDI or any other more advanced audio expansions are not supported.

Logging

When running into problems running a game, you can use logging to collect information.

Setting the fmsx_log_level has the following effects:

  • Off => (the default) no fMSX-specific logging; only RetroArch/libretro-related messages
  • Info => fMSX (startup) information logged
  • Debug => fMSX debug details logged
  • Spam => same, plus a lot of 'unknown I/O PORT' messages

Note: set the RetroArch log level to Info or Debug to be able to see these fMSX log messages!

See https://docs.libretro.com/guides/generating-retroarch-logs/ how to do that.

Or do it manually: edit ~/.config/retroarch/retroarch.cfg

log_verbosity = "true"    # needs to be true to see logs from a libretro core. Will also enable a lot of RetroArch logging.
libretro_log_level = "1"  # 0=debug, 1=info, 2=warn, 3=error

For the curious, here are the bitflags fMSX uses internally for various categories:

  • Info: Verbose!=0 => fMSX (startup) info
  • Debug: Verbose&0x02 => VDP
  • Debug: Verbose&0x04 => disk & tape incl. FDIDisk.Verbose & WD1793.Verbose
  • Debug: Verbose&0x08 => RAM/ROM mapper
  • (none) Verbose&0x10 => n/a
  • Spam: Verbose&0x20 => I/O

Limitations

Not supported:

  • Turbo-R (fMSX does not implement that platform)
  • Drive B
  • Cartridge slot 2
  • Printer
  • RS-232 serial COM
  • Mouse
  • FM-PAC drums
  • FM-PAC instruments are replaced by triangle waves
  • .. and anything that requires accurate timing, like the MSX2+ boot screen.

Technical details

Audio/Video

Video: 16bpp RGB565 (PSP: BGR565, PS2: BGR555) 272x228 (544x228 in 512px MSX2 screen modes). This includes an 8px border (16px horizontal in 512px modes).

MSX native screen resolutions are:

  • horizontal: 240, 256 or 512 (textmode: 32, 40 or 80 columns)
  • vertical: 192 or 212 (192-line mode adds 10px to vertical border top+bottom)

The MSX2 supports interlacing, which is used by some software. Combined with showing two alternating pages, this increases the maximum vertical resolution to 424, at the expense of halving the effective FPS to 25 (PAL) or 30 (NTSC). Setting fmsx_hires to "Interlaced" will approximate an interlaced screen. The approximation suffers from 'time-based aliasing', most prominent when this core's FPS is not equal to that of the actual display. Setting fmsx_hires to "Progressive" is less authentic, but more pleasing to the eye.

Some games and demos create an overscan effect. On a real MSX, this can go up to 256 vertical lines (PAL) or 243 (NTSC). A part of the overscan is then actually displayed on top of the screen, replacing the top border. This core supports limited overscan, when enabled (fmsx_overscan=Yes). The lines beyond 212 will be displayed at the bottom. No attempt is made to display them on top. Most software that does overscan will apply custom blanking, e.g., at line 224. Overscanned lines beyond those are not shown. The bottom border is not drawn when overscan is active. A limitation: in text mode overscan, incorrect text characters are shown.

In theory, an MSX2 can show 512x512 pixels by combining interlacing with overscan in PAL mode.

In hires mode, the vertical output resolution will be doubled. Combined with overscan, this can result into maximum 528 vertical lines. RetroArch will automatically scale this to retain aspect ratio and window size.

Audio: rendered in 48kHz 16b signed mono.

Framerate: NTSC (US/JP) implies 60Hz - thus 60FPS, PAL (EU) implies 50Hz (=50FPS). Gameplay and audio actually becomes 17% slower when switching from NTSC to PAL - just like on a real MSX.

Memory layout

Unlike BlueMSX and openMSX, fMSX does not implement any or all specific models sold historically. The memory and slot layout of this 'derivative' MSX model differs for model MSX1 vs. MSX2/2+.

MSX1

primary slot 0 1 2 3 Address range
subslot n/a n/a n/a 3-0 3-1 3-2 3-3
page 3 ROM content or empty same RAM mapper ^ 0xC000-0xFFFF
page 2 ROM content, Game Master 2 or SCC-I MegaRAM same FMPAC # RAM mapper ^ 0x8000-0xBFFF
page 1 BASIC ^ ROM content, Game Master 1/2 or SCC-I MegaRAM same FMPAC # disk ROM *# RAM mapper RS-232 # 0x4000-0x7FFF
page 0 BIOS ^ ROM content or empty same RAM mapper 0x0000-0x3FFF

Legend:

  • ^: active page at startup
  • *: page selected in slot at startup
  • #: optional; ROM loaded if present

Regarding game ROM contents:

  • In most cases, the game is mapped to slot 1 (external slot A). Slot 2 (B) is unused.
  • Game Master, when present, is always mapped to slot 1.
  • Game Master 2 (GM2), when present, is mapped to slot 1 except for Contra & Hai no Majutsushi. For those 2 games, GMASTER2.ROM is mapped to slot 2. They only use GM2 for SRAM saves.
  • The game (ROM content) is then mapped to the other external slot, i.e., slot 2 or 1.
  • The SCC-I MegaRAM is available in a free cartridge slot. When both are free, it is mirrored in cartridge slots 1 and 2. When a Game Master as well a game ROM is loaded, SCC-I MegaRAM is not available.
  • The SCC/SCC-I music chip is available in a free cartridge slot, and in any cartridge slot with a ROM with "Generic 8kB" or "Konami5 8kB" mapper.

MSX2/2+

For these two models, slot 0 is also expanded, and more optional roms are loaded when present.

primary slot 0 1 2 3 Address range
subslot 0-0 0-1 0-2 0-3 n/a n/a 3-0 3-1 3-2 3-3
page 3 b ROM content or empty same a RAM mapper ^ 0xC000-0xFFFF
page 2 b c ROM content, Game Master 2 or SCC-I MegaRAM same a / MSXDOS2 *# RAM mapper ^ 0x8000-0xBFFF
page 1 BASIC ^ b c ROM content, Game Master 1/2 or SCC-I MegaRAM same a / MSXDOS2 *# disk ROM *# RAM mapper RS-232 # 0x4000-0x7FFF
page 0 BIOS ^ b ROM content or empty same a extended BIOS * RAM mapper 0x0000-0x3FFF

Legend:

  • ^: active page at startup
  • *: page selected in slot at startup
  • #: optional; ROM loaded if present
  • a-c: fMSX loads some optional ROMs, if present. The ROMs are mapped in the order indicated by letters a~c.

If all three optional 'dynamically mapped' ROMs are loaded, they are mapped to the following subslots:

  • [3-0] MSXDOS2 (64k, mapped to p1-2)
  • [0-1] PAINTER.ROM (64k, all 4 pages)
  • [0-2] FMPAC.ROM (64k, mapped to p1-2)

Regarding game ROM contents, SCC-I MegaRAM and SCC/SCC-I music, the same applies as described for MSX1 above.

The MSXDOS2 ROM (always in 3-0), when loaded, extends the DISK.ROM (in 3-1).

The RS232 ROM, when present, is always mapped to 3-3.

MSX1 colour palette

"To make a custom palette for Game.rom, create Game.pal [in the same directory] containing 16 #RRGGBB hex values, one per line. This palette file will be loaded automatically." (fMSX site, section "New in fMSX 4.0")

The fMSX default:

#000000
#000000
#20C020
#60E060
#2020E0
#4060E0
#A02020
#40C0E0
#E02020
#E06060
#C0C020
#C0C080
#208020
#C040A0
#A0A0A0
#E0E0E0

Note: there is some discussion about the 'right' mapping of TMS9918 colours to RGB. This is how fMSX does it.

An example alternative palette with less vibrant colours is:

#000000
#010101
#3eb849
#74d07d
#5955e0
#8076f1
#b95e51
#65dbef
#db6559
#ff897d
#ccc35e
#ded087
#3aa241
#b766b5
#cccccc
#ffffff

Colours are rendered as RGB565 (16 bit). Due to rounding down in conversion from RGB888 32 bit, the colours mentioned above can lose some detail. E.g., #2020E0 (blue) is converted for RetroArch to RGB565 (3,7,27) which, when shown on a 32b display, actually displays as #181cd8.

Developers

Some information for developers wanting to upgrade to newer fMSX versions, or improve this port.

Changes applied to the fMSX sources in this port

Some changes are applied to the fMSX core in order to make fmsx-libretro portable & efficient for its target audience.

  • portability refactorings, e.g. register flags removed, PS Vita file support, etc.
  • (verbose) logging removed, including startup info & some debugging statements
  • some whitespace
  • EMULib.c WaitJoystick() removed; implemented another way in libretro.c
  • RetroArch VFS (Virtual FileSystem) used (rfopen etc.); ZLIB code removed
  • removed various pieces of code intended for older ports, like Borland C, Meego, etc.
  • removed various pieces of code intended for other platforms (fMSX is part of a suite of emulators)
  • removed SndDriver; implemented another way in libretro.c
  • reimplemented state loading/saving
    • note: Save1793() is never invoked! The WD1793 FDC is supposed to be 'at rest' when saving state. This means: don't save state during disk writes. All other hard- & software state is fully captured. fMSX has the same behaviour.
  • switched MSB first/LSB first
  • due to the fact that fmsx-libretro renders audio&video per frame:
    • delay invocation of SyncSCC()/Sync2413() to fix a sound interference bug
    • drop invocation of PlayAllSound()
    • MSX.c LoopZ80(): move if(ExitNow) return(INT_QUIT) downwards to support autospace option.

non-ported/dropped fMSX features

Mostly because RetroArch supports this out of the box, or because it falls out of scope.

  • built-in debugger
  • in-emulator options menu
  • MIDI sound export ('MIDI logging')
  • IPS patching
  • custom shader-like effects
  • cheat 'hunter'
  • net play
  • record & playback
  • support for touch devices
  • mouse in both joystick & real mode
  • serial COM
  • printer

The following fMSX code is not present in this core:

  • fMSX/Unix-related code
  • EMULib: EMULib.c, Console(Mux).c/h, Hunt.c/h, Image.c, ImageMux.h, IPS.c/h, MIDIFreq.h, NetPlay.c/h, Record.c/h, Touch(Mux).c/h
  • fMSX: fMSX.c, fMSX.html, Help.h, Menu.c, I8251.c/h
  • Z80: (Con)Debug.c

non-ported/supported fMSX cmdline options

  • all of these options:

    -verbose
    -skip - always 0 -help
    -home
    -printer -serial
    -diskb
    -font
    -logsnd - MIDI logging removed -state
    -joy - both joysticks always on. Both mouse modes unsupported. -sound [] - always 48kHz -nosound

  • All effects-related options

  • All options based on a platform-specific #define (incl. -static, -nosync & -sync)

About

Port of fMSX to the libretro API.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published