________  _______  ________
                       --<__   __/-/  ____/-<__   __/--
                      ---  /  /-- /  /_/~>- __/  /__ ---
                       --_<__/_-_<______/_ <_______/_--
                          Turtle Group Incorporated
                           http://tgi.home.ml.org/

      NES Image version 3.32
      Copyright (c) 1996-1997 John Pappas (DiskDude). All rights reserved.

      It is a crime to redistribute this software in a commercial venture
      of any kind without written permission or a licensing agreement.
      Please contact DiskDude <diskdude@poboxes.com> via email for
      information on licensing.

      This package is freely distributable for private use, however DiskDude
      disclaims any damages which may result from the use or misuse of the
      software. In addition, you may not charge *any* fee(s) for the
      distribution of NES Image, and it may *only* be distributed in whole
      (i.e. the original ZIP file with no modifications). You are also
      required to send the author a PostCard of your local area if you use
      NES Image. See section 8.0 Registration for more information.

Contents:

1.0 Abstract
    1.10 Version history
2.0 The History of NES utilities
3.0 How to use NES Image
    3.01 View .NES image information
    3.02 Convert an iNES image to FFE's format and vice versa
    3.03 To split an iNES image to Pasofami's format
    3.04 To join a Pasofami image to the iNES format
    3.05 Edit a Nintendo image
    3.06 Load a header to an iNES image
    3.07 Save an iNES header to a file
    3.08 Making a list of all your Nintendo images
    3.09 How to batch convert Nintendo images
4.0 Compatibilities
5.0 Acknowledgements
6.0 Information required
7.0 Known bugs
8.0 Registration       <-<-<-<-<-<-<-<-<-<-<-<-<-<-<-<-- IMPORTANT!!!!!!!!

1.0 Abstract
------------

This tool is designed to manipulate Nintendo Entertainment System (NES) images
which were backed up using a console backup system. It will convert between
the following formats:

  o iNES
  o Pasofami
  o FFE

The iNES format is becoming the standard for images and was designed for the
iNES Nintendo emulator originally written by Alex Krasivsky (Landy), later
improved by Marat (who also ported the code to other operating systems.

Pasofami, another Nintendo emulator has its own image format, however due to
the fact that it requires the image to be split into many files (including
image information and image title files), it isn't very popular (in my opinion
anyhow).

FFE's image format is very similar in design to the rest of its family of
backup systems, consisting of a standard 512 byte header to the images.

There is a new format out recently, with extension .FAM. It is for a new
Japanese Famicom emulator. Currently, NES Image does not support it.

A NES cartridge usually consists of a "program" or PRG ROM and a "character"
or CHR ROM (also sometimes RAM). The PRG ROM, as you might have guessed is
where the actual code of the game is stored. It has a maximum density of
4 Megabits. The CHR ROM (or RAM) is where sprite information is stored. Most
larger games (usually 1Mbit or bigger) do not have the CHR ROM/RAM which
implies that the sprite information is stored in the PRG ROM. NES Image can
accommodate both types - if a CHR ROM image is not found, NES Image will not
complain, but assume it isn't needed.

`NES Image' is CARDWARE. See section 8.0 `Registration' for more information.

1.10 Version history
--------------------

Initial version (no version number was specified)
o Source code was released!
o Support for *.ROM and *.VID to *.NES was added.

Version 0.9
o Added support for FFE and Pasofami.
o Added support for titles in .NES and FFE images.
o Added support to remove titles from images.
o Added support to convert image format .NES <o> FFE.

Version 0.91
o Totally new reowrite because v0.9 code was very messy.
o Autoodetects format of an image file, regardless of extension.
  (The Pasofami format requires the extensions are standard *.prg, *.chr,
  *.prm and *.nam however) No extension? Specify the filename as "mario.".
o Removed title flag bit in header o NES Image detects titles automatically.
o Added a new option! You can now add/edit a title embedded within an image.
o Encrypted the secret message within NES Image because MindRape thought he
  was clever and just used a hex editor to view it. Now lets see if you can
  find it Donald! :>

