Snes9X v1.00 06/13/98
=====================

Contents
========
Introduction
What's Emulated
What's Not
What You Will Need
Getting Started/Command Line Options
Keyboard Controls
Joystick Support
SideWinder Support
GrIP Support
Super FX
Problems With ROMs
Sound Problems
Converting ROM Images
Speeding up the Emulation
Credits

Introduction
============

Snes9X is a portable, freeware Super Nintendo Entertainment System (SNES)
emulator. It basically allows you to play most games designed for the SNES
and Super Famicom Nintendo game systems on your PC or Workstation; they
include some real gems that were only ever released in Japan.

Snes9X is the result of well over a year and a half's worth of part-time
hacking, coding, recoding, debugging, divorce, etc. (just kidding about the
divorce bit). Snes9X is coded in C++ with three assembler CPU emulation
cores on the i386 Linux, MS-DOS and Windows ports.

Snes9X is better than a real SNES:
o Freeze a game at any position, then restore the game to that exact spot at
  a later date - ideal for saving a game just before a difficult bit.
o Built-in cheat cartridge.
o Built-in peripheral emulation. The SNES mouse, Multi-player 5 and SuperScope
  external add-ons are all emulated, they cost extra money with a real SNES.
o Stereo sound - yes I know the SNES produced stereo sound, but who actual
  paid the inflated price for the special lead just so you could hear it?
o No more cartridge contact cleaning!
o Some SNES hardware features that be turned on and off during game play,
  games might be using one of these features to deliberately make a section
  of the game more difficult. Easy, just turn the feature off.
o Crystal clear graphics on your computer monitor - actually that could be a
  minus point as well because the fuzzy T.V. picture could be used to
  disguise the fact that most SNES games output only a 256x224 pixel display.

Snes9X is worse than a real SNES:
o Unless your computer is very fast (Pentium II+), some games just can't
  hit every frame being rendered and the emulator starts to omit rendering
  some frames to keep the emulator running at a constant speed - to you
  it appears as if the graphics aren't moving as smoothly as they should.
o Not all games work; bugs and missing features cause some games to fail to
  run or renders them unplayable.
o You have to wait for your computer to boot before you can play games,
  no waiting on the real SNES.
o The SNES has an analog low-pass sound filter that give a nice bass to
  all the sounds and music - Snes9X doesn't emulate this. If you have
  a posh sound card, you could try fiddling with it mixer controls to produce
  a similar effect.

What's Emulated
===============
- The 65c816 main CPU.
- The Sony SPC700 sound CPU.
- SNES variable length cycles.
- 8 channel DMA and H-DMA (raster effects).
- All background modes, 0 to 7.
- Sound DSP, with 8 16-bit stereo channels, compressed samples, hardware
  attack-decay-sustain-release volume processing, echo, pitch modulation
  and digital FIR sound filter.
- 8x8, 16x8 and 16x16 tile sizes.
- 32x32, 32x64, 64x32 and 64x64 screen tile sizes.
- H-IRQ, V-IRQ and NMI.
- Mode 7 screen rotation, scaling and screen flipping.
- Vertical offset-per-tile in modes 2, and 4.
- 256x224, 256x239, 512x224, 512x239, 512x448 and 512x478 SNES screen
  resolutions.
- Sub-screen and fixed color transparency effects.
- Mosaic effect.
- Single and dual graphic clip windows, with all four logic combination mode,
  although XOR and X-NOR are still a bit buggy.
- Color effects only inside a window.
- 128 8x8, 16x16, 32x32 or 64x64 sprites, flipped in either direction.
- SNES palette changes during frame.
- Super FX, a 21/10MHz RISC CPU found in the cartridge of several games.
- SNES mouse.
- SuperScope (light gun) emulated using computer mouse.
- Multi-player 5 - allowing up to five people to play games simultaneously.
- Game-Genie, Action Replay and Gold Finger cheat codes.
- Multiple ROM image formats, with or without a 512 byte copier header.
- Single or split images, compressed using gzip, and interleaved in one of two
  ways.
- Auto S-RAM (battery backed RAM) loading and saving.
- Freeze-game support, now portable between different Snes9X ports.

What's Not
==========

- DSP1 support. The DSP1 is a math co-processor chip that was inside the
  cartridge of some games, notably Mario Kart.
- Any other odd chips that manufactures sometimes placed inside the
  cartridge to enhance games and as a nice side-effect, also act as an 
  anti-piracy measure.
- Direct color mode - uses tile and palette-group data directly as RGB value.
- Pseudo hi-res. mode - SNES hardware uses interpolation to give apparent
  increase in horizontal resolution.
