pkmn-savedata

Rust library for reading and manipulating save data for Pokémon games.

Currently this only supports GBA (Generation 3) games. Save data from some ROM hacks may work but others will not.

Goals

• No unsafe code.
• no_std compatible. Build with no-default-features if you want this.
• Endianness safe: usable on both little- and big-endian targets.
• Limit the number of ways user code can break saves without sacrificing flexibility.
• Do not panic with any input save data, no matter how malformed.
• Do not panic no matter how callers interact with this library as long as they don't use unsafe code to tamper with private structures or exhaust heap memory.
• Support all official international releases of supported games.

Non-Goals

• No spinoff games: Mystery Dungeon, Ranger, etc.
• No PC fan-games: RPG Maker, etc.
• No server-based titles: Pokémon Go, Bank, Home

Usage

Use this crate as a library dependency by adding it to your Cargo.toml. If you build with no standard library, note that alloc is required.

[dependencies]
pkmn-savedata = {version = "0.1.0", default-features = false, features = ["std"]}

Binary

This crate also includes an executable binary that can be installed with cargo install pkmn-savedata.

Some examples of things you can do with it:

• Print help text.
  $ pkmn-savedata --help
• Print out trainer info including name, playtime, pokedex info, etc.
  $ pkmn-savedata trainer ruby english "Pokemon - Ruby Version (USA).sav"
• Extract all Pokémon from the PC as pkm3 files.
  $ pkmn-savedata pkm "Pokemon - Ruby Version (USA).sav" ruby_pkm
• Print out the contents of a pkm3 file as json.
  $ pkmn-savedata pkm-decode ruby_pkm/PC01/01.pkm3

TODO

• Add C and C++ bindings (locked behind a feature flag which permits unsafe)
• Support for a wider variety of GBA ROM hacks
• Game Boy games: Red, Green, Blue, Yellow, Gold, Silver, Crystal
• DS Gen4 games: Diamond, Pearl, Platinum, HeartGold, SoulSilver
• DS Gen5 games: Black, White, Black 2, White 2
• N64 games: Stadium, Stadium 2, Japanese Stadium
• GameCube games: Colosseum, XD, Box
• Wii: My Pokémon Ranch

Possible further future

Modern Pokémon games aren't a short-term goal but would be nice to include later.

• 3DS Gen6 games: X, Y, Omega Ruby, Alpha Sapphire
• 3DS Gen7 games: Sun, Moon, Ultra Sun, Ultra Moon
• Switch games