Snes9x for Unix

Introduction

What is Snes9x?

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 Mac, Linux, Windows and so on. The games include some real gems that were only ever released in Japan.

The original Snes9x project was founded by Gary Henderson and Jerremy Koot as a collaboration of their earlier attempts at SNES emulation (Snes96 and Snes97.) Over the years the project has grown and has collected some of the greatest talent in the emulation community (at least of the SNES variety) some of which have been listed in the credits section, others have helped but have been loss in the course of time.

Why Emulate the SNES?

Well, there are many reasons for this. The main reason is for nostalgic purposes. In this day and age, it's hard to find an SNES and many good games. Plus, many of us over the course of time have lost our beloved consoles (may they R.I.P) but still have our original carts. With no other means to play them, we turn to emulators. Besides this there are many conveniences of doing this on the computer instead of dragging out your old system.

Advantages consist of :

ability to save in any location of the game, despite how the game was designed. It's amazingly useful when you don't want to redo the same level over and over.
built-in peripherals. This is anything from multi-taps, to super scopes, to cheat devices.
ability to rip sprites and music for your own personal use.
easier to organize and no stacks of cartridges.
filters can be used to enhance graphics and sounds on old games.

As with all things there are disadvantages though :

if you have an ancient computer, you aren't likely to get a playable experience.
some games are still unemulated (though this a very tiny minority.)
the emulator can be difficult for new users to configure.

Getting Started

Usage:

snes9x [options] <ROM image file>

Use -help option to see available options.

SNES ROM images come in lots of different formats. Snes9x supports zipped ROMs as long as there is only 1 per zip file. Also Snes9x can open gzip and jma compressed files.

Game Color System

By default, Snes9x displays the ROM information when a ROM is first loaded. Depending on the colors used you can tell whether or not a ROM is a good working ROM, or if it's been altered or is corrupted.

white	the ROM should be a perfect working copy.
green	the ROM is mode 1 interleaved.
orange	the ROM is mode 2 interleaved.
aqua	the ROM is Game Doctor 24M interleaved.
yellow	the ROM has probably been altered. Either it's a translation, PD ROM, hacked, or possibly a bad ROM. It may also be an overdumped ROM.
red	the ROM is definitely hacked and that a proper version should be exist. Some ROM Tools such as NSRT can also fix these ROMs.

When asking for help on the Snes9x forums, please list the color and CRC32 that is displayed. This will help to find out what the problem is.

These colors do NOT signify whether a game will work or not. It is just a means for reference so we can understand what may or may not be a problem. Most often the problem with games that don't work it's because they are corrupt or are a bad dump and should be redumped.

SNES Joypad Emulation

The default key mapping for joypad 1 is as follows:

U or Up	Up direction
J or Down	Down direction
H or Left	Left direction
K or Right	Right direction
D	A button
C	B button
S	X button
X	Y button
A	L button
Z	R button
Space	Select button
Return	Start button

And the default key mapping for joypad 2 is as follows:

Keypad 8	Up direction
Keypad 2	Down direction
Keypad 4	Left direction
Keypad 6	Right direction
Page Up	A button
Page Down	B button
Home	X button
End	Y button
Insert	L button
Delete	R button
Keypad +	Select button
Keypad Enter	Start button

Pausing and Quitting the Game

Don't forget how to pause the game and quit Snes9x.

ESC quits Snes9x.

Pause or Scroll Lock pauses the game.

Requirements

System Requirements

Relatively fast CPU like Pentium 2 or PowerPC G3 300MHz or higher, and 16MB memory or more.
Certain games use added hardware which will require a faster machine. The specs listed above is the minimum to use Snes9x in any playable form. It is recommended that you get a semi-modern machine with a 800MHz CPU if you want good results. A 1GHz CPU is recommended for those that want a near perfect experience.

X Window System with 15, 16, 24 or 32-bit color depth. For maximum emulation speed, have the X server switched to 15 or 16-bit.

Software

You will need access to SNES ROM images otherwise you will have nothing to run! Some home-brewed ROM images can be downloaded from http://www.zophar.com/.
Please note, it is illegal in most countries to have commercial ROM images without also owning the actual SNES ROM cartridges, and even then you may be liable under various EULAs.

Controllers Support

Input Devices

The real SNES has two ports to connect input devices. Usually 1P and 2P SNES joypads are connected but various devices and adopters can be plugged.

Use -port1 and/or -port2 options to specify which input device to be emulated in each port.

Multi Player 5	known as Multi Tap; a five player adapter, allowing up to five people to play at once on games that supported it.
SNES Mouse	a 2-button mouse, originally supplied with a paint program.
Super Scope	a light-gun; it used infrared to provide wireless communication between the gun and the console unit.
Justifier	a gun similar to Super Scope, supported with one gun-shooting game.

Snes9x can emulate those input devices with the keyboard and mouse. The default mapping is as follows:

Mouse Left	SNES Mouse Left button / SuperScope Fire button / Justifier trigger
Mouse Right	SNES Mouse Right button / SuperScope Cursor button / Justifier Start button
Mouse Center	when you want to shot offscreen, fire with pressing this button.
`	SuperScope Turbo toggle switch
/	SuperScope Pause button

Peripherals Support

Satellaview

Snes9x partially emulates Satellaview system, so-called BS-X. To play BS games or read BS magazines with the BS-X base cartridge, do the following.

If you have .srm files of BS games which were created by Snes9x 1.43 or earlier, trash them first.
Prepare the BS-X ROM image. Make sure the file is uncompressed and doesn't have a header.
Rename the BS-X ROM image to 'BS-X.bin'.
Put BS-X.bin in the proper directory. ~/.snes9x/bios by default.
Launch BS-X.bin as you usually play SNES games.
Set your name and gender.
Launch a BS game. The game is launched for the first time and its .srm doesn't exist, so BS-X.srm is loaded instead.
Once you launched the game, its .srm is created and loaded from the next time.

If you launch a BS game for the first time without BS-X.srm, maybe the game doesn't work properly.
To boot up BS games from BS-X town, use -bsxbootup option.

Sufami Turbo

To play Sufami Turbo games, do the following.

Prepare the Sufami Turbo base cartridge ROM image. Make sure the file is uncompressed and doesn't have a header.
Rename the base cartridge ROM image to 'STBIOS.bin'.
Put STBIOS.bin in the proper directory. ~/.snes9x/bios by default.
Use -multi, -carta and -cartb options to play games.

-multi

BIOS only

-multi -carta game1.smc

BIOS + game1.smc in Slot A

-multi -cartb game2.smc

BIOS + game2.smc in Slot B

-multi -carta game1.smc -cartb game2.smc

BIOS + game1.smc in Slot A + game2.smc in Slot B

Note that the base cartridge can initialize SRAM for only the game in slot A, so you have to set every game in slot A and launch at least once.
If no games are set in the slots, only the base cartridge runs.
If you have a combined ROM image, split it to each games and the base cartridge. NSRT will help you.

Other Multiple Cartridge Games

Use -multi option as follows:

-multi -carta maincart.smc -cartb addon.smc

Currently supported: Same Game

Game Saving

Many SNES games take a very long time to complete from start to finish, so they allowed your progress to be saved at the predefined places chosen by the game designers. The game cartridge contains a battery-backed RAM, known as SRAM, and your save data remain in this SRAM until the battery shutoff.

Snes9x has two methods for saving games. One is the same as of the real SNES shown above; emulating SRAM. The SRAM contents are saved into a file (.srm) so you don't need to be worried about the battery shutoff. The other is more convenient way than the real SNES; 'freezing' or 'snapshotting' the game. It means saving the whole game state anywhere you want, beyond the game designers' intent - ideal for saving your game just before a tricky bit!

Using the SRAM File

It's easy enough, just save the game as you do with the real SNES. Snes9x outputs the contents of the emulated SRAM into a file (.srm) when you load a new game or quit Snes9x. This file is automatically loaded the next time you play the game. Files are stored in ~/.snes9x/sram by default.

Freezing and Defrosting the Game State

Snes9x provides 9 slots for freezing the whole of your game state. During the game, press Shift + F1 to F9 to save the state, and just F1 to F9 to load it again later. Files are stored in ~/.snes9x/savestate by default.

Real-Time Clock Emulation

Some games have a battery-backed real-time clock (RTC) in their cartridge to bring a real-time event in the game. Snes9x saves the state of RTC into a file (.rtc), stored in ~/.snes9x/sram by default, and also into a freeze file.
Note that because it's a 'real-time' clock, when these files are loaded, the emulated clock is automatically advanced in reference to your system's time and date.

Fool-Proof System

If you quit the game by error without saving your long-time progress, try to press F10 key and find '.oops' file in the same directory as freeze files. It's a freeze file automatically generated if you don't save anything for a long time.

Cheat Support

Cheat codes allow you to cheat at games. They might give you more lives, infinite health, enable special powers normally only activated when a special item is found, and etc. Three major formats are well-known: Game Genie, Pro-Action Reply (PAR) and Gold Finger. Many existing codes can be found via Internet.

Snes9x supports all the three formats. Cheats are saved in .cht files and are automatically loaded the next time a game with the same filename is loaded.

Technically, a cheat code consists of two elements; an address in SNES memory map where you want to overwrite, and a value which is overwritten on the address.
Beware of cheat codes designed for a ROM from a different region compared to the one you are playing or for a different version of the ROM; the source of the cheats should tell you which region and for which version of the game they were designed for. If you use a code designed for a different region or version of your game, the game might crash or do other weird things because the cheat address might be different between regions and versions.

How to Enter Cheat Code

Use -gamegenie, -actionreplay and -goldfinger options to enter your cheat code. Files are stored in ~/.snes9x/cheat by default.

Movie Support

Movie support allows you to record your actions while playing a game. This can be used for your own personal playback or to show other people that you can do something without them having to be around when you did it.

Recording the Movie

Press Shift + 1 to begin recording and Shift + 2 to stop recording. Also you can use -recordmovie option to record from the start of the game.

Playing Back the Movie

Press Shift + 3 and enter the movie filename (.smv) to play the movie. Also you can use -playmovie option to play the movie recorded from the start of the game.

Miscellaneous

Where the Files are Stored

By default, ~/.snes9x is used to load/save files related to Snes9x. The subdirectories Snes9x refers to are as follows:

rom	ROM image files
sram	SRAM files (.srm), RTC files (.rtc)
savestate	freeze (snapshot, savestate) files
screenshot	screenshot files
spc	SPC files (.spc)
cheat	cheat files (.cht)
patch	IPS files (.ips)
bios	BIOS image files

Using IPS or UPS Patch

Snes9x automatically patches without overwriting the ROM image.

Put the IPS or UPS file into the proper directory. ~/.snes9x/patch by default.
Rename the name to the same as the ROM image (except extension, it is '.ips' or '.ups').
(IPS only) If you want to use multiple IPS files at a time, set their extensions to '.000.ips', '.001.ips', ...
Open and load the ROM image.

SPC File Dumping

SPC file (.spc) is the freeze state of only sound part, so it is known as SNES music data file. Dump the SPC file by Snes9x and play the file by SPC players.

Press Alt/Control + F1 to dump a SPC file. It's stored in ~/.snes9x/spc by default.
Note that the actual dumping occurs at the next note-on event so that you can dump the BGM from just the beginning.

Additional Keyboard Controls

Snes9x has various functions to play games with fun. The default mapping is as follows:

Control + Shift + ESC	hardware reset as you turn off and on the power switch.
Shift + ESC	software reset as you press the reset button.
F12	saves the freeze file you specify.
F11	loads the freeze file you specify.
Shift + F1-F9	quickly saves a freeze file into the slot 1-9.
F1-F9	quickly loads a freeze file from the slot 1-9.
F10	tries to load the fool-proof freeze file you specify.
Alt/Control + F1	dumps a SPC file.
Print Screen	takes a screenshot.
Shift + 1	begins recording a movie.
Shift + 2	ends recording a movie.
Shift + 3	plays the movie you specify.
Tab	turbo mode while pressing.
Shift + Tab	toggles turbo mode on/off.
=	increases frame skip rate / switches to auto-frame rate adjustment.
-	decreases frame skip rate / switches to auto-frame rate adjustment.
Shift + =	increases frame time in 1ms steps: works only with auto-frame rate adjustment.
Shift + -	decreases frame time in 1ms steps: works only with auto-frame rate adjustment.
Alt + =	increases frame skip rate in turbo mode.
Alt + -	decreases frame skip rate in turbo mode.
Control + =	increases speed in turbo mode.
Control + -	decreases speed in turbo mode.
6	toggles swapping of joypad one and two.
Alt/Control + F4-F11	toggles sound channel 1-8 on/off.
Alt/Control + F12	enables all sound channels.
1-4	toggles background 1-4 on/off.
5	toggles sprites on/off.
9	(not recommended) toggles transparency effects on/off.
Backspace	(not recommended) toggles emulation of graphics window effects on/off.
0	(not recommended) toggles H-DMA emulation on/off.

Gamepad Support

The Linux port makes use of the v1.x joystick kernel drivers written by Vojtech Pavlik to allow the use of a wide variety of different gamepad types to control SNES games.
If you are still using the older versions of the drivers, you can download the latest driver version from http://atrey.karlin.mff.cuni.cz/~vojtech/joystick/.
Refer to the documentation that comes with the drivers to enable support for your type of gamepad in Snes9x.

Configuring Settings and Key Mapping

The Unix port of Snes9x reads the preferences file snes9x.conf when launching, if it exists.
To make your snes9x.conf, copy the template file snes9x.conf.default, rename it to 'snes9x.conf', put it in the proper directory (~/.snes9x by default), and edit it as you like. The document control-inputs.txt will help you to edit the keyboard/gamepad mapping.

Building Snes9x from Source

The source release of Snes9x comes with a configure file that will try to make a Makefile suitable for your system. To invoke it go into the snes9x/unix directory inside the distribution:

cd snes9x-1.xx-src/snes9x/unix

Then run configure and finish with running make if it went well.

./configure make

configure takes several arguments. Further documentation about this is available by running ./configure --help.

Compatibility

Compatibility with Other Ports

All the files generated by Snes9x are compatible between platforms, except for the extension of the freeze files.

Compatibility with Other SNES Emulators

Cheat files (.cht) are common between Snes9x and ZSNES. RTC files (.rtc) are common between Snes9x and bsnes. SRAM files (.srm) should be common among all SNES emulators.

Problems

Problems with ROMs

If Snes9x just displays a black screen for over 10 seconds after you've loaded a ROM image, then one of the following could be true:

You just loaded some random ROM image and it isn't even a SNES game or you only have part of the image. Snes9x only emulates games designed for the Super NES, not NES, or Master System, or Game Boy, or <insert your favorite old games system here>.
Someone has edited the Nintendo ROM information area inside the ROM image and Snes9x can't work out what format the ROM image is in. Try playing around with the ROM format options.
The ROM image is corrupt. If you're loading from CD, I know it might sound silly, but is the CD dirty? Clean, unhacked ROM images will display [checksum ok] when first loaded, corrupt or hacked ROMs display [bad checksum].
The original SNES ROM cartridge had additional hardware inside that is not emulated yet and might never be.
You might be using a file that is compressed in a way Snes9x does not understand.

The following ROMs are known to currently not to work with any version of Snes9x:

SD Gundam GX DSP-3

Hayazashi Nidan Morita Shougi Seta-11

Hayazashi Nidan Morita Shougi 2 Seta-18

Problems with Sounds

If you hear crackling noise during the game, try these options to eliminate the noise.

-buffersize

Sound generating buffer size in millisecond. Larger value will be safe from crackling noise, but may cause lag.

-fragmentsize

Fragment size of the system sound driver in byte. It must be a power of 2, and must be the value the driver accepts.

-soundsync

When this option is on, Snes9x tries and ensures all available samples are buffered so there are no overruns.

-inputrate

Adjusts the sound rate through resampling. For every -inputrate samples generated by the SNES, -playbackrate samples will be produced.

Technical Information

What's Emulated?

65c816 main CPU.
Variable length machine cycles.
8 channel DMA and H-DMA.
H-IRQ, V-IRQ and NMI.
Sony SPC700 sound CPU.
Sound DSP, with eight 16-bit, stereo channels, compressed samples, hardware envelope processing, echo, pitch modulation and digital FIR sound filter.
SRAM, a battery-backed RAM.
All background modes, 0 to 7.
All screen resolutions including interlace mode.
Pseudo hi-res mode.
8x8, 16x8 and 16x16 tile sizes, flipped in either direction.
32x32, 32x64, 64x32 and 64x64 screen tile sizes.
Vertical and horizontal offset-per-tile.
128 8x8, 16x16, 32x32 and 64x64 sprites, flipped in either direction.
Sub-screen and fixed color blending effects.
Mosaic effects.
Mode 7 screen rotation, scaling and screen flipping.
Single and dual graphic clip windows, with all four logic combination modes.
Color blending effects only inside or outside a window.
Palette changes during frame.
Direct color mode - uses tile and palette-group data directly as RGB value.
SNES Mouse.
Super Scope, emulated using computer mouse.
Justifier, by Konami, similar to the Super Scope and used only in Lethal Enforcers.
Multi Player 5, allowing up to five people to play games simultaneously on games that support that many players.
Super FX, a fast RISC CPU used in several games.
SA-1, a faster version of main CPU with some functions, used in several games.
DSP-1, a custom chip used in several games, mainly racing games.
DSP-2, a custom chip used only in Dungeon Master.
DSP-4, a custom chip used only in Top Gear 3000.
C4, a sprite scaler/rotator/line drawer/simple maths co-processor chip used only in Megaman X2 and X3.
Seta-10, a custom chip used only in F1 Race of Champions 2.
OBC1, a sprite management chip used only in Metal Combat.
S-DD1, a data decompression chip used only in Star Ocean and Street Fighter 2 Alpha.
SPC7110, similar in use to S-DD1, used in a few Hadoson games.
S-RTC, a real-time clock chip, used only in Dai Kaijyu Monogatari 2.
Satellaview and BS-X, only partially.

What's Not?

Exact sub-cycle timings of communication among most of parts - main CPU, sound CPU, DMA, H-DMA, IRQ, NMI, and so on. Snes9x cannot run games that require severe timings!
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. (DSP-3, Seta-11 and Seta-18, as examples)
The expansion slot found in many carts.

Custom Chips

Super FX

The Super FX is a 10.5/21MHz RISC CPU developed by Argonaut Software used as a game enhancer by several game titles. Released SNES Super FX games included Yoshi's Island, Doom, Winter Gold, Dirt Trax FX, StarFox, Stunt Race FX and Vortex.

SA-1

The SA-1 is a fast, custom 65c816 8/16-bit processor, the same as inside the SNES itself, but clocked at 10MHz compared to a maximum of 3.58MHz for the CPU inside the SNES. The SA-1 isn't just a CPU; it also contains some extra circuits developed by Nintendo which includes some very fast RAM, a memory mapper, DMA and, several real-time timers.

C4

The C4 is custom Capcom chip used only in the Megaman X2 and Megaman X3 games. It can scale and rotate images, draw line-vector objects and do some simple maths to rotate them.

S-DD1

The S-DD1 is a custom data decompression chip that can decompress data in real-time as the SNES DMA's data from the ROM to RAM. Only two games use the chip: Star Ocean and Street Fighter Alpha 2.

SPC7110

The SPC7110 is a compression and memory mapping chip. It provides a few extra features as well. It functions as an RTC interface, and has a multiply/divide unit that has more precision than the SNES. The SPC7110 is found only in 4 games: Super Power League 4, Far East of Eden Zero, Far East of Eden Zero - Shounen Jump no Shou and Momotaro Dentetsu Happy.

Others

Other known custom chips: DSP-1, DSP-2, DSP-3, DSP-4, Seta-10, Seta-11, Seta-18, OBC1 and S-RTC.

Credits

Jerremy Koot for all his hard work on previous versions of Snes96, Snes97 and Snes9x.
Ivar for the original Super FX C emulation, DSP-1 emulation work and information on both chips.
zsKnight and _Demo_ for the Intel Super FX assembler, DSP-1 and C4 emulation code.
zsKnight and _Demo_ for all the other ideas and code I've nicked off them; they've nicked lots of my ideas and information too!
John Weidman and Darkforce for the S-RTC emulation information and code.
Kreed and Maxim Stepin for excellent image enhancer routines.
Nose000 for code changes to support various Japanese SNES games.
Neill Corlett for the IPS patching support code.
DiskDude's SNES Kart v1.6 document for the Game Genie(TM) 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.
Vojtech Pavlik for the Linux joystick driver patches.
Maciej Babinski for the basics of Linux's DGA X server extensions.
Alexander Larsson for the GGI Linux port code.
Harald Fielker for the original sound interpolation code (never used directly due to problems).
Takehiro TOMINAGA for many speed up suggestions and bug fixes.
Predicador for the Windows icon.
Lindsey Dubb for the mode 7 bi-linear filter code and the improved color addition and subtraction code.
Anti Resonance for his super-human efforts to help get his fast sound CPU core and sound DSP core working in Snes9x.
Brad Martin and TRAC for better and refined sound emulation.
ernstp and entonne for patches and testing on Linux PPC.
byuu for the most exact timing information and tons of the newest technical findings.
Blargg for the most accurate timings between sound CPU and DSP and exact sound emulation codes.
pagefault, TRAC, Dark Force, byuu, and others who have donated ideas and/or code to the project.

Nintendo is a trademark.
Super NES, Super Famicon, Super Scope and Super FX are trademarks of Nintendo.
Sufami Turbo is a trademark of Bandai Co., Ltd.
Game Genie is a trademark of Lewis Galoob Toys, Inc.
Pro Action Replay is a trademark of Datel Inc.
Macintosh, Mac and Mac OS X are trademarks of Apple Computer, Inc.
UNIX is a trademark of The Open Group.
Linux is a trademark of Linus Torvalds.
Windows is a trademark of Microsoft Corp.
Intel is a trademark of Intel Corp.
PowerPC is a trademark of International Business Machines Corp.
Sony is a trademark of Sony Corp.
Konami and Justifier are trademarks of Konami Corp.
Hudson is a trademark of Husdon Soft Co., Ltd.
Capcom is a trademark of Capcom Co., Ltd.

Gary Henderson

Edited for Unix port by: zones (kasumitokoduck@yahoo.com)
Updated most recently by: 2011/04/10 zones

SD Gundam GX	DSP-3
Hayazashi Nidan Morita Shougi	Seta-11
Hayazashi Nidan Morita Shougi 2	Seta-18