=================================================================
 NESticle                                   Version 0.21 (4/4/97)
 by Bloodlust Software
             "The only NES emu with elephantitus" (TM)
=================================================================

---------------------
     What it is
---------------------

NESticle is a DOS/Win95 based emulator for the Nintendo
Entertainment System written in C++/Assembly. It 
is essentially the product of 2 weeks of boredom and 
a smattering of effort. 

It is freeware and it is not to be distributed with game
ROMs and it is not to be sold. If you like it, or have
bug reports/questions/comments send me email to the 
address below. 

The CPU emulation is based on a modified version of
Neil Bradley's (neil@synthcom.com) assembly m6502 core.

A majority of the NES technical information used to create this
came from Marat Fayzullin's (fms@freeflight.com) great NES.DOC
and a lot of 'hacking' on my own. 

Sound information was provided by Y0SHi (yoshi@parodius.com) from
his NES technical document. His doc did not exist until recently,
but it is updated quite often. He is one of the authors of another
NES emulator, 'qNES'...details of which can be found at 
its website, http://qnes.parodius.com.


---------------------
    What's New
---------------------

Version 0.21:
 - You can change directories now when you load roms.
 - Sound cards under DOS that do not support auto-initialized
    DMA transfer have been fixed, i hope.
 - Now uses a secondary sound buffer for mixing as opposed to using
   the primary one (under Win95 DirectSound). This should make it
   more compatible. Also is using a timer callback to update the buffer,
   should eliminate some static. DirectSound is atrocious.
 - 'swapbut' command line option added.  Swaps the A&B joystick buttons
 - 'palfile' command line option added.  Now you can use multiple-palettes.
 - The new palette was thankfully provided by Loopy (loopy@itsnet.com).

Version 0.2: 
 - Initial release

---------------------
    What it does
---------------------

NESticle emulates the basic NES hardware, along with several of
the memory mapping chips used by various games. As of now,
it runs a majority of games although there are still
a few bugs and glitches here and there.

What's emulated:

   -6502 CPU
   -PPU
   -VRAM/VROM 
   -Horizontal/Vertical/4-screen mirroring
   -Scrolling
   -Multiple split screens (although some glitches still)
   -8x8 and 8x16 Sprites
   -Dual joypads
   -Memory mappers 0,1,2,3,4 (as defined in the iNES headers)
   -Battery backed RAM
   -Sound emulation (still needs work)

Other neat features:

   -Ability to save/load your game at any time
   -Joystick support
   -"Friendly" GUI
   -VESA/DirectDraw support
   -Fullscreen 256x224 VGA mode (DOS only)
   -Save .pcx snapshots
   -iNES single cart format (pasofami format coming soon)
   -Virtual frame speed not system dependant
   -Fully editable palette (I dont have the correct colors)
   

---------------------
 What it doesn't do
---------------------
All of the sound channels are not emulated entirely correctly.
Lots of tweaking needs to be done. Particularly the frequency
sweeps which are responsible for most sound effects. The sound
mixer still needs to be rewritten in assembly as well.
You can turn the sound off if it gets on your nerves.
If you notice the sound "breaking up" or becoming staticy, 
try lowering the sampling rate.

Any memory mapper other than the first 5. This includes, most
notably, Castlevania 3. However I do have 4-screen vram working.

I'll put in turbo/autofire settings later.

There are still some bugs with games that utilize split screens.
In my opinion, the NES method of split screen-ing is utterly horrible.
Lots of games rely on CPU speed to tell when to split the screen, others
use a dumb hitflag, and others use IRQs. Games that switch pattern tables
halfway through the frame were a bitch. Adjusting the HBlank/Vblank length
under Settings/NesTiming may fix some split screen quirks.

Some games are screwed all to hell. Galaxian comes to mind.
Fuck it, play Galaga instead. Status bar gets screwed in SMB3 when you fly.

Long file name support under dos.

---------------------
  What you get
---------------------

There are 6 files:

  dos4gw.exe       : 32-bit DOS extender
  NESticle.exe     : The 32-bit DOS version
  NEStcl95.exe     : The Win95/NT Directdraw version
  NESticle.pal     : The NES palette (256 colors in RGB format)
  gui.vol          : Extra graphics stuff for the gui
  readme.txt       : This file

Note that it does not come with ROMs.
It will never come with ROMs.
And it must never be distributed with ROMs.
Distribute it with ROMs and you die.
Ask me for ROMs and you die.


---------------------
  What you need
---------------------

A 486 or Pentium running DOS or Windows 95/NT.

For the Windows version you need DirectX Version 3.0.
It's available somewhere on Microsoft's labyrinth of a website.
I'd recommend at least 16MB of memory for the Win95 version.

The DOS version only needs the dos4gw extender that comes
in this package. NESticle can also take advantage of VESA 2.0 support
if it exists. If it does not exist, NESticle will resort to only the
video modes 320x200 and 256x224. You need about 8MB of memory
for the DOS version, maybe less.

The DOS version currently supports any 8-bit or 16-bit Soundblaster
or compatible. 16-bit preferred, of course. (GUS support may be added
later). The Win95 version utilizes DirectSound for digital output (which
sucks horribly).

Other differences between the DOS and Win95 versions are
described later.

---------------------
 How to work it good
---------------------

If you can figure out the japanese version of Pasofami
then you can figure out this.

Most of the menu options are self explanitory.
Load up a .NES rom from the File/Load ROM.
Execute the rom from CPU/Reset.

If you're running in a high-res mode (>320x240), the NES
game screen will appear in a window. You can maximize the window
with the LEFT button in the title bar. You close the window with
the RIGHT button. I know the buttons aren't marked and they should 
be but I'm lazy and this aint win95. 

You can toggle the GUI on and off by pressing ESC.
Pressing the spacebar will disable the GUI and maximize the NES game window.

You change the input devices from the Settings/RedefineInput menu(s).
No matter what the settings are, Enter/Tab are always Start/Select in order
to accomodate 2 button joysticks.

F5/F7 saves and loads your games. Essentially it stores the entire NES state
in a "*.STA" file. This seems to work for the most part, although there might
be some unforseen bugs.


---------------------
  ROMS and stuff
---------------------

NESticle currently uses the iNES single file cart format (*.NES). 
It will support the pasowing format in the future.
The ROMs must be stored in the same dir as the .exe.

Here's a description of a sample cart 'ZELDA' and some extensions:

 - ZELDA.NES         
    The actual ROM/VROM data preceded by a 16-byte header

 - ZELDA.HDR         
    An alternate 16-byte header file. If NESticle encounters this in the dir
    of the ROM, it will use this header instead of the one present in the
    NES file.

 - ZELDA.SAV
    8K file representing the contents of the battery backed memory used
    in some games. This file is automagically saved and loaded as needed.

 - ZELDA.STA
    I couldn't think of a good extension for this one. It's the 'state' file
    used by saved games. It's pretty big, about 22k. 

 - ZELDA.Dxx    It's a dump of the 64k cpu address space. For debug purposes.
 - ZELDA.Rxx    It's a dump of all 16k rom banks. For debug purposes.
    

Selecting 'Write ROM Header' from the file menu will write the header stored
in memory to the .NES rom file. Essentially, this lets you use an alternate
rom header file (*.hdr) and load and test the rom, then if it works you can 
write it permanently. I put this in for those of you without hex editors.

Numerous roms floating around out there have incorrect headers.
Having an incorrect memory mapper type in the header will most likely cause
the game to crash. Having an incorrect mirroring bit will cause the background
to appear jumbled, or split, while scrolling. You can flip the mirroring bit
from the settings menu. If changing the mirroring fixes the game, you can then
write the ROM header as described above. 


---------------------
Command line options
---------------------

DOS & WIN95:
------------

-res <xw> <yw>  : Sets the resolution to xw,yw on startup.
                  Use this if 256x224 doesn't work.
-setinput <num> <type>
                : Sets input device <num> to <type>
                   ex. '-setinput 1 GRAVIS'
-swapbut        : Swaps the A&B buttons (joysticks only)

-waitvsync      : Wait for the vertical sync to draw frames (see Performance)
-showfps        : Show FPS on startup
-hidegui        : Hide GUI on startup

-load <rom>     : Load <rom>
-run <rom>      : Load & Run <rom>
-restore <rom>  : Load & Run & Restore saved game for <rom>

-sndrate <rate> : Sets the sound sampling rate (8000-44100)
-nosound        : Bypasses the initialization of any sound hardware



DOS only:
---------
-? or -h        : Display command line help
-novesa         : Don't use VESA extensions
-linear         : Force linear video mode
-banked         : Force banked video mode

-sb   <port> <irq> <dma8>  : Forces 8-bit soundblaster settings
-sb16 <port> <irq> <dma16> : Forces 16-bit soundblaster settings
      (if soundblaster settings are not supplied, they will
        be extracted from the BLASTER environ variable)


Frequently used command line options can be put in the 
file "default.cmd" which is automatically parsed anytime
NESticle loads. 

---------------------
 Performance Issues
---------------------

This section has lots of technical crap.
Read at your discretion.

The DOS and Win95 versions vary greatly in the performance they achieve.
It all depends on the video hardware you have and the video acceleration
available. The Win95 DirectDraw version of NESticle takes advantage of hardware
blitting to improve performance tremendously. If your card does not support
hardware blitting then performance will most likely be worse than the DOS
version. You can tell if your card supports this by selecting
Misc/DirectDrawInfo from the menu.

There's one big catch: Most drivers written for Win95 do not inherently
support low res modes like 320x200 and 320x240. The ones that don't support
them have to substitute by using notoriously slow ModeX modes for these
resolutions. Not only do the ModeX modes not have hardware blitting, they
also have much slower page flips because of additional conversions necessary.
The DOS version will be significantly faster in cases like these.

The DOS version starts up in 256x224 mode by default. It's a resolution
perfect for the NES. The DOS version requires VESA 2.0 extensions to run
at 320x240 or above...if your video card does not have this built
in you can get Univbe from http://www.scisoft.com. Why would you want to
run at anything above 256x224 if the NES res is 256x224? Well, there's
two reasons: A 320x240 linear frame buffer VESA 2.0 mode on a PCI bus will
most likely be faster than the 256x224 mode. And secondly, Scisoft's Univbe
allows you to pump up the refresh rate of low resolution modes which
makes things look a lot nicer. 

You can show the fps counter by selecting ShowFPS from the Misc menu.
To squeeze the most fps out of your system, make sure the GUI is disabled and 
the NES game window is maximized (ie hit spacebar). This eliminates a lot
of overhead. Having WaitVsync turned on waits for vertical syncs before
drawing frames, this slows the frame rate to the refresh rate of the video
card (thats why it's a good reason to increase the refresh rate with Univbe).
WaitVsync is off by default.

You can see the % of CPU utilization in an option in the misc menu. I dunno what it's
good for, just looks neat. Anything besides the NES rendering and the 6502 Emulation 
bars is purely overhead. Interesting to note that under Win95, that all of the CPU
utilization bars never add up to 100% showing how much CPU time is sucked out by the OS. 

As an aneqdotal example, on my p133 with a #9 Motion 771 w/VESA 2.0 playing
Super Mario Bros maximized I get roughly:

 DOS   256x224  203fps  : Standard DOS mode
 DOS   320x240  215fps  : This is actually faster than 256x224 cuz it's a linear frame buffer (VESA 2.0).
 DOS   640x480  111fps  : DOS really chokes on high res modes cause of the way i pageflip.

 WIN95 320x240   77fps  : ModeX mode! Sucks!
 WIN95 640x480  610fps  : This is no typo. Linear mode and hardware blitting.


If a game ever 'slows down', it's most likely because it would have slowed
down at that part on a real NES too, and it isn't an emulator problem. 
Increasing the vblank/hblank intervals may alleviate that though.

---------------------
     Contact
---------------------

Bloodlust Software
bldlust@southwind.net
http://www2.southwind.net/~bldlust/NESticle.html

Email me about ROMs and your suffering will be legendary.

---------------------
  Acknowledgements
---------------------

Marat Fayzullin for his priceless NES.DOC and iNES emulator.

Multi-6502 CPU emulator by Neil Bradley (neil@synthcom.com)

Y0SHi and Marat for supplying valuable information on NES sound.

Loopy, Vectriff and DeceiverX for additional NES stuff.

Scrotum-art and testing by digger.

Nesticular name idea by Sabin.

---------------------
     Disclaimer
---------------------

NESticle Copyright 1997 Bloodlust Software
Nintendo Entertainment System (NES) is a registered trademark of Nintendo.
Neither Bloodlust Software nor the author are affiliated with Nintendo
 nor advocate the piracy of NES games.
NESticle is freeware and can be distributed freely as long as it is not
modified and ROMs are not packaged with the program.
You use this software at your own risk.


Coming soon........SNESticle!


