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
• Build from Source
• CLI Usage
• Library Usage
• Contributing
• 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 from standard project structure 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 project type and decomp family from on-disk structure, plus game/version and table offsets for binary projects
• 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
• Strict Constant Expression Evaluation: Pratt parser for arithmetic/bitwise/shift/comparison/logical constant expressions; unsupported constructs fail explicitly
• 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.5.6"

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

Build from Source

This repository keeps nitroarc as a git submodule at the project root in nitroarc/.

Clone recursively, then build:

git clone --recursive https://github.com/KalaayPT/uxie.git
cd uxie
cargo build

If you already cloned without submodules, run git submodule update --init --recursive.

uxie uses the nitroarc_ffi shared library for NARC support, so you will need a working Rust toolchain plus a C compiler available on your system.

If the submodule is missing, builds will fail because the NARC implementation now comes from nitroarc rather than the previous in-house parser.

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")

Contributing

See CONTRIBUTING.md for development workflow, testing setup, lint expectations, and documentation update policy.

Supported Games

Note: Platinum is the primary target and has the most complete support. HeartGold/SoulSilver support has improved substantially, but remains partial in some workflows.

License

This project is licensed under the MIT License. See LICENSE for details.

Note: the repository currently includes nitroarc as a git submodule, and it is licensed separately under the GNU LGPL-3.0-or-later. If you redistribute builds that include it, make sure you also comply with that dependency's license terms. The intended model is to ship nitroarc_ffi as a separate shared library alongside uxie.

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