bsnes :: User Guide
Frequently Asked Questions
Why can't bsnes see any of my ROM images? - you need to use snespurify first. See the "Getting Started" section below.
Why can't bsnes or snespurify see my ZIP'ped ROMs? - bsnes does not support compressed ROMs. You must decompress them first.
How do I enter fullscreen mode? - by default, press F11 toggle fullscreen on and off.
My video tears and/or my audio crackles! - first, make sure your system meeets the bsnes system requirements. Second, read the audio settings "frequency" information section below.
How can I make bsnes always start in fullscreen mode? - set settings.startFullScreen to true in bsnes.cfg. See the bottom of the article for more info.
How do I use the Mouse / Super Scope / Justifier(s)? - you must capture the mouse. By default, press F12 to toggle mouse capture.
How can I map hotkeys? - go to Settings->Configuration Settings, choose Input, and select Hotkeys from the Port drop-down box.
When I'm using bsnes, I can't see any windows! - delete geometry.cfg from the configuration settings folder. See the bottom of the article for more info.
My save states aren't compatible between versions! - unlike save RAM, save states contain internal emulation state, which changes as the emulator evolves.
Loading a save state overwrites my save RAM! - save RAM is part of the system state. Some games use it as work RAM, and will crash if it is not preserved. You will have to exercise caution when utilizing save states with RPGs and the like.
Accuracy vs Compatibility profiles
bsnes operates in two modes.
Accuracy uses a pixel-based renderer, which is required to properly emulates effects such as the plane shadow from Air Strike Patrol. However, it is almost twice as slow as the compatibility profile.
Compatibility uses a scanline-based renderer, which works with 99.9% of games, and is much faster than the accuracy profile.
The 64-bit Windows binary uses the accuracy profile, because the 64-bit compilation adds an additional 15% speedup, and anyone meeting its system requirements should have a 64-bit system anyway.
The 32-bit Windows binary uses the compatibility profile, because lower-end systems may not have 64-bit processors. If your 64-bit system is not fast enough for the accuracy profile, use this version.
Performance is a special third profile, which sacrifies a large degree of accuracy in return for running nearly twice as fast as the compatibility profile. However, due to the nature of bsnes targeting accuracy, I do not distribute pre-compiled builds of this profile. You must build it yourself from source. See the compilation guide for instructions on how to do this.
Getting Started
bsnes is not like other emulators. It is designed to promote preservation, and thus does not cater to antiquated file formats nor needless complexity. In the short term, this unfortunately means that many users will have to clean their ROM images prior to using bsnes. In the long term, it will hopefully ensure unification to a single, clean standard.
Most predominantly, this means that compressed archives (eg ZIP files), copier headers, the Super Magicom (SMC) extension, and IPS patches are not supported.
Compressed Archives
First, if your ROM images are compressed, you must first decompress them. To do this, go to your ROM folder, select all of them (Ctrl+A), right-click, and choose to "extract all here."
It's up to you if you wish to keep the compressed versions as well.
Cleaning SNES ROM images
The easiest way to proceed is to utilize snespurify to clean all of your ROMs at once. snespurify will remove copier headers, correct file extensions to Super Famicom (SFC), and convert IPS patches to the UPS file format used by bsnes.
snespurify is distributed with bsnes. For Windows users, a pre-compiled binary is included in the same folder as the bsnes executable. Run this application:
First, choose browse. Select the folder that your decompressed ROM images are stored in. Now hit scan. snespurify will validate all of your ROM images, and alert you of any changes that it needs to make in the list below. Finally, click the correct button at the bottom right, and all of your ROMs will be fixed.
All set!
You are now ready to use these images with bsnes! I apologize that you, the end user, have to go through the above steps first. Hopefully in time, ROM image sets will be distributed cleanly, and the above steps will be unnecessary.
Main Window
Upon starting bsnes, you will be greeted with the main emulation window:
There is a menubar at the top. Note that to close the emulator, you would use the close icon on the titlebar, as there is not an exit entry under the system menu.
The video output appears in the center.
Lastly, there is a status bar along the bottom that serves many purposes. It will inform you of the state of the emulator, the frame rate while running applications, and it will display messages when various actions are taken.
System
Load Cartridge will allow you to load an SNES ROM image.
Load Special will allow you to load an SNES cartridge that takes additional sub-cartridges. This includes the BS-X and BS-X slotted cartridges, which take BS-X flash pack (BS) files, the Sufami Turbo which takes individual Sufami Turbo (ST) games, and the Super Game Boy, which takes individual Game Boy (GB) and certain Game Boy Color (GBC) cartridges.
Note that only the black Game Boy Color cartridges, which are compatible with the original monochrome Game Boy, are playable. The clear Game Boy Color cartridges will not work on the Super Game Boy, and consequently, will not work in bsnes.
Power Cycle will simulate turning the SNES off and back on again, which will flush any high scores saved in RAM.
Reset will simulate a simple system reset, which leaves RAM intact, and will sometimes skip over certain splash screens.
Controller Port 1 and Controller Port 2 will allow you to choose which controllers should be emulated in their respective ports, if any.
The Mouse, Super Scope, and Justifiers require the host mouse to be captured before they can be used. Mouse capture toggle defaults to the F12 key, although this can be configured via the input settings -> hotkeys window.
Settings
Video Mode allows you to control how the main video output is presented.
You can choose to scale the video size up to 5x its original height.
You can choose whether or not to correct the aspect ratio. A TV displays the SNES video as 4:3, whereas on a monitor with square pixels, the image is not in fact 4:3 anymore, but is a bit taller. Without this option on, characters will appear skinnier than they should, circles will look like ovals, etc.
You can choose whether or not to smooth the video output. Leaving this on will blur the image when scaling, whereas leaving this off will result in pixellated scaling.
You can choose your TV region, either NTSC or PAL. NTSC shows only 224 scanlines, whereas PAL shows all 239 scanlines, and has a wider aspect ratio. Since virtually no NTSC games use the extra scanlines, you will end up with black bars in these games if you use PAL mode. Inversely, some PAL games will have part of their images cut off if you use NTSC mode. Note that this setting only controls the TV output mode, and not which system is emulated. bsnes will automatically choose whether to emulate an NTSC or PAL SNES console.
Video Filter will allow you to choose a software filter to be applied to the image prior to display. Filters are located inside the folder named "filters", which can be found in the same folder as the bsnes binary, or in the bsnes configuration file folder.
Video Shader will allow you to choose a pixel shader to applied to the post-filtered image prior to display. Shaders are located inside the folder named "shaders", which will be in the same location as the filter folder.
Note that this option will not appear if your video card or selected video driver does not support pixel shaders.
Synchronize Video allows you to synchronize the video output to the vertical refresh rate of your monitor, resulting in a smooth scrolling image.
Synchronize Audio allows you to synchronize the audio output to the sample rate of your sound card, resulting in crackle-free audio.
You can enable one or the other, both, or none. With neither enabled, emulation will run as fast as possible on your system, as it has no way to throttle speed. If you enable both, the two will compete with one another, and you may sometimes get video stuttering, audio crackling, or both. You will need to adjust the audio input frequency, explained below, in order to ensure that both operate smoothly.
Mute Audio allows you to silence the audio output.
Configuration Settings allow you to control various settings, which are detailed below.
Tools
Save State and Load State allow you to capture quick save states that can be loaded and restored at will. They act as universal save points that work in any game.
Capture Screenshot will allow you to save a screenshot of the post-filtered, yet pre-shaded and pre-scaled video output. By default, these images will be time-stamped, and saved to the same folder as the ROM image itself.
Cheat Editor allows you to enter Game Genie and Pro Action Replay cheat codes. This is discussed further below.
State Manager is a tool to allow long-term storage of save states. You can give these state files unique descriptions, and keep them organized. This is discussed further below.
Load Cartridge
bsnes uses a custom load file dialog, which is done both for consistency, and to support a special cartridge-folder approach.
Using the dialog is easy: click the "..." button to browse for a specific folder using the OS native folder browse box. Or use the ".." button to go up a single folder. Folders end in "/", and you can double-click them to enter their respective folders. To load a file, simply double-click it.
You can also manually type in a folder path into the text box at the top, pressing enter to select it.
bsnes will remember the last folder path you were in upon loading a cartridge successfully. It will even remember the position in the file list within the same instance of the program.
Cartridge-Folders
bsnes will allow you to treat folders as "complete cartridges." Think of Mac OS X's ".app" bundles. They are really folders with many individual files, but they appear to be a single file that acts as a program. bsnes works similarly.
Folders ending in ".sfc" act as cartridge folders. Upon double-clicking them, bsnes will load them directly, so that you don't need to go inside the folder to load the ROM file. Further, all related data for this game: save RAM, RTC data, cheat codes, save states, etc; will be saved right into this folder. When you want to move your game to another PC, simply copy the whole folder along with you. All of your saved information will go with it, just like a real cartridge!
Load Special
For SNES cartridges that have slots for other cartridges, you must use the load special dialogs. These allow you to select the base cartridge, and each individual slot cartridge, if any.
Click the "..." button to select a file for each slot. The base cartridge must be specified at the very least, as it's not physically possibly to only plug a slot-cartridge into a real SNES deck. Hit ok to load the cartridge.
Note that for the BS-X, Sufami Turbo, and Super Game Boy, bsnes will remember the path to the base cartridge, so that you only have to select it once.
Also note that bsnes will remember the paths to each type of file separately. BS images, ST images, and GB/GBC images all remember paths individually, so that you can keep your images in separate folders.
Configuration Settings - Video
Enable NTSC gamma ramp simulation enables an approximation of the gamma observed on a CRT television, which is darker than the image displayed on LCD monitor. Leaving this option on will result in more authentic colors, assuming you have a decent LCD monitor. If the image appears too dark for you, you can turn this option off. However, colors may appear washed out after doing so.
Fullscreen allows you to toggle how the image is scaled when you are in fullscreen mode.
Center will scale the image as much as possible, while keeping an even multiple of the image height. This is the ideal setting if you use scanlines, or pixellated video output, as otherwise the pixels will not be of uniform height, and look rather awful. However, you will end up with black bars not only on the left and right, but on the top and bottom of the image, as well.
Scale will fill the entire height of your monitor, at the cost of losing an even video multiplier. This option should be used with smooth video enabled, and no scanline filter applied. You will still have black bars on the left and right side of your monitor, if you are using a widescreen monitor.
Stretch will fill the entire monitor, leaving no black bars anywhere. However, on widescreen monitors, it will completely destroy the aspect ratio. Characters will appear extremely fat, and scrolling will be heavily distorted. This option should only be used on 4:3 monitors running at 1280x1024 resolution, as this is a custom PC resolution that uses non-square pixels, and this option will result in a clean image here. If you care at all about image quality, do not use this for any other reason.
Configuration Settings - Audio
Volume will allow you to modify the default volume level. Note that setting this value above 100% may result in audio being clamped, causing some signal degradation. 200% in this case indicates that the volume will be twice as loud as it should be.
The reason I allow for volume going over 100% is because SNES audio output volume is traditionally extremely low. Without raising it, you will have to keep adjusting your PC speaker volume to compensate for the loudness difference between bsnes and other applications, such as audio players.
Frequency is a very difficult option to explain.
The premise is that SNES video outputs at ~60.09hz in NTSC mode, and ~50hz in PAL mode. SNES audio outputs at ~32040hz. PC monitors vary. Even if you set your monitor to 60hz, it is most likely running somewhere between 59hz and 61hz. PC audio is the same. Even at 32000hz, it's most likely somewhere between ~31950hz and ~32050hz. This is because these sorts of things have built-in tolerances to work with different hardware configurations. Worst of all, it is virtually impossible to auto-detect the exact rates of your monitor and sound card, as they will lie and claim to be 60z and 32000hz, respectively.
Since bsnes is an accuracy-focused emulator, it will never attempt to distort emulation speeds to generate samples on demand, nor will it ever drop or duplicate video frames intentionally.
Emulators that "just work" utilize the former, and this is why they produce inferior audio, especially with regards to sound effects in games like Super Mario World. Some other emulators will forcefully show or drop an extra video frame every ~10 seconds or to compensate, which produces clean audio, yet causes jarring jumps on scrolling scenes.
bsnes is much harder to set up, but allows you to have perfect video and audio at the same time.
Put simply, frequency is the output rate for audio to your PC sound card. It will take the 32040hz audio input from the SNES, and scale it to the requested frequency value.
By adjusting this value, you will cause infinitesimal shifts in pitch in the audio, which is regrettably completely unavoidable. But this will allow you to align your video and audio to perfectly match the rates of your hardware, resulting in smooth scrolling and clean audio.
To use this, all you need to consider is that moving the value in one direction will help eliminate video stuttering, but will increase audio crackling. Moving it in the other direction will help eliminate audio crackling, but will increase video stuttering. Keep moving this back and forth, in a balancing act, and you can reach a value that will eliminate both: a perfect harmony.
It is best to set the emulator to ignore input when inactive, that way you can adjust this value while the emulator is running.
If this option proves ineffective, you might also consider disabling the window compositor as well, which will help even more with video synchronization issues.
Note that this option is pointless unless you have both synchronize video and synchronize audio enabled at the same time.
Configuration Settings - Input
Here, you can map keyboard, mouse and gamepad keys to simulated controllers.
Port allows you to choose which controller port to configure, and Device allows you to choose which device on said port to configure.
To map an input setting, double-click an item in the list box, and press the key you wish to map. Buttons will appear that allow you to map to mouse axes or buttons, depending upon the input type, which you can optionally click instead. You can also press clear, or hit the Escape key, to erase the mapping for this key.
The status bar at the bottom of the configuration window will inform you when you need to press a key for mapping. Also, when using joypads with analog axes or analog buttons, a calibration window will pop up when you first try and map it. It will advise you move or press all analog inputs, let go of the gamepad, and then press okay. Doing this helps to ensure axes are detected as axes, and analog buttons are detected as analog buttons — information that is not provided by current input polling APIs such as DirectInput and SDL.
Configuration Settings - Hotkeys
At the bottom of the port combo box, there is an option to map hotkeys. These are shortcuts for common GUI operations. In this mode, the device combo box acts as a hotkey sub-specifier. Right now, there is only "General" here.
This works exactly the same as the controller port mapping functionality explained above.
Configuration Settings - Advanced
Here, you can configure the driver APIs used by bsnes. Note that if you change these driver settings, you must restart bsnes for the changes to take effect. bsnes will not attempt to change them in real-time, because that may prove dangerous while you are playing a game that you may not have saved in recently.
The focus settings allow you to configure what bsnes does when the main video window loses focus. Pause emulator will freeze the emulator, not allowing gameplay to progress. Ignore input will allow the game to keep running in the background, but will ignore all input. Use this if you wish to multi-task, and are using a keyboard to play games. Allow input will let the input go through even if the window is inactive. Use this if you wish to multi-task, and are using a gamepad to play games. Note that hotkeys will never go through unless the main window is active.
You can choose to disable the desktop window compositor as well. Compositors are what allow Windows Vista and above to show the translucent Aero glass theme, allowing you to see windows underneath the title bars; and allows Compiz to do all of its fancy tricks under Linux. Unfortunately, both Windows and Linux ship with horribly broken, defective designs for compositors, and they compete with APIs such as OpenGL to capture Vblank.
With a compositor and bsnes Vsync enabled at the same time, you may notice that roughly every other frame is lost entirely. Thus, bsnes provides you with options to disable the compositor.
Never will leave your compositor setting alone. Fullscreen will make sure it is off when you enter fullscreen mode, and if you had it on before, it will turn it back on when you exit fullscreen mode. Always will turn the compositor off as soon as you open bsnes, and will leave it off until you close bsnes. If you are not using a compositor at all, these options will have no effect.
Note that this option only works with the Windows and Xfce compositors. It will have no effect with other compositors, such as those used by Gnome and KDE on Linux.
Cheat Editor
Here, you can enter cheat codes in Game Genie or Pro Action Replay format. Note that each cheat code can contain multi-part cheat codes, separated by the "+" symbol. You can give each code a description, and you can use any character from UTF-8, so they do not have to be English descriptions.
You can toggle codes on and off in real-time with the checkboxes along the left-hand side.
Find Codes ... will use the included cheats.xml database to try and find any previously known cheat codes for the game you are playing. This will save you the trouble of searching the internet for shady adware-ridden websites to find codes that may or may not work for your particular region and revision of a particular game. If any are found, you'll be presented with the below window.
Cheat Database
Here, cheats were found for the game, "Legend of Zelda - A Link to the Past."
You can check any cheats that you would like to use, and click ok. These will then be appended to the end of your personal cheat code list.
State Manager
Ever find yourself not remembering what "state 3" was for? Ever want to save a state before each boss fight in a game, to quickly jump back to that part again? Or just wanted to have your own home-made level select for a game that lacks such functionality? Well, now you can!
The state managers allows you to save states with a sense of permanence, allowing you to assign each one a unique description. All of these are saved into a single state archive file.
Configuration Files
Configuration files store additional settings for advanced users. You can find these files on Windows by pressing Win+R, or going to Start->Run, and typing in "%appdata%/bsnes" and pressing enter. From Linux, navigate to "~/.config/bsnes".
You can edit all configuration files by opening them up in your text editor of choice. Notepad2, Mousepad and gedit all work fine.
Note that you can also set up bsnes in multi-user / portable mode: create empty versions of any of the below text files in the same folder as the bsnes executable, and bsnes will use these files instead. The files will be auto-populated after running bsnes once after creating them.
bsnes.cfg
This file stores all of the basic configuration settings.
settings.startFullScreen will allow you to start bsnes in fullscreen mode. I'd strongly suggest mapping the "Exit Emulator" hotkey, and remembering what the hotkey is to exit fullscreen mode, if you use this setting. This should only be used for people using frontends such as XBMC.
paths.cfg
This file will allow you to override where all of the various files are saved. By default, all data will be saved in the same folder as the ROM image you have loaded. But if you want all of your save RAM files to be saved to a specific folder for easier backup, then set the "srm" path in this file to where you want them to go.
geometry.cfg
This file remembers the window positions and sizes of every window from the application. That way, the next time you run bsnes, your windows appear exactly where you left them.
Note that in rare circumstances, this file can get corrupted. If you find yourself unable to see certain windows, you can delete this file and re-run bsnes afterward. You can also make this file read-only when you are happy with your window placements, and bsnes will always use those coordinates from then on.
cheats.xml
This is the database of all known cheat codes for all known games. This database is provided by mightymo, and can be freely updated if you like.