
  MEKA 0.12 - Documentation
 ===========================
  Sega Master System, Game Gear, SG-1000 and SC-3000 emulator for MS-DOS.
  (c) in 1998-1999 by Omar Cornut / Zoop (cornut@cybercable.fr)
  and Hiromitsu Shioya / Hiro-shi (shica@cool.ne.jp)
 =========================================================================
  This documentation is best viewed with the MS-DOS editor, as usual.

----------------------------------------------------------------------------
 Level 1 : Introduction
----------------------------------------------------------------------------

 MEKA is a Sega 8-bit emulator for MS-DOS, made by the following people:

 > Omar Cornut / Zoop (cornut@cybercable.fr)
   Machines emulation, graphical user interface and the rest.

 > Hiromitsu Shioya / Hiro-shi (shica@cool.ne.jp)
   Sound emulation (standard PSG and Yamaha 2413 chipset).

 > Marat Fayzullin / Rst38h (fms@cs.umd.edu)
   Z80 CPU Core (publicly released a while ago).

 MEKA officially emulates the following systems:
  - Sega Master System / SMS
  - Sega Game Gear     / GG
  - Sega Game 1000     / SG-1000
  - Sega Computer 3000 / SC-3000
 You can play other systems on it only if you are smart enough to figure how.
 And if you are, I doubt you will want to play Nintendo games. So forget it.

 Now let me tell you more about these cool systems:

 The SG-1000, for "Sega Game 1000", was released in Japan in July 1983.
 Heavily based on the MSX hardware, it is the first known Sega system (until
 someone proves me wrong, which I would love to have happen).

 The SC-3000, for "Sega Computer 3000", is a variation of the SG-1000 (still
 compatible with it) with a keyboard, and some optionial peripherals such as
 a printer (SP-400), a tape recorder (SR-1000), or a big black box called the
 SF-7000 that provided a 3" floppy disk drive, a Centronics printer port and
 more memory for use for programmers. The SC-3000 was released in November
 1983 in Japan, and then was sold in certain countries around the world (in
 Australia and Europe, I think), shipped a Basic programming cartridge.

 Later, Sega released some updates to these systems, included, but not
 limited to the SC-3000h, SG-1000-II, SK-1000, Mark II and then Mark III.

 I don't know a lot about these systems, but the Mark III is compatible with
 what we call the Master System, and still have the necessary ports to plug
 a printer, or a keyboard. A FM extension was available, providing a much
 better sound hardware, and which is supported by most games released in
 Japan between 1986 and 1988.

 In 1987 came the Sega Master System, almost around the same time Nintendo
 released the crappy gray box. It was sold just about everywhere, but the
 Japanese system had the FM extension embeded and profited from it because
 of better musics.

 Later came the Game Gear, which was nothing but a portable Master System
 with a smaller screen, a communication port (for dual gaming) and more
 colors to choose from.

----------------------------------------------------------------------------
 Level 2 : Features
