模型已加载但全部显示为白色

最常见的原因是文件名编码问题 —— 当文件名使用不同的字符编码时，将无法定位贴图。

• 对于 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 可能无法将系统识别为签发许可证时的系统。只需再次运行激活步骤即可 —— 没有额外费用。请参阅 激活与授权 指南。如果您遇到问题，请 联系我们。