146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# 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.
|