- Mosaic effect on mode 7.
- Color subtraction with the halve-the-result flag set. Didn't think any
  games used it, but zsKnight tells me Chrono Trigger does.
- extbg mode in mode 7. Seems to reduce the available colors to 128, but
  provide a priority bit with each pixel, but selectable priority between
  what? Answers on a postcard please....
- A couple of SPC700 instructions that I can't work out what they should do.
- Fixed color and mosaic effects in SNES hi-res. (512x448) modes.
- Offset-per-tile in mode 6. Luckily I haven't found a game that uses it, yet.
- Horizontal offset-per-tile in modes 2, 4 and 6.
- Cycle counting on SPC700 emulation.
- Executing SPC700 instructions during SNES DMA operation.
- Exact sound CPU and sound generation synchronization.
- Various pixel priority problems with sprites and transparency effects.

What You Will Need
==================

CPU
---
Faster the better, but 486DX4 100 minimum when using 8-bit graphics and
minimal or no sound, Pentium 166 or higher for transparency effects and
Pentium 200 or higher for Super FX games.

Memory
------
8Mb for DOS (absolute minimum) and 16Mb for Windows 95 and Linux.

Screen
------
Fast graphics card. DOS prefers to have VESA2 support, so it can access a
320x240 16-bit screen mode.

Disk Space
----------
1Mb for the emulator.

Software
--------
Access to SNES ROM images in *.smc, *.sfc, *.fig or *.1, *.2, or sf32xxxa,
sf32xxxb, etc., format otherwise you will have nothing to run!

Please note, it is illegal in most countries to have commercial ROM images
without also owning the actual SNES ROM cartridge.

Getting Started
===============

From a shell just type:
snes9x <ROM filename>

ROM images are normally loaded from the directory .\roms. This can be
changed by specifying a pathname with the image name or setting the
environment variable SNES96_ROM_DIR to point to a different directory.

Freeze game files and S-RAM save files are normally read from and written to
the directory .\snesnaps, for DOS and $HOME/.snes96_snapshots for Linux.
This can be changed by setting the environment variable SNES96_SNAPSHOT_DIR
to point to a different directory.

Some command line flags are available:

Graphics options:
-tr or transparency (default: off)
   Enable transparency effects, also enabled 16-bit screen mode selection.
-16 or -sixteen (default: off)
   Enable 16-bit screen mode, allows palette changes but no transparency
   effects.
-hires or -hi (default: lo-res.)
   Enable support for SNES hi-res. and interlace modes. USE ONLY IF GAME
   REQUIRES IT (FEW DO) BECAUSE IT REALLY SLOWS DOWN THE EMULATOR.
-scale or -sc (default: off)
   Stretch the SNES display to fit the whole of the computer display.
-m 0-12 or -mode 0-12 (default: based on above options)
   0 - 320x240, ModeX 8-bit, slow.
   1 - 320x200 8-bit, faster but clips part of display.
   2 - 256x256 8-bit, best when using 8-bit graphics, but might not work with
                      all graphics cards.
   3 to 6 - 640x480 8-bit, various auto-detect or VESA modes.
   7 - 640x400 8-bit.
   8 - 800x600 8-bit.
   9 - 320x240 16-bit.
   10 - 640x480 16-bit.
   11 - 640x400 16-bit.
   12 - 800x600 16-bit.

Sound options:
-ns or -nosound
   Disable sound CPU emulation and sound output, useful for the few ROMs
   where sound emulation causes them to lock up due to timing errors.
-sk 0-3 or -soundskip 0-3 (default: 0)
   USE ONLY IF SOUND IS DISABLED. 
-stereo or -st (default: mono)
   Enable stereo sound output.
-r 0-7 or -soundquality or -sq 0-7 (default: 4)
   Sound playback rate/quality:
       0 - disable sound, 1 - 8192, 2 - 11025, 3 - 16500, 4 - 22050 (default),
       5 - 29300, 6 - 36600, 7 - 44000.
-b size or -buffersize size or -bs size (default: auto-select)
   Sound playback buffer size in bytes 128-4096.
-envx or -ex (default: off)
   Enable volume envelope height reading by the sound CPU. Can cure sound
   repeat problems with some games, while causing others to lock if enabled.
-nosamplecaching or -nsc or -nc (default: on)
   Disable decompressed sound sample caching. Decompressing samples takes time,
   slowing down the emulator. Normally the decompressed samples are saved
   just in case they need to be played again, but the way samples are stored
   and played on the SNES, it can result in a click sound or distortion when
   caching samples with loops in them.
