
                                 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.600)
5.) Current Progress
6.) Future Progress
7.) ZSNES Default Keys
8.) Extra Pop-Up Menu (F1 Menu)
9.) Configuration File (ZSNES.CFG)
10.) Cheat Codes
11.) Extra Features (SNES Mouse/Super Scope/SuperFX/MultiTap)
12.) Bugs Section
13.) Contact Information
14.) The Debugger
15.) Credits

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

See WHATSNEW.TXT

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

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

- 386 processor (486 processor required for new graphics engine)
- 8MB of RAM (You need at least 6MB free)
- VGA card

Somewhat Recommended System :

- 486/100 processor
- Min 8MB of RAM (min 6MB free, only can run 2MB rom images)
- VGA card
- Sound Blaster or 100% compatible

Strongly Recommended System :

- Pentium processor (P100 or higher)
- 16MB of RAM (min 12MB free)
- SVGA card
- Sound Blaster 16 or 100% compatible

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

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

Recommended System for SFX support :

- Fast Pentium processor (P200 or higher)
- 16MB of RAM (min 10MB free)
- VGA card
- Sound Blaster 16 or 100% compatible

* You need 10MB of RAM to run 48mbit(6megabytes) roms.
* You need 11MB of RAM to use the new graphics 16bit engine.

For SuperFX emulation, 10 megabytes of free memory is required to run.

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

- Transparency effects are only available in 65536 color mode
- Using 320x240 resolution modes are faster than 640x480 modes.  Use
  640x480 modes only if you can't run 320x240 modes or if you want the
  added features of 640x480 modes
- For some reason, some transparency modes in the new graphics 16bit
    engine is slower than the old graphics engine.  This will hopefully
    be figured out later on.
- New Graphics 16bit only works on 320x240x65536 mode at the moment
- New Graphics 16bit engine is missing many effects so many games won't
    display the graphics correctly when using this 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.
- SuperFX can be slow because it is an extra 10/20mhz cpu that has to be
    emulated as well as the snes emulation
- 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.
- Game Genie codes don't seem work well with HiROM games at the moment
- 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 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
- Pressing the Fast Forward key is equivalent to running ZSNES using -f 9
- If ZSNES doesn't work for you, then don't use it.  Use SNES9X, ESNES,
    NLKSNES, SNEESE, or SNEMUL instead!  In fact, even if you use ZSNES,
    use those emulators too!

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

The following are implemented :
- complete 65816 instruction set
- SRAM support
- LoROM and HiROM support
- SlowROM and FastROM support
- Full DMA support
- HIRQ/VIRQ/NMI Interrupts
- Support for most snes file formats
- Multi file format support (.1,.2,.3,A.,B.,C.)
- Interleaved format support
- PAL/NTSC timing support

The following are implemented in the old graphics engine :
- Line by line based 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 HDMA effects for wavy backgrounds, interesting mode 7 effects, etc.
- Mode 7 rotating and scaling effects
- Single and Dual Windowing Routines
- BG priorities
- Sprite Priorities
- Add/sub of back area
- 16-bit graphics support
- offset per tile mode (mode 2/vertical only)
- High res 512 horizontal resolution

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

The following are implemented in the new graphics engine 8 bit :
- Combination of line by line and tile based graphics engine
- Graphic Modes 0,1,2,3,4,5,6,7
- 8x8, 16x16, 32x32 and 64x64 sprite support (flipped in all directions)
- 8x8 and 16x16 tiles
- 32x32,64x32,32x64,64x64 tile modes
- Full HDMA effects for wavy backgrounds, interesting mode 7 effects, etc.
- Mode 7 rotating and scaling effects
- BG priorities
- Sprite Priorities
- Add/sub of back area
- Mosaic Effects
- Offset per tile mode (mode 2/vertical only)
- High res 512 resolution and 448/478 vertical resolution

The following are implemented in the new graphics engine 16 bit :
- Combination of line by line and tile based graphics engine
- Renders graphics by using 256 color buffers
- Graphic Modes 0,1,2,3,4,5,6,7
- 8x8, 16x16, 32x32 and 64x64 sprite support (flipped in all directions)
- 8x8 and 16x16 tiles
- 32x32,64x32,32x64,64x64 tile modes
- Full HDMA effects for wavy backgrounds, interesting mode 7 effects, etc.
- Mode 7 rotating and scaling effects
- BG priorities
- Sprite Priorities
- Add/Sub of back area (Not Correct and slow)
- Fixed Color Add/Sub (Not Correct due to lack of Windowing)

