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

KiGB v1.60


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 has started a project to improve the compatibility and
    accuracy of KiGB. We will test all the games and demos in the GoodGBX
    ROM set (over 6,000). Games which are not supported properly or behave
    strangely in KiGB will be further tested on a real GBC. Our target is
    to make KiGB as close as the real one. So far, we have completed games
    start with #'s, A's to Q's. If you find any bugs, please notify Scott:
        nash67@hotmail.com
    Please place "[BUGS]" before the subject.

    Though the project has not yet completed, we believe KiGB already
    provides the best compatibility and accuracy in graphics, sound and
    timing. Prehistorik Man among others can only be emulated perfectly in
    KiGB. Please see the compatibilty page in my web page for results on
    the compatibility tests on KiGB and 4 most popular and highly-rated
    emulators.

    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.  Performance

    The 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 or 1
      Pentium               FS, 1x1             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.


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, HuC1 and HuC3 supported
    - All 4 sound channels and digital sound supported
    - Battery supported
    - Real time clock supported
    - 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)


3.  Known Issues

    All ports
    =========
    - The following features are not yet supported/emulated:
      * Infrared communication port
      * Camera functions in Gameboy Camera
      * MBC7 and TAMA5
      * HuC3 real time clock
      * Rumble
      * Demotronic Trick

    Windows
    =======
    - In Win 9X/Me, scrolling horizontally and vertically is jerky on some
      games. No problem in Win XP. This may be a bug of Allegro.

    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

    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.


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

    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 will appear. Press
    the right mouse button. A menu will appear. To start a game, select
    "Load ROM...".

    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, GB Printer on/off, emulation types,
    perferences and speed, and customized palettes.

    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, right-click to open the menu. 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
        - key mapping:
              ESC              - exit             (not configurable)
              keypad *         - reset            (not configurable)
              F12              - dump screen      (not configurable)
              F1 - F10         - load save states (not configurable)
              Shift+(F1 - F10) - save save states (not configurable)
              F11              - play input files (not configurable)
              Shift+F11        - save input files (not configurable)
              Enter            - start button
              N                - select button
              A                - A button
              S                - B button
              Arrow keys       - corresponding to the direction keys

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

    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, for the verification of games running on a real GB/GBC.
    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)