Version 0.91c
o Should read Pasofami images properly now.
o *.prm flag added for battery backup (hope it's right!).
o Bank mode nibble for .NES header fixed.
o Size detect of Pasofami CHR image fixed.

Version 1.00
Version 2.00
o Skipped because MindRape released his own "NES Image" versions 1.xxo2.xx
  People still thought that it was the latest (which wasn't).

Version 3.00 (beta)
o Added new bank modes for the .NES image format.
o Fixed a little mistake where the title string in the FFE format wasn't
  placed in the file where it should've been. If you've added a title with
  a previous version, it is now missing its first character... Sorry! :)

Version 3.00
o Fixed a bug... I thought the biggest CHR ROM was 32kbytes. Before NES Image
  said it couldn't find the file when it was >32kbytes. Now it will allow for
  image sizes up to 4Mbits.
o NES Image is now *CARDWARE*.

Version 3.10
o Added read/write of .NES image headers (including extended headers with
  title information).
o Added a list function which will scan ALL files in a directory, autodetecting
  the format, and reporting the information on them to a text file.

Version 3.20
o Added more editing support for NES images and changed the key mapping to
  make editing .NES images easier. Getting FFE images converted to the .NES
  format and working on an emulator is now VERY easy and quick! :)
o Added better support for FFE images: NES Image will now autodectect around
  three types of FFE image headers.
o Added support for 7bit ASCII in the ROM listing so you can send a list via
  email.

Version 3.21
o Removed the beep when editing .NES images because it *really* bothered me. :)
o When converting a FEE image to .NES, and NES Image doesn't autoodetect the
  image information, it will prompt you asking if you would like to edit the
  image now.
o Other small changes such as the usage screen.

Version 3.30
o A completely new look! NES Image now uses colour and full screen windows
  with pop up dialog boxes and menus to make your life easier.
o Updated iNES header manipulation to comply with the iNES emulator ver 0.6.
o Editing an image now works for *all* Nintendo image types, with a simplified
  menu system.
o Incorporated Add/Edit and remove title functions into the image editor.
o You may now save an image in the editor without quitting NES Image.
o ALL FFE images are detected with the PRG size equal to the whole image size;
  previous autodetects did not work with ALL images, even those with the same
  headers. Hence autodetects have been removed.
o Many other little changes... see if you can find them! ;o)

Version 3.31
o Fixed a bug in the edit window when dealing with titles. Once you make a new
  title, and decrease the size of a PRG or CHR ROM, you cannot increase it
  again when you are supposed to.

Version 3.32
o I compiled v3.31 with debug information, including I/O error checking which
  is done by the program itself. Hence it didn't work properly with some
  images as it would read past the end of file producing an error (which the
  program is supposed to catch as a form of ROM file detection). It has been
  fixed.
o I got my *first* PostCard for NES Image! :) There is now a way for this
  person (and anyone else who sends a postcard) to remove the nag screen from
  their copy of NES Image, but it's a secret :-)

2.0 The History of NES utilities
--------------------------------

As you might have guessed, NES utilities haven't been around for a very long
time. As far as I know, the first person to write a console utility
specifically for the NES was Donald Moore (MindRape) of Damaged Cybernetics.
It was called BreakNES which simply took PRG and CHR images and joined them
into a .NES file.

At first, it seemed very crude as it only supported one image size. I then
decided to write my own utility - NES Image. Since then, Donald improved his
BreakNES and renamed it, strangely enough, to NES Image! Well, let me explain
at this point in time that since then, he has agreed to rename it back to
BreakNES to allow my continued development of NES Image... but he never did. :(

Why am I telling you this? You may be startled at the different versions of
NES Image circulating around the world (especially via the Internet) and
some people may be unsure of which one is which - NES Image by Donald was
at version 2.1c at the time of writing, whereas the original NES Image hadn't
passed its version 1.0 release - this is why NES Image is now in its version
3.xx, skipping versions 1.xx and 2.xx altogether.

3.0 How to use NES Image
------------------------

I was quite surprised to find that some people on the Internet were confused
on how to use the first version of NES Image which was released some time ago.
A small document was written and posted to some World Wide Web page explaining
its usage... it was *very* surprising let me tell you! :>

Anyway, the basic concepts are below. An example is given and it is assumed
that the file "mario.nes" contains a copy of `Super Mario Bros'. (Although it
could be any Nintendo game you like... even just a file full of junk! Well, so
long as it has a proper iNES header it will work)

  NESimage [tool] [filename] [header filename]

  [tool]  [description]
  w       View image information (default)
  c       Convert a NES image to FFE and vice versa
  s       Split an iNES/FFE image to Pasofami format
  j       Join a Pasofami image to NES format
  e       Edit a NES Image
  o       Load a header (from a file) to an iNES image (req [header filename])
  v       Save an iNES header to a file
  l       Make a detailed list of all images in current directory
  l:s     Make a simple list of all images in current directory
          [Note: lower case `l' for 8bit ASCII; upper case for 7bit ASCII]

3.01 View .NES image information
--------------------------------

NESimage w mario       (.nes is assumed)
NESimage w mario.nes
NESimage w mario.ffe
NESimage w mario.prm

Nintendo images contain information such as:

o The title of the game (see "compatibilities" below)
o The size of the whole image and separate PRG/CHR images
o If the image uses vertical or horizontal mirroring
o If the image uses a battery backup
o If the image has a 512 byte trainer
o The type of bank switching the image uses
o Whether it uses a Four Screen VRAM Layout

This function will display this information, extracted from the image's
header/footer and/or image information file.

3.02 Convert an iNES image to FFE's format and vice versa
---------------------------------------------------------

NESimage c mario      (.nes is assumed)
NESimage c mario.nes

A file will be created called "mario.ffe" which is in FFE's standard format.
To go backwards, you type:

NESimage c mario.ffe

Now the a file called "mario.nes" will be created. Note: this file will NOT
be the same as the original file "mario.nes" because not all file formats
are 100% compatible. See "compatibilities" below.

3.03 To split an iNES image to Pasofami's format
------------------------------------------------

NESimage s mario     (.nes is assumed)
NESimage s mario.nes

The following Pasofami files are created, ready for use with the emulator:

mario.prg
mario.chr
mario.prm
mario.nam (if applicable - see "compatibilities" below)

3.04 To join a Pasofami image to the iNES format
------------------------------------------------

NESimage j mario      (.prm is assumed)
NESimage j mario.prm

The resulting file is mario.nes. If NES Image finds the file "mario.nam",
which contains the title of the game (or who distributed it :>), then it will
be stored into the new "mario.nes" file.

3.05 Edit a Nintendo image
--------------------------

NESimage e mario      (.nes is assumed)
NESimage e mario.nes 

As stated previously, Nintendo images contain some information about the ROM
image. This will allow you to edit this information - it is provided as a
tool for people who know what they are doing as it effects how the Nintendo
emulator(s) processes the image.

This option should be self explanatory by using the menu.

3.06 Load a header to an iNES image
-----------------------------------

NESimage o mario     mario.hdr (.nes is assumed for the image)
NESimage o mario.nes mario.hdr

NOTE: You must specify the header file. It doesn't have to be the same name
      as the image file either.

This command allows you to write header information to a .NES image from a
header file so you may use pre-defined settings for the image, allowing the
ROM to correctly run on an emulator (such as iNES). Don't ask for header files
for a particular game if it isn't included with NES Image because I gave you
every one I had! :)

If the header file contains a title, it will be embedded within the iNES image.

3.07 Save an iNES header to a file
----------------------------------

NESimage v mario     (.nes is assumed for the image)
NESimage v mario.nes

This command allows you to read header information from an iNES image, then
save it in a header file (also saving the game title if present). If you have
a working header for a game which isn't included with NES Image, then please
email it to me <diskdude@poboxes.com> for inclusion in any future versions.

The header file created automatically has the same name as the image file,
except with an extension "hdr".

3.08 Making a list of all your Nintendo images
----------------------------------------------

NESimage l mylist.txt
NESimage L mylist.txt        (There IS a difference... see below)
NESimage l:s mylist.txt
NESimage L:s mylist.txt

This will go through EVERY file in the current directory and auto-detect all
Nintendo images (ignoring non Nintendo images). Once an image is found,
NES Image will extract the information from it and put it in the list file.

The list file is a standard text file, with no line longer than 80 characters
so you can easily view them in DOS or print them on a standard printer.

By specifying only the tool 'L', the resulting list will be detailed, with
much information about the Nintendo images. Hence the list is a little cramped.
Most people do not need all this information, so a 'simple' list tool has been
developed. It is enabled by using the 'L:S' tool as shown in the examples
above.

Note: If you wish the generated text file to contain only plain text (7bit
      ASCII characters) so you can send them via email, use an uppercase "L"
      for the tool switch as above. Using a lowercase switch will generate
      a text file using 8bit ASCII characters (which looks much nicer imho).

3.09 How to batch convert Nintendo images
-----------------------------------------

This is a handy tip if you've got a few hundred Pasofami images in a directory,
but you don't want to sit there for hours converting each file individually so
you can play them on your brand spanking new iNES emulator.

All you have to do is make a batch file like the following:

      rem [start of go.bat]
      @echo off
      echo.
      echo Converting all Pasofami images to to iNES format...
      FOR %%t IN (.\*.prm) DO nesimage j %%t
      echo.
      echo Deleting non-converted images...
      del *.prg > nul
      del *.chr > nul
      del *.nam > nul
      del *.prm > nul
      del *.set > nul
      echo.
      echo Complete.
      rem [end of go.bat]

Put this file in the same directory as your Pasofami images and type "go" to
start the mass conversion. 

Due to the way Borland wrote their CRT unit in Turbo Pascal, having a "> nul"
after "nesimage j %%t" has no effect - which slows the conversion down because
it must write to the screen. If there are enough requests for a "quiet" switch
(to turn off writes to the display) then I will do so... For now, you will 
just have to wait an extra 10 seconds or so. :>

4.0 Compatibilities
-------------------

The images NES Image creates are completely compatible with those created by
the previous version or Donald's BreakNES. However, this version of NES Image
extends the iNES and FFE formats considerably.

NES Image has the ability to embed the title information into a iNES file
without having an effect on it when used with the iNES emulator. How does it
do this you ask? It places a maximum 128 byte title area at the *end* of the
image - which the iNES emulator ignores.

As for the FFE header, it consists of 512 bytes - only 4-5 are actually used!
128 bytes are used for title information - the last 128 bytes of the 512 byte
header.

NOTE: When you convert iNES images to Pasofami or vice versa, some information
      is lost between formats. This information is used by the emulators which
      is why some games may not work after conversion. To fix this, I have
      included sample iNES headers and .PRM files for the iNES and Pasofami
      emulators respectively. Use the `write header' option to use the iNES
      headers on your iNES images and the game should work with the iNES
      emulator. For Pasofami, just copy and/or rename the correct .PRM file
      for your image.

5.0 Acknowledgements
--------------------

o Landy/Marat for the format of the .NES header
  (from the official iNES web page)
o Marat for the sample NES header files
o EFX for the sample PRM files

6.0 Information required
------------------------

o Format of the NES Game Genie codes

This will allow NES Image to "patch" a Nintendo image with a Game Genie code,
similarly to the way CartDisk patches SNES images with Game Genie, Gold Finger
and Action Replay codes. The cheat is then made permanent and usable on a 
backup system or emulator.

o Complete format of Pasofami's .PRM file format.

I have the information MindRape gave me which was translated from Japanese
by EFX, however I'm a bit hesitant in including this into NES Image at the
present stage - I would like a "second opinion" first. :>

o Proper format of the first two image size bytes in the FFE header

7.0 Known bugs
--------------

The following are known problems present in NES Image:

o FFE header format not 100% correct
o Pasofami *.prm format only about 50% correct

Please report any bugs you may find or "features" to DiskDude.

Make sure you include a small description of what the problem is, a directory
listing of all the files where you typed the command and the command itself.
To write the directory listing to a file, type "dir > dir_list.txt". Please
attach this in the email otherwise I am unable to recreate the bug, hence fix
it for any future release.

It's amazing to see just how many people do not do this - perhaps no-one reads
my documentation..... :(

8.0 Registration
----------------

This version of NES Image is the product of many hours of work (probably upto
100 hours all up so far... it could be more) and contains 1500+ lines of code
(This document is 450+ lines by itself!). If you use it and/or like it, I
request only one thing of you: Register it with me by sending a PostCard of
your beautiful city/town/country to the following address:

                             John Pappas
                             PO BOX 48
                             Coburg 3058
                             VIC, AUSTRALIA
                            
Please include a *statement*of*the*weather* and that you sent it for the
registration of `NES Image'. MAKE SURE YOU GIVE ME YOUR EMAIL ADDRESS!
How else am I going to thank you by allowing you to remove the nag screen? :)

Thanks dude... :-)

All PostCards are eventually scanned in and put up on `DiskDude's PostCard
Gallery' on the Internet. URL: http://diskdude.home.ml.org/postcard.html

DiskDude of the Turtle Group Inc. <diskdude@poboxes.com>
[EOF]