网络同步使用指南 Network Sync Guide

MassBattle 的网络同步采用确定性锁步（deterministic lockstep）模型：网络上只传输玩家输入命令和每 tick 的状态哈希，数千甚至上万个单位的位置、血量、行为完全不逐个同步。每台机器（服务器与全部客户端）运行完全相同的模拟代码、以完全相同的顺序吃进相同的命令，从而各自推演出逐位一致（bit-identical）的世界。哈希不一致（desync，失步）时才动用快照（snapshot）重建。带宽只随玩家数增长，与实体数无关。

MassBattle networking uses a deterministic lockstep model: only player input commands and a per-tick state hash travel the wire — positions, health and behavior of thousands of agents are never replicated individually. Every machine (server and all clients) runs the exact same simulation code and consumes the exact same commands in the exact same order, so each derives a bit-identical world. Snapshots are only used when hashes diverge (desync). Bandwidth scales with player count, not entity count.

本页分三部分：① 原理（锁步是什么、K 缓冲、失步检测与恢复、快照系统），配一个可操作的交互式时间线演示；② 使用指南——照着 HordeSurvival 联机演示地图的三个蓝图，从零接入一套完整的联机玩法；③ 调试与硬规则——失步排查工具链与绝不能踩的雷。

This page has three parts: ① Principles (what lockstep is, the K-buffer, desync detection & recovery, the snapshot system) with a hands-on interactive timeline demo; ② Usage guide — wire up a complete networked game from zero, following the three blueprints of the HordeSurvival replicated demo map; ③ Debugging & hard rules — the desync forensics toolchain and the pitfalls you must never step on.

下棋类比：两个在不同城市的棋手不下发棋盘照片，只宣布走法。相同的初始棋盘 + 相同的规则 + 相同的走法顺序 ⇒ 棋盘永远一致——根本不需要检查对方的棋盘。MassBattle 把整个战场当作这盘棋：走法就是命令（Command），规则就是确定性模拟。

Chess analogy: two players in different cities exchange moves, not board photos. Identical boards + identical rules + identical move order ⇒ always-identical boards — without ever checking each other's board. MassBattle treats the whole battlefield as that game: moves are Commands, rules are the deterministic simulation.

框架由四层组成。注意 RPC 的放置由引擎规则决定：AGameMode 只在服务器存在，因此下行多播挂在 GameState、上行 Server RPC 挂在 PlayerController——二者两端都有。命令本身是 FMassBattleNetCommand（tag + 四种负载数组 + 调度信息），执行入口统一是 AMassBattleNetworkGameStateBase::ExecuteNetCommand。

The framework has four layers. RPC placement follows engine rules: AGameMode exists only on the server, so downlink multicasts live on GameState and uplink Server RPCs on PlayerController — both exist on every machine. A command is an FMassBattleNetCommand (tag + four payload arrays + scheduling info); the single execution entry is AMassBattleNetworkGameStateBase::ExecuteNetCommand.

RPC 清单（节选，全部可在 GameStateBase / PlayerControllerBase API 页查到）：

RPC roster (excerpt; full list on the GameStateBase / PlayerControllerBase API pages):

下面的演示还原了锁步的完整节奏：客户端 0（上）把输入发给服务器（中），服务器排入 K 缓冲后广播给客户端 0 与客户端 1（下）。可以调大网络延迟或把客户端推到滞后，观察命令迟到（红色 LATE）→ 暂停 → 快照 → 追帧的完整恢复链——这正是 MassBattle 失步恢复的行为模型。

The demo below replays the full lockstep rhythm: Client 0 (top) sends input to the Server (middle), which schedules it through the K-buffer and broadcasts to Client 0 and Client 1 (bottom). Crank up the net delay or push a client behind to watch the complete recovery chain — late command (red LATE) → pause → snapshot → fast-forward — which is exactly how MassBattle desync recovery behaves.

怎么玩：① 点「发送输入」，看黄色输入包上行、服务器排期、紫色广播包下行、两端在自己的 ExecuteTick 上点亮执行标记；② 把延迟调到 300ms 以上再发——广播到达时该 tick 已过，标记变红 LATE，落后端随即进入 🔄 暂停 → 快照 → 6 倍速追帧；③ 用「推到滞后 / 推到超前」直接制造偏差，观察调速带（faster / slower / PAUSED / FAST-FWD）——这就是客户端四档调速的直观版；④ 调小 K 再加大延迟，迟到更容易复现。

