Nestopia Documentation

version 1.35
last updated November 6, 2006

Homepage: http://nestopia.sourceforge.net/
Mail: martin-freij at home.se

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Table of Contents

• Introduction
• Features
• System Requirements
• Getting Started
• Troubleshooting
• Credits

For recent changes refer to the changelog.txt file.

Introduction

Nestopia is a portable open source NES/Famicom emulator written in C++. It's designed to be as accurate as possible and supports a large number of peripherals. The hardware is emulated at cycle-by-cycle granularity, ensuring full support for software that do mid-scanline and other timing trickery. The emulation core has been carefully made to conform to the C++98 standard and any decent compiler should be able to compile it without any hassle. To ease the process of porting the emulator to a platform of choice, the core provides a set of API classes.

Back to Top

Features

Boards (not mapper-assigned)

• 603-5052
• 64-in-1 NoRepeat
• 8157 4/20-in-1
• A65AS
• CC-21
• DreamTech 01
• Edu2000
• FK23C
• Kof97
• Street Heroes
• Super 24-in-1
• Super Game 8237
• T-262
• WS 40-in-1

Sound Chips

• MMC5
• NAMCOT 106/163
• RP2C33 (FDS)
• SUNSOFT5B
• VRC6
• VRC7

Controllers

• Standard Pad
• Light Gun (1)
• Family BASIC Keyboard
• Subor Keyboard + Mouse
• Doremikko Keyboard
• Hori Track (1)
• Pachinko Controller (2)
• Family Trainer Mat / Power Pad
• Family Computer Robot / R.O.B
• Arkanoid Paddle (1)
• Oeka Kids Tablet (1)
• Hyper Shot
• Crazy Climber Stick
• Mahjong Controller
• Exciting Boxing Bop Bag
• Top Rider Bike
• Pokkun Moguraa Tap-tap Mat
• Party Tap

    (1) With mouse
    (2) With mouse wheel

Other Peripherals

• Bandai Karaoke Studio
• Barcode Battler
• Data Recorder
• Datach Joint ROM System
• Famicom Disk System
• Game Genie & Pro Action Rocky
• Turbo File
• VS.UniSystem

Extras

• Savestates / Saveslots
• Png/Jpeg/Bmp File Screenshots
• Movie/Avi File Recording
• Wave File Recording
• Zip/Rar/7zip Archive Support
• On-the-fly IPS Patching
• Netplay
• NSF Player
• Video Filters including NTSC video emulation
• Real-time Rewinding
• Cheat Searching
• Database for correcting bad file-headers
• Game Configuration Files
• File Launcher
• Palette Editor
• iNes File Header Editor

Mappers (fully or partially)

..that renders a total of 194.

Recognized VS UniSystem Games

Games with Sound Sample Support

Samples must be in MS Wave format and use indexed naming convention, i.e 00.wav, 01.wav and so on.
The compression format may be zip, rar or 7zip. The archives must be placed in the directory specified
in the Paths Settings (defaulted to .\Samples).

Mappers/Boards with Reset-based or DIP Switch Settings

• 43, 57, 60, 83, 90, 105, 209, 211, 230, 233, 236
• UNIF Boards: 8157, FK23C, StreetHeroes
• Family BASIC, Playbox BASIC

Back to Top

System Requirements

(1) With this spec you should expect nothing but turtle speed.
(2) Win98/Me users need to obtain the Unicode Layer DLL (unicows.dll) from the Microsoft site and place it in the same directory as Nestopia. It can be downloaded from here.

Back to Top

Getting Started

NES / Famicom Console

Supported cartridge formats are .nes and .unif. To get beyond the limitation of the .nes format Nestopia maintains an internal database that will attempt to fix incorrect headers as well as provide necessary info for certain cartridge types. No changes are made to the physical file. This feature can be disabled in the preferences dialog.

Non-volatile save data is managed by Nestopia as needed. The save data is usually an 8K sized chunk of battery-backed RAM which when in use, will be placed in a default or user defined directory. It's possible to instruct Nestopia not to save the data through an option in the paths dialog, thus making it read-only.

Famicom Disk System

Supported disk formats are .fds and raw files. In order to run FDS software a valid BIOS ROM file in either a .nes or a raw format is required. During application startup Nestopia performs a search in various directories for it by the name "disksys.rom". If none was found you have to open the FDS dialog and set the file path yourself.

You can select between three options that let you choose how changes to disk files should be handled. The default and prefered way to handle it is through the use of IPS files. Any data that was changed during a gaming session is saved and put into a default or user defined directory. The next time the game is loaded Nestopia will locate this IPS file and use it to patch the original disk file in memory. This method however, is not garuanteed to work if the disk file has been altered between saves unknowingly to Nestopia, by for example another emulator. The second option will simply make the changes directly to the disk file. Be aware that this method is unsafe and can if you're extremely unlucky, cause the disk file to become corrupted. Possible reasons could be I/O error, system crash, in-game bug etc. The last option simply disables disk file saving altogether.

Save States / Movies

Whenever a game is running its current state can be captured and saved into a file enabling you to resume your game at a later time. Also available are 9 quick save slots which are automatically managed by Nestopia. Unless you disable the auto import/export to files option in the paths dialog the save slots will be saved to/loaded from files with the same name as the game file - i.e, nighthawk.nes will save them as nighthawk.ns1..nighthawk.ns9.

Nestopia is capable of recording movies by listening to the NES I/O ports collecting any data that gets transmitted from any connected input devices to the CPU. During playback the recorded data stream is then fed to the CPU whenever it makes a read from one of the I/O ports. Available commands are play, record, stop, rewind and forward.

As of version 1.20 these two file formats have gone through a major overhaul and as a result, the old formats will no longer work with new versions of Nestopia. The files are chunk based and uses (unless disabled by the user) internal compression with the help of ZLib. The file extensions for the state and movie files are .nst respective .nsv.

Image Patching

Nestopia can apply IPS patching on all the supported image file formats. By making the changes in memory your physical files will remain intact. There are several ways to apply the patching. Either you can just open the IPS file and apply it on a game currently running, in which case a power-reset will be made. Another option is to enable Nestopia to look for it when a game is loaded and have the patch applied automatically.

Cheats

The cheat dialog provides two tables for cheat codes. Codes listed in the "temporary codes" table will get flushed once a game has been unloaded. This is useful if you're trying out codes but later forget to remove or disable them, causing the next game you load to misbehave due to the codes still being in use. Codes listed in the "static codes" table will be preserved at all time, even after the application is closed.

Cheat codes can be submitted in two different ways. Either by providing the address, data and compare bytes explicitly; or through the Game Genie / Pro Action Rocky method with the values packed and encoded into a 6-8 character string.

The cheat searcher is another recently added feature that can help you locate and modify in-game-data values inside the CPU RAM. It could be the number of lives, money, weapons, basically anything that a game reads/writes in that region. The way it works is that the cheat dialog shows you two different states of the CPU RAM; one with the content at the time you hit the reset button or opened the dialog for the first time after a new game was started and the other with what's currently stored in it. They're referred to as R0 (old) and R1 (current) in the dialog. Now, with the help of the provided search filters you can compare the values on different addresses and see what changes the game made to it - before and after you lost a life for instance. Once you think you've found the address where the game stores its current-number-of-lifes-value you can now change it to something else and with a bit of luck, it will work as expected and you can now cheat your way to victory.

Netplay

Netplay is supported through the Kaillera network. The user interface should be fairly easy to navigate through. Before you start playing make sure you and your gaming buddies share the same emulation settings. For more Kaillera info visit the official site.

NSP Files

This is a text based game configuration file format. It's easy to edit by hand and will give you more control over what files and settings to use for individual games. You may also at any time save your current emulation configuration into this format.

Available arguments are:

• -ROM or -IMAGE [filename]
• -SAVE [filename]
• -TAPE [filename]
• -STATE [filename]
• -MOVIE [filename]
• -STATESLOT1..STATESLOT9 [filename]
• -PALETTE [filename]
• -IPS [filename]
• -MODE [ntsc,pal]
• -PORT1..PORT5 [unconnected,pad1,pad2,pad3,pad4,zapper,mouse,paddle,powerpad,familytrainer,familykeyboard,suborkeyboard,doremikkokeyboard,horitrack,pachinko,oekakidstablet,hypershot,crazyclimber,excitingboxing,toprider,pokkunmoguraa,partytap]
• -GENIE [code] [on,off] [optional comment]
• -CHEAT [address] [value] [optional compare value] [on,off] [optional comment]

Note, the brackets [] should not be included and you can only specify one argument per line.

Example - c:\game.nsp:

-IMAGE c:\games\willybeamish.nes
-MODE pal
-PORT1 pad1
-PORT2 unconnected
-GENIE szneevvk on

This will load willybeamish.nes, force it into PAL mode with one standard controller plugged in and enable one cheat code.

Command Line/Configuration File Parameters

While parameters in the command line and configuration file shares the same syntax and can be used interchangeably, command line parameters are given higher priority. Directories, filenames, guids and input keys must be surrounded by quotation marks.

Example: Nestopia.exe "c:\gianasisters.nes" -video fullscreen bpp : 16 -video fullscreen width : 1024 -video fullscreen height : 768 -preferences fullscreen on start : yes -view size fullscreen : stretched

Back to Top

Troubleshooting

If you experience slow performance with Nestopia, here are a couple of things you can try to speed it up:

• Lower the screen resolution and/or pixel bit-depth (video dialog).
• Disable video filtering (video dialog).
• Change the NES screen memory location (video dialog)
• Enable triple buffering (timing dialog).
• Enable auto-frame-skiping (timing dialog).
• Disable vsync (timing dialog).
• Disable the rewinder (timing dialog).
• Change the application priority to "above normal" or "high" (preferences dialog).
• Lower the sound frequency and/or sample bit-depth or disable sound output completely (sound dialog).
• If your video driver has an option for vsync, make sure it's set to be application-controlled.

If you have trouble running a particular game, possible reasons could be:

• The image file has incorrect header data such as wrong mapper or name-table mirroring.
• It's a bad dump.
• Does it work on the actual hardware? If not, it's not supposed to work on Nestopia either.
• It has been hacked solely for the purpose of making it run on another emulator.
• You have the wrong region setting applied, try switching to either PAL or NTSC.
• Proper controller(s) connected? For instance, it could be a keyboard-only program or a game that only responds to the secondary controller.
• Do you have the 'no sprite limit' option enabled? Try disabling it, some games might depend on this hardware limitation.
• It's possible that the image database will cause more harm than good with some games. If the problem goes away when you disable the option for auto-correction of faulty images, please send me a report with the name of the game so I can correct it.
• It's unsupported by Nestopia.

Misc:

• If the gridlines are not drawn properly in the launcher dialog, follow this link.

Back to Top

Credits

Translations

Ports

Back to Top

Nestopia is Copyright © 2003-2006 by Martin Freij.

NES is either a trademark or registered trademark of Nintendo of America Inc.
Famicom is either a trademark or registered trademark of Nintendo Co., LTD.
All other trademarks are property of their respective owners.
Nestopia is not affiliated with or endorsed by any of the companies mentioned.