----------------------------------------------------------------------------

 Graphics
 --------
 Unlike some other emulators, MEKA doesn't feature thousands of different
 graphic engines, but only one, and a working one. Therefore most games
 should be working, as it uses a true line-per-line refresh, and supports
 most raster effects (including palette effects).

 Consequently, MEKA is slow. Very slow.
 If your computer is not a fast Pentium, I suggest using BrSMS instead, which
 will run very fast on most games (not all, though). It is available at the
 following address: http://www.lsi.usp.br/~ricardo/brsms.htm


 Sound
 -----
 MEKA emulates both PSG and FM hardware.
 Although technically better, the FM hardware is only used in certain Master
 System games, released in Japan between 1986 and 1988.

 The four channels of the Programmable Sound Generator should be correctly
 emulated, and waves are realtime synthetized. Last but not least, the way
 the sound is updated allow voices to be heard in games that uses them (not
 perfectly, though).

 The FM hardware uses the Yamaha 2413 chipset. It features nine voices,
 fifteen pre-defined instruments, and one user definable. Three of the voices
 can be used for percussions, and the chipset provides hardware vibrato and
 amplitude modulation. 

 Consequently, MEKA is even slower.


 Peripherals
 -----------
 MEKA supports/emulates the following peripherals:

  - Standard two buttons joypads:
    Almost all games use them. 

  - Lightguns 1 and 2:
    So far only two dumped games use them: Gangster Town and Rescue Mission.
    It is emulated using a cursor that you control with mouse. Yet you cannot
    use both Lightguns on the same time (for Gangster Town).

  - Paddle Controllers ("ala Steering Wheel"):
    Some Japaneses games use it. It is emulated via the mouse, and therefore
    you cannot use two of these at the same time (for Galactic Protector).

  - SC-3000 Keyboard:
    Used in all SC-3000 programs.
    Please note that keyboard emulation is *working* under MEKA, which
    obviously is not the case with all emulators that "supports" SC-3000.

  - 3-D Glasses:
    This is one of the weirdest features of this emulator, as 3-D Glasses are
    supported, but not simulated properly. If someone is familiar with 3-D
    on the PC, I'm interested in knowing which is the best way to simulate
    this kind of effect. You can also drop me a note to tell me the pros and
    cons of the differents methods featured in the Virtual Boy emulator.


 Interface
 ---------
 A feature that most emulators lack is a graphical user interface (GUI).
 MEKA has one, which does not require particular skill to use. Just use your
 mouse to point and click. Experienced users that are sick of using mice are
 also able to use keyboard shortcuts to activate certain functions.

 Due to the way it was done, the graphical user interface is extremely slow,
 and a *very* fast machine is recommended to use it in optimal conditions
 (without having to skip frames). Of course, it doesn't affect the emulation
 speed (which is already slow) while in fullscreen mode.

 I have some ideas on how to optimize it. Maybe.


 Other things
 ------------
 A lot of work has been done on certain other things that most people won't
 notice (because they have been worked on), including, but no limited to:

  - Patching system: this allows you to hack/crack ROMs without having to
    modify the file. Check the file called "MEKA.PAT".

  - Smart configuration file system: MEKA will *never* bother you because of
    a corrupted configuration file, or some bad options in it.
    Also, the file is rewritten and commented everytime you quit.

  - BIOS inclusion. You can play the snail game in MEKA, provided you know
    how to access to it :-)
    Originally, MEKA was supposed to use my own reprogrammed BIOSes. Then I
    found that someone already dumped them so I stopped working on mines and
    included the original ones instead.

  - A very precise compatibility list. MEKA was heavily tested, unlike some
    other emulators that you doubt they were even ran by their author because
    being released. Most of the tests on Game Gear games were done by Mxs.

  - Easter eggs / secret features: find them by yourself.


----------------------------------------------------------------------------
 Level 3 : "Does it work ?"
----------------------------------------------------------------------------

 I tried to make MEKA the most compatible I could make it.
 Unfortunatly, not every game is working properly with it. If you want to
 know which, be sure to check the compatibility list provided.

----------------------------------------------------------------------------
 Level 4 : "I just checked it.. Heh ! where did you got all these roms ?!"
----------------------------------------------------------------------------
 
 There are tons of Sega 8-bit roms not yet on the internet.
 Unfortunatly, I am not able to distribute them yet for the simple reason
 the guy that hosts my site (thanks) considers ten-year-old software as more
 illegal than two months old software. So I am not allowed to put 'em online.
 Now please stop bugging me about them.

----------------------------------------------------------------------------
 Level 5 : Usability
----------------------------------------------------------------------------

 The default keyboard mapping is:

 Common to all systems
 ---------------------
  D-Pad ...................... Arrow Keys
  Button 1 ................... Left Control
  Button 2 ................... Left Alternate

 Master System / SG-1000
 -----------------------
  Soft Pause ................. Return
    This is the same pause as if you pressed the button on a real machine.
    It can be used only if the game supports it at the moment you press it.
  Hard Pause ................. Alt+P
    This "special" pause with keep the game paused without changing anything.
    It is usable everytime, everywhere.
  Soft Reset ................. Backspace
    This is the same reset as if you pressed the button on a real machine.
    It can be used only if the game supports it at the moment you press it.
  Hard Reset ................. Alt+Backspace
    This "special" reset with completly reset the emulated system.
    It is usable everytime, everywhere.

 Game Gear
 ---------
  Start ...................... Return
  Hard Reset ................. Backspace

 SC-3000
 -------
  Soft Reset ................. Break

 Other keys are mapped at the same place as the SC-3000 keyboard.
 So be sure to look at the provided picture carefully. For example:

  Control .................... Caps Lock
  Graph ...................... Left Control

 Miscellaneous keys
 ------------------
  Display all frames ......... F1
  Display 1/2 frames ......... F2
  Display 1/3 frames ......... F3
  Auto frameskip (buggy) ..... F4

  Save Game .................. F5
  Load Game .................. F7
  Previous/Next Game Slot .... F6/F8
  Set slot (0 to 9) .......... 0 -> 9

  Change control device ...... F9
  Enable/Disable keyboard .... Alt+F9

  Quit emulator .............. F10
  Save screen (PCX) .......... F12

 To use a mouse (for the graphical user interface, and Lightgun / Paddle
 emulation), be sure to have an appropriate driver loaded in DOS mode.

 To use a joystick, edit the configuration file.
 MEKA wasn't properly tested with a joystick, granted I don't have one.
 Tell me if it's working for you, or send me a joystick.

