Readme File for KiGB - a free portable emulator for Game Boy, Game Boy Color and Super Game Boy by Ricky Liu.

KiGB v2.02

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.

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). Only a few ones are found with minor issues. If you find any bugs, please notify Scott:

nash67@hotmail.com
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 can only be 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

System Requirements
1. 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+
2. 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
3. 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)
MBC 1, MBC 2, MBC 3, MBC 5, MBC 7, HuC1, HuC3 and Rocket 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.

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. Then, change directory to /usr/local/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, right-click and then select Cheat in the menu. 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.

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.

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

    For bugs reports           : nash67@hotmail.com (Scott Nash)
    Other issues               : kigb@emuunlim.com (Ricky Liu)