# IGP Unity SDK 接入指南

本文档对应 Unity `2022.3.62f3c1` 和 IGP Unity SDK `0.3.4`。

## 安装

正式交付按模块同时提供 `.unitypackage` 与离线 UPM `.tgz`，同一模块选择其中一种载体。所有接入至少安装 Core：

- `cn.indiegp.sdk.unity-0.3.4.unitypackage`

按需继续导入 Multiplayer、Compliance、Game Kit 等可选包，这些包均依赖
Core。公开 Multiplayer 的目标职责仅为 descriptor-driven RoomNode Game
数据面、Realtime 和 Mirror；房间控制面不属于公开 Multiplayer。当前
descriptor connect API 已落地，Runtime 只建立 Playing 阶段的 Game 数据面连接。

仓库内开发也可以通过 Unity Package Manager 的 `Packages/manifest.json` 使用本地 `file:` 依赖，路径指向 `adapters/unity/Runtime/` 下的对应 package。

使用 UPM tarball 时，先安装 `core-igp-0.3.4.tgz`，再按需安装 `multiplayer-igp-0.3.4.tgz`、`compliance-igp-0.3.4.tgz` 和 `game-kit-igp-0.3.4.tgz`。外层文件名以功能名开头，归档内部仍使用正式 UPM 包名。

## 配置

在场景对象上添加 `IGPRuntimeManager`，创建并填写 SDK 配置，最重要的配置是平台分配的 `appId`。常规接入不需要填写游戏运行目录或可执行文件路径。

SDK 不会自动扫描、创建或修改接入工程中的场景、Prefab、配置资源或 Project Settings；这些资源由接入者显式创建和引用。

## 初始化

将 [`Examples/CoreQuickstart.cs.txt`](./Examples/CoreQuickstart.cs.txt) 复制到项目脚本目录，去掉 `.txt` 后缀，再挂到包含 `IGPRuntimeManager` 的场景对象或显式绑定 runtime 引用。

游戏通过 Desktop 启动后，Core 会建立 desktop session。业务代码应等待 `InitializeAsync()` 成功后再调用用户、授权、成就等能力，并订阅对应公开事件处理运行时状态变化。

初始化完成后可通过 `runtime.RuntimeInfo.SaveRootPath` 读取宿主提供的存档根目录。该属性不需要参数且始终返回非 `null` 字符串；宿主没有提供时返回空字符串。SDK 只提供该值，不会创建或修改目录。

Core 对明确列入范围的登录和 Profile 能力可自行组织 Curio 请求。Hosted Session
宿主平台通过 Core 配置的 `IGPHostSessionPlatform.Desktop` 或 `Mobile` 选择；
Multiplayer 不读取该配置，只消费 Core Host provider 或调用方显式提供的
RoomNode descriptor，并直接建立 Game 数据面。

## 代码案例

- [`CoreQuickstart.cs.txt`](./Examples/CoreQuickstart.cs.txt)：最小初始化。
- [`AchievementsExample.cs.txt`](./Examples/AchievementsExample.cs.txt)：解锁成就和上报进度。
- [`ComplianceExample.cs.txt`](./Examples/ComplianceExample.cs.txt)：通过 Desktop 提交实名数据，并刷新、监听防沉迷状态。
- [`GameKitExample.cs.txt`](./Examples/GameKitExample.cs.txt)：读取当前用户资料与排行榜列表。
- [`MultiplayerDataPlaneExample.cs.txt`](./Examples/MultiplayerDataPlaneExample.cs.txt)：在
  显式 descriptor 路径中把房间控制面或其他集成取得的 SDK descriptor
  交给 Multiplayer，并等待 RoomNode Game 数据面进入 Ready。
- [`MirrorTransportExample.cs.txt`](./Examples/MirrorTransportExample.cs.txt)：仅在项目已安装 Multiplayer 与 Mirror 时使用；复制进工程时去掉 `.txt` 后缀。

代码案例是独立文件，不附带完整工程、场景或 Prefab。所有案例都以 `.cs.txt` 交付，避免导入 `.unitypackage` 时自动参与编译；复制需要的文件后去掉 `.txt` 后缀。接入者需要在自己的工程中创建对象、挂载组件并填写引用。
