PixelPet - Automated graphics processing for GBA/NDS

[Prof. 9]

Introduction
PixelPet is a graphics processing tool intended for ROM hacks. I started work on PixelPet a number of years ago, because I was unsatisfied by the options available in contemporary tools, like grit, and wanted more fine-grained control over my tileset/tilemap generation. Over the past years I've used PixelPet in pretty much all of my projects to great effect. Since the API and codebase have gotten fairly stable, I felt this would be a good time for a more public release.

Currently PixelPet is geared towards Game Boy Advance and Nintendo DS, with full support for 4BPP and 8BPP tilesets/tilemaps and bitmaps. However, it should be easy to add other graphics formats as needed. There is some very early support for Game Boy as well.

PixelPet is intended to be a "Swiss Army knife" of automated graphics processing for ROM hacks. The key principle is that PixelPet usage is imperative, rather than declarative. You can define every step of the pipeline, which ends up giving you far more control over the output. PixelPet is fully command line-based and should be easy to integrate into automated build scripts. I've also used Python scripts to generate a script for PixelPet before.

Usage explanation
Basically, how it works is that PixelPet creates a workbench holding a bitmap image, byte stream, tilemap, tileset and palette set. You can then interact with those objects in any way you like. The basic flow looks something like this:

• Load a palette
• Load an image
• Generate a tilemap + indexed tiles from the image
• Export tilemap to file
• Export tileset to file
• Export palette to file

(Some steps left out for simplicity.)

The cool part is that each of these steps can be reordered, or additional steps added in between. Want to load an additional image and generate a tilemap from that too, but combine it with the tileset from the previous image? Sure, you can do that:

• Load a palette
• Load an image
• Generate a tilemap + indexed tiles from the image
• Export tilemap to file
• Clear the tilemap (but keep the tileset)
• Load another image
• Generate a tilemap + indexed tiles from the image - merging any new tiles into the previous tileset
• Export tilemap to file
• Export tileset to file
• Export palette to file

And just like that, you've generated two tilemaps that share the same tileset and palette. What if you want the second image to use a different palette, but still use the same tileset? No problem, simply load in the new palette with the second image. Since both tilesets are indexed, PixelPet will even be able to combine tiles that use different palettes if they end up sharing the same color indexes for each pixel.

Highlight features

• Uses human-editable PNG files as input. This lets you easily make tweaks using standard image editing tools, rather than needing to use specialized tools like tile editors.
• Predetermined palettes can be loaded from a color strip image, giving you full control over the position of each color in the palette. Alternatively, you can also auto-generate a palette from a given image.
• Supports multiple palettes, with any number of colors per palette. For instance, you could have 16 palettes with 16 colors each, or one palette with 256 colors. Or any combination, really.
• Palettes can be swapped in/out at any point in the pipeline. This lets you do fun things like generating different parts of the same tileset with different palettes or even specific subsets of the same palette, by loading differently masked versions of the same palette. This is useful if you're looking to use e.g. palette animation.
• Tilemaps are optimized by reducing duplicate tiles, including by flipping tiles horizontally and/or vertically if the tilemap format allows it. But you can also turn this optimization off, if you want to generate e.g. OAMs.
• You can choose a base tile index for the tilemap. This can be useful when your tileset is loaded into a predetermined location in VRAM. Similarly, you can manually specify each palette's number in VRAM.
• Tilemaps can be generated using multiple palettes at once. Want to convert an image for a game level and need to use a different palette for trees and water? Simply load the palettes into the correct VRAM slots and PixelPet will automatically use them.
• You can combine multiple images to build separate tilemaps that all use the same tileset. For instance, when generating menu screens that all use a shared tileset, but have a separate tilemap per screen.
• You can also use only a subsection of the loaded image; for instance, if you want certain tiles to be at the start of the tileset, process that part of the image first, and then process the rest of the image.
• PixelPet can also work in the other direction: given a set of tilesets, tilemaps and palettes, it can combine them to render PNG images.
• PixelPet is fully open source, with automated builds on GitHub.
• Runs on Windows, macOS and Linux (.NET 7 runtime is required).

Links:

• Downloads on GitHub releases
• Documentation

Example usage of PixelPet in projects:

• Mega Man Battle Chip Challenge - Chip Control
• Mea Man Battle Network 2 (No G Code)
• Mega Man Star Force DX

Some older projects where PixelPet is used - these have some command differences over the release version:

• Mega Man Battle Network - Operate Star Force Demo Version - English translation
• Mega Man Battle Network 4.5: Real Operation - English translation