GBA Emulator Compilation Build Scripts: Difference between revisions

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

Revision as of 13:21, 17 February 2024

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

The scripts combine emulator binaries with game ROMs and their necessary metadata to generate .gba executables that can be run on the Gameboy Advance. They are compatible with most modern platforms, helping to preserve these technical marvels.

Features

All scripts:
- Drag and drop ROMs for easy addition.
- Create blank SRAM save files.
- Create GSS patch files for EZ-Flash IV firmware 2.x (to force 64KB SRAM saves).
- Patch file data embedded in the script (no external dependency).
Some scripts:
- Splash screen support.
- Auto-detection of ROM types, regions, and PAL timings.
- Boot-to-BIOS support.
- Mark small ROMs for link transfer (<192KB).
- Specialized features for MSXAdvance, PCEAdvance, Goomba, PocketNES, SNESAdvance, Snezziboy, HVCA, and ZXAdvance.

User guide

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

Please check the README for usage tips.

External links

@@ Line 13: / Line 13: @@
 |donation=
 }}
-[https://www.python.org/ Python 3] scripts to build emulator + ROM compilations for various emulators for Gameboy Advance. Cross-platform replacements for the original 32bit Windows-only tools.
+[https://www.python.org/ Python 3] scripts to build emulator + ROM compilations for various Gameboy Advance emulators. Cross-platform alternatives to the original 32bit Windows-only tools.
-==User guide==
+The scripts combine emulator binaries with game ROMs and their necessary metadata to generate .gba executables that can be run on the Gameboy Advance. They are compatible with most modern platforms, helping to preserve these technical marvels.
-===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.
+==Features==
+* All scripts:
+** Drag and drop ROMs for easy addition.
+** Create blank SRAM save files.
+** Create GSS patch files for EZ-Flash IV firmware 2.x (to force 64KB SRAM saves).
+** Patch file data embedded in the script (no external dependency).
+* Some scripts:
+** Splash screen support.
+** Auto-detection of ROM types, regions, and PAL timings.
+** Boot-to-BIOS support.
+** Mark small ROMs for link transfer (&lt;192KB).
+** Specialized features for MSXAdvance, PCEAdvance, Goomba, PocketNES, SNESAdvance, Snezziboy, HVCA, and ZXAdvance.
+==User guide==
 ===Supported emulators===
-{| class="wikitable"
+{| class="wikitable sortable"
 ! Emulator||Target System||Author(s)||1st Release||Release page
 |-
@@ Line 51: / Line 61: @@
 | [https://github.com/FluBBaOfWard/NGPGBA NGPGBA]||SNK Neo Geo Pocket / Pocket Color||Flubba||Jul 2008||[https://github.com/FluBBaOfWard/NGPGBA Link]
 |-
-| [https://github.com/EvilJagaGenius/jagoombacolor/releases Jagoomba]||An enhanced Goomba Color fork||FluBBa, Dwedit, Jaga + various||Nov 2021||[https://github.com/EvilJagaGenius/jagoombacolor/releases Link]
+| [[Jagoomba Color GBA|Jagoomba]]||An enhanced Goomba Color fork||FluBBa, Dwedit, Jaga + various||Nov 2021||[https://github.com/EvilJagaGenius/jagoombacolor/releases Link]
 |}
@@ Line 98: / Line 108: @@
 </pre>
-===Features===
+Please check the [https://github.com/patters-match/gba-emu-compilation-builders/blob/main/README.md README] for usage tips.
-*'''All scripts:'''
-**<code>-h</code> 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 <code>-sav</code> option.
-**GSS patch file for EZ-Flash IV firmware 2.x (to force 64KB SRAM saves) can now be created automatically using <code>-pat</code> 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 <code>-c</code> option.
-*'''Some scripts (as applicable):'''
-**Splash screen support with <code>-s</code> 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 <code>-bb</code> option.
-**Small ROMs suitable for link transfer (<192KB) can be marked in the game list with <code>-m</code> option.
-*'''MSXAdvance:'''
-**Detects appropriate mapper for added ROMs and records this in a previously unused byte in the header, can opt out using <code>-nomap</code> option.
-**Use the [https://github.com/patters-syno/msxadvance 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 <code>-trim</code> option (needed for certain CD-ROM² titles).
-*'''Goomba:'''
-**Works around an [https://www.dwedit.org/dwedit_board/viewtopic.php?id=643 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 <code>-f</code> option.
-*'''PocketNES:'''
-**Will, if present, lookup ROM checksum in PocketNES Menu Maker database ([https://web.archive.org/web/20060208115559/http://www.pocketnes.org/tools/pnesmmw12a.zip pnesmmw.mdb]) for optimal game settings, sprite/memory follow for "Unscaled (Follow)" display mode.
-**Can prefer game titles from PocketNES Menu Maker database with <code>-dbn</code> option.
-**256 byte alignment of all ROM data for [https://github.com/Dwedit/PocketNES/issues/5#issuecomment-1107541215 optimum performance].
-*'''SNESAdvance:'''
-**SuperDAT database is mandatory ([https://web.archive.org/web/20080208234615/http://www.snesadvance.org/files/superdat20060124-mog123.zip snesadvance.dat], some additional supported titles [https://github.com/m45t3r/snes9x4d/blob/master/snesadvance.dat 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 <code>-strip</code> option.
-**Can prefer game titles from SuperDAT database with <code>-dbn</code> option.
-**Verbose mode with <code>-v</code> 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 [https://github.com/m45t3r/snes9x4d/blob/master/snesadvance.dat 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: <code>for file in *.pce *.iso ; do ./pceadvance_compile.py "${file}" -o "${file%.*}.gba" ; done</code>
-Windows: <code>for %f in (*.pce *.iso) do @pceadvance_compile.py "%f" -o "%~nf.gba"</code>
-If you own an EZ-Flash IV flashcart, you may find the curated collection of [https://github.com/patters-syno/gba-ezflash-iv-emulators 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 [https://github.com/patters-syno/msxadvance author's new fork of MSXAdvance v0.2] which adds auto mapper selection.
-*An early [https://web.archive.org/web/20070612060046/http://boards.pocketheaven.com/viewtopic.php?t=3768 compatibility list].
-*Versions 0.3 and 0.4 [https://gbatemp.net/threads/msxadvance-compatibility-many-games-in-gamelist-txt-dont-work.609615/ are broken].
-'''PCEAdvance:'''
-*Audio tends to work pretty well in mixer mode, but you do need to restart the emulator after enabling it.
-*[https://github.com/patters-syno/pceadvance#pc-engine-cd-rom-support CD-ROM ISO extracting info], and [https://gbatemp.net/threads/pceadvance-cd-rom-support-howto-required.610542/ this forum thread].
-*[https://www.necstasy.net/ CD-ROM² / Super CD-ROM² / Arcade CD-ROM² titles lists, and TOCs].
-*[https://web.archive.org/web/20060508083011/http://boards.pocketheaven.com/viewtopic.php?t=27 Speedhacks howto].
-*Use the [https://github.com/patters-syno/pceadvance 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.
-*[https://web.archive.org/web/20050305113636/http://ygodm.tonsite.biz/snesadv/snesadv_gamelist.html 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.
-*[https://web.archive.org/web/20090503124323/http://wiki.pocketheaven.com/Snezziboy Wiki page].
-*[https://web.archive.org/web/20090508192702/http://wiki.pocketheaven.com/Snezziboy_Compatibility_List Compatibility list].
 == External links ==