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


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)
    - 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)
