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