Virtual GameBoy Advance
version 5.5

by Marat Fayzullin

Contents

Disclaimers

New in This Version

Introduction

Virtual GameBoy Advance (VGBA) emulates Nintendo's GameBoy Advance handheld videogame console. VGBA can run most commercial GameBoy Advance software on a desktop, palmtop, or any sufficiently fast computing device. It will also run correctly written homebrewn software. You can always get the latest version of VGBA at

http://fms.komkon.org/VGBA/

VGBA is a logical continuation of my previous work in videogame emulation, namely, the Virtual GameBoy (VGB). VGB emulates GameBoy Classic, GameBoy Pocket, Super GameBoy, and GameBoy Color. VGBA is a completely different program though. It will not run the original GameBoy software, so you will have to use VGB for that.

VGBA Ports

Because VGBA is a very portable program, it can be compiled on many different platforms: Windows, Unix, Linux, Android, MacOS, MSDOS, etc. The complete up-to-date list of VGBA ports can be found at the VGBA homepage. Following are just the major VGBA ports:

VGBA-Android

The Android version of VGBA are available from Google Play:

https://play.google.com/store/apps/details?id=com.fms.vgba2

Once you download a copy, you should be able to use it on as many Android devices as you own, as long as they are all linked to the same Google Play account. Make sure to enable automatic updates, as VGBA-Android updates often. The Android version comes with many additional features, such as Cheatopedia with cheat codes for many popular games, State Exchange letting VGBA users exchange saved games, the Box Art Downloader, improved Network Play functionality, and more.

VGBA-Windows

The VGBA-Windows is now free for everyone to use and share. It can be downloaded from the VGBA homepage:

http://fms.komkon.org/VGBA/

For more information, take a look at my other products for Windows:

http://fms.komkon.org/EmuWindows/

As I have made VGBA-Windows free, it is no being sold via eSellerate. Existing users should go to the above site and download a fresh copy. If you wish to support my work on VGBA-Windows and other emulators, please consider buying VGBA-Android.

VGBA-Unix and VGBA-Linux

VGBA-Unix and VGBA-Linux are available freely in binary form from the VGBA homepage:

http://fms.komkon.org/VGBA/

I am always trying to compile it on as many different Unix and Linux flavors as I have handy at the moment.

VGBA-Maemo and VGBA-Meego

The VGBA-Maemo works on Nokia devices running Maemo or Meego OS. It is specifically optimized for Maemo platform and available for free from respective package repositories and VGBA homepage. As both Maemo and Meego platforms are dead, I am no longer developing for them though.

VGBA-MSDOS

I am no longer developing and supporting VGBA-MSDOS, as the MSDOS platform is completely dead nowadays. Older VGBA-MSDOS versions were sold as part of the VGBA-Windows package (now free) and used DOS4GW extender and VESA screen drivers on MSDOS and Windows platforms.

VGBA-Symbian

The VGBA-Symbian port ran on phones running the 3rd Edition of the Nokia S60 software. It is no longer being developed and supported, as Symbian and all its development tools are dead. You can still access some of my Symbian products at this address though:

http://fms.komkon.org/EmuSymbian/

VGBA-PocketPC

The PocketPC version of VGBA has long been developed by Aaron Oneal. As PocketPC is long dead though, VGBA-PocketPC is dead as well. You can still get older PocketPC versions of VGBA and my other emulators from

http://fms.komkon.org/MorphGear/

What is Included

This version of VGBA has emulation for the following:

Not emulated:

Here is a list of emulated features:

Feature Text BGsRotation BGsMODE 3MODE 4MODE 5Sprites
Variable Size YES YES N/A N/A N/A YES
Tile Flipping YES N/A N/A N/A N/A YES
16/256-Color TilesYES N/A N/A N/A N/A YES
Scrolling YES N/A N/A N/A N/A N/A
Mosaic YES YES YES YES YES rotated sprites only
Rotation N/A YES YES YES YES YES
Window YES YES YES YES YES YES
Color Effects YES YES YES YES YES YES

Including the real Nintendo BIOS with the emulator would be a copyright violation. Therefore, I have tried to simulate GBA BIOS routines by trapping and handling ARM SWI opcodes. GBA BIOS is now fully emulated except for the built-in music player and some networking routines. Here is the list of supported BIOS calls:

Function SWI # Supported
BIOS_SoftReset 0x00 Yes
BIOS_RegisterRAMReset 0x01 Yes
BIOS_Halt 0x02 Yes
BIOS_Stop 0x03 Yes
BIOS_IntrWait 0x04 Yes
BIOS_VBlankIntrWait 0x05 Yes
BIOS_Div 0x06 Yes
BIOS_DivARM 0x07 Yes
BIOS_Sqrt 0x08 Yes
BIOS_ArcTan 0x09 Yes
BIOS_ArcTan2 0x0A Yes
BIOS_CPUSet 0x0B Yes
BIOS_CPUFastSet 0x0C Yes
BIOS_BIOSChecksum 0x0D Yes
BIOS_BgAffineSet 0x0E Yes
BIOS_ObjAffineSet 0x0F Yes
BIOS_BitUnPack 0x10 Yes
BIOS_LZ77UnCompWRAM 0x11 Yes
BIOS_LZ77UnCompVRAM 0x12 Yes
BIOS_HuffUnComp 0x13 Yes
BIOS_RLUnCompWRAM 0x14 Yes
BIOS_RLUnCompVRAM 0x15 Yes
BIOS_Diff8bitUnFilterWRAM 0x16 Yes
BIOS_Diff8bitUnFilterVRAM 0x17 Yes
BIOS_Diff16bitUnFilter 0x18 Yes
BIOS_SoundBiasChange 0x19 No
BIOS_SoundDriverInit 0x1A No
BIOS_SoundDriverMode 0x1B No
BIOS_SoundDriverMain 0x1C No
BIOS_SoundDriverVSync 0x1D No
BIOS_SoundChannelClear 0x1E No
BIOS_MIDIKey2Freq 0x1F No
BIOS_MusicPlayerOpen 0x20 No
BIOS_MusicPlayerStart 0x21 No
BIOS_MusicPlayerStop 0x22 No
BIOS_MusicPlayerContinue 0x23 No
BIOS_MusicPlayerFadeOut 0x24 No
BIOS_MultiBoot 0x25 No
BIOS_HardReset 0x26 No
BIOS_CustomHalt 0x27 No
BIOS_SoundDriverVSyncOff 0x28 No
BIOS_SoundDriverVSyncOn 0x29 No
BIOS_GetJumpList 0x2A Yes

What is not Included

Absolutely no ROM images of commercial GameBoy Advance games are included. These games are copyrighted by the companies which produced them, and therefore, I cannot distribute any of these games. I'm also unable to tell you where to find the games, so do not send me email asking for them. You will have to look for them on your own.

It may also be a good idea to buy a real cartridge for each GameBoy Advance ROM image you use with the emulator. Owning a real, physical cartridge is the right thing to do, both legally and ethically.

The VGBA web page contains some links to GameBoy Advance cartridge copier info. Cartridge copiers can be used to dump GameBoy Advance cartridges into files. I cannot provide you with any additional information about these copiers, so do not send me email asking for this information. Use the copier-related links at the VGBA web page.

GameBoy Advance has a BIOS ROM inside with some useful subroutines. Including the real Nintendo BIOS with the emulator would be clearly illegal. Instead, VGBA tries to simulate GBA BIOS routines. It still has an option to use the real BIOS supplied from the GBA.ROM file in the current directory. I cannot tell you where to find the real BIOS, so do not ask me about it. The current BIOS simulation is quite functional. It also runs faster than the real BIOS would on the emulator.

Buttons

These button assignments apply to all three VGBA ports developed by myself. They will work in Windows, Unix, and MSDOS.

  [SPACE]        - FIRE-A button (also: [SHIFT],A,S,D,F,G,H,J,K,L)
  [CONTROL]      - FIRE-B button (also: Z,X,C,V,B,N,M)
  [Q]            - FIRE-L button (also: E,T,U,O)
  [W]            - FIRE-R button (also: R,Y,I,P)
  [TAB]          - SELECT button
  [ENTER]        - START button
  [ESC]          - Quit emulation (also: [F12])
  [F2]           - Turn soundtrack logging on/off
  [F3]           - Turn FIRE-A button autofire on/off
  [ALT]+[F3]     - Turn FIRE-L button autofire on/off
  [F4]           - Turn FIRE-B button autofire on/off
  [ALT]+[F4]     - Turn FIRE-R button autofire on/off
  [F5]           - Invoke built-in menu
  [F6]           - Load emulation state from .STA file
  [F7]           - Save emulation state to .STA file
  [F8]           - Replay last few seconds of gameplay
  [F9]           - Fast-forward emulation (also: [PGUP])
  [F11]          - Reset GBA hardware
  [F12]          - Quit emulation (also: [ESC])
  [PGUP]         - Fast-forward emulation (also: [F9])
  [PGDOWN]       - Toggle GameShark cheats
  [5]-[8]        - Turn backgrounds display on/off
  [9]            - Turn sprites display on/off
  [-]            - Descrease light level (Boktai)
  [=]            - Increase light level (Boktai)

With #define DEBUG:
  [F1]           - Go into the built-in debugger

With #define SOUND:
  [ALT]+[PGUP]   - Increase audio volume
  [ALT]+[PGDOWN] - Decrease audio volume
  [0]            - Turn all sound on/off
  [1]-[4]        - Turn melodic sound channels on/off
  [[],[]]        - Turn direct sound channels on/off

With #define WINDOWS:
  [ALT]+[ENTER]  - Switch between full scren and window modes

Command Line Options

Start VGBA with the following command line:

vgba [-option1 [-option2...]] [FILENAME.GBA]

When no cartridge name is given, VGBA will print the list of keyboard assignments and available command line options. Following is a list of options supported in VGBA-MSDOS and VGBA-Unix. VGBA-Windows only accepts the cartridge name.

  -skip <percent>     - Percentage of frames to skip [25]
  -verbose <level>    - Select debugging messages [1]
                          0 - Silent          1 - Startup messages
                          2 - I/O accesses    4 - Illegal memory accesses
                          8 - DMA transfers  16 - Illegal CPU ops
                         32 - SWI calls      64 - FlashROM/EEEPROM/RTC
                        128 - Sound messages
  -crc/-nocrc         - Check cartridge CRC/CMP [-crc]
  -guesshw/-defaulthw - Guess FlashROM/EEPROM ID and size [-guesshw]
  -flashid <id>       - Set FlashROM maker/device ID [D4BFh]
  -flash <bits>       - Set FlashROM size, ≥16 bits [17]
  -eeprom <bits>      - Set EEPROM size, 6..16 bits [6]
  -tilt/-rtc          - Emulate tilt sensor or real time clock chip [-rtc]
  -gs0/-gs1/-gs3      - GameShark cheats encryption: none/v1/v3 [-gs3]
  -logsnd <filename>  - Write soundtrack to a MIDI file [LOG.MID]
  -ds <method>        - Sound rendering method [1]
                        0 - Off                1 - Automatic
                        2 - Accurate           3 - Fast

With #define SOUND:
  -sound [<quality>]  - Sound emulation quality [22050]
  -nosound            - Same as '-sound 0'

With #define DEBUG:
  -trap <address>     - Trap execution when PC reaches address [FFFFFFFFh]
                        When a keyword 'now' is used in place of the
                        <address>, execution will trap immediately.

With #define MSDOS or UNIX:
  -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
                        (<frequency> must be in 20Hz..100Hz range)
  -nosync             - Do not sync screen updates [-nosync]
  -tv/-lcd/-raster    - Simulate TV scanlines or LCD raster [off]
  -soft/-eagle        - Scale display with 2xSaI or EAGLE [off]
  -epx/-scale2x       - Scale display with EPX or Scale2X [off]
  -cmy/-rgb           - Simulate CMY/RGB pixel raster [off]
  -mono/-sepia        - Simulate monochrome or sepia CRT [off]
  -green/-amber       - Simulate green or amber CRT [off]
  -4x3                - Force 4:3 television screen ratio [off]

With #define MSDOS:
  -vsync              - Sync screen updates to VBlank [-vsync]

With #define UNIX:
  -saver/-nosaver     - Save CPU when inactive [-saver]
  -scale <factor>     - Scale window by <factor> [2]

With #define MITSHM:
  -shm/-noshm         - Use MIT SHM extensions for X [-shm]

Frequently Asked Questions

  1. I WANNA PLAY GAMES!!!! WHERE DO I GET GAMES???????

    I do not know. I can't give you any due to both legal and moral reasons. Please, do not mail me asking for games. I will delete your mail right away, and you won't get an answer.

  2. Can I play GameBoy Classic and GameBoy Color games on VGBA?

    No, you can't. GameBoy Advance hardware is completely different from the older GameBoy and GameBoy Color models. To play older games, you may want to consider my other emulator, Virtual GameBoy (VGB).

  3. How do I copy games from cartridges to a computer?

    You can use a special device called cartridge copier, such as Flash Advance Linker from Lik-Sang. Don't forget to get a rewritable flash card too.

  4. What is GameBoy Advance? How its hardware works?

    GameBoy Advance (GBA) is a handheld videogame machine made by Nintendo. Its hardware has nothing to do with GameBoy and GameBoy Color handhelds previously produced by Nintendo. GBA is built around an ARM7TDMI 32bit CPU running at 16MHz. GBA video subsystem is very similar to that of SNES, but more advanced. The sound subsystem uses direct sample output. GBA also includes the four-channel melodic sound chip from the original GameBoy.

    In order to be compatible with the original GB/GBC, GBA includes the complete set of GBC hardware. This hardware (aside from the sound chip) is not accessible from the GBA side and only used when somebody inserts a GB/GBC cartridge into GBA.

  5. There is no version of VGBA for my Unix!

    I am trying to compile Unix binaries for as many flavors of Unix as possible, but as I do not have access to many machines, do not expect immediate support for every Unix flavor out there. Don't mail me asking for the source either: VGBA source code is not publicly distrbutable, as much as I regret to say this :(.

  6. My favorite game doesn't work on VGBA. What do I do?

    There may be several reasons why a game has problems running on VGBA or does not run at all.

  7. Direct sound sounds really bad!

    Use -ds command line option (or corresponding options in the VGBA-Windows Setup Panel) to choose the way VGBA renders direct sound. In Windows, you should also try changing volume, sound rate, and the number of sound buffers. If this doesn't help, you may be out of luck. Hopefully, sound emulation becomes better in the upcoming versions.

  8. Why is VGBA so slow on my machine?

    Because your machine is too slow to run VGBA. My experience shows that you need at least a PentiumII/400 machine with fast video to run VGBA at a reasonable speed. Following are the ways to speed things up:

  9. VGBA is too fast on my machine! How do I slow it down?

    Frankly, when I started writing VGBA, I never expected that it will be too fast on any machine :). But times change...

  10. When starting VGBA-Unix, ld says that some library isn't found.

    This may happen if the versions of your shared libraries are older than the ones for which VGBA has been compiled. A decent way to deal with this is to upgrade your Unix. A quick and dirty way is to make a symbolic link from the existing library to a name required by VGBA.

  11. When starting VGBA-Unix, I get X_ShmAttach error.

    You are probably trying to run VGBA-Unix on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use -noshm option to tell it not to use shared memory.

  12. When starting VGBA-Unix, I get X_PutImage error.

    VGBA-Unix version currently needs 16bit X. Xterminals that do not support 16bit image format will not work.

  13. The sound is distorted in the VGBA-Windows. How do I fix it?

    The wave-synthetized sound in VGBA may become distorted on slow or highly loaded machines (no graphics acceleration, for example). There are several ways you can improve sound:

  14. Does VGBA-Windows support joystick? My joystick doesn't work!

    VGBA-Windows supports joystick. If your joystick does not work, go into Windows Control Panel to see if it is configured and calibrated properly. Also, some new joysticks working in esoteric standards (like GRiP) are known to have problems.

  15. Colors are all screwed up in VGBA-Windows!

    VGBA-Windows requires Windows to be in 65536-color or better color mode. When running Windows in 256-color mode, it will try to approximate colors to existing ones, but expect results to be dismal.

  16. Black window in VGBA-Windows!

    If you are running Windows in 256-color mode, then this is most likely the cause of a problem. Try switching Windows into 65536-color or better screen mode.

  17. How do I save and load the GBA state during the game?

    The GBA state can be saved by pressing [F7] button. The resulting data file will have the same name as your .GBA file, but its extension is going to be .STA. You can load state from this file by pressing [F8] at any point in the game. This state file will also be loaded automatically next time you start VGBA. The same state file is not guaranteed to work for versions of VGBA running on a different hardware. State saving is not perfect yet, so for some games state may not be correctly saved.

History

New in Version 5.4

New in Version 5.3

New in Version 5.2

New in Version 5.1

New in Version 5.0

New in Version 4.9

New in Version 4.8

New in Version 4.7

New in Version 4.6

New in Version 4.5

New in Version 3.6

New in Version 3.5

New in Version 3.4

New in Version 3.3

New in Version 3.2

New in Version 3.1

New in Version 3.0

New in Version 2.1

New in Version 2.0

New in Version 1.7

New in Version 1.6

New in Version 1.5

New in Version 1.4

New in Version 1.3

New in Version 1.2

New in Version 1.1

New in Version 1.0

New in Version 0.6

New in Version 0.5

New in Version 0.4

Thanks

I would like to thank people from the EFNet #gbadev IRC channel for their help locating GBA specifications and testing the emulator.


© Copyright by Marat Fayzullin (marat [AT] komkon /DOT/ org)