MSXLaunch
Latest Build: v0.1b (beta), September 1, 2019

INTRODUCTION
------------
MSXLaunch is a menu system to catalog and launch your MSX ROMs, for the
distinguished APMSX connoisseur. Some highlights include:

- Uses only 6502 opcodes and fits in 64KB of RAM (should work on 64K
  Apple II Plus)
- User-editable ROM directory file
- Selectable slot, Z80 speed, and more
- Supports MegaROMs with custom mapper settings
- Made with an Apple IIe and Merlin 8 Pro

COMPATIBILITY
-------------
- Nobody I know has ever gotten APMSX working on an Apple IIgs
- For best compatibility, remove FastChip IIe completely, don't just disable.
  It will work with a disabled FastChip IIe, but some ROMs don't work, and
  often you'll have to reboot completely to get the next one to work.
  Nobody I know has ever gotten APMSX working with an enabled FastChip IIe.

INSTALLING MSXLaunch
--------------------
Just copy the MSXLAUNCH SYS file as well as the MSXDIR text file into the
directory containing your MSX ROMs. Next, make sure your MSXDIR file is
correct.

MODIFYING MSXDIR
----------------
The format of the MSXDIR text file is as follows:

First there is a configuration record consisting of:
%
1
0
^
The % is a header specifying the configuration record.
The '1' is the slot number of your APMSX card. Change this if it isn't 1 or
you'll have to use the 'S' key to set your APMSX slot everytime you use
MSXLaunch.
The '0' is currently reserved.
The ^ is the end-of-record delimiter.

Next, there are up to 255 ROM records (no, we don't do 16-bit math yet)
consisting of:
ROMFILENAME
Readable text description
MEGAROMPART2
MEGAROMPART3
MEGAROMPART4
MEGAROMPART5
MEGAROMPART6
MEGAROMPART7
MEGAROMPART8
^

Notice that most records will not have additional 32KB mega-ROM parts, so
those entries are optional.

A note about mega-ROMs: MSXLauncher will assume mapper bit setting $09 for
mega-ROMs, unless there is an extra line containing a + before the end-of-
record delimiter, in which case it will assume $11. This helps to set the
proper mapper bits for compatibility.

These are examples of valid records:

[ Example 1: 8-part Mega-ROM with $09 bit setting ]
G3.1
Gradius 3 (Nemesis 3) (1988)
G3.2
G3.3
G3.4
G3.5
G3.6
G3.7
G3.8
^

[ Example 2: 1-part ROM ]
GUARDIC.MSX
Guardic (1986)
^

[ Example 3: 4-part Mega-ROM with $11 bit setting ]
ALIENS20.BIN
Aliens. Alien 2 (1987)
ALIENS21.BIN
ALIENS22.BIN
ALIENS23.BIN
+
^

You probably already have most of the ROMs in the provided sample MSXDIR file.
Note that if you make a mistake in the MSXDIR file, MSXLaunch will likely
crash. Its parser isn't particularly forgiving, and it can't really be.

RUNNING MSXLaunch
-----------------
MSXLaunch looks at $280 to find the pathname that was used to invoke it. It
uses this path to make sure the ProDOS prefix is set so it can find MSXDIR.
If it can't load MSXDIR, it will show an error message and quit and we'll be
sad.

If everything worked, you'll see the menu.

USING MSXLaunch
---------------
If the 'Slot' shown at lower-right isn't correct, you can tap the 'S' key to
change it until it is correct (although you'll probably just want to change
line 2 of the MSXDIR file).

The up/down arrow keys (ctrl-J/ctrl-K on Apple II+) will select the ROM to
launch. You can hold down the Open Apple key while doing this to navigate a 
full page at a time.

The Return key will launch the selected ROM.

While a ROM is running, the Z key will change the speed of the Z80 CPU. It
stops the CPU, changes the speed setting, then un-stops it. This seems to be
the most reliable way to do on-the-fly speed changes.

Note that after starting a ROM, the most reliable way to start another is to
hold Ctrl-Reset, which resets both the APMSX card and MSXLauncher. You can
just use the arrow keys and Return to start another ROM without doing Ctrl-
Reset, but it's less likely to work because of the unknown state of the APMSX
card.

TECH NOTES
----------
Notice that I build up a routine at $300 to do LDA #00 ; STA $Cx00 ; RTS.
Why didn't I just do that inside the main program at $9xxx? Because it doesn't
work if executed from there! Nobody knows why this is, but likely an artifact
of the $1000-$9000 'windowing' from APMSX.

If you've developed a patch for MSXLaunch, it will be reviewed and merged
promptly if sent to msxlaunch@ballmerpeak.org

LICENSE (MIT)
-------------
Copyright (c) 2019 ballmerpeak

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.