# 帧同步游戏服务

帧同步游戏服务是 游戏服务 其中一项，适用多人实时对战游戏使用。

# 游戏流程

# 前端创建房间

# 后台创建房间

# 游戏过程

# 开发

# 配置

game.json 需要配置帧同步相关参数，具体字段名和含义如下：

# 前端接口

# 初始化

所有接口和事件都通过 wx.getGameServerManager 返回的 GameServerManager 对象调用。获取到该对象之后，首先要调用 GameServerManager.login 建立和服务器的连接，连接成功后，才能调用后续的 GameServerManager.createRoom、GameServerManager.joinRoom 等接口。

# 断线重连

房间服务和游戏服务是两条不同连接，游戏开始之前，只需要关注房间服务。收到 GameServerManager.onLogout 事件之后，需要自行选择合适的时机调用 GameServerManager.login 重连回服务器。游戏开始之后，需要关注游戏服务的连接，收到 GameServerManager.onDisconnect 事件之后，需要自行选择合适的时机调用 GameServerManager.reconnect 重连服务器。

如果小游戏发生了重启，需要自行选择合适的时机按顺序调用 GameServerManager.login 和 GameServerManager.reconnect 进行重连。

# 补帧

游戏已开始的情况下，发生断线重连后，会在重连的回调收到当前最大帧号 maxFrameId，并通过 onSyncFrame 补回丢失的帧。没有提供主动补帧接口。

# 示例小游戏

https://github.com/wechat-miniprogram/minigame-lockstep-demo

# 后台接口

第三方后台可以通过https调用帧同步相关后台接口。

# 后台创建游戏房间

如果已经通过匹配或者其他方式已经组好对局，后台可以通过https直接创建帧同步游戏房间。

后续各个玩家在前端调用GameServerManager.joinRoom加入房间，GameServerManager.startGame开始游戏。根据在创建房间时传入的start_percent参数，达到相应人数的玩家调用GameServerManager.startGame接口后，即可进入帧同步流程。

# 分片拉取对局游戏帧

游戏结束后，第三方后台可以游戏对局时同步的游戏帧，用于数据校验和对局回放等功能。

还可以通过传入游戏帧序号的返回拉取固定区间的游戏帧。

# 获取游戏房间信息

同样的可以拉取当前房间的信息，查看当前房间和其中各个玩家的状态。

# 获取对局玩家位次信息

在玩家加入房间(调用GameServerManager.joinRoom)后，会分配唯一的clientId。通过该接口可以拉取房间中各个玩家的openId和其clientId。

# Q&A

# Q1：调用 GameServerManager.startGame 已返回 errCode:0，但客户端始终收不到 onSyncFrame？

startGame 返回成功只代表本端发起请求被服务器接收，不代表对局真正进入帧同步流程。常见原因：

1. 未达到 start_percent：服务端要等达标人数都各自调用了 startGame 才会开始下发帧。请确认房间内每一个客户端都各自调过 startGame，且都返回 errCode:0。
2. lockStepOptions 配置无效：见 Q1，配置项校验失败时会回退默认值，部分场景下会出现不下发帧。
3. 存在未清理的旧房间：用户上次未正常结束的对局如果未通过 GameServerManager.endGame / GameServerManager.memberLeaveRoom / GameServerManager.ownerLeaveRoom 清理，可能会影响新房间开局。处理方式见 Q5。
4. 真机网络受限：部分网络环境（企业 NAT、IPv6-only 等）会影响 UDP 通道建立，建议切换网络重试。

# Q2：onSyncFrame 中的 frameId 会跳号吗？

正常网络下 frameId 单调递增；断线重连后服务端会通过 onSyncFrame 补发缺失帧，期间客户端可能收到一段连续的旧 frameId，需要按服务端为准推进本地逻辑帧，不要因为本地 frameId 看起来"倒退"就丢弃这些帧——这些正是补帧数据。

# Q3：帧同步常见优化手段

• 缓冲节流：降低上传频次 在帧同步管理器中新增 bufferFrame 缓冲机制，替代直接 uploadFrame： 高频指令加入缓冲队列，按帧率间隔（40ms）批量上传 对同类型指令做去重，同一对象的同类指令只保留最新一条 低频关键指令标记 immediate，优先发送

• 增量同步：只发变化的数据 对象状态同步从"全量同步所有对象"改为"只同步状态有实际变化的对象"，无变化的对象不再纳入上传数据。