:: gp2xmess readme ::

    gp2xmess is a port of the xmess (www.mess.org) emulator to the gp2x
    handheld. xmess is the XWINDOWS port of mess which is a multi-system
    emulator and is capable of emulating many different computers and game
    consoles. For more details on mess and xmess visit their website at
    www.mess.org.  This readme mostly covers the gp2x port.  See the mess
    README file for more info on how to usee mess in general.

    Currently this port uses SDL. I'd like to keep it that way since
    SDL is a supported library for xmess. However, in the future, if a
    significant increase in performance can be achived by switching to a
    different library, I will consider it after all other options have
    been exhausted.

    *********************************************************************

    NOTE:

        If you have issues running roms/cars/images under gp2xmess,
        please try and verify that the image works under either mess or
        xmess proper before contacting me. I will try my best however to
        help diagnose any issues.  Also read the FAQ and help sections
        below.

    *********************************************************************

:: gp2xmess requirements ::

    A gp2x handheld  :)
    The BIOS for the system you are trying to run (if needed)
    Some games/programs for the emulated system

:: running gp2xmess ::

    To run gp2xmess you have to use a launcher script with the 
    appropriate arguments.  These are provided with gp2xmess and
    have a .gpe extension.

    Tested systems will have a .gpe startup script included with the
    gp2xmess package. The launcher scripts follow the convention
    system_name.gpe. i.e. a7800.gpe for the Atari 7800 emulator. a7800
    is the mess driver name.
    
    The gp2xmess package *DOES NOT* come with the BIOS roms or any
    software for emulated systems. It is up to the user to hunt these
    down due to copyrights. Please do not ask me for these.  All needed 
    bios zip files should be placed in the bios subdirectory which 
    should have been provided and empty in the gp2xmess package.  Do
    *NOT* unzip them.  Just place the zip file for the BIOS in the 
    bios directory.  The BIOS zip file itself has to be the same name 
    as the driver you are trying to run.  If you are unsure of the 
    driver name the .gpe launcher is always named the same.

    For instance:

        The Texas Instruments 99/4A driver is called ti99_4a.  The gpe
        launcher file for this driver is called ti99_4a.gpe (by my convention).
        xmess requires that the BIOS file also be named in the same manner.
        In this case it would be ti99_4a.zip.

    Some systems will prompt for an intial cart or disk to bootstrap the
    system. In this case a file selection dialog will come up prompting
    for the file to use. While using the emulated system the main menu
    is used for further file selection/changes.

    Roms/disks/cassette images can go anywhere you'd like.  The pre-launch file
    picker (for systems like the Atari 7800) and the in emulator file selector
    (brought up by the right shoulder button) allow you to move around directories 
    so you can place them anywhere in any directories desired.

:: gp2xmess controls/input ::

    Main menu:

        Once in gp2xmess by default the left "shoulder" button will toggle the
        main menu. The joystick up/down moves through the menu and the 'A'
        button selects. These can all be remapped if desired via the Input
        menus. Seem the mess readme for more details.

        From here you can:

            - Map any of the inputs to any button you wish both for
              the current system and globally for all systems. 
            - Restart the emulated system  (somtimes necessary after
              changing carts/images)
            - Use the file manager to select a new cart/rom/disk 
              image/save state 
            - Exit gp2xmess

    Initial file selection dialog:

        Moving the joystick up will move the selection pointer up

        Moving the joystick down will move the selection pointer down

        Pressing the A button will cd into a directory if selected or use
        the file as input for the emulator if selected
        
        Pressing the Start Button exits the program

    To get past any OK dialogs that may pop up, you can move the joystick 
    left and then right to dismiss them.

    The volume buttons are by default mapped to control the volume. If
    and when systems that will look better in a vertical orientation are
    supported (vectrex) the volume buttons can be mapped to another input 
    just like any other button if desired.

