Castaway/GP - An Atari ST emulator for GP32
Jeff Mitchell, Codejedi

"Castaway" Atari ST emulator originally by Joachim Hoenig. "CastCE" port for Pocket PC by Ludovic Olivencia and Andrew Gower. "Atari" is copyright "Atari", "Infogrames", and whatever else they may be called now.

Credits

This emulation core is entirely derived from the SourceForge Castaway and CastCE projects; credit must go to them first and last to me for this work would not have been possible without them. The GUI, games database and GP32 work and many extensions are all homegrown. Database content is donated fro the public as part of a project to catalogue Atari ST games.

Thanks also to the great community that has come up around Castaway/GP! The games database is mostly populated by data submitted by users of the appliaction. The compatability website is donated (thanks DWN!) and the data is again entered by you guys. Thanks for the eternnal comments and questions that drive me forward!

Thanks to the developers of yesteryear who made the Atari ST scene what it was :)

Useful Links and Contact Information

Of course, the Castaway/GP homepage is useful: Codejedi Castaway/GPM

Visit us at:
http://www.codejedi.com -- click on "GP32" under "XCade"

Or write:
support@codejedi.com

Other assorted links:

Status and Compatability

Castaway/GP is very stable and highly compatible. Crashes are rare if you ever see one at all, and most Atari ST game disk images will work well.

We recommend using disk images of original disks where possible; the various crack groups sometimes made the game loaders more complex than needed, or broke the game a little, etc. Original disks tend to be more compatible than cracked ones.

File Extension Reference

Various file extensions are used by Castaway/GP. In general you needn't concern yourself too much, but for reference here they all are:

.STTAtari ST raw disk image (.ST renamed to .STT)
.MSAAtari ST compressed disk image (Magic Shadow Archiver)
.ZIPAtari ST raw or compress disk image, zipped
.RAWA Castaway/GP savestate for fast loads
.SAVAn Atari ST raw disk image saved from emulation (a savegame probably)
.CNFCastaway/GP config file
.TXTCastaway/GP config file
.IMGAtari TOS ROM (dumped from ROM chips)

Installation

First Time Installation

  1. Create an ATARIST directory within GPMM on your GP32. gp:\GPMM\ATARIST is the full path

  2. Find yourself an Atari TOS ROM image file. TOS is the Atari ST basic operating system and is needed for anything to run. You may dump one from an Atari ST or find one somewhere. You may find one called TOS_102.IMG, or ROM, or TOS.ROM or whatever, but make sure its installed as TOS.IMG (thats what Castaway/GP looks for!). Just rename it to TOS.IMG before uploading to the GP32. (You can use other .IMG names, but then you'll have to select them in the menu each time you run Castaway/GP!)

  3. Copy castaway.fxe into GPMM (this is where Free Launcher looks for applications and games)

  4. Install any disk images you want; they must end in 3 characters and be no more than 8 characters in the main filename. They should not end in .IMG unless they are TOS ROM images.

    It is recommended you use .STT for your disk image filenames. Most disks you will find are .ST or .MSA. The .MSA files are already fine since they end with 3 characters, but you'll need to rename the .ST ones. Changing them to .STT or .FOO or .STZ or whatever you want is fine.)

    .ZIP's of .MSA or .ST are fine to use, though you won't be able to look them up in the game database unless they are unzipped!

  5. You must have at least two disk images.. one for Drive A: and one for Drive B:. By default, Castaway/GP will look for DISKA.STT and DISKB.STT, and we've included some nearly blank ones in the distribution to make sure you've got some.

    Installing these are optional, but they are handy to have there so that the default installation works and so you can get a GEM Desktop if you want it.

  6. Optionally install STGAMES.TXT into your ATARIST directory -- this will let you look up disk images to find out what games are in them. For example most disk images you find will be named something like "A_097.ST", which isn't really descriptive. You will need to rename it to A_097.STT in order to use it, anyway, but thats still of no use to knowing whats on that disk. But if you install STGAMES.TXT into ATARIST directory, you'll be able to press SELECT to get a list of what games are there!
DISKA.STT and DISKB.STT are dummies that don't have much useful stuff, but they do boot to the desktop so you can mess around.

Recommended TOS Versions

Castaway/GP supports the TOS 1 series, which is to say TOS 1.0, TOS 1.02 ("1.2"), 1.04 ("1.4", "Rainbow TOS"), and even some others like KaosTOS. The TOS 2 and later are not supported.

It is recommended to use TOS 1.02 for maximum compatability, however. TOS 1.0 had some bugs while TOS 1.4 was a superior TOS overall, didn't like all games. Since your'e not using the Atari ST for serious work, game compatability is your main concern here.

So use TOS 1.02

Recommended Disk Images

For maximum compatability, it is usually best to work with disk images made from the original disks of a game. Often the cracking process or the cracking groups compressed loader or the like introduced some complexity that coudl screw up Castaway/GP, or sometimes even a real Atari ST. Most cracked disk images will work well, but a few have shown problems that originals have not.

For example.. it is known that Automation 97 (Dungeon Master and OIDs) will not work with TOS 1.02 on Castaway/GP, but will work with TOS 1.04 in Castaway/GP. However, the original Dungeon Master disk images will work on any version of TOS that Castaway/GP supports.

Upgrading Castaway/GP

You can at any time head over to Codejedi's Castaway/GP homepage to find the latest versions of the application or the game database.

Upgrading is generally easy... copy Castaway.fxe into your GPMM directory on your GP32, and copy any files from the distributions ATARIST directory into your GP32's ATARIST directory. Easy.

Upgrading Game Database

You can at any time head over to Codejedi's Castaway/GP homepage to find the latest versions of the application or the game database.

The latest game database at the time of a distribution is usually included in the distribution, but it is common for the games database to get updated many times each week while the main Castaway/GP distribution is not updated. The main distribution is only updated for application updates, not for every database update we receive!

As such, you may wish to update your games database. Just download the latest stgames.txt file from the website. For example, you might find ST Games Database 2.1 on the website, and it would for that version be called stgames21.txt. The GP32 ATARIST folder must have an un-numbered version installed, however.. so simply download the games database and rename it from stgames21.txt to stgames.txt, and install into your ATARIST folder on the GP32. Voila!

Running Castaway/GP

Introduction Screen

The introduction screen just shows the application credits and a little bouncey-text demo in the tradition of Atari ST demos.

Push any GP32 button to dismiss the demo and head into the Disk Picker Menu and the emulation proper.

Working With the Menus

Castaway/GP uses a simple but elegant menu system. Whenever a blue selection menu is present, you can operate it like this:

Note that START, SELECT and LEFT SHOULDER get over-ridden in the disk selection menu.

Disk, ROM, Config, Deletion Menu

This menu primarily lets you insert floppies into the Atari ST's disk drives so you can run them. You can also pick TOS ROM's (in case you have multiple versions installed, or didn't call one TOS.IMG), pick Config files, or delete things you've lost interest in.

As directed, insert a disk into Drive A: by pushing the GP32 "A" button. Insert a disk image into Drive B: by pushign the GP32 "B" button. If you don't pick anything for A:, "DISKA.STT" is used by default. Likewise for Drive B:, "DISKB.STT" is used.

Typically you will launch Castaway/GP, scroll up and down to find a disk of interest, push A, and push Start. Thats all you need to know!

Pushing SELECT will look the file up in the games database and display any search results. In certain versions, the resulting game list will be shown to the right of the filename this time and in the future.

Toggle into Game Listing Menu

Note that the disk picker menu can run in one of two modes at any given time; in normal mode, the disks are shown on the left, and on the right is a tight fitted summary of whats on the disk. Due to space constraints, only a few disks can fit on there at a time.

However, you can toggle into "game listing mode" using the Right Shoulder button, and use it again to toggle back to normal mode. In Game Listing Mode, the display shows a game on the left, and which disk it is on on the right. The trick here is that Castaway/GP has to *guess* what games are on your disk images based on its game database and cache system. So no games will show up in the listing until you've looked them up in the database by hitting SELECT on the disk. Once you have looked the image up in the database, the system will try to remember what games its intuited are present, for displaying in this game listing mode.

This is a very handy view for running games -- look the game up by name rather than trying to remember what disk image its on!

Things you can do:

NOTE: Whenever you change something from the disk menu, the display will be updated to reflect the change. Setting a disk A: will put "A:" beside the new disk in Drive A:, so you know you picked something. Setting a TOS will put "ROM" beside the new ROM image. Picking a .CNF file will show "CNF" beside it so you know you've loaded it at some point, etc.

NOTE on Insert: If you try and insert a disk image into a drive that already has an image in it, Castaway/GP will automatically eject the existing disk image for you, and then insert the new disk.

Game Lookup Database

The games database is included as stgames.txt in every distribution. When you push "SELECT" while in the disk picking menu and a disk is selected the disk will be looked up in the games database. If an exact match is found there, the listing of games will be shown onscreen so you know what is on the disk.

The games database has been built up by volunteers.. people just like yourself. If you would like to help add to the games database, write to support@codejedi.com and let us know!

The games database is fairly complete currently, in that it has all the Automation disks, all the Super GAU disks, all the Zuul and Medway and Pompey Pirates disks, and various other ones. But it is not 100% complete by any means. We have tried to put both .ST and .MSA versions into the database but if your disk image has a different number of tracks or sectors, or is perhaps an alternat version, or perhaps has an anti-virus or the like in it, then it may not match up to anything in the database. If you have a lot of disks that don't turn up results, perhaps consider contacting us to add your disks into the database!

Runtime Input Modes

Due to the variety of input devices the Atari ST could take, you must select which one is being fed by the GP32 controls. For example, you can have the GP32 working the ST mouse, joystick or keyboard. We've also added our own pseudo-inputs to handle various things like setting Frameskip.

The default input mode is Mouse-mode. All other modes will indicate at the bottom of the screen what mode you are in.

Changing modes is done a variety of ways:

Each input mode operates a little differently. Here are what the GP32 buttons do in each mode.

All-modes (except Custom)

Start Pause and open up the Options Menu (this is available in Custom mode)
Select Enter Frameskip mode, or return to the last mode you were in before entering frameskip mode.
L-Shoulder Keyboard toggle - Jump straight to keyboard mode (remembering the mode you were in), or returning to the previous mode if you had already used this to jump to keyboard mode.

Mouse-mode

D-Pad Pushes mouse around
B Pushes left mouse button ("B" is left button on GP32)
A Pushes right mouse button
R-Shoulder Go to Cursor mode. A quick way to use the cursor keys!

Cursor-mode

Useful for Dungeon Master, Captive, RPG's, Wargames, etc etc.
D-Pad Pushes ST cursor keys
B Pushes Insert (turn left)
A Pushes Clear/Home (turn right)
R-Shoulder Go to Mouse mode. A quick way to toggle between mouse and cursor keys!

Keyboard-mode

Shows a virtual keyboard on screen

There are some notes. A few keys have multiple spaces assigned to them, such as "Es" for ESCAPE. Hitting "B" on either "E" or "s" will get you an escape character, for conveniance.

"SS" on the keyboard is actually two separate SHIFT keys.. the left shift and the right shift. Pressing "B" on the left "S" will get you the left shift press.

Holding down versus a key press

Note that pressing "B" on a key will push and release it, and pressing "A" on a key will either push *or* release it. This lets you hold a key down while you go to do other things. For example, you might want to "A" to hold Shift down while you go and "B" to press a keyboard letter. This would let you enter caps into a word processor, for example.

Colour Codes

The virtual keyboard is drawn in blue. The current "cursor" is the key shown in red. A key being held down is shown in green.

D-Pad Select key
B Pushes key once
A Toggles a key down or up; the first "A" on a key will press it, and the second "A" will release it. This lets you hold a key down.
L-Shoulder If you jumped to keyboard mode using Left-Shoulder, this will jump you back to the mode you were in before.
NOTE: You can go off any side of the virtual keyboard to wrap around to the opposite side. Can be handy to get around faster.

Joystick-mode

Shows "Joystick" on bottom of screen so you know what mode
D-Pad Push joystick
B Push fire button
A Push "up" on joystick; may be easier "jump" for some games.
R-Shoulder Push spacebar. Handy to avoid jumping to keyboard mode.

Frameskip-mode

Shows "Frameskip ##" on bottom of screen so you know what frameskip value is currently set. Frameskip is used to suppress rendering of the emulated ST monitor, and thus speed up the emulation. Good for skipping through disk loading and other uninteresting aspects of using a computer.
D-Pad (left/right) Decrease or Increase frameskip (speed of emulator)
D-Pad (up/down) Decrease/Increase frameskip by 10!
R-Shoulder Increase frameskip by 90 in one hop!
L-Shoulder Decrease frameskip by 90 in one hop!

Custom-mode

Shows "Custom" so you know you're in this mode. This is a special mode in which all the GP32 buttons are defined by you. When you first enter this mode via the Options menu, if no configuration is loaded you will be presented with a warning and given the option to load a config file if you've made one.

This mode is only useful if you have created one or more config files to define how it works.

See the section on config files to learn how to build one.


All Modes Note

You should notice that the shoulders are used for extra functions in a given mode. Select always jumps to frameskip and back, to let you do quick frameskip adjustments during disk accesses. START always pulls up the options menu where you can do crazy out-of-band stuff.

Options Menu

The Options Menu is your runtime control panel -- it is available while the emulation is running and not from the disk selection menu. After you've fired off the emulator by hitting START in the disk menu screen below, you can hit START at any time to bring up the options menu.

The Options Menu offers you mainly the ability to change the input modes and pick options; an input mode (described above) specifies how your input goes into the emulated Atari ST. For instance, the D-Pad on your GP32 can act as a joystick or a mouse (or keyboard!), so you choose from the Options Menu. You can also turn on and off the audio, eject floppy disks, and other useful things such as saving to SMC. Toggle which render mode you're in, pick config files, adjust the gamma and brightness.. you name it, and if its juicey enough, its here :)

The default rendering mode is ACCURATE rendering.

Things you can do from the Options Menu:

The Floppy Disk menu is the same as the menu above, except it does not show you .RAW savestates (since you're already in the middle of an emulation). Note that if you try inserting a disk image while a disk is already in the drive, Castaway/GP will automatically eject the current disk for you! This menu serves to let you change floppies while the emulation is running, or even to change configuration files!

The savestate menu is detailed below.

The restart menu simply lets you restart Castaway/GP (quit the current emulation so you can pick new disks to boot) or reboot the GP32 entirely, letting you do something else without having to physically turn off the GP32. Save that switch life!

Configuration Menu

The configuration menu is where you can adjust the runtime settings of the system that are less commonly used. For example, turning audio on and off is in the main Options menu, but changing the Render Mode is now contained here, since few people will ever need to do it.

Things you can do here:

Autofire is simply where the joystick pushes the fire button for you automatically. This can be handy to avoid wear and tear on your device, and .. your thumb :)

For details about configuration files, see their section.

Runtime Frameskip

Castaway/GP is pretty fast. You generally want to play at frameskip zero or one. Yes, thats right, frameskip zero or one.

But floating point math can be hard on the emulation and will slow it down; raytracing, lots of 3d vector calculation and.. *unpacking* can be slow. So if you're using compacted-disks (like Automation, Flame of Finland, etc etc) chances are the games are *packed*, and unpacking (where the screen is flickering) is slow.

Some original disks (like Dungeon Master) include compression normally. While Dungeon Master loads, it may take a good minute or two to get to the game itself, while it looks like nothing is going on. Rest assurred that even on a real ST it took a bit of time, though not that much.. its just working the GP32 really hard, so it can take a moment.

This is where Frameskip is useful .. if the game is going to be reading disks for 2 minutes, you might as well crank Frameskip up to 90 or so and shave off 50% of your load time by not rendering the screen. In practice this can work really well, or barely at all, depending on what the game is doing.

Again, for Dungeon Master, it is best to play at frameskip 1 or 0, but load at Frameskip 90. The left and right shoulder buttons, while in Frameskip mode, are plus or minus 90 frameskip. Perfect!

Rendering Modes

Castaway/GP can run in two modes -- FAST and ACCURATE. By default it runs in the ACCURATE rendering mode, since it is much prettier to look at and sometimes speeds up the emulation. The differences are described here:

If the screen is blinking like mad, chances are its either a pirate unpacking/decompression system, or the palette is changing like mad and you're in FAST but not ACCURATE rendering mode. By default we run in ACCURATE mode so things tend to look how they should on a real Atari ST.

ACCURATE Render Mode:

FAST Render Mode:

Gamma and Brightness

The options menu has a submenu to let you force a brightness modifier into the palette. Note that this only works in the ACCURATE render mode.

The default gamma is "0" which is to say.. no modifier. You have the modifiers 1 through 4, which let you bump up the colour brightness. Essentially, each step is one step closer to white for each colour palette entry.

If a colour is already at max green for example (like the GEM Desktop), then increased gamma will not make it any more green... it'll just stay green. Adjusting brightness tries to get you a more intense version of the same colour, and if your'e starting from a dark colour like brown, you're going to eventually hit white. But if you're starting from an already bright colour it will not be able to get much brighter.

But if a colour is at (for example) half-green, and you bump up its gamma, then it'll work its way brighter.

The result is that if you have a screen that is mostly bright blue, with some darker elements on it, than those darker elements will get brighter, but the bright blue may stay the same.

Another example is "black".. the darkest "colour". Gamma modifier "4" on black will make it nearly white. Bringing black up in colour just makes it whiter.

Runtime Disk Menu and Multi-Floppy Games

The disk menu (available from the Options Menu while the emulation is running

primarily lets you eject disks or insert new ones while the emulation is running.

For example, Civilization is 4 disks (in some distributions anyway). You boot "Civilization (A)" to get it going. At some point it will ask for Disk B, so just pull up the Options menu, pick the Floppy menu, pick Insert, and hit "A" whjen you've got "Civilization (B)" selected. Then press Start, and since you'd changed disk A, Castaway/GP will load up the disk image, eject the existing one, insert the new one, and away you go playing Civlization!

You can also save the cached in GP32 memory disk image to SMC as a brand new .SAV disk image. This lets you save a game to emulated floppy, and then store the now modified floppy to SMC as a real ST disk image. Thus you can load your real saved games from the emulated floppy disk, no problem. Or you could just use a saved state -- see below.

Saving

Saving State Snapshots

A savestate is where you copy the entire RAM of the emulated machine, along with current values for all the registers and equipment there-in (like the state of the CPU, sound chips, keyboard processors, etc etc) and write it out to storage. The goal is that you can load from the savestate again much faster than going through an entire boot process. This is especially true for something like a 4 disk game (like Civilization) where booting it up can take 5 minutes of your life away. In this case it is best to do the 5 minute boot once, then save your state out to SMC so that next time you wish to load, you can open the savestate and be up and going in about 10 seconds. Thats a serious time and battery saver!

Another popular use of savestates is to save where you are when your batteries are getting low. If your frontlight suddenly starts blinking and you're afraid of losing your game... pop out a savestate.

Lastly of course, you can cheat.. every time you get somewhere in a game, drop a savestate. This is cheating, but at the same time.. maybe we're a little older or wiser and dont' have as much free time as we used to.

Castaway/GP provides you with 8 savestate slots. At any time while the emulation is running, you can open the Savestate Submenu and save to one of these state slots. Each savestate will consume a few hundred K of SMC (approximately 300k or so). (They are zipped internally, so there is little waste!)

To load a savestate, just restart Castaway/GP and pick the SAVE_??.RAW file in the disk picker. Instead of trying to insertt it into the disk drive, Castaway/GP will restore the emulated Atari ST to the exact state it was in when you dropped out the savestate. Within a few seconds you're exactly where you left off.

FAST!

Saving Disks to SMC

This option is designed to simulate the Atari ST save game experience. For example, if your game allows you to save to Atari ST floppy disks, thats cool. Most RPG's for example support this, so you can play from day to day. The problem with an emulator is that when the ST saves to disk, its actually saving to an emulated disk in the device RAM.. not to a real ST floppy. So the Save to SMC option in the menu lets you get this emulated ST floppy and write out a ST disk image.. a .ST (or .STT) file. So that you know its a savegame disk, we use. SAV instead of .STT.

You could, for example, get the .SAV file and copy it to your PC and rename it to .ST and use it in a desktop-side Atari ST emulation. This could be handy someday :)

The main purpose however is to save those games, and without using up one of your valuable savestate slots.

To open the .SAV disk image later, just pick it from the Floppy Selection Menu instead of its .STT disk. It has the same filename proper, so will sort right in beside it. Just rememebr to use the .STT if you want the original untouched disk image, or the .SAV if you want the save disk.

Here is how you use it:

  1. Within the emulation, save your game. (ex: In Dungeon Master, pull up a character and left-mouse-click on the little disk icon in the top right of the character display.) -- this saves your game to your emulated floppy disk.
  2. Hit START to bring up the Options Menu
  3. Scroll down to the Floppy Menu and hit A or B
  4. Pick "Save Disk A: to SMC" to write out a .SAV disk image
  5. Turn off the GP32 (for example)
  6. Later, instead of booting from (say) A_097.STT to fire up Dungeon Master, boot up from A_097.SAV that you'd saved out above. This version will include your save game!

Configuration Files

Castaway/GP has sensible defaults built into it, so most people will never nee to build a configuration file. However, if you or a game has special needs, you may need one or more configurations. Furthermore, we let you customize what GP32 buttons do what, and you would configure this through the configuration files.

A configuration file has a specific layout:

An example config file you create could look like this:

# A configuration file for
# Castaway/GP
#
# make virtual keyboard slower to use
vkeytravel 700
# make virtual key repeat slower
vkeyrepeat 800
# done

You can have as many configuration files as you like. A file called DEFAULTS.CNF will be loaded when you boot up Castaway/GP, and thus can be used to set up your overrides for the built in defaults. If no DEFAULTS.CNF exists, no problem.. Castaway/GP has good defaults built in.

Your .CNF files will show up in the Disk Picker Menu, and if you hit A or B while a .CNF is selected, it will be read and processed immediately. This way you can set up a set of configuration files for individual disks or games if you like, and before firing up a disk, just pick the .CNF file of your choice. This would let you set low key repeat rates for some disks, and fast key repeat rates for others.

In general, the default values are good for most people, and so you never need to worry about config files.

Config keys and values are mostly CASE SENSITIVE -- "joy-fire" means exactly that. The ST keyboard keys are case insensitive, however... "ST_SPACE" is the same as "st_space"

TIP: You do not need to include all variable values in a config file. So you could create very specific little config files.. for instance, a config file called C_FSTRPT.CNF that always sets virtual keyboard key repeat to a low delay, and thats it. Then create a config file called C_SLWRPT.CNF that does trhe reverse. This way you can pick a fast or slow repeat whenever you like, without touching any other config values. Handy!

TIP: Begin all your config files with the same letter (like "C" or "_") so they all sort together in the disk picker menu!

As of Castaway/GP version 11, the variables you can set are:

keythresh Minimum time between GP32 registering button presses since last button press Default: 600
vkeytravel After moving the virtual keyboard's key cursor, the delay before moving it again. If you're finding the virtual keyboard hard to maneauver to the right key to push, then try adjusting this value up Default: 300
vkeyrepeat The amount of time you need to hold down the GP32 B button in the virtual keyboard before it fires off another key press. A low value may cause you to push the same butotn many times by accident. A high value will make this not happen, but some games need you to hold down a key to increase throttle (like in a flight sim, for example). Default: 400
vkeyduration The amount of time Castaway/GP holds a key down for you, when you've pressed a emulated key. For example, when you push "B" on the GP32 while the virtual keyboard cursor is over "1", you'll send a "1" into the Atari ST's keyboard buffer. The key will be released a moment later, after this duration has gone by. Some games require a the key to be released a moment after its pressed and not immediately. The default value is probably perfect for everyone. Default: 200
joy_autofirethresh Speed of autofire; 200 is too fast for the system, but 300 is a damned fast autofire if you really need it :) Default: 400
joy_autofireactive If 0, turn autofire off. If 1, turn autofire on. Default: 0
print The word (only one "word"!) value will be displayed in the error log for the config file. You can use this to give a title to the config, for example, so you know what you picked later :) The last print value is also shown beside the "Custom" mode line at the bottom of the screen, so you can use it to know what Custom mode you are in. Ex: "print BigWord". You cannot use "print Big Word" since that is two values and print can only handle one. Default: n/a
gamma Set the current gamma/brightness adjustment. 0-4 allowed. Default: 0
widedesc If set to 0, file menu is normal (filename+description). If set to 1, file menu will show game descriptions where they're already looked up. (Similar to using right shoulder to toggle wide description from the menu itself). This is a useful option for the DEFAULTS.CNF file! Default: 0

Changing the Custom Mode (the "key bindings"):

Using a configuration file(s) you can define what each button on the GP32 does. You can not define a new START button, as we reserve that to always pull up the START menu, so you don't hang yourself.

To define key bindings, you simply use the appropriate key to pick a GP32 button, and a value to tell the system what it should do when pressed or not pressed.

A sample (useless) joystick definition could be:

# A bogus example joystick mode
print joys
bind-fl joy-fire
bind-fr ST_SPACE
bind-up joy-up
bind-down joy-down
bind-b  joy-left
bind-a  joy-right
bind-select ST_1

The binding key's you can pick from are:

bind-up The UP direction on joystick/d-pad
bind-down The DOWN direction on joystick/d-pad
bind-left The LEFT direction on joystick/d-pad
bind-right The RIGHT direction on joystick/d-pad
bind-fl The left-shoulder button
bind-fr The right-shoulder button
bind-a The "A" button
bind-b The "B" button
bind-select The SELECT button

The values you can assign to bindings are:

toggle-autofire Turn autofire on or off
toggle-frameskip Toggle into and out of Frameskip mode; normally SELECT.
toggle-keyboard Toggle into and out of keyboard mode; normally left shoulder.
goto- Load another config file. This is a very powerful mechanism as it lets you create both toggle controls and cycle/chain controls. For example, you could create two config files (c_joy.cnf and c_mouse.cnf for example), and c_joy.cnf could include goto-c_mouse.cnf while c_mouse.cnf could include goto-c_joy.cnf, both bound to the left-shoulder say. In this way you could press left shoulder to toggle between your custom joystick and mouse modes. You could create a series of 3 or 5 or 100 configs that all chain together... could be very useful for those flight simulators or other games with a million keystrokes. Remember to include "print" directives in your config files so that when you go from config to config, you can see what config you're currently in!
frameskip+90 Bump frameskip up 90 points
frameskip-90 Bump frameskip down 90 points
menu_configload Brings up the Config -> Load dialog; this lets you instantly show a listing of configs and pick one to load, right away. So if you need two or three config sets for a game, this would let you swap between them almost effortlessly!
mouse-up Push mouse up
mouse-down Push mouse down
mouse-left Push mouse left
mouse-right Push mouse right
mouse-fl Click mouse left button
mouse-fr Click mouse right button
joy-up Push joystick up
joy-down Push joystick down
joy-left Push joystick left
joy-right Push joystick right
joy-fire Push joystick firebutton
ST_* - Assorted; see below. Push a key on the ST keyboard. Specifically, binding an STKEY this way means pushing the button pushes and releases the ST key.
bind-ST_* - Assorted; see below. Hold a key down on the ST keyboard. This is like the normal STKEY above, except the key is held down while the button is held down. If you bind ST_SPACE to a button, then want to hold it down, just press and hold the button. If you bind with ST_SPACE only, the key is pressed and released.. but binding hold-ST_SPACE will make it a hold-style of button.

The available ST_ keys you can bind are these. They can be referred to in the uppercase or lowercase -- "ST_SPACE" is equivalent to "st_space".

ST_ESC ST_1 ST_2 ST_3 ST_4 ST_5 ST_6 ST_7 ST_8 ST_9 ST_0 ST_MINUS ST_EQUAL ST_BS ST_TAB ST_Q ST_W ST_E ST_R ST_T ST_Y ST_U ST_I ST_O ST_P ST_SQ_OPEN ST_SQ_CLOSE ST_RETURN ST_CONTROL ST_A ST_S ST_D ST_F ST_G ST_H ST_J ST_K ST_L ST_SEMIC ST_APOST ST_GRAVE ST_LSH ST_BACKSL ST_Z ST_X ST_C ST_V ST_B ST_N ST_M ST_COMMA ST_DOT ST_SLASH ST_RSH ST_ALT ST_SPACE ST_CAPSLOCK ST_F1 ST_F2 ST_F3 ST_F4 ST_F5 ST_F6 ST_F7 ST_F8 ST_F9 ST_F10 ST_HOME ST_UP ST_PG_UP ST_KP_MINUS ST_LEFT ST_RIGHT ST_KP_PLUS ST_END ST_DOWN ST_PG_DN ST_INSERT ST_DELETE ST_ISO ST_UNDO ST_HELP ST_KP_OPEN ST_KP_CLOSE ST_KP_DIV ST_KP_MULT ST_KP_7 ST_KP_8 ST_KP_9 ST_KP_4 ST_KP_5 ST_KP_6 ST_KP_1 ST_KP_2 ST_KP_3 ST_KP_0 ST_KP_DOT ST_KP_ENTER

Tip: While setting up config files, it might be a good idea to create several similar files. Since you can load them up from the menu, you can send a half dozen files to your GP32, and then try them out one at a time until you find the one that is the best. Saves uploading config files back and forth like crazy. Remember that you can get to the disk selection menu while the emulation is running and thus change the configuration without quitting the game!