# TROUBLESHOOTING

这份文档只收口第一阶段最常见的问题。

排查顺序建议固定下来，不要一次改很多地方：

1. 先看 desktop 里的房间状态
2. 再看这次启动包是不是刚生成的
3. 再看 Unity Inspector 或打包版到底有没有真的进房
4. 最后看日志和诊断信息

## 1. 看不到 `SDK 联调` 入口

先到 `设置 -> 关于`，确认 `SDK 联调 Beta` 已经打开。

如果开关已经打开，但游戏详情页或房间页还是看不到入口，再考虑权限问题。

处理方式：

1. 先刷新当前页面，或者退出桌面端后重新打开
2. 回到当前游戏的详情页或房间页再看一次
3. 如果 `SDK 联调 Beta` 开关本身都没有，联系支持或对接人开通权限

## 2. 能打开联调页，但提示先创建或加入测试房间

说明当前机器还不在这款游戏的测试房间里。

处理方式：

1. 在当前游戏里创建测试房间，或者输入房间号加入
2. 确认你已经真的进入当前房间
3. 再回来点 `获取启动信息`

## 3. 已经生成启动包，但 Unity 还是没进房

先按下面顺序查：

1. 启动包是不是刚在当前房间生成的
2. 这份启动包是不是当前机器自己的
3. 你有没有先点 `Apply Launch Package`
4. 你是不是进入了 Play 以后才点 `Connect Current Test Room`
5. `IGPConfig.appId` 和当前游戏是不是同一个

如果你手工改过下面这些字段，也先恢复成 desktop 生成的原值：

- `Launch Ticket`
- `Bootstrap Endpoint`
- `Bootstrap Secret`

## 4. Editor 能通，打包版不通

这通常说明接入主线已经差不多了，问题更可能在打包侧。

先查这几件事：

1. desktop 里的这款游戏是不是已经就绪
2. desktop 点 `启动本地打包版` 后，最近结果是什么
3. 主进程日志里有没有启动失败信息
4. 导出的诊断信息里有没有明显路径或启动报错

建议不要一开始就只盯着打包版。先让 Editor 跑通，再回来看打包版，排查会快很多。

## 5. host 可以，guest 不行

这是双机联调里最常见的问题。

优先查：

1. guest 是不是真的已经加入 host 创建的房间
2. guest 用的是不是 guest 自己那份启动包
3. host 和 guest 的 `appId` 是不是一致
4. guest 是不是在加入房间之前就先启动了 Unity

记住：

- host 和 guest 不能共用同一份启动包
- 每台机器都要在自己的 desktop 上生成自己的启动包

## 6. desktop 提示已经启动，但 Unity 没反应

先分两种情况看：

### Editor 联调

检查你是不是已经：

1. 先把启动包贴进 Inspector
2. 点了 `Apply Launch Package`
3. 进入了 Play
4. 再点 `Connect Current Test Room`

### 打包版联调

检查这几项：

1. 游戏可执行文件路径是否正确
2. desktop 当前是不是对准了正确的本地构建
3. 游戏进程有没有真的被拉起
4. 联调页里的当前游戏进程和最近输出有没有变化

## 7. 日志在哪里看

第一阶段优先看 3 个地方：

1. desktop 联调页里的最近结果
2. `打开主进程日志`
3. `导出诊断信息`

如果是 Editor 联调，还要一起看：

4. Unity Console

建议提问题时把这几样一起带上，不要只发一句“没进房”：

- 当前房间号
- 你是 host 还是 guest
- 生成启动包的时间
- 最近一次结果
- 主进程日志
- Unity Console 报错
- 诊断信息导出文件

## 8. 什么时候应该重新生成启动包

出现下面任意一种情况，都建议重新生成：

- 你离开过当前房间
- 你重新加入过房间
- 你切换过 host / guest 角色
- 你隔了一段时间才重新联调
- 你不确定手上的启动包是不是最新的

最稳的做法是：

- 每次准备启动前，都在当前房间里重新点一次 `获取启动信息`

## 9. 什么时候该怀疑不是 SDK 接入问题

如果下面这些都已经确认没问题：

- desktop 房间状态对
- 启动包是最新的
- Unity 已经完成附着
- 基础进房已经成功

但你的业务逻辑还是不对，那就要开始查你自己的游戏代码了，比如：

- 进房后的初始化逻辑
- ready / start 的监听逻辑
- 自己的消息分发逻辑
- 房间状态渲染逻辑

不要把“已经进房但业务没反应”和“根本没进房”混在一起处理。

## 10. desktop 已经换地图，但 Unity 没触发 `onMapChanged`

先确认这不是“离开旧房间再进入新房间”的流程。`onMapChanged` 只在同一个 `roomId` 内地图字段变化时触发。

优先查：

1. 游戏是不是仍然停留在同一个房间里
2. desktop / lobby 是否真的下发了新的房间快照
3. 新快照里的 `mapPublicId` 或 `mapVersionId` 是否和上一份不同
4. 你的脚本是否已经监听 `IGPRuntimeManager.onMapChanged` 或 `IGPEventManager.onMapChanged`
5. `IGPRuntimeManager` 是否因为切场景被销毁或重复创建

如果 `onRoomUpdated` 能收到，但 `mapPublicId` / `mapVersionId` 没变，说明平台侧还没有把新地图写进房间快照；这时先回到 desktop / 后端链路排查。
