Unity 调试

本页说明 如何在 Unity Editor 中调试 IGP SDK。安装和最小接入请先查看 安装 和 Quick Start。

在 Editor 中调试 IGP SDK 有两种典型场景：

• 场景 A：验证 IGP 桌面客户端提供的能力（正版校验、成就解锁、进度上报）。
• 场景 B：验证完整托管房间流程（launch ticket、自动进房、ready、start、finish、房间消息、state、RPC、数据面）。

单机游戏或暂不接入联机房间的游戏，通常只需要完成场景 A。只有接入房间、realtime、state、RPC、Mirror Transport、KCP 或运行中换地图时，才需要完成场景 B。

怎么算连接成功

这里也分两层看：

• 桌面能力成功：InitializeAsync() 返回成功，且 IGPRuntimeManager.IsDesktopSessionAttached == true
• 房间链路成功：在上面基础上，onRoomJoined 已触发，并且需要房间时 IsHostedSessionAttached == true

如果你只验证授权、成就或其他 room 无关能力，桌面能力成功就够了，不要把“没看到房间”误判成没连上。

开启详细联机日志

需要排查房间、realtime、state、RPC、KCP 或 Mirror Transport 问题时，可以在 IGPConfig 中把 Debug Logging 选择为 Error / Warning / Info / Debug。等级使用最低等级语义，选择 Warning 时会记录 Warning 和 Error。

开启后 Unity Console 会额外输出：

• [IGP SDK] 日志的 runId 和启动总览 event=session-start，用于对齐同一次游戏运行里的 SDK、desktop 和 server 日志
• hosted session 命名管道连接、命令、数据面请求和服务端消息类型
• hosted realtime 高层操作，例如发送消息、state、RPC、ping
• KCP 目标解析、UDP datagram、KCP frame、握手、App RTT、KCP srtt/rto 和收到的消息类型
• P2P 网络层的 localPlayerId / sourcePlayerId / targetPlayerId / messageType / payload 大小 / checksum / 可靠分片摘要；默认不输出完整 payload
• IGPMirrorTransport 的消息收发摘要；Mirror Transport 统一通过 [IGP SDK] scope=mirror-transport 输出，跟随 Runtime LogLevel，未绑定 Runtime Manager 时默认不打印日志

也可以在运行时临时修改挂载到 IGPRuntimeManager 的 IGPConfig：

runtimeManager.Config.debugLogging = IGPLogLevel.Debug;

正式发布建议保持关闭，避免输出过多联机细节和影响日志可读性。

场景 A：验证桌面客户端能力

这条路径使用 desktop session，不依赖房间上下文。它适用于正版校验、成就解锁、成就进度上报等 room 无关能力。

Unity Editor 里直接调 desktop 能力时，通常不需要填写 Desktop Executable Path Debug Override。

不填这个路径时，SDK 会按环境启动桌面端，并把 Unity Editor 当前进程路径和 appId 一起交给桌面端；是否允许联调由桌面端的 SDK 联调规则判断。只有需要模拟正式安装路径或排查本地 exe 绑定时，才需要填这个路径；此时应填写该游戏真实的 Windows 可执行文件路径（例如 D:\builds\MyGame\MyGame.exe），不要填写桌面端路径。

这个配置不是桌面端路径。桌面端启动命令由 SDK 根据 SDK Environment 自动选择：PROD 对应 IndieGamesPass，PREVIEW 对应 IndieGamesPass Preview，DEV 对应 IndieSpark。PROD 和 PREVIEW 只会启动对应环境的官方可信桌面端；DEV 才允许用 Desktop Launch Command 或 INDIEGP_DESKTOP_PATH 明确指定本机调试用桌面端。

注意

这个路径只会在 Editor 中生效。Build 生成的 Player 会使用自身 exe 路径，不需要额外清理。

场景 B：验证完整托管房间流程

这条路径使用 hosted session，只适用于需要房间上下文的能力。单机接入不需要创建测试房间或选择地图。

需要验证从 launch ticket 开始的端到端流程时：

1. 进入当前游戏的测试房间

1. 在 IGP 桌面客户端打开当前游戏的 SDK 联调 页
2. 创建测试房间，或者加入一个已经存在的测试房间

注意

Connect Current Test Room 只会连接当前已经在桌面客户端中进入的测试房间。 如果尚未进入房间，后续即使启动包正确，也会表现为连接失败。

2. 在 IGP 桌面客户端生成 Unity 启动包

在 IGP 桌面客户端中打开 SDK 联调 页，点击生成 Unity 启动包，复制生成的 JSON。

3. 将启动包粘贴到 Runtime Manager

1. 打开包含 IGPRuntimeManager 的场景
2. 选中挂了 IGPRuntimeManager 的对象
3. 在 Inspector 中找到 Unity Editor 联调 → Launch Package JSON
4. 粘贴整包 JSON
5. 点击 Apply Launch Package

4. 进入 Play mode 并连接房间

1. 点击 Editor 的 Play 按钮
2. 在 Inspector 中点击 Connect Current Test Room

整个过程对 host 和 guest 是对称的：调试 host 端时使用 host 启动包，调试 guest 端时使用 guest 启动包。

常见问题

• 只看到 detached 状态：确认桌面端已登录、已打开 SDK 联调，后台已允许该账号联调当前 appId。
• Connect Current Test Room 持续连接失败：尚未先在 IGP 桌面客户端进入当前游戏的测试房间。
• Apply Launch Package 后没有进房：启动包已经过期（ticket 有时效），回到桌面客户端重新生成。
• 两端都已启动但看不到对方：两端使用了同一份启动包。每个玩家都需要使用各自对应的启动包。