yamazakiyasuhiro/webmsx

WebMSX - Online MSX Emulator

WebMSX

WebMSX, or simply WMSX, is a new cross platform MSX emulator designed for the Web.

WebMSX is great for displaying MSX software running inside webpages. You can launch the emulator and load ROMs, DSK and CAS images with a single link.

Please go to http://webmsx.org to enjoy it online!

Refer to /doc for parameters reference and URL usage examples. Refer to /release for stable release files and deployment examples.

New in Version 4.0

• Support for mobile iOS and Android devices
• Finally enjoy MSX games on your iPhone/iPad!
• Customizable Touch Controls, Virtual Keyboard, with Haptic feedback
• Install as a WebApp on iOS/Android/Desktop, then run offline!
• Open files from local storage, iCloud, Google Drive, Dropbox, web links
• Higher resolution GUI for high-density displays, Retina displays
• Menu navigation by keys. Easy GUI switches for most used options
• CPU Turbo mode @ 7.16MHz

Features

• 9 Generic machines (MSX1, MSX2, MSX2+). NTSC 60Hz or PAL 50Hz
• PSG, SCC, SCC-I, FM-PAC, PCM and MSX-MUSIC sound
• Cross platform HTML5/JS. Runs in any Browser, tested in Chrome/Firefox/Safari
• Finally enjoy MSX games on your iPhone/iPad
• Customizable Touch Controls/Virtual Keyboard for mobile devices (iOS, Android)
• Install as a WebApp, then run offline
• Put games or any MSX software in webpages easily
• Show MSX software running with a single link to the WebMSX page
• Play Cartridge ROMs, Disk and Tape images
• Powerful Drag & Drop system for loading media files
• Load several disks at once and easily switch disks
• "Files as Disk" and "ZIP as Disk" emulation
• Savestates support. Export and share Savestate files
• Fully customizable Keyboard, Joysticks, Joykeys, Mouse and Touch controllers
• Joykeys support. Emulate MSX Joysticks using Host Keyboard
• Virtual buttons. Map Host Joystick buttons to MSX Keyboard keys
• Easily toggle extensions like SCC, PAC, DOS2, etc.
• Adjustable speed, Pause and Frame-by-frame advance. CPU Turbo mode
• Copy & Paste text, Screen Capture, Debug modes
• Resizable Screen, Full Screen mode
• Javascript API for loading media and machine control

WebMSX Configuration and Launch Options

Several parameters are available for customizing the emulator. They can be changed either directly in Javascript if you are hosting the emulator in your own page, or via URL Query Parameters if you are creating links or bookmarks to open the emulator, or just using it in your browser.

All parameters are in the form of properties in the global object WMSX. Just set these object properties in Javascript, or use URL Query parameter/value pairs. For example:

WMSX.ROM = "files/Game.rom";      is the same as      http://webmsx.org?ROM=files/Game.rom

IMPORTANT: Any parameter setting via Javascript must be done AFTER importing the webmsx.js file.

Another important concept is the use of configuration Presets. Some configurations are a bit complicated and may require setting various parameters in conjunction. For those cases, its easier to use a Preset that will automatically set all the relevant parameters for a specific task. You may specify any number of Presets to be used by setting the PRESETS parameter, with a comma separated list of the Preset names to apply. For example:

WMSX.PRESETS = "RAM128, NODISK";         or           http://webmsx.org?PRESETS=RAM128,NODISK

Media Loading

The emulator can be set to automatically load files like ROMs, DSK and CAS images. Additionally, normal "loose" files can be loaded and automatically put in a Disk image. Image files may be compressed in ZIP or GZIP formats. If several Disk images are found in a ZIP file, all of them (up to 10) will be loaded in the Drive Stack. Available parameters:

Parameter	Function	Shortcut for URL form
CARTRIDGE1_URL	URL of ROM image file to load in Slot 1	ROM, CART1
CARTRIDGE2_URL	URL of ROM image file to load in Slot 2	CART2
CARTRIDGE1_FORMAT	Force ROM Format for Cartridge in Slot 1	ROM_FORMAT, CART1_FORMAT
CARTRIDGE2_FORMAT	Force ROM Format for Cartridge in Slot 2	CART2_FORMAT
DISKA_URL	URL of Disk image file to load in Drive A:	DISK, DISKA
DISKB_URL	URL of Disk image file to load in Drive B:	DISKB
DISKA_FILES_URL	URL of "loose" file or ZIP file to load "as Disk" in Drive A:	DISK_FILES, DISKA_FILES
DISKB_FILES_URL	URL of "loose" file or ZIP file to load "as Disk" in Drive B:	DISKB_FILES
TAPE_URL	URL of Tape image file to load	TAPE
STATE_URL	URL of SaveState file to load	STATE, SAVESTATE
AUTODETECT_URL	URL of file to load with media auto-detection	AUTODETECT, AUTO, ANY

ROM Format (or Mapper Type)

The ROM Format is auto-detected. To force a format, use the CARTRIDGE1_FORMAT and CARTRIDGE2_FORMAT parameters. You can also put the format specification in the ROM file name, between brackets. Example: Game [KonamiSCC].rom

Valid Formats

Normal, Mirrored, NotMirrored, ASCII8, ASCII16, Konami, KonamiSCC, KonamiSCCI, ASCII8SRAM2, ASCII8SRAM8, ASCII16SRAM2, ASCII16SRAM8, GameMaster2, KoeiSRAM8, KoeiSRAM32, Wizardry, FMPAC, FMPAK, MSXDOS2, Majutsushi, Synthesizer, RType, CrossBlaim, Manbow2, HarryFox, AlQuran, AlQuranDecoded, Halnote, SuperSwangi, SuperLodeRunner, Dooly, Zemina80in1, Zemina90in1, Zemina126in1, MSXWrite

Enabling Extensions

The emulator supports several Extensions, or optional components that can be turned on/off. Some are in the form of expansion cartridges that can be inserted in either Slot 1 or 2. We use Presets to make configuring Extensions easier:

Extension	Default in Machine	Presets
Disk interface with 2 drives	ALL	DISK, NODISK
Standard RAM Mapper, adjustable size	MSX2, MSX2+	RAM128..RAM4096, NORAMMAPPER
MSX-MUSIC sound with BASIC extension	MSX2, MSX2+	MSXMUSIC, NOMSXMUSIC
Support for Kanji Characters	Japanese MSX2, MSX2+	KANJI, NOKANJI
MSX-DOS 2 ROM Cartridge	--	DOS2
SCC-I Sound Cartridge with 128K RAM	--	SCCI, SCCI2 (in Slot 2)
SCC Sound Cartridge	--	SCC, SCC2 (in Slot 2)
PAC SRAM Cartridge	--	PAC, PAC2 (in Slot 2)

Loading BASIC files and Typing commands after launch

The emulator can be set to automatically Run/Load BASIC programs after launch, or type any commands or text in the BASIC prompt. NOTE that these are not necessary for AUTOEXEC.BAS and AUTOEXEC.BAT files, or if you have loaded a Tape Image file (in which case the emulator will automatically detect and Run the first program in the Tape). Available parameters:

Parameter	Action
BASIC_RUN	Run the specified file name
BASIC_LOAD	Load the specified file name
BASIC_ENTER	Type the specified text then hit ENTER
BASIC_TYPE	Type the specified text

Choosing a Machine

There are 9 different generic machines to choose from. The default machine is the MSX2+, and the emulator will try to auto-detect your region. You can ask for a specific machine by setting the MACHINE parameter with the respective Machine ID:

Machine	Machine ID	Specific Machine	Machine ID
MSX2+ Auto-detection	MSX2P	MSX2+ American (NTSC 60Hz)	MSX2PA
		MSX2+ European (PAL 50Hz)	MSX2PE
		MSX2+ Japanese (NTSC 60Hz)	MSX2PJ
MSX2 Auto-detection	MSX2	MSX2 American (NTSC 60Hz)	MSX2A
		MSX2 European (PAL 50Hz)	MSX2E
		MSX2 Japanese (NTSC 60Hz)	MSX2J
MSX1 Auto-detection	MSX1	MSX1 American (NTSC 60Hz)	MSX1A
		MSX1 European (PAL 50Hz)	MSX1E
		MSX1 Japanese (NTSC 60Hz)	MSX1J

Launch URL Examples

WebMSX is great for displaying MSX software in the web. With a simple URL, you can launch the emulator and automatically load and run anything. You may combine several settings and media loading options in a single link. Here are some examples:

• To load a game in ROM format:

http://webmsx.org?ROM=http://gamesarchive.org/Goonies.rom

• To load a game in a ZIPped Disk Image and insert a SCC+ Sound Cartridge:

http://webmsx.org?DISK=http://gamesarchive.org/SDSnatcher.zip&PRESETS=SCCI

• To launch an European MSX1 machine, loading a Disk image and then run a BASIC program:

http://webmsx.org?MACHINE=MSX1E&DISK=http://basicmuseum.org/Demos.dsk&BASIC_RUN=Bubbles.bas

Parameters Reference

Parameter	Default	Description
MACHINE	--	Machine Type. Leave blank for auto-detection
PRESETS	--	Configuration Presets names to apply, comma separated
CARTRIDGE1_URL	--	URL of ROM image file to load in Slot 1
CARTRIDGE2_URL	--	URL of ROM image file to load in Slot 2
CARTRIDGE1_FORMAT	--	ROM Format for Cartridge in Slot 1
CARTRIDGE2_FORMAT	--	ROM Format for Cartridge in Slot 2
DISKA_URL	--	URL of Disk image file to load in Drive A:
DISKB_URL	--	URL of Disk image file to load in Drive B:
DISKA_FILES_URL	--	URL of "loose" file or ZIP file to load "as Disk" in Drive A:
DISKB_FILES_URL	--	URL of "loose" file or ZIP file to load "as Disk" in Drive B:
TAPE_URL	--	URL of Tape image file to load
STATE_URL	--	URL of SaveState file to load
AUTODETECT_URL	--	URL of file to load with media auto-detection
BASIC_RUN	--	Run the specified file name
BASIC_LOAD	--	Load the specified file name
BASIC_BRUN	--	Run the specified binary file name
BASIC_BLOAD	--	Load the specified binary file name
BASIC_ENTER	--	Type the specified text then hit ENTER
BASIC_TYPE	--	Type the specified text
SCREEN_ELEMENT_ID	"wmsx-screen"	HTML Element ID to place the Emulator Screen
ALLOW_URL_PARAMETERS	true	Allows overriding any parameters via URL query parameters
AUTO_START	true	Auto-Start the emulator as soon as ready
AUTO_POWER_ON_DELAY	1600	Auto-Power-ON after specified msecs. -1: no Auto-Power-ON
RAMMAPPER_SIZE	512	RAM Mapper size. 128, 256, 512 .. 4096, if enabled
CARTRIDGE1_SLOT	[1]	Slot specification for Cartridge Slot 1
CARTRIDGE2_SLOT	[2, 0]	Slot specification for Cartridge Slot 2
MEDIA_CHANGE_DISABLED	false	Block user from changing Media (Cartridges, Disks, etc)
SCREEN_RESIZE_DISABLED	false	Block user from changing Sreen size
SCREEN_FULLSCREEN_MODE	-1	FullScreen mode. -2: disabled; -1: auto; 0: off; 1: on
SCREEN_FILTER_MODE	-1	Screen CRT Filter level. -2: browser default; -1: auto; 0..3: smoothing level
SCREEN_CRT_MODE	-1	Screen CRT Phosphor Effect. -1: auto; 0: off; 1: on
SCREEN_DEFAULT_SCALE	-1	Screen size. -1: auto; 0.5..N in 0.1 steps
SCREEN_DEFAULT_ASPECT	1.1	Screen aspect ratio (width) in 0.1 steps
SCREEN_CONTROL_BAR	1	Screen Bottom Bar controls. 0: on hover; 1: always
SCREEN_FORCE_HOST_NATIVE_FPS	-1	Force host native video frequency. -1: auto-detect. Don't change! :-)
SCREEN_VSYNCH_MODE	1	V-Synch mode. -1: disabled; 0: off; 1: on
AUDIO_MONITOR_BUFFER_BASE	-1	Audio buffer base size. 2: disable audio; -1: auto; 0: platform default; 1..6: base value. More buffer = more delay
AUDIO_MONITOR_BUFFER_SIZE	-1	Audio buffer size. -1: auto; 256, 512, 1024, 2048, 4096, 8192, 16384: buffer size. More buffer = more delay. Don't change! :-)
AUDIO_SIGNAL_BUFFER_RATIO	2	Internal Audio Signal buffer based on Monitor buffer
AUDIO_SIGNAL_ADD_FRAMES	3	Additional frames in internal Audio Signal buffer based on Monitor buffer
CPU_TURBO_MODE	0	CPU Turbo (7.16MHz). 0: off; 1: on
MOUSE_MODE	0	Mouse control. -1: disabled; 0: auto; 1: enabled at port 1; 2: enabled at port 2
TOUCH_MODE	0	Touch control. -1: disabled; 0: auto; 1: enabled at port 1; 2: enabled at port 2
KEYBOARD_JAPAN_LAYOUT	1	Japanese keyboard layout. 0: ANSI, 1: JIS