The following are present in sound :

- 16bit digital stereo sound
- SPC700 Sound CPU
- DSP Sound Processor
     - Echo Effects
     - FIR Filter
     - ADSR volume effects
     - GAIN volume effects
     - Noise effects

The following are extra features emulated :

- Super NES Mouse Support
- Super NES Super Scope Support
- SuperFX support
- MultiTap (Multiplayer 5) support

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 9
    frame skips
- configuration file support (ZSNES.CFG)
- 2 player support w/ Joystick and Gamepad support

The following features are missing :

- DSP features such as pitch modulation
- Mode 7 horizontal flip and extbg mode
- Screen Subtraction (half) (Except for newgfx 16b engine)
- 512 snes horizontal resolution, 16x16 tiles (Except for newgfx 8b engine)
- Pseudo 512 snes horizontal resolution
- 448/478 snes vertical Interlaced resolution (Except for newgfx 8b engine)
- Some modes in Offset Mode
- Windowing in the back area of the main screen
- Some Direct Color Modes

What will not run (or not play properly) :

- Some Super FX games such as Star Fox and Stunt Race FX
- DSP games such as Mario Kart, Pilotwings, etc.
- Games with other special chips such as Megaman X2 and Mario RPG
- 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.) Future Progress
---------------------------------------------------------------------------

These are only here for people who wants to know what we might do for
  the future version.  Please take note that we will not guarantee that
  these will be implemented nor are they listed in the order on which
  they will be implemented.  They are also not guaranteed to be in the
  upcoming version.

- Add Pitch Modulation
- Attempt to fix up several incorrectly played SFX (Wind noises, etc.)
- Fix up remaining SuperFX bugs (If possible) and optimise
- Add windowing to the main screen back area
- Finish Mode 7
- Rewrite 65816 emulation or at least give it an overall (fix up timing/speed up)
- Add proper HIRQ emulation, should fix up some compatibility and fix those
  off by 1 line bugs
- Finish up new graphics engine in 256 colors and eliminate the old
  graphics engine
- Fix up new graphics 16bit engine and speed up
- Update spc700 timer to 64KHz instead of 16KHz to allow music to
  sync more properly with the game
- Add spc700 cycle deduction (maybe not necessary)
- Add Modem/Network Support
- Rewrite Sound Buffering/Add AWE32 Support (Should speed up emulation!)
- Make an MMX enhanced version of ZSNES (possibly with the newgfx16bit engine)
- Speed up emulation
- Anything else that comes up

---------------------------------------------------------------------------
7.) ZSNES Default Keys
---------------------------------------------------------------------------

Here are the default keys while running the emulator.  They can be changed
through the GUI except for F1 and ESC :

Disable Backgrounds 1,2,3,4  = 1,2,3,4
Disable Sprites              = 5
Panic Key (enable all)       = 6
Enable SNES Mouse/SuperScope = 7
Enable New Graphics Engine   = 8
Disable Windowing            = 9
Disable OffsetMode           = 0
Fast Forward Key             = ~
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 through the GUI):

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>

---------------------------------------------------------------------------
8.) Extra Pop-Up Menu (F1 Menu)
---------------------------------------------------------------------------

Save Snapshot - Saves a snapshot as either .PCX (8-bit color) or .BMP
                (16-bit color)

Show/Hide FPS - Shows or hides the frame per second display which appears
                on the bottom-left corner of the screen.  This can only
                be enabled in auto-frame rate mode.

Save SPC Data - Selecting this will search for the beginning of the next
                song and save the data into a .spc file which saves it
                similarly as a .srm file.  To capture a song, it is best
                recommended to initiate this feature approx 2 seconds
                before the next song starts.  This does have potential to
                fail though so don't expect it to work all the time.
                Also, this feature doesn't work in the new gfx engine.

Sound Buffer Dump - This dumps the sound buffer in zsnes and also filters
                out any unoccupied space.  The sound buffer contains
                decompressed samples which are written to when zsnes
                plays/decodes a sample from sound memory. Because of the
                way zsnes buffers the sound data, this can produce
                inaccurate results.

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

Almost everything in zsnes.cfg should now be editable through the gui

---------------------------------------------------------------------------
10.) 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, enter the code of your choice in the cheat menu
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.