----------------------------------------------------------------------------
 Level 6 : "It is slooooooooow !!"
----------------------------------------------------------------------------

 Yes.
 MEKA was entirely programmed in C language, and I don't know x86 assembler.

 One of the reasons for that is that MEKA emulates the system properly.
 MEKA provides dynamic palette emulation, and a real line-per-line engine.
 Both are disabled by default in BrSMS, that's why it is so fast.
 Thus, if you have a slow system, use BrSMS (or Massage).

 You can you also try running MEKA in pure DOS mode.
 Also, be sure to try and use a Vesa 2 video mode in fullscreen.
 Close all boxes in the interface. The tiles viewer is slow in SG1000 mode.

 Disable YM2413 hardware emulation for games that use it.
 It requires a lot of CPU power.
 You can switch to software emulation, it'll be less accurate, but faster.

 Or disable whole sound emulation.
 Or erase MEKA.

 Another reason is that in MEKA, everything is buffered, to avoid flickers
 and make some things easier for the programmer. If you want to give a speed
 boost to the interface, edit the configuration file and change the entry
 "gui_access_mode = buffered" to "gui_access_mode = direct".
 Maybe I'll work on findind a way to make the interface usable in the
 second mode, as it is much faster. Maybe.

 The last thing you can do if to configure MEKA to use VESA modes, if your
 video card supports them. Edit MEKA.CFG and change the _driver entrys to
 one of the following values (the higher the better):

    1 : VGA
    2 : Mode-X
    3 : Vesa 1.0
    4 : Vesa 2.0 Banked
    5 : Vesa 2.0 Linear
    6 : Vesa 3.0
    7 : VBE/AF

----------------------------------------------------------------------------
 Level 7 : "Man, I still like MEKA !"
----------------------------------------------------------------------------

 Thanks. In this case, if you want to help further development and support
 the author, you are invited to send me a (Sega) cartridge. Or more, if you
 are nice enough. If you plan to send something, e-mail me beforehand. If you
 cannot find any cartridge, you can send some money, I will buy one myself.
 This way, you will be a registered user.

 My address is:    Omar Cornut
                   21 rue Beranger
                   75003 Paris
                   France

 If you do not agree these terms, then you can delete this software now, as
 it will destroy your computer after a certain amount of time using a non
 registered version. Also, if you have dogs living in your house, Meka will
 autodetect them and kill them by sending ultra sonic waves through the PC
 speakers. Just don't say I made it for the money, please.

 Registered users will receive information and updates before others.
 They will also be able to receive intermediate updates, if they want to.

----------------------------------------------------------------------------
 Level 8 : Reasons to use MEKA instead of those other emulators
----------------------------------------------------------------------------

 There is no reason why you should use it instead of another emulator.
 Use it if you like it.
 I am not trying to compete with anyone.
 I made MEKA for my own use, to play my own cartridges on my own computer.

 When starting, I planned to continue updating it regulary, in respect to
 registered users. I also wanted to do only quality releases, instead of
 releasing a new (buggy) version every week. That's why it came so late..

 Anyway, I am not really motivated anymore, so it's not *certain* that you
 will see an update to this emulator. Maybe.

 And I won't release the sources now, as BouKiChi may find them, and release
 some sort of D-Sms after adding his name into it.

----------------------------------------------------------------------------
 Credits
----------------------------------------------------------------------------

 I would like to thank the following persons for their help:

 Hiromitsu Shioya (Hiro-Shi):
  for having done the sound/music emulation in Meka. without him, you would
  be using the emulator with a crap and buggy sound engine.

 Nicolas Hamel (Gouky):
  for the invaluable help at the very beginning. "heh, what is a CPU ? :)"
  http://www.multimania.fr/gouky

 David Michel (Rony):
  for Magic Engine, support, advice and help.
  http://joyce.eng.yale.edu/~bt/turbo/emu/

 Yakmo, Jun, Casiopea Skylark and Skyhigh:
  for having dumped tons of roms (including the first SG-1000 games), and
  still doing it. Also because they are cool guys and they helped with
  various other information. 8-bit or die !

 James McKay:
  for Massage, and kindly answered all the crap questions I asked when I was
  starting, and even after (although I helped him a bit, too ;)
  http://www.enterspace.org/world/massage.htm

 Charles Mac Donald:
  for SMSPlus, and for lot of help regarding optimizations.
  http://cgfm2.home.ml.org

 Marat Fayzullin:
  for Master Gear, for being the one all users and authors should respect,
  for having released the sources of most of his emulators and CPU cores,
  and is still continuing, despite people that are profiting from his work
  without respecting some elementary rules. Also because he wrote a technical
  document about the Master System. Now if you are the kind of person who
  hate him for no other reasons that the Windows ports of his emulators are
  not free, remember he is the father of console emulation, and that without
  him, many emulators wouldn't exist (Nesticle comes to mind. And MEKA).
  http://www.komkon.org/fms/MG/

 Ricardo Bittencourt:
  for BrSMS (great emu!), and for having shared (some) information together.
  http://www.lsi.usp.br/~ricardo/brsms.htm

 Jon (the unknown one):
  this guy is the one who wrote the (old) document with all the knowledge
  on which the first emulators were based. I am also pretty sure the first
  dumps came from him. Although I doubt he's still on the internet, I would
  love to be in contact with him. Jon, if you're reading, e-mail me ;)

 Super Majik Spiral Crew (the):
  for writing a technical documentation about the SMS.

 Richard Talbot Watkins:
  for having written a technical documentation about the SMS, although I
  found it recently and it didn't helped me much. He is also the author of
  Miracle, a SMS emulator for Acorn machines.
  http://www.willothewisp.demon.co.uk/SMS/

 Sean Young:
  for writing a technical documentation about the TMS9918a.
  http://www.msxnet.org

 Andrew Lindsay:
  for having dumped tons of roms, and for SMScheck. If you don't know him and
  his site, then you missed the golden age of emulation.

 Sega Notebook (the):
  for having dumped a few roms, and because the site is cool (tons of cheats)
  http://shell0.elnet.com/~gm-quinn/sms/

 Dump Masters (ViperZ and Omega):
  for having dumped a few roms (including those crappy Brazilian hacks ;)
  http://www.emucamp.com/dump_masters

 Charles Doty:
  this guy contributed a lot to the console development scene. He also wrote
  an old text demo for Game Gear, which is from where I started learning Z80.
  http://www.pcisys.net/~cdoty/console

 Nicolas Lannier (Archeide):
  for SNEmul, support, advice and help.
  http://www.epita.fr/~lannie_n/english.html

 Richard Bush (Antiriad):
  for Raine, support, advice and help.
  http://www.rainemu.com

 Richard Mitton (Nodrog):
  for TNZS-Emu, support, advice and help.
  http://www.emucamp.com/tnzs

 Mxs:
  for being the only good tester, and having done the GG compatibility list.
  http://vertigo.sohonet.com

 Sam Pettus:
  for your Gam.. err, Sega 8-bit Compatibility Chart ;)

 Lasse (of Image/Helsinki/Finland):
  for the original Master System BIOS rom. Before getting it, me and Martin
  spent a lot of time reprogramming it and creating the needed tools for it.
  Then a few days before the release, Lasse sent me the ROM. Believe it or
  not, there was only one different pixel between the original Sega logo and
  mine ;-)

 Martin Skog (MoonTrip):
  for the Wonderboy 3 music he made, for some explanations about sound waves,
  waves, and for your very good Sega sound reproduction (the one that was
  about to be used in the reprogrammed boot rom, before Lasse sent it).

 Larry M (Ellum):
  for the Wonderboy 3 music he made.
  http://sega-zone.com/sega_haven

 Olivier Aichelbaum and the_unknown_contributor:
  for the SC-3000h, the BASIC cartridge and the documentations.
  http://www.acbm.com

 Peter Hegedus (Gurty Gurt):
  for donating the SR-1000 (Sega Recorder).

 Alexandre Kubrusly (Lestat):
  for donating Street Fighter 2 (what ? Must I send it back ? ;).

 An unknown guy:
  for the rendered Master System picture used on the interface.

 Puyolin:
  for the "Ocean" and "Emucamp" color themes (used in the interface), and
  for having corrected(correcting) mistake/s? in/on? (the?) documentation/s?
                    ~~~                  ~~~~          xx                ~~~
 Westone:
  for making Wonderboy 3, the best game ever.. ten years ago :~)
  http://www.westone.co.jp

 And of course thanks to SEGA, for such a cool system and great games !

----------------------------------------------------------------------------
  ú         ù                ú          ú          ú        ù         ú
     Goodnight Wonderboy,       ù  ú         ú                    ù
     Goodnight Monsterland.           ù           ù    ú      ú           ù
       ù        ù     ú         ú         ù               ù        ù
  ú       __________     ù             ú       ú                       ú
    ù    /          \        ú    ù         ù         ú    ú
        |____________|     ù            ú                       ù         ú
 ù       |     ___  |           ú                ú      ù             ú
      ú  |    |   | |   ú     ù       ù     ú               ú
  ú      |    |   | |             ú                ù                ú   ù
----------------------------------------------------------------------------
