NES.app The NES Emulator for iPhone Version 2.1 Web: http://www.zdziarski.com/projects/nesapp/ ACKNOWLEDGEMENS NES.app Code: Jonathan Zdziarski NESCore Code: Jonathan Zdziarski Jordan Laughlin Coding Assistance: Brian Whitman (CoreAudio) Patrick Walton (CoreSurface) John Bafford (General Hackery) Special Thanks: Jay Freeman (iPhoneOS 2.0 Support) The iPhone Community (Thorough Testing) TABLE OF CONTENTS I. Introduction 1. Features ... Multitouch ... Zapper ... Sensory Pad ... Sound ... Frame Skip ... Full Screen ... Landscape Mode ... Save RAM ... Save State ... Game Genie ... Player 2 Control 2. Preferences ... Game Options ... Auto-Save Game ... Swap A/B ... Allow Suspend ... Full Screen ... Sensory Pad ... Game Genie ... Advanced Options ... Frame Skip ... Color Palette ... CPU Clock ... Bass Boost ... Debug Mode 3. How do I... 4. Known Issues ... Sound ... PAL vs. NTSC 5. NESCore 6. License NES.app is a Nintendo Entertainment System emulator for Apple's iPhone. NES.app uses an emulator core we call NESCore, which we've forked from pNESx and InfoNES and re-engineered as a highly-portable and high-performance Nintendo emulator core. In order to use NES.app, you will need ROM images of games written for the Nintendo Entertainment System platform. There are many public domain, home-brew games available which have been written for the Nintendo platform, and depending on your country of origin, you may be entitled to play images of commercial games which you rightfully own. The NESCore project can be found here: http://www.zdziarski.com/projects/nescore/ ADVERTISEMENT Countless nights of work have been spent on NES.app to deliver a top-quality application for your iPhone. If you find NES.app useful, please consider sending the author a cash donation through PayPal at jonathan@zdziarski.com FEATURES MULTITOUCH NES.app uses the iPhone's multitouch sensor to deliver a controller environment very similar to the original NES controllers. This allows you to "Run with B", and so forth. The multitouch programming also allows you to drag your finger to a different direction or button. Note: "rolling" your thumb between A & B will allow you to depress both buttons, just like on the original controller. ZAPPER The iPhone's touchscreen makes for a great way to implement the zapper gun. Just tap the screen where you want to shoot. Zap-Tap works on many games including Duck Hunt, Hogan's Alley, and others, but does not work at all on the more nonstandard games, such as Chiller and Freedom Force. SENSORY PAD Since there is no tactile feedback on an iPhone, it may be more desirable to play some games with a controller that measures motion, rather than presses on specific buttons. Activating the 'Sensory Pad' option causes NES.app's directional pad to track with the motion of your finger, regardless of where inside the sensory pad you are touching. When sensory pad is active, the directional pad is replaced with a yellow track sensor. SOUND Sound is played through the iPhone's native interface, allowing you to hear email dings or accept phone calls while playing NES.app. FRAME SKIP Using the frame skip option, games that otherwise might run slightly slow on your iPhone can be made playable. An auto-frameskip option is the default, which continually adjusts the frame skip and frame wait to make your games play as smooth as possible. FULL SCREEN MODE Using the full screen option, you can zoom in on your favorite game as close to "full screen" as the NES aspect ratio will allow. NOTE: Using full screen mode slows down the display a bit, so your frameskip will typically bump up by 1, making the game more choppy. LANDSCAPE MODE NES.app takes advantage of the iPhone's tilt sensor and will automatically switch to a landscape-based view when you tilt your phone to either side. SAVE RAM Games with battery-backed RAM, like Zelda, are automatically saved to preserve your character data. SAVE STATE NES.app can save the state of any game when you exit. Unlike save ram, which only for certain games with battery RAM, this option allows you to take a "snapshot" of your game in progress, and come back to it later right where you left off. You can choose to start a fresh game from the "All Games" menu, or tap "Saved Games" and load your previously saved game. The game state is stored separate from save ram, so if you are playing games like Zelda, where your game is usually stored to battery ram, you will not need to save state unless you want to save an exact snapshot. The save ram from the game is automatically stored regardless of whether you save state. TWO PLAYER CONTROLLERS Although NES.app does not support netplay, you can toggle between first and second player controllers by tapping the gray bar at the top of the controller. The controller will change from red to blue to identify itself as the 2nd player controller. Tap again to switch back. This is useful for some 2-player games where the players take turns. GAME GENIE Game Genie was a popular cheat system for the NES. Many cheat codes are published on the Internet. Up to four game genie codes can be specified per game via the preferences menu. Load a ROM, then back out into preferences to edit the genie codes. NOTES: Game genie slows down the game slightly, as the CPU is constantly having to match read addresses with genie codes. This may increase your auto-frameskip or require a bump if manually adjusting it. Leave the genie switch "off" when not using it. It's also a good idea to turn off full-screem mode if you're using game genie. TIP: For complex codes to start on a particular level, you can enable the code, then save your game after beginning, disable the code, and run at full speed again. PREFERENCES The following preferences are available by tapping the 'Preferences' navigation button... Auto-Save Game When active, every game you play will be automatically saved when you leave the game. You may re-enter the game where you left off by tapping 'Saved Games' from the top of the menu. If you decide to start a new game, your old saved game will be overwritten. Swap A/B Swaps the A/B buttons around. NOTE: The labels do not change, only the function. Allow Suspend When active, this allows you to push the home button, or accept a phone call from within a game. When you return to NES.app, the game will continue where you left off. When this feature is disabled, NES.app will promptly quit instead. Full Screen Stretches the game screen to as large as possible, while maintaining aspect ratio. NOTE: This impacts performance slightly. Sensory Pad Changes the directional pad to a sensory pad, which sets the direction based on finger movement. Game Genie Activates any Game Genie codes you have entered at the bottom of the preferences screen, for whatever game you happen to be playing. NOTE: Leave this option off unless you are using it. Advanced Options: Frame Skip Allows for manual adjustment of the frame skip. It is recommended you leave this on 'A' for 'Auto'. Color Palette This option allows you to change the color scheme of NES games to your liking. The following palettes are available: A: Standard palette, optimized for iPhone B: Standard palette, unoptimized (used in older versons of NES.app) C: Original NTSC palette D: Original PAL palette CPU Clock The CPU clock controls the frequency of the CPU during rendering. As of present best-practice, 339 provides accurate rendering for most games and is the default. 341 can be used to tweak any games that you might have a problem with, or if you find a game that doesn't run using 339 cycles. Bass Boost Boosts the triangle wave output (responsible for most basslines). Debug Mode Debug mode draws colored rectangles over the hot spots of your game controller, and also writes a diagnostic log to /tmp/NES.debug for development. NOTE: Leave this option off unless you are using it. Add -DDEBUG to your CFLAGS to build with this option HOW DO I... Q. Upload ROMs to my iPhone? A. Try iPhuc, iFuntastic, iBrickr, or set up SSH on your iPhone Q. Reset my game? A. Tap 'ROM List' and then tap your ROM again Q. Adjust my volume? A. With the volume buttons on the left. Q. Use the player 2 controller? A. Touch the top gray bar to switch between player 1 and player 2. The controller buttons and text will change from red to blue when 2 player is active. Q. Press A & B at the same time? A. In recent versions, you can now roll your thumb from one button to the middle of both buttons. Both A and B should show up in the active control window. Sliding your thumb from one side to the other will gracefully switch between the two buttons. COMPILING FROM SOURCE COMPILER ENVIRONMENTS There are two different compilers available for the iPhone: 1. Open Source Tool Chain http://iphone-dev.org/howto:toolchain_on_leopard_aspen 2. Apple SDK (Private APIs required) http://developer.apple.com/iphone/ http://iphone-dev.org/howto:using_sdk_with_toolchain_headers You will need to install one of these compilers to build NES.app. BUILDING THE PROJECT Open Tool Chain --------------- To build using the open tool chain, for iPhone firmware v1.0 and v1.1, use: make -f Makefile.iPhoneOS1.1 For iPhone firmware v1.2 and 2.0, use: make -f Makefile.iPhoneOS1.2 This will build the NES.app application directory in build/, which may then be copied to the iPhone's /Applications directory. Apple SDK --------- To build using the Apple SDK from Xcode, you will need to install the private, low-level APIs which are part of the open source tool chain. $ sudo mkdir -p /Developer/SDKs/iPhoneOS.sdk/Versions/iPhoneOS2.0.sdk/ $ svn co http://iphone-dev.googlecode.com/svn/branches/include-1.2-sdk $ cd include-1.2-sdk $ ./configure --prefix=/Developer/SDKs/iPhoneOS.sdk/Versions/iPhoneOS2.0.sdk $ sudo sh install-headers.sh Installing these APIs won't affect the Apple SDK's headers in any way, or your existing proejcts, but will only be used when specified in your Xcode project settings. Now, open the NES.xcodeproj file to build from Xcode. Be sure to choose "Device | Release" as a target, as the Simulator does not have the proper low-level frameworks to run NES.app. Once built, the application can be installed directly on the iPhone from within Xcode. NOTE: For command-line builds, example SDK makefiles have been provided, which are appropriately named with an _SDK suffix. ROMS Place your ROM files in /var/mobile/Media/ROMs/NES You will need to use a tool such as iPhoneInterface, iFuntastic, or SSH KNOWN ISSUES PAL VS. NTSC NES.app supports both PAL and NTSC games, however not all PAL games are appropriately identified as such in their headers. You can force NES.app to identify a game as a PAL game by adding the text (E) to the filename (including the parenthesis). For example: MyGame (E).nes. It is recommended that you title all of your PAL games in this way, to ensure they are clocked properly. NESCORE NESCore is an emulator core we originally forked from InfoNES, which was left as a defunct and buggy NES emulator. We've since heavily modified and rewritten many pieces of it, and given it a new birth as a portable LGPL emulator core. The NESCore project can be found at http://www.zdziarski.com/projects/nescore/ LICENSE 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; version 2 of the License. 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.