Preflight Engine Statistics

Preflight is built on a high-performance validation engine that combines OpenUSD C++ Interop with RealityKit-specific heuristics. This page provides the exact technical specification of the engine’s capabilities.

⚡ Closing the “DCC-to-Runtime” Gap

The primary friction in spatial asset development is the Export-Retry Loop: identifying a technical error in RealityKit and being forced to return to the source DCC (Blender, Maya) for a trivial metadata fix.

Preflight’s Surgical Engine is designed to eliminate this loop for the majority of common integration hurdles. We categorize these into Direct Repairs (Fixable in Preflight) and Source Requirements (Requires DCC architectural changes).

The Zero-Loopback Repair Index

Statistically, 7 of the top 10 most common RealityKit load failures are caused by metadata, pathing, or coordinate mismatches. Preflight resolves these Directly in the Session Layer, meaning you never have to leave the verification environment to stand your model up.

Friction Point	Issue Category	Resolution Strategy	Capability
Stage Sanity	Missing Default Prim	Automated Metadata Injection	✅ Direct Repair
Orientation	Up-Axis Mismatch (Z vs Y)	Root Transform Injection	✅ Direct Repair
Animation	Skeleton Path Mismatch	Non-destructive Path Rebasing	✅ Direct Repair
Materials	Missing UV Mapping	Non-destructive Planar Gen	✅ Direct Repair
Scale	MetersPerUnit Mismatch	Metadata Standardizing	✅ Direct Repair
Connectivity	Missing Material Binding	API Schema Correction	✅ Direct Repair
Runtime Sync	Static Keyframe Errors	Timeline Sample Buffering	✅ Direct Repair
Geometry	Unsupported Prim Types	Mesh Topology Reconstruction	❌ Source Req
Scene Logic	PointInstancers	Instance Realization	❌ Source Req
Shaders	Non-Standard Nodes	Shader Graph Translation	❌ Source Req

The Preflight Advantage: By resolving the “Metadata 7” directly in the viewport, technical artists can cut their iteration time by up to 80% per asset.

---

🔍 Diagnostic Heuristics (Total: 28)

The engine runs 28 distinct validation checks across 5 categories.

1. Loadability (7 Checks)

• Stage Integrity: Validates binary consistency/schema.
• PseudoRoot: Ensures the USD logic tree is traversable.
• Default Prim Missing: Essential for QuickLook/RealityKit entry.
• Multiple Root Prims: Flags unpredictable anchoring.
• Unsupported Geometry: NurbsPatch, BasisCurves (Hair), Points (Point Clouds).
• PointInstancer: Flags schemas unsupported by RealityKit runtime.
• USD Lights: Distant, Dome, and Rect lights (which fail in RK).

2. Materials & Textures (6 Checks)

• UV Coordinates: Validates primvars:st presence.
• Surface Normals: Detects missing normals causing flat/black lighting.
• Material Bindings: Ensures meshes aren’t unassigned (Pink Mesh).
• Shader Schema: Flags non-UsdPreviewSurface definitions.
• Shader info:id: Validates unique identifier presence.
• Texture Link Scanning: Traces all file attributes for potential breakage.

3. Scale & Orientation (3 Checks)

• Up-Axis Logic: Z-up vs Y-up metadata detection.
• mpu Range: Detects metersPerUnit outside standard ranges (e.g., < 0.001).
• mpu Existence: Flags missing scale metadata defaults.

4. Animation & Rigging (9 Checks)

• Skeleton Schema: Validates the joints attribute exists.
• SkelAnimation Schema: Ensures clips target a valid skeleton.
• Skeleton Path Mismatch: Detailed remapping check for DCC prefixes (e.g. /Armature/).
• Static Animation: Detects 1-keyframe clips that RealityKit optimizes away.
• Empty Animation: Detects clips with 0 keyframes.
• Joint Influence: Flags performance-heavy skinning (>4 influences/vertex).
• Blend Shape Conflict: Flags simultaneous SkelAnim + BlendShape usage.
• FPS Compliance: Check for non-standard rates (non 24, 30, 60).
• Xform Keyframes: Flags static keyframes on non-skeletal meshes.

5. Dependencies & Packaging (3 Checks)

• Path Resolution: Deep-tracing of all sub-layers and references.
• Format Constraints: FBX/glTF specific plugin limitations.
• Asset Locality: Detection of absolute local paths (e.g., /Users/dev/...).

---

🛠 Surgical Capabilities (Total: 18)

The engine maintains 18 distinct implementation-ready tools for USD modification.

1. remapSkeleton: Automated prefix stripping for animation paths.
2. mergeSkeletons: Hierarchy flattening for fragmented rigs.
3. setUpAxis: Rotates the stage root and updates metadata.
4. setMetersPerUnit: Corrects scaling metadata without geometry risk.
5. makeRCPReady: Injects timeline metadata for Reality Composer Pro.
6. setDefaultPrim: Designates a primary content anchor.
7. addUVs: Non-destructive Planar UV generation.
8. assignMaterial: Binds a fallback material to unassigned meshes.
9. cleanupMissingReference: Safely removes broken USD links.
10. applyMissingSchema: Repairs missing API schemas on prims.
11. setDoubleSided: Toggles backface culling metadata.
12. setSubdivisionScheme: Configures tessellation behavior.
13. flattenNestedShader: Optimizes material hierarchies.
14. setTexture: Swaps assets for optimized .ktx2 alternatives.
15. fixShaderPropertyType: Casts input values to standard types.
16. scaleModel: Physical geometry resizing (Physical scale).
17. export_session (alias: export): Finalizes all session layers into a single output USD/USDZ file.
18. undoLastFix: Transactional rollback of the last surgical step.