c4e2d73300
- game-cloud：yudao-cloud fork(裁剪至 system/infra)+ 5 业务模块 project/aigc/runtime/feed/telemetry - 黄金模块 game-module-project + 克隆 4 脊柱模块；46 单测绿 + 41 模块集成编译绿 - contracts/：8 类契约锁定(5 API YAML + sdk-interface.d.ts + game-package.schema + events 等) - yudao-server 接线：全局组件扫描 + @MapperScan + Flyway V1-V5(baseline-version=0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
90 lines
3.7 KiB
TypeScript
90 lines
3.7 KiB
TypeScript
/**
|
||
* 契约 #3 | HuijingGameSDK 公共 API 类型 + SDK↔宿主 postMessage 协议
|
||
* owner：WS3 SDK 负责人 | 消费方：game-studio 宿主 / 游戏侧
|
||
*
|
||
* 硬约束（来自 engineering-conventions §3）：
|
||
* - 零第三方依赖；Core(Lifecycle+EventBus+Telemetry+ErrorTrack) 压缩后 < 8KB；每 Plugin < 5KB
|
||
* - 所有对外 API 不返回 Promise（fire-and-forget），不占游戏主线程，异常绝不向游戏抛
|
||
* - 新版本只增字段/方法、不删不改已有签名（semver）
|
||
*/
|
||
|
||
/** SDK 初始化参数（宿主注入） */
|
||
export interface HuijingGameSDKInitOptions {
|
||
gameId: string;
|
||
versionId: string;
|
||
/** 贯穿 生成→编译→加载→运行→上报 的 trace_id */
|
||
traceId: string;
|
||
/** 是否开发模式（加载 Plugin.Debug，仅 dev） */
|
||
debug?: boolean;
|
||
}
|
||
|
||
/** 游戏生命周期事件名 */
|
||
export type LifecycleEvent =
|
||
| 'sdk_ready' // SDK 初始化完成
|
||
| 'game_loaded' // 游戏资源加载完成
|
||
| 'game_start' // 开始游玩
|
||
| 'game_end' // 本局结束
|
||
| 'game_error'; // 运行错误
|
||
|
||
/** SDK 根对象（挂在游戏侧 window.HuijingGameSDK） */
|
||
export interface HuijingGameSDK {
|
||
/** 初始化（宿主调用一次） */
|
||
init(options: HuijingGameSDKInitOptions): void;
|
||
/** 生命周期事件订阅（EventBus） */
|
||
on(event: LifecycleEvent, handler: (payload?: Record<string, unknown>) => void): void;
|
||
off(event: LifecycleEvent, handler: (payload?: Record<string, unknown>) => void): void;
|
||
/** 遥测上报（fire-and-forget，内部 10条/5s 批量 flush + sendBeacon 兜底） */
|
||
track(event: string, props?: Record<string, unknown>): void;
|
||
/** 错误上报（去重，不中断游戏） */
|
||
reportError(error: { message: string; stack?: string }): void;
|
||
/** 插件（首次调用懒加载） */
|
||
ad: AdPlugin;
|
||
pay: PayPlugin;
|
||
}
|
||
|
||
/** 广告插件（MVP 桩 → 真实穿山甲/优量汇切换；每调用 5s 超时降级） */
|
||
export interface AdPlugin {
|
||
/** 激励视频；完成回调 rewarded=true */
|
||
showRewarded(slotId: string, cb: (result: { rewarded: boolean }) => void): void;
|
||
/** 插屏广告 */
|
||
showInterstitial(slotId: string, cb?: (result: { shown: boolean }) => void): void;
|
||
}
|
||
|
||
/** 支付插件（MVP 桩 → 真实微信支付切换） */
|
||
export interface PayPlugin {
|
||
/** 发起积分充值；宿主侧拉起支付 */
|
||
pay(order: { orderId: string; amount: number }, cb: (result: { paid: boolean }) => void): void;
|
||
}
|
||
|
||
/* ============================================================================
|
||
* SDK ↔ 宿主 postMessage 协议
|
||
* 游戏在 iframe 沙箱内，通过 postMessage 与 game-studio 宿主通信。
|
||
* 宿主侧校验 origin 白名单 + 消息 schema（双校验，见 security-and-reliability §1.1）。
|
||
* ========================================================================== */
|
||
|
||
/** 消息方向 */
|
||
export type MessageDirection = 'game_to_host' | 'host_to_game';
|
||
|
||
/** 消息类型全集 */
|
||
export type PostMessageType =
|
||
| 'init' // 宿主→游戏：初始化参数
|
||
| 'lifecycle' // 游戏→宿主：生命周期事件
|
||
| 'telemetry' // 游戏→宿主：遥测事件转发
|
||
| 'error' // 游戏→宿主：错误上报
|
||
| 'ad' // 双向：广告请求/结果（广告在 iframe 外宿主侧渲染）
|
||
| 'pay' // 双向：支付请求/结果
|
||
| 'social' // 双向：分享等
|
||
| 'storage'; // 双向：键值存储
|
||
|
||
/** postMessage 信封 */
|
||
export interface PostMessageEnvelope<T = unknown> {
|
||
/** 固定标识，宿主据此过滤非本协议消息 */
|
||
channel: 'huijing-game-sdk';
|
||
type: PostMessageType;
|
||
direction: MessageDirection;
|
||
/** 请求/响应配对 ID（ad/pay 等需回调的消息） */
|
||
requestId?: string;
|
||
traceId: string;
|
||
payload: T;
|
||
}
|