-noecho or -ne (default: on)
   Turn off sound echo and FIR filter effects. Processing these effects can
   really slow down a non-MMX Pentium machine due to the number of calculations
   required to implement these features.
-ratio 1+ or -ra 1+ (default: 2)
   Ratio of 65c816 to SPC700 instructions. Default of 2 is fine for most
   games, but 3 gets Fifa 96 and games written by the software house Human
   working. There will be others.

Cheat options:
-gg <code> or -gamegenie <code>
   Supply a Game Genie code for the current ROM. Up to 10 codes can be in
   affect at once. Game Genie codes for many SNES games are available from:
   http://game-genie.nvc.cc.ca.us
-ar <code> or -actionreplay <code>
   Supply a Pro-Action Reply code for the current ROM. Up to 10 codes can be in
   affect at once. At the moment, codes which alter RAM do not work.
-gf <code> or -goldfinger <code>
   Supply a Gold Finger code for the current ROM. Up to 10 codes can be in
   affect at once.

Speed up/slow down options: (See "Speeding Up The Emulation")
-f <frame skip count> or -frameskip <frame skip count> (default: auto-adjust)
   Set this value to deliberately fix the frame skip rate and disable auto-
   speed regulation. Use a larger value faster emulation but more jerky
   movement and a smaller value for smooth but slower screen updates.
   Use '+' and '-' keys to modify the value during a game.
   Ideal for some Super FX games that confuse the auto-adjust code or
   for games that deliberately flash the screen every alternate frame.
-h <0-200> or -cycles <0-200>(default: 100)
   Percentage of CPU cycles to execute per scan line, decrease value to
   increase emulation frame rate. Most ROMs work with a value of 85 or above.
-j or -nojoy
   Turn off automatic joystick detection (joystick polling on the PC slows
   the emulator down).

ROM image format options:
-i or -interleaved (default: auto-detect)
   Force interleaved ROM image format.
-i2 or -interleaved (default: can't be auto-detected)
   Force alternate interleaved format (i.e. most Super FX games).
-hirom or -fh or -hr (default: auto-detect)
   Force Hi-ROM memory map for ROMs where the Hi-ROM header test fails.
-lorom or -fl or -lr (default: auto-detect)
   Force Lo-ROM memory map for ROMs where the Hi-ROM header test fails)
-p or -pal (default: auto-detect)
   Fool ROM into thinking this is a PAL SNES system.
-n or -ntsc (default: auto-detect)
   Fool ROM into thinking this is a NTSC SNES system.
-l or -layering (default: off)
   Swap background layer priorities from background involved in sub-screen
   addition/subtraction. Can improve some games play-ability - no need to
   constantly toggle background layers on and off to read text/see maps, etc.
   Toggle feature on and off during game by pressing '8'.
   Not used if transparency effects are enabled.
-l <freeze game file name> or -loadsnapshot <freeze game file name>
   Load snapshot file and restart game from saved position.
-nh or -nohdma (default: H-DMA enabled)
   Turn off the H-DMA emulation. Pressing '0' during a game toggles H-DMA on
   and off.
-n or -nospeedhacks (default: speed hacks)
   Turn off a couple of speed hacks. The hacks boost the speed of many ROMs
   but cause problems a few ROMs.
-nw or -nowindows (default: graphics windows emulated)
   Disable graphics windows emulation. Use 'backspace' key during a game to
   toggle the emulation on and off.

Joystick options:
-a 
   Alternate SideWinder game pad button mappings.
-4 or -four (default: auto-detect two-button joystick)
   Joystick connected to computer has 4 buttons.
-6 or -six (default: auto-detect two-button joystick)
   Joystick connected to computer has 6 buttons.
-s or -swap
   Swap emulated joy-pad 1 and 2 around, pressing '6' during a game does the
   same thing.
-j or -nojoy
   Turn off automatic joystick detection (joystick polling on the PC slows
   the emulator down).

For example, to start a game called "mario", with sound, and transparency
effects, type:

snes9x -tr mario.smc

Keyboard Controls
=================

While the emulator is running:
'Escape'                 Quit the emulator
'Pause' or 'Scroll Lock' Pause the emulator

Joy-pad 1:
'up' or 'u'             Up direction
'down', 'j' or 'n'      Down direction
'left' or 'h'           Left direction
'right' or 'k'          Right direction
'a', 'v' or 'q'         TL button
'z', 'b' or 'w'         TR button
's', 'm' or 'e'         X button
'x', ',' or 'r'         Y button
'd', '.' or 't'         A button
'c', '/' or 'y'         B button
'return'                Start button
'space'                 Select button

