微信小游戏直播连麦PK接入
概述
将微信官方直播连麦PK组件（MiniGameCommon 插件的 liveBattle RankManager）接入小游戏：主播与观众连麦挑战同游戏同关卡，游戏复用已有单机关卡即可，无需自建房间对局玩法。核心架构原则：微信小游戏专属能力必须落在微信适配层，游戏业务代码通过事件/回调弱耦合适配层，不直接依赖 wx 与插件 API，避免影响多平台发布。
官方资料：
- 能力介绍：https://developers.weixin.qq.com/minigame/dev/guide/open-ability/channels-event.html
- 关卡配置入口：小游戏 MP 端，游戏能力地图 > 小游戏直播 > 直播PK玩法
第一步：确认信息，不确定先追问（不要急着开发）
开始编码前逐项确认，任何一项不明确时先向开发者追问，不要擅自假设：
- MP端玩法配置：开发者是否已在小游戏 MP 端配置玩法？索取
scoreKey、subScoreKey列表、分数结算模式（比分/时间/枚举 + 权重）、排序（升序/降序）。
- 已提供 → 严格按开发者提供的配置开发。
- 未提供 → 根据实际业务先定义scoreKey/subScoreKey（写入适配层常量并注明"待与 MP 端配置对齐"），开发测试阶段使用 mock（见第四步），且必须在回复中明确告知开发者当前使用了 mock 逻辑；完成开发后务必提醒开发者前往 MP 端配置玩法与关卡、提供真实的 scoreKey/subScoreKey，接入真实关卡数据后方可上线。 - 项目结构与引擎：游戏引擎（Cocos Creator / Laya / 原生等）、微信适配层位置（如
platform/wx、adapter/wechat目录）、业务事件机制（事件总线/回调）。适配层代码只落在微信专属目录。 - 房间逻辑：游戏是否已有房间/对局系统需要用
roomId关联？没有则跳过 roomId 相关业务对接（适配层仍记录 roomId）。
硬性规则（必须遵守，违反会导致PK不可用）
battleInstance创建与onChallengeStart监听必须在游戏初始化完成后立即执行，无任何前置条件。小游戏分冷启动与热启动：用户可能先常规方式（下拉/搜一搜）冷启动游戏，再经直播PK热启动进入；有前置逻辑会导致官方PK半屏逻辑无法触发。GameGlobal.miniGameCommon.getRankManager({ type: 'liveBattle' })返回空 = 微信版本过低或能力未放开，必须优雅降级，不得报错阻断游戏主流程。onChallengeStart的 payload（{ stageName, scoreKey, subScoreKey, roomId }）是进入关卡的唯一依据：用scoreKey（玩法）+subScoreKey（关卡）映射到游戏关卡，不要硬编码假定固定值。
接入流程
- 插件接入：game.json 声明 MiniGameCommon 插件，游戏启动时初始化插件实例挂到
GameGlobal.miniGameCommon。完整代码见references/api.md。 - 适配层实现：以
assets/templates/live-battle-adapter.js为模板，在项目微信适配层实现：
-init()内无前置条件创建battleInstance并绑定onChallengeStart，payload 通过事件/回调派发给业务层；
-wx.onShow中解析wxgame_live_battle_data提取roomId，仅当 roomId 存在时更新（每次接通连麦 roomId 都不同）；
- 暴露reportScore(score)供业务层对局结束时调用（内部调battleInstance.update）。 - 业务层对接：业务代码监听适配层派发的挑战开始事件，按
scoreKey + subScoreKey进入对应关卡（可复用现有关卡，无需单独做直播关卡）；对局结束调用reportScore(score)，score为 number。 - mock 测试（scoreKey/subScoreKey 未确定或无法真机PK时）：使用
assets/templates/live-battle-mock.js：
- 全局开关字段（GameGlobal.__LIVE_BATTLE_MOCK__）控制，默认关闭；
-setTimeout模拟触发onChallengeStartpayload 走完整业务链路；
- mock 逻辑独立成文件，上线前整体删除（删文件 + 删适配层中的引用 + 删开关）；
- 当前使用 mock 时，必须在回复中明确告知开发者；
- 完成开发后务必提醒开发者：前往 MP 端（游戏能力地图 > 小游戏直播 > 直播PK玩法）配置玩法与关卡，提供真实的 scoreKey/subScoreKey 后替换 mock 数据、接入真实关卡。 - 自检：对照
references/checklist.md逐项自测，全部通过才算接入完成。
分数结算模式速览
scoreKey 一般为玩法名称 id，玩法 id 在 MP 端绑定分数结算模式，update 上传分数后平台组件按规则判定胜负：比分模式 / 时间模式 / 枚举模式（MP 端为每个枚举值配置不同权重），三种模式均可设升序或降序。subScoreKey 为关卡标识（MP 端为每个关卡单独配置的一个整数），一种玩法可创建多个关卡；关卡名是 payload 中的 stageName，一般为中文等对外友好文案，组件半屏内展示使用。详见 references/score-config.md。
参考资料索引（按需加载）
references/api.md— 插件声明/初始化、onChallengeStart、update、wx.onShow提取 roomId 的完整 API 与代码references/score-config.md— scoreKey/subScoreKey 语义、三种结算模式、MP 端配置方法与玩法测试通过流程references/checklist.md— 自检清单：重开一局、三种对局状态下的 onChallengeStart、冷/热启动、换对手重连 roomId 变更references/qa.md— 常见 QA（stageName 含义、MP 战绩类型填写、玩法id拉取为空、关卡数量限制、多关卡配置、玩家卡住、主播/观众链接用法）assets/templates/live-battle-adapter.js— 微信适配层模板（弱耦合事件派发 + roomId + 能力降级 + mock 钩子）assets/templates/live-battle-mock.js— mock 模板（全局开关控制，可整体删除）
