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
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 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 ;
let rom = open?;
let symbols = from_path?;
let extractor = new;
// Tilesets
let metatiles = extractor.metatiles?;
for in metatiles.iter
// Base species sprites
let sprites: = extractor.sprites?;
let names = extractor.species_names?;
let national_dex = extractor.national_dex_map?;
// Alternate forms
let forms: = extractor.forms?;
WebAssembly / JavaScript
Build the WASM package with wasm-pack:
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:
import init from "@cuebitt/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 = await ex.;
console.log; // ["General", "Petalburg", ...]
// Render a tileset to PNG bytes
const pngBytes = await 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
const species = await ex.;
console.log; // ["bulbasaur", "ivysaur", ...]
// Render a Pokémon sprite (by national dex ID) to PNG bytes
const spritePng = await ex.; // 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:
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 |
|---|---|---|
identifyGame(romBytes) |
(Uint8Array) => string |
Identify game from raw ROM bytes |
countSym(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.metatileNames() |
() => string[] |
Available metatile group names |
HypercutterExtractor.renderTileset(name) |
(string) => Uint8Array |
Render a tileset as PNG bytes |
HypercutterExtractor.speciesNames() |
() => string[] |
All species names by dex order |
HypercutterExtractor.symbolNames() |
() => string[] |
Symbol names used by the extraction logic |
HypercutterExtractor.renderSprite(speciesId) |
(number) => Uint8Array |
Render a Pokémon front sprite as PNG bytes |
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 are used. This project contains no content from any Pokemon ROM dump.