******* Virtual GameBoy ******* The Portable Nintendo GameBoy Emulator version 0.3 by Marat Fayzullin email: fms@wam.umd.edu IRC: RST38h WWW: http://www.cs.umd.edu/users/fms/ (*) GameBoy is a registered trademark of Nintendo. * INTRODUCTION * Virtual GameBoy [VGB] is a portable emulator of the Nintendo GameBoy portable videogame console written in C. Although it is an initial release of the emulator in which many things do not quite work yet, it was able to run about 85% of 80 games checked with it. You can always get the latest VGB source code and support files from http://www.cs.umd.edu/users/fms/GameBoy/VGB.html There are two different VGB distributions which are both covered by this manual: 1. *** Source Code Distribution *** This distribution contains C sources of the emulator, and the screen/keyboard drivers for Unix/X. Virtual GameBoy has been tested on the following Unix systems: SunOS Solaris OSF/1 FreeBSD HP/UX Linux AIX 3.2.5 It was also successfully run on a Mac, Amiga, and Atari Falcon, although no decent ports are available for these platforms yet. If you would like to write new drivers, or port VGB to another platform, *please*, contact me by email or some other means. Feel free to look at existing drivers as well as at the other code. 2. *** VGB-Windows Distribution *** Due to the flood of requests from the people who use DOS/Windows running PCs and are unable to compile the emulator on their own, I have ported VGB under Microsoft Windows. This distribution contains an executable of a limited version of VGB-Windows which doesn't allow you to reload a new game from a menu when emulation is already running, and has an annoying "Virtual GameBoy DEMO" message across its window. The uncrippled version of VGB-Windows is available for $35US from Marat Fayzullin 6304 Hampton Place Elkridge, MD 21227 USA VGB-Windows is a 32-bit application which runs under Windows 3.11, Windows 95, and Windows NT. It is compiled with Borland C++ and needs Microsoft WinG library which can be obtained from ftp://ftp.microsoft.com/Softlib/MSFILES/WING10.EXE * NEW IN THIS VERSION * o Windows version is made. o Some heavy magic is done on the interrupts. o Palette registers are writable now. o Sprite display routine is changed. o Sprites are now clipped properly at the top and bottom boundaries. o -delay/-nodelay option is added. o etc. * SHORT MANUAL FOR THE WINDOWS USERS * In order to use VGB-Windows, you will first have to install WinG graphical library which can be obtained from Microsoft [see address above]. Also, the VGB-WIndows distribution contains a file called BWCC32.DLL which should be either kept in a directory from which VGB runs, or copied into \WINDOWS\SYSTEM directory. VGB-Windows runs in a resizable window with the following menus: o File o New This opton allows to run a new game. If you only have an unregistered version of VGB-Windows, it will be disabled so that you will only be able to choose a game when emulator starts. o Setup This option pops up a setup dialog allowing to change all 4 GameBoy's colors and some emulation parameters: o Palette Use this group of controls to select a color and change its RGB components. The palette controls may not work very well if you run Windows in 256-color mode. Use 16-bit or 24-bit graphical mode for best effect. o VBlank Period This parameter determines how many CPU commands will be executed between vertical blanking interrupts. Setting it lower may speed up the emulation, but setting it too low will hang it. o Update Period This parameter determines how many vertical blanking interrupts will pass between window refreshes. It is usually set to 2, but you can increase it to make VGB work faster. The sprite movements become jerky at high update periods though, and some sprites may simply disappear. o Delay Line Interrupts If you see "dirty" horizontal lines in some games, you may turn this option on or off to remove them. There is no some universal state of this option which will work for all games though. o Quit o Size o 1:1 These options change the window size to be the same as in real o 2:1 GameBoy, or 2/3/4 times bigger. Please, note that you can change o 3:1 window size by simple dragging the bottom-right corner of a o 4:1 window with the mouse. o Help o About This option will display a dialog box with copyright information and other legal stuff. * FREQUENTLY ASKED QUESTIONS * 1. What is GameBoy? GameBoy is a handheld videogame machine produced by Nintendo. It is built around a custom CPU similar to Z80, but with some changes. GameBoy is frequently laughed at because of its reflective green-on-yellow LCD screen which in fact is its virtue. Due to the low power consumption of its LCD, GameBoy can work for 35 hours off 4 AA batteries. There is a lot of good games produced for GameBoy, both classics [Tetris, Pacman, Asteroids, etc.] and specific ones [Final Fantasy series for GB]. It excells in RPGs and classic games where gameplay is more important than graphics. More information about GameBoy is available from http://www.cs.umd.edu/users/fms/GameBoy/ 2. Where do I get GameBoy games? You buy the cartridges. GameBoy software is copyrighted and still sold. Therefore, its distribution is an act of piracy. Nothing prohibits you from backing up a cartridge you own and playing it on the emulator though. To back up a GameBoy cartridge, you can use either SmartCard copier [about $100 for a standalone version], or a self-built copier, description of which will hopefully be available at the WWW page soon. 3. Is it legal to spread GameBoy cartridge snapshots? NO. Be aware of the fact that by using commercial software you haven't bought, you are commencing an act of piracy. Not that I care, anyway... 4. What are the keys used in VGB? VGB Unix/X keys: [SPACE] - A button [LALT] - B button ([CONTROL] in Windows) [TAB] - SELECT button [ENTER] - START button [ESC] - Quit emulation [F1] - Turn tracing on/off (Not implemented in Windows) [F2] - Show LCD controller registers (Not implemented in Windows) 5. Where is the complete list of command line options of VGB? Use -help option. It will tell VGB to display all options available in your version. Following are the options available in VGB-Unix/X: -verbose - Select debugging messages [5] 0 - Silent 1 - Startup messages 2 - Illegal writes 4 - Illegal CPU ops 8 - Bank switching -vperiod - Set VBlank interrupts period [10000ops] -uperiod - Number of interrupts per screen update [2] -help - Print this help page -cheat - Activate a GameGenie cheat [not supported yet] -shm/-noshm - Use/don't use MIT SHM extensions for X [-shm] -trap
- Trap execution when PC reaches address [FFFFh] -delay/nodelay - Delay/don't delay coincidence int-s [-nodelay] -saver/-nosaver - Save/don't save CPU when inactive [-saver] -color0 - Change color#0 [black] -color1 - Change color#1 [#585858] -color2 - Change color#2 [#989898] -color3 - Change color#3 [white] 6. Why some games do not run with VGB? As it was said before, VGB emulation is not completely accurate yet. Also, some games will probably never run on VGB. o If a game refuses to work, try changing -vperiod value from 2000 to 15000, or moving a "VBlank Period" knob in the VGB-Windows setup window. o If you see a group of "dirty" lines on VGB screen, or a game behaves strangely, try -delay/-nodelay options, or check/clear the "Delay Line Interrupts" checkbox in the VGB-Windows setup window. o If some sprites blink or do not appear at all, try changing -uperiod value from 1 to 10 [1 will give you the best picture, but the slowest emulation], or moving an "Update Period" knob in the VGB-Windows setup window. 7. Palette controls in VGB-Windows do not work. This probably means that you are running Windows in the 256-color mode. In this mode, not all of 256 possible colors are available, and you will be able to choose only from the available colors. Switch Windows into 16-bit or 24-bit graphics and palette will start working. 8. I start VGB-WIndows, but it tells me that WING.DLL is not found. This means that you haven't installed WinG library necessary to run VGB. Check the information in the beginning of this manual on how to obtain WinG. 9. I start VGB-WIndows, but it tells me that BWCC32.DLL is not found. VGB-Windows comes with a file called BWCC32.DLL. This file should be either kept in the directory from which VGB runs, or put into \WINDOWS\SYSTEM directory. 10. Why is VGB so slow on my computer? Because your computer is too slow to run VGB. VGB is written entirely in C language and therefore is quite slow. Although it works on 486/33 and even 386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can try to speed it up by increasing -uperiod value controlling the number of vertical blanking impulses between screen updates to 3-6, and by decreasing -vperiod value controlling the number of CPU cycles between vertical blanking impulses to 3000-6000. Please, DO NOT SEND ME MAIL about VGB speed. 11. Can I compile VGB with my Borland/Turbo C compiler? You can, given that your compiler creates executables using flat 32bit memory model. Two PC compilers which do that are WATCOM [using DOS4GW DOS extender] and GCC [using DJPP extender]. The only Borland/Turbo C 32-bit compiler that I'm aware of is for Windows. 12. When compiling VGB under Unix, I get "undefined name" errors. This means that your linker can not find the libraries necessary for VGB [namely, libX11.a and libXext.a]. Find these libraries in your system and modify the Makefile so that the final invocation of the C compiler has "-L" options. If the errors persist, try #undefining MITSHM option. 13. When starting VGB-Unix/X, I get X_ShmAttach error. You are probably trying to run VGB on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use -noshm option to tell VGB not to use shared memory. 14. VGB starts under Unix, but then I get X_PutImage error. Unix/X version of VGB currently needs 256-color X. Neither 2-color nor TrueColor Xterminals will work with the drivers included into "official" VGB distribution. 15. I start VGB-Unix/X but the window stays black. Some other X application took over all available colors so that VGB could not allocate any for itself. Check if you run XV, Netscape, or something similar. --------------- Marat Fayzullin