meisei 1.2.3 is a freeware open-source MSX emulator derived from Sega Li,
for Microsoft Windows, (C) 2005-2008 hap, http://hap.samor.nl/

Sega Li 1.12p (C) 2005-2008 hap, http://hap.samor.nl/
ti_ntsc 0.1.0 (C) 2005-2007 Shay Green, http://www.slack.net/~ant/
zlib 1.2.3 (C) 1995-2005 Jean-loup Gailly and Mark Adler, http://www.zlib.net/
unzip 1.01e (C) 1998-2005 Gilles Vollant, http://www.winimage.com/zLibDll/minizip.html

Z80 emulation mostly based on Zilog's official documentation, and "undocumented"
documentation by Sean Young and Jan Wilmans. TMS9918 emulation based on Texas
Instruments' datasheet, documentation by Sean Young, and my own research.
YM2149 emulation based on AY-3-8910 datasheet, and detailed information from the
MAME team. Mappers and SCC emulation mostly based on information by Sean Young.

Compiled with GCC 4.3.2, using MinGW, http://www.mingw.org/

Executable bundled with Kaillera client 0.9 modified by ? (C) 2001-2003 Christophe
Thibault, http://www.kaillera.com/, C-BIOS 0.21 (C) 2002-2005 C-BIOS team,
http://cbios.sourceforge.net/, Montana John and the Templar's Treasure (C) 2008
Infinite, and Universe: Unknown (C) 2005 Infinite, http://www.infinitemsx.org/

Also thanks to: ARTRAG, BiFiMSX, blargg, Dave, Disch, dvik, GuyveR800,
MAME team, Martin Freij, Martin Korth, NewRisingSun, openMSX team, Quibus,
Quietust, Samor, Vampier, Wolf, wouter.

MSX is a trademark of MSX LC.

meisei may be freely distributed, not for commercial purposes.
The source code can be obtained from my homepage. If you want to reuse anything,
go ahead, as long as you credit me, and your project is open source too.