:: gp2xmess virtual keyboard::

    gp2xmess uses a virtual on screen keyboard to allow input to both gp2xmess
    and the emulated system being run.  The default mapping of the virtual
    keyboard is the right "shoulder" button.  This can be remapped to a different
    joystick button if desired (though not recommended) via the input mapping
    menu.

    The keyboard emulation has 2 modes.  You can toggle between these 2 modes by
    using the virtual keyboard's Scroll Lock key ('sl').  This behaves exactly
    as it does in the standard mess/xmess software.  Pressing Scroll Lock toggles
    between the keyboard input going to gp2xmess itself (the UI portion) and
    sending all of the keyboard input to the emulated system.

    For example by default the 'P' key is mapped to 'Pause' within the gp2xmess
    GUI.  This pauses the emulated system.  When using the emulated system you 
    will not want the P to do that but rather enter a P as if you had typed it 
    on the system you are emulating.  You toggle this mode by pressing the Scroll
    Lock key.  A short popup dialog will show you which mode you are in when
    pressing the Scroll Lock key.  It is *highly* recommended that you do not
    remap this key within the UI.

    Any joystick button can be mapped to a key within the emulated system.  Doing
    this means that the keyboard key that normally would do the same is no longer
    able to do this.  What you need to do is after mapping, for example, the '1'
    key to the 'X' button on the GP2X be sure to then also map the '1' key to the
    '1' key using the virtual keyboard.  This insures that both methods will input
    a '1' into the emulated system.

    Currently the keyboard that is displayed is a (mostly) full PC keyboard
    layout.  Each emulated system that uses a keyboard has it's own mapping
    for mapping it's keyboard to a PC keyboard.  In the future I plan on
    displaying the keyboard layout as seen on the emulated system to make it
    easier for the user to know which key is what.

    The shift, ctrl, and alt keys are toggles.  When selected they act as if they
    were being held down.  A red rectangle is drawn around them when they are
    being held down.  To simulate an actual press of the button, select the key
    and press the 'A' button twice.

    When the shift key is pressed the shifted keys should be displayed on screen.

:: building gp2xmess ::

    The source archive includes files that are in addition to the xmame/xmess
    source.  There is also a patch that must be applied to the xmess
    source code before building.

    To build gp2xmess modify the makefile.gp2x by changing the
    BUILD_TARGET to gp2x. To build gp2xmess to run on your host
    UNIX/Linux/BSD machine change BUILD_TARGET to x. That should be all
    you need to change. This makefile assumes you have the open2x
    cross compiling environment installed and in your path to build
    the version for the gp2x. The arrow keys and enter key act as the
    joystick and A button respectively.

    You can build using the host tools by changing BUILD_TARGET to 'x'.
    This by default will be a debug build w/ gprof support.

    Run make -f makefile.gp2x after making the above changes to build
    the executable.  The binary names should be xmess for gp2x host and
    gp2xmess.gpe for the gp2x binary.

    There are also CFLAGS and LD options for building debug, gprof, and asm
    output w/ saved temp files for viewing generated asm by gcc.

:: gp2xmess driver compatibility/notes ::

    Unless a driver is listed here it hasn't been tested/tried yet.

    a7800 (Atari 7800):

        This driver runs at a decent speed 75% w/ frameskip.  Overclocking brings 
        this driver almost to full speed.

        xmess will not run without a cartridge inserted in this system so a file
        selection dialog will appear before starting the emulation.  Here you will 
        choose the initial cartridge to use and after that the main menu can be 
        used for changing cartridge images.

        The 'Select' button on the gp2x maps to the 'Select' button on the Atari
        7800.  The reset button can be mapped to any control you would like
        via the gp2xmess menu (Left shoulder -> Input (this system)).

    adam (Coleco Adam Home Computer:

        This driver runs but I have no way currently to test it.  Until I find
        some disk images I have no way to know how well it runs.

    coleco (Colecovision):

        This driver runs quite well.  Games tested so far run at close to full
        speed with no frameskip.

        The virtual keyboard for this system shows the keypad.

        The 'Start' button on the gp2x maps to the '1' button on the Coleco
        keypad.  Other buttons can be mapped if desired via the gp2xmess 
        menu (Left shoulder -> Input (this system)).

    ti99_4a (Texas Instruments 99/4A Home Computer):

        This driver runs quite well.  Games tested so far run at full
        speed with the default frameskip.

        The '1' button is currently mapped to the Start button on the gp2x.
        The '2' button is currently mapped to the Select button on the gp2x.

    arcadia (Emerson Arcadia 2001):

        From what I can tell a BIOS is not necessary for this system.

        This driver seems to run well.  I don't have a lot of experience
        with it so I'd appreciate feedback on it.

        The 'Start' button is currently mapped to the Start button on the gp2x.
        The 'Option' button is currently mapped to the Select button on the gp2x.

        The virtual keyboard for this system shows the default PC keyboard layout.

        xmess will not run without a cartridge inserted in this system so a file
        selection dialog will appear before starting the emulation.  Here you will 
        choose the initial cartridge to use and after that the main menu can be 
        used for changing cartridge images.

    coco (Tandy Color Computer)

        This drivers run OK, somewhat slow.  Overclocking helps here.

        With coco Color BASIC 1.0 doesn't seem to support disk commands so you
        can't run those. I did find some .pak snapshots that run such as
        pooyan.pak. I have yet to find a BASIC program that runs without
        syntax errors so I'm assuming that extended color BASIC would
        run these.  Your best bet is running coco2 or coco3 when they are
        supported.  These have EXTENDED BASIC.

    odyssey2 (Magnavox Odyssey 2):

        This driver runs at a decent speed but compatability is very low.  It
        seems only 2k carts are currently supported in core mess.  I am currently
        working on this.

    apple2  (Apple II):
    apple2e (Apple IIe)
    apple2c (Apple IIe)

        These drivers run somewhat slow (75%) but so far compatibility seems 
        very good.  Overclocking helps w/ emulation speed.  Your best bet for
        compatibility is to try the 2e and 2c drivers first.

:: gp2xmess license ::

    Use at your own risk. I'm not responsible if it hoses your gp2x.
    Standard disclaimers apply.   :)

    All I ask is that I'm made aware of changes so I can incorporate
    them into my version, that and my contact info stays in the gp2xmess
    package. This version of mess uses the same license as xmess.  Please
    go to www.mess.org for more details.

:: gp2xmess help ::

    If the emulator exits almost immediately after launching chances are you 
    either do not have the BIOS installed correctly or it is an incompatible
    version.  There are sometimes changes made to the names of the files expected
    in the BIOS so these need to be up to date.  This port of xmess is based on
    xmess .102 so verify that your BIOS is compatible with that.

    Feel free to email me (bsturk@comcast.net) with issues regarding
    gp2xmess or if you've found a bug etc. Please read this file, the
    CHANGELOG, and the TODO to see if I already know about the issue,
    or is a known limitation before contacting me. If you do email me
    please include the output of running the program by adding the
    following to the .gpe file for the system you are having issues
    with.  Add this to the end of the line that starts gp2xmess

        > debug.txt 2>&1

    After exiting the emulator there should be a file called debug.txt
    present.  Please send that to me.

    Also, please try and verify that the same issue *doesn't* 
    happen with a more stable version of mess, such as the WIN32 mess 
    or xmess.

:: gp2xmess FAQ ::

    Q: gp2xmess exits immediately after starting
    A: 99.9999% of the time it's because you do not have the correct BIOS rom.
       Please see the above sections regarding this.

    Q: Oregon Trail doesn't run w/ the Apple ][, is it my disk image?
    A: I have successfully run Oregon Trail using the 2c emulation.

:: gp2xmess info ::

    The latest version is always available @
         http://users.adelphia.net/~bsturk/gp2x.html

    Please support the mess project if you can in any way.  
    They are the folks that really made this possible!!

    Please send bug reports, suggestions, and other email to
        bsturk@comcast.net

    I can also usually be found on #gp2x and #gp2xdev on EFNet.
    Or on the gp32x.com forums.  My handle is 'telengard'

vim:tw=82:
