
                                 ZSNES
                        by zsKnight and _Demo_


ZSNES is a Super Nintendo Entertainment System emulator made in assembler.
It runs commercial games and even with sound.  However, it still lacks
compatibility and the sound still has bugs.

We would really like to thank the snes9x team for all their help and
also for an excellent snes emulator.  We also wish them the very best
of luck!

---------------------------------------------------------------------------
Table of Contents
---------------------------------------------------------------------------

1.) What's New
2.) Disclaimer
3.) System Requirements
4.) Things you should know about ZSNES (UPDATED v0.295)
5.) Current Progress
6.) ZSNES Default Keys
7.) Configuration File (ZSNES.CFG)
8.) Cheat Codes
9.) Extra Features (SNES Mouse/Super Scope)
10.) How to contact the authors / Homepage Address
11.) The Debugger
12.) Credits

---------------------------------------------------------------------------
1.) What's New
---------------------------------------------------------------------------

v0.305 - Fixed a snes ppu multiplication bug.  Thanks to Lord Esnes!
       - Hopefully fixed 6-button joystick support.
       - Fixed a little memory overflow bug which caused some games to not
         work
       - Forgot to clear NMI wait substitute variables when another game
         is loaded from the GUI
       - Changed sound processing engine back to v0.297.  If for any reason
         you want to go back to v0.300 sound engine, use -x as a command line
       - Added Cursor Mode Button to the Super Scope.  Never thought it was
         necessary until recently.  Use the =/+ key.

v0.300b - Fixed a bug that causes sidewinder support to crash.

v0.300 - Fixed a 65816 wrapping bug
       - Added Super Scope Emulation!  (Press 7 beyond mouse)
       - Some minor touches to the GUI
       - Manually calculated RGB bit lengths when using 16-bit modes
       - Fixed another bug when loading 48mbit images from the GUI
       - Sped up the execution loop when sound is enabled
       - Implemented NMI wait substitute for speed
       - Added some extra vesa2 routines to help some video cards
         with ARGB format of 1:5:5:5, however interpolation won't work
         for those at the moment.  Thanks to Dark Force for helping out
         on this one!
       - Implemented 512x384 VESA2 resolution for both 8 and 16 bit
       - Implemented Sound Mute and Reset
       - Implemented Joystick Remapping.  Edit ZSNES.CFG to access this.
       - Fixed and sped up 6 button joystick support
       - Fixed 2 2-button joystick support
       - Hopefully fixed 2 sidewinder support
       - Fixed an overflow sound bug

v0.297 - Fixed a bug when loading 48mbit images from the GUI
       - Fixed some crashing bugs by just adding some zero space
           Very weird bug!

v0.296 - Fixed up Cheat Menu in 16-bit color mode
       - Changed SPC700 skipper back since it was causing problems in
           certain games
       - Added Multiple Snapshot files
       - Fixed a minor loading bug
       - Fixed 16-bit color full add/sub conversion table when video
           is in BGR format
       - Fixed some fixed color screen add/sub bugs
       - Supported .SWC format in the GUI

