Missing Default Prim
Severity: ⚠️ Warning
Fixable: 🔧 Manual
Prevalence: 🔶 Medium
Summary
Section titled “Summary”The USD file has no defaultPrim set. This can cause QuickLook failures and some RealityKit loading methods to fail or behave unexpectedly.
Evidence
Section titled “Evidence”Community Reports
Section titled “Community Reports”TODO: Add specific forum/Stack Overflow links
When It Occurs
Section titled “When It Occurs”- Files exported from some DCC tools without proper USD configuration
- Hand-authored USD files that omit the metadata
- Files that have multiple root prims without a designated default
Root Cause
Section titled “Root Cause”USD allows files to have multiple root-level prims. The defaultPrim metadata tells consumers which prim to use as the entry point. Without it:
- QuickLook may fail to display anything
- Some loaders pick the first prim arbitrarily
- Composition (referencing) becomes ambiguous
Detection
Section titled “Detection”File: PreflightCore/USDClient.swift
Function: performValidation()
let defaultPrim = stage.GetDefaultPrim()if !defaultPrim.IsValid() { results.append(.warning("No Default Prim set..."))}Solution
Section titled “Solution”Manual Fix (DCC Tool)
Section titled “Manual Fix (DCC Tool)”Set the default prim before export:
- Blender: Set in USD export options
- Maya: Configure in USD export dialog
Manual Fix (Text Editor)
Section titled “Manual Fix (Text Editor)”Add to the stage metadata:
#usda 1.0( defaultPrim = "MyRootPrim" upAxis = "Y")Validation
Section titled “Validation”Related Issues
Section titled “Related Issues”- Skeleton Path Mismatch - May mask this issue if skeleton fails first
Changelog
Section titled “Changelog”| Date | Change |
|---|---|
| 2024-12-18 | Stub created |