# 子游戏 SDK 契约

返回[框架目录](../README.md)。相关：[创建房间](../integration/create-room.md)、[房间设计](../architecture/room-platform.md)。

本页整理当前接口职责，类型名对应工程中的同名契约。具体游戏通过契约接入，不导入平台内部状态实现。

## GameDefinition：子游戏入口定义

必须提供 key、route、config.versionResource、config.assetRoot、createGame(gameId)、chat、roomMenu（mainSceneButton/vipInfinite）、createPageClass、roomViewClass，以及 resources 中的 createRoom/room/roomScene 路径描述。

key 与场景 gameKey 一致。route 遵循协议，gameId 来自 XML。versionResource 精确为 `<gameKey>/version`，assetRoot 是本游戏的 `games/<目录>`。createRoom/room 必须位于本游戏根目录内，加载器从目标 Bundle 自动加载；roomScene 是公共承载场景引用。定义由本游戏 `GameEntry_<gameKey>` 类的 static definition 暴露，公共框架不维护游戏列表。

## GameBinding 与 GameEntry

GameBinding 包含 entry、mount(view)、restoredSnapshot、roomProjection。entry 提供 key/gameId/route、resolveSeatCount(roomtype)、createModule()。

resolveSeatCount 解释服务器实际返回的本游戏配置；不要让平台猜人数。createModule 创建独立房间模块，禁止把上一房间可变状态复用于下一房间。

## GameModule 生命周期

```ts
interface GameModule {
  attach(host: GameHost): void;
  handlePlatformEvent(event: PlatformToGameEvent): void;
  handleGameMessage(message: GameServerMessage): void;
  restore(deskinfo: unknown): void;
  dispose(): void;
}
```

这是核心生命周期摘录。可选 roomProjection 用于向公共房间展示提供游戏投影；没有投影时明确为空。restore 必须按本游戏快照协议恢复，不能将仅缓存对象当作恢复完成。

## RoomCapabilities

通过 requireRoomCapabilities(host) 取得能力；生产宿主缺少能力时显式报错，不退回另一套隐藏实现。

- room.seat：座位映射。
- room.getSnapshot / subscribe：快照与订阅，subscribe 返回退订函数。
- room.prepare / requestExit / applyDissolution：公共房间操作。
- messages.send(rpc, data)：本游戏消息发送，data 遵循 JSON 与真实协议。
- ui.beginLoading()：返回具有 close() 的所有权句柄。
- ui.showBusinessTip(message,time)：玩家业务提示，返回 close() 句柄；不能传入异常或调试字符串。
- ui.requestNumber / requestDigitText / requestMultiplier：异步输入，区分 confirmed 与 cancelled。
- scope.active：会话是否有效。
- scope.defer(cleanup)：会话结束清理；返回函数用于取消该清理注册，不会立即执行 cleanup。

输入取消原因包含 user、scope-ended、replaced。取消不是故障，游戏必须处理取消分支。释放后回调不得继续操作 UI 或发送旧房间消息。

## 创建页面

```ts
interface CreateRoomPageContext {
  readonly previousRoomtype: unknown;
  submit(roomtype: Roomtype): void;
  cancel(): void;
  reportError(message: string): void;
}
interface CreateRoomPagePort {
  open(context: CreateRoomPageContext): void;
  setBusy(busy: boolean): void;
  close(): void;
}
```

Cocos 页面继承 CreateRoomPage 并挂在 prefab 根节点。previousRoomtype 为 null 时，子游戏来源可定义首次默认值；已有无效数据不能静默重置。reportError 当前用于诊断，不显示玩家提示。详细实现步骤见[创建房间接入](../integration/create-room.md)。

## 聊天、视图与释放

每款游戏提供自己的 RoomChatConfig，常用语和历史通过动态列表展示，不根据另一款游戏的固定数量写框架分支。

RoomPresentation.render 接收平台快照、公共操作与可选游戏投影；close 释放展示状态。房间视图匹配注册的 roomViewClass。组件、定时器、事件和订阅都要在页面关闭、房间结束或节点销毁后解除。