Nestopia Documentation

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

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 plattform of choice, the core provides a set of API classes. At the moment, a Mac port  by Richard Bannister is available under an alternative licence.

Features

Boards (non-assigned mapper)

• Mario 1 Malee 2
• Novel Diamond 9999999-in-1
• Super 24-in-1
• Super Game 8237
• WS 40-in-1

Sound Chips

• FDS
• FME-07
• VRC6
• N106
• MMC5

Controllers

• Standard Pad
• Light Gun 
• Family Basic Keyboard
• Power Pad
• Arkanoid Paddle
• Oeka Kids Tablet
• Hyper Shot
• Crazy Climber
• Mahjong
• Exciting Boxing
• Top Rider
• Pokkun Moguraa

Extras

• Famicom Disk System
• NSF Player
• VS.UniSystem

Fully or Partially Supported Mappers

..that renders a total of 159.

Recognized VS UniSystem Games

 System Requirements

Minimum
Processor	Pentium MMX or comparable AMD (1)
Ram	64MB
Video	Direct3D 9.0 compatible graphic card
OS	Windows 98/Me/2000/XP (2)
Software	DirectX 9.0c or greater

(1) With this spec you should expect nothing but turtle speed.

(2) Untested on 98/Me/2000. If Nestopia doesn't work on any of them, I'd like to know.

Recommended
Processor	Pentium 4 or comparable AMD (1)
Ram	256MB
Video	Direct3D 9.0 compatible graphic card
Sound	DirectSound 8.1 compatible sound card
OS	Windows XP
Software	DirectX 9.0c or greater

(1) This is better; expect ninja turtle speed.

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 game 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 / Movie Tapes

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 method with the values packed and encoded into a 6-8 character string.

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 or -SAV [filename]
• -STATE [filename]
• -MOVIE [filename]
• -STATESLOT1..STATESLOT9 [filename]
• -IPS [filename]
• -MODE [ntsc,pal]
• -PORT1..PORT5 [unconnected,pad1,pad2,pad3,pad4,zapper,paddle,powerpad,keyboard,oekakidstablet,hypershot,crazyclimber,excitingboxing,toprider,pokkunmoguraa]
• -GENIE or -CHEAT [code] [on,off] [optional comment]

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

This will load the willybeamish.nes file, 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 interchangebly, 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 