How to play: ① Click "Send Input" — watch the yellow input packet go up, the server schedule it, purple broadcasts come down, and both peers light the execute marker at their ExecuteTick. ② Raise the delay past 300ms and send again — the broadcast lands after the tick has passed, the marker turns red LATE, and the lagging peer enters 🔄 pause → snapshot → 6× fast-forward. ③ Use "Push Behind / Push Ahead" to create offset directly and watch the pacing bands (faster / slower / PAUSED / FAST-FWD) — an intuitive view of the four client pacing tiers. ④ Lower K and raise delay to make lateness easier to reproduce.

一条命令从玩家手指出发到全军一致移动的完整旅程（对照当前源码，以演示地图的 Player.DealDmg 为例）：

The full journey of a command from a player's fingertip to an identically-moving army (per current source, using the demo's Player.DealDmg as the example):

1. 玩家蓝图构造命令：0.75s 循环定时器触发 SendLockstepCommandToServer("Player.DealDmg", IntPayload=[AgentUID, 减益类型], FloatPayload=[X, Y, Z])。
2. PlayerController 的 Server_SendNetCommand Server RPC 上行；服务器盖上真实 PlayerIndex 后进入 ReceivePlayerCommand。
3. 三道闸门：命令白名单（服务器权威 tag 一律拒绝，其余必须在 ClientAllowedCommandTags 中）→ 每玩家每 tick 准入配额（默认 16）→ 待广播队列上限（4096）。
4. K 缓冲排程：ExecuteTick = max(服务器tick, 发起tick, 最快客户端ack) + K + ExtraDeferTicks，并在该 tick 下分配递增的 ServerExecSequence；超过 16KB 的负载自动改走 TCP 数据块 + 引用命令。
5. 排序后经 GameState 的 MulticastCommandToClients 可靠多播；服务器自己也入队（EnqueueNetCommand）。
6. 各端按 (ExecuteTick, ServerExecSequence) 插入本地待执行队列；以 (PlayerIndex, ExecuteTick, TagHash, ServerExecSequence) 为键去重，重复投递不会二次执行。
7. 模拟开始前主 Tick 出队到期的命令，交给 GameState::ExecuteNetCommand：内置 tag 走 C++ 分支，其余落到蓝图钩子 ReceiveLockstepCommandFromServer —— 服务器与所有客户端在同一个 ExecuteTick 收到它。
8. 蓝图钩子里执行效果（本例：ApplyRadialDamageAndDebuff 在命令携带的位置放一个 750 半径的范围伤害圈）——各端输入相同、模拟相同，结果逐位一致。
9. 帧末 NetworkProcessor 折叠哈希；服务器广播哈希，客户端比对，形成闭环校验。

