GBA Emulator Compilation Build Scripts

GBA Emulator Compilation Build Scripts
GBA Emulator Compilation Build Scripts
General
Author	patters
Type	Build Tools and Hacks
Version	2023
License	Mixed
Last Updated	2023/06/09
Links
	Download
	Website
	Source

Python 3 scripts to build emulator + ROM compilations for various emulators for Gameboy Advance. Cross-platform replacements for the original 32bit Windows-only tools.

User guide

Purpose

By combining the emulator binary with the game ROMs and their required metadata, the scripts generate a .gba executable that can be run on the Gameboy Advance.

These scripts are coded in Python 3, making them compatible with most modern platforms, helping to preserve these technical marvels.

Supported emulators

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

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 the author's 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 rather than original ROM game titles in the game list with -f option.
PocketNES:
- Will, if present, lookup ROM checksum 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.
- A .cfg filename must match the filename of the game it targets.

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, you may find the curated collection of exit-patched emulator binaries worth exploring.

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 the author's 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 the author's 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.

External links