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
- Extract overworld object event sprites (NPCs, Pokemon, items, decorations)
- Extract Pokemon footprints as PNG images
- CLI and Rust API
- WebAssembly bindings for in-browser use
Installation
Or build from source:
Usage
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.symfile (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 all dumps everything):
--tilesets: Render and export tileset PNGs--sprites: Dump Pokemon battle sprites--overworld: Dump overworld object event 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)
Overworld output options (only meaningful with --overworld):
--overworld-filter <PATTERN>: Glob pattern to filter overworld sprites--overworld-shiny: Include shiny palette variants for overworld sprites--overworld-spritesheet: Output overworld sprites as a spritesheet--overworld-columns: Columns in overworld spritesheet (default: 8)
Other:
--list: List available tilesets, sprites, or overworld objects without extracting
Output directory structure
out/
├── tilesets/ # One PNG per metatile group
│ ├── General.png
│ ├── Petalburg.png
│ └── ...
├── sprites/pokemon/ # One subdirectory per species
│ ├── 001_bulbasaur/
│ │ ├── front.png
│ │ ├── front_shiny.png
│ │ ├── back.png
│ │ ├── back_shiny.png
│ │ └── footprint.png
│ ├── 025_pikachu/
│ │ └── ...
│ ├── egg/ # Egg sprite (species 412)
│ └── 000_??????????/ # Circled Question Mark (species 0)
├── sprites/overworld/ # One subdirectory per overworld sprite
│ ├── 000_Brendan/
│ │ ├── frame_0.png
│ │ └── ...
│ └── ...
└── forms/ # Alternate forms (adjacent to sprites/pokemon)
├── unown_a/
│ ├── 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 ;
let rom = open?;
let symbols = from_path?;
let extractor = new;
// Tilesets
let metatiles = extractor.metatiles?;
for in metatiles.iter
// Base species sprites (includes front, back, palette, footprint)
let sprites: = extractor.sprites?;
let names = extractor.species_names?;
let national_dex = extractor.national_dex_map?;
// Render a footprint to PNG
if let Some = sprites.footprint
// Alternate forms
let forms: = extractor.forms?;
// Overworld sprites (NPCs, Pokemon, items, decorations)
let overworld: = extractor.overworld_sprites?;
WebAssembly / JavaScript
Build the WASM package with wasm-pack:
WASM optimization settings are configured in Cargo.toml under [package.metadata.wasm-pack.profile.release]. 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:
import init from "hypercutter";
await ;
// Load ROM and sym file
const romBytes = ;
const symText = await .;
// Identify the game
console.log; // "emerald"
// Count symbols in a .sym file
console.log; // 14026
// Create an extractor
const ex = ;
console.log; // "emerald"
// List metatile groups
const names = ex.;
console.log; // ["General", "Petalburg", ...]
// Render a tileset to PNG bytes
const pngBytes = ex.;
const blob = ;
const url = ;
// <img src={url} /> or save to disk
// List symbol names used by hypercutter (filtered subset of the memory map)
const symbols = ex.;
console.log; // ["Start", "gMonFrontPicTable", "gTileset_Overworld", ...]
// List species names (by species index)
const species = ex.;
console.log; // ["bulbasaur", "ivysaur", ...]
// Render a Pokémon sprite (by national dex ID) to PNG bytes
const spritePng = ex.; // Bulbasaur front sprite
// List overworld sprite names
const overworld = ex.;
console.log; // ["Brendan", "May", "CuttableTree", ...]
// Render a single frame of an overworld sprite to PNG bytes
const framePng = ex.;
Vite
Vite does not support the WebAssembly ESM integration proposal used by wasm-pack
output. You need to install two dev dependencies:
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 species index order |
HypercutterExtractor.symbol_names() |
() => string[] |
Symbol names used by the extraction logic |
HypercutterExtractor.render_sprite(id) |
(number) => Uint8Array |
Render a Pokémon front sprite as PNG bytes |
HypercutterExtractor.overworld_sprite_names() |
() => string[] |
Names of all overworld object event sprites |
HypercutterExtractor.render_overworld_frame(name, frame) |
(string, number) => Uint8Array |
Render a single overworld sprite frame |
Development
# Run tests (requires real ROMs in tests/fixtures/)
# Lint
# Verify crates.io packaging
# Build for WebAssembly
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)
# Run hooks manually
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:
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:
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
License
MIT OR Apache-2.0
Attribution
This project builds on the work of many open-source libraries and tools:
Libraries
- nintendo-lz: LZSS decompression
- clap: CLI argument parsing
- ureq: HTTP client for symbol file downloads
- png: PNG encoding for rendered images
- binrw: Binary data parsing of ROM structures
- bilge: Bitfield struct support
- wasm-bindgen / js-sys: WebAssembly bindings
- serde: Serialization framework
- thiserror / anyhow: Error handling
- dialoguer: Interactive prompts
- indicatif: Progress bars
- console: Terminal styling
- rayon: Parallel iteration
- glob: Pattern matching
- sha2: ROM hashing / game identification
- dirs: Platform cache directory resolution
Tools
- wasm-pack: WebAssembly build tooling
Reference
- pret/pokeemerald, pret/pokefirered, pret/pokeruby
- Only the memory maps and symbol names are used. This project contains no content from any Pokemon ROM dump, no game code, and no copyrighted assets.