支持

在Windows上，打开系统菜单（齿轮图标），选择内容库 → 在资源管理器中显示，即可打开内容库文件夹。

Android和Meta Quest的共享内容库通常位于 /DanceXR/。旧版本或使用应用内部存储时，路径为 /Android/data/com.vrstormlab.dancexr/files/。在iPhone或iPad上，打开“文件”应用，在我的iPhone或我的iPad下找到DanceXR文件夹。

将模型及其纹理复制到内容库的 actors/ 中，保留原有的文件夹结构。也可以将每个模型及其资源打包成单独的ZIP文件。

打开角色菜单，选择加载模型，再选择所需模型。在桌面版中，也可以将模型文件或模型ZIP直接拖到DanceXR窗口中。

支持PMX和XPS。FBX模型加载目前是预览功能，不会加载FBX内嵌的动画。

将VMD或BVH动作文件及音频放入内容库的 motion/ 中。舞蹈套装可以使用WAV或OGG音频。

打开音频／动作菜单，选择加载音频／动作。桌面版也支持将文件直接拖到DanceXR窗口中。

要让音乐和动作一起加载，将一首歌及其相关动作放在同一个子文件夹或ZIP中。如果只有一组动作和音频，也可以使用相同的文件名，例如 dance.vmd 和 dance.ogg。

打开系统 → 内容库 → 刷新内容，等待扫描完成。在DanceXR运行时复制或移动文件后，可以使用此功能。

应用启动时也会检查内容库的变化。如果文件仍未出现，请确认放入了正确的子文件夹：模型放在 actors/，动作和音频放在 motion/，舞台放在 stages/，天空贴图放在 texture/sky/。

Native是拥有独立渲染和设置的Windows应用。HD、LW和RT是Unity版本。从2026.10起，Native可在支持DirectX 12但不支持光线追踪的电脑上使用光栅渲染；路径追踪需要兼容的光追GPU。

Launcher负责安装、更新和启动运行程序与配套应用，也可以直接下载Native。请在下载页面核对当前版本、激活方式和功能限制。

Unity应用支持PMX/XPS模型、仅模型导入的FBX预览支持、VMD/BVH动作和OBJ场景道具。XPS/FBX模型可能需要骨骼映射。Native当前文档列出PMX/XPS模型和VMD动作。

VRM、VRChat或DAZ工程不一定是可直接使用的模型包。导出或转换属于独立流程，请确认目标格式和骨骼。DanceXR播放导入的动作并提供程序化摆姿，不能替代完整的动画制作工具。

在桌面Unity版本中，将完整内容库复制到新位置并保留备份。打开 System → Content Library → Switch Library，选择包含各内容子文件夹的根文件夹。需要浏览时使用 Select Library Folder。

切换只改变DanceXR使用的位置，不会自动移动文件。等待扫描并检查已保存的场景。测试旧构建时，请使用独立设置。移动端和独立头显不提供此桌面文件夹选择器。

先启动一次DanceXR。在文件 → 我的iPhone / 我的iPad → DanceXR中，打开应用创建的内容库（通常是 content 文件夹）。模型和贴图放入 actors，动作和音频放入 motion。保留原始贴图目录结构，也可使用完整模型ZIP。

将云端下载复制到本地内容库；单独链接不等于导入模型。使用 System → Content Library → Refresh Content 或重启应用。旧版本请以应用创建的目录结构为准。

打开角色 → 加载模型，点击要添加的模型旁边的 + 图标。直接选择模型通常会替换当前选中的角色；使用+可以保留当前角色并添加另一个。

多角色场景需要已激活的付费版本。如果无法使用+，请检查版本和激活状态。

拖动角色脚下的黄色选择圆盘即可移动角色。拖动时使用鼠标滚轮可以旋转；在VR中，将控制器摇杆向左或向右拨动。

要精确调整，打开角色的缩放与偏移设置。使用模型缩放调整大小、旋转调整朝向、偏移X/Z调整水平位置、地面偏移调整高度。如果希望保留模型的原始大小，请关闭统一身高。

将替代纹理放在模型文件夹内单独的子文件夹中，或同一个模型ZIP内的任意位置。每张替代纹理必须与被替换的纹理使用相同的文件名。

例如，模型使用 base.png，可以在 alternate/ 子文件夹中放入另一张 base.png。重新加载模型，在角色菜单的替代纹理中选择DanceXR检测到的纹理组。请将替代文件保留在模型包内，以便扫描时找到它们。

将道具模型和纹理放入内容库的 accessory/，必要时刷新内容库。

选中角色，打开配件。启用左手或右手，然后在模型中选择道具。调整大小与对齐、旋转和偏移，使其贴合手部。如果提供抓握姿势选项，还可以调整握持方式。

需要使用支持配件功能的版本。

播放音频时，启用Playback Options中的 Lip Sync 和角色Facial Control中的 Use Lip Sync。确认音频正在播放，并手动测试各母音控制。若手动也无效，请检查面部映射和模型已有的骨骼或变形。

手动调整嘴型时关闭 Use Lip Sync。加载的动作和Lifelike Motions也可能修改表情。AI聊天语音使用单独的口型驱动。

在角色的 Dressing 中控制PMX材质变形或XPS可选部件。必要时在 Material List 中检查单独材质，不要直接隐藏整个材质组。

如果模型本身没有衣服下面的身体几何体，隐藏衣服不会生成身体。有些服装与身体共享材质。可用的换装选项取决于模型作者的制作方式。

Eye Contact会在摄像机、其他角色和身体部位之间转移注意。调整 Look At Camera、Look At Peers 和 Look At Body 的优先级。Stare Mode 会持续关注最近的有效目标，替代自然的视线切换。

模型需要兼容的眼部骨骼。没有眼球骨骼时，可配置 Shape Morph Eye Control。Stare Mode不保证总是选择观看者。

打开所选材质的 Textures 设置，检查检测到的贴图。识别错误时，修正贴图用途和通道映射。模型原始法线贴图与平铺细节贴图不同。

自动关联取决于模型格式和导入器，改文件名不是通用修复。检查完整模型包和原始引用路径。仍然无效时，请提供模型格式、贴图文件名、构建版本和截图。

在Unity版本中调整 Application Settings → Use Translated Names。需要与模型说明或编辑器中的原始名称对应时，将它关闭。已有标签未更新时，重新加载模型。

作者自定义的名称可能没有完整翻译。此设置只改变显示名称，不修改模型原文件或骨骼。

在Unity版本中，对模型自带的PMX变形启用 Override Value，再调整数值。覆盖关闭时，仍由正常动作驱动的值控制。需要已解锁该功能的版本。

面部表情还应检查口型同步、加载的动作和Lifelike Motions，它们可能驱动同一个表情。其他模型格式和Native不一定使用相同控制。

先确认角色的物理方式。PMX自带刚体和关节可比较 Physics Mode 选项；Auto 使用系统 PMX Default。XPS/FBX自定义工具中，启用 Hair Physics 或 Skirt Physics，用 Select Bones 选择骨骼链根部，并检查身体碰撞体。

一次只调一个设置：PhysX用弹簧和阻尼，XPBD用柔顺度和阻尼。用自定义工具替换PMX物理时，先将PMX Physics Mode 设为 Off。功能可用性随构建和版本而异，Native有独立物理设置。

在音频／动作菜单中加载动作，然后选中要播放动作的角色。

选择动作并使用分配给选中角色。也可以打开角色菜单，从动作列表中选择已加载的动作。要让所有角色执行同一个动作，请使用分配给所有角色。

如果XPS或FBX角色仍停留在标准姿势，请检查其骨骼映射器中的分配。

加载群舞套装，使所有动作轨道都可用。在动作菜单中使用分配所有角色，将不同轨道分配给场景中已有的角色。

如果希望DanceXR自动加载角色并为每个角色分配轨道，使用加载并分配角色。要手动控制，逐个选中角色，对所需轨道使用分配给选中角色。

多角色场景需要已激活的付费版本。

在 motion/ 下创建子文件夹或ZIP，将歌曲、角色动作文件和镜头动作放入其中。每个包中只保留一个音频文件。DanceXR会把相关文件识别为舞蹈套装，方便一起加载。

对于一组动作和音频，相同的文件名（例如 dance.vmd 和 dance.ogg）也可以。如果同一文件夹内包含无关文件，请将它们分成独立的包，明确分组关系。

加载模型，在角色菜单中打开骨骼映射器。运行自动映射，检查带感叹号的槽位：这些是尚未分配、但正常动作所必需的骨骼。

将每个缺失槽位映射到模型中对应的骨骼。链式映射可以加快手臂、手指等骨骼链的设置。完成必要映射后，分配动作并检查结果。

XPS和FBX需要骨骼映射。PMX模型通常已包含标准骨骼名称。

先用默认设置比较同一个模型和动作，再一次调整一个控制项。检查 Feet On Floor、Ground Offset 和 Reduce Sliding。错误的骨骼映射或标准姿势也会影响结果。

Unity版本中，请检查 Motion Leg IK 与 Model IK 是否产生冲突。不要把关闭全部IK当作通用修复。如果新版本破坏了原本正常的模型，请报告模型、动作、当前版本和最后正常的构建版本。

检查整体播放速度和动作自身的速度设置。非标准源帧率可能需要单独调节动作速度，不要把所有动作都设为两倍速。录制FPS是另一项设置。

音乐对齐时检查音轨的音频偏移；程序化舞蹈则检查 Music Timing 中的BPM和节拍偏移。一次改一个设置，并与预期播放效果比较。

从程序化动作列表选择 Free Pose，将当前动作替换为手动摆姿。拖动身体控制柄；鼠标用户可滚轮调整深度，VR用户可用射线拖动或直接握住控制柄。

先让双脚着地。拖动脚后保持不动，标记变绿即可固定；红色时松开会回落。Reset 解除固定并恢复自然站姿。不要把临时固定理解为已保存的可复用姿势。

将全景天空图片放入内容库的 texture/sky/。环境贴图推荐使用HDR格式。如果在DanceXR运行时添加了文件，请使用系统 → 内容库 → 刷新内容。

打开环境 → 天空，将模式设为天空贴图，再在天空贴图中选择图片。要旋转背景，请调整方向。

打开环境 → 天空，确认模式为天空贴图。调整方向，即可让全景背景绕场景旋转。

这也会旋转地面天空穹顶材质所使用的天空投影，因此修改后请检查地面和反射效果。

打开环境 → 天空。

在HD/RT版本中，背景控制可见天空的亮度，天空环境光控制天空对场景照明的影响。如果明亮背景使角色的明暗层次变淡，请降低天空环境光。

轻量版使用天空曝光度和强度。天空曝光度也会影响反射亮度，调整时请同时检查反光材质。

将舞台模型和所需纹理放入内容库的 stages/，保留原有文件夹结构，或将整套资源打包成ZIP。标记为 stage 的角色模型也可以显示在舞台菜单中。

必要时刷新内容库，然后打开场景 → 加载舞台并选择模型。加载新舞台会替换旧舞台。使用已加载舞台的设置调整外观和位置。

舞台和道具模型不能播放动作。要让它们播放动作，请将文件放入 actors/，作为角色加载，再分配动作。天空贴图是另一类资源，应放在 texture/sky/。

点击空白处，在界面、控制和沉浸模式之间切换。沉浸模式会隐藏菜单和黄色的角色选择圆盘，让画面保持整洁。

也可以使用已绑定的切换界面操作，桌面版默认按键为 Esc。再次点击空白处或使用切换界面，即可恢复显示。

将镜头VMD与歌曲、角色动作放在同一个舞蹈套装文件夹或ZIP中，然后加载该套装。

打开相机，选择已加载套装中的镜头动作。Freefly、Auto等内置相机模式是其他选项；要跟随舞蹈作者设计的镜头运动，请选择导入的轨道。

轨道缺失时，请检查加载的包中是否有该文件。Unity VR版本结合头部追踪与摄像机整体移动，具体行为取决于所选相机模式。Freeze in VR 会在UI可见时暂停移动。Native有独立相机控制。

使用 Creator Edition 进行离线渲染。打开录制菜单（红色圆圈），进入录制设置，选择 UHD 3840x2160、所需帧率和图片格式。

先预览场景，检查构图和动作，再开始 2D 录制。即使实时播放达不到所选帧率，DanceXR仍会按目标输出帧率渲染每一帧。

输出为图片序列，需要在渲染完成后转换为视频。具体步骤请参阅图片序列转视频的回答。

打开渲染帧所在的文件夹。如果已安装FFmpeg，并且可以通过系统PATH运行它，可以使用录制附带的转换批处理文件。也可以使用支持导入图片序列的视频编辑软件。

手动转换示例：假设以60 fps录制，文件名为 movie_0000.jpg、movie_0001.jpg 等。

ffmpeg -framerate 60 -i movie_%04d.jpg -i sound.wav movie.mp4

请将帧率、编号格式和扩展名改为实际输出所使用的值。不需要音频时，省略 -i sound.wav。

使用屏幕录制软件，实时录下DanceXR的播放画面即可，不需要Creator Edition。

1. 打开系统 → 显示与界面 → 分辨率，关闭全屏，使用窗口模式。
2. 选择窗口分辨率。竖屏时开启垂直，横屏时关闭。
3. 点击应用分辨率，调整构图；如需干净画面，可以隐藏界面。
4. 在录屏软件中选择DanceXR窗口及其音频，开始录制后播放动作。

录制流畅度取决于实际播放帧率。如果播放卡顿，请降低画质设置或分辨率。

使用已激活的 Creator Edition。在录制菜单中选择 Record 3D → Side by Side / Top Bottom，或 Record VR → VR 120 3D / VR 180 3D / VR 360 2D。VR360是单目。先检查 Preview 和Recording Settings。

录制会生成图像序列。用视频编辑器或生成的批处理转换；批处理需要FFmpeg。全景批处理使用NVIDIA编码器，其他GPU需改用可用编码器。在VR播放器中选择匹配的投影和立体模式。

设置好角色、舞台、动作、环境和相机后，打开场景，使用已保存场景浏览器中的保存图标。输入名称并选择保存。

要恢复配置，返回场景浏览器，选择保存的名称。场景保存的是设置及对资源的引用，请将原始模型和动作保留在内容库中。如果还需要传输资源文件，请使用场景包。

使用场景包，将场景与模型、舞台、道具、配件和舞蹈套装一起打包。

加载并检查场景，打开场景 → 场景包，使用保存操作输入名称。等待正在创建场景包…结束后，将压缩包复制到目标设备内容库的 bundles/ 中并打开。

在目标设备上检查播放和材质。可用功能仍取决于目标设备的构建版本和版本等级。场景包菜单需要已激活的付费版本。

配置好角色，打开其预设菜单。选择保存角色预设，将设置与该模型关联；选择保存为全局预设，则可供其他角色使用。输入名称并保存。

使用时，选中角色，在预设菜单中选择已保存的条目。预设仅保存设置，不包含模型文件。应用到其他模型时，请检查骨骼映射、材质槽位和物理设置，因为它们可能不同。

调整灯光、天空、地面等应用设置，然后打开环境 → 系统预设。使用保存操作，输入名称并选择保存。

以后从同一菜单中选择已保存的预设即可应用。设置存储在内容库的 presets/system/ 中。如果还要恢复角色、已加载资源及动作分配，请保存场景。

在PC上，连接头显并启动VR软件。确认正在使用的运行时（如SteamVR或Meta）已被设置为当前 OpenXR 运行时。

启动支持VR的DanceXR构建版本，打开环境并开启 VR。使用独立Quest时，从头显中启动已安装的Quest版本。

如果VR未启动，请检查当前运行时，并参阅VR启动故障排查的回答。

授予DanceXR使用共享 /DanceXR/ 文件夹所需的存储权限。模型放入 actors/，动作和音频放入 motion/，其他资源放入对应的内容库子文件夹。

可以使用设备上的“文件”应用，或通过USB连接PC并选择文件传输。Android的内容管理器应用也能将支持的ZIP和图片文件添加到内容库。

旧版本或内部存储模式使用 /Android/data/com.vrstormlab.dancexr/files/。复制后重新启动DanceXR，或执行刷新内容。

在支持的Android或iOS设备上启动DanceXR，打开环境，选择 AR。如果设备请求相机权限，请允许访问，然后等待AR初始化。

在AR设置中使用显示相机来显示真实环境背景。若希望角色看起来直接站在实际地板上，启用隐藏地面。使用停止AR返回普通模式。

AR需要已激活的Pro版本及兼容的设备／构建版本。如果没有AR选项，请同时检查设备支持情况和激活状态。Quest透视功能另有说明。

Unity版本中，Freeze in VR 会在菜单可见时暂停摄像机移动。隐藏菜单再试，或在Camera Settings中调整 Freeze in VR，允许操作菜单时移动。

头部追踪与摄像机整体移动不同。如果隐藏菜单后控制器仍无法移动，请提供构建版本、头显、控制器和OpenXR运行时。Native使用独立的控制系统。

在Unity版本中检查 Controller Input → Options。关闭 Trackpad Mode，尝试不按下触摸板或摇杆的轴输入。握持误触时，可提高 Grip Threshold 或关闭 Use Grip Input；后者也会禁用基于握持的交互。

一次只改一个选项。这些是可尝试的设置，不保证适用于所有头显。Native的控制设置独立。

在Unity VR版本中指向菜单面板，按住控制器 grip button 并移动手来重新定位，松开后留在该位置。

在 Environment → VR → UI 调整 UI Distance 和 UI Auto Return。Auto Return让移出视野的面板返回。菜单隐藏时，用已绑定的Toggle UI重新显示。Native使用独立界面。

模型全白通常表示无法找到纹理文件。请保持纹理相对于模型文件的原始位置。

如果ZIP内包含日文或中文文件名，可以添加对应编码后缀：日文使用 model.jis932.zip，中文使用 model.gb2312.zip。重命名压缩包后重新加载模型。Android的内容管理器也可以设置此编码。

如果仍然全白，请检查模型的纹理引用，确认文件名、文件夹路径和空格与实际文件完全一致。

在HD/RT版本中，透明深度预处理可能使多层透明头发的内层消失。

尝试关闭系统 → 图形 → 选项 → 透明预处理并比较结果。若希望只修改局部，可以仅调整受影响的头发材质的透明预处理。

关闭后可能出现其他透明排序问题。请从多个角度检查，选择最适合该模型的设置。

丝袜、睫毛或衣服不透明或消失时，还需检查材质 Auto / Opaque / Transparent 分类、可见性及分组/全局覆盖。缺失贴图与透明层问题不同。上述预处理建议适用于HD/RT，Native和其他渲染管线使用不同控制。

确认VR软件正在运行，头显所用的运行时已设为当前 OpenXR 运行时。如果安装了多个运行时，请在所选运行时的设置中将其启用，再重新启动该运行时和DanceXR。

再次尝试开启环境 → VR。如果仍然失败，请禁用不必要的VR覆盖层或插件，并查看DanceXR的 Player.log 中的错误。报告问题时，请附上日志、应用构建版本、头显和运行时信息。

Steam和Google Play版本通常会在商店验证购买后自动激活。

需要手动激活的版本，请打开系统 → 激活您的副本。按照浏览器提示，选择购买平台并登录。成功页面出现后，返回DanceXR，再次点击激活您的副本以获取许可证。

如果该设备之前已激活，DanceXR可能无需打开浏览器即可恢复许可证。重新安装、更换硬件或切换构建版本后再次激活，不会额外收费。

PC、Android和iOS不一定同时更新。Steam默认分支和测试分支可能使用不同构建；Patreon提前发布不代表所有商店版本都已获得相同功能。

请检查当前更新说明、下载页面的版本信息和激活状态。询问缺失功能时，请提供平台、购买版本、运行程序、准确版本号以及Steam分支（如适用）。移动端有独立发布安排，PC发布日期不是移动端的交付承诺。

用默认场景和单个角色与问题场景比较。降低渲染比例，并逐项测试镜面、阴影和高开销效果。Unity HD/RT有画质预设；Native提供 Detect best settings、光栅画质档位及独立的桌面/VR图形设置。

路径追踪噪点与卡顿不同：Native的Realtime使用降噪和超采样，Reference为静态画面积累采样。问题持续时，请提供设备/GPU、构建版本、场景、FPS和日志。不要假设一个设置能修复所有平台。

同样是由半透明深度预处理引起的 —— 当存在多个半透明天空球时，在某些区域只会完全渲染最顶层。

• 关闭半透明深度预处理，或者
• 找到背景天空球，并将其材质从半透明更改为不透明。

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 将您的设备连接到电脑，并使用文件传输模式来定位此文件。

Native 请使用 System → Open Log、Copy Diagnostics 或 Report Issue，不要套用Unity日志路径。报告中包含准确构建版本、平台、渲染器/VR运行时、复现步骤、预期结果和截图。仅分享有权提供的模型或动作。移动端存储访问随系统版本变化，USB不一定显示所有应用文件夹。

这通常意味着在启动过程中出了问题。请按顺序尝试以下步骤：

• 删除 license.txt 并重新启动。
• 删除（请先备份）config.json —— 这将重置所有设置并修复由于配置文件损坏引起的问题。
• 从您的内容媒体库中删除（请先备份）cache.json。

这通常是 VR 运行时的问题，而不是 DanceXR 本身的问题。

• 如果您安装了多个 VR 运行时，请尝试切换到另一个。
• 对于 SteamVR：禁用不需要的启动叠加层（overlays）和插件；尝试干净的重新安装。
• 检查 SteamVR 的 driver 文件夹，看看是否有最近安装或更新的可以删除的项目。

这是由动作平滑系统中的 bug 引起的。临时解决方法：在动作设置中禁用动作平滑。

这是由于模型定义的 IK 在动作没有 IK 移动时处于激活状态。解决方法：在演员动作设置中禁用“模型 IK”。 注意：在 2026.7 版本发布后，这不再需要。