meisei doesn't have any official forum, but you may discuss it on the MRC
( http://www.msx.org/ ) emulation subforum.


== Hello? ==

Least but not last, meisei is an MSX emulator, it does not emulate the MSX2.
The MSX was a Japanese 8-bit home computer standard that sadly failed success
outside Japan and scattered regions throughout the world, including the tiny
country I live in. To anyone that never heard of the MSX, the MSX hardware is
very similar to that of Coleco's ColecoVision. If you've never heard of the
ColecoVision either, just look it up on Wikipedia then. Ok, now that most
readers got stuck on Wikipedia, let's continue with the details.


== Tails? ==

I'll explain some details that aren't very straightforward.

* Opening a game/program
Before starting, you might want to download several MSX1 BIOS ROMs for better
compatibility. C-BIOS is alright, but it won't start disks, tapes, or BASIC ROMs.
In order to boot disks, you'll need to place Vincent van Dam's DSK2ROM.ROM into
the executable folder, it's available at http://home.kabelfoon.nl/~vincentd/ .
As a side effect, disks are write-protected. I'll add real diskdrive emulation
later.

Optional sound samples (gamename.zip with numbered .wav samples), currently
only used by Playball, and IPS patches (gamename.zip/ips) will be loaded
automatically. Hold Shift while loading a file from the media dialog to skip
automatic soft patching.

MSX ROMs are headerless, so it's up to you to pick the mapper type. meisei
makes it a bit easier by having an internal database with some GoodMSX ROMs,
and autodetection for simple ROMs. It's also possible to specify the mapper
type inside the ROM filename, case insensitive, like gamename {type}.rom:

ASCII 8 {A8}, ASCII 8 + SRAM {A8S}, ASCII 16 {A16}, ASCII 16 + SRAM {A16S},
Bootleg 80-in-1 {B80}, Bootleg 90-in-1 {B90}, Bootleg 126-in-1 {B126},
dB-Soft Cross Blaim {CB}, Irem R-Type {RT}, Koei {KOEI}, Konami {K},
Konami Game Master 2 {GM2}, Konami SCC {SCC}, Konami Sound Cartridge {SCCI},
Konami Synthesizer {KS}, Manuel Mega Flash ROM SCC {MFR}, Matra INK {INK},
MicroCabin Harry Fox {HF}, Simple mirrored/$0000/$4000/$8000/$C000 {M/0/4/8/C},
Sony Playball {PB}, Zemina ZMB {ZMB}

Most commonly, MSX tape dumps are of the fMSX CAS format, which is currently
the only supported tape format in meisei. After inserting a tape, the selected
block denotes the tape position. Right-click on a block for a number of options.
For obvious reasons, the tape is only writable on a free block inserted by the
user.

Tape loading commands from BASIC differ per block type:
BASIC:	CLOAD (after loading, press F5 to run)
binary:	BLOAD"CAS:",R
ASCII:	RUN"CAS:"

* Netplay
meisei uses Kaillera, a closed source netplay solution with an external DLL
and separate server software. If you don't trust this, you can rename or
remove kailleraclient.dll, or just never start netplay. To start netplay,
pick a server and join it, then create a game or join an existing one. Make
sure that you and the other player use the exact same MSX state (game filename,
BIOS checksum, cartridge checksums, mapper types, CPU speed, video format).
Kaillera settings are saved into kaillera.ini in your Windows folder.

If you want to run your own server, or play on a LAN, get the official server
software from http://www.kaillera.com/, or EmuLinker from http://www.emulinker.org/

* Reverse/Savestates/Movies
Reverse emulation (default key: F11) is a useful feature that allows you to
rewind to correct mistakes, or watch an instant replay. It's also pretty funny
if you combine it with Slowdown or Speed Up (default keys: F10,F12). To continue
after reverse, press any MSX key/button. If you're using a joypad, I suggest you
to map reverse to the left shoulder button, and speed up to the right one.
In pause state, reverse and speed up allow you to step through emulation frame
by frame. Reverse uses a lot of resources though, so if you're not using it,
disable it.

Savestates and movies work similar to other emulators, with numbered file slots
for quick loading/saving, and one custom slot. One temporary memory slot is
included, that won't save to a file. Movie recording can be combined with
reverse, to allow perfect looking playback, or so-called tool assisted speedruns.
You can continue a movie recording by pressing record during movie playback,
it will continue from that point, not from the end. Savestates will be compatible
with future versions of meisei, movies will not.

meisei supports subtitles on movies with an external text file in the States
folder. If the movie file is called gamename.m0, the subtitles file should be
named gamename.m0.txt. You'll have to create and edit the file yourself, an
example, with added information, is shown underneath:

meisei movie subtitles

; This is a comment, they are not allowed inside subtitles.
; The 1st line "meisei movie subtitles" is required, it's the file header.

00:01:08;00
After 1 min 8 secs I lose a life already!

00:03:34;00
WOW! Look at this nutter,
he looks like Chewbacca,
dipped in peanut butter.

; Placing <id,cc,yy> in front of a subtitle, each 2 digits long, where
; id=unique subtitle id, cc=colour, and yy=y axis location, allows for more
; control. But that's a bit advanced, unless you understand the internal
; message system in meisei.
00:04:00;00
<01,06,00>green :D
<02,03,04>red, and 4 spaces under green

* Video
Doubleclick on the main window to switch to/from full screen. If meisei is
running too slow, set the video signal to RGB.

The only other detail I want to point out is that the internal TMS9918/J palette
is an estimate, you're probably better off using the TMS9129 palette, rotating
the hue 15 degrees to the right, combined with a Japanese tv decoder, and of
course a composite video signal.

* Controls
meisei uses powerful input trigger rules to customise controls, eg. by default
you can toggle between keyboard and keyboard-joystick (up down left right Z X)
with Scroll Lock, with rapid fire buttons by holding shift. These, along with
some other settings that aren't in the GUI, can be edited in the .ini file
generated by meisei on exit.

+ Default commonly used controls:
F6/F7: Change Savestate/Movie slot
F8: Save State
F9: Load State
F10 (hold): Slowdown
F11 (hold): Reverse
F12 (hold): Fast forward

+ Default controls for MSX keys unavailable on PC keyboards:
Graph: Left Alt
Code: Right Alt
Stop: Page Up
Select: End
Accent Mark: Page Down

I'll quickly mention the included games' controls too. For more information
about these games, check their documentation on the archive on my homepage.
Montana John and the Templar's Treasure: up/down/left/right/SPACE, F1 for menu.
Universe: Unknown: up/down/left/right/SPACE, N+up/down to select weapon.


== Advanced ==

The advanced features are intended for people who know a bit more about (MSX)
computers rather than just using the software, hence I'm not going to explain
their concepts. Most of it is still pretty straightforward though.

* Tile/Sprite Viewer

Right-click on the pattern area to enter a popup menu, the tile/sprite editor
can be reached from there. Inside the editor, use the mouse to edit in Polka
fashion. Drag with the left mouse button while holding shift, and undo/redo
with Ctrl+Z/Y. Uncommonly used controls, optionally in combination with Shift
where applicable, are [E]rase, [H]orizontal flip, [V]ertical flip, [R]otate
(sprite editor only), and [C]hange view colour (sprite editor only).

Saved pattern- and screen files are mostly compatible with eachother.

* PSG Toy

If you encounter problems with MIDI logging due to a game having its notes on
edges of the default tuned cents, adjust the cents offset by right-clicking
on the piano.

The channel waveforms feature doesn't sacrifice emulation accuracy, just audio
output accuracy. Use the mouse buttons to draw waves. Mind that due to tone+noise
handling, the left side of the waveform is prefered to be positive, and the right
side negative. To preview(listen) a channel, left click on the piano or press P.
Copy/paste to other channels with Ctrl+C/V.


== Newest Changes ==

Refer to history.txt for the complete list.

31-08-08: 1.2
meisei's website moved to http://hap.samor.nl/

- input: fixed keyboard matrix ghosting on more than 2 rows
- input: fixed DirectInput lag
- fixed possible memory leak with on-screen messages
- moved enable/disable on-screen messages to the GUI menu (previously, it was
  just in the .ini file)
- mappers: added Korean bootleg multicarts: 80-in-1, 90-in-1, and 126-in-1
- mappers: bought and reverse engineered Cross Blaim and Harry Fox mappers,
  their emulation should be almost completely accurate now
- mappers: added Konami Sound Cartridge, SCC-I with 128KB RAM
- mappers: fixed stupid crash when loading savestates with SRAM mappers
- mappers: added preliminary support for Zemina ZMB hardware
- PSG: added emulation of pin 6/7 mask quirk
- input: added Konami HyperShot controller emulation
- input: added Torikeshi/Jikkou keys, available on some Panasonic MSXes
- input: added support for Sony's hardware pause key
- mappers: fixed SCC power-on state, the music in Nerlaska's Monster Hunter
  was broken
- gfx: fixed a few NTSC renderer bugs and made S-Video the default video
  signal, if it's too slow for you, change it to RGB
- added a powerful tile viewer, with support for loading/saving tables or SCx
  files, and a built-in editor similar to Wolf's Polka
- added a sprite viewer, with similar features to the tile viewer, like changing
  the Indian's expression to http://hap.samor.nl/meisei_archive/magdance.gif
- added custom savestate/movie slot, allowing any filename instead of the
  numbered defaults
- added support for saving screenshots
- PSG: added support for AY8910 (only configurable in the .ini file for now)
- added a PSG logger, allowing you to to log raw, MIDI, or YM files. YM files can
  be played back, on eg. Ay_Emul ( http://bulba.untergrund.net/emulator_e.htm ).
  http://hap.samor.nl/meisei_archive/Infinite%20-%20Universe%20Unknown.zip , and
  http://hap.samor.nl/meisei_archive/Konami%20-%20Usas.zip for example.
- PSG: added output viewer, with currently played notes on a piano bar
- PSG: added support for substituting simple waveforms with the default
  squarewaves, including many presets by Wolf, and a wave editor
- gfx: made the palette editor easier to use, and included a few more presets
- included yet another game by Infinite, Montana John and the Templar's Treasure

03-09-08: 1.2.1
Regarding movies, this version is fully compatible with 1.2.

- fixed meisei crashing on Windows Vista when closing any of the tool windows

21-10-08: 1.2.2
- tile and sprite viewer can be resized
- added support for fMSX CAS images (tapes), including the ability to save
  separate blocks, and import common MSX files normally meant for MSX disks.
  Be aware that you'll need an official BIOS ROM to be able to play tape games.
- PSG: moved chip type configuration to the GUI
- VDP: added chip type configuration: TMS9118, TMS9129, TMS9918, and TMS9929
  (TMSxx18 is NTSC/J, can also be TMSxx28. TMSxx29 is PAL)
- VDP: enabled 4KB mode address bus mangling for TMS99xx
- VDP: added M3 sprite cloning quirk
- fixed tile viewer screen loader BLOAD header detection

23-11-08: 1.2.3
- added setting to overrule checksum when loading states or movies, handy if
  you're ROM hacking and made savestates on an earlier hack revision
- Z80: fixed a couple of undocumented details not caught by test programs
- input: added PC keyboard LED flags for trigger rules
- input: you can now grab the mouse pointer (Ctrl+Shift+M), making games like
  Arkanoid easier to control
- input: fixed Sony pause key conflict with default pause shortcut
- added support for Sony's Magic Key dongle, a simple cheat device that can be
  used with Gall Force (and a couple of MSX2 games)