1. The player Blueprint builds the command: a 0.75s looping timer fires SendLockstepCommandToServer("Player.DealDmg", IntPayload=[AgentUID, debuffType], FloatPayload=[X, Y, Z]).
2. The PlayerController's Server_SendNetCommand Server RPC uplinks it; the server stamps the real PlayerIndex and enters ReceivePlayerCommand.
3. Three gates: the command whitelist (server-authority tags always denied; everything else must be in ClientAllowedCommandTags) → per-player per-tick admission quota (default 16) → pending-broadcast cap (4096).
4. K-buffer scheduling: ExecuteTick = max(serverTick, issuedTick, fastestClientAck) + K + ExtraDeferTicks with an incrementing ServerExecSequence under that tick; payloads over 16KB auto-switch to a TCP data block + reference command.
5. Sorted and multicast reliably via the GameState's MulticastCommandToClients; the server enqueues locally too (EnqueueNetCommand).
6. Every peer inserts into its local pending queue ordered by (ExecuteTick, ServerExecSequence); dedup keyed by (PlayerIndex, ExecuteTick, TagHash, ServerExecSequence) — re-delivery never double-executes.
7. The main Tick dequeues due commands before simulation and hands them to GameState::ExecuteNetCommand: built-in tags take C++ branches, the rest fall to the Blueprint hook ReceiveLockstepCommandFromServer — server and all clients receive it at the same ExecuteTick.
8. The hook applies the effect (here: ApplyRadialDamageAndDebuff drops a 750-radius damage circle at the command's position) — identical inputs, identical simulation, bit-identical results.
9. At frame end NetworkProcessor folds the hash; the server broadcasts it and clients compare — closing the verification loop.

K 缓冲是一段故意引入的输入延迟（以 tick 计）：命令不立即执行，而是排到未来第 K 个 tick，给网络留出"所有人都能在执行前收到"的时间窗。K 由静态输入缓冲换算：K = ceil(MinInputBufferMs / 每tick毫秒)，默认 150ms（30Hz 下 K=5）。广域网环境请在 GameMode 配置中调大 MinInputBufferMs；生成类命令另有 ExtraSpawnBufferMs（默认 66ms）加码。

The K-buffer is a deliberate input delay measured in ticks: commands execute K ticks in the future, leaving a window in which every peer can receive them before execution. K derives from a static input buffer: K = ceil(MinInputBufferMs / msPerTick), default 150ms (K=5 at 30Hz). For WAN play raise MinInputBufferMs in the GameMode config; spawn commands get an extra ExtraSpawnBufferMs (default 66ms).

根本区别：屏障同步里服务器必须等到所有客户端确认才推进下一 tick——一人卡顿、全体冻结（星际争霸 / 帝国时代的经典手感）。K 缓冲里服务器从不等待：命令提前排期到未来执行，跟不上的端自己失步、自己恢复。

The fundamental difference: under barrier sync the server waits for all clients to ack before advancing a tick — one slow peer freezes everyone (the classic StarCraft / AoE feel). Under the K-buffer the server never waits: commands are scheduled into the future; a peer that can't keep up desyncs and recovers alone.

检测是双侧的。客户端侧：服务器每 flush tick 广播哈希（MulticastDesyncCheck），客户端在本 tick 模拟完成后于确定性 post-tick 边界比对。服务器侧：客户端每次 ack（ServerAckTick）携带本地哈希，服务器对账。两端都有 5 tick 防抖（DesyncConfirmTicks）：瞬态毛刺不升级，真发散只是晚 5 tick 被发现——防抖层是保险，不是"毛刺可容忍"的许可。服务器确认失步后会隔离该客户端（丢弃其上行命令）直到恢复完成。

Detection is two-sided. Client side: the server broadcasts the hash every flush tick (MulticastDesyncCheck); the client compares at the deterministic post-tick boundary after finishing the tick. Server side: every client ack (ServerAckTick) carries the local hash for reconciliation. Both sides apply a 5-tick debounce (DesyncConfirmTicks): transient blips never escalate, real divergence is merely caught 5 ticks later — the debounce is insurance, NOT a license to tolerate blips. On confirmation the server quarantines the client (dropping its uplink commands) until recovery completes.

客户端调速四档（客户端视角 ClientServerTickDelta = 本地tick − 服务器tick，负数为落后）与服务器踢出：

Four client pacing tiers (client view: ClientServerTickDelta = local − server, negative = behind) plus the server kick:

镜像的超前侧：超前 0 ~ K 减速至 0.3×；超前 ≥ K 暂停等服务器（输入天然领先，等一等无害）。踢出基于 ack 停滞而非哈希失配——哈希失配走恢复路径，绝不踢人。

Mirrored leading side: ahead 0 ~ K decelerates to 0.3×; ahead ≥ K pauses waiting for the server (leading on input is harmless). The kick is ack-stall-based, never hash-based — hash mismatch routes into recovery, not kickout.

快照是"把整个世界装进一个载荷"的机制：FEntitySnapshotPayload 携带全部网络实体的记录（模板键 + UID + 类别 + flag + 逐 fragment 的 blob）、挂起命令、gap 命令、延迟生成队列、BP 异步任务记录、LockstepVarStore 变量、随机流、UID 游标，以及流场基底（保证恢复端先有导航基底再模拟任何 tick）。三条设计主线：

A snapshot is "the whole world in one payload": FEntitySnapshotPayload carries every networked entity's record (template key + UID + category + flags + per-fragment blobs), pending commands, gap commands, the deferred-spawn queue, BP async-task records, LockstepVarStore variables, random streams, the UID cursor, and flow-field substrates (so a recovering peer never simulates a tick without its navigation substrate). Three design threads:

模板注册表：每个网络实体都由 SnapshotTemplateRegistry 里的模板重建（键 = DataAsset 路径或合成键）。模板在命令到达时就幂等预注册（不等执行）——这样即使生成命令晚到，快照重建也能自足。蓝图变量同步：任务模板 BP 里声明的普通变量经 LockstepVarStore 自动进哈希与快照，恢复按变量名匹配（BP 增删变量安全）。

Template registry: every networked entity rebuilds from a template in SnapshotTemplateRegistry (key = DataAsset path or a synthetic key). Templates pre-register idempotently at command arrival (not execution) — so snapshot rebuilds are self-sufficient even if the spawn command arrived late. BP variable sync: ordinary variables declared on task-template BPs flow into hash & snapshot via the LockstepVarStore; restore matches by variable name (BP add/remove safe).

引擎可靠 RPC 有 ~64KB bunch 上限且会饱和可靠通道。MassBattle 的方案：SendLockstepCommandToClients / SendLockstepCommandToServer 在负载估算达到 MassBattle.AutoFloodSwitchBytes（CVar，默认 16KB）时自动切换为 TCP 数据块 + 轻量 UDP 引用命令——块先走自建 TCP 通道（压缩 + 双层 CRC + 分块重组），引用命令只带 BlockId 与 CRC，到达时从块缓存解包执行。

Engine reliable RPCs have a ~64KB bunch limit and saturate the reliable channel. MassBattle's answer: when the estimated payload reaches MassBattle.AutoFloodSwitchBytes (CVar, default 16KB), SendLockstepCommandToClients / SendLockstepCommandToServer auto-switch to a TCP data block + lightweight UDP reference command — the block rides the custom TCP channel first (compressed, dual-layer CRC, chunked reassembly); the reference command carries only BlockId + CRC and unwraps from the block cache at execution.

流场基底是这套机制的典型用户：SendLockstepCommandToClients_RebuildFlowField 导出场的量化基底（MB 级），恒走块路径，支持全量 / 差分 / 自动择小（Auto，默认）三种形态；动态 NavMesh 重建完成时自动重导出。全端导入同一份字节后本地跑同一套 A*——引擎 NavMesh 查询链彻底退出锁步路径。

Flow-field substrates are the canonical user of this machinery: SendLockstepCommandToClients_RebuildFlowField exports the field's quantized substrate (MB-scale), always rides the block path, in Full / Incremental / Auto (default) wire forms; dynamic-navmesh rebuilds re-export automatically. Every peer imports the same bytes then runs the same A* locally — the engine navmesh query chain leaves the lockstep path entirely.

客户端上行命令在 ReceivePlayerCommand 唯一收口点执法，默认拒绝（default-deny）：

Client uplink commands are enforced at the single choke point ReceivePlayerCommand, default-deny:

GameState::ExecuteNetCommand 内置处理的命令（游戏自定义 tag 之外的全部）；处理完后无条件转发蓝图钩子 ReceiveLockstepCommandFromServer：

Commands handled natively by GameState::ExecuteNetCommand (everything besides game tags); after the built-in branch the Blueprint hook ReceiveLockstepCommandFromServer always fires:

以下全部取自联机演示地图 GameMap_HordeSurvival_Replicated 的三个蓝图：一个 GameMode、一个 GameState、一个玩家 Character。这是一个"尸潮生存"玩法：玩家被僵尸围攻，随身带 0.75s 一跳的范围伤害光环，服务器持续刷僵尸波次直到 10000 上限。麻雀虽小，覆盖了接入所需的全部模式。

Everything below is taken from the three Blueprints of the networked demo map GameMap_HordeSurvival_Replicated: one GameMode, one GameState, one player Character. It's a horde-survival setup: the player is swarmed by zombies, carries a 0.75s-ticking radial damage aura, and the server keeps spawning waves up to the 10,000 cap. Small, but it covers every pattern you need.

1. 换基类：项目 GameMode 继承 AMassBattleNetworkGameModeBase，GameState 继承 AMassBattleNetworkGameStateBase，PlayerController 继承 AMassBattleNetworkPlayerControllerBase；DefaultPawn 设为携带 UMassBattleAgentComponent 的 Character。GameMode 上 bEnableNetworkSync（默认开）决定会话是否锁步。
2. 配置模拟：GameState BeginPlay 调 Set Sim Config（步长 0.0333、Deterministic=true）与 Set Physics Substeps——两端必须一致。
3. 注册模板：把每个兵种 DataAsset 做成模板、挂上 Navigation（流场）、按确定性 Key 注册进网络模板注册表。
4. 填白名单：把所有客户端可发的命令 tag 填进 GameMode 的 ClientAllowedCommandTags（演示中即 Player.DealDmg）。
5. PIE 双端验证：Play 模式选 2 Player / Net Mode = Listen Server；开着 NetworkDebugWidget 打一局，观察哈希一致与实体数同步。

1. Swap base classes: derive the project GameMode from AMassBattleNetworkGameModeBase, GameState from AMassBattleNetworkGameStateBase, PlayerController from AMassBattleNetworkPlayerControllerBase; set DefaultPawn to a Character carrying UMassBattleAgentComponent. bEnableNetworkSync on the GameMode (default on) decides whether the session is lockstep.
2. Configure the sim: GameState BeginPlay calls Set Sim Config (step 0.0333, Deterministic=true) and Set Physics Substeps — identical on both peers.
3. Register templates: turn each unit DataAsset into a template, attach Navigation (flow field), and register it under a deterministic key.
4. Fill the whitelist: put every client-issuable command tag into the GameMode's ClientAllowedCommandTags (in the demo: Player.DealDmg).
5. Verify in PIE: play as 2 Players / Net Mode = Listen Server; run a session with the NetworkDebugWidget up and watch hashes agree and entity counts track.

GameState 的 BeginPlay 完成四件事：定模拟参数、注册兵种模板、创建调试 UI、延迟 130 tick 后启动刷怪循环。模板注册是关键——所有端都要在命令到达前把模板注册好，键必须一致：

The GameState's BeginPlay does four things: pin sim parameters, register unit templates, create debug UI, and start the wave loop after a 130-tick delay. Template registration is the crux — every peer must register templates under identical keys before commands arrive:

刷怪循环只活在服务器上（Switch Has Authority → Authority 分支），每 5 tick 发一条 AI.Spawn，直到场上 10000 个 agent 为止。命令只携带模板键数组——真正的生成发生在所有端的命令钩子里：

The wave loop lives only on the server (Switch Has Authority → Authority leg), sending one AI.Spawn every 5 ticks until 10,000 agents are alive. The command carries just the template-key array — the actual spawning happens in the command hook on every peer:

玩家 Character 的移动用标准 UE 角色移动（Enhanced Input → Add Movement Input），由引擎复制到服务器。玩家的 Mass agent 则由框架自动桥接：服务器每个网络 flush tick 采样 pawn 上 AgentComponent 的变换（按 K 缓冲做速度外推），广播 AgentComponent.SetAgentTransform，全端把实体吸附到角色位置——Character 走引擎复制、agent 走锁步命令，两条腿各走各的。输入分支的三个守卫值得照抄：

The player Character moves with standard UE character movement (Enhanced Input → Add Movement Input), engine-replicated to the server. The player's Mass agent is bridged automatically by the framework: every network flush tick the server samples the pawn's AgentComponent transform (K-buffer velocity extrapolation) and broadcasts AgentComponent.SetAgentTransform; all peers snap the entity to the character — Character via engine replication, agent via lockstep commands, two legs walking their own roads. The input branch's three guards are worth copying verbatim:

伤害光环是"客户端发起、全端执行"自定义命令的完整范例。发送端在玩家 Character 上（仅本地控制端运行）：0.75 秒循环定时器，每跳把自己的位置、agent UID 和服务器随机掷出的减益类型发上去：

The damage aura is a complete example of a client-originated, all-peers-executed custom command. The sender lives on the player Character (local controller only): a 0.75s looping timer ships the aura position, the agent UID, and the server-rolled debuff type every tick of the timer:

僵尸朝玩家寻路依赖流场，而引擎 NavMesh 查询不是确定性的——所以基底必须同步。GameMode 的 BeginPlay 只做两步：先在服务器上全量重建场，再把基底锁步广播出去：

Zombie pathing toward the player rides a flow field, and engine navmesh queries aren't deterministic — so the substrate must sync. The GameMode's BeginPlay does exactly two things: rebuild the field on the server, then lockstep-broadcast the substrate:

演示在 BeginPlay 里挂了三个 widget：WB_NetworkDebugWidget（网络状态：tick 差、调速比、命令队列深度、哈希、失步计数——来自 GetNetworkStats）、WB_EntityCountAndFPS、WB_GraphicsQuality。联机调试时保持 NetworkDebugWidget 常开，双端 tick 差稳定在 ±K 内、哈希一致即为健康。

The demo mounts three widgets at BeginPlay: WB_NetworkDebugWidget (network state: tick delta, speed ratio, command-queue depth, hashes, desync count — from GetNetworkStats), WB_EntityCountAndFPS, and WB_GraphicsQuality. Keep NetworkDebugWidget up while testing: a healthy session shows both peers' tick delta steady within ±K and matching hashes.

每一条都对应源码里的守卫或惨痛教训（详见技能库 lockstep-lessons）。违反的后果统一是：轻则 checkf 崩溃，重则静默失步——最坏的那种 bug。

Each maps to a guard or a scar in the source (see the lockstep-lessons reference). The penalty for violation is uniform: a checkf crash if you're lucky, silent desync if you're not — the worst kind of bug.