uxie

A data fetching library for Pokemon Gen 4 romhacking. Provides unified access to ROM data from DSPRE projects and decompilation sources.

Table of Contents

• Background
• Features
• Install
• CLI Usage
• Library Usage
• Supported Games
• License

Background

Working with Pokemon Gen 4 ROMs involves multiple data sources: binary files extracted via ndstool or ds-rom, DSPRE projects (folders containing arm9.bin and unpacked/ filesystem), and modern JSON/C source structures from decompilation projects (pokeplatinum/pokeheartgold). Each source has different formats and conventions.

uxie provides a unified interface for reading ROM data regardless of source. Its Workspace::open() function auto-detects the format and returns a consistent API. The library also includes utilities for reading map headers, parsing C enums and defines, and querying relationships between game data.

The name comes from Uxie, the legendary Pokemon known as the "Being of Knowledge."

Features

• Smart Discovery: Automatically detects game version, internal project names, and table offsets
• Unified ROM Access: Auto-detects and reads data from DSPRE projects and decompilation sources
• High-Level Workspace: Unified API for managing symbols, script mappings, text banks, and global script tables
• Global Script Table: Automatic resolution of CallCommonScript IDs to their script files and text banks (supports HGSS binary reading and Platinum hardcoded tables)
• Full C Expression Evaluation: Pratt parser with correct operator precedence for all C operators
• Parallel Loading: Multi-threaded header file loading via rayon (~200ms for 50,000+ symbols)
• Bidirectional Script Resolution: Resolve constants from names to values AND values to names

Install

CLI

cargo install uxie

Library

cargo add uxie

Or add to Cargo.toml:

[dependencies]
uxie = "0.4.0"

For full API documentation, visit docs.rs/uxie.

CLI Usage

All commands support --json for structured output and -p/--project to specify the project path.

Use -d/--decomp to specify a decompilation project path for symbol resolution.

Library Usage

Workspace API

The Workspace struct is the primary entry point:

use uxie::Workspace;

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

// Resolve constants
let val = workspace.resolve_constant("VARS_START"); // Some(16384)

// Bidirectional symbol resolution
let resolved = workspace.resolve_script_symbols("SetFlag FLAG_UNK_0x000A");
println!("{}", resolved); // "SetFlag 10"

// Access global script table for CallCommonScript resolution
if let Some(entry) = workspace.global_script_table.lookup(2050) {
    println!("Script file: {}, Text bank: {}", entry.script_file_id, entry.text_bank_id);
}

SymbolTable API

For parsing C headers and evaluating expressions:

use uxie::SymbolTable;

let mut symbols = SymbolTable::new();
symbols.load_headers_from_dir("include/constants")?;

// Resolve constants
if let Some(val) = symbols.resolve_constant("ITEM_POKE_BALL") {
    println!("ID: {}", val);
}

// Evaluate C expressions with correct precedence
let expr_val = symbols.evaluate_expression("(1 << 8) | (2 << 4) | 3");
println!("Value: {:?}", expr_val); // Some(275)

Reading ROM Headers

use uxie::RomHeader;

let header = RomHeader::open("path/to/header.bin")?;
println!("Game: {:?}", header.detect_game());   // Some(Platinum)
println!("Region: {:?}", header.region());      // Some("USA")

Supported Games

Note: This library is a work in progress. Platinum is the primary target and has the most complete support. HeartGold/SoulSilver support is partial—some NARC paths and data structures differ and are not yet fully implemented.

License

MIT License. See LICENSE for details.

"It is said that its emergence gave humans the intelligence to improve their quality of life." -- Pokédex entry from Pokémon Pearl