hypercutter 0.3.2

Extract data from GBA Pokemon ROMs.
Documentation

hypercutter

Binary extraction tool for GBA Pokemon ROMs. Rust library + CLI + WebAssembly.

Features

  • Extract tiles, palettes, and metatiles from GBA Pokemon ROMs
  • Supports Pokemon Emerald, FireRed, LeafGreen, Ruby, Sapphire
  • Decompress LZSS-compressed tileset and sprite data
  • Render metatiles as PNG images
  • Dump Pokemon battle sprites (front, back, normal, shiny, alternate forms)
  • Per-form palette and shiny palette support
  • CLI and Rust API
  • WebAssembly bindings for in-browser use

Installation

cargo install hypercutter

Or build from source:

git clone https://github.com/cuebitt/hypercutter
cd hypercutter
cargo build --release
./target/release/hypercutter --help

Usage

hypercutter pokeemerald.gba

Without any flag, both tilesets and sprites are dumped.

Options:

  • -g, --game: Game to use for symbol file download (emerald, firered, leafgreen, ruby, sapphire)
  • --sym-file: Path to a .sym file (auto-downloaded if not provided)
  • -e, --export: Directory to export PNGs (default: out)
  • -v, --verbose: Verbose output
  • -q, --quiet: Suppress all non-error output
  • -c, --clear: Clear export directory before writing
  • -y, --yes: Clear without prompting
  • --overwrite: Write over existing files without prompting (skips clear)

Output selection (mutually inclusive with each other; omitting both dumps everything):

  • --tilesets: Render and export tileset PNGs
  • --sprites: Dump Pokemon battle sprites

Output filtering:

  • --tileset-filter <PATTERN>: Glob pattern to filter which tilesets to extract (e.g. Battle*)
  • --sprite-filter <PATTERN>: Glob pattern to filter which sprites to extract (e.g. pikachu)

Sprite output options (only meaningful with --sprites):

  • --spritesheet: Output sprites as a spritesheet instead of individual PNGs
  • --spritesheet-columns: Columns in spritesheet (default: 8)

Other:

  • --list: List available tilesets or sprites without extracting

Output directory structure

out/
├── tilesets/              # One PNG per metatile group
│   ├── General.png
│   ├── Petalburg.png
│   └── ...
└── pokemon/sprites/       # One subdirectory per species
    ├── 001_bulbasaur/
    │   ├── front.png
    │   ├── front_shiny.png
    │   ├── back.png
    │   └── back_shiny.png
    ├── 025_pikachu/
    │   └── ...
    └── ...

When alternate forms exist (e.g. Unown, Castform), they are written under a forms/ subdirectory:

    025_pikachu/
    └── forms/
        └── <form-name>/
            ├── front.png
            └── back.png

Symbol file auto-download

The .sym file is auto-downloaded from the pret disassembly repositories (via jsDelivr CDN) and cached in your platform's standard cache directory. Override with the HYPERCUTTER_CACHE_DIR environment variable.

Library

use hypercutter::{
    Extractor, FormSprite, Game, Rom, SpeciesId, Sprite, SymbolTable,
    TilesetRenderer, SpriteRenderer,
};

let rom = Rom::open("pokeemerald.gba")?;
let symbols = SymbolTable::from_path("pokeemerald.sym")?;
let extractor = Extractor::new(&rom, &symbols);

// Tilesets
let metatiles = extractor.metatiles()?;
for (name, entry) in metatiles.iter() {
    let mut renderer = TilesetRenderer::new(&entry.primary);
    if let Some(secondary) = &entry.secondary {
        renderer = renderer.with_secondary(secondary);
    }
    let img = renderer.render();
    // img.save_png("...")?;
}

// Base species sprites
let sprites: Vec<Sprite> = extractor.sprites()?;
let names = extractor.species_names()?;
let national_dex = extractor.national_dex_map()?;

// Alternate forms
let forms: Vec<FormSprite> = extractor.forms()?;

WebAssembly / JavaScript

Build the WASM package with wasm-pack:

cargo install wasm-pack
wasm-pack build --release

The build target is configured in wasm-pack.toml. This produces a pkg/ directory with JS glue code, TypeScript types, and a package.json ready for npm publishing.

Once published to npm, install with:

pnpm install hypercutter
import init, {
  HypercutterExtractor,
  identify_game,
  count_sym,
} from "hypercutter";

await init();

// Load ROM and sym file
const romBytes = new Uint8Array(
  await (await fetch("pokeemerald.gba")).arrayBuffer(),
);
const symText = await (await fetch("pokeemerald.sym")).text();

// Identify the game
console.log(identify_game(romBytes)); // "emerald"

// Count symbols in a .sym file
console.log(count_sym(symText)); // 14026

// Create an extractor
const ex = new HypercutterExtractor(romBytes, symText);
console.log(ex.game); // "emerald"

// List metatile groups
const names = ex.metatile_names();
console.log(names); // ["General", "Petalburg", ...]

// Render a tileset to PNG bytes
const pngBytes = ex.render_tileset("General");
const blob = new Blob([pngBytes], { type: "image/png" });
const url = URL.createObjectURL(blob);
// <img src={url} /> or save to disk

// List symbol names used by hypercutter (filtered subset of the memory map)
const symbols = ex.symbol_names();
console.log(symbols); // ["Start", "gMonFrontPicTable", "gTileset_Overworld", ...]

// List species names
const species = ex.species_names();
console.log(species); // ["bulbasaur", "ivysaur", ...]

// Render a Pokémon sprite (by national dex ID) to PNG bytes
const spritePng = ex.render_sprite(1); // Bulbasaur front sprite

Vite

Vite does not support the WebAssembly ESM integration proposal used by wasm-pack output. You need to install two dev dependencies:

pnpm add -D vite-plugin-wasm vite-plugin-top-level-await

Then add them to your vite.config.ts:

import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  plugins: [wasm(), topLevelAwait()],
});

API reference

JS name Type Description
identify_game(romBytes) (Uint8Array) => string Identify game from raw ROM bytes
count_sym(symText) (string) => number Count symbols in a .sym file
HypercutterExtractor constructor new (Uint8Array, string) => HypercutterExtractor Create an extractor from ROM bytes and sym text
HypercutterExtractor.game getter => string Identified game short name
HypercutterExtractor.metatile_names() () => string[] Available metatile group names
HypercutterExtractor.render_tileset(name) (string) => Uint8Array Render a tileset as PNG bytes
HypercutterExtractor.species_names() () => string[] All species names by dex order
HypercutterExtractor.symbol_names() () => string[] Symbol names used by the extraction logic
HypercutterExtractor.render_sprite(speciesId) (number) => Uint8Array Render a Pokémon front sprite as PNG bytes

Development

# Run tests (requires real ROMs in tests/fixtures/)
cargo test --all

# Lint
cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked

# Verify crates.io packaging
cargo package --list
cargo publish --dry-run

# Build for WebAssembly
cargo build --release --target wasm32-unknown-unknown

Pre-commit hooks

This repository uses pre-commit hooks for cargo fmt and cargo clippy, configured in .pre-commit-config.yaml. prek is the preferred tool:

# Install prek (preferred, Rust-native)
cargo install prek --locked
prek install

# Run hooks manually
prek run --all-files

If another tool (e.g. bgit) has set core.hooksPath globally, prek install will refuse to run. Use --git-dir to bypass the check and install into .git/hooks/ directly:

prek install --git-dir .git

Note: this writes prek's shims to .git/hooks/ while Git still uses the global core.hooksPath. To make both work, copy or symlink bgit's hooks (e.g. pre-push) into .git/hooks/ as well.

Alternatively, use pre-commit:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Publishing

Releases are published automatically to crates.io and npm when a version tag (v*) is pushed. The publish workflows are in .github/workflows/.

Forks need these repository secrets to publish:

Secret Purpose Where to get it
CRATES_IO_TOKEN Publish to crates.io crates.io/settings/tokens
NPM_TOKEN Publish to npm npmjs.com → Access Tokens

To release:

# 1. Bump version in Cargo.toml
# 2. Commit and push
# 3. Tag and push the tag
git tag v0.4.0
git push origin v0.4.0

License

MIT OR Apache-2.0

Attribution

This project builds on the work of many open-source libraries and tools:

Libraries

Tools

Reference