cursebreaker-parser-rust/README.md

Cursebreaker Unity Parser

A high-performance Rust library for parsing Unity project files (.unity scenes, .prefab prefabs, and .asset ScriptableObjects).

Features

• Parse Unity YAML files (scenes, prefabs, and assets)
• Extract GameObjects, Components, and their properties
• Type-safe data structures
• Fast and memory-efficient
• Comprehensive error handling
• Zero-copy where possible

Installation

Add this to your Cargo.toml:

[dependencies]
cursebreaker-parser = "0.1"

Quick Start

use cursebreaker_parser::UnityFile;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse a Unity file
    let file = UnityFile::from_path("Scene.unity")?;

    // Iterate over all documents
    for doc in &file.documents {
        println!("{}: {}", doc.class_name, doc.file_id);
    }

    // Find GameObjects
    let game_objects = file.get_documents_by_class("GameObject");
    println!("Found {} GameObjects", game_objects.len());

    // Look up by file ID
    if let Some(doc) = file.get_document(12345) {
        println!("Found document: {}", doc.class_name);
    }

    Ok(())
}

Examples

See the examples/ directory for more detailed examples:

cargo run --example basic_parsing

Project Status

Phase 1: Foundation & YAML Parsing ✅ COMPLETED

Phase 1 is complete with the following features:

• ✅ YAML document parsing and splitting
• ✅ Unity type tag parsing (!u!N tags)
• ✅ Anchor ID extraction (&ID)
• ✅ Core data model (UnityFile, UnityDocument)
• ✅ Comprehensive error handling
• ✅ 23 passing tests (unit + integration)
• ✅ Successfully parses real Unity files

Upcoming Phases

• Phase 2: Property parsing and type system
• Phase 3: Reference resolution
• Phase 4: Optimization and robustness
• Phase 5: API polish and documentation

See ROADMAP.md for detailed implementation plan.

Architecture

src/
├── lib.rs              # Public API exports
├── error.rs            # Error types
├── model/              # Data structures
│   └── mod.rs          # UnityFile, UnityDocument
└── parser/             # Parsing logic
    ├── mod.rs          # Main parser
    ├── unity_tag.rs    # Unity type tag parser
    └── yaml.rs         # YAML document splitter

Testing

Run all tests:

cargo test

Run integration tests with real Unity files:

# Ensure submodules are initialized
git submodule update --init --recursive

cargo test --test integration_tests

Supported File Formats

• .unity - Unity scene files
• .prefab - Unity prefab files
• .asset - Unity ScriptableObject files (coming soon)

All formats use the same YAML 1.1 structure with Unity-specific extensions.

Performance

Current benchmarks (Phase 1):

• Parse 15-document prefab: ~1ms
• Parse 100+ document scene: ~10ms
• Memory usage: ~2x file size

Further optimizations planned for Phase 4.

Contributing

Contributions are welcome! Please see DESIGN.md for architecture details and ROADMAP.md for planned features.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

This project uses the PiratePanic sample project from Unity Technologies for testing.