GBA Emulator Compilation Build Scripts

Python 3 builder scripts for the following emulators for Gameboy Advance:

Emulator	Target System	Author(s)	1st Release
PocketNES	Nintendo NES	Loopy, later FluBBa, Dwedit	Jan 2001?
ZXAdvance	Sinclair ZX Spectrum 48K	TheHiVE	May 2001
PCEAdvance	NEC PC Engine / Super CD-ROM²	FluBBa	Apr 2003
Goomba	Nintendo Gameboy	FluBBa	Oct 2003
HVCA	Nintendo NES / Famicom Disk System	outside-agb?	Sep 2004
Wasabi	Watara Supervision	FluBBa	Nov 2004
SNESAdvance	Nintendo SNES	Loopy, FluBBa	Feb 2005
SMSAdvance	SEGA Master System / Game Gear / SG-1000	FluBBa	Jul 2005
Cologne	ColecoVision	FluBBa	Jan 2006
Goomba Color	Nintendo Gameboy / Gameboy Color	FluBBa, Dwedit	Jan 2006
MSXAdvance	MSX-1 (version 0.2 is most compatible)	FluBBa	Mar 2006
Snezziboy	Nintendo SNES	bubble2k	May 2006
NGPGBA	SNK Neo Geo Pocket / Pocket Color	Flubba	Jul 2008
Jagoomba	An enhanced Goomba Color fork	FluBBa, Dwedit, Jaga + various	Nov 2021

Purpose

The scripts combine the emulator binary with the game ROMs and their required metadata into a .gba executable for Gameboy Advance. Since the scripts are written in Python 3 they will run on most present-day platforms, helping to preserve these technical marvels.

Usage

git clone https://github.com/patters-syno/gba-emu-compilation-builders

You can drag and drop multiple file selections onto the shell window in which you are preparing the command line. Most options are not needed since they have sensible defaults. This makes these scripts well suited for building large compilations very easily. Usually the shell will alphabetically sort multiple file selections.

Each script has help information accessible via the -h command line option. For example:

usage: pocketnes_compile.py [-h] [-s SPLASHSCREEN] [-e EMUBINARY]
                            [-db DATABASE] [-dbn] [-m] [-c] [-o OUTPUTFILE]
                            [-sav] [-pat]
                            romfile [romfile ...]

This script will assemble the PocketNES emulator and NES ROMs into a Gameboy
Advance ROM image. It is recommended to type the script name, then drag and
drop multiple ROM files onto the shell window, then add any additional
arguments as needed.

positional arguments:
  romfile          .nes ROM image to add to compilation. Drag and drop
                   multiple files onto your shell window.

optional arguments:
  -h, --help       show this help message and exit
  -s SPLASHSCREEN  76800 byte raw 240x160 15bit splashscreen image
  -e EMUBINARY     PocketNES binary, defaults to pocketnes.gba
  -db DATABASE     PocketNES Menu Maker Database file which stores optimal
                   flags and sprite follow settings for many games, defaults
                   to pnesmmw.mdb
  -dbn             use game titles from PocketNES Menu Maker database
  -m               mark small ROMs suitable for link transfer
  -c               clean brackets from ROM titles
  -o OUTPUTFILE    compilation output filename, defaults to pocketnes-
                   compilation.gba
  -sav             for EZ-Flash IV firmware 1.x - create a blank 64KB .sav
                   file for the compilation, store in the SAVER folder, not
                   needed for firmware 2.x which creates its own blank saves
  -pat             for EZ-Flash IV firmware 2.x - create a .pat file for the
                   compilation to force 64KB SRAM saves, store in the PATCH
                   folder

coded by patters in 2022

Features

• All scripts:
  • -h for help
  • Drag and drop a selection of ROMs onto the shell window after typing the script name, to easily add multiple ROMs
  • Blank SRAM save file of the appropriate size can now be created automatically using -sav option
  • GSS patch file for EZ-Flash IV firmware 2.x (to force 64KB SRAM saves) can now be created automatically using -pat option
  • Patch file data is encoded within the script body - no external dependency
  • Optional overrides of file paths
  • Can clean brackets from ROM titles with -c option
• Some scripts (as applicable):
  • Splash screen support with -s option
  • Auto-detection of ROM types for emulators that support multiple types with specific header requirements
  • Region options and PAL timings are now auto-detected based on ROM naming
  • Boot-to-BIOS support with -bb option
  • Small ROMs suitable for link transfer (<192KB) can be marked in the game list with -m option
• MSXAdvance:
  • Detects appropriate mapper for added ROMs and records this in a previously unused byte in the header, can opt out using -nomap option
  • Use my new fork of MSXAdvance v0.2 which adds auto mapper selection
• PCEAdvance:
  • ISO and TCD tracklist support for PC Engine CD-ROM²
  • Some sprite follow settings for "Unscaled (Auto)" display mode (those featured in gamelist.txt)
  • CD BIOS automatically added when an ISO image is added, and titled with the ISO name
  • Can trim compilation to fit within 16MB PSRAM with -trim option (needed for certain CD-ROM² titles)
• Goomba:
  • Works around an EZ-Flash issue where some ROMs would cause duplicate game list entries
  • Can prefer ROM filenames in the game list rather than original ROM game titles, with -f option
• PocketNES:
  • Will, if present, lookup ROM checksums in PocketNES Menu Maker database (pnesmmw.mdb) for optimal game settings, sprite/memory follow for "Unscaled (Follow)" display mode
  • Can prefer game titles from PocketNES Menu Maker database with -dbn option
  • 256 byte alignment of all ROM data for optimum performance
• SNESAdvance:
  • SuperDAT database is mandatory (snesadvance.dat, some additional supported titles here)
  • Default graphics assets are encoded in the script, external skin files are ingested if present
  • Can accept headered or unheadered ROMs (.smc/.sfc)
  • Can export header-stripped ROMs with -strip option
  • Can prefer game titles from SuperDAT database with -dbn option
  • Verbose mode with -v option
• Snezziboy:
  • Each game must be bundled with its own emulator instance, though multiple games can be processed in one command line
  • Dat file database is mandatory (snezzi.dat), but can use SNESAdvance SuperDAT also (snesadvance.dat, some additional supported titles here)
  • Can accept headered or unheadered ROMs (.smc/.sfc)
  • Can export header-stripped ROMs with -strip option
  • Verbose mode, to mimic original snezzi.exe builder with -v option
• HVCA:
  • Reconstructs FDS ROM headers if they are missing, which HVCA requires
  • Adds an exit function for EZ-Flash IV / 3in1 / Omega flashcarts
• ZXAdvance:
  • On first run use the -e builder option to extract the emulator from the original ZXAdvance exe file, will accept v1.0.1 or v1.0.1a
  • Adds an exit function for EZ-Flash IV / 3in1 / Omega flashcarts
  • Will retrieve game-specific controls configurations from ZXA.INI
  • Can create a Pogoshell plugin integrating the game configurations from ZXA.INI with the -p builder option
  • Can clean and sort the inifile using the -c option

Automation

With a simple FOR loop the scripts can also create a standalone executable for each game in a folder.

Bash:

for file in *.pce *.iso ; do ./pceadvance_compile.py "${file}" -o "${file%.*}.gba" ; done

Windows:

for %f in (*.pce *.iso) do @pceadvance_compile.py "%f" -o "%~nf.gba"

If you own an EZ-Flash IV flashcart my curated collection of exit-patched emulator binaries will be of interest.

---

Emulator Tips

Cologne

• Find the BIOS rom with the no-delay patch to speed up the boot time: "ColecoVision BIOS (1982) (No Title Delay Hack)"
• R+Start to bring up the virtual controller keypad

MSXAdvance

• The BIOS you need is "MSX System v1.0 + MSX BASIC (1983)(Microsoft)[MSX.ROM]"
• R+Start to bring up the virtual keyboard
• Use my new fork of MSXAdvance v0.2 which adds auto mapper selection
• An early compatibility list
• Versions 0.3 and 0.4 are broken

PCEAdvance

• Audio tends to work pretty well in mixer mode, but you do need to restart the emulator after enabling it
• CD-ROM ISO extracting info, and this forum thread
• CD-ROM² / Super CD-ROM² / Arcade CD-ROM² titles lists, and TOCs
• Speedhacks howto
• Use my new fork of PCEAdvance v7.5 to get additional RAM support for EZ-Flash IV and EZ-Flash 3in1 flashcarts

SMSAdvance

• BIOS booting (effectively a blank 16KB ROM image) requires the system type to be hard set to Master System, assuming Master System BIOS games, because without a ROM the emulator cannot guess which system BIOS (SMS or GG) should be loaded
• "Lock toprows" is an option for Full Screen display mode useful for certain Master System games, such as Outrun, which can keeps the score/speedometer on screen despite cropping the image to the GBA resolution

SNESAdvance

• Start+Select+A+B for the emulator menu
• Select+Up/Down to change screen offset
• List of best functioning games

Snezziboy

• L+R+Start for the emulator menu
• L+R+Select+Up to cycle BG Priority Sets
• L+R+Select+Down to cycle Forced BG Modes
• Wiki page
• Compatibility list

HVCA:

• A .cfg filename must match the filename of the game it targets
• Hold L+R in the menu to exit back to the flashcart menu
• This requires the -x builder option to add a .sub file containing exit code for specific flashcart models. My own hacked flash_ez4_ezo.sub for EZ-Flash IV / 3in1 / Omega is included in this repo.

ZXAdvance:

• ZXA.INI has a [section] for each game filename (lower case without file extension), the 'filename=' key is in fact how the game title will be displayed in the ZXAdvance ROM list. 'Config' can be Custom, or can refer to one of the sections prefixed with 'Config_' at the top of the file - e.g. Config=Kempston