Unity 插件接入

UPM 包围绕真实 SDK 实现 JSON 桥接，提供请求关联、超时、取消和场景释放。Unity API 采用 Starlight.Engine.BridgeClient；Android / iOS 使用 UnityNativeBridge，Windows 使用独立 WindowsBridge。

安装

1. 从下载中心取得 Unity TGZ，用 Package Manager 的“Add package from tarball”安装。
2. Android 将包内 Native~/Android/starlight-engine.androidlib 复制到 Assets/Plugins/Android/；它已包含 Java SDK 与原生门面源码，不要再导入包含相同类的 AAR。按包内 README 合并权限、minSdk 与混淆规则。
3. iOS 导出 Xcode 项目后加入 Swift Package 与 C ABI 门面；Swift 源码不等于已生成 XCFramework。
4. Windows 引用同版本 netstandard2.1 目标程序集及依赖。不要混入两个版本的 Starlight.GameSDK 或重复 JSON 库。

授权与业务

BridgeClient 构造接收 IEngineBridge、IBridgeCodec 和游戏服务器交换函数。交换函数把授权 JSON 发给自己的可信后端，返回 SessionResponse JSON；永远不在 C# 脚本中保存游戏密钥。

InitializeAsync 接收包含 appId、baseUrl 的配置 JSON。LoginAsync 接收 method、account、密码或短信挑战及 consentVersion；Windows 系统浏览器可使用 BrowserLoginAsync。RestoreSessionAsync 仅在原生验证候选之后恢复。

CenterAsync、OrdersAsync 等常用包装和 CallAsync 的白名单操作复用原生 SDK，错误以 BridgeException.Code 交给宿主。未支持的目标会明确返回 UNSUPPORTED_PLATFORM，不在 Editor 伪造登录成功。

external 模式使用 roles 返回的绑定 id。claimGift 返回 ok=true、orderId、deliveryStatus=pending 时只是领取已接受，需使用 order 查询发货结果；status=fulfilled 才表示游戏服确认，paid 不表示到账。订单 JSON 保留 source/giftId（礼包奖励来源）与 fulfillmentMode/externalRole（履约目标）；v0.2.1 修复了 iOS 强类型订单再编码时丢失这些字段的问题。旧本地订单或仅有 ok 的领取结果仍兼容，不应自行增加游戏资产。

主线程与销毁

Android/iOS 的 UnityNativeBridge 将原生回调排队并由 Unity Update 派发；WindowsBridge 完成回调可能来自工作线程，宿主应通过 Unity SynchronizationContext 切回主线程后更新游戏对象。场景销毁时 Dispose BridgeClient / bridge，解除事件；不要向已销毁 GameObject 回调。跨场景唯一实例由游戏宿主决定，iOS 同一进程只允许一个原生回调拥有者。

已知验证边界

Unity 2021.3+ 条件编译接口已提供，C# 核心和 Windows 桥接执行了协议测试，Android 门面与 SDK 联编通过。当前环境无 Unity Editor 或设备，IL2CPP、AOT、代码裁剪、实际 Unity 导出和输入事件验收尚未执行。必须按发行游戏使用的 Unity 版本完成验证，不能仅依据 C# 编译宣称全版本支持。