

                        ******* VGB *******
                           Virtual Gameboy 
                             version 2.0

                         by Marat Fayzullin
                      
	             Acorn Port by David McEwen 
	            Port Version : 2.03 (06/12/00)



In this version 
---------------
	Version 2.03
	------------
	* All bugs fixed - I think...
	* Now accepts old sabe files (see below)
	* Washed out palette option
	* Auto Load/save options	

	Version 2.02
	------------
	* New Check CRC option
	* Screen redrawn if initialisation fails
	
	Version 2.01
	------------
	* Dynamically increases the wimpslot for roms
		- seems to use a lot more memory in some cases
		- makes loads more roms work that really should have worked in the last release
	
	Version 2.0
	-----------
        * Sound - better than standard VGB sound! 
        * All the changes from the new source (Conker's Pocket Tales now runs!)
        * Minor speed increases
	* Saving code revised and fixed
	* Key redefinition -> again thanks to Gareth (although I did rewrite a lot of it ;-) )
	* New save options
	* Eagle mode (huge thanks to Dirk Stevens without whom Eagle mode wouldn't be with us today!)
	* Scanlines
	* Tertis-esque bouncy screen rumble mode (I thought about blurring stuff, but that would be going too far...)
	* 16 bit mode
	* Kreed's excellent interpolation routines (2xSaI, Super 2xSaI and Super Eagle)
	
	NOTE
	* VGB 1.4 saves are *NOT* compatible

	             
New In Last Version
-------------------

	* More speed
		- A definite increase 
		   - should help all those people with lowly SA less machines 
		- The method used may cause minor corruption in the last couple of columns
		- Also scrolling can be jerky... but it runs so much faster it doesn't matter   
	* Cheat codes (both Game Shark & Game Genie) - see below
	* Seems a lot more stable to me
	* All features from the main 1.4 source -> Zelda DX now works as does Wario 2 CGB
	  	- This is also one of the few emulators that can run Disney's Bug's Life
	* Super GB colours fixed
	* Super GB & Colour GB palette setting sped up...
        * On Colour GB I have sped up palette setting on a Risc PC by only setting the physical
          palette once for every four colour changes - larger values caused strange effects...
          I might make this configurable in the future
          

Coming Soon
-----------

 * Dunno...

	                          
Introduction
------------

This is a port of Marat's Gameboy emulator. It emulates all gameboy stuff... Pocket GB, 
Super GB, Colour GB and even support for combined Colour & Super GB.

Use it to play the best version of Tetris anywhere!!!

OK a challenge... can anyone beat my Tetris score (1288 lines) ??
<NB this was achieved on a real Gameboy Color not the emulator>


Note for users of old machines
------------------------------

The best way of using it is to increase the Uperiod and decrease the Vperiod in the 
options window. Please note that for older machines eg A5000... the screen mode will
always be 320 by 256. This will be Mode 13 in 256 colours.
The reasons for this are speed and guaranteeing the user has the right mode.


How do I use it ?
-----------------

Easy - just download a game from the internet there are various good sites around 
and few companies actually care what happens with these roms since they are in 
many cases over 10 years old and noone is really going to buy them in this day 
and age. One of the best sites is Daves Arcade Classics, great for MAME roms as well.

Once you have some ROMS you can run them by setting the filetype to Gameboy and 
double clicking or dragging the game to the VGB icon. This loads the ROM.
Now there is no need to decompress files!! You can run straight from a Gzipped or
singularly PKZipped file - save a bit of Hard Drive space... 

It is fairly intuitive to use... 

The keys during emulation are :


  Cursor keys control movement

  [SPACE]  - SELECT button   
  [ALT]    - B button 
  [CTRL]   - A button
  [RETURN] - START button
  [F8]     - Force filename to generated one (ie <VGB$Dir>.saves.<game name>)
  [F9]     - Save State Hotkey
  [F10]    - Load State Hotkey
  [ESC]  - Exit
  
The frontend allows you to alter various variables that will affect the
speed of the game - the Uperiod and Vperiod values. Uperiod is sort of equivalent 
to a frame skip, and Vperiod is the clock cycles per screen refresh. The lower the
value the more probs that may occur... some games require higher values to work well.

There are several resolution choices available. The first 4 are simple resolutions
no scaling is implemented. There is a full screen mode. If using Super GB the mode will be 256 by 256, otherwise it'll be 320 by 288, which plots 4 times as many pixels!! An MDF is included for these modes. If for whatever reason the modes cannot be found Mode 13 (320 by 256) is used.

The Delay option determines whether VRAM reads are delayed or not. This may make games
work better or worse...

The Check CRC option allows you to specify whether the CRC in the ROM being correct matters
for the game to be run. If set the CRC will be checked and loading will fail if this is wrong,
otherwise it is ignored and all ROMs will be loaded.

The pause function mean that when you press Escape the emulation isn't killed
instead it is paused so that it can be continued from that point by clicking on the
icon. If you wish to reset the emulation either press F5 while in the emulator or
click on Reset in the menu.

For those with StrongARMs there is a frame locking option, which forces update to 
the set number of FPS regardless of the refresh rate of the mode it is running in!!

Auto frame rate is active on slow machines with frame locking on. This will try and 
match frame skipping to your system, but is far from perfect. I'm doing lots of 
optimizations to the emulators and hopefully this will help.

Save RAM support is available. this is very much changed from the last release -> still
buggy, but a lot nicer. There is a Saves directory inside the VGB application. This is
the default location for saves. If you press F9 and you haven't set up the save name
it will be saved with a name that is conatined in the rom -> this may mean that another
games save could be overwritten, be careful! If you have a save to load that is not in
the default location or of a different name, just drag it into the options window and
click OK or save and when you load or save from that moment on (until you load another ROM)
this file will be used. Please tell me what you think of this system. Note that the filename
doesn't update between rom loads -> press F8 if you want to use a generated filename or
sort out the filename manually.

Since some people wanted the old functionality (you know who you are!) I have added the
Auto Load and Auto Save options. If you want to start up with your save loaded check Auto Load. 
If you are using a new format save then the state will be set to where you saved, an old save 
will just restore the SRAM - so you will have to go through the start of the game. The Auto 
Save function will save the state when you quit to the desktop (press F12). F9 & F10 (as well
as F8 to reset save file to generated one) can still be used with these options.

Sound option obviously means you get sound. Channel 3 sound is currently wrong -> it should
be a 4 bit waveform, but it is generated as a melodic tone. This will be changed soon - well
as soon as I can work out a nice implementation that works with most games.

There are several render modes available. 
Normal -> which is not scaled 
Scaled -> doubles the display area
Scanlines -> doubles the displa area, but only displays alternate lines
Eagle -> smoothed double scaled mode

Specific to 16 bit :

Super Eagle -> an improved eagle routine (smoothed double scale)
2xSaI -> Even nicer smoothed double
Super 2xSaI -> awesome!

The washed out palette provides a palette more akin to what you actually see on a CGB. If you 
change the option while rom is running the palette may look strange as each new colour set
will use the washed out/not washed out look. Either reset or reload the rom for the correct 
look.

A future release should hopefully be running in a window... I will try and optimise as
much of the code as I can!! This may also mean that it becomes more playable on older
machines, but please do not expect miracles.

CHEATS
------

To add cheats simply open the cheats menu using the option on the main menu.
Then click on a tick to unfade a writable field. Then type in your cheat code and click on
OK. When you drag a new rom to the icon the cheats will be active. 

The cheats will be stored throughout the session, so if you drag another rom to the icon be 
sure to untick all the boxes.

In future you will be able to save out cheats...

PROBLEMS
--------

If you have a crash. Edit the !Run file. Comment out the line mentioned and alter the bottom
line so that it outputs to a file (such as <VGB$Dir>.^.output). Email me this file and I will
have a better idea of what is going wrong. If you have problems its best to let me know 
rather than sit on them as they won't get fixed if I don't know about them.

 
*FAQ*
----- 

Why are my Roms images not working ?
-------------------

Some Colour Roms don't work properly yet, but you can get them to work in colour
by using the Super GB option.
Try downloading them again. If there is still no joy. Send the image to 
Marat and see if he can find a reason. 

Where's the sound ?
-------------------

When it sounds nice I'll add it. I'll probably do a direct MIDI output too.


Do I need a special screen mode ?
---------------------------------

Nope the emulator runs happily in a 320 by 256 mode as the screen fits nicely. 
The full screen modes require  specially defined modes... a Mode Definition File 
is included. It runs in either 16 or 256 colours - it just depends on your taste!

Will you get it to run in the desktop ?
---------------------------------------

Moon on a stick anyone !!


Will you be porting any other emulators ?
-----------------------------------------

**** ???? ****

For me to decide...


Copyright and Disclaimer
------------------------

This emulator is copyright Marat Fayzullin 1994-8, and the Acorn-specific
components are copyright David McEwen 1998. You may not attempt to pass off
any part of this work as your own, although you may distribute it freely as
long as you supply the complete archive (that is, all the files supplied to
you).

This software is supplied "as is". I make no claims about the reliability or
suitability for any purpose of this emulator, and any use of it is undertaken
at your own risk. No responsibility is taken for any failure of the software,
or for any loss or damage caused directly or indirectly by the software.

Whilst I will endeavour to help you if you have problems with this emulator,
no such support is guaranteed.

In the above "This emulator" refers to everything supplied within this
archive, which is specifically the !VGB application and all the files
contained within it, and also the documentation files (including the one you
are reading now).



COMMENTS
--------

Any comments about the emulator as such should go to Marat Fayzullin : 
email : fms@komkon.org
Website : http://www.komkon.org/fms

Any comments about the Acorn specific parts and please no inane emails giving 
me ways of making money etc... just useful constructive stuff please
email : david@acornemus.freeserve.co.uk (Home)
	davidm@argonaut.com (Work)
Website : http://www.lizjay.demon.co.uk/david

Thanks
------

Marat for letting me have the source...
Gareth Moore for testing and getting info on his site so quick, as well as providing help!
Dave Sharp for testing on his aged A5000
Michael Koenig for testing this and many other emulators...
Dirk Stevens for Eagle
Derek Liaw (Kreed) for the excellent 16 bit interpolation routines
Nintendo for making such a cute machine - buy one, go on you know you want to!!

