hypercutter 0.5.0

Extract data from GBA Pokemon ROMs.
Documentation

hypercutter

Extract tiles, palettes, sprites, and field effects from GBA Pokemon ROMs. Ships as a Rust library, a CLI binary, and WebAssembly bindings.

Supports Emerald, FireRed, LeafGreen, Ruby, and Sapphire.

Features

  • Tilesets, metatiles, and palettes (with LZSS decompression)
  • Battle sprites: front/back, normal/shiny palette variants, alternate forms
  • Overworld character sprites, packed into facing-frames grids
  • Field effect sprites (tall grass, surf blob, shadows, etc.) with palettes resolved from the game's script bytecode
  • PNG rendering for everything

Installation

cargo install hypercutter

From source:

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

Usage

hc pokeemerald.gba

By default this exports a sprite pack: overworld sprites in a facing-frames grid with manifest.json. Field effects go to out/field_effects/.

Common flags:

Flag Description
-e, --export <DIR> Output directory (default: out)
--sym-file <FILE> Custom symbol file (TOML or .sym). Bundled tables by default.
-v / -q Verbose / quiet output
-c / -y / --overwrite Output handling (clear, skip prompts, overwrite)
--tileset-filter <PAT> Glob pattern to filter which tilesets to extract
--sprite-filter <PAT> Glob pattern to filter which sprites to extract

Symbol tables are bundled as TOML inside the binary. Use --sym-file to override for ROM hacks.

Library

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

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

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

// Sprites and alternate forms
let sprites: Vec<Sprite> = extractor.sprites()?;
let forms = extractor.forms()?;

WebAssembly

See WASM_JAVASCRIPT.md for JS usage, Vite setup, and API reference.

Development

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

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

# Verify packaging
cargo package --list
cargo publish --dry-run

# WASM build
cargo build --release --target wasm32-unknown-unknown

Pre-commit hooks

Configured in .pre-commit-config.yaml. Install with:

cargo install prek --locked
prek install
prek run --all-files

If another tool (e.g. bgit) sets core.hooksPath globally, try prek install --git-dir .git and copy that tool's hooks into .git/hooks/. pre-commit (pip) works too.

Publishing

Push a v* tag and GitHub Actions publishes to crates.io and npm automatically. Forks need CRATES_IO_TOKEN and NPM_TOKEN secrets.

git tag v0.4.0 && git push origin v0.4.0

License

MIT OR Apache-2.0

Attribution

The TOML memory maps are built from the pret/pokeemerald, pret/pokefirered, and pret/pokeruby.

This project contains no content from any Pokemon ROM dump.

See Cargo.toml for the full dependency list.