Plugins2GBA

Plugin2GBA
General
Author	Kuwanger
Type	File Operation
Version	0.19
License	Mixed
Last Updated	2009/02/10
Links
Download
Website

Plugin2GBA is a binary patcher to allow for PogoShell plugins to be used without Pogoshell. This was specifically created because many flash carts of today (like the EZ-Flash IV) are not Pogoshell compatible. While it would be hypothetically possible to mold Pogoshell to all these flash carts, Pogoshell is mainly oboslete--the main reason for Pogoshell was to more effectively use SRAM and most newer flash carts using massive memory cards for SRAM saves.

This leaves many people migrating from Pogoshell-compatible flash carts to non-Pogoshell-compatible flash carts without acccess to some of the nicer features of Pogoshell. One of those nice features are Pogoshell plugins, applications launched from Pogoshell with reference to a file to use.

Note: This requires Python 2.x to use.

User guide

How to use

There are two types of Pogoshell plugins available: binary and multiboot. Binary plugins tend to end in .gba or .bin while multiboot plugins tend to end in .mb, .mbz, or .mbap. On rare occassion, this doesn't hold, but always in that plugins that appear to be binary plugins are actually multiboot plugins.

Some plugins try to verify that Pogoshell is being used. Some will even look into the Pogoshell filesystem for things like fonts which they'll use. While in the future work might be done to better support plugins which need a legitimate Pogoshell filesystem, as it stands Plugin2GBA is designed to fake a legitimate Pogoshell filesystem for plugins that only use a cursory check.

Usage: plugin2gba.py [-fmzals] [--background=converted_image] output.gba plugin.bin file1.plugin [... filen.plugin]

-f	Adds a fake Pogoshell filesystem. Generally is this not needed. The exception are some of Loopy/FluBBa/Dwedit's emulators. Odds are good you'd probably rather use a compilation and not Plugin2GBA, though.
-m	Support a multiboot plugin; otherwise, plugin.bin is assumed to be a binary plugin. Some plugins will work as both as a binary and a multiboot plugin normally (ie, they will multiboot themselves if run as a binary plugin), but Plugin2GBA's patching will sometimes break the binary plugin mode. So, try out this option if a plugin doesn't seem to be working. Do not mix this option with -z or -a.
-z	Just like -m except for lz77 compressed multiboot files (.mbz). Do not mix this option with -m or -a.
-a	Just like -m except for apack compressed multiboot files (.mbap). Do not mix this option with -m or -z.
-l	Converts the extension of all added files to lowercase. This is needed for some plugins.
-s	Sorts file1.plugin...filen.plugin alphabetically. This is mainly necessary when using wildcards under Windows.
--background=converted_image	Allows you to specify an alternative background image (it must have 223 or fewer colors and be converted through grit). When specifying an image, just include the base part of the name (eg. "background" for "background.img.bin", "background.map.bin", and "background.pal.bin"). If no name is given, "background" is used as the default.
output.gba	The actual gba rom to run.
plugin.bin	The Pogoshell plugin you want to use. The actual extension might be .bin, .gba, or .mb.
file1.plugin ... filen.plugin	One or more files to use with plugin.bin.

Grittier Details

Binary plugins are ones that run from the ROM memory space. In simple terms, that means that Pogoshell passes control to a binary plugin by pushing the binary plugin to the start of the ROM memory space and running it as if it were the only thing on the flash cart. In doing so, Pogoshell also passes some file pointers and filenames in a special place in RAM.

Plugin2GBA patches the first instruction of a binary plugin to jump to a mini-pogoshell to simulate the passing of file pointers and filenames by copying the appropriate data to the same special place in RAM that Pogoshell would.

Multiboot plugins are ones that are run from RAM, specially external work ram. Pogoshell copies a multiboot plugin to RAM then passes some file pointers and filenames in a special place in RAM. Plugin2GBA does the same thing, including a legitimate romheader as some multiboot plugins were never designed to be run as a binary.

While patching can quite possibly break a binary plugin, it's nearly impossible for the same to be true with a multiboot plugin as no patching to the plugin itself is done. Instead, a multiboot plugin is wrapped on both sides with the functions to recreate the function of Pogoshell. With binary plugins, this is impossible; adding to the front would shift addresses. Thankfully, for very few plugins does this seem relevant.

Backgrounds

Using Plugin2GBA for a while, you might notice that as much as you just love the existing background, you'd like to create one of your own. Doing so is relatively easy. The first step is downloading grit, a tool to convert images into GBA (and NDS) compatible data. Extract and copy grit.exe to the directory where you put plugin2gba.

Next, create an 240x160 image with at most 223 colors. Most paint programs allow you to choose to convert an image into an indexed image with an optimized palette of a set number, so this part should be easy. Save your image into the directory where you put plugin2gba.

Now it's as simple as running grit, replacing <your_image> with the name of your image (in doublequotes, if you used spaces in the filename) and <your_converted_image> with the name you want to use with plugin2gba.py: grit <your_image> -pzl -pe224 -gu16 -gzl -gB8 -m -mzl -mRtf -aw256 -ftb -o <your_converted_image>

This produces a collection of <your_converted_image>.*.bin files. These are the image data files used by plugin2gba.py in creating an ouptut.gba. Just be sure to pass --background=<your_converted_image> to plugin2gba.py. Also, remember to not make your image too bright, or it'll be distracting when reading the menu.

Changelog

v0.19 2009-02-10

• Fixed single-file mode to reset properly.

v0.18 2008-10-27

• More options when making a stand-alone gba file.
• Less screen clutter when launching a plugin.

v0.17 2008-10-25

• Make sure each filename is unique.
• Don't reset screen for multiboot plugins.
• A better copy of PocketNES's menu behavior.
• Slightly better handling of restoring list position on restart.

v0.16 2008-10-19

• More properly makes a background.
• Adds a throbber.
• A little smaller/faster.

v0.15 2008-10-13

• Create an actually valid pogoshell filesystem. This fixes bmp.bin.
• It also means you can extract most (all with multiboot) original files with extractfs.py when using the -f option.

v0.14 2008-10-12

• Fix GBA romheader for binary plugins.
• Fix stupid bug I introduced when adding more multiboot plugin options.

v0.13 2008-10-11

• Broken/Don't Use - Add support for lz77 compressed and apack compressed multiboot images.
• Added appropriate options for such. Darkened the background a bit, following my own suggestion.

v0.12 2008-10-10

• Allow much more colorful backgrounds in combination with grit.

v0.11 2008-10-09

• Saves the current position in the menu.

v0.10 2008-10-09

• Fixed globbing support.

v0.09 2008-10-09

• Broken/Don't Use - Attempt to fixing globbing support.
• Added sort option.

v0.08 2008-10-09

• Broken/Don't Use - Fixed the menu to be more PocketNES like and adds glob (wildcard) support for Windows.

v0.07 2008-10-09

• Fixed bugs introduced with v0.05 and menuing.

v0.06 2008-10-08

• Broken/Don't Use - Adds support for background.

v0.05 2008-10-08

• Broken/Don't Use - Adds support for multiple files attached to one plugin, using a menu to select which to use.

v0.04 2008-10-04

• Adds support for the EZ-Flash IV to reset back to the launcher.

v0.03 2008-10-01

• Adds support for multiboot plugins as well.

v0.02 2008-10-01

• Adds support for creating a fake Pogoshell filesystem, for those few plugins which need it.

v0.01 2008-09-30

• Initial release. Supports binary plugins only.

External links

• Author's website - http://kuwanger.net/gba/plugin2gba/ (archived)