# 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`:

```toml
[dependencies]
cursebreaker-parser = "0.1"
```

## Quick Start

```rust
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:

```bash
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](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:

```bash
cargo test
```

Run integration tests with real Unity files:

```bash
# 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](DESIGN.md) for architecture details and [ROADMAP.md](ROADMAP.md) for planned features.

## License

Licensed under either of:

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

at your option.

## Acknowledgments

This project uses the [PiratePanic](https://github.com/Unity-Technologies/PiratePanic) sample project from Unity Technologies for testing.