The latest articles on DEV Community by Tatsuya Ogawa (@_4a49fbaa067787556beb). https://dev.to/_4a49fbaa067787556beb https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3587889%2Ffb85af02-119e-42a8-8b08-0a205fc4e9c3.png https://dev.to/_4a49fbaa067787556beb en Tatsuya Ogawa Wed, 29 Oct 2025 17:27:25 +0000 https://dev.to/_4a49fbaa067787556beb/investigating-missing-skeletons-in-realitykit-after-converting-unirig-glb-files-2kfj https://dev.to/_4a49fbaa067787556beb/investigating-missing-skeletons-in-realitykit-after-converting-unirig-glb-files-2kfj <p>UniRig does a great job auto-generating skeletons for GLB models, which makes preparing assets for RealityKit much easier. The surprise came when I pulled that GLB into Reality Composer Pro, exported it as USDZ, and loaded it in a RealityKit app: calling <code>ModelEntity</code> for the skeleton just returned <code>nil</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight swift"><code><span class="k">let</span> <span class="nv">skeletonIterator</span> <span class="o">=</span> <span class="n">entity</span><span class="o">.</span><span class="n">components</span><span class="p">[</span><span class="kt">ModelComponent</span><span class="o">.</span><span class="k">self</span><span class="p">]</span><span class="o">!.</span><span class="n">mesh</span><span class="o">.</span><span class="n">contents</span><span class="o">.</span><span class="n">skeletons</span><span class="o">.</span><span class="nf">makeIterator</span><span class="p">()</span> </code></pre> </div> <p>The same code works flawlessly with Apple's sample <code>robot.usdz</code>, so the issue clearly lives in the asset converted from UniRig. Here is what I discovered and how I worked around it.</p> <h2> What I Observed </h2> <ul> <li>Convert the UniRig GLB to USDZ via Reality Composer Pro.</li> <li>Load the USDZ in RealityKit and the <code>ModelEntity</code> reports a <code>nil</code> skeleton.</li> <li>Swap in Apple's <code>robot.usdz</code> and everything behaves, confirming the runtime side is fine.</li> </ul> <h2> Digging Into The Asset </h2> <ol> <li>Converted the problematic USDZ from binary (<code>usdc</code>) to text (<code>usda</code>) with <code>usdcat</code> so I could diff it.</li> <li>Replaced its skeleton with the one from <code>robot.usdz</code>; the scene loaded, which pointed to naming or structure in the skeleton data.</li> <li>Checked the <code>uniform token[] joints = []</code> definition and noticed some joint names in the UniRig output contained slashes (<code>XXXX/YYYY</code>). RealityKit appears to reject skeletons whose joint names include <code>/</code>.</li> </ol> <h2> Fixing The Skeleton Names </h2> <ol> <li>Unpack the USDZ you exported from Reality Composer Pro.</li> <li>Run <code>usdcat</code> to convert the <code>usdc</code> file to <code>usda</code>.</li> <li>In the <code>uniform token[] joints = []</code> array, batch-replace joint names that contain <code>/</code> with names that don't, e.g. turn <code>XXXX/YYYY</code> into <code>XXXXYYYY</code>.</li> <li>Repack the edited <code>usda</code> back into USDZ.</li> </ol> <p>After stripping the slashes from those joint names and repacking, RealityKit once again exposes the skeleton without any code changes.</p> <h2> Takeaways </h2> <p>RealityKit seems intolerant of joint names that include <code>/</code>. When you pipeline UniRig GLBs through Reality Composer Pro, double-check the skeleton joint names and sanitize them before publishing the USDZ if needed. That one tweak keeps RealityKit happy.*** End Patch</p> realitykit unirig