NES.app
The NES Emulator for iPhone
Version 1.11
SVN: http://svn.natetrue.com/nesapp

ACKNOWLEDGEMENS

NES.app Code:
    NerveGas

NESCore Code:
    NerveGas
    Jordan

Coding Assistance:
    Nightwatch (CoreSurfaces)
    BWhitman (CoreAudio)
    DShadow  (General Hackery)

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
      ... Bass Boost
      ... Game Genie
   ... Advanced Options
      ... Frame Skip
      ... Color Palette
      ... CPU Clock
      ... PCM Sound
      ... Delete ROMs
      ... Debug Mode
      ... IRQ Enable
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 Nintendo games. ROM 
images are files containing the dumped instruction code from a physical 
cartridge. In many cases, you are legally entitled to posess a ROM image
of any game that you presently own. ROM images for NES are widely available 
online, or with the appropriate hardware, you can dump them yourself directly 
from the cartridge. 

The NESCore project can be found here: 

http://iphone.natetrue.com/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 nervegas@natetrue.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
      counter-clockwise.

  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 yet, 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,
      and for ROMs like the 1990 World Championship ROM, which requires the 
      second controller to start.

  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.

   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.

   Bass Boost
       Boosts the triangle wave output (responsible for most basslines).

   Game Genie
       Activates any Game Genie codes you have entered below.
       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. 

   Can Delete ROMs
       By default, only saved games may be deleted with a finger swipe. This
       option allows you to delete game ROMs. NOTE: Deletion is permanent!

   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

0. You will need to install arm-apple-darwin toolchain v0.30 or above.

   http://iphone.fiveforty.net/wiki/index.php/Toolchain_Project

   Set your HEAVENLY environment variable to point to your iPhone environment.

   You will also require AudioQueue.h from Leopart's AudioToolbox framework. 
   I cannot provide this. If you own Leopard, locate this file and copy it
   into your toolchain includes in AudioToolbox/AudioQueue.h

1. Compile using 'make'

   This will create a new NES.app package in ./build. 

   Upload entire NES.app directory into /Applications on the iPhone and reboot
   the iPhone. It should automatically detect the application and add it to the
   springboard. 

2. Place your ROM files in /var/root/Media/ROMs/NES
   You will need to use a tool such as iPhoneInterface, iFuntastic, or SSH

KNOWN ISSUES

  SOUND

  Occasionally, the sound may appear to play severely lagged; at about half 
  speed. Rebooting the phone appears to resolve this. This appears to be
  related to the sample rate of whatever sound was last played on the iPhone 
  (prior to launching NES.app). 

  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: Tetris (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://iphone.natetrue.com/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.