v0.295 - Compiled under a newer version of WDOSX.  This should help fix some
         VESA 2 problems.
       - Fixed multiple SPC700 bugs
       - Added a command line to force either NTSC (-t) or PAL (-u) timing
       - Added a command line to force 8-bit sound on (-8)
       - Zsnes.cfg is now loaded from the directory where zsnes.exe is located
       - Zsnes.cfg now re-writes itself when zsnes exits
       - Reduced zsnes.exe filesize
       - The IRQ's are now more stable.  This should help fix some
         crashing/rebooting problems under dos.  Thanks to Sardu for some
         help on this!
       - Fixed some VRAM accessing bugs
       - Several fixes to the sound DSP
       - Optimised SPC700 a bit
       - Implemented primitive Mode 5, 512 horizontal resolution.  To get
         full potential of this mode, use 640x480 resolutions except for
         interpolated/nonscanline mode.
       - Improved 65816 <-> SPC700 communication
       - Slightly improved sound skipper
       - Fixed a directory changing bug
       - Implemented Scanlines for 640x480x256 video mode
       - Added a temporary command line to enable sound compression
         buffering (-Q)
       - Added a extra menu which pops out when you press F1
       - Added snapshot feature.  Press F1 and select Save Snapshot
         ZSNES saves 256 color under image.pcx and 65536 under image.bmp.
       - Added FPS feature.  At the moment, it only works when auto frame
         rate is used.
       - 65816 bugfix : x flag is supposed be used in MVN/MVP
       - Fixed up color addition/subtraction clipping a bit
       - Added Scanlines, Interpolation, Enterskip, and Force 8-bit sound
         in zsnes.cfg
       - GUI now saves the loading directory
       - Added a separate save directory feature in zsnes.cfg.
       - SPC700 bugfix : fixed mem.bit addressing mode.  Thanks to Phoenix
         for this info!
       - Fix up a bug where more memory was cleared than needed in 256 color
         video memory processing
       - Optimised video memory clearing in 65536 color mode
       - Minor optimisations to the 65816/SPC700
       - Implemented Mode 7 Tile #0 Repetition
       - Rewrote most of the Mode 7 routines for speed
       - Fixed a 65536 color Mode 7 bug where the background wasn't cleared
         properly
       - Added Pro Action Replay, Gold Finger,and Game Genie cheat code
         support
       - Optimised Memory/Register accessing routines
       - Used a newer version of Sidewinder driver.  Should fix
         some problems and also support 2 sidewinder pads (not tested yet).
         Thanks Robert!  Also, thanks to Sardu for helping to get it
         to work right!
       - Whoops!  256 Color palette was set when GUI is exited in 16-bit mode.
         Hopefully fixed now.
       - Added the ability to Clear/Disable/Enable cheat codes through the menu.
       - Optimised Graphics Decompression Routines.  Thanks to Nerlaska for
         this info!
       - A Bunch of other Minor Bugs Fixed.

v0.270 - Properly cleared memory when loaded off of the GUI
       - Implemented realtime adsr/gain switch.  Special thanks to Sardu for
         help on this!
       - Fixed up a VESA 2 error message
       - Temporarily disabled Sound Compress buffering till we can get the
         bugs out.
       - Volume fixes to the sound DSP
       - Fixed up > 16mbit LoROM support
       - Added partial 48mbit ROM support (no games seems to work yet
                                           + 9MB mem required)
       - Fixed a SRAM Memory Map Bug
       - Fixed a bug in old style joystick read
       - Disabled sram save using tilde key.  Instead, enter/exit
         the GUI since it also saves the sram.
       - Added panic key which turns back on all sound channels and
         backgrounds.  Press 6 to activate this.
       - Added snes mouse support!  Use 7 to switch between keyboard and
         mouse.  Thanks to Y0SHi for info on this!
       - Panic key now turns off mouse when mouse is enabled
       - Fixed a minor IRQ bug
       - Fixed a HDMA bug.  Thanks to Lord Esnes for help on this!
       - Fixed a timing bug.  Thanks to TaNdRuM for help on this!
       - Fixed up some Fixed color add/sub bugs
       - Implemented OBJ Name Base Select.  Thanks to Y0SHi for info!
       - Windowing was off by 1 pixel.  Now fixed.
       - Fixed Screen Add/Sub on back area
       - Added support for 4 and 6 button joysticks
       - Added support for sidewinder joypads
       - Fixed a VESA 2.0 bug.  It should be more compatible now.
       - Implemented Interpolation for 640x480x65536 mode.  Use -Y to enable.
       - Modified sound mixing code a bit
       - Added GUI disable in zsnes.cfg. Add this if you want to disable the GUI
         GUIDisable = 1
       - Implemented Directory Changing in the GUI
       - Fixed a bug where it crashed when loading some ROMs
       - Fixed an ADSR sustain bug.  Thanks to Trepalium for help on this!

v0.201b - Fixed up Save State Selection bug

v0.201 - Fixed up PAL/NTSC detection when GUI is used
       - GUI now doesn't enter load when no files are found.
         Thanks to ScanT for reporting this!
       - Sped up execution loop a bit
       - Fixed up a major save state conversion bug.  Old save states
         should work better now.

