Unity Asset Parser

A Rust implementation of Unity asset parsing, inspired by and learning from UnityPy. This project focuses on parsing Unity YAML and binary formats with Rust's memory safety and performance characteristics.

🎯 Project Status

⚠️ Early Development: This is a learning project and reference implementation. It is not production-ready and has significant limitations compared to mature tools like UnityPy.

What This Project Is

• 📚 Learning Exercise: Understanding Unity's file formats through Rust implementation
• 🔍 Parser Focus: Emphasis on parsing and data extraction rather than manipulation
• 🦀 Rust Exploration: Exploring how Rust's type system can help with binary parsing
• 📖 Reference Implementation: Code that others can learn from and build upon

What This Project Is NOT

• ❌ UnityPy Replacement: UnityPy remains the most mature Python solution
• ❌ Asset Editor: This is a read-only parser, not an asset creation/editing tool

🏗️ Architecture

The project uses a workspace structure to organize different parsing capabilities:

unity-asset/
├── unity-asset-core/      # Core data structures and traits
├── unity-asset-yaml/      # YAML file parsing (complete)
├── unity-asset-binary/    # Binary asset parsing (complete)
├── unity-asset-lib/       # Main library crate (published as `unity-asset`)
├── unity-asset-cli/       # CLI tools
│   ├── main.rs           # Synchronous CLI tool
│   └── main_async.rs     # Asynchronous CLI tool (--features async)
├── examples/             # Usage examples and demos
└── tests/                # Integration tests and sample files

Current Capabilities

🔧 YAML Processing (Complete)

• Unity YAML format parsing for common file types (.asset, .prefab, .unity)
• Multi-document parsing support
• Reference resolution and cross-document linking
• Filtering and querying capabilities
• Serialization back to YAML format

🔧 Binary Asset Processing (Advanced)

• AssetBundle structure parsing (UnityFS format)
• SerializedFile parsing with full object extraction
• TypeTree structure parsing and dynamic object reading
• Compression support (LZ4, LZMA, Brotli)
• Metadata extraction and dependency analysis
• Performance monitoring and optimization

🔧 Object Processing (Production Ready)

• AudioClip: Full format support (Vorbis, MP3, WAV, AAC) with Symphonia decoder
• Texture2D: Complete parsing + basic format decoding + PNG export
• Sprite: Full metadata extraction + atlas support + image cutting
• Mesh: Structure parsing + vertex data extraction + basic export
• GameObject/Transform: Hierarchy parsing and relationship mapping

🔧 CLI Tools (Feature Complete)

• Synchronous CLI for file inspection and batch processing
• Asynchronous CLI with concurrent processing and progress tracking
• Export capabilities (PNG, OGG, WAV, basic mesh formats)
• Comprehensive metadata analysis and reporting
• Basic progress reporting

⚠️ Known Limitations

• Some advanced Unity asset types not yet implemented (MonoBehaviour scripts, complex shaders)
• Object manipulation is read-only (no writing back to Unity formats)
• Some edge cases in LZMA decompression may fail on corrupted data
• Advanced texture formats require texture-advanced feature (DXT, ETC, ASTC)
• Audio decoding requires audio feature for Symphonia integration
• Large file performance could be optimized further
• Error messages could be more user-friendly

🚀 Quick Start

Installation

Note: This project will be published to crates.io soon. For now, to try it out:

# Clone and build from source
git clone https://github.com/Latias94/unity-asset.git
cd unity-asset

# Build the library
cargo build --all

# Try the CLI tools
cargo run --bin unity-asset -- --help
cargo run --features async --bin unity-asset-async -- --help

Once published, you'll be able to install it with:

# Add to your Cargo.toml
[dependencies]
unity-asset = "0.1.0"

# Install CLI tools
cargo install unity-asset-cli

Testing Status

We have basic tests for core functionality, but this is not a comprehensive test suite. Some tests pass, others reveal limitations in our implementation.

Comparison with UnityPy

UnityPy is a mature, feature-complete Python library for Unity asset manipulation. This Rust project is:

• Much less mature: UnityPy has years of development and community contributions
• More limited: We focus on parsing, not manipulation or export
• Learning-oriented: This project helps understand Unity formats through Rust
• Experimental: Many features are incomplete or missing

If you need a production tool for Unity asset processing, use UnityPy instead.

📝 Basic Usage Examples

YAML File Parsing

use unity_asset::{YamlDocument, UnityDocument};

// Load a Unity YAML file
let doc = YamlDocument::load_yaml("ProjectSettings.asset", false)?;

// Get basic information
println!("Found {} entries", doc.entries().len());

// Try to find specific objects (may not work for all files)
if let Ok(settings) = doc.get(Some("PlayerSettings"), None) {
    println!("Found PlayerSettings");
}

CLI Usage

# Parse a single YAML file
cargo run --bin unity-asset -- parse-yaml -i ProjectSettings.asset

# Try async processing (experimental)
cargo run --features async --bin unity-asset-async -- \
    parse-yaml -i Assets/ --recursive --progress

🏗️ Architecture Details

This project is organized as a Rust workspace with separate crates for different concerns:

• unity-asset-core: Core data structures and traits
• unity-asset-yaml: YAML format parsing
• unity-asset-binary: Binary format parsing (AssetBundle, SerializedFile)
• unity-asset-lib: Main library crate (published as unity-asset)
• unity-asset-cli: Command-line tools (published as unity-asset-cli)

🙏 Acknowledgments

This project is a learning exercise inspired by and learning from several excellent projects:

UnityPy by @K0lb3

• The gold standard for Unity asset manipulation
• Our primary reference for understanding Unity formats
• Test cases and expected behavior patterns

unity-rs by @yuanyan3060

• Pioneering Rust implementation of Unity asset parsing
• Architecture and parsing technique inspiration
• Binary format handling examples

unity-yaml-parser by @socialpoint-labs

• Original inspiration for this project
• YAML format expertise and reference resolution patterns
• Clean API design principles

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.