微信小游戏直播PK连麦接入

解决什么问题

在微信小游戏上做「主播与观众连麦 PK」时，开发者面临两个现实约束。其一，微信官方直播连麦 PK 组件（MiniGameCommon 插件的 liveBattle RankManager）与微信客户端版本、MP 端玩法配置强绑定，业务代码若直接调用 wx 与插件 API，平台专属逻辑会渗入游戏主流程，多平台发布时难以剥离。其二，组件对接入时机有硬性要求：battleInstance 的创建与 onChallengeStart 监听必须在游戏初始化完成后立即执行、无任何前置条件，否则官方 PK 半屏可能无法触发——用户可能先冷启动游戏，再经直播 PK 热启动进入，前置逻辑会直接卡死这条链路。

这个技能把接入方案固化为一套弱耦合架构：平台能力全部收敛在微信适配层，游戏业务只通过事件/回调与之交互，复用已有单机关卡即可，无需自建房间对局玩法。

核心架构

• 适配层承载微信专属能力：init() 内无前置条件创建 battleInstance 并绑定 onChallengeStart；wx.onShow 中解析 wxgame_live_battle_data 提取 roomId（每次接通连麦 roomId 都不同，仅在存在时更新）；对外暴露 reportScore(score) 供业务层结算。
• 业务层弱耦合：监听挑战开始事件，按 scoreKey + subScoreKey 映射到对应关卡（可复用现有关卡），对局结束调用 reportScore(score) 上传分数。
• 能力降级：getRankManager({ type: 'liveBattle' }) 返回空代表微信版本过低或能力未放开，此时优雅降级，不得报错阻断主流程。

关键步骤与 mock 测试

1. game.json 声明 MiniGameCommon 插件，启动时初始化实例挂到 GameGlobal.miniGameCommon。
2. 以 live-battle-adapter.js 为模板实现适配层；配置未定时用 live-battle-mock.js，以 setTimeout 模拟 onChallengeStart payload，走通完整业务链路。
3. 对照 references/checklist.md 自检：重开一局、三种对局状态下的 onChallengeStart、冷/热启动、换对手重连 roomId 变更。

若 scoreKey/subScoreKey 尚未确定，可以用 mock 顶替开发，但必须在回复中明确告知开发者，并在上线前删除 mock 文件、适配层引用与开关字段。

分数结算与配置前提

scoreKey 对应 MP 端玩法 id，绑定比分、时间或枚举（含逐项权重）三种结算模式之一，可设升序或降序；subScoreKey 是关卡标识（一个整数），一种玩法可建多个关卡；stageName 是 payload 中对外友好的中文关卡名，在组件半屏内展示。全部配置在小游戏 MP 端「游戏能力地图 > 小游戏直播 > 直播PK玩法」完成。

注意点

• onChallengeStart 的 payload 是进入关卡的唯一依据，不要硬编码假定 scoreKey/subScoreKey 的固定值。
• 微信小游戏专属能力只落在微信适配层，这是多平台发布的前提，也是整套架构不可妥协的边界。
• 上线前必须完成 MP 端真实玩法与关卡配置、替换 mock 数据、接入真实关卡，三者缺一不可。