
  MEKA 0.30 - Documentation
 ==========================
  Multi machine 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 (emulation of 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
  - Colecovision         / COLECO
  - Othello Multi Vision / OMV
 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:

 -- on the Sega side --

 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
 (Australia and Europe to my knowledge), shipped with 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.

 -- on the other side -- (text by Tincho DJ)

 There was a machine called the Othello Multi Vision, released in Japan,
 which is in fact a SG-1000 with a new shape. Eight games were released
 for it, but you were able to play SG-1000 games with it.

 In 1982, Coleco (COnnecticut LEather COmpany) released the Coleco Vision.
 In those years, Atari led the home video games market with Atari 2600, a
 4-bit console released in 1978. Coleco wanted to release Coleco Vision with
 Donkey Kong, the Nintendo's arcade smash hit. But it wasn't possible; Mattel
 (the Intellivision manufacturer) and Atari released this game first. Anyway,
 Coleco could release Donkey Kong four months later, acquiring KING KONG's
 rights from Universal Studios (Nintendo had been demanded by Universal, due
 to suspicious similarities between Donkey Kong and King Kong. Some months
 later, Nintendo won). This wasn't the last controversy in which Coleco was
 involved. In 1983, a cartridge adaptor was released by Coleco. This adaptor
 would let you use Atari 2600 cartridge on the ColecoVision. Of course, Atari
 demanded Coleco; but Coleco won.

 Later, Coleco released Adam, a computer based on Colecovision hardware. It
 wasn't very successful. Colecovision's time was running out, and production
 was stopped in 1984.

----------------------------------------------------------------------------
 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. 

  - Light Phasers 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 Light Phasers 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 technology: MEKA will *never* bother you because
    of a corrupted configuration file, or some bad options in it. The file
    itself is rewritten and commented everytime you quit the program.

  - BIOS inclusion. You can play the snail game in MEKA, provided you know
    how to access to it (alright, if you forgot, try pressing UP+1+2).
    Originally, MEKA was supposed to use my own reprogrammed BIOS. Then I
    found that someone already dumped them so I stopped working on mine and
    included the original one instead.

  - A very precise compatibility list. MEKA was heavily tested, unlike some
    other emulators that you doubt they were even ran by their author before
    being released. Thanks goes to Mxs, Jossa and Tincho DJ for their help
    with the Game Gear and Coleco Vision lists.

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

  - A Graphical User Interface, did you noticed there was one ?


----------------------------------------------------------------------------
 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 (COMPAT.TXT).

----------------------------------------------------------------------------
 Level 4 : "I just checked it.. Heh ! where did you got all these roms ?!"
----------------------------------------------------------------------------

 Monitor this site: http://smspower.speedhost.com
 New roms will appears regularly here.
 Contact me if you have a specific cartridge that you want to see dumped.

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

 You can run MEKA from the command line. Simply type "MEKA" followed by the
 filename of the game you want to play. You can also run "MEKA /?" to get
 a crap command line help shown.

 Inside of the emulator, 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 ................. Ctrl+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 frameskipper .......... F4

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

  Show FPS counter ........... F

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

  Enable/Disable sprites ..... F11
  Enable/Disable background .. Alt+F11

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

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

 To use a gamepad / joypad / joystick, edit the configuration file with a
 text editor and use your brain. Please do not e-mail me about how to
 enable them if you didn't tried by yourself. 

 And if you have a Side Winder to donate to me, that would be very nice.
 (that should be better than my keyboard)

----------------------------------------------------------------------------
 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, it's even better).

 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 some games.

 Disable YM-2413 hardware emulation for games that use it.
 It requires a lot of CPU power.

 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.

 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 values mentionned below the line.

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

 Thanks. In this case, if you want to help further development and support
 the author, you are welcome to register Meka.

 To do so, you have to send me some Sega cartriges (Master System, SG-1000,
 SC-3000 or Game Gear) or hardware. If you plan to do so, be sure to e-mail
 me beforehand, as it would be better for me not to receive the same thing
 twice. And please do not e-mail me saying "I would love to register but
 unfortunately I only have a dozen of common games which you probably got".
 It isn't because a game is common that I have it. 

 If you cannot find any cartridges, then you can send money, I know a place
 that sell tons of cartridge and I will buy some myself. The fixed price for
 Meka is 20$. You can also send the French Franc equivalent, if you live in
 France. If you don't want to send money for some reasons, I also accept
 non-Sega 8-bits videogames or hardware (especially Genesis and Mega CDs ;-)

 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 new version before others.
 They will also receive intermediate updates of Meka, if they want to.
 They will also get informations about my other projects (and betas).

----------------------------------------------------------------------------
 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 first made MEKA for my own use,
 to play my own cartridges on my own computer.

 When starting it, I planned to do only quality releases, instead of
 releasing a new (buggy) version every week. That's why it came so late.

 Meka will be kept updated, in respect for registered users. If I ever
 have to drop Meka on my side, finding someone to continue the project
 wouldn't be hard.

----------------------------------------------------------------------------
 Level 9 : Cool things to do when playing games is not enough
----------------------------------------------------------------------------

 Edit MEKA.NAM to add comments about games you like (and send them to me).

 Edit MEKA.PAT to add new game patches (and send them to me).

 Edit MEKA.THM to add new GUI color themes (and send them to me).
 Also check MEKA homepage for "Wonder Theme", a graphical theme editor.

 Register the programs you like.

 Connect to an Efnet IRC server and join #meka to meet strange people.


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

 I would like to thank the following persons for their invaluable 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:
  for roms, informations, help, and everything :)

 Sankichi, Casiopea Skylark and Skyhigh:
  for having dumped tons of roms, and informations.
  let's hope I will be able to converse with you one day (in Japanese).

 James McKay:
  for Massage, and because when you ask him a simple technical question,
  he answer ten pages. He also took the time to kindly answer all the crap
  questions I asked when I was starting. And very nice guy.
  http://www.enterspace.org/world/massage.htm

 Charles Mac Donald:
  for SMSPlus, some help regarding optimizations and good chats together.
  http://www.emucamp.com/cgfm2

 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 I'm afraid you missed the golden age of emulation.
  http://members.aol.com/smsstuff (do not even try, it was closed in 1997)

 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

 Flavio Morsoletto:
  for his help with hardware hacking and precious reports:
   "It eats +5 and GND (duh!). One line reports trigger activity. The last
    line goes (theoretically) low when the phototransistor is lit."

 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 having done the GG compatibility list and beta testing.
  http://vertigo.sohonet.com

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

 Lasse Reinikainen (of Image/Helsinki/Finland):
  for beta testing and tons of roms, roms he sent me, including the original
  Master System BIOS. Before getting it, me and Martin spent a lot of time
  time recreating it from stratch. 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 the one I drew ;-)

 Martin Skog (MoonTrip):
  for the Wonderboy 3 music he made, for some explanations about sound 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 the original one).

 Jonathan Griffith (Lilac):
  alright, I had to put you somewhere :)
  for his suggestions, and the Meka theme editor he made.
  http://www.emucamp.com

 Larry M (Ellum):
  for the Wonderboy 3 music he made. This game definitively rocks !
  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

 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 correcting(corrected) mistake/s? in/on? (the?) documentation/s?
                 ~~~              ~~~~          xx              ~~~
 Westone (including Shinichi Sakamoto and Ryuichi Nishizawa):
  for making Wonderboy 3, the best game ever.. ten years ago :~)
  http://www.westone.co.jp

 The 50+ persons who bothered registering Meka,
 And of course thanks to SEGA, for such a cool system and great games !

----------------------------------------------------------------------------
                                                                
     Goodnight Brave Warrior,                                  
     Goodnight Monster-land.                                          
                                                             
         __________                                                
        /          \                                  
        |____________|                                                 
        |     ___  |                                              
        |    |   | |                                   
        |    |   | |                                                
----------------------------------------------------------------------------