'Mouse left'            Mouse left button or SuperScope fire button.
'Mouse right'           Mouse right button or SuperScope cursor button.

'tab'                   SuperScope turbo toggle switch.
'`'                     SuperScope pause button.

'0'                     Toggle H-DMA emulation on/off.
'1'                     Toggle background 1 on/off.
'2'                     Toggle background 2 on/off.
'3'                     Toggle background 3 on/off.
'4'                     Toggle background 4 on/off.
'5'                     Toggle sprites (sprites) on/off
'6'                     Toggle swapping of joy-pad one and two around
'7'			Rotate between Multi-player 5, mouse on port 1,
                        mouse on port 2 and SuperScope emulation.
'8'                     Toggle background layer priorities for backgrounds
                        involved in sub-screen addition/subtraction.
'9'			Toggle transparency effects on and off - only if
			16-bit screen mode selected.
'Backspace'		Toggle emulation of graphics window effects on/off.

'-'			Decrease frame redraw skip rate
'+'			Increase frame redraw skip rate
			The sequence is auto-frame rate adjust, render every
                        frame, render 1 frame in two, render 1 frame in three,
                        render 1 frame in four, etc.

Shift+'F1-F10'          Quick save a freeze game file.
'F1-F10'                Quick load a freeze game file, restoring a game to an
                        exact position.
Alt+'F2'                Load a game's saved position.
Alt+'F3'                Save a game's position.

Alt+'F4' -> 'F11'	Toggle sound channels on/off.
Alt+'F12'		Turn on all sound channels.

Joystick Support
================

Snes9X supports one or two 2-button joysticks, or one 4-button or 6-button
joystick - this limitation is imposed by PC hardware.

On a 2-button joystick only the A and B SNES buttons are available, the
remaining 4 can still be accessed via the keyboard.

The following diagram shows you the button layout for 6-button PC joy-pads
that look similar to real SNES joy-pads:

     ---TL---           ---TR---

        ^                  X
        |
     <-   ->            Y     A
        |       /  /
        v                  B

Make sure the joystick is centered or no buttons pressed for joy-pads when
the emulator is first started to enable auto-calibration to work.

SideWinder Support
==================

Snes9X can auto-detect up to four or more Microsoft SideWinder game-pads.
A Pentium or faster computer is required with a speed-regulated joystick port.

Under Windows 95, Microsoft's latest 2.0 drivers prevent DOS applications
accessing the joystick port directly and instead emulate a standard 4-button
joystick, which Snes9X promptly auto-detects. The trick is to temporarily
disable the Microsoft drivers so Snes9X can auto-detect the SideWinders and
access all 14 button of its buttons.

Try one of the following:
- Reboot into DOS mode and run Snes9X from there.
- Use the unload profiler option from the task bar icon popup menu, start
  Snes9X, press the mode button twice on the sidewinder, quit Snes9X and
  restart it again. Snes9X should have correctly auto-detected the SideWinder.
  This trick only works if one SideWinder is plugged in.
- From the Control Panel, double-click on the Game Controllers icon,
  then press on the advanced tab, then change all the controller ID's to
  none except the first, change that to 2-axis, 4-button joystick.
  Start Snes9X. To go back to Windows drivers, change controller ID 1 back
  to being a SideWinder gamepad.

Button mapping
--------------
 SNES                SideWinder           Alternate SideWinder (-a)
 ----                ----------           -------------------------
 A                   B                    A
 B                   A                    B
 X                   Y                    X
 Y                   X                    Y
 TL                  Trigger Left         Trigger Left
 TR                  Trigger Right        Trigger Right
 Start               Start                Start
 Select              M                    M

GrIP Support
============

Snes9X supports one or two Gravis GamePad Pros plugged into the joystick
port. Make sure the GRIP.GLL file is in the same directory as Snes9X.exe
or in one of directories listed in the GRIP environment variable.

Unfortunately, the official GrIP toolkit seems to use the same DOS timer
as the Allegro library, and the Snes9X continually speeds up and slows down
as the two libraries fight for control, which makes the native GrIP
support worse than useless. Gravis themselves were no help; they deserve to
go under.

Any one have any suggestions?

Super FX
========

The Super FX is a 10/21MHz RISC CPU developed by Argonaut Software used as a
game enhancer by several game tiles. Support is still buggy and I've no
idea what the problem is. Oh well, may be one day. Anyway, games that work:
Yoshi's Island (best single-player game on SNES), Doom, Winter Gold and 
Dirt Trax FX.

Games that don't work:
StarFox, Stunt Race FX, Vortex.

