Unity Quick Start

本 Quick Start 文档覆盖以下内容：

工程中已安装 IGP.UnitySDK
在场景中挂载 IGPRuntimeManager
只配置 appId
游戏启动流程中主动调用 IGPRuntimeManager.InitializeAsync()
单机或非房间接入先验证 桌面能力（正版校验 / 成就）
联机接入再通过 IGP 桌面客户端注入启动信息，验证 进房 → ready → realtime

也就是说，桌面能力 和 房间流程 都可以从本页开始验证，但二者的前提条件不同。如果游戏不接入联机房间，不需要创建房间、选择地图、ready、realtime 或 KCP。如需优先验证联机主流程，也不需要先完成成就配置。

前置条件

已经按 Unity 安装将 cn.indiegp.sdk.unity 安装到工程中
有 IGP 运营提供的 appId
本机已安装并可启动 IGP 桌面客户端（Windows 10 及以上）

1. 添加一个最小 bootstrap 脚本

在工程中新增 Assets/Scripts/IGPQuickstartDriver.cs：

using System;
using UnityEngine;
using IGP.UnitySDK;
using IGP.UnitySDK.Models;

public sealed class IGPQuickstartDriver : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtimeManager;
    [SerializeField] private string debugMessageType = "quickstart_ping";
    [SerializeField] private string unlockAchievementKey = "first_session";
    [SerializeField] private string progressAchievementKey = "matches_played";

    private void Awake()
    {
        runtimeManager ??= FindObjectOfType<IGPRuntimeManager>();
    }

    private void OnEnable()
    {
        if (runtimeManager == null)
        {
            Debug.LogError("[IGP Quickstart] IGPRuntimeManager is missing.");
            enabled = false;
            return;
        }

        runtimeManager.onRoomJoined.AddListener(HandleRoomJoined);
        runtimeManager.onMessageReceived.AddListener(HandleMessageReceived);
        runtimeManager.onError.AddListener(HandleError);
    }

    private async void Start()
    {
        var ok = await runtimeManager.InitializeAsync();
        if (!ok)
        {
            Debug.LogError("[IGP Quickstart] SDK initialization failed.");
        }
    }

    private void OnDisable()
    {
        if (runtimeManager == null) return;
        runtimeManager.onRoomJoined.RemoveListener(HandleRoomJoined);
        runtimeManager.onMessageReceived.RemoveListener(HandleMessageReceived);
        runtimeManager.onError.RemoveListener(HandleError);
    }

    [ContextMenu("IGP/Send Quickstart Message")]
    public async void SendQuickstartMessage()
    {
        if (runtimeManager == null) return;
        await runtimeManager.SendMessageAsync(new Message
        {
            type = debugMessageType,
            roomId = runtimeManager.CurrentRoomId,
            playerId = runtimeManager.PlayerId,
            reliable = true,
            content = new
            {
                text = "hello from quickstart",
                sentAt = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
            }
        });
        Debug.Log("[IGP Quickstart] Sent realtime message.");
    }

    [ContextMenu("IGP/Unlock Achievement")]
    public async void UnlockAchievement()
    {
        if (runtimeManager == null) return;
        var result = await IGPSDK.UnlockAchievementAsync(runtimeManager, unlockAchievementKey);
        Debug.Log($"[IGP Quickstart] Unlock success={result.success}, duplicated={result.duplicated}");
    }

    [ContextMenu("IGP/Report Achievement Progress")]
    public async void ReportAchievementProgress()
    {
        if (runtimeManager == null) return;
        var result = await IGPSDK.ReportAchievementProgressAsync(
            runtimeManager, progressAchievementKey, 1, "quickstart_manual");
        Debug.Log($"[IGP Quickstart] Progress success={result.success}, duplicated={result.duplicated}");
    }

    private async void HandleRoomJoined(Room room)
    {
        Debug.Log($"[IGP Quickstart] Joined room id={room.id}, code={room.code}");
        await runtimeManager.SetReadyAsync(true);
        Debug.Log("[IGP Quickstart] Local player marked ready.");
    }

    private void HandleMessageReceived(string messageType, object content)
    {
        Debug.Log($"[IGP Quickstart] Message type={messageType}, payload={content}");
    }

    private void HandleError(string error)
    {
        Debug.LogError($"[IGP Quickstart] Runtime error: {error}");
    }
}

2. 在场景中挂载运行时组件

创建一个空对象，例如 IGPBootstrap
为其挂载：
- IGPRuntimeManager
- IGPQuickstartDriver
将 IGPQuickstartDriver.runtimeManager 指向同一个对象上的 IGPRuntimeManager
如果游戏后续会切换场景且需要保持联机不中断，请将该对象设置为跨场景常驻，并确保全程只有一个 IGPRuntimeManager

3. 配置 appId

给对象添加 IGPRuntimeManager 后，SDK 会自动挂载项目里的 IGPConfig。如果项目里还没有配置资源，会自动创建 Assets/IGP/IGPConfig.asset。

在 IGPConfig 上填写 IGP 运营提供的 appId。

SDK 不会因为场景里存在 IGPRuntimeManager 就自动启动。游戏需要在自己的启动流程中调用 InitializeAsync()。

4. 在 Editor 中验证

按这次接入目标选择验证路径：

4.1 单机 / 非房间接入

如果只接入正版校验、成就或其他 room 无关桌面能力，请先按 Unity 调试中的“验证桌面客户端能力”完成验证。

最低目标是看到：

InitializeAsync() 返回成功
手动触发 Unlock Achievement 或 Report Achievement Progress 后看到成功日志

这条路径不要求创建房间、选择地图、进入 ready、发送 realtime 消息或连接 KCP。

4.2 联机 / 房间接入

如果游戏接入房间、realtime、state、RPC、Mirror Transport、KCP 或运行中换地图，请按 Unity 调试中的“验证完整托管房间流程”完成进房验证。

最低目标是看到：

Joined room 日志
Local player marked ready 日志
手动触发 Send Quickstart Message 后看到发送日志

如果这一步尚未通过，请先排查房间流程，不要同时排查成就问题。

5. 桌面能力调试路径说明

如需在 Unity Editor 中验证正版校验或成就，请使用 Unity 调试中“验证桌面客户端能力”的准备项。

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

它不是桌面端路径。SDK 会按 SDK Environment 自动找对应桌面端：PROD 找 IndieGamesPass，PREVIEW 找 IndieGamesPass Preview，DEV 找 IndieSpark。PROD 和 PREVIEW 只会启动对应环境的官方可信桌面端；DEV 才允许用 Desktop Launch Command 或 INDIEGP_DESKTOP_PATH 明确指定本机调试用桌面端。

完成准备后，随后手动触发：

Unlock Achievement
Report Achievement Progress

6. 最小验收标准

验收标准按接入目标分开看：

单机 / 非房间接入

appId 已配置
InitializeAsync() 成功
正版校验或成就调用能返回预期结果

联机 / 房间接入

出现 Joined room 日志
出现 Local player marked ready 日志
手动触发 Send Quickstart Message 后看到发送日志

可选：桌面能力补充

手动触发 Unlock Achievement 后看到成功日志
或手动触发 Report Achievement Progress 后看到成功日志

7. 下一步

Quick Start 完成后，按目标能力继续：

按功能查看引擎示例：按功能使用 SDK
基础启动流程：启动与连接
正版校验：正版校验
成就：成就
联机大厅：联机大厅
最小代码样例：主包 Samples 下的 StarterDemo（UPM → Samples 面板导入）
综合手动联调：主包 Samples 下的 HostedPlayground
项目已使用 Mirror：Mirror 传输层
上线前检查：联调与测试