常见问题¶

安装部署¶

运行 add_hmd.bat 脚本出现异常¶

异常日志及问题原因：adb 进程冲突导致脚本无法正常运行。

解决方案：

打开任务管理器（Ctrl + Shift + Esc）。
切换到"进程"选项卡。
搜索 adb.exe 进程。
找到 adb.exe (32 位) 进程，右键选择"结束任务"。
重新运行 add_hmd.bat 脚本。

PCControl 图标不见了，被 Windows 病毒保护删除了¶

问题原因：程序被 Windows 的病毒保护误删。

解决方法：

打开 Windows 安全中心：点击任务栏上的 Windows 安全中心图标（盾牌形状）。
查看保护历史记录：在 Windows 安全中心窗口中，点击左侧菜单中的"保护历史记录"。
找到被隔离的文件：在保护历史记录中，找到被误删的程序（通常显示为"已隔离威胁"）。
恢复被隔离的文件：在威胁详细信息中，点击"操作 → 还原"，将被误删的程序恢复到原来的位置。
添加到白名单（可选）：如果问题仍然存在，可以将该程序添加到 Windows Defender 的白名单中：
- 打开 Windows 安全中心 → 病毒和威胁防护 → 管理设置。
- 拉到最底部，找到"排除项"，点击"添加或删除排除项"。
- 添加 pccontrol.exe 到排除项。

创建房间时遇到"内部错误"¶

错误原因：浏览器缓存了历史版本的页面数据，导致页面加载异常。

解决方案：

清除浏览器缓存：按下 Ctrl + F5 强制刷新页面清除缓存。
通过调试模式禁用缓存：
- 按下 F12 键，进入浏览器的开发者工具。
- 切换到"网络"选项卡。
- 勾选"禁用缓存"选项。
- 按下 F5 键刷新页面。
- 尝试再次创建房间。

安装失败，提示"找不到路径 'D:/XKData'"¶

错误原因：默认数据会保存在 D:/XKData 目录，如果 PC 中不存在 D 盘，就会导致该错误。

解决方案：修改 install.config 文件中的 XK_DATA_DIR，将其修改为一个有效的路径。如：XK_DATA_DIR=D:/XKData

启动中控，显示无法访问此页面¶

错误原因：切换了网络，导致 IP 变了。

解决方法：退出中控，然后重新点击桌面的"中控图标"重启启动中控。如果 IP 变了，头显需要重新注册。

安装成功，但是无法打开中控页面¶

错误原因：中控后台页面不支持 IE 浏览器。

解决方法：请更换浏览器为 Chrome、Edge 或 Firefox。

安装时提示"启动后端失败"¶

错误原因：可能没有安装 VC++ 运行环境。

解决方法：通过以下链接下载 VC_redist.x64.exe 安装后重新尝试安装： https://aka.ms/vs/17/release/vc_redist.x64.exe

安装时提示"激活失败，请求云端激活失败，请确认联网正常"¶

如果 PC 联网正常却仍然出现该错误，可能的原因如下：

DNS 解析问题：DNS 服务无法解析激活服务器的域名。
- 先尝试 ping prod.ximmerse.com，如果 ping 不通可修改 DNS 服务为 8.8.8.8，修改完毕后再次尝试激活。
代理软件冲突：PC 有开着代理软件或者 VPN。
- 关闭代理软件再尝试激活。

iPad 端应用安装限制¶

问题描述：无官方应用商店版本，需由燧光团队手动安装。

解决方案：需通过燧光团队提供的专用安装包进行手动安装。设备需联系燧光商务人员，将 iPad 设备发给燧光安装。

启动编辑器，卡在"正在检查系统资源更新"¶

解决方案：需要先启动 PCControl，确保 PCControl 已经启动，再启动编辑器。

安装部署在 C 盘空间不够问题¶

醒空安装包不要解压在桌面，要放在非 C 盘，然后再执行 Install.exe，安装时注意磁盘空间是否够。
默认数据是安装在 D 盘的。

若 C 盘空间不足，可通过以下方式调整数据存储路径：

修改数据存储路径：
- 找到醒空目录下的 install.config 文件，将其中的 XK_DATA_DIR 参数值修改为其他有效路径（如 XK_DATA_DIR=D:/XKData），避免占用 C 盘空间。
- 若未配置 XK_DATA_DIR，默认数据路径为 C:\Users\Public\Documents\XKData，需手动修改该路径至其他分区。
升级时的路径管理：
- 若数据保存在醒空子目录（如 C 盘下的默认路径），需将数据目录备份到其他分区（如 D:/XKData_backup），并在新版本安装时修改 XK_DATA_DIR 指向备份路径。

授权码过期重新激活¶

如果授权码过期，需要重新申请一个激活码。然后将获取的激活码填写到激活页面：

启动系统。
将激活码填写到激活页面（URL：http://服务器IP:Http端口号/activate，如 http://127.0.0.1:18080/activate）。

安装 MR 头显训练端运行脚本 add_hmd 出现异常 "file contains a virus"¶

错误信息：Error, couldn't launch child ([Error 225] Operation did not complete successfully because the file contains a virus or potentially unwanted software.)

解决步骤：

方法 1：关闭实时防护（Windows Defender）
- 打开 Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 关闭"实时保护"。
方法 2：添加文件/文件夹到排除列表
- 在"病毒和威胁防护" → "管理设置" → "添加或删除排除项" → 将报错的文件或所在文件夹添加为排除项。

升级¶

升级醒空系统：数据备份与路径管理指南¶

在升级醒空系统时，确保数据的安全性是至关重要的。

1. 确认数据保存的路径¶

1.1 检查 .env 文件

打开醒空目录下的路径：XRGC_PC_Control/addons/services/.env
查找是否存在 XK_DATA_DIR

1.2 默认路径

如果 XK_DATA_DIR 不存在，或者该行以 # 开头（被注释），则数据保存的默认路径为：XRGC_PC_Control/data
该目录通常包含以下两个子目录：
- mysql：存储数据库文件。
- filestore：存储文件存储相关数据。

2. 备份目录¶

2.1 判断是否需要备份

如果数据保存路径不在醒空的子目录下，则无需备份，可直接进行升级。
如果数据保存路径位于醒空的子目录下（如 XRGC_PC_Control/data/），则需要将该目录复制到其他安全路径进行备份。

2.2 备份操作

建议将备份路径选择为醒空目录之外的安全位置，例如 d:/xk_data。

3. 删除旧版本醒空¶

在完成数据备份后，请删除旧版本的醒空目录，以避免冲突或残留文件影响新版本的安装。

4. 修改新版本醒空保存数据的路径¶

4.1 检查 .env 文件

打开新版本醒空目录下的路径：XRGC_PC_Control/addons/services/.env
查找是否存在 XK_DATA_DIR
- 如果存在，将其值修改为备份路径。示例：XK_DATA_DIR=d:/xk_data
- ⚠️ 注意：确保该行未被注释（即不以 # 开头）。

4.2 添加 XK_DATA_DIR

如果 .env 文件中不存在 XK_DATA_DIR，请手动添加：XK_DATA_DIR=d:/xk_data

5. 安装新版本醒空¶

完成上述步骤后，您可以按照官方文档或安装指南安装新版本醒空。安装完成后，醒空将自动使用指定的备份路径作为数据目录。

编课资源问题¶

模型面数优化问题¶

问题描述：模型面数过高，导致 PC 显示异常或移动端场景性能不足。

不同平台的总面数限制如下：

平台	总面数限制
Windows	不超过 500 万面
MR 设备	不超过 70 万面
iOS 设备	不超过 70 万面

解决方案：

减面工具：
- 使用专业减面工具，或在 3DMAX 中通过"Decimate Modifier"或"Quad Draw"工具手动优化拓扑结构。
- 使用模型转换工具的减面功能进行减面。
优化原则：
- 删除不可见面（如内部/遮挡面）。
- 合并顶点、简化高曲率区域。
- 优先保证关键区域细节，低重要性区域大幅减面。

模型无法拆解的问题¶

问题描述：模型无法拆解，只能抓取。

解决方案：模型拆解需要满足两个条件： 1. 模型本身需要拆分成多个部件（可在模型转换工具的编辑模式下确认）。 2. 模型各个部件需要有碰撞体（在模型转换工具里面导入模型时需要允许生成碰撞体）。

3D 墙体厚度调整问题¶

问题描述：3D 墙体组件无法调整 X 轴缩放，厚度参数未开放。

解决方案：直接导入自定义平面模型。

OBJ 模型导入失败问题¶

问题描述：带纹理的 OBJ 格式模型无法直接导入编辑器。

解决方案：使用模型转换工具将 OBJ 转为单文件 .xobj 格式后导入。

模型显示异常问题（贴图缺失/法线错误）¶

问题描述：模型面数过高或贴图/法线贴图未正确打包，导致 PC 显示异常或空白。

解决方案：

检查贴图格式：确保使用 PNG/JPG 等通用格式，避免 EXR/PSD 等特殊格式。
重新打包材质：在 Unity 中使用"Lit 材质"重新打包，确保 UV 映射正确。
法线修正：若模型全黑，需检查法线向量或通过代码自动计算。
面数优化：适配目标平台性能限制。

模型转换贴图丢失或 UV 错误问题¶

问题描述：模型在不同软件中显示正常，但转为 .xobj 时出现贴图丢失或 UV 错误。

解决方案：

转换工具更新：使用最新版本转换工具；若默认解码器效果不佳，将导入设置的解码器改为 FBX V1 重新导入。
贴图兼容性调整：
- 检查材质类型是否为标准"Blinn"材质（特殊材质可能导致解析失败）。
- 清理未使用的残留材质球，避免干扰转换过程。
手动调整材质效果：当其他方式都不奏效时，可进入模型转换工具的编辑模式，在编辑模式下调整材质球的贴图和属性。

在转换工具中打开模型报错问题¶

问题描述：在模型转换工具中打开已有模型时提示解析失败或不兼容等错误信息。

解决方案：

尝试把导入设置的解码器更换为其他解码器。
如果所有解码器都无法解析，则需要在建模软件中导出 fbx、glb、gltf、obj 等其他格式。3ds Max 建议以 FBX 2012 版本导出 FBX，Blender 建议导出 gltf 格式。

模型转换工具中法线贴图的规范¶

问题描述：在模型转换工具中使用的法线规范未明确定义。

解决方案：在转换工具中，法线贴图中的每个像素的 RGB 值表示法线方向的 X、Y 和 Z 分量。在切线空间中，法线的 X 分量对应红色通道，Y 分量对应绿色通道，Z 分量对应蓝色通道。通常，法线贴图会有一个蓝色的主色调，因为 Z 分量（指向屏幕外）在切线空间中占据主导地位。

在模型转换工具中打开 obj 模型贴图丢失问题¶

问题描述：在模型转换工具中打开 obj 没有找到模型。

解决方案：

带贴图的 obj 模型至少需要有三个文件：
- *.obj 文件：存储模型网格数据。
- *.mtl 文件：存储模型使用的材质数据。
- *.jpg 或 *.png 文件：存储模型使用的贴图。
obj 模型暂不支持中文名材质文件，需确认 *.mtl 文件名是否包含中文，如果是则需要改成英文名，并将 *.obj 中指向 mtl 的名称改为新名称。
加载 obj 贴图使用的是相对路径加载，需确认 *.mtl 文件中的图片路径是否是相对路径，如果不是需要改成相对路径。
obj 文件中需要指定 mesh 使用的材质，需检查 obj 文件中是否有 usemtl 字段指定网格使用的材质。

模型转换工具失去响应¶

问题描述：在模型转换工具中打开已有模型时卡死或失去响应。

解决方案：

FBX 格式解析最长可能需要数分钟，请耐心等待。如果超过十分钟还没有转换完成（对于大小超过 1G 的模型，可以尝试等待 20 分钟），则认为无法解析，可以强制关闭程序。
尝试把导入设置的解码器更换为其他解码器。
如果所有解码器都无法解析，则需要在建模软件中导出 fbx、glb、gltf、obj 等其他格式。3ds Max 建议以 FBX 2012 版本导出 FBX，Blender 建议导出 gltf 格式。

编辑器与模型显示问题¶

导入的模型在场景中显示为黑色，无光照效果¶

问题描述：创建课程，编辑器场景界面变黑（丢失光照）。

解决方案：通过素材库重新添加"空场景 show"模板（自带光照配置）。

硬件系统¶

无人机手柄连接后无响应¶

解决方案：按手柄 A/B 键重新激活识别。