All games that actually work are extremely playable on my 200MHz K6 desktop
machine. Frame rates will suffer for folks with slower machines.

Problems With ROMs
==================

If the emulator just displays a black screen for over 10 seconds then one
of the following could be true:

1) If its a SuperFX game, chances are its in interleaved2 format, try the -i2
   switch.
2) Someone has edited the Nintendo ROM information area inside the ROM image
   and Snes9X can't work out what format ROM image is in. Try playing
   around with the ROM options: -i, -fl, -fh, -hd, -nh.
3) The ROM image is corrupt. If you're loading from CD, I know it might
   sound silly, but is the CD dirty?
4) The 65c816 to SPC700 communication has failed. Try -ratio 3. If that
   doesn't work, and you don't mind playing the game without sound, try 
   -ns and then -ss 0 or -ss 1 or -ss 2 or -ss 3.
5) The original SNES ROM cartridge had additional hardware inside that is not
   emulated yet and might never be - e.g. Street Fighter 2 Alpha,
   all DSP1 games, etc.

Sound Problems
==============

No sound coming from any SNES game using Snes9X? Could be any or all of
these:

- Your computer doesn't have a Sound Blaster or true compatible sound card
  fitted. Wait for the Windows 95/NT port.
- The BLASTER environment variable isn't setup correctly.
- The sound card mixer volume has been turned right down. Use the mixer
  utility that should have come with the card to set the volume.
- You haven't got the volume control on your speakers turned down, have you?

General sound problems:

- Music plays very slowly on some games, try the -nh option.
- Sound samples keep getting repeatedly played on some games, try -envx.
- Sound quality is poor. Only true Sound Blaster 16 cards and better support
  16-bit sound samples with the Allegro driver I'm using, everything else
  has to put up with 8-bit sound. Buy a better card, or wait for the
  Windows port. One day I might get around to using the SEAL library, it
  supports a wider range of sound cards in 16-bit mode, including some Sound
  Blaster incompatible cards.

Converting ROM Images
=====================

If you have a ROM image in several pieces, simply rename them so their
filename extensions are numbered: e.g. game.1, game.2, etc. Then, when
loading the ROM image, just specify the name of the first part; the remaining
parts will be loaded automatically.

If they are already in the form sf32xxxa, sf32xxxb, etc., you don't even have
to rename them; just specify the name of the first part, as above.

Emulation speed
===============

Emulating an SNES is very compute intensive, with its two or three CPUs,
an 8 channel digital sound processor with real-time sound sample decompression
and stereo sound, two custom graphics processors, etc.

If you only have a 486 machine, you will need to stick to using only 8-bit
graphics and minimal or no sound:

With sound:
snes9x -ne -r 1 -m 2 -mono <rom filename>

Without sound:
snes9x -ns -m 2 <ROM filename>.

Disabling the joystick support will also help (-j).

Users of non-MMX, slower Pentium machines might want to turn off echo and
digital FIR filter effects, due to the number of multiply operations needed
to implement them (multiply is a lot faster on MMX CPUs). Use -ne option.

Got a big throbbing beast of a CPU under the cover of your computer? These
options will sort out the men from the boys:
snes9x -m 10 -r 5 -scale <ROM filename>

Credits
-------

- Jerremy Koot and Gary Henderson for all their hard work on previous versions
  of Snes96, Snes97 and Snes9X.
- Lstat for the original Super FX C emulation and information.
- zsKnight and _Demo_ for the Intel Super FX assembler code.
- zsKnight and _Demo_ for all the other ideas I've nicked off them; they've
  nicked lots of my ideas and information too!
- DiskDude's SNES Kart v1.6 document for the Game Genie(TM), Gold Finger and
  Pro Action Replay cheat system information.
- Lord ESNES for some nice chats and generally useful stuff.
- Lee Hyde (lee@jlp1.demon.co.uk) for his quest for sound information and 
  the Windows 95 icon.
- Shawn Hargreaves for the rather good Allegro 3.0 DOS library.
- Robert Grubbs for the sidewinder information - although I didn't use his
  actual driver in the end.
- Steve Snake for his insights into SNES sound sample decompression.

Super NES, SuperScope and Super FX are a trademarks of Nintendo. 
Sun, Solaris and Sparc are trademarks of Sun Microsystems, Inc.  
Game Genie is a trademark of Lewis Galoob Toys, Inc.
MS-DOS and Windows 95 are trademarks of Microsoft Corp.
Intel, Pentium and MMX are all trademarks of Intel Corp.
Sony is a trademark of Sony Corp.

------------------------------------------------------------------------------
feenix65@hotmail.com
