Troubleshooting Guide

This guide maps common visual symptoms to their underlying causes and recommended fixes. It is based on the decision logic used by the Preflight AI Agent.

Visual Symptoms

Symptom	Probable Cause	Recommended Action
Pink / Magenta Mesh	Missing UVs or Material Binding	1. Check UVs in Inspector. 2. Use fix:addUVs (Emergency) or unwrap in Blender.
Invisible / Empty Viewport	1. PointInstancer 2. BasisCurves (Hair) 3. Purpose Mismatch	1. Flatten instances in DCC. 2. Convert curves to polygons.
Model Lying Flat	Z-Up Axis (Blender Default)	1. Use fix:setUpAxis:Y. 2. Re-export as Y-Up (Preferred).
Static “T-Pose”	Skeleton Path Mismatch	1. Use fix:remapSkeleton. 2. Check export hierarchy for prefixes like /Armature/.
Collpased Geometry (0,0,0)	Unapplied Transforms or Instancing	1. Apply/Freeze transforms in DCC. 2. Check for PointInstancer.

---

RealityKit “Hard Limits”

RealityKit is a realtime engine with stricter requirements than offline USD renderers.

❌ No PointInstancer

RealityKit does not support the USD PointInstancer schema.

• Why: It cannot efficiently batch-render instanced prototypes without converting them to internal Entity structures.
• Fix: “Realize” or “Make Instances Real” in your DCC to convert them to individual meshes.

❌ No MaterialX (Yet)

While visionOS 2.0 has some MaterialX support, Preflight recommends UsdPreviewSurface for maximum compatibility.

• Why: Complex node graphs often fail silently or fallback to gray.
• Fix: Bake complex shaders into standard PBR textures (Diffuse, Roughness, Normal, Metallic).

❌ No Nurbs or Curves

RealityKit only renders Polygon Meshes.

• Why: It does not tessellate NURBS or curves at runtime.
• Fix: Convert all surfaces to polygons before export.

---

Fix Priority Order

When facing multiple issues, follow this “Critical Path” to avoid wasted effort:

1. 🛑 set Default Prim: If this is missing, the file may not load at all. Fix this first.
2. 📏 Up-Axis: If orientation is wrong, all other visual checks are harder to judge.
3. 🎨 Materials & UVs: Fix visual errors (pink meshes) next.
4. 🦴 Animation: Finally, debug skeletal bindings and timelines.

---

Scaling Best Practices

Do not rely on metersPerUnit metadata to resize your model. RealityKit respects it, but it does not change the underlying geometry.

Correct Approach:

1. Use the Scale Tool (fix:scaleModel) to physically resize geometry to standard dimensions.
   • Palm-sized: ~0.10m
   • Tabletop: ~0.50m
   • Human-scale: ~1.70m
2. Reset metersPerUnit to 1.0 (standard meters).