v0.200 - Reg$2137 was calculating the horizontal position incorrectly
       - Fixed up a looping bug in sound DSP.  Thanks to EFX for some help
           on this!
       - Added Key to dump SRAM to Harddisk (tilde key, ~) during game
       - Fixed up gain sound effects
       - Fixed a couple of SPC timer bugs
       - Added Stereo Sound!  (Use -Z)
       - Added some precision to the DSP (this seemed to have
           slowed emulation down)
       - Changed Real Time State Save Format.  However, ZSNES will
         automatically convert from an older format.  Some problems
         may come up because of the many changes in the dsp.
       - Fixed up a sprite ordering bug.  Thanks to Y0SHi!
       - Added Scanlines (Use -N)  Only available for 256x256/640x480x65536
       - Adjusted SPC timers
       - Fixed up BG Mode 0 display
       - Fixed up a bug that crashes when hirom sram is accessed
       - Fixed up a VIRQ bug
       - Added a simple, yet effective dsp timer wait substitute.  Seems to
         make many games run much faster with sound!
       - Fixed VRAM increment bug.  Special thanks to Trepalium for this
         info!
       - Fixed up multiple SPC bugs
       - Player 2 was still reading the joystick even though keyboard was
         selected.  This is now fixed.
       - Added VSync (-w).  Thanks to Marius Fodor for the code!
         Please use -f 0 when using this.
       - Added a very simple GUI.  Currently, it only loads, reset, and
         quit.  Also, load cannot change the current directory.
       - Added -m to disable the GUI
       - Added Stereo to zsnes.cfg.  Add this if you want to enable stereo :
           Stereo = 1

---------------------------------------------------------------------------
2.) Disclaimer
---------------------------------------------------------------------------

zsKnight and _Demo_ are not responsible for any damages caused by the use
of this software.  This software also must not to be distributed with
ROMs.

---------------------------------------------------------------------------
3.) System Requirements
---------------------------------------------------------------------------

Minimum System that ZSNES can run on (but strongly not recommended) :

- 386 processor
- 8MB of RAM (You need at least 7MB free)
- VGA card

Somewhat Recommended System :

- 486/66 processor
- 8MB of RAM (min 7MB free)
- VGA card
- Sound Blaster or 100% compatible

Strongly Recommended System :

- Pentium processor or equivalent
- 8MB of RAM (min 7MB free)
- SVGA card
- Sound Blaster 16 or 100% compatible

Recommended System for 65536 (16-bit) color mode :

- Fast Pentium processor (P133 or higher) or equivalent
- 8MB of RAM (min 7MB free)
- SVGA card which supports 320x240x65536 or 640x480x65536 colors
- Sound Blaster 16 or 100% compatible

* You need 9MB of RAM to run 48mbit(6megabytes) roms.

---------------------------------------------------------------------------
4.) Things you should know about ZSNES (Updated v0.295)
---------------------------------------------------------------------------

- Transparency effects are only available in 65536 color mode
- To view 512 resolutions properly, use 640x480 mode.  Only a few games
    uses 512 resolution.  One way to find out is to see if a game has
    that feature is to look for text that looks squished.
- True 512 resolution isn't implemented in 640x480x65536 interpolation,
    non-scanline mode.
- Scrolling in 512 resolution under 640x480 may appear choppy since
    it alternates between the left and right pixels at each frame.
- In 640x480 resolution, the image is scaled so it will look like 320x240
    resolution.  Only use 640x480 resolution if you want to use scanlines,
    interpolation, or if 320x240 doesn't work.
- ZSNES seems to have problems with some 16-bit sound cards and
    sometimes, Windows 95 doesn't set the HDMA setting in the SET BLASTER
    string correctly.  If sound doesn't work on your 16-bit sound card,
    use the -8 command line switch.
- Screen Snapshot and FPS counter are available through a menu by pressing
    F1 during emulation
- Screen Snapshot currently saves as Image.PCX (256 colors) and Image.BMP
    (65536 colors).  This may change in the future.
- FPS counter currently only works when auto frame rate is on.  One for
    non auto frame rate will probabily be implemented in the future when
    we have time.
- To use the cheat function, be sure to have the ROM which you want to
    patch loaded already.
- If the cheat codes do not work, chances are that you are using a different
    version of the rom that was originally used to create them or the codes
    are converted incorrectly from other code formats.
- Config options in the GUI are not available yet and will
    be implemented in the future when we have time.
