Skip to main content

Crate pkmn_savedata

Crate pkmn_savedata 

Source
Expand description

§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.2.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

§Examples

ⓘ
use pkmn_savedata::gba::{GbaSave, LanguageGBA};
use std::fs::File;

let file = File::open("Ruby.sav")?;
let save = GbaSave::from_reader(file, LanguageGBA::English)?;
let game_state = save.game_state;
assert_eq!(game_state.trainer_id(), (12345, 22222));
assert_eq!(game_state.pokedex_count(), 50);

// Print the names of every Pokemon in Box 1.
let box1 = save.boxes().box_ref(0)?;
for pkm in box1.contents() {
    if pkm.exists() {
        let decoded = pkm.decode();
        if let Some(nickname) = decoded.nickname() {
            println!("{}", nickname.to_ref().decode());
        }
    }
}

Re-exports§

pub use pkmn_core_types as core_types;
pub use pkmn_strings as strings;

Modules§

gba
Save data implementation for GBA (Generation 3) Pokémon games.

Enums§

SaveError
Error type used by this crate.

Type Aliases§

Result
Result type used by this crate.