Readme File for KiGB - a free portable emulator for Game Boy, Game Boy Color and Super Game Boy by Ricky Liu. KiGB v2.05 0. Introduction It is my third emulator project (1st is CHIP8 and 2nd is Phoenix). KiGB is a free portable emulator for Game Boy, Game Boy Color and Super Game Boy running on MS Windows 9X/Me/NT/2000/XP, Linux and MS-DOS. It may or may not run on Windows Vista - I don't have Vista installed. Scott Nash and I have completed a project to improve the compatibility and accuracy of KiGB. We have tested all the games and demos in the GoodGBX V2.02 ROM set (over 6,000). If you find any bugs, please notify me: k*i%g-b@emuunlim.com (remove *%-) Please place "[BUGS]" before the subject. With the completion of the project, we are confident that KiGB provides the best compatibility and accuracy in graphics, sound and timing. 4x4 World Trophy, Carmageddon, Prehistorik Man, Demotronic Final Demo and Color Panel Demo among others are first emulated perfectly in KiGB. Please see the compatibilty pages in my web page for results on the compatibility tests on KiGB and 4 most popular and highly-rated emulators, namely, VisualBoyAdvance, bgb, no$gmb and TGB Dual. Starting from v1.20, Game Link Cable is emulated. You can now play games in 2-player mode via TCP/IP network. See link.txt for details. Super Game Boy (SGB) emulation is added in v1.30. See sgb.txt for the current emulation status. A Mac OS port has been released by Richard Bannister. You can get it at Richard's web page: http://www.bannister.org/software/kigb.htm 1. System Requirements A. Win95/98/Me/XP/NT/2000 CPU : Pentium (minimum), Pentium II+ (recommended) RAM : 16 MB free Display card : DirectX supported Sound card : DirectX supported Color depth : 16-bit or higher Network : TCP/IP (for link cable support) DirectX : V3.0+ B. Linux CPU : Pentium (minimum), Pentium II+ (recommended) RAM : 16 MB free Display card : many (supported by Allegro) Sound card : many (supported by Allegro) Color depth : 16-bit or higher C. MS-DOS CPU : Pentium (minimum), Pentium II+ (recommended) RAM : 16 MB free Display card : many (supported by Allegro) Sound card : many (supported by Allegro) Color depth : 16-bit or higher Joypads/joysticks are optional. The performance bottleneck is on the blitting (drawing) to the screen. So, the screen size and color depth will have great impact on the performance. Here are my suggestions on the settings for different processors: CPU Screen Color Depth Frame Skip ------------------ ------------ ----------- ---------- PIII+ any >8 0 PII and Celeron FS, 1x1, 2x2 16 0 Pentium FS, 1x1, 2x2 16 0, 1, 2 FS = Full Screen The above is my estimation only and the performance varies games by games. In general, if you find KiGB runs slow in your computer, first turn off all other applications. Then, set the color depth to 16. Turn off video filters. Turn off Mix Frame option. Try full screen mode. If the speed is still slow, try frame skip 1 or 2. Starting from V1.63, a PII can run in full speed with the following settings (most are the default): - full screen or 2x2 - 16-bit color depth - frame skip 0 - sound on with 44100 sampling freqency - all filters off - mix frame can be on or off 2. Features - Game Boy, Game Boy Color and Super Game Boy (SGB and SGB2) emulated - Best compatibility and accuracy both in graphics and sound - Game Link Cable supported (allows 2 players to play over a network) - MBC1, MBC2, MBC3, MBC5, MBC6, MBC7, HuC1, HuC3, Rocket and MMM01 supported - All 4 sound channels and digital sound supported - Battery supported - Real time clock supported (adjustable) - Pre-defined switchable palettes for GB mono games in GBC mode (12 of them and some specific games have their own palettes, as in a real GBC) - Zipped and gzipped files supported - Screen size: 1x1, 2x2, 3x3 and full screen - Frame skip supported - Joypad supported - GameGenie and GameShark cheats supported - Screen dump supported - Save states supported - Close color as a real Game Boy Color - Input playback supported - Save states and input files are compressed - Battery save, save states and input files are portable across all supported platforms, currently MS Windows, Linux and MS-DOS - Default border image supported - Up to 4 players are supported (SGB only) - Gameboy Printer supported - Per-game configuration - Sound wave file output - Customizable Gameboy palettes - Adjustable emulation speed - Graphics filters: Super 2xSaI, Super Eagle, scanline and bilinear - Special effect: sprite shadow (experimental) - Mix Frame (required by quite a number of games) - Generic flashcart supported (required by many PD, hacks and trainers) - Demotronic Trick supported - 5-speed auto-fire - Barcode Boy supported - GB boot ROM supported (boot ROM not included) - Simulate the startup code in GBC mode - Gin & Tonic Trick supported 3. Known Issues All ports ========= - The following features are not yet supported/emulated: * Infrared communication port * Camera functions in Gameboy Camera * TAMA5 * Rumble * External devices: barcode reader, mobile adaptor, full changer and GPS receiver. * The network update service of MBC6 MS-DOS ====== - May have problems on long file names in pure MS-DOS environment. - Game Link Cable not supported. - Sound quality is not as good as the window port. - Scrolling is a bit jerky. - It may have problems under Windows XP DOS prompt. In Windows 9x/Me, it should be fine. Linux ===== - The distributed executable was linked statically to Allegro but not for the others starting in v1.31 (I got a message "Aborted" when running a copy which linked all libraries statically under Red Hat 8.0 and Allegro 4.0.3. I did not encounter such problem in Allegro v4.0.2). If you are using Red Hat Linux 8.0 (my development platform), you should have no problems. - Support x86 platforms only. - Scrolling is a bit jerky. 4. Distribution Files All ports ========= readme.txt - This file faq.txt - As named cheat.txt - General info on the supported cheat feature kigb-ggs.txt - Specification of the cheat library file kigb.cfg - A sample configuration file changes.txt - Changes between releases link.txt - Read it before start using the Game Link Cable feature sgb.txt - Contains the current emulation status in Super Game Boy barboy.txt - Contains the usage information on Barcode Boy barboy.cod - Contains a sample code for loading to Barcode Boy Windows ======= kigb.exe - The emulator executable alleg40.dll - DLL file of Allegro for Windows zlib.dll - DLL file of zip support for Windows HawkNL.dll - DLL file of the HawkNL network library pthreadVCE.dll - DLL file for use with HawkNL Linux ===== kigb - The emulator executable libNL.so.1.6.4 - The HawkNL library MS-DOS ====== kigb.exe - The emulator executable 5. Getting Started Extract all the files from the zip (Windows and DOS) or gz (Linux) file. It will create the following 7 sub-directories for you: doc - contains documentation of KiGB rom - places your ROM here save - battery saves are stored here snap - snapshot or screen dump files state - save states files inp - input files cfg - per-game configuration files (All except doc are configurable. See Section 6 below.) If you run KiGB with a file name, KiGB will search the absolute path of the rom first. If it can't find one, it will try the ROM_PATH (default 'rom') directory. See Configuration section below for details. If you omit the file extension, KiGB will search for .gb, .gbc, .sgb, .zip and .gz in order automatically. If no file name provided, a blank window or screen with the main menu will appear. To run a game, select File->Load ROM.... To run a recently played game, select File->Recent. During game play, you can open the main menu by pressing the Tab key or pressing the left or right mouse button. To resume game play, press the Esc key. The following 5 sub-directories must be created in order to have the corresponding features supported: save - battery save files and real time clock data files snap - screen dumps state - save states inp - input files (for recording and play back input keys) cfg - per-game configuration files (see below) Per-game configuration files allow each game having its own configuration settings including keyboard/joypad mapping, windowed/full screen, screen size, sound options, border options, external devices, emulation types, perferences and speed, and customized palettes. This feature is particularly useful for games better played with non-standard key mappings such as pinball games. Select Option->Configure->Per Game Config to toggle it on or off. When a game is loaded the first time, it will 'inherit' the settings of the last game played. Any subsequent changes on the settings will be saved. When the same game is re-loaded, all its configuration settings will be restored. For Linux ========= Starting from v1.11, KiGB is linked statically except the HawkNL library. To set up HawkNL library, copy the file libNL.so.1.6.4 to /usr/local/lib. For Debian and maybe other Linix distributions, this file has to copied to /usr/lib (thanks Andrzej Lupa). Then, change directory to /usr/local/lib or /usr/lib. Add a soft link: ln -s libNL.so.1.6.4 NL.so.1.6 You have to be root to do this. To enable full screen mode, you may need to update the /etc/XF86Config file. See faq.txt. If your IP addresses are not listed when you are a host (see link.txt about what is a host), follow the steps below: - note your host name by issuing the command hostname - edit the /etc/hosts file to add a line or lines for the host name with the IP addresses (you need to be root to do this) - if you have multiple IP addresses for the host name, edit the /etc/host.conf file to add the following line: multi on The above line should start at the first column and you need to be root to do this. If the IP address is still not appeared, move the line containing the desired IP address to be the first one among the same host name entries in the /etc/hosts file. 6. Configuration To configure KiGB, open the main menu by pressing the Tab key or clicking the left or right mouse button. Select the options you want to change. The settings will be stored in a file name kigb.cfg when you quit KiGB. If the file does not exist, KiGB will create it; otherwise, KiGB will overwrite it. Do not edit the kigb.cfg file directly. When you run KiGB the first time, some important default settings are: - path: the 7 sub-directories created (see Section 5 above) - screen size: 320x288 windowed mode (Windows and Linux) 640x480 full screen mode (MS-DOS) - border: on - emulation types: GB, GBC and SGB - emulation preference: GBC with SGB border - emulation speed: 100% - frame skip: none - sound: all channels on, stereo, highest sampling rate, middel volume and no pan - hot keys: F1 - F10 - load save states F11 - play input files F12 - dump screen Shift+(F1 - F10) - save save states Shift+F11 - save input files Ctrl+0 - full screen Ctrl+1 - 1x1 screen size Ctrl+2 - 2x2 screen size Ctrl+3 - 3x3 screen size Ctrl+B - toggle border on/off Ctrl+O - open ROM Ctrl+P - pause Ctrl+R - reset Ctrl+S - toggle sound on/off Ctrl+X - exit Ctrl+, - lower emulation speed by half Ctrl+. - double the emulation speed Ctrl+[ - decrease frame skip by 1 Ctrl+] - increase frame skip by 1 Ctrl+(F1 - F8) - load recent ROMs For GB mono games running in GBC mode only: ------------------------------------------- Shift+`(~) - set default palette Shift+1(!) - brown Shift+2(@) - red Shift+3(#) - dark brown Shift+4($) - pale yellow Shift+5(%) - orange Shift+6(^) - yellow Shift+7(&) - blue Shift+8(*) - dark blue Shift+9(() - gray Shift+0()) - green Shift+-(_) - dark green Shift+=(+) - reverse - key mapping: Enter - start button N - select button A - A button S - B button Arrow keys - corresponding to the direction keys You can set alternate hot keys for exit, reset and pause. Select File-> Key Mapping->System... After KiGB exits, the current settings will be saved and a new kigb.cfg file is created or replaced. WARNING: KiGB does not validate the key mapping settings. If you map the same key to more than one buttons or direction keys, strange behavious will result. If you find the configuration file is corrupted, simply delete it. The default settings will be restored. 7. Cheats Both GameGenie and GameShark cheats are supported. To enable/disable cheats, show the menu and select "File->Cheat". Then select "Game Genie" or "Game Shark". See cheat.txt for more details. 8. Screen Dumps Press F12 during game play will dump the current screen in PCX format with the resolution 160 x 144 or 256 x 224 depending the border is on or off. Screen dumps can be found in the snap sub-directory by default. 9. Save States Press Shift+F1 to Shift+F10 during game play will save the current game state to slot 1 to 10 correspondingly. To load back the saved states, press the corresponding F1 to F10 during game. You can make use of the GUI menu to save/load game states. In addition, you can also edit the description of the game states. The default description is the current date/time of the game state. 10. Input Files Press Shift+F11 to record the input for future playing back. A dialog box will appear asking you whether you want to record here or at the begining. If you select here, the current state will be saved and the recording of input is started immediately. If you select begin, the game will be reset automatically and the recording of input is then started. Press Shift+F11 again to stop the recording. To play back the input file, press F11. A file selection dialog will appear. Select the appropriate input file for play back. Press F11 again to stop the playback. You can make use of the GUI menu to record/play back the input files. 11. Game Link Cable KiGB emulates the Game Link Cable. 2 players can play over a TCP/IP network. Read the link.txt file for details. Cascading of Game Link Cable to support 4 players (games like Mahjong Quest) is not supported. Someone notified me that this feature was broken in Vista. It may be caused by the incompatibility of the HawkNL library to Vista. 12. Super Game Boy SGB emulation is not complete. See sgb.txt for the emulation status. 13. Future Work - Infrared communication port (possible???) - debugger 14. Warranty KiGB comes with no warranty. Use it at your own risk. 15. Disclaimer Use of this emulator with copyrighted ROMs which you don't own is ILLEGAL. You will take full responsibilities if you choose to do so. 16. Special Thanks (in no particular order) nocash, for the updated version of the original gbspec.txt. kOOPa, the creator of the gbspec.txt. Shawn Hargreaves, for his wonderful game libaray - Allegro. Bas Steendijk, thanks for the valuable info. (He is the author of the cool Gameboy, Gameboy Color and Super Gameboy emulator called bgb. I recommend you to try it out.) Mihai Dragan, thanks for helping to port KiGB to Linux. Phil Frisbie, for the excellent network library - HawkNL. Kreed, for the great graphics filters: Super 2xSaI and Super Eagle. Scott Nash, for the thorough testing of KiGB on huge volumes of games and demos. Without him, KiGB will never reach the current level of compatibility and accuracy. Anna Kubisty, for the verification of games running on a real GB/GBC and dumping of rare games. She hosts a web site called "Retro den" at http://www.retroden.co.uk/. In there, you can find her verified GBx collection. You can download her little but wonderful program "Pocket GBx" to see the collection offline. Pocket GBx works with KiGB. If you have any games not on the list, send them to her. Toshi, for the valuable information about MMM01 and MBC6. Aren (my wife), for her patience and support. 17. Support Please consider support KiGB by making a donation. You can send your donation via PayPal (www.paypal.com) by clicking the donate button in my web site. 18. Contact The official KiGB web site : http://kigb.emuunlim.com e-mail address : k*i%g-b@emuunlim.com (remove *%-)