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
From source:
&& &&
Usage
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 ;
let rom = open?;
let symbols = resolve_for_rom?;
let extractor = new;
// Tilesets
for in extractor.metatiles?.iter
// Sprites and alternate forms
let sprites: = 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/)
# Lint
# Verify packaging
# WASM build
Pre-commit hooks
Configured in .pre-commit-config.yaml. Install with:
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.
&&
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.