492 lines
18 KiB
Markdown
492 lines
18 KiB
Markdown
# ROADMAP: GUID Resolution for MonoBehaviour Components
|
|
|
|
## Executive Summary
|
|
|
|
The `#[derive(UnityComponent)]` macro system is **fully functional** for parsing custom Unity components. However, Unity stores custom MonoBehaviour scripts in scene/prefab files using a generic `MonoBehaviour` class name with a GUID reference to the actual script. To enable automatic discovery and parsing of custom components like `PlaySFX` from real Unity projects, we need to implement **GUID → Class Name resolution**.
|
|
|
|
## Current Status ✅
|
|
|
|
### What's Working
|
|
|
|
1. **Procedural Macro System**
|
|
- `#[derive(UnityComponent)]` generates parsing code automatically
|
|
- Supports all Unity primitive types (f64, String, bool, Vector3, etc.)
|
|
- Generates `UnityComponent::parse()` implementation
|
|
- Generates `EcsInsertable::insert_into_world()` implementation
|
|
|
|
2. **Auto-Registration via Inventory**
|
|
- Components automatically register themselves at compile time
|
|
- `build_world_from_documents()` discovers and registers all custom components
|
|
- No manual modification of builder.rs needed
|
|
|
|
3. **Type Filtering System**
|
|
- `TypeFilter` allows selective parsing for performance
|
|
- `parse_with_types!` macro for ergonomic type selection
|
|
- Works with both Unity types and custom types
|
|
|
|
4. **ECS Integration**
|
|
- Custom components insert into Sparsey ECS world
|
|
- Components can be queried via `world.borrow::<PlaySFX>()`
|
|
- Full integration with existing Transform, GameObject, etc.
|
|
|
|
### What's Missing
|
|
|
|
**MonoBehaviour GUID Resolution**: Unity scene/prefab files store custom scripts like this:
|
|
|
|
```yaml
|
|
--- !u!114 &1234567
|
|
MonoBehaviour: # ⚠️ Generic class name, not "PlaySFX"
|
|
m_GameObject: {fileID: 890}
|
|
m_Script: {fileID: 11500000, guid: 091c537484687e9419460cdcd7038234, type: 3} # 👈 Actual type
|
|
volume: 1.0
|
|
startTime: 0.0
|
|
endTime: 5.0
|
|
isLoop: 0
|
|
```
|
|
|
|
**Problem**: When parsing, we see `class_name = "MonoBehaviour"`, so we can't match it to the `PlaySFX` component registration.
|
|
|
|
**Solution**: Resolve the `m_Script` GUID to discover the actual class name `"PlaySFX"`.
|
|
|
|
## The GUID Resolution Feature
|
|
|
|
### How Unity GUID Resolution Works
|
|
|
|
1. **Every asset has a .meta file** alongside it with a unique GUID:
|
|
```
|
|
Assets/Scripts/PlaySFX.cs # The actual C# script
|
|
Assets/Scripts/PlaySFX.cs.meta # Contains GUID
|
|
```
|
|
|
|
2. **The .meta file contains the GUID**:
|
|
```yaml
|
|
fileFormatVersion: 2
|
|
guid: 091c537484687e9419460cdcd7038234 # 👈 This is the GUID
|
|
MonoImporter:
|
|
serializedVersion: 2
|
|
defaultReferences: []
|
|
executionOrder: 0
|
|
```
|
|
|
|
3. **MonoBehaviour references the GUID**:
|
|
```yaml
|
|
m_Script: {fileID: 11500000, guid: 091c537484687e9419460cdcd7038234, type: 3}
|
|
```
|
|
|
|
4. **We need to map**: `GUID → Script Path → Class Name`
|
|
- `091c537484687e9419460cdcd7038234` → `Assets/Scripts/PlaySFX.cs` → `"PlaySFX"`
|
|
|
|
### Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Unity Project Parsing │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 1. Scan for .meta files (*.cs.meta) │
|
|
│ Build GUID → Asset Path mapping │
|
|
│ Parse class name from .cs files │
|
|
│ Result: GuidResolver { guid → class_name } │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 2. Parse Unity files (.unity, .prefab) │
|
|
│ When encountering MonoBehaviour: │
|
|
│ - Extract m_Script.guid │
|
|
│ - Lookup guid in GuidResolver │
|
|
│ - Get actual class_name (e.g., "PlaySFX") │
|
|
│ - Match with component registry │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 3. Component Registration (via inventory) │
|
|
│ Check if class_name matches registered component │
|
|
│ If match found: │
|
|
│ - Call component.parse_and_insert() │
|
|
│ - Insert into ECS world │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Implementation Plan
|
|
|
|
### Phase 1: GUID → Asset Path Resolution
|
|
|
|
**Goal**: Build a mapping from GUID to file path by scanning .meta files
|
|
|
|
**New Module**: `src/parser/guid_resolver.rs`
|
|
|
|
```rust
|
|
/// Resolves Unity GUIDs to asset paths
|
|
pub struct GuidResolver {
|
|
/// Map from GUID string to asset file path
|
|
guid_to_path: HashMap<String, PathBuf>,
|
|
}
|
|
|
|
impl GuidResolver {
|
|
/// Scan a Unity project directory for .meta files
|
|
pub fn from_project(project_path: &Path) -> Result<Self> {
|
|
// 1. Find all *.meta files (recursively)
|
|
// 2. Parse each .meta file to extract GUID
|
|
// 3. Derive asset path from .meta path (remove .meta extension)
|
|
// 4. Build HashMap
|
|
}
|
|
|
|
/// Look up a GUID to get the asset path
|
|
pub fn resolve(&self, guid: &str) -> Option<&Path> {
|
|
self.guid_to_path.get(guid).map(|p| p.as_path())
|
|
}
|
|
}
|
|
```
|
|
|
|
**Files to Create/Modify**:
|
|
- 📄 `src/parser/guid_resolver.rs` - New file
|
|
- 📄 `src/parser/mod.rs` - Export GuidResolver
|
|
- 📄 `src/lib.rs` - Re-export GuidResolver
|
|
|
|
**Implementation Details**:
|
|
1. Recursively walk project directory
|
|
2. Filter for `*.cs.meta` files (MonoBehaviour scripts)
|
|
3. Parse YAML to extract `guid:` field
|
|
4. Store `guid → "Assets/Scripts/PlaySFX.cs"` mapping
|
|
|
|
### Phase 2: Class Name Extraction from C# Files
|
|
|
|
**Goal**: Parse .cs files to extract the class name
|
|
|
|
**Approach**: Simple regex/string parsing (no full C# parser needed)
|
|
|
|
```rust
|
|
impl GuidResolver {
|
|
/// Extract class name from a C# script file
|
|
fn extract_class_name(cs_path: &Path) -> Result<String> {
|
|
let content = std::fs::read_to_string(cs_path)?;
|
|
|
|
// Look for: "public class PlaySFX" or "class PlaySFX"
|
|
// Regex: r"(?:public\s+)?class\s+(\w+)"
|
|
// Return the captured class name
|
|
}
|
|
|
|
/// Resolve GUID to class name
|
|
pub fn resolve_class_name(&self, guid: &str) -> Option<String> {
|
|
let path = self.resolve(guid)?;
|
|
Self::extract_class_name(path).ok()
|
|
}
|
|
}
|
|
```
|
|
|
|
**Files to Modify**:
|
|
- 📄 `src/parser/guid_resolver.rs` - Add class name extraction
|
|
- 📄 `Cargo.toml` - Add `regex` dependency (optional, can use manual parsing)
|
|
|
|
### Phase 3: MonoBehaviour Parser Enhancement
|
|
|
|
**Goal**: Extract m_Script GUID when parsing MonoBehaviour components
|
|
|
|
**Current MonoBehaviour Parsing** (`builder.rs` line 206):
|
|
```rust
|
|
_ => {
|
|
// Check if this is a registered custom component
|
|
for reg in inventory::iter::<crate::types::ComponentRegistration> {
|
|
if reg.class_name == doc.class_name.as_str() { // ⚠️ Won't match "MonoBehaviour"
|
|
// ...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Enhanced MonoBehaviour Parsing**:
|
|
```rust
|
|
"MonoBehaviour" => {
|
|
// Extract m_Script GUID
|
|
if let Some(script_ref) = yaml_helpers::get_external_ref(yaml, "m_Script") {
|
|
let guid = script_ref.guid();
|
|
|
|
// Resolve GUID to class name (requires access to GuidResolver)
|
|
if let Some(class_name) = guid_resolver.resolve_class_name(guid) {
|
|
// Now match against registered components
|
|
for reg in inventory::iter::<crate::types::ComponentRegistration> {
|
|
if reg.class_name == class_name.as_str() {
|
|
if (reg.parse_and_insert)(yaml, &ctx, world, entity) {
|
|
linking_ctx.borrow_mut().entity_map_mut().insert(doc.file_id, entity);
|
|
}
|
|
return Ok(());
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Fall back to generic MonoBehaviour warning
|
|
eprintln!("Warning: Skipping unknown MonoBehaviour");
|
|
}
|
|
```
|
|
|
|
**Files to Modify**:
|
|
- 📄 `src/ecs/builder.rs` - Add MonoBehaviour case, pass GuidResolver
|
|
- 📄 `src/types/references.rs` - Ensure ExternalRef has `guid()` method
|
|
- 📄 `src/types/component.rs` - Add `get_external_ref` to yaml_helpers (if not exists)
|
|
|
|
**Challenge**: How to pass GuidResolver to `build_world_from_documents()`?
|
|
|
|
**Option A**: Add parameter (breaking change)
|
|
```rust
|
|
pub fn build_world_from_documents(
|
|
documents: Vec<RawDocument>,
|
|
guid_resolver: Option<&GuidResolver>, // 👈 New parameter
|
|
) -> Result<(World, HashMap<FileID, Entity>)>
|
|
```
|
|
|
|
**Option B**: Store in ComponentContext (preferred)
|
|
```rust
|
|
pub struct ComponentContext<'a> {
|
|
pub type_id: u32,
|
|
pub file_id: FileID,
|
|
pub class_name: &'a str,
|
|
pub entity: Option<Entity>,
|
|
pub linking_ctx: Option<&'a RefCell<LinkingContext>>,
|
|
pub yaml: &'a Mapping,
|
|
pub guid_resolver: Option<&'a GuidResolver>, // 👈 New field
|
|
}
|
|
```
|
|
|
|
### Phase 4: Integration with UnityFile Parsing
|
|
|
|
**Goal**: Build GuidResolver when loading a Unity project
|
|
|
|
**Current Flow** (`UnityFile::from_path`):
|
|
```rust
|
|
pub fn from_path(path: &Path) -> Result<UnityFile> {
|
|
let content = std::fs::read_to_string(path)?;
|
|
let documents = parse_unity_file(&content)?;
|
|
|
|
match file_type {
|
|
Scene => {
|
|
let (world, entity_map) = build_world_from_documents(documents)?;
|
|
// ...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Enhanced Flow**:
|
|
```rust
|
|
pub fn from_path(path: &Path) -> Result<UnityFile> {
|
|
// 1. Detect if this is part of a Unity project
|
|
let project_root = find_project_root(path)?;
|
|
|
|
// 2. Build GUID resolver for the project
|
|
let guid_resolver = GuidResolver::from_project(&project_root)?;
|
|
|
|
// 3. Parse file with GUID resolution
|
|
let content = std::fs::read_to_string(path)?;
|
|
let documents = parse_unity_file(&content)?;
|
|
|
|
match file_type {
|
|
Scene => {
|
|
let (world, entity_map) = build_world_from_documents(
|
|
documents,
|
|
Some(&guid_resolver) // 👈 Pass resolver
|
|
)?;
|
|
// ...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Files to Modify**:
|
|
- 📄 `src/model.rs` - Update `UnityFile::from_path()`
|
|
- 📄 `src/parser/guid_resolver.rs` - Add `find_project_root()` helper
|
|
|
|
**Optimization**: Cache GuidResolver per project (expensive to rebuild)
|
|
```rust
|
|
// Thread-local cache for performance
|
|
thread_local! {
|
|
static GUID_CACHE: RefCell<HashMap<PathBuf, Arc<GuidResolver>>> = RefCell::new(HashMap::new());
|
|
}
|
|
```
|
|
|
|
### Phase 5: Update Examples and Tests
|
|
|
|
**Examples to Update**:
|
|
- 📄 `examples/find_playsfx.rs` - Should now find PlaySFX components!
|
|
- 📄 `examples/ecs_integration.rs` - Add example with GUID resolution
|
|
|
|
**Tests to Add**:
|
|
- 📄 `tests/guid_resolution_tests.rs` - New test file
|
|
- Test GuidResolver can scan project
|
|
- Test GUID → path resolution
|
|
- Test class name extraction
|
|
- Integration test with VR_Horror project
|
|
|
|
**Integration Test**:
|
|
```rust
|
|
#[test]
|
|
fn test_guid_resolution_vr_horror() {
|
|
let project_path = Path::new("test_data/VR_Horror_YouCantRun");
|
|
|
|
// Build resolver
|
|
let resolver = GuidResolver::from_project(project_path).unwrap();
|
|
|
|
// Known PlaySFX GUID
|
|
let playsfx_guid = "091c537484687e9419460cdcd7038234";
|
|
|
|
// Should resolve to class name
|
|
assert_eq!(
|
|
resolver.resolve_class_name(playsfx_guid),
|
|
Some("PlaySFX".to_string())
|
|
);
|
|
|
|
// Now parse a scene with PlaySFX
|
|
let scene_path = project_path.join("Assets/Scenes/TEST/Final_1F/1F.unity");
|
|
let file = UnityFile::from_path(&scene_path).unwrap();
|
|
|
|
if let UnityFile::Scene(scene) = file {
|
|
// Should find PlaySFX components
|
|
let playsfx_view = scene.world.borrow::<PlaySFX>();
|
|
let mut count = 0;
|
|
for entity in scene.entity_map.values() {
|
|
if playsfx_view.get(*entity).is_some() {
|
|
count += 1;
|
|
}
|
|
}
|
|
assert!(count > 0, "Should find at least one PlaySFX component");
|
|
}
|
|
}
|
|
```
|
|
|
|
## File Checklist
|
|
|
|
### New Files to Create
|
|
- [ ] `src/parser/guid_resolver.rs` - GUID resolution logic
|
|
- [ ] `tests/guid_resolution_tests.rs` - Unit and integration tests
|
|
|
|
### Existing Files to Modify
|
|
- [ ] `src/parser/mod.rs` - Export GuidResolver
|
|
- [ ] `src/lib.rs` - Re-export GuidResolver
|
|
- [ ] `src/ecs/builder.rs` - Add MonoBehaviour GUID resolution
|
|
- [ ] `src/model.rs` - Update UnityFile::from_path()
|
|
- [ ] `src/types/component.rs` - Add guid_resolver to ComponentContext
|
|
- [ ] `src/types/references.rs` - Ensure ExternalRef has guid() method
|
|
- [ ] `Cargo.toml` - Add regex dependency (optional)
|
|
- [ ] `examples/find_playsfx.rs` - Update with notes/verification
|
|
- [ ] `examples/ecs_integration.rs` - Add GUID resolution example
|
|
|
|
## Technical Challenges & Solutions
|
|
|
|
### Challenge 1: Performance - Scanning Large Projects
|
|
|
|
**Problem**: Scanning thousands of .meta files on every parse is slow
|
|
|
|
**Solutions**:
|
|
1. **Lazy Loading**: Only scan when needed (first MonoBehaviour encountered)
|
|
2. **Caching**: Store GuidResolver per project path in thread-local cache
|
|
3. **Incremental**: Only scan Assets/ directory, skip Library/Temp
|
|
4. **Parallel**: Use rayon to scan .meta files in parallel
|
|
|
|
**Recommendation**: Start with simple implementation, optimize if needed
|
|
|
|
### Challenge 2: Class Name Extraction Complexity
|
|
|
|
**Problem**: C# parsing can be complex (namespaces, partial classes, etc.)
|
|
|
|
**Solutions**:
|
|
1. **Simple Regex**: `r"(?:public\s+)?class\s+(\w+)(?:\s*:\s*MonoBehaviour)?"`
|
|
- Good enough for 95% of cases
|
|
- Fast and simple
|
|
2. **Full C# Parser**: Use tree-sitter or similar
|
|
- Overkill for this use case
|
|
- Adds heavy dependency
|
|
|
|
**Recommendation**: Start with regex, handle edge cases as discovered
|
|
|
|
### Challenge 3: Breaking API Changes
|
|
|
|
**Problem**: Adding GuidResolver parameter changes public API
|
|
|
|
**Solutions**:
|
|
1. **Option A**: Make it optional with `Option<&GuidResolver>`
|
|
- Backward compatible
|
|
- GUIDs won't resolve if not provided
|
|
2. **Option B**: Add separate method `from_path_with_resolver()`
|
|
- Keep original API unchanged
|
|
- Explicit opt-in to GUID resolution
|
|
3. **Option C**: Detect and auto-create GuidResolver
|
|
- Best user experience
|
|
- Always attempt GUID resolution
|
|
- Fall back gracefully if project not detected
|
|
|
|
**Recommendation**: Option C - Auto-detect and resolve
|
|
|
|
### Challenge 4: Multiple Scripts Per File
|
|
|
|
**Problem**: C# files can have multiple classes
|
|
|
|
**Example**:
|
|
```csharp
|
|
public class PlaySFX : MonoBehaviour { }
|
|
public class SFXHelper { } // Same file!
|
|
```
|
|
|
|
**Solution**: The .meta file is associated with the **file**, not the class. Unity creates separate .meta files for each public MonoBehaviour. Non-MonoBehaviour helper classes in the same file aren't referenced by GUID.
|
|
|
|
**Recommendation**: Extract first public class that inherits from MonoBehaviour
|
|
|
|
## Success Criteria
|
|
|
|
When this feature is complete:
|
|
|
|
✅ **Functionality**:
|
|
- [ ] GuidResolver can scan a Unity project and build GUID mappings
|
|
- [ ] MonoBehaviour components resolve to their actual class names
|
|
- [ ] Custom components like PlaySFX are discovered and parsed automatically
|
|
- [ ] `examples/find_playsfx.rs` finds PlaySFX components in VR_Horror project
|
|
|
|
✅ **Performance**:
|
|
- [ ] GUID resolution adds < 500ms overhead for typical projects
|
|
- [ ] Caching prevents redundant scanning
|
|
|
|
✅ **Testing**:
|
|
- [ ] Unit tests for GUID resolution
|
|
- [ ] Integration test finds PlaySFX in VR_Horror
|
|
- [ ] Edge cases handled (missing .meta, invalid GUIDs, etc.)
|
|
|
|
✅ **Documentation**:
|
|
- [ ] GUID resolution documented in README
|
|
- [ ] Examples show usage with real Unity projects
|
|
- [ ] API docs explain GuidResolver usage
|
|
|
|
## Timeline Estimate
|
|
|
|
- **Phase 1** (GUID → Path): 2-4 hours
|
|
- **Phase 2** (Class Name Extraction): 1-2 hours
|
|
- **Phase 3** (MonoBehaviour Parser): 2-3 hours
|
|
- **Phase 4** (Integration): 2-3 hours
|
|
- **Phase 5** (Tests & Examples): 2-3 hours
|
|
|
|
**Total**: 9-15 hours of development time
|
|
|
|
## Future Enhancements (Out of Scope)
|
|
|
|
These can be added later if needed:
|
|
|
|
1. **Prefab GUID Resolution**: Resolve nested prefab references
|
|
2. **AssetDatabase**: Full asset path resolution (materials, textures, etc.)
|
|
3. **GUID Cache File**: Persist GUID mappings to disk for instant loading
|
|
4. **Watch Mode**: Auto-update GUID mappings when .meta files change
|
|
5. **Cross-Platform Paths**: Handle Windows/Mac/Linux path differences
|
|
|
|
## Related Documentation
|
|
|
|
- Unity YAML Format: [UnityYAMLParser](https://github.com/HearthSim/UnityYAMLParser)
|
|
- Unity .meta Files: [Unity Manual - Meta Files](https://docs.unity3d.com/Manual/class-Meta.html)
|
|
- GUID Format: RFC 4122 compliant UUIDs without hyphens
|
|
|
|
---
|
|
|
|
**Status**: 📋 Planning Complete - Ready for Implementation
|
|
|
|
**Last Updated**: 2026-01-02
|