模型已載入但全部顯示為白色

最常見的原因是檔案名稱編碼問題 —— 當檔案名稱使用不同的字元編碼時，將無法定位貼圖。

• 對於 ZIP 壓縮包，請在壓縮包名稱中新增編碼，以便 DanceXR 能夠正確解析檔案名稱。詳細資訊請參閱此頁面 →
• 檔案名稱中的額外空格也可能導致貼圖無法載入。請在 PMXEditor 中開啟模型，驗證貼圖引用是否與實際檔案名稱完全一致。

頭髮材質透光/透明

半透明深度預處理（Transparency depth prepass）預設處於開啟狀態。它透過僅渲染最頂層的透明層來修正半透明排序問題 —— 這意味著多層疊加的半透明（如分層頭髮）只顯示最外層。

• 關閉半透明深度預處理以渲染所有半透明層。如果模型的材質順序不正確，這可能會引入排序錯誤/偽影。
• 沒有十全十美的通用解決方案 —— 請嘗試不同的配置，選擇視覺問題較少的那一種。

舞台模型的天空球有破洞或看起來有像素顆粒

同樣是由半透明深度預處理引起的 —— 當存在多個半透明天空球時，在某些區域只會完全渲染最頂層。

• 關閉半透明深度預處理，或者
• 找到背景天空球，並將其材質從半透明更改為不透明。

在報告 bug 之前，請嘗試以下快速修復方法：

1. 更新至最新版本 —— 您的問題可能已在新版本中得到解決。
2. 重置設定 —— 備份並刪除 config.json 以排除設定檔損壞的情況。
3. 重置授權/許可證 —— 如果應用程式無法啟動或行為異常，請嘗試從安裝目錄中刪除 license.txt 並重新啟動。
4. 清除媒體庫快取 —— 備份並刪除內容庫資料夾中的 cache.json，以強制播放器重新掃描您的檔案。
5. OpenXR 設定 —— 如果 VR 無法啟動，請仔細檢查您的 VR 軟體設定中是否正確設定了當前活動の OpenXR 執行階段。

在哪裡可以找到記錄檔？

報告 bug 時，附上記錄檔會非常有幫助。請在您的 bug 報告中附帶 Player.log（目前工作階段）和 Player-prev.log（上一次工作階段）。

Windows PC 路徑：

C:\Users\[User]\AppData\LocalLow\VR Storm Lab\DanceXR [HD|LW|RT]\Player.log

注意：請將 [User] 替換為您的 Windows 使用者名稱。如果 AppData 資料夾被隱藏，請在 Windows 檔案總管中啟用「隱藏的項目」。

Android 和 Meta Quest 路徑：

/Android/data/com.vrstormlab.dancexr/files/Player.log

注意：透過 USB 將您的裝置連接到電腦，並使用檔案傳輸模式來定位此檔案。

只顯示天空 —— 沒有 UI 或相機控制介面

這通常意指在啟動過程中出了問題。請按順序嘗試以下步驟：

• 刪除 license.txt 並重新啟動。
• 刪除（請先備份）config.json —— 這將重置所有設定並修復由於設定檔損壞引起的問題。
• 從您的內容媒體庫中刪除（請先備份）cache.json。

每次啟動都崩潰 —— 回退到舊版本也無濟於事

這通常是 VR 執行階段的問題，而不是 DanceXR 本身的問題。

• 如果您安裝了多個 VR 執行階段，請嘗試切換到另一個。
• 對於 SteamVR：停用不需要的啟動重疊層（overlays）和外掛程式；嘗試乾淨的重新安裝。
• 檢查 SteamVR 的 driver 資料夾，看看是否有最近安裝或更新的可以刪除的項目。

無法啟動 VR

DanceXR 使用 OpenXR 來初始化 VR。如果您安裝了多個 VR 執行階段，則需要將其中一個設定為活動的 OpenXR 執行階段：

• Oculus / Meta： 開啟 Oculus 應用程式 → 設定 → 測試版 → OpenXR 執行階段 → 點擊「將 Oculus 設定為活動」。
• SteamVR： 開啟 SteamVR → 左上角功能表 → 設定 → 開發者 → 點擊「將 SteamVR 設定為 OpenXR 執行階段」。
• Windows Mixed Reality： 從 Microsoft Store 下載 「Windows Mixed Reality OpenXR Developer Tools」，並從中將 WMR 設定為活動。

如何在 Android 或 Meta Quest 上設定我的內容媒體庫？

Android 系統具有嚴格的檔案存取規則。預設情況下，內容媒體庫位於應用程式內部儲存中。

• 透過 USB 將您的裝置連接到電腦，選擇「檔案傳輸」模式，然後導航到 /Android/data/com.vrstormlab.dancexr/files/ 或根目錄的 /DanceXR/ 資料夾以複製您的 zip/影像檔案。
• 在 Android 和 Meta Quest（自 2024.3 版本起）上，授予 DanceXR 儲存權限以使用系統「檔案」應用程式或內建的「內容管理器」應用程式來共享和管理您的媒體庫。
• 有關更多詳細資訊，請參閱 Android 和 Quest 內容媒體庫 指南。

提示需要再次啟用

在重大 OS 或硬體變更後，DanceXR 可能無法將系統識別為核發授權時的系統。只需再次執行啟用步驟即可 —— 沒有額外費用。請參閱 啟用與授權 指南。如果您遇到問題，請 聯絡我們。