     /********************************************************************/


                                  CHASMS v.0.30
                      Copyright (C) 2000 Benjamin J. Eirich
                               All Rights Reserved


     /********************************************************************/

   I. What is CHASMS?
   ==================
       CHASMS is a Windows/DirectX based emulator for the Sega Master System
   and Sega Game Gear systems. It requires DirectX6, and basically a fairly
   modern computer. CHASMS is not heavily optimized, although I do intend to
   spend some more time optimizing it, it is not a large priority. My 400mhz
   system is slow by today's standards; trying to optimize it to the point
   that it runs fullspeed on a 486/25 is sort of rediculous. It was written
   because there were no freely available Windows based SMS emulators. Why
   do we need a Windows based emulator? Firstly, it solves many hardware
   issues with soundcards, video modes, advanced joysticks, etc. Secondly,
   for those of us who like to run Windows 2000, you know the DOS VM in 2k
   does not emulate DOS sound or joysticks. Sound is, needless to say, a
   critical part of the console experience, and playing with a keyboard just
   doesn't quite have the same feel as a gamepad. So, in addition to the fact
   that I've never written an emulator before and it seemed like a fun project,
   I decided I'd try to write such an emulator myself.

   II. Where can I get CHASMS?
   ===========================
        webpage: http://chasms.midgetrebellion.com
          email: vecna@verge-rpg.com

   You'd betta recognize!

   CHASMS was written primarily by myself, me being vecna. But I couldn't have
   done it alone, and because it's a swell thing to do, credit must be given
   where credit is due. ^_^

             zeromus - Windows specific code, SMS sound interface
          air - Base MikMod code; drivers, mixers; fixing zero's code

       Michael Montague - Major thanks for NeoSMS source, which helped me
                fix up Lineints and VDP Status emulation.

              Zoop, Nyef, Eric Quinn, Jose Manuel Delgado, etc. for
        tolerating my dumb ass on the S8-Dev board and putting out some
                            great SMS resources.

         Special thanks to Charles Mac Donald for his VDP documentation,
       as well as generally being a super-helpful guy on the S8-Dev forum.

        Much of this emulator was written while listening to Dream Theater.

   III. How do I use it?
   =================================
       You can start the emulator by itself, or passing the name and path of a
   ROM to start up with. You might take a look at the CHASMS.CFG file, which is
   quite straightforward, but controls some semi-important options. If you run
   it for instance, and have problems setting the fullscreen DirectX mode that
   it defaults to, you can open this file up and tell it to default to Windowed
   mode.

   You summon the menu by pressing ESC. Many menu functions have hotkeys, and
   these are quite visibly listed next to their menu functions, but for the
   sake of being thorough, I'll list them here as well:

     ALT-F4        Exits the emulator immediately.
     ALT-ENTER     Toggles fullscreen/windowed mode.
     TAB           Does a soft reset (ie, Reset button on the SMS)
     SHIFT-TAB     Does a hard reset (ie, turn the power off and back on)
                   (yes, there is a difference in some cases)
     0 .. 9        SaveState slot select
     F5            Save State
     F7            Load State
     ALT-L         Load ROM
     ALT-P         Begin PSG Music Logging

     Default keyboard controls:
     Up/Down/Left/Right  -  Controls the directional pad. Duh.
     Z                   -  Button 1 ("Start")
     X                   -  Button 2
     Space               -  Pause / Game Gear Start

     Default joystick controls:
     B1                  -  Button 1
     B2                  -  Button 2
     B3                  -  Pause (but recommend you use keyboard pause for
                            the time being)

   Savestates:
   -----------
      The SaveRAM data is stored in the savestate files. If you load a
   savestate, it's SaveRAM data will ultimately overwrite the .SAV file. Right
   now the best way around this is to make a savestate with "your" SaveRAM data
   in it on a different slot number. I'm open to other suggestions on how to
   handle this, as well.

   BIOS:
   -----
      The BIOS is pretty easy to use. There are two more or less seperate BIOS
   functions. The first is under Misc -> Enable Startup BIOS. This flag simply
   determines if the BIOS screen that appears when you normally power on a SMS
   with a cartridge plugged in should be emulated. In most circumstances, this
   serves no purpose except to make the emulated experience that much more
   authentic. There are a few games which, for whatever reason, only seem to
   boot up if the Startup BIOS is used, however, and those games are recognized
   in CHASMS' internal checksum database; for these games, the BIOS will always
   be used, regardless of the value of Enable Startup BIOS.
      The second BIOS function is File -> Run BIOS. This runs the BIOS by
   itself, "without a cartridge plugged in". Both the Japanese and USA BIOSes
   are included in CHASMS, and which one is ran is determined by the CPU
   nationality. The Japanese BIOS, when run by itself, simply displays a
   looping demo of a scrolling field, logo, twinkling stars, and music. The USA
   BIOS will display an instruction screen. At this screen, however, if you
   press UP+1+2 simultaneously, you will access the hidden Snail-Maze mini-game.

   Pro Action Replay codes and Cheat Finder:
   -----------------------------------------
	Using the Pro Action Replay function (under the Misc menu) to enter
   codes that someone else has created is pretty easy. Simply click on a slot,
   and you can begin typing. The cursor is denoted by which letter is flashing
   on and off. All Pro Action Replay codes are in the format 00xx-xxyy. Since
   they all start with 00, the cursor starts in the 2 spaces into the code.
   You can use the checkboxes next to the code boxes to turn certains codes
   on or off. As soon as you close the Pro Action Replay menu, your codes will
   take effect.

       You can also create your own Pro Action Replay codes with the Cheat
   Finder dialog. The best way to explain how it works is to lead you through
   an example. For this example, I'll use Sonic the Hedgehog 1 (SMS).

   Essentially, what we have to do, is find the memory location the game uses
   to store variables that we'd like to alter. In the case of Sonic, the two
   things we'll try to make codes for is Lives and Rings. First we'll do Rings.

   Start a game, and when you get to the first level, immediately open up the
   Cheat Finder dialog. If you do not see 'New Search' displayed, hit Clear
   first. For 'value', enter the number of rings you currently have (0). Then
   hit Search. When I do this, it displays: "Refine search (5404 matches)".
   The actual number of matches it comes up with may vary at this point. Now we
   change the number of rings we have; grab one ring. Then enter the new number
   of rings (1) into the Value field and hit Search. Now my display says
   "Refine search (14 matches)". We'll do it again; grab a couple more rings,
   enter the new number of rings, and hit Search again. Finally, it says
   "Address: D2AA". This is the address where Sonic stores the number of Rings.

   Before we turn this value into a Pro Action Replay code, let's get the 
   address for the number of lives as well. Hit the Clear button, and then
   enter the current number of lives in the value box (3) and hit Search. You
   should see something like "Refine search (37 matches)". Don't grab any
   rings, run into an enemy (die), and try again. "Refine search (2 matches)".
   Repeat one last time, and you should get: "Address: D246".

   Now, to make codes from these values. I already said that the format of
   a PAR code is 00xx-xxyy. The xxxx represent Address. So we can simply plug in
   the values we got for Address into here: 00D2-AAyy. The yy represents
   the value we want to write at this address; the number of lives or number of
   rings. In general, you're best off keeping it simple. Things are more likely
   to work if you put in 3 lives than 200. 

   Here are the codes I use for Sonic 1:
     Infinite Lives: 00D2-4603
     Invincibility:  00D2-AA03 (does not stop pit death, crushing death, etc)

   The value field (yy) is in hexadecimal. It can store any value 0-255, or
   0-FF in hex. If you don't know how to convert a decimal number to 
   hexadecimal, open the Windows Calculator, make sure it's in Scientific mode,
   enter the value you want to convert in decimal, and then click on the "Hex"
   radio button.

   IV. PSGPLAY
   ===========
       PSGPLAY is a small command line (Win32 Console Application) standalone
   utility for the playback of .PSG files generated by CHASMS. On my 400mhz
   machine, it does not even register on the cpu usage meter. PSGPLAY is very
   easy to use, you simply run the program with any number of file specifiers
   on the command line. All of these are valid:

     psgplay zillion1.psg
     psgplay rtype*.psg zillion*.psg alexkidd.psg
     psgplay *.psg

   etc. Inside the player, you can use the following keys:

     ESC     Quits the player immediately.
     SPACE   Advances to the next song.
     l       Toggles song looping.

   When a song is looping, you must you the SPACE key to advance tracks.

   V. What's planned for the future?
   =================================
       First of all, I should say what's NOT planned. I have no intentions of
   making this an 'all-SEGA emulator', or of adding a thorough debugging
   interface, or making it some sort of SMS emulator / development kit. I also
   do not intend to add netplay, or include cute little minigames or anything
   of that nature. It's just an emulator, and it's designed to be as
   non-intrusive as possible.

   However, some of the things that ARE on my potential todo list are as
   follows:

      * Internal source cleanup
      * VDP Right-block scroll lock, VDP 16x16 sprites
      * Rework music player to support speech and voices
      * Fullscreen-only 8bpp support
      * FM chip sound output
      * Lightgun / paddle / 3d glasses support?

   If you have a suggestion that's not on this list, and isn't explicitly on
   the list of things I WONT do, feel free to email me and suggest a feature.

   VI. Known Bugs
   ==============
    - Occasional crash-at-exit bug. This is very irritating, because it's
      virtually impossible to debug; it never occurs in Debug mode, and even
      in Release mode it only seems to happen something like 1 in 20 times.
      However, there are no known bugs causing the emulator to crash during
      normal execution.
    - The File Selector won't properly load files with a filename longer
      than 80 characters; It can't handle a directory with more than 768
      total entries (directories, drives, and ROMs - files that don't show
      up in the file selector don't count towards this limit)
    - Pressing ALT-ENTER in 32bpp crashes most systems.
    - Pressing ALT-TAB in fullscreen mode also crashes.

   VII. History
   ============

   v.0.30 (Jun 3, 2000)
   =============
    - CHASMS is now DX3/NT4 compatible, thanks to Aegis.
    - More Load ROM dialog changes:
       * Now can see and change disk drives.
       * Listings now sorted by type in addition to alphabetically;
         directories go on top, ROMs go next, drives go last.
       * Pressing keys A through Z will now allow you to 'jump' to ROMS
         beginning with that letter
       * Modified mousewheel so that it moves the window frame rather
         than just the highlight
       * Added cute little poorly-drawn icons to the file browser.
    - CHASMS now uses the Z80 emulation core from MAME. This is the 4th Z80
      core I've used (Marat Fayzullin's in v.0.10a, RAZE in v.0.20b, Marcel
      De Kogel's in an intermittent trial version, and finally MAME in v.0.30).
      Hopefully I can stick with this one for a while. ^_~ Unfortunately
      MAME's core is slower than RAZE, but it's much more accurate and stable.
    - Fixed a bug that caused no emulation video to show up on a 15bpp
      (5:5:5 instead of 5:6:5) display even though the GUI would show up.
    - Now supports ROMs with a 64 byte header at the end of the ROM. Peculiar.
    - CHASMS.CFG will now always be saved in the directory that CHASMS starts
      up in, regardless if you change directories during execution.
    - Added 'rompath' option to CHASMS.CFG; CHASMS will now remember what
      directory you were last in and put you there next time you start up.
    - Rewrote video system; video memory is now converted from planar to
      linear on the fly whenever a ROM changes a byte in VRAM. Greatly
      simplified and optimized rasterizing routines.
    - Drastically optimized the Pattern view dialog.
    - Added the SMS BIOS! Both the USA version and Japanese version are
      included. Thanks to Zoop for finally releasing them. (Hint: On the
      USA BIOS, when running without a cartridge, you can press UP and
      buttons 1 and 2 simultaneously at the instructions screen to access
      a hidden minigame)
    - Fixed a bug where the very first tile would sometimes be corrupted.
    - Generalized source cleanup. I'd like to prepare for an eventual
      source-code release.
    - Began an internal ROM checksum database. This is a small database, only
      ROMs which need specific settings to run, are known bad dumps, or do
      not currently work are in the database.
    - Removed parts of emulator that use translucency for sake of speed;
      they are especially slow when the backbuffer is in Video RAM.
    - May heaven have a special place of pleasure for the man who invented
      code profiling. Did some significant optimization.
    - Preliminary FM emulation (FM chip is emulated, but I haven't written
      actual sound output code for it yet)
    - Fixed a scrolling bug that was causing the status bar of Gauntlet
      to be 'all weird'.
    - CHASMS now remembers window positions.
    - Modified keyboard system so that left and right cannot be pressed at the 
      same time, or up and down at the same time, as this would cause some games
      to bug out.
    - Video system: When running CHASMS in Windowed mode, it will detect your
      desktop BPP and automatically adjust it's BPP to match, or if it can't
      (24bpp), will switch to fullscreen. Likewise, there is a series of
      fallback mode tests in case fullscreen modesetting fails. Ultimately,
      you hopefully shouldn't have to mess with chasms.cfg to find a working
      video setting.
    - Added Pro Action Replay code support, as well as a Cheat Finder system.
    - Modified PSGPLAY to handle playing PSGs from other directories.
    - SMS compatiblity is now something like 97%, and probably close to 99%
      if you don't count games that just need weird peripheral emulation.
      (lightun, 3d glasses, paddle, sportspad). GG emulation is ~95%.

   v.0.20 (May 01, 2000)
   =============
    - Fixed 8x16 sprite handling; fixes sprites for Golvlius, etc.
      (Thanks to Charles Mac Donald)
    - Changed handling of cpu interrupt timing.
    - Reworked VRAM reading to account for read-ahead buffer. Fixes Astro
      Warrior, etc.
    - CHASMS now uses the RAZE Z80 emulation core instead of Marat's. RAZE is
      quite a bit faster, as well as more accurate.
      (Fixes BIT bug, fixing R-Type, Simpsons vs. Space Mutants, etc.)
      (Fixes IRQ Line emulation, fixing timing issues on Choplifter, etc)
    - Load ROM dialog changes:
       * Now alphabetically sorted.
       * Improved PGUP/PGDN behavior; added HOME/END behavior.
       * Can now see and change directories.
       * Added mousewheel support.
    - 32 bpp color depth now works
    - Modified rendering code to shut off when DDraw surface is lost. This
      means that when CHASMS is not the foreground task, it will yield a
      significant amount of cpu time back to the OS.
    - Proper PAL emulation (311 lines per refresh rather than 262 @ 50fps)
    - SaveRAM now saves both pages of RAM
    - VDP Sprite Collision now emulated
    - Game Gear ports 1 through 6 now emulated
    - Stereo Game Gear sound supported
    - State load now F7 instead of F6
    - HCounter now implemented (No lightgun support _yet_, tho)
    - Miscellaneous bugfixes
    - New SaveState format; an open standard that we hope to encourage
      other SMS/GG emulators to support
    - chasms.cfg is written fresh at shutdown - modified settings are saved.
    - All GUI functions are now implemented!
    - ROM Checksumming
    - Added support 2 joysticks, and more than 4 buttons; No longer requires
      DirectX7.
    - Added PSG logging. Added standalone PSGPlay program.
    - Rewrote the Dialog Manager; no longer bugs out when closing dialogs when
      more than two were open.
    - ALT-F4 now works to close CHASMS.

   v.0.10a (Apr 11, 2000)
   =============
    - Initial alpha release

   VIII. Legal
   ===========
   CHASMS is Copyright (C) 2000 vecna (Benjamin J. Eirich)
   Sega, Sega Master System, Sega Mark III, and Sega Game Gear
   are trademarks of Sega Enterprises, Ltd.
   The author is neither affiliated with Sega in any way, nor endorses
   piracy of Sega products.

   CHASMS is freeware, and you can distribute it freely, so long as
   it is not modified, no ROMs are packaged with the program, and
   nothing is charged for distribution.

   You use this software at your own risk, the author is not responsible for
   any loss or damage resulting from the use of this software. If you do not
   agree with these terms do not use this software.

   MAME Z80 core Copyright (C) 1998,1999,2000 Juergen Buchmueller
   All rights reserved.