---------------------------------------------------------------------------
11.) Extra Features (SNES Mouse/Super Scope/SuperFX/MultiTap)
---------------------------------------------------------------------------

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
  Cursor Mode Button = Right Mouse button
  Pause = Backspace Key on keyboard
  Enable/Disable Autofire = =/+ key on keyboard, should be located to the
                       left of the backspace key

Zsnes auto-detects the SFX emulation from the header and enables it when
   found.  Also, take note that the SFX is an additional 10Mhz(Ver1) or
   20Mhz(Ver2) chip which also has to be emulated with the snes and will
   most likely produce a very noticeable slow down in emulation.  There is
   also an unknown bug in the SuperFX emulation which causes many games to
   not run properly.

Sometimes, the Multitap isn't compatible with some games.  If that happens,
   disable Multitap by setting Player3 and 4's input device to 'None' in
   the GUI

---------------------------------------------------------------------------
12.) Bugs Section
---------------------------------------------------------------------------

- Several transparency effects are incorrect in zsnes due to some priority
  problems that are not easy to implement.  If you encounter a problem
  in transparencies (and make sure you're in 16bpp mode), try changing
  to the new graphics 16bit engine since it handles the transparencies
  differently.
- SuperFX bugs are present.  We've got some great help (thanks to that
  person who attempted to help us!) and we spent a lot of time
  debugging it (even after .400 release), but we still can't figure
  out what causes the polygons to not show in several games.
- DSP1 emulation is present in ZSNES, but is very limited because of the
  precision problems present when some of the functions that are converted
  from C to ASM in fixed point notation.  Those functions with problems
  were removed from this version.  Once ZSNES gets C linked to it,
  a floating point version should be possible.
- 65816 lacks correct timing.  Although ZSNES bases the timing on a
  variable cycle/instruction, it does not deduct correct values such
  as 16bit instructions should deduct 1 more cycle than 8bit instructions.
  100% cycles of zsnes isn't 100% cycles of a snes because of that.
  This means that a lot of games either won't run or will produce horrible
  displays.
- Several games that don't update at every screen tend to flicker.  This
  is probabily because zsnes doesn't handle forced blank properly yet.  This
  can temporarily be fixed by setting the frameskip value until the flicker
  goes away
- Some games tend to produce off by 1 line bugs.  This is because
  HIRQ isn't implemented correctly
- Games sometimes tend to not display things properly because of graphic
  features that aren't implemented yet
- The Sound DSP chip is nearly complete (pitch modulation is missing), but
  it still has its bugs
- Several Sound Effects such as Wind , Soft Noises, etc. play incorrectly
  and tend to sound like beeps or loud howling noises.  We are currently
  unsure on what causes this and it will be addressed once we find out.

---------------------------------------------------------------------------
13.) Contact Information
---------------------------------------------------------------------------

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

If you have any questions about zsnes and you have read ZSNES.FAQ,
README.TXT, and GUINOTES.TXT to make sure the answer isn't there.
And your question is NOT a ROM Request or asking about a newer
version, you can post your question at the zsnes www board located at :

http://www.csoft.net/~zsnes/board/

Be sure to also read the RULES!  The link to the rules is located at the
top of the page.

If you wish to contact the authors, you may contact them through :
(Remember - No ROM requests please! and don't send any files without
 permission!)

zsknight@usa.net
_demo_@videotron.net
pharos@dal.net

Try not to send a copy of your e-mail to all of us since that will just
  waste our time.  Also, don't expect to get a reply since we are often
  busy.

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

---------------------------------------------------------------------------
15.) 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!
  Crono for 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, Sidewinder, Gamepad Pro, and some
    optimisation info!
  Sardu for some great info and help!
  Lord Esnes for some great 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!
  Pharos for some keyboard coding help!
  Lestat and feenix65 of snes9x team for all the great help which includes
    their superfx info and code, info on interleave formats (hirom & superfx),
    offset per tile mode, FIR filter, some spc700 and hdma bugs!
  WolfWings ShadowFlight for help on several issues of nasm!
  All those people who helped us by either sending us docs
    helping us, supporting us, and reporting bugs!
  Special Thanks to : Hucard, Kaiden, and the people in #zsnes efnet
  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 Snes9x, Nlke, SNEeSe, and
    SNEMul!  And also good luck to the makers of TheSE!