- Certain video cards/monitors cannot support ModeQ (default resolution)
    If your video card/monitor doesn't support it, run zsnes with -v 0.
    If -v 0 doesn't work, use -v 2 (vesa 2 required)
- Sound DSP has features missing such as noise, echo, and pitch modulation
- 16 bit mode in zsnes requires a Scitech Display Doctor (v5.3+) to provide
    high color, low resolution modes.  You can obtain this software at
    www.scitechsoft.com.  If your video card already supports lo-res,
    hi-color, then don't worry about getting this driver.
- Full Screen addition/subtraction in 65536 mode uses a 13-bit color
    palette (8192 colors) instead of a 15-bit color palette (32768 colors)
    used on a real snes when using full add/sub.
- There are still many bugs left in ZSNES so don't expect it to run all
    your favorite games.
- VSync won't run well unless you specify a frame skip (eg. -f 0)  But
    this feature is highly recommended to be used on very fast machines
    (eg. Pentium IIs)
- The sound buffering is a little buggy at the moment.  It is disabled
  by default and can only be enabled through a command line (-Q).
- SNES Mouse support is still missing some features such as speed settings
- Some ROMs in GD3 format (.078) are interleaved.  This format isn't supported
    by ZSNES at the moment.
- If ZSNES doesn't work for you, then don't use it.  Use SNES9X, ESNES,
        NLKSNES, or SNEESE instead!

---------------------------------------------------------------------------
5.) Current Progress
---------------------------------------------------------------------------

The following are implemented :
- complete 65816 instruction set (bugs still left)
- SRAM support
- LoROM and HiROM support
- SlowROM and FastROM support
- Line by line graphics engine
- Graphic Modes 0,1,2,3,4,5,6,7
- 8x8, 16x16, 32x32 and 64x64 sprite support (flipped in all directions)
- Mosaic effects
- 8x8 and 16x16 tiles
- 32x32,64x32,32x64,64x64 tile modes
- Full DMA support
- Full HDMA effects for wavy backgrounds, interesting mode 7 effects, etc.
- Mode 7 rotating and scaling effects
- Single Windowing Routines
- BG priorities
- Sprite Priorities (still needs some work)
- Add/sub of back area
- HIRQ/VIRQ/NMI Interrupts
- Support for most snes file formats
- Multi file format support (.1,.2,.3,A.,B.,C.)
- 16-bit graphics support
- PAL timing support

The following are present in sound :

- 16bit digital stereo sound
- SPC700 Sound CPU (bugs still left)
- DSP Sound Processor
     - ADSR volume effects
     - GAIN volume effects

Following are present in 16-bit graphics mode :

- Palette changing in the middle of a screen
- Screen Addition (full and half)
- Screen Subtraction (full)
- Fixed Color Addition/Subtraction
- Window clipping for Fixed Color (still needs work)

The following are the features present in ZSNES :

- Game State Save (F2=Save, F3=Select, F4=Load).
    Warning : A state file takes 260 kbytes of HD space!
- Auto frame rate to give you constant Super Nintendo speed up to 12
    frame skips
- configuration file support (zsnes.cfg)
- 2 player support w/ Joystick and Gamepad support

The following features are missing :

- DSP features such as noise, echo, and pitch modulation
- Mode 7 horizontal flip and extbg mode
- Screen Subtraction (half)
- Interleaved ROM formats
- Dual Windowing support
- 512 snes horizontal resolution (not mode 5)
- 448/480 snes vertical Interlaced resolution
- Raster Effects (Scrolling location change in the middle of a
     horizontal line.  There might be a way to get through some of this)

What will not run (or not play properly) :

- Super FX games such as Star Fox, Yoshi's Island, etc.
- DSP games such as Mario Kart, Pilotwings, etc.
- Games with other special chips such as Megaman X2
- Games that have a unique sound checking routine (if sound is disabled)
- Games which doesn't have a valid header (use -L or -H to get it working)
- Games that hit a severe bug in the 65816/PPU/SPC700/DSP routines
- Games that require special timing

---------------------------------------------------------------------------
6.) ZSNES Default Keys
---------------------------------------------------------------------------

Here are the keys while running the emulator:

Disable Backgrounds 1,2,3,4  = 1,2,3,4
Disable Sprites              = 5
Panic Key (enable all)       = 6
Enable SNES Mouse            = 7
PopUp Extra Menu             = F1
Save State                   = F2
Switch State                 = F3
Load State                   = F4
Disable Sound Channel        = F5 - F12
Quit                         = ESC

Here are the default keys for the game play (unless modified in zsnes.cfg) :

Player 1 :

Up,Down,Left,Right : Cursor Keys on Numerical Pad (You can also use
                     the non-numerical pad, but numerical pad is
                     strongly recommended)
A,B,X,Y            : Home, End, Insert, Delete
L,R                : Page Up, Page Down
Start, Select      : Enter, RShift

Player 2 : (You need to enable Player 2)

Up,Down,Left,Right : K, M, N, <
A,B,X,Y            : D, X, S, Z
L,R                : F, C
Start, Select      : Ctrl, Alt

To run the emulator, just type  ZSNES <romname.smc/.sfc/.fig/.1>
To run it with sound, type  ZSNES -s <romname.smc/.sfc/.fig/.1>
To run it in 16-bit mode (VESA2 w/ video card that supports 320x240x65536
        required), type  ZSNES -v 3 <romname.smc/.sfc/.fig/.1>
    or with sound, type  ZSNES -v 3 -s <romname.smc/.sfc/.fig/.1>

* type ZSNES -? to see the available command parameters such
as how to enable joystick, etc.

---------------------------------------------------------------------------
7.) Configuration File (ZSNES.CFG)
---------------------------------------------------------------------------

If zsnes.cfg is missing, please run zsnes.exe since it will create one for
   you if it is not there.

You may edit zsnes.cfg to enter default keys.

Here are the scan codes to use with ScanKey1 and ScanKey2 in the zsnes.cfg

 1  ESC         21 Y        41  ~        61  F3       81  PGDN
 2  1           22 U        42  LSHFT    62  F4       82  INS
 3  2           23 I        43  \        63  F5       83  DEL
 4  3           24 O        44  Z        64  F6
 5  4           25 P        45  X        65  F7
 6  5           26 [        46  C        66  F8
 7  6           27 ]        47  V        67  F9
 8  7           28 ENTER    48  B        68  F10
 9  8           29 CTRL     49  N        69  NUM
10  9           30 A        50  M        70  SCRL
11  0           31 S        51  ,        71  HOME
12  -           32 D        52  .        72  UP
13  =           33 F        53  /        73  PGUP
14  BACKSPC     34 G        54  RSHFT    74  -
15  TAB         35 H        55  PRTSC    75  LEFT
16  Q           36 J        56  ALT      76  KEY5
17  W           37 K        57  SPACE    77  RIGHT
18  E           38 L        58  CAPS     78     
19  R           39 ;        59  F1       79  END 
20  T           40 '        60  F2       80  DOWN

For joystick configuration, here are some ideal configuration for several
    types of joysticks :

2 Button Joysticks :
--------------------

JoyMap1 = 0, 0, 1, 2, 4, 3, 5, 6

Gravis Gamepads :
-----------------

JoyMap1 = 0, 0, 1, 2, 3, 4, 5, 6

Generic 4-button joysticks :
----------------------------

JoyMap1 = 0, 0, 1, 2, 4, 3, 5, 6  (Default)

6-button Joystick Configurations :
----------------------------------

JoyMap1 = 0, 0, 1, 2, 3, 4, 5, 6
JoyMap1 = 0, 0, 1, 2, 4, 3, 5, 6
JoyMap1 = 0, 0, 1, 2, 3, 4, 6, 5
JoyMap1 = 0, 0, 1, 2, 4, 3, 6, 5

If none of those configurations matches you joystick, try changing the
   values around until you find one that's ideal.

Note : If you select 4 button joystick mode, buttons 5 & 6 are ignored.
       If you select 2 button joystick mode, buttons 3,4,5, & 6 are ignored.

Take note that re-running zsnes.exe will automatically create any new
configurations introduced in a version.

---------------------------------------------------------------------------
8.) Cheat Codes
---------------------------------------------------------------------------

Currently, ZSNES supports Game Genie, Pro Action Replay and GoldFinger codes

Here are the steps to get the codes working :

1.) Load the ROM which you want to patch
2.) Exit to the GUI, go to CHEAT, then enter the code of your choice
3.) After that, you may have to RESET the game to get the cheat code to
      work.  Sometimes, it is not necessary.

NOTE : Some cheat codes are meant to be for different versions of the game.
       If a cheat code doesn't work and there is one for both Game Genie
         and Pro Action Replay, try them both.

---------------------------------------------------------------------------
9.) Extra Features (SNES Mouse/Super Scope)
---------------------------------------------------------------------------

To Enable SNES Mouse, Press 7 once for 1st player and twice for 2nd player
To Enable SNES Super Scope, Press 7 three times
To disable either one, either press 6 or press 7 until you see a disable
   message onscreen.

Here are the controls for the Super Scope :

  Fire = Left Mouse button
  Enable/Disable Autofire = Right Mouse button
  Pause = Backspace Key on keyboard
  Cursor Mode Button = =/+ key on keyboard, should be located to the
                       left of the backspace key

---------------------------------------------------------------------------
10.) How to contact the authors / Homepage Address
---------------------------------------------------------------------------

The ZSNES homepage is located at : http://www.csoft.net/zsnes/

When sending mail to the authors, please follow these guidelines to save
  time.  These rules also apply to any other emulation authors :

* Please don't send requests for ROM Images (or games)
* Please don't ask when the next version will be out
* Please read and understand the entire readme file.  Chances are that
    the message you are about to send might be covered here.
* Please do not send any files without asking first.

Also, please don't ask to be a beta tester since we won't accept anymore.

Once you know that your message does not relate to the above, e-mail either
  one of us at :
    zsKnight : zsknight@usa.net
    _Demo_   : _demo_@videotron.ca

---------------------------------------------------------------------------
11.) The Debugger
---------------------------------------------------------------------------

* Note : The debugger is disabled when you don't enter zsnes with a -d

Here are the keys:

1 : Enable/Disable spc700 display
2 : Enable/Disable 65816 display
T : Trace (in 65816 opcodes)
B : 65816 break point
S : SPC break point
C : Clear Counter
M : 65816 modify
A : SPC modify
D : Debug Dump (SPC/DSPRam Dump Only)
W : Break at signal (Used only by the programmers)
F1 : Exit debugger and return to Game
F2 : Save State
F4 : Load State
ESC : Exit entire program

---------------------------------------------------------------------------
12.) Credits
---------------------------------------------------------------------------

Special thanks to wnelson!  Without him, ZSNES would have never existed!
Also to Y0SHi for his excellent snes docs, his help, and his excellent
        support!

Also Thanks to :
  The_Teach of snes9x for some great info and the nice chats!
  Trepalium of snes9x for some great info and help!
  Gary of Snes9x and Steve Snake of KGen for being the source of info for
      sound decompression!
  Gary of Snes9x for being the source of info for TCall/PCall!
  MrGrim for his great support!
  Void for some info on Sound Blaster programming!
  Aquis for the zsnes logo!
  Alucard for helping us with an issue in the 65816!
  Vertigo for making a compatibility list!
  EFX for being a great supporter and also giving a lot of help and stuff!
  Zophar for being a great supporter and also maintaining the mirror site!
  Chris Hickman for redesigning the ZSNES web page!
  CSoft for hosting our web page!
  Marius Fodor for the code for VSync!
  Sardu for some great info and help!
  Lord Esnes for some help!
  Robert Grubbs for the sidewinder info!
  Nerlaska for some useful info on optimising and also for some help!
  Diskdude for writing sneskart which we used for the info on cheat codes!
  DarkForce for some great help!
  All those people who helped us by either sending us docs
    helping us, supporting us, and reporting bugs!
  And also to all those whom we forgot!

Special Thanks to all our beta testers for being a great help!
_Demo_ would also like to give thanks to tgenius and 4999 for testing his
    65816emu hack in #snesemu a while ago.
Info on 256x256x256 scanlines mode is from the MAME source.  Thanks to
   those behind MAME!

Also, good luck to all those who are writing emulators, especially those
    who are writing snes emulators, including Esnes, Nlksnes, SNEeSe and
    SNEMul!
