Crate uxie

Crate uxie 

Source
Expand description

§Uxie - Data fetching library for Pokemon Gen 4 Romhacking

Named after the legendary Pokémon Uxie, the “Being of Knowledge”, this library provides unified access to ROM data from multiple sources: DSPRE projects, decompilation sources (pokeplatinum/pokeheartgold), and raw binary files.

§Quick Start

use uxie::{Workspace, RomHeader};

// Auto-detect and open any supported project
let workspace = Workspace::open("path/to/project")?;

// Resolve constants from any loaded header file
if let Some(value) = workspace.resolve_constant("ITEM_POKE_BALL") {
    println!("Poké Ball ID: {}", value);
}

// Read ROM header information
let header = RomHeader::open("path/to/header.bin")?;
println!("Game: {:?}", header.detect_game());

§Core Features

  • Smart Project Detection: Automatically detects DSPRE projects, decompilation sources, and raw binaries
  • Unified Symbol Resolution: Parse C headers, enums, and defines with full expression evaluation
  • High Performance: ~200ms to load 50,000+ symbols with parallel parsing and caching
  • Map Header Access: Read map data across all Gen 4 games (Diamond, Pearl, Platinum, HeartGold, SoulSilver)
  • Script & Text Banks: Bidirectional symbol resolution for game scripts and text archives
  • Format Agnostic: Seamlessly handle binary formats (NARC, arm9.bin) and modern JSON/YAML sources

§Module Organization

  • workspace: High-level API for managing projects, symbols, scripts, and text banks
  • rom_header: ROM header reading with auto-detection of game version and region
  • c_parser: C header file parsing with full expression evaluation (enums, defines, includes)
  • map_header: Map header structures for all Gen 4 games
  • provider: Trait-based data access for different project types
  • event_file / encounter_file: Event and encounter data structures
  • ds_rom: DSPRE and ds-rom-tool project structures
  • narc: Nintendo Archive (NARC) file format reader
  • game: Game version detection and family classification

§Examples

§Working with Decompilation Projects

use uxie::Workspace;

let workspace = Workspace::open("path/to/pokeplatinum")?;

// Access the symbol table
if let Some(val) = workspace.resolve_constant("FLAG_HIDE_RIVAL") {
    println!("Flag value: {}", val);
}

// Bidirectional script resolution
let script = "SetFlag FLAG_HIDE_RIVAL";
let resolved = workspace.resolve_script_symbols(script);
println!("{}", resolved); // "SetFlag 1234"

§Parsing C Headers

use uxie::SymbolTable;

let mut symbols = SymbolTable::new();

// Load all headers from a directory
symbols.load_headers_from_dir(temp_dir.join("include"))?;

// Evaluate complex expressions
let value = symbols.evaluate_expression("(1 << 8) | 0xFF");
assert_eq!(value, Some(0x1FF));

§Reading Map Headers

use uxie::{Arm9Provider, GameFamily, DataProvider};

let provider = Arm9Provider::new(
    "path/to/arm9.bin",
    0xE601C,  // Platinum table offset
    559,      // Header count
    GameFamily::Platinum,
);

let header = provider.get_map_header(0)?;
println!("Map 0 script file ID: {}", header.script_file_id());

§Performance

Uxie is optimized for high-throughput symbol resolution:

  • ~200ms: Load 50,000+ symbols from pokeplatinum
  • < 1 microsecond: Cached constant resolution (O(1) lookup)
  • < 5 microseconds: Complex C expression evaluation
  • Parallel loading: Multi-threaded header parsing via rayon
  • Smart caching: Global canonical path cache and expression evaluation cache

§Supported Games

GameRegion CodesFamily
DiamondADAE (US), ADAJ (JP), ADAP (EU)DP
PearlAPAE (US), APAJ (JP), APAP (EU)DP
PlatinumCPUE (US), CPUJ (JP), CPUP (EU)Platinum
HeartGoldIPKE (US), IPKJ (JP), IPKP (EU)HGSS
SoulSilverIPGE (US), IPGJ (JP), IPGP (EU)HGSS

§Design Philosophy

Uxie bridges the gap between legacy binary ROM hacking tools and modern decompilation workflows:

  • Universal Symbols: Single namespace for C headers, assembly constants, and binary offsets
  • Toolchain Agnostic: Works with DSPRE, ds-rom-tool, and decompilation projects
  • Format Fluidity: Unified API regardless of source format (binary, YAML, JSON, C)
  • Zero Configuration: Smart auto-detection for standard project structures

Re-exports§

pub use c_parser::SymbolTable;
pub use ds_rom::DsRomArm9Config;
pub use ds_rom::DsRomToolProject;
pub use ds_rom::DspreProject;
pub use egg_move_data::EGG_MOVE_SPECIES_OFFSET;
pub use egg_move_data::EGG_MOVE_TERMINATOR;
pub use egg_move_data::EggMoveData;
pub use egg_move_data::EggMoveEntry;
pub use encounter_file::BinaryEncounterFile;
pub use encounter_file::JsonEncounterFile;
pub use error::Result;
pub use error::UxieError;
pub use event_file::BgEventBinary;
pub use event_file::BgEventJson;
pub use event_file::BinaryEventFile;
pub use event_file::CoordEventBinary;
pub use event_file::CoordEventJson;
pub use event_file::JsonEventFile;
pub use event_file::ObjectEventBinary;
pub use event_file::ObjectEventJson;
pub use event_file::WarpEventBinary;
pub use event_file::WarpEventJson;
pub use evolution_data::EVOLUTION_FILE_SIZE;
pub use evolution_data::EVOLUTIONS_PER_SPECIES;
pub use evolution_data::EvolutionData;
pub use evolution_data::EvolutionEntry;
pub use evolution_data::EvolutionMethod;
pub use game::Game;
pub use game::GameFamily;
pub use game::GameLanguage;
pub use item_data::BattlePocket;
pub use item_data::FieldPocket;
pub use item_data::ITEM_DATA_SIZE;
pub use item_data::ItemData;
pub use item_data::ItemPartyUseParam;
pub use learnset_data::LEARNSET_TERMINATOR;
pub use learnset_data::LearnsetData;
pub use learnset_data::LearnsetEntry;
pub use map_header::MapHeader;
pub use map_header::MapHeaderJson;
pub use move_data::MOVE_DATA_SIZE;
pub use move_data::MoveData;
pub use move_data::MoveFlags;
pub use move_data::MoveSplit;
pub use narc::Narc;
pub use personal_data::PERSONAL_DATA_SIZE;
pub use personal_data::PersonalData;
pub use provider::Arm9Provider;
pub use provider::DataProvider;
pub use rom_header::RomHeader;
pub use script_file::ScriptTable;
pub use text_bank::GameStrings;
pub use text_bank::TextBankTable;
pub use trainer_data::AiFlags;
pub use trainer_data::PartyPokemon;
pub use trainer_data::TRAINER_PROPERTIES_SIZE;
pub use trainer_data::TrainerData;
pub use trainer_data::TrainerFlags;
pub use trainer_data::TrainerProperties;
pub use workspace::ProjectType;
pub use workspace::Workspace;

Modules§

c_parser
C header file parsing with full expression evaluation
ds_rom
DSPRE and ds-rom-tool project structures
egg_move_data
encounter_file
Wild Pokemon encounter table parsing
error
Error types for the Uxie library
event_file
Event file parsing for Pokemon Gen 4 maps
evolution_data
game
Game version detection and configuration
item_data
learnset_data
map_header
move_data
narc
Nintendo Archive (NARC) file format reader and writer
personal_data
provider
Data provider abstraction for accessing ROM data from different sources
rom_header
ROM header reading and parsing for Nintendo DS Pokemon Gen 4 games
script_file
Script file handling for Gen 4 Pokémon games.
text_bank
trainer_data
workspace
High-level workspace API for managing ROM hacking projects