Argument	Values	Default
files auto export states	yes, no	yes
files auto import states	yes, no	yes
files auto ips patching	yes, no	no
files compress states	yes, no	yes
files fds bios	file	-
files fds led	screen, numlock, scrolllock, capslock, disable	screen
files fds save	ips, image, disable	ips
files last path images	dir	-
files last path scripts	dir	-
files path cartridge data	dir	.\cartridge\
files path image	dir	.\
files path ips	dir	.\ips\
files path screenshot	dir	.\screenshots\
files path script	dir	.\scripts\
files path state	dir	.\states\
files readonly cartridge	yes, no	no
files recent 1..9	file	-
files recent dir 1..5	dir	-
files screenshot format	png, jpg, bmp	png
files use last image path	yes, no	yes
files use last script path	yes, no	yes
gamegenie 1..N	code on, off	-
input autofire speed	0..5	4
input crazyclimber left down	key, (joy device) button, ...	S
input crazyclimber left left	key, (joy device) button, ...	A
input crazyclimber left right	key, (joy device) button, ...	D
input crazyclimber left up	key, (joy device) button, ...	W
input crazyclimber right down	key, (joy device) button, ...	H
input crazyclimber right left	key, (joy device) button, ...	G
input crazyclimber right right	key, (joy device) button, ...	J
input crazyclimber right up	key, (joy device) button, ...	Y
input device 0..N	guid	-
input emulation alternative speed	key, (joy device) button, ...	BACK
input emulation insert coin 1..2	key, (joy device) button, ...	F2, F3
input excitingboxing body	key, (joy device) button, ...	DOWN
input excitingboxing left hook	key, (joy device) button, ...	K
input excitingboxing left jabb	key, (joy device) button, ...	,
input excitingboxing left move	key, (joy device) button, ...	LEFT
input excitingboxing right hook	key, (joy device) button, ...	L
input excitingboxing right jabb	key, (joy device) button, ...	.
input excitingboxing right move	key, (joy device) button, ...	RIGHT
input excitingboxing straight	key, (joy device) button, ...	UP
input file exit	key, ...	ALT+X
input file launcher	key, ...	ALT+L
input file load script	key, ...	CTRL+SHIFT+W
input file load state	key, ...	F7
input file open	key, ...	CTRL+O
input file quick load last state	key, ...	SHIFT+0
input file quick load state 1	key, ...	SHIFT+1
input file quick load state 2	key, ...	SHIFT+2
input file quick load state 3	key, ...	SHIFT+3
input file quick load state 4	key, ...	SHIFT+4
input file quick load state 5	key, ...	SHIFT+5
input file quick load state 6	key, ...	SHIFT+6
input file quick load state 7	key, ...	SHIFT+7
input file quick load state 8	key, ...	SHIFT+8
input file quick load state 9	key, ...	SHIFT+9
input file quick save next state	key, ...	0
input file quick save state 1	key, ...	1
input file quick save state 2	key, ...	2
input file quick save state 3	key, ...	3
input file quick save state 4	key, ...	4
input file quick save state 5	key, ...	5
input file quick save state 6	key, ...	6
input file quick save state 7	key, ...	7
input file quick save state 8	key, ...	8
input file quick save state 9	key, ...	9
input file save screenshot	key, ...	ALT+E
input file save script	key, ...	CTRL+SHIFT+S
input file save state	key, ...	F5
input help help	key, ...	F1
input machine change disk side	key, ...	SHIFT+B
input machine hard reset	key, ...	SHIFT+T
input machine pause	key, ...	SHIFT+P
input machine power	key, ...	SHIFT+D
input machine soft reset	key, ...	SHIFT+R
input machine unlimited sprite toggle	key, ...	SHIFT+U
input mahjong a	key, (joy device) button, ...	Q
input mahjong b	key, (joy device) button, ...	W
input mahjong c	key, (joy device) button, ...	E
input mahjong chii	key, (joy device) button, ...	B
input mahjong d	key, (joy device) button, ...	R
input mahjong e	key, (joy device) button, ...	T
input mahjong f	key, (joy device) button, ...	A
input mahjong g	key, (joy device) button, ...	S
input mahjong h	key, (joy device) button, ...	D
input mahjong i	key, (joy device) button, ...	F
input mahjong j	key, (joy device) button, ...	G
input mahjong k	key, (joy device) button, ...	H
input mahjong kan	key, (joy device) button, ...	C
input mahjong l	key, (joy device) button, ...	J
input mahjong m	key, (joy device) button, ...	K
input mahjong n	key, (joy device) button, ...	L
input mahjong pon	key, (joy device) button, ...	V
input mahjong reach	key, (joy device) button, ...	N
input mahjong ron	key, (joy device) button, ...	M
input mahjong select	key, (joy device) button, ...	X
input mahjong start	key, (joy device) button, ...	Z
input nsf next song	key, ...	SHIFT+RIGHT
input nsf play song	key, ...	SHIFT+UP
input nsf previous song	key, ...	SHIFT+LEFT
input nsf stop song	key, ...	SHIFT+DOWN
input pad1 a	key, (joy device) button, ...	.
input pad1 autofire a	key, (joy device) button, ...	L
input pad1 autofire b	key, (joy device) button, ...	K
input pad1 b	key, (joy device) button, ...	,
input pad1 down	key, (joy device) button, ...	DOWN
input pad1 left	key, (joy device) button, ...	LEFT
input pad1 right	key, (joy device) button, ...	RIGHT
input pad1 select	key, (joy device) button, ...	RSHIFT
input pad1 start	key, (joy device) button, ...	RETURN
input pad1 up	key, (joy device) button, ...	UP
input pad2 a	key, (joy device) button, ...	X
input pad2 autofire a	key, (joy device) button, ...	W
input pad2 autofire b	key, (joy device) button, ...	Q
input pad2 b	key, (joy device) button, ...	Z
input pad2 down	key, (joy device) button, ...	V
input pad2 left	key, (joy device) button, ...	C
input pad2 right	key, (joy device) button, ...	B
input pad2 select	key, (joy device) button, ...	A
input pad2 start	key, (joy device) button, ...	S
input pad2 up	key, (joy device) button, ...	F
input pad3 a	key, (joy device) button, ...	-
input pad3 autofire a	key, (joy device) button, ...	-
input pad3 autofire b	key, (joy device) button, ...	-
input pad3 b	key, (joy device) button, ...	-
input pad3 down	key, (joy device) button, ...	-
input pad3 left	key, (joy device) button, ...	-
input pad3 right	key, (joy device) button, ...	-
input pad3 select	key, (joy device) button, ...	-
input pad3 start	key, (joy device) button, ...	-
input pad3 up	key, (joy device) button, ...	-
input pad4 a	key, (joy device) button, ...	-
input pad4 autofire a	key, (joy device) button, ...	-
input pad4 autofire b	key, (joy device) button, ...	-
input pad4 b	key, (joy device) button, ...	-
input pad4 down	key, (joy device) button, ...	-
input pad4 left	key, (joy device) button, ...	-
input pad4 right	key, (joy device) button, ...	-
input pad4 select	key, (joy device) button, ...	-
input pad4 start	key, (joy device) button, ...	-
input pad4 up	key, (joy device) button, ...	-
input pokkunmoguraa row 1 button 1	key, (joy device) button, ...	T
input pokkunmoguraa row 1 button 2	key, (joy device) button, ...	Y
input pokkunmoguraa row 1 button 3	key, (joy device) button, ...	U
input pokkunmoguraa row 1 button 4	key, (joy device) button, ...	I
input pokkunmoguraa row 2 button 1	key, (joy device) button, ...	G
input pokkunmoguraa row 2 button 2	key, (joy device) button, ...	H
input pokkunmoguraa row 2 button 3	key, (joy device) button, ...	J
input pokkunmoguraa row 2 button 4	key, (joy device) button, ...	K
input pokkunmoguraa row 3 button 1	key, (joy device) button, ...	B
input pokkunmoguraa row 3 button 2	key, (joy device) button, ...	N
input pokkunmoguraa row 3 button 3	key, (joy device) button, ...	M
input pokkunmoguraa row 3 button 4	key, (joy device) button, ...	,
input powerpad side a 1	key, (joy device) button, ...	Q
input powerpad side a 10	key, (joy device) button, ...	X
input powerpad side a 11	key, (joy device) button, ...	C
input powerpad side a 12	key, (joy device) button, ...	V
input powerpad side a 2	key, (joy device) button, ...	W
input powerpad side a 3	key, (joy device) button, ...	E
input powerpad side a 4	key, (joy device) button, ...	R
input powerpad side a 5	key, (joy device) button, ...	A
input powerpad side a 6	key, (joy device) button, ...	S
input powerpad side a 7	key, (joy device) button, ...	D
input powerpad side a 8	key, (joy device) button, ...	F
input powerpad side a 9	key, (joy device) button, ...	Z
input powerpad side b 10	key, (joy device) button, ...	M
input powerpad side b 11	key, (joy device) button, ...	N
input powerpad side b 2	key, (joy device) button, ...	U
input powerpad side b 3	key, (joy device) button, ...	Y
input powerpad side b 5	key, (joy device) button, ...	K
input powerpad side b 6	key, (joy device) button, ...	J
input powerpad side b 7	key, (joy device) button, ...	H
input powerpad side b 8	key, (joy device) button, ...	G
input view fullscreen	key, ...	ALT+RETURN
input view screen size 1x..9x	key, ...	ALT+1..9
input view screen size max	key, ...	ALT+S
input view toggle fps	key, ...	CTRL+F
input view toggle menu	key, ...	ESC
input view toggle statusbar	key, ...	CTRL+B
input view toggle window ontop	key, ...	CTRL+T
launcher color background	0x00000000..0xFFFFFFFF	0x00FFFFFF
launcher color foreground	0x00000000..0xFFFFFFFF	0x00000000
launcher column 1..10	file, system, mapper, prom, crom, wram, battery, trainer, mirroring, name, maker, folder	-
launcher search any file extension	yes, no	no
launcher search files fds	yes, no	yes
launcher search files ips	yes, no	yes
launcher search files nes	yes, no	yes
launcher search files nsf	yes, no	yes
launcher search files nsp	yes, no	yes
launcher search files unf	yes, no	yes
launcher search files zip	yes, no	yes
launcher search no duplicate files	yes, no	yes
launcher search path 1..N	dir	-
launcher search path 1..N subs	yes, no	-
launcher show gridlines	yes, no	yes
launcher use image database	yes, no	yes
netplay in fullscreen	yes, no	no
netplay use database names	yes, no	yes
nsf in background	yes, no	yes
preferences allow multiple instances	yes, no	no
preferences autocorrect images	yes, no	yes
preferences autostart emulation	yes, no	yes
preferences confirm exit	yes, no	yes
preferences confirm machine reset	yes, no	no
preferences default desktop menu color	yes, no	yes
preferences default fullscreen menu color	yes, no	yes
preferences desktop menu color	0x00000000..0xFFFFFFFF	0x00EFCA18
preferences fullscreen menu color	0x00000000..0xFFFFFFFF	0x00EFCA18
preferences power off on exit	yes, no	no
preferences priority	normal, above normal, high	normal
preferences run in background	yes, no	no
preferences save cheats	yes, no	yes
preferences save launcher files	yes, no	yes
preferences save logfile	yes, no	no
preferences save netplay list	yes, no	yes
preferences save settings	yes, no	yes
preferences start in fullscreen	yes, no	no
preferences suppress warnings	yes, no	no
sound adjust pitch	yes, no	yes
sound apu dpcm	on, off	on
sound apu external	on, off	on
sound apu noise	on, off	on
sound apu square 1	on, off	on
sound apu square 2	on, off	on
sound apu triangle	on, off	on
sound buffers	1..10	2
sound device	guid	-
sound enabled	yes, no	yes
sound output	mono, stereo	mono
sound sample bits	8, 16	16
sound sample rate	11025, 22050, 44100, 48000, 96000	44100
sound volume	0..100	100
timer alternative speed	30..240	180
timer auto frame skip	yes, no	no
timer default speed	yes, no	yes
timer max frame skips	1..16	8
timer performance counter	yes, no	yes
timer speed	30..240	60
timer vsync	yes, no	yes
video color brightness	0..255	128
video color hue	0..255	128
video color saturation	0..255	128
video device	guid	-
video filter	bilinear, scanlines bright, scanlines dark, tv soft, tv harsh, scale2x, scale3x, 2xsai, super 2xsai, super eagle, hq2x, hq3x, none	none
video fullscreen bpp	16, 32	16
video fullscreen height	height	480
video fullscreen width	width	640
video ntsc bottom	1..239	231
video ntsc left	0..255	0
video ntsc right	1..255	255
video ntsc top	0..239	8
video pal bottom	1..239	239
video pal left	0..255	0
video pal right	1..255	255
video pal top	0..239	0
video palette	internal, emulated, custom	internal
video palette file	file	-
video texture location	auto, vidmem, sysmem	auto
video unlimited sprites	yes, no	no
view show fps	yes, no	no
view show on top	yes, no	no
view show status bar	yes, no	yes
view show window menu	yes, no	yes
view size fullscreen	1..9, stretched	9
view size window	1..9	1

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 auto-frameskip (timing dialog).
• Disable vsync (timing dialog). 
• Change the application priority to "above normal" or "high" (preferences dialog).
• Keep the menu and other windows hidden while in fullscreen.
• 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 real thing? 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 game 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.

 Credits