Unity 对接指南

本指南对应 Unity 2022.3 LTS。安装步骤见 Unity 安装， 最小代码见 Unity Quick Start。

接入顺序

1. 安装 Core，再按需安装 Compliance、GameKit 或 Multiplayer。
2. 在场景中保留唯一的 IGPRuntimeManager。
3. 在 IGPConfig 中填写 appId；Host Session 平台无需配置。
4. 由游戏启动流程显式调用 InitializeAsync()。
5. Core 就绪后再调用正版校验、成就和其他 Desktop 能力。
6. 只有明确需要游戏数据同步时才安装 Multiplayer；Multiplayer 不再提供独立的 Host 平台或初始化模式开关。

Core 配置

配置	必填	说明
appId	是	当前游戏的应用 ID。
SDK Environment	否	选择 PROD、PREVIEW 或 DEV 对应环境。
Debug Logging	否	调试时提高日志等级；正式发布建议关闭详细日志。
Desktop Executable Path Debug Override	否	仅用于 Editor 模拟游戏 exe 绑定，不是桌面端路径。

SDK 不会自动修改接入工程的场景、Prefab、Project Settings 或业务配置。 Core 初始化时根据当前 Unity 运行平台按 Desktop、Mobile 优先级判断，命中后只 创建一个 Host runtime；attach 失败不会切换平台。Multiplayer 只使用当前 Core Host provider，不判断平台。

最小初始化

using IGP.UnitySDK;
using UnityEngine;

public sealed class IGPBootstrap : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtime;

    private async void Start()
    {
        runtime ??= FindObjectOfType<IGPRuntimeManager>();
        if (runtime == null || !await runtime.InitializeAsync())
        {
            Debug.LogError("IGP initialization failed.");
            return;
        }

        Debug.Log($"Desktop attached={runtime.IsDesktopSessionAttached}");
    }
}

组件存在不等于 SDK 已启动。只有 InitializeAsync() 成功后，依赖 Desktop session 的能力才可以调用。

正版校验和成就

正版校验、成就解锁和进度上报属于 Core/Desktop 能力，不依赖房间或 Multiplayer Runtime。具体返回类型、错误码和离线语义见：

• 正版校验
• 成就

成就调用示例：

var result = await IGPSDK.UnlockAchievementAsync(runtime, "first_session");
Debug.Log($"success={result.success}, duplicated={result.duplicated}");

Runtime 与房间控制边界

公开 Multiplayer Runtime 的目标职责只有进入 Playing 后的游戏数据同步：

Core-selected Host descriptor OR caller descriptor -> Multiplayer Runtime
Multiplayer Runtime -> KCP/TCP reliable + optional UDP unreliable -> RoomNode

Runtime 可以负责 Realtime、状态/RPC、原始游戏数据、Mirror、心跳和传输诊断， 但不负责以下行为：

• 创建、查询、加入、离开或关闭房间；
• 玩家资料、ready、team、map、start、finish 或 rematch；
• Gateway HTTP/WebSocket；
• 通过 Desktop Hosted、launch ticket 或 host bridge 执行房间控制；
• 房间/玩家/队伍 snapshot、RoomChanged、CurrentRoomData 或 room manager。

无参数 TryCreateRuntimeAsync() 向 Core 当前 Host provider 请求 descriptor； TryCreateRuntimeAsync(IGPMultiplayerDescriptor) 接受调用方 descriptor。两者不是 模式，不需要切换配置。不要把源码中仍存在的 Hosted 房间投影或 Runtime 房间 API 当作数据面稳定接口。

Multiplayer 调用顺序

1. Gateway 侧完成房间控制并使对局进入 Playing。
2. 调用无参数入口从 Core Host provider 获取 descriptor，或调用 descriptor 重载传入调用方取得的不可变 descriptor。
3. Host 自动创建失败时，Core 仍成功，IsRuntimeCreated 为 false；修复 Host 链路后调用显式重试接口。
4. Runtime 只连接 RoomNode Game lane，并通过连接事件报告 readiness。
5. 游戏结束时，先显式断开 Runtime 数据面；finish、rematch 或 leave 仍由 Gateway 侧房间控制执行。

Runtime 断开不得隐式 finish 或 leave。调用方 descriptor 过期只报告错误，由 调用方取得新 descriptor 后重新调用显式创建接口；无参数重试则通过 Core Host provider 取得新的 descriptor。

错误处理

Core 和 Multiplayer 错误应分别处理：

• Core 错误关注 Desktop attach、能力可用性和业务错误码。
• Multiplayer 错误只关注 descriptor 校验、RoomNode 连接、Game lane framing、 超时、断线和传输故障。
• Gateway 房间错误不应从 Multiplayer Runtime 事件中出现。
• 日志、异常和事件不得包含 bearer token、WebSocket token 或 RoomNode token。

接入检查清单

• 场景中只有一个长期有效的 IGPRuntimeManager。
• appId 和 SDK 环境配置正确。
• InitializeAsync() 成功后才调用 Desktop 能力。
• 单机或非联机能力不等待房间事件。
• 新联机接入没有使用 Hosted launch package、Connect Current Test Room、 RoomChanged 或 Runtime 房间命令。
• 使用 IsRuntimeCreated 与 IsRealtimeReady 分别确认 Runtime 创建和数据面就绪。

Editor 调试方法见 Unity 调试。