Cocos Creator 插件接入

提供 TypeScript Web / native 适配器及 Android / iOS 门面。Web 路径直接包装 @starlight/sdk；原生路径通过 Creator 3.x 的 native.reflection 连接平台 SDK。

Web 游戏

import { createWebSDK } from '@starlight/cocos-sdk';
const sdk = createWebSDK({
  appId: '你的H5AppID',
  baseUrl: 'https://account.example.com',
  storage: sessionStorage,
  exchange: async authorization => {
    const response = await fetch('/game/session', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(authorization)
    });
    if (!response.ok) throw new Error('游戏服务器交换失败');
    return response.json();
  }
});
await sdk.init();
await sdk.restoreSession();

解压下载包后安装本地 @starlight/cocos-sdk，并安装对应版本 @starlight/sdk 作为 peer dependency。游戏服务器保存 X-API-Key，浏览器不接触密钥。

原生导出

用 createCocosTransport('android' 或 'ios', native.reflection) 建立传输，传给 NativeSDK，并提供游戏服务端 exchange 回调。initialize 接收 appId、baseUrl。发行包 Native/ 目录包含需要集成进导出工程的门面源码。Android 按包内 README 加入 Java SDK 与门面 sourceSets，或接入 androidlib；不要重复引入相同 SDK 类的 AAR。iOS 添加 Swift Package 与专用 Cocos 门面。

Android 调用 games/starlight/engine/CocosBridge，iOS 调用 StarlightCocosBridge。原生回传经 __starlightNativeReceive 关联请求；同一进程仅一个拥有者，重复初始化拒绝覆盖。dispose 时清理订阅、超时和原生对象。

订单、权益、支持工单使用 call 的受限方法分派；超时不会自动重复付款。保留原 requestId，查询原订单。业务 JSON 字段与OpenAPI一致。

external 模式 roleId 使用 roles 返回的可信绑定 id。claimGift 的 ok=true、orderId、deliveryStatus=pending 代表领取已接受，不能显示已到账；继续调用 order，直到 status=fulfilled 才是游戏服确认。订单保留 source/giftId 和 fulfillmentMode/externalRole，礼包奖励不能计作充值购买。v0.2.1 修复 iOS 门面对这些订单字段的丢失，旧本地订单可缺省元数据。原生 Node 协议测试共 8 项通过，其中包含待发货结果与旧本地领取兼容；这不替代 Creator 设备验证。

能力边界

TypeScript 与 Web/native 协议测试已执行，Android 桥接联编通过。Creator 编辑器导出、实际 JSB、iOS Objective-C++ / Xcode、设备前后台和触摸事件需使用目标工程继续验收。此插件不等于微信或抖音小游戏渠道 SDK，也没有默认开启原生 Windows Cocos 适配。

JSB 环境依赖

NativeSDK 不要求 structuredClone，全局会话快照按 JSON 复制。构造前需提供 AbortController / AbortSignal（宿主缺少时安装兼容 polyfill）；缺失时立即返回 MISSING_ABORT_CONTROLLER 并释放 transport，不会挂起登录。原生示例使用 XMLHttpRequest 交换授权。缺少两个 Web 全局的兼容场景已纳入 Node 测试，但不替代 Creator JSB 真机验收。