启动与连接

启动与连接是所有能力的前置流程。不同引擎的接入方式不同，但目标一致：让游戏获得 appId，连接本机 IGP 桌面客户端，并在需要时进入联机大厅流程。

功能说明

这一层主要负责：

读取或配置 appId
执行游戏主动触发的 SDK 初始化
连接本机 IGP 桌面客户端
判断连接状态
查询桌面客户端当前暴露的能力
处理从 IGP 桌面客户端启动游戏时注入的参数
在房间、实时消息、状态和 RPC 场景中建立房间联机连接

支持引擎

引擎	状态	说明
Unity	Preview	`IGPRuntimeManager` 负责桌面客户端连接、启动参数和房间联机连接。
GameMaker	Preview	Windows runtime 负责初始化、每帧更新、能力查询和事件队列。
Godot	开发中	通过命令行参数 bootstrap，并用 autoload 暴露房间联机能力。

前置条件

本机安装 IGP 桌面客户端。
游戏已获得 IGP 分配的 appId。
游戏会在启动流程中调用 IGP SDK 初始化方法。
需要房间、实时消息、状态或 RPC 时，游戏必须由 IGP 桌面客户端按联调流程启动。
只验证成就、正版校验、实名认证与防沉迷时，也需要 IGP 桌面客户端连接可用。

游戏内初始化

初始化由游戏项目自己的启动流程控制。只把 SDK 组件放进场景不会自动启动 SDK。

Unity 侧调用 IGPRuntimeManager.InitializeAsync() 完成初始化。

GameMaker 侧调用 igp_init(...) 完成初始化。

按引擎查看

Unity 侧需要在场景中放置一个 IGPRuntimeManager，配置 appId，并在启动流程中调用 InitializeAsync()。

using UnityEngine;
using IGP.UnitySDK;

public sealed class IGPStartupDriver : MonoBehaviour
{
    [SerializeField] private IGPRuntimeManager runtimeManager;

    private void OnEnable()
    {
        if (runtimeManager == null)
        {
            return;
        }

        runtimeManager.onConnectionStateChanged.AddListener(OnConnectionChanged);
        runtimeManager.onRoomJoined.AddListener(room =>
        {
            Debug.Log($"IGP room joined: {room.id}");
        });
        runtimeManager.onError.AddListener(error =>
        {
            Debug.LogError($"IGP runtime error: {error}");
        });
    }

    private async void Start()
    {
        await runtimeManager.InitializeAsync();
    }

    private void OnDisable()
    {
        if (runtimeManager == null)
        {
            return;
        }

        runtimeManager.onConnectionStateChanged.RemoveListener(OnConnectionChanged);
    }

    private void OnConnectionChanged(bool connected)
    {
        Debug.Log($"IGP connected={connected}");
    }
}

如需在 Unity Editor 中调试完整房间流程，请查看 Unity 调试。

GameMaker 侧的基本流程为初始化、每帧更新和轮询事件。

// Create
global.igp_app_id = YOUR_APP_ID;
global.igp_sdk_enabled = true;

if (global.igp_sdk_enabled)
{
    igp_init(global.igp_app_id, {
        desktop_auto_attach: true
    });
}

// Step
if (!global.igp_sdk_enabled)
{
    exit;
}

igp_update();

var snapshot = igp_get_state_snapshot();
if (snapshot.connection_state == "connected")
{
    // 可以继续读取授权、实名认证与防沉迷和成就相关状态。
}

var evt = igp_poll_event();
while (!is_undefined(evt))
{
    show_debug_message("IGP event: " + string(evt.type));
    evt = igp_poll_event();
}

如需确认桌面客户端支持的能力：

var capabilities = igp_get_desktop_capabilities();
if (!is_undefined(capabilities) && capabilities.achievements)
{
    // 可以调用成就接口。
}

Godot 当前通过命令行参数完成 bootstrap，并建议注册为 autoload。

using Godot;
using IGP.GodotSDK.Autoload;

public partial class BootstrapFromCommandLine : Node
{
    public override async void _Ready()
    {
        var igp = GetNode<IGPGodotAutoload>("/root/IGP");
        var bootstrapped = await igp.BootstrapFromCommandLineAsync();

        if (bootstrapped)
        {
            await igp.ConnectHostedSessionAsync();
        }
    }
}

Godot 仍是开发中状态，当前入口用于评估，不建议直接用于正式发行项目。

自测方式

引擎	最小自测
Unity	完成 Unity Quick Start，非房间接入时至少看到桌面能力结果，房间接入时至少看到进房和 ready 日志。
GameMaker	完成 GameMaker Quick Start，确认连接状态不再停留在 `disconnected`。
Godot	用预览工程验证 `BootstrapFromCommandLineAsync()` 返回成功，并收到房间快照。

更完整的检查清单见联调与测试。

常见问题 / 排查

没有 appId：优先补齐平台分配的 appId。
SDK 没有任何连接或事件：确认是否调用了 IGPRuntimeManager.InitializeAsync() 或对应引擎的初始化入口。
没有从桌面客户端启动：房间、实时消息、状态、RPC 通常不会完整可用。
连接状态持续失败：先确认本机 IGP 桌面客户端是否已安装并可启动。
Unity 切场景后断线：确保全程只有一个 IGPRuntimeManager，并按需要做成跨场景常驻。