Phoinix, the free Gameboy emulator for PalmOS

by Bodo Wenzel
Home (downloads)
F. A. Q.
Old news
Compatibility of...
  free cartridges
  commercial cartridges
  colour games
How to...
  use the emulator ==>
  convert cartridges
  make cartridges run
  get in touch
  the history
  the future
  the playability testing
  skipping frames
  some accessories
  limits and extensions
Thank you for the cookies

This site is kindly hosted by SourceForge Logo

How to use the emulator

On this page: - Installation - The games manager - Running games - Adjustable options - Compatibility - Runtime errors and crashes


The emulator

Basically there's just one file to install: "Phoinix.prc". Please hotsync this file in your usual way...

To install a newer version over an old one, you don't need to remove the old version. However, the chances are that you need to setup your options again.

To uninstall Phoinix, simply choose "Delete..." in the application launcher. The emulator and all its on-board data will be removed, leaving no trace.

The games

Phoinix only emulates the Gameboy's hardware, to play a game requires the game's binary data. You'll find these as files, commonly with a "*.GB" file extension.

After obtaining a game's file, it must be converted to a Palm database ("*.PDB"). This is achieved with the converter "gb2pdb" on your personal computer. For a quick start download a collection of already converted free games.

After converting, simply install the database.

Support of Flash memory (on-board)

Phoinix can't run in Flash memory, but converted games can be stored in Flash memory. If they use cartridge RAM it is created in a separate place, anyway. Since devices with on-board Flash memory are getting outdated this will most probably never be changed.

External media (memory cards, VFS)

Starting with OS4, PalmOS supports external media in a generalized way. This is called "VFS", the Virtual File System.

On VFS-enabled devices Phoinix shows a location selector which you can use to move the game between available media and/or on-board RAM. On the external medium the directory /PALM/Phoinix is used to store the games and their data.

There are two ways to put games on the external medium:

  1. Install it in on-board memory and move it via the Game Details form.
  2. Copy the "*.PDB" file into the directory /PALM/Launcher where it will be handled.

When the manager initializes, the directory /PALM/Launcher is scanned for new games. This is where card-installers place new files, and if you use a card writer you should copy your converted games into this directory, too. If new games are found, there are checked and if accepted moved into Phoinix' own directory /PALM/Phoinix. In the course of this copy each filename is checked that it equals the game's name and doesn't contain wrong characters. Good names consist of letters, numbers, and a small set of special characters including apostrophe, minus, dot, underline, round braces, and some few more.

To play a game from an external medium, Phoinix needs to copy the data to the internal RAM; this may take a moment. The game's changed data is copied back when the emulation quits.

When you remove Phoinix via the application launcher, games installed on external media are not removed! Please remove those games via Phoinix, or use an appropriate utility.

The games manager

The list of games

Screenshot of list of games.

The manager shows the list of games, the saved states of the current game, and a big "GO!" button. If you have no game installed, the list is empty. If you have many games installed, a scrollbar is shown. The little card marker at the right side flags games on external memory cards.

You use the list as any other, however there are some additions. If you use the up/down buttons, the selection wraps around the ends of the list. To speed up the navigation you could also enter the first character of the game's name. The matching or next entry will be selected.

Launch a game

To begin playing tap "GO!" and the game starts.

Saved states

Screenshot of a thumbnail in the GO! button.

Left of the "GO!" button the list of saved states is shown, sorted by the played time. The first entry always represents the current state which will be overwritten when the game is run. This state is only saved if you have enabled the "Auto save state" option (see below) before quitting a game. Each saved states contains a snapshot of the GB screen which is shown as a thumbnail in the "GO!" button.

The "Delete" button below the list is used to delete the selected saved state. You will use this to get rid of unwanted saved states or to free some memory. The current saved state can be deleted that way, too.

Game administration

Screenshot of the Game Details dialog.

To rename or move the current game, open the Game Details. This dialog shows also the game's code (a 32 bit checksum), the type of cartridge, and the grand total of memory used. The latter is the sum of the game's binary image (ROM) and the saved information like state and RAM. Please note that changes of the name or the location will not be made until you tap "OK".

To delete a game, select this action from the menu. The saved states (if any) and the game's preferences are deleted with the ROM.

Running games

User interface

Nearly all of the display is used for the GB screen. Just the lower border contains up to four selectable controls, see below. You can place emulation controls, GB buttons, or information fields here.

While emulating the standard Palm user interface is still in place. You should receive your alarms and battery warnings. And you could tap in the display title area to open the menu:

Screenshot of the emulator with open menu.

Many games react with a restart when you press all control buttons (Select, Start, A, and B). With some button mappings this is quite difficult, so Phoinix provides it as a menu command.

To stop a game momentarily, choose "Pause" on the menu or check its checkbox. This is quite convenient for screenshots. Additionally the hard keys get back their standard function so you can launch your favourite applications.

To restart a game as if switching off-and-on with a real Gameboy, use "Reset".

To return to the manager, select "Quit" in the menu. The current state of the game is only saved if you enabled the option!

If you exit Phoinix while playing a game (i. e. via the "Home" icon), the state of the game is saved in any case. Launching Phoinix again brings you back where you left.

Pen usage

The pen can be used as direction control; simply put it down on the screen and drag it around.

Saved states

Screenshot of the shortcut bar with icons.

Saving the current state is done through the menu or its shortcut. The newly saved state is added at the end of the list of saved states.

You load a saved state through the Load State dialog. It shows the list of saved states and the thumbnail of the selected entry. Initially the last saved state is selected for your convenience. Tap the big button like in the manager to load the selected saved state. To cancel the load, select the first entry. It never contains a saved state, and the button shows "Cancel".


Screenshot of the shortcut bar with icons.

There are several shortcuts, shown in the menus, and as icons. The function of the icons are, from left to right: "paste" to open the Load State dialog, "copy" to save the current state, "undo" to restart the game, and "delete" to quit the emulation.

Frame skipping

To gain some speed a method called "frame skipping" is used. It saves some time by skipping an adjustable number of frames. However, the game's code has to be emulated for each frame to keep the game going. Please read my thoughts about skipping frames... Anyway, here are two modes: the Normal mode which tries to maintain the real speed of the GB, or the Boost mode which doesn't. You switch between the modes via the menu command or the checkbox if you have put it in the screen.

The real speed (1.00x pace) with no frames skipped can be achieved only with some games on fast handhelds. If your device happens to be faster, Phoinix inserts some delays preserving the battery.

Adjustable options

Several options can be adjusted, and all of them are stored individually per game. New games get the options of the last selected game, so your favourites are spread automagically...

Emulation Options

Screenshot of Emulation Options.

Phoinix preserves the state of the emulation if you quit it while playing. Additionally to this you might like to save the state also when you switch back to the manager. Please check "Auto save state" for this, and your memory will be loaded with some additional kilobytes ;-)

The number of skipped frames can be adjusted separately for Normal and Boost. In Normal the number is just the limit. If your device is fast enough to get the real speed with less skipped frames, not all are used. In Boost mode all set frames are skipped regardless of the pace reached. HINT: To get a non-skipping emulation, set Boost's value to zero and switch the mode on.

Button Mapping

Screenshot of Button Mapping.

You can assign each GB button to a hard key that is supported by the Palm OS. Unfortunately some devices can't handle multiple keys pressed at a time, i. e. the Zire 31. Then you will place some keys on the screen, see "Screen Layout".

The form displays all GB buttons and their assigned keys. The value shown represents an internal number if a key is assigned. If no key is assigned, no number is shown. To map a key to a button, tap the trigger (the dotted rectangle). After the "Sample Key" form is shown, press the desired key. If you like to unmap a button, tap "No key".

Some handhelds have "jog wheels" which can be used. As these units emit just short pulses, you'll need to enable "Hold" to make them usable. Now, when you jog in one direction, the mapped GB buttons gets pressed down permanently even if you stop jogging. To release the GB button, jog a bit in the opposite direction.

Screen Layout

Screenshot of Screen Layout.

The bottom of the display can be populated with emulation controls, GB buttons, or information fields.

If more than one GB button is shown on the screen, you can "press" multiple buttons simultaneously by tapping in the first and dragging to the next.


Device Remark
All devices with OS5 (Tungstens, Treos, ...) Works well, but not as fast as the higher clock rates might suggest. There is no native ARM code in Phoinix.
Palm III and V series Works well, though slowly due to small processor power.
Palm m1xx and m5xx series Works well.
Palm Zire series Works well.
Handspring, all series Works well.
Handera H330 Works well, the GB display is shown in the middle of the screen.
Sony Clié series Works well.
Kyocera QCP 6035 Phoinix works with OS version 3.5.3 or newer, older OS versions have a problem with non-functional silk buttons.
Samsung i500 Reports still missing.
G18 Reports still missing. Because of an apparently sloppy design of this device Phoinix will work really slow!
Tapwave Zodiac series Works well.
AlphaSmart Dana Works well, the GB display is shown in the middle of the screen. Only few standard keys can be used: On/Off, Date, Address, To-Do, Memo, Sync, PgUp, and PgDn.
Fossil Wrist PDA Since the standard video mode shows vertical stripes, Phoinix switches to another grey mode. Unfortunately it slows down the emulation. Sorry, but I believe it's better than garbled graphics.

If your device is not listed, please try Phoinix cautiously. Then send me a report, please. Include any important information like manufacturer, device name, OS version,... Do the same if you find an incorrect entry in this list.

Software Remark
Screenshots via TealPaint If you stop the emulator and use TealPaint v.4.92, screenshots are perfect. I don't know whether other versions capture the grey level image correctly.

If you like to contribute any information, don't hesitate to send me a report, please. Include all that should be filled into the fields of the table. Do the same if you find an incorrect entry in this list.

Runtime errors and crashes

When Phoinix detects a runtime error while emulating, it will notify you. The current state of the game is saved into a crash database which can be transfered to your PC via the standard backup procedure. Please contact me for further help. Describe the circumstances as verbose as you can!

If you experience crashes, something may have corrupted the internal memory organization of your device. I recommend strongly to perform a hard reset erasing all memory! Otherwise you have a good chance for data losses...