# START HERE

这份文档只讲一条最短路径，目标是让外部 Unity 开发者自己跑通第一次联调。

适用范围：

- Windows
- Unity `2022.3 LTS`
- Curio desktop
- 房间创建、加入和开始游戏都由 desktop 控制

先记住一个原则：

- SDK 不负责创建房间
- SDK 不负责开始游戏
- SDK 负责在游戏启动后接住 desktop 给的这次启动信息，然后完成进房和附着

## 1. 先完成 Unity 最小接入

先按下面两份文档把 SDK 接进工程：

- [Unity Quick Start](QUICKSTART.md)
- [Package README](../README.md)

如果你想先确认 Unity 里到底能监听哪些事件，再看：

- [Unity Event Reference](EVENT-REFERENCE.md)

至少要确认这些基础项已经就位：

- 工程里已经安装 `IGP.UnitySDK`
- 场景里已经挂了 `IGPRuntimeManager`
- `IGPRuntimeManager` 已自动挂载 `IGPConfig`
- `IGPConfig` 里已经填好 `appId`
- 游戏启动流程里会主动调用 `IGPRuntimeManager.InitializeAsync()`

授权验证现在也走这条主线，不需要额外再配别的必填项。

如果你想先直接看一份现成代码，不要自己从零写，优先导入：

- `Samples~/StarterDemo`


## 2. 先打开 desktop 里的 SDK 联调开关

在 Curio desktop 里先打开 `设置 -> 关于`，把 `SDK 联调 Beta` 设为开启。

如果你在这里都看不到这个开关，说明当前账号还没有开通联调权限，需要联系支持或对接人处理。

打开以后，再进入这款游戏的详情页或房间页，找到 `SDK 联调`。

这页会给你 4 类信息：

- 当前角色是房主还是成员
- 当前房间号
- 当前游戏是否已经就绪
- 最近一次生成或启动的结果

## 3. 创建或加入测试房间

在 `SDK 联调` 页或房间页完成下面任意一种操作：

- 自己创建测试房间
- 输入房间号加入别人创建的测试房间

进入房间后，再继续后面的步骤。

如果你当前在别的游戏房间里，先离开那个房间，再调当前游戏。

## 4. 生成这次启动要用的 Unity 启动包

进入测试房间后，点击：

- `获取启动信息`

desktop 会生成一份 Unity 启动包。你可以直接复制它，不需要再手工拆 `ticket`、`endpoint`、`secret`。

第一阶段统一使用这份结构：

```json
{
  "roomId": "当前房间 ID",
  "appId": 123,
  "ticket": "本次启动票据",
  "endpoint": "本次 bootstrap 地址",
  "secret": "本次 bootstrap 密钥",
  "autoConnect": true,
  "generatedAt": "生成时间"
}
```

## 5. 选一种联调方式

### 方式 A：Unity Editor 联调

适合先跑通单机和最小功能验证。

接下来直接看：

- [EDITOR DEBUG](EDITOR-DEBUG.md)

### 方式 B：本地打包版联调

适合验证 desktop 真正启动本地游戏的完整路径。

最短流程：

1. 在 desktop 里进入测试房间
2. 点击 `启动本地打包版`
3. 观察游戏是否自动进入当前房间
4. 如果失败，点击 `打开主进程日志` 或 `导出诊断信息`

如果 Editor 能跑通，但打包版不行，先看：

- [TROUBLESHOOTING](TROUBLESHOOTING.md)

## 6. 先看什么算跑通

第一次联调建议只验证下面 5 件事：

1. 游戏能接住 desktop 给的启动信息
2. 授权验证已经通过，或者被明确标成 `Skipped`
3. Unity 能自动进入当前测试房间
4. 本地玩家能看到自己的房间信息
5. `ready`、基础消息或最小状态同步至少有一个能跑通

不要第一次就把所有功能一起排查，否则你很难判断是接入没通，还是业务逻辑有问题。

如果你的游戏要支持“一局结束后不重启游戏直接换地图”，在基础进房跑通后再接 `onMapChanged`：

- desktop / lobby 换地图后，游戏会收到新的房间快照
- Unity 侧监听 `IGPRuntimeManager.onMapChanged` 或 `IGPEventManager.onMapChanged`
- 回调参数 `IGPMapChangeData.currentMapPublicId` / `currentMapVersionId` 是新地图
- 详细字段和示例看 [Unity Event Reference](EVENT-REFERENCE.md)

## 7. 双机联调怎么开始

第一阶段只做基础双机闭环，建议按这个顺序：

1. host 机器创建测试房间
2. guest 机器输入房间号加入
3. 两边分别生成各自的 Unity 启动包
4. 两边各自完成一次 Editor 或打包版启动
5. 再验证 ready、开始游戏、基础消息

不要把 host 的启动包复制给 guest，也不要把 guest 的启动包复制给 host。每台机器都要用自己那一份。

## 8. 出问题先看哪里

先按这个顺序排查：

1. 有没有进入当前游戏的测试房间
2. 启动包是不是刚生成的
3. Unity 里是不是用了当前机器自己的启动包
4. desktop 里的最近结果是什么
5. 主进程日志和导出的诊断信息里有没有明显报错

详细问题列表看：

- [TROUBLESHOOTING](TROUBLESHOOTING.md)
- [AUTHORIZATION](AUTHORIZATION.md)
