UMassBattleNetworkSubsystem

USubsystem 生命周期入口。预注册全部骨架模板(早于任何端点的快照捕获/应用):debuff(RegisterDebuffSkeletonTemplates)、FX(FxHost/FxHost_CPU/FxEntity)、ProjectileHost、LootHost、ActorHost/SoundHost/AgentHost(均为幂等注册);随后 InitializeSnapshotTcpTransport() 按网络角色初始化 TCP 快照传输。

USubsystem lifecycle entry. Pre-registers all skeleton templates (before any snapshot capture/apply on any peer): debuffs (RegisterDebuffSkeletonTemplates), FX (FxHost/FxHost_CPU/FxEntity), ProjectileHost, LootHost, ActorHost/SoundHost/AgentHost (all idempotent); then InitializeSnapshotTcpTransport() initializes the TCP snapshot transport for the current net role.

USubsystem 生命周期出口:ShutdownSnapshotTcpTransport() 关闭并释放 TCP 传输对象,再调用父类实现。

USubsystem lifecycle exit: ShutdownSnapshotTcpTransport() shuts down and frees the TCP transport object, then calls the parent implementation.

静态访问器:WorldContext 为空或 GetWorld() 为空时返回 nullptr;否则取其 Network 子系统。

Static accessor: returns nullptr when WorldContext is null or GetWorld() is null; otherwise returns the world's Network subsystem.

静态访问器的引用版本:失败即 check 断言崩溃——用于「子系统必须存在」的不变式场景。

Reference version of the static accessor: fails via check assertion — for invariant paths where the subsystem must exist.

锁步外守卫:网络模式且当前不在锁步命令执行窗口(!IsInCommandExecution() 且 !IsInSnapshotRestore())时为真。public spawn API 用它区分"确定性命令路径调用"(放行——开发者可把任意函数接到自定义 CommandTag)与"任意帧 BP/C++ 调用"(拦截——会污染全局 UID 游标)。resync 重建窗口(bSnapshotRestoreContext)是刻意例外。

Off-lockstep guard: true when in networked mode and currently OUTSIDE the lockstep command-execution window (!IsInCommandExecution() and !IsInSnapshotRestore()). Public spawn APIs use it to separate deterministic command-path calls (allowed — developers wire arbitrary functions to their own CommandTags) from arbitrary-frame BP/C++ calls (blocked — would pollute the global UID cursor). The resync restore window (bSnapshotRestoreContext) is an intentional exception.

入队一条网络指令(客户端输入转发、服务器汇聚、GameState 补发等入口)。按 MakeExecutedNetCommandKey(PlayerIndex/ExecuteTick/CommandTag/ServerExecSequence 的 CityHash64 组合)去重——已执行过的 key 或已在 pending 中的同 key 指令直接丢弃;随后按 (ExecuteTick 升序,同 tick 按 ServerExecSequence 升序) 有序插入,保证确定性执行顺序;同时追加进 ReceivedCommands 历史(供本地恢复 gap 填充)。

Enqueues a network command (client input forwarding, server convergence, GameState replay, etc.). Deduplicates by MakeExecutedNetCommandKey (CityHash64 over PlayerIndex/ExecuteTick/CommandTag/ServerExecSequence) — keys already executed or already pending are dropped; then inserts in order (ExecuteTick ascending, ServerExecSequence ascending within a tick) for a deterministic execution order; also appends to the ReceivedCommands history (for local-recovery gap filling).

取回本 tick 到期的全部指令(由 UMassBattleSubsystem::Tick 锁步命令执行循环调用,置于 bInCommandExecution 窗口内)。含三个行为:① 每 1024 tick 执行一次账本裁剪(ExecutedCommandKeyToTick 与 ReceivedCommands 丢弃超过 2048 tick 的旧条目,防止无界增长);② 零容忍迟到策略——任何 ExecuteTick < CurrentTick 的指令一律无差别跳过并置 bOutHadLateCommands(无 tag 特权、无例外):迟到即失步,调用方必须转入失步恢复;绝不允许补放到更晚的 tick——延迟施加会与服务器在原 tick 的执行静默发散(旧签名"无故失步、local 恢复能修好"即由此而来);③ 已执行 key 跳过,未执行 key 记录后加入返回数组。注:旧的 bTolerateLate 容忍参数(PauseForServerToCatchUp 恢复路径补放迟到指令)已在 1.19.20 移除。

Dequeues all commands due for the current tick (called by the lockstep command-execution loop in UMassBattleSubsystem::Tick, inside the bInCommandExecution window). Three behaviors: ① ledger pruning every 1024 ticks (ExecutedCommandKeyToTick and ReceivedCommands drop entries older than 2048 ticks to bound growth); ② zero-tolerance late policy — any command with ExecuteTick < CurrentTick is skipped uniformly and flags bOutHadLateCommands (no tag privilege, no exceptions): late = desync, and the caller MUST route to desync recovery; never replay at a later tick — deferred application silently diverges from the server's execution at the original tick (source of the old "causeless desync, local resync fixes it" signature); ③ already-executed keys are skipped, new keys are recorded and added to the result. Note: the old bTolerateLate parameter (replaying late commands on the PauseForServerToCatchUp resume path) was removed in 1.19.20.

从 ReceivedCommands 历史拷贝半开区间 [MinExecuteTick, MaxExecuteTick) 的指令——本地恢复(TryLocalSnapshotRecovery/ProcessDeferredSnapshot 的 GapCommands 补全)、晚加入与 resync gap 填充的消费者。

Copies commands in the half-open range [MinExecuteTick, MaxExecuteTick) from the ReceivedCommands history — consumed by local recovery (TryLocalSnapshotRecovery/ProcessDeferredSnapshot GapCommands filling), late-join and resync gap fill.

BlockId 分配器(头文件内联):AllocServerBlockId 自 NextServerBlockId 递增(服务器权威,从 1 起);AllocLocalBlockId 自 NextLocalBlockId 递增(客户端上行本地编号,从 1 起)。

BlockId allocators (inline in the header): AllocServerBlockId increments NextServerBlockId (server-authoritative, starts at 1); AllocLocalBlockId increments NextLocalBlockId (client-uplink local numbering, starts at 1).

把收到的(下行或汇聚)数据块按权威 BlockId 存入 ReceivedLockstepDataBlocks,记录执行 tick 与到达墙钟。

Stores a received (downlink or converged) block into ReceivedLockstepDataBlocks by authoritative BlockId, recording the execute tick and arrival wall-clock.

按权威 BlockId 查找已接收数据块。

Finds a received block by authoritative BlockId.

按 [PlayerSlot][LocalBlockId] 查找客户端上行暂存块。

Finds a client-uplink staged block by [PlayerSlot][LocalBlockId].

移除已接收块(ExecuteNetCommand 消费块后由调用方调用)。

Removes a received block (called after ExecuteNetCommand consumes the block).

消费并移除已上传的上行块;该槽位清空后删除槽位映射。

Consumes and removes an uploaded uplink block; removes the slot map once it empties.

暂存等待其 TCP 块的上行引用命令(服务器,High-1 竞态修复)——块比命令先到之外的反向竞态:命令先到则暂存,块到达时汇聚。

Stages an uplink reference command waiting for its TCP block (server, High-1 race fix) — the inverse race where the command arrives before its block: the command is staged and converges on block arrival.

取出并移除暂存命令(块到达汇聚时调用);槽位清空后整槽移除。

Removes and returns a staged command (called at block-arrival convergence); empty slots are removed entirely.

监听服务器主机的"上行"暂存(1.19.20 新增):主机按设计没有客户端 TCP socket(共享服务器模拟),其自动分流路径调用本函数把块直接暂存进已上传缓存——与 TCP 上行回调(OnLockstepDataBlockUploaded)写入同一入口,结构与键完全一致,ConvergeUplinkBlock 像对待远程玩家 TCP 上行一样对待主机。由 AMassBattleNetworkPlayerControllerBase 调用(:80)。

Listen-server HOST "uplink" staging (new in 1.19.20): the host has no client TCP socket by design (it shares the server sim), so its auto-flood path calls this to stage the block directly into the uploaded cache — the same entry the TCP uplink callback (OnLockstepDataBlockUploaded) writes, with identical structure and keying, so ConvergeUplinkBlock treats the host exactly like a remote player's TCP upload. Called by AMassBattleNetworkPlayerControllerBase (:80).

【修复 2026-08-29·块竞态失步】客户端下行块命令的"块未到"暂存等待:UDP 引用命令(引擎复制)与 TCP 数据块(自建传输)是两条独立发送路径,服务器卡顿恢复后两者 flush 顺序无保证——引用命令先到、块未到时,旧代码直接丢弃命令(客户端永久缺失该命令效果,只有服务器快照能修)。现在:暂存命令(对暂存列表按 MakeExecutedNetCommandKey 去重,防重投递产生孪生)+ 由调用方冻结本地 tick 推进,块到达后在同一 tick 号执行——与服务器序列完全一致;超时(10s,如 TCP 断链)才 RecordDesync 并 fail loud。由 AMassBattleNetworkGameStateBase 在块缺失时调用(:574)。与 Uplink 的 ConvergeUplinkBlock stage-&-wait 同款先例。

[FIX 2026-08-29 block-race desync] Client-side stage-and-wait for block commands whose TCP data has not arrived yet: the UDP reference command (engine replication) and the TCP data block (custom transport) are two INDEPENDENT send paths — a server stall recovers them in arbitrary order. When the reference arrives first, the OLD code silently dropped the command (the client permanently missed its effects; only a server snapshot rebuilds it). Now: the command is staged (deduped against the staged list by MakeExecutedNetCommandKey so re-delivery cannot twin) + the caller freezes local tick advancement; the command executes at the SAME tick number once the block lands — identical sequence to the server; only a timeout (10s, e.g. dead TCP) RecordDesyncs, failing loud. Called by AMassBattleNetworkGameStateBase when the block is missing (:574). Mirrors the uplink ConvergeUplinkBlock stage-&-wait.

重试全部暂存块命令:块到达(FindReceivedBlock 命中)→ 在冻结的 tick 号上执行(置 bInCommandExecution 窗口,经 GameState::ExecuteNetCommand + OnNetCommandExecuted 广播)并手动盖已执行键(本路径不经出队);超时(10s)→ RecordDesync 并丢弃命令(fail loud)。仍有暂存时返回 true——调用方据此冻结本地时间线。由 UMassBattleSubsystem::Tick 每帧调用(:1401,与 FlushStagedSpawnCommands 按位或)。

Retries every staged block command: block arrived (FindReceivedBlock hit) → execute at the frozen tick number (inside the bInCommandExecution window, via GameState::ExecuteNetCommand + the OnNetCommandExecuted broadcast) and manually stamp the executed key (this path bypasses the dequeue); timed out (10s) → RecordDesync and drop the command (fail loud). Returns true while any command remains staged — the caller freezes the local timeline on it. Called every frame by UMassBattleSubsystem::Tick (:1401, bitwise-OR'd with FlushStagedSpawnCommands).

【修复 2026-09-07·生成延迟失步】*Component.Spawn / Obstacle.Spawn 命令目标宿主组件未复制时的客户端暂存等待:旧的 DeferOrDropSpawnCommand 路径把 ExecuteTick 每次重试 +3(仅在落后端)——服务器在 tick E 生成、客户端 E+3k 才生成,最新实体两端成员集合错开 3k tick(晚加入排查:恰为最新 8 实体的瞬态全体哈希毛刺,发生在追赶 FF 终点)。现在:暂存命令(同款按 key 去重)+ 冻结本地 tick 推进,组件复制到达后在同一 tick 号执行;超时(10s,如 actor 在途销毁)才 RecordDesync。由 AMassBattleNetworkGameStateBase 在宿主缺失时调用(:634/:700/:750/:955/:968/:980)。

[FIX 2026-09-07 spawn-defer desync] Client-side stage-and-wait for *Component.Spawn / Obstacle.Spawn commands whose target host component has not replicated yet: the OLD defer path (DeferOrDropSpawnCommand) rebased ExecuteTick +3 per retry on the LAGGING peer only — the server spawned at tick E while the client spawned at E+3k, so the newest entities were missing from one peer's per-tick hash for 3k ticks (late-join hunts: exactly the newest 8 uids, transient whole-army hash blips at the chase-FF endpoint). Now: the command is staged (same key dedup) + local tick advancement freezes; it executes at the SAME tick number once the component replicates; only a timeout (10s, e.g. an actor destroyed in flight) RecordDesyncs. Called by AMassBattleNetworkGameStateBase when the host is missing (:634/:700/:750/:955/:968/:980).

重试全部暂存生成命令:宿主组件已复制(FindLockstepHost 命中)→ 在冻结的 tick 号上执行(同块冲刷契约:置 bInCommandExecution、经 GameState::ExecuteNetCommand、手动盖已执行键);超时(10s)→ RecordDesync 并丢弃。仍有暂存时返回 true(调用方冻结本地时间线)。由 UMassBattleSubsystem::Tick 每帧调用(:1401)。

Retries every staged spawn command: host component replicated (FindLockstepHost hit) → execute at the frozen tick number (same contract as the block flush: inside bInCommandExecution, via GameState::ExecuteNetCommand, executed key stamped manually); timed out (10s) → RecordDesync and drop. Returns true while any command remains staged (the caller freezes the local timeline). Called every frame by UMassBattleSubsystem::Tick (:1401).

把未执行的到期命令按序插回队头:出队循环在暂存块命令处中断,同 tick 的后继命令不得先于它执行(服务器序为 (ExecuteTick, ServerExecSequence))——待暂存命令执行后它们重新出队。实现为逆序头部插入(恢复原执行顺序),同时移除各命令的已执行键(出队在调用方执行之前就盖键,带旧键重新出队会被当已执行跳过删除、永不执行)。由 UMassBattleSubsystem::Tick 的暂存等待路径调用(:1457/:1832)。

Puts un-executed due commands back at the queue HEAD (in order): the dequeue loop stops at a staged block command; its successors in the SAME tick must not run before it (server order is (ExecuteTick, ServerExecSequence)) — they re-dequeue after the staged command executes. Implemented as reverse head-insertion (restoring the exact original order), also removing each command's executed-key (the dequeue stamps keys BEFORE the caller executes; a re-dequeued stamped key would be skipped-and-deleted as an already-executed duplicate, never running). Called by the staged-wait path in UMassBattleSubsystem::Tick (:1457/:1832).

丢弃超过 30 秒宽限窗的未消费块(防泄漏;块应在 K-buffer tick 内消费)。对三个 map 统一清理:ReceivedLockstepDataBlocks、UploadedLockstepDataBlocks、PendingBlockCommands;空槽位整槽移除。

Drops unconsumed blocks past the 30-second grace window (anti-leak; blocks should be consumed within K-buffer ticks). Cleans all three maps uniformly: ReceivedLockstepDataBlocks, UploadedLockstepDataBlocks, PendingBlockCommands; empty slots are removed entirely.

把四个 payload 数组(FName/int32/float/uint8)打包为字节 blob,供 TCP 块传输。FName 经 FString 中转——FName 索引是进程内的,不跨机器可移植。顺序:Names → Ints → Floats → Bytes。

Packs the four payload arrays (FName/int32/float/uint8) into a byte blob for TCP block transport. FName round-trips via FString — FName entry indices are per-process and not portable across machines. Order: Names → Ints → Floats → Bytes.

把字节 blob 反解回四个 payload 数组(与 PackLockstepPayload 镜像)。空 blob 或读错误返回 false;FString 转回 FName。

Unpacks a byte blob back into the four payload arrays (mirror of PackLockstepPayload). Returns false on an empty blob or a read error; FStrings convert back to FNames.

序列化负载大小的粗略保守估算(字节):Names.Num() × 16 + Ints.Num() × sizeof(int32) + Floats.Num() × sizeof(float) + Bytes.Num()。用于自动分流阈值比较。

Rough conservative estimate of the serialized payload size (bytes): Names.Num() × 16 + Ints.Num() × sizeof(int32) + Floats.Num() × sizeof(float) + Bytes.Num(). Used for the auto-flood threshold comparison.

读取 CVar MassBattle.AutoFloodSwitchBytes(默认 16384)——超过该阈值的 lockstep 命令从 UDP RPC 切到 TCP 块 + 引用命令;0 = 从不切换(始终 UDP)。

Reads the CVar MassBattle.AutoFloodSwitchBytes (default 16384) — lockstep commands whose payload exceeds the threshold switch from UDP RPC to TCP block + reference command; 0 = never switch (always UDP).

判断是否已缓存最新快照(CachedLatestSnapshot 指针有效且 Entities 非空)。由 AMassBattleNetworkGameModeBase 在发快照前检查。

Checks whether the latest snapshot is cached (the CachedLatestSnapshot pointer is valid and Entities is non-empty). Checked by AMassBattleNetworkGameModeBase before sending a snapshot.

记录一次失步:LastDesyncTick = TickCount,TotalDesyncCount++。由 UMassBattleSubsystem::Tick(服务器端哈希失配)、AMassBattleNetworkGameModeBase(ack 失配/迟到)与 AMassBattleNetworkGameStateBase(延迟失步检查)调用。

Records a desync: LastDesyncTick = TickCount, TotalDesyncCount++. Called by UMassBattleSubsystem::Tick (server-side hash mismatch), AMassBattleNetworkGameModeBase (ack mismatch/late) and AMassBattleNetworkGameStateBase (deferred desync checks).

从 ServerHashHistory 查指定 tick 的服务器哈希。FF 完成块在 EvaluateDeferredDesyncChecks 后紧随读取(当前 tick 条目经严格 < 裁剪存活)。

Looks up the server hash for a tick in ServerHashHistory. Read by the FF-completion block right after EvaluateDeferredDesyncChecks (strict-< trimming keeps the current-tick entry alive).

写入服务器同步状态:更新 ServerTickCount 与 ServerTimeDilation;LastKnownInputBufferMs 仅在输入值 > 0 时更新(保持旧值防抖动)。由 AMassBattleNetworkGameStateBase 在接收服务器同步 tick 时调用。

Writes server sync state: updates ServerTickCount and ServerTimeDilation; LastKnownInputBufferMs updates only when the input is > 0 (keeps the old value to avoid jitter). Called by AMassBattleNetworkGameStateBase when a server sync tick arrives.

组装并缓存最新快照(由 UMassBattleSubsystem::Tick 在 OnTickCompleted 广播前调用)。流程:① EntitySnapshotBuffer.Merge() 合并并行收集的实体快照记录,按 UniqueID 排序保证 payload 顺序确定性;② 盖 TickCount(捕获 tick 末状态)与 ServerHashAtCapture(本端 LastTickHash);③ 采集待执行命令(ExecTick ≥ TickCount)、deferred agent spawn 队列(锁内拷贝,仅网络模板)、UIDOccupiedCount(UID 分配器占用计数指纹)、Agent/HashGrid 随机流、BP 任务记录与任务 ID 计数器、LockstepVarStore(PendingVarStoreSnapshot 移入);④ 存入 ValidatedSnapshots 验证环缓冲(槽 0 永不覆盖);⑤ 事后交叉验证——若 ServerHashHistory 已有同 tick 哈希且与本端一致,补盖章。

Assembles and caches the latest snapshot (called by UMassBattleSubsystem::Tick before the OnTickCompleted broadcast). Flow: ① EntitySnapshotBuffer.Merge() merges the parallel-gathered entity snapshot records, sorted by UniqueID for deterministic payload order; ② stamps TickCount (end-of-tick state) and ServerHashAtCapture (this peer's LastTickHash); ③ captures pending commands (ExecTick ≥ TickCount), the deferred agent spawn queue (copy under lock, networked templates only), UIDOccupiedCount (UID-allocator occupied-count fingerprint), the Agent/HashGrid random streams, BP task records and task-ID counters, and LockstepVarStore (moved from PendingVarStoreSnapshot); ④ stores into the ValidatedSnapshots validation ring buffer (slot 0 never overwritten); ⑤ post-hoc cross-validation — if ServerHashHistory already has the same-tick hash matching the local one, the snapshot is stamped.

【2026-08-30 性能·v2】把被替换的快照记录(数万~十几万 per-fragment blob TArray,如 7000 实体 ≈ 17.5 万次 heap free)整批移交后台任务析构——纯 POD/数组、无 UObject,默认分配器线程安全。历史:一次性串行析构曾是每 NetworkFlushIntervalTicks tick 一次 10-30ms 卡顿(落在 NetworkProcessor 与 TickCpuInterp 之间);v1 分片退休(每帧消化一片 512 条)追不上追加速率(每次捕获 7 千条),队列无界膨胀;v2 改为整批后台析构。由 CacheLatestSnapshot 在替换 CachedLatestSnapshot 与覆写验证环槽位时调用(:1833/:1865)。

[2026-08-30 perf v2] Retires replaced snapshot records (tens of thousands of per-fragment blob TArrays — 175k heap frees at 7k entities) by moving the whole destructor storm onto a background task — POD/arrays only, no UObjects; the default allocator is thread-safe. History: the one-shot serial destructor used to cost a 10-30ms hitch every NetworkFlushIntervalTicks tick (landing between the NetworkProcessor span and TickCpuInterp); the v1 sliced retirement (512 records drained per frame) could never keep up with the append rate (7k records per capture), so the queue grew unbounded; v2 hands the whole batch to the background. Called by CacheLatestSnapshot when replacing CachedLatestSnapshot and overwriting ring slots (:1833/:1865).

用服务器哈希给环缓冲中未验证(ServerHash == 0)的快照盖章:本端哈希与服务器哈希一致即验证通过。由 AMassBattleNetworkGameStateBase 在 MulticastSyncTick 接收路径调用。

Stamps unvalidated (ServerHash == 0) snapshots in the ring buffer with the server hash: a snapshot whose local hash matches the server hash becomes validated. Called by AMassBattleNetworkGameStateBase on the MulticastSyncTick receive path.

排队待应用快照:① 拒绝严格早于上次已成功应用 payload 的快照(PayloadTick < LastAppliedSnapshotPayloadTick)——回滚会致持续 resync 循环;允许相等 PayloadTick 重新应用(上次应用后 FF 发散,给服务器时间拍新快照);② 拒绝早于或等于当前排队中 payload 的快照;③ 通过则存入 PendingSnapshotPayload / PendingSnapshotTargetTick 并置 bPendingSnapshotApply。由客户端 TCP 回调与 TryLocalSnapshotRecovery 调用。

Queues a snapshot for application: ① rejects payloads strictly older than the last successfully applied one (PayloadTick < LastAppliedSnapshotPayloadTick) — rolling back would cause a persistent resync loop; equal PayloadTick is allowed to re-apply (the previous apply may have FF'd with divergence; this gives the server time to capture a newer snapshot); ② rejects payloads older than or equal to the currently queued one; ③ on acceptance stores into PendingSnapshotPayload / PendingSnapshotTargetTick and sets bPendingSnapshotApply. Called by the client TCP callback and TryLocalSnapshotRecovery.

本地快照恢复主路径(server 快照为兜底),每次失步都重试:① 防重入——已有恢复在途(bPendingSnapshotApply/bSnapshotFastForward/bFastForwarding)直接返回 false;② 从验证环缓冲选最新且 ServerHash != 0、tick 龄 ≤ LagResyncThresholdTicks 的快照;③ 拷贝 payload 并从本地命令历史(CopyReceivedCommandsRange)补全 GapCommands(原快照的 GapCommands 只覆盖发送时的跨度);④ QueueSnapshotApply;⑤ 成功则置 bPendingLocalRecovery(来源意图标记)与 bSnapshotFastForward(应用后自动追帧);快照过期(被拒绝)时不锁 bSnapshotFastForward——否则永久为真并屏蔽后续失步恢复。

Primary local-snapshot recovery path (server snapshot is the fallback), retried on every desync: ① re-entrancy guard — returns false when a recovery is already in flight (bPendingSnapshotApply/bSnapshotFastForward/bFastForwarding); ② picks the newest snapshot in the validation ring buffer with ServerHash != 0 and tick age ≤ LagResyncThresholdTicks; ③ copies the payload and fills GapCommands from the local command history (CopyReceivedCommandsRange) — the original GapCommands only covered the span at send time; ④ QueueSnapshotApply; ⑤ on success sets bPendingLocalRecovery (source-intent flag) and bSnapshotFastForward (auto-FF after apply); on a stale (rejected) snapshot it must NOT latch bSnapshotFastForward — otherwise it stays true forever and blocks all future desync recovery.

应用快照载荷——resync 的核心重建。主要阶段:① 重建顺序排序(EntityType 优先级 Agent→Debuff→Projectile/Loot→FxEntity→Host→Obstacle,类型内 UID 升序,索引数组避免深拷贝);② 模板解析——注册表命中,否则按 DA 路径 LoadObject 兜底链(agent → projectile → loot 独立 if 链,晚加入客户端也能 apply),重复 UniqueID 检查(fail loud);③ 清场——HashGrid.ResetOccupiedAgentCells() + DestroyQuery(全部 FNetworkTag 实体),销毁前先释放 UObject 组件(Fx/Actor/Sound 分支防孤儿特效与双份宿主);④ 重建循环——agent 分支从 blob 提取 Team、按模板 SubType 盖章、注入 shared fragment blob、应用 archetype tag 增量、剥离端侧本地渲染 flag(SnapshotStrippedRenderFlagsMask);非 agent 分支走骨架模板 + blob 恢复;两者都 RegisterUIDEntity;⑤ 恢复全局状态——UID 分配器经 ReconcileUIDAllocator 从重建映射收敛(位图不同步,占用计数仅为哈希指纹)、BP 任务 ID 计数器、Agent/HashGrid 随机流、LockstepVarStore;⑥ 命令合并——快照命令 + 握手窗口旧命令(ExecTick > PayloadTick)+ GapCommands,按 (ExecuteTick, ServerExecSequence) 排序,移除 ≤ payload tick 的命令,裁剪执行账本;⑦ 回滚 TickCount 与 SimulationTime(apply 按设计滞后捕获 1 tick,不回滚则客户端绝对时间基线永久领先);⑧ 逐实体 blob 恢复(全部字段策略,含 HandleFixups 解析);⑨ 池回填(ClearPoolArraysForRestore + ReturnPooledXxx 按 (类型,UID) 升序,与服务器 LIFO 弹池一致);⑩ deferred spawn 队列恢复、宿主 bNeedsSpawnRefresh 标记(已生成宿主重发组件 op,不重置 bSpawned 防双消费随机流)、运行时对象指针解析、LaunchGatherer.Reset()、验证环裁剪;⑪ 恢复哈希校验——重折叠全部重建实体与 VarStore,与 ServerHashAtCapture 比对,不匹配 fail loud 拒绝应用。

Applies a snapshot payload — the core rebuild of resync. Main phases: ① rebuild-order sort (EntityType priority Agent→Debuff→Projectile/Loot→FxEntity→Host→Obstacle, UID ascending within a type; index array avoids deep-copying blobs); ② template resolution — registry hit, otherwise a DA-path LoadObject fallback chain (agent → projectile → loot as independent if-chains so late-join clients can still apply), duplicate UniqueIDs fail loud; ③ teardown — HashGrid.ResetOccupiedAgentCells() + a DestroyQuery over all FNetworkTag entities, releasing UObject components first (Fx/Actor/Sound branches prevent orphaned FX and duplicate hosts); ④ rebuild loop — the agent branch extracts Team from the blob, stamps SubType per template, injects shared-fragment blobs, applies archetype tag deltas, and strips peer-local render flags (SnapshotStrippedRenderFlagsMask); the non-agent branch goes through skeleton templates + blob restore; both call RegisterUIDEntity; ⑤ restores global state — the UID allocator converges via ReconcileUIDAllocator from the rebuilt map (bitmap not synced; the occupied count is only a hash fingerprint), BP task-ID counters, Agent/HashGrid random streams, LockstepVarStore; ⑥ command merge — snapshot commands + handshake-window old commands (ExecTick > PayloadTick) + GapCommands, sorted by (ExecuteTick, ServerExecSequence), commands ≤ payload tick removed, execution ledger trimmed; ⑦ rolls back TickCount and SimulationTime (apply lags capture by 1 tick by design; without this the client's absolute-time baseline stays permanently ahead); ⑧ per-entity blob restore (all field policies, including HandleFixup resolution); ⑨ pool push-back (ClearPoolArraysForRestore + ReturnPooledXxx in (type, UID) ascending order, matching the server's UID-sorted LIFO pools); ⑩ deferred-spawn-queue restore, host bNeedsSpawnRefresh marking (only already-spawned hosts re-issue the component op; bSpawned is NOT reset to avoid double-consuming the random stream), runtime object-pointer resolution, LaunchGatherer.Reset(), validation-ring trimming; ⑪ restore-hash validation — re-folds all rebuilt entities and VarStores and compares against ServerHashAtCapture; a mismatch fails loud and rejects the apply.

处理排队的快照应用(由 UMassBattleSubsystem::Tick 在帧末/帧首调用,无 pending 时直接返回)。流程:① 本地恢复专用 apply 滞后补偿——本地恢复在 tick N 捕获 GapCommands=[T0,N) 而 apply 发生在 N+1,期间 dequeue 执行的 ≤ N+1 命令效果会被重建销毁,故在 apply 当刻用 CopyReceivedCommandsRange(PayloadTick, TickCount+1) 重新捕获(+1 因半开区间需含 ==N+1);② ApplyEntitySnapshotPayload 应用,成功则 ResyncGeneration++(渲染身份令牌,使 GPU resync 后跳变插值);③ 清空 pending 状态(防重入);④ 失败 → 向服务器报告失败结果并返回;⑤ 成功后:组件重链(LockstepRegistry 中全部 UMassBattleEntityComponentBase 的 RebindToEntity())、本地视觉宿主重挂(RebindLocalVisualsAfterResync)、BP 任务重建(在 bSnapshotRestoreContext 窗口内,任务工厂放行 IsOffLockstep);⑥ 若指定 TargetTick 则 BeginFastForward,否则只解除归属自己的暂停(epoch 校验);⑦ 向服务器报告成功。

Processes the queued snapshot apply (called by UMassBattleSubsystem::Tick; returns immediately when nothing is pending). Flow: ① apply-lag compensation for local recovery — TryLocalSnapshotRecovery captured GapCommands=[T0,N) at tick N but apply happens at N+1, and commands with ExecuteTick ≤ N+1 executed in between are destroyed by the rebuild, so it re-captures via CopyReceivedCommandsRange(PayloadTick, TickCount+1) at the actual apply tick (+1 because the half-open range must include ExecuteTick == N+1); ② ApplyEntitySnapshotPayload; on success ResyncGeneration++ (render identity token so the GPU snaps interpolation after resync); ③ clears pending state (re-entrancy safety); ④ on failure — reports the failure to the server and returns; ⑤ on success: component re-link (each UMassBattleEntityComponentBase in LockstepRegistry gets RebindToEntity()), peer-local visual host re-link (RebindLocalVisualsAfterResync), BP task rebuild (inside the bSnapshotRestoreContext window so task factories bypass IsOffLockstep); ⑥ with a TargetTick it calls BeginFastForward, otherwise it only releases a pause it owns (epoch check); ⑦ reports success to the server.

按 fragment 类型名取快照布局(缓存命中直接返回;TotalBlobSize ≤ 0 的缓存视为无效返回 nullptr)。未命中时经注册表宏(MB_SNAP_LAYOUT,拆成 BuildSnapshotLayoutPartA/B 两个静态助手规避 MSVC C4883)构建并缓存。冷路径,由处理器捕获与恢复端共用。

Returns the snapshot layout for a fragment type name (cache hit returns directly; cached layouts with TotalBlobSize ≤ 0 are treated as invalid and return nullptr). On a miss it builds via the registry macros (MB_SNAP_LAYOUT, split into the static helpers BuildSnapshotLayoutPartA/B to stay under MSVC's C4883) and caches. Cold path, shared by the processor capture side and the restore side.

预填全部快照布局(注册表宏遍历普通 + shared fragment 列表)——在所有并行工作之前执行,保证 TMap 指针稳定(无并发插入)。由 MassBattleNetworkProcessor 每帧进入并行段前调用。

Pre-populates all snapshot layouts (registry macros over the normal + shared fragment lists) — runs before any parallel work so TMap pointers stay stable (no concurrent inserts). Called by MassBattleNetworkProcessor before its parallel section each frame.

按 fragment 类型名取哈希布局(缓存命中直接返回;Fields 空的缓存视为无效返回 nullptr)。未命中时经哈希注册表宏构建(MB_HASH_LAYOUT,逐类别列表)并缓存。由处理器 per-entity 折叠与恢复校验共用——两处必须保持同步。

Returns the hash layout for a fragment type name (cache hit returns directly; cached layouts with empty Fields are treated as invalid and return nullptr). On a miss it builds via the hash registry macros (MB_HASH_LAYOUT, per-category lists) and caches. Shared by the processor per-entity fold and the restore validation — both must stay in lockstep.

预填全部哈希布局(处理器循环前;串行循环 + 预建 ⇒ 无并发插入)。由 MassBattleNetworkProcessor 每帧与 PreBuildSnapshotLayoutCache 成对调用。

Pre-populates all hash layouts (before the processor loop; serial loop + prebuild ⇒ no concurrent inserts). Called by MassBattleNetworkProcessor each frame paired with PreBuildSnapshotLayoutCache.

把单个 fragment 的字段按布局逐字段折叠进 64 位哈希(RawBytes 原字节;float 结构规范化;-0.0→0.0;FRandomStream 取 seed;FEntityHandle 折叠目标 UID,经 MB->FindUIDByEntity 且无效 → -1,与 blob 序列化器一致——失效句柄残留映射时折叠残留 UID 会导致恢复端重折叠分叉,resync 卡死)。布局为空时静默返回(防御——注册表为唯一来源不会触发)。

Folds one fragment's fields into the 64-bit hash per layout (RawBytes as raw bytes; float structs canonicalized -0.0→0.0; FRandomStream folds its seed; FEntityHandle folds the target UID via MB->FindUIDByEntity with invalid → -1, matching the blob serializer — a stale handle lingering in the map would fold a stale UID while the blob serializes -1, diverging the restore-side re-fold and sticking resync at PauseForServerSnapshot). Silently returns on a null layout (defensive — the registry is the single source, so this never fires).

从 TickHashHistory 查指定 tick 的本端哈希。由 AMassBattleNetworkGameModeBase 的 ack 校验与 AMassBattleNetworkGameStateBase 的失步检查读取。

Looks up this peer's hash for a tick in TickHashHistory. Read by AMassBattleNetworkGameModeBase ack validation and AMassBattleNetworkGameStateBase desync checks.

开始追帧:目标已 ≤ 当前 tick 时无需追帧——必须清 bSnapshotFastForward(否则永久为真并屏蔽失步恢复;FF 完成清除受 bFastForwarding 门控,而本路径从不设置它)并解除归属自己的暂停。追帧进行中则取更大的目标 tick。首次进入:置 bFastForwarding、记录起止 tick、清零失配计数、保存并临时关闭 MB->bFrameSpreading,并按来源广播事件(本地快照/服务器快照/纯追帧)。

Begins fast-forward: when the target is ≤ the current tick no FF is needed — it MUST clear bSnapshotFastForward (otherwise it stays true forever and blocks desync recovery; the FF-completion clear is gated on bFastForwarding, which this path never sets) and releases the pause it owns. While FF is running it keeps the larger target tick. On first entry: sets bFastForwarding, records start/target ticks, zeroes mismatch counters, saves and temporarily disables MB->bFrameSpreading, and broadcasts the event by source (local snapshot / server snapshot / pure catch-up).

【2026-08-29·追帧中止】拆除进行中的追帧并转入服务器快照恢复,而非硬追数百 tick:追帧落后服务器活前沿超过 FastForwardAbortBehindTicks(如追帧途中本机卡顿掉队)时,倍速硬追要数分钟——中止并请求新快照,重建直接跳到服务器前沿附近,几 tick 即追完;FF 速率低于服务器推进速率(持续卡顿)时尤为重要。镜像追帧完成清理(减去完成广播与 FF tick 哈希校验),随后把暂停交给 EnterDesyncRecovery 由其请求新快照。由 UMassBattleSubsystem::Tick 的追帧块调用(:2020)。

[2026-08-29 FF-abort] Tears down an in-flight fast-forward and enters server-snapshot recovery instead of hard-chasing hundreds of ticks: when the FF falls more than FastForwardAbortBehindTicks behind the LIVE server head (e.g. the client hitched during catch-up), hard-chasing at FF rate takes minutes — abort and request a fresh server snapshot so the rebuild jumps straight to the server head and the fresh FF covers only a few ticks; especially important when the local FF rate trails the server advance (sustained hitch). Mirrors the FF-completion teardown (minus the completion broadcast and the FF-tick hash check), then hands the pause to EnterDesyncRecovery, which requests the fresh snapshot. Called from the fast-forward block of UMassBattleSubsystem::Tick (:2020).

进入硬失步恢复(暂停模拟等待服务器快照):已在恢复中(bSimulationPaused && bHardDesyncDetected)时直接返回;否则置 bHardDesyncDetected、放弃本地路径意图(bPendingLocalRecovery = false,迟到指令直接触发的失步不经本地)、递增 RecoveryEpoch 认领暂停归属、置暂停,并广播 PauseForServerSnapshot 事件。由 UpdateNetworkClientPacing(严重落后)、UMassBattleSubsystem::Tick(客户端哈希失配)与 EvaluateDeferredDesyncChecks 调用。

Enters hard desync recovery (pause the sim waiting for a server snapshot): returns immediately when already in recovery (bSimulationPaused && bHardDesyncDetected); otherwise sets bHardDesyncDetected, abandons the local-path intent (bPendingLocalRecovery = false; late-command-triggered desyncs skip the local path), increments RecoveryEpoch to claim pause ownership, pauses, and broadcasts the PauseForServerSnapshot event. Called by UpdateNetworkClientPacing (severe lag), UMassBattleSubsystem::Tick (client hash mismatch) and EvaluateDeferredDesyncChecks.

注入式手动触发本地快照 resync(无视自然失步检测;测试/调试用,如 BP 调试键或自动失步测试循环)。防重入——已有恢复在途(bPendingSnapshotApply/bSnapshotFastForward/bFastForwarding)时跳过并返回 false;失步暂停中(服务器恢复持有暂停)时跳过并提示改用 TriggerServerResync。随后直接调用 TryLocalSnapshotRecovery。经 UMassBattleFuncLib 暴露给 BP。

Injection-style manual trigger forcing a local-snapshot resync regardless of natural desync detection (testing/debugging, e.g. BP debug keys or the auto-desync test loop). Re-entrancy guard — skips and returns false when a recovery is already in flight (bPendingSnapshotApply/bSnapshotFastForward/bFastForwarding); skips with a hint to use TriggerServerResync while the desync pause is active (the server recovery owns the pause). Then calls TryLocalSnapshotRecovery directly. Exposed to BP via UMassBattleFuncLib.

注入式手动触发服务器快照 resync:无视当前状态强制进入硬失步恢复,刻意绕过 EnterDesyncRecovery 的重入保护(注入工具重复注入必须总是重新触发)。置标志、放弃本地路径、递增 epoch 认领暂停、记录首个请求 tick、广播暂停事件,当帧立即经 AMassBattleNetworkPlayerControllerBase::ServerRequestResync 发送请求(不等恢复分支的节流窗口);无 PC 时放行节流让恢复分支尽快重试。经 UMassBattleFuncLib 暴露给 BP。

Injection-style manual trigger forcing a server-snapshot resync: force-enters hard desync recovery regardless of current state, deliberately bypassing EnterDesyncRecovery's re-entrancy guard (a re-injection must always re-trigger, never no-op). Sets flags, abandons the local path, bumps the epoch to claim the pause, records the first request tick, broadcasts the pause event, and sends the request the same frame via AMassBattleNetworkPlayerControllerBase::ServerRequestResync (bypassing the recovery-branch throttle window); without a PC it releases the throttle so the recovery branch retries promptly. Exposed to BP via UMassBattleFuncLib.

客户端调速主入口(由 UMassBattleSubsystem::Tick 与 AMassBattleNetworkGameStateBase 调用):非网络模式/非客户端/ServerTickCount ≤ 0 时重置 delta 与比率并读 ping 后返回。否则按 ClientServerTickDelta = TickCount - ServerTickCount 分档:K = ceil(输入缓冲/每 tick 毫秒):① 追帧中 → 保持目标 ≥ 服务器 tick,比率 1;② 落后 ≥ 3K 且 ≥ LagResyncThresholdTicks(严重落后)→ 直接走服务器快照恢复(EnterDesyncRecovery),从陈旧本地状态纯 FF 几乎必然失步;冷却期内则暂停但不请求,冷却结束才进入硬失步;③ 落后但 < 3K(一般落后)→ 纯 FF(BeginFastForward(ServerTickCount)),无需快照;④ 落后 0..3K 之间 → 按比例加速到 MaxNetworkTickSpeedRatio;⑤ 领先 0..K → 强力减速 lerp 到 0.3;⑥ 领先 ≥ K → 比率 0(停摆);⑦ 对齐 → 1。仅在对齐或领先时乘以 ServerTimeDilation(落后的客户端保持完整追赶倍率)。MulticastSyncTick 是客户端 ServerTickCount 的唯一来源——缺失则调速完全失效。

Client pacing main entry (called by UMassBattleSubsystem::Tick and AMassBattleNetworkGameStateBase): on non-networked/non-client/ServerTickCount ≤ 0 it resets the delta and ratio, reads the ping, and returns. Otherwise it bands by ClientServerTickDelta = TickCount - ServerTickCount, with K = ceil(input-buffer ms / ms-per-tick): ① fast-forwarding → keeps the target ≥ server tick, ratio 1; ② behind ≥ 3K and ≥ LagResyncThresholdTicks (severe lag) → straight to server-snapshot recovery (EnterDesyncRecovery); pure FF from a stale local state almost certainly desyncs at every step; during the resync cooldown it pauses without requesting, entering hard desync only when the cooldown expires; ③ behind but < 3K (moderate lag) → pure FF (BeginFastForward(ServerTickCount)), no snapshot needed; ④ behind by 0..3K → accelerates by lerp up to MaxNetworkTickSpeedRatio; ⑤ ahead by 0..K → aggressive deceleration lerp to 0.3; ⑥ ahead ≥ K → ratio 0 (stall); ⑦ aligned → 1. ServerTimeDilation applies only when aligned or ahead (behind clients keep the full catch-up ratio). MulticastSyncTick is the only source of the client's ServerTickCount — without it pacing is dead.

幂等注册快照模板:模板无效返回 NAME_None;确保 FNetworking.Key 存在(为空则自动生成 Template_N 并跳过已占 Key);Key 已注册则返回已有注册(幂等);否则无条件加 FNetworkTag(每个注册模板都参与锁步)后存入注册表并返回 Key。调用方:模板工厂(MakeAgentTemplateDataFromDataAsset / MakeLootTemplateFromDataAsset / MakeProjectileTemplateFromDataAsset)、骨架模板注册(Host/Debuff 子系统)与 UMassBattleFuncLib 的 BP 包装。

Idempotently registers a snapshot template: invalid templates return NAME_None; ensures FNetworking.Key exists (auto-generates Template_N when empty, skipping taken keys); an already-registered key returns the existing registration (idempotent); otherwise it unconditionally adds FNetworkTag (every registered template participates in lockstep), stores the template, and returns the key. Callers: the template factories (MakeAgentTemplateDataFromDataAsset / MakeLootTemplateFromDataAsset / MakeProjectileTemplateFromDataAsset), skeleton-template registrations (Host/Debuff subsystems) and the UMassBattleFuncLib BP wrapper.

带显式 Key 的重载(Blueprint 友好):Key 非空且模板有效时,把 Key 写入模板副本的 FNetworking.Key 后委托 3 参数版;否则直接委托 3 参数版(自动 Key 或幂等)。

Overload with an explicit key (Blueprint-friendly): when the key is non-empty and the template valid, it stamps the key into the template's FNetworking.Key and delegates to the 3-parameter version; otherwise it delegates directly (auto key or idempotent path).

按 Key 查已注册模板(拷贝返回)。

Looks up a registered template by key (returned by copy).

从注册表移除指定 Key 的模板。

Removes the template for the given key from the registry.

把流场 FieldName 的最新导出基底字节写入 CachedFlowFieldSubstrates(同键覆盖)。由 AMassBattleNetworkGameModeBase 在导出/广播基底时调用(:1625/:1642,注释标明"晚加入补发源")。

Stores the latest exported substrate bytes of flow field FieldName into CachedFlowFieldSubstrates (same-key overwrite). Called by AMassBattleNetworkGameModeBase when exporting/broadcasting a substrate (:1625/:1642, marked "late-join re-delivery source").

只读访问全部已缓存基底。消费方:AMassBattleNetworkGameModeBase 的晚加入补发/重播路径(:1117/:1229/:1592/:1680-1686)与 AMassBattleNetworkGameStateBase 的 gap 命令基底回退查找(:563)。

Read-only access to all cached substrates. Consumers: the late-join re-delivery/replay paths of AMassBattleNetworkGameModeBase (:1117/:1229/:1592/:1680-1686) and the gap-command substrate fallback lookup in AMassBattleNetworkGameStateBase (:563).

失步诊断日志(仅 WITH_EDITOR 编译):打印 Agent 总数、TickCount、SimulationTime 与哈希网格前 20 个 agent 的位置/速度/质量,供双端日志 diff。经 UMassBattleFuncLib 暴露。

Desync diagnostic logging (compiled only under WITH_EDITOR): prints the agent count, TickCount, SimulationTime and the first 20 agents' position/velocity/mass from the hash grid for cross-peer log diffing. Exposed via UMassBattleFuncLib.

按 PlayerId 从 GameState 的 PlayerArray 查客户端延迟(毫秒)。

Looks up a client's latency in milliseconds by PlayerId from the GameState's PlayerArray.

组装网络统计:CommandQueueDepth(pending 指令数)、LastTickHash(TickHashHistory 中最大 tick 的哈希)、TotalDesyncs、LastSnapshotSizeBytes = 0(按需 resync,无定期快照)、bIsFastForwarding,并从 PlayerArray 收集各玩家 ping。经 UMassBattleFuncLib 暴露给 BP。

Assembles network stats: CommandQueueDepth (pending command count), LastTickHash (hash of the max tick in TickHashHistory), TotalDesyncs, LastSnapshotSizeBytes = 0 (on-demand resync — no periodic snapshot), bIsFastForwarding, plus per-player pings from the PlayerArray. Exposed to BP via UMassBattleFuncLib.

按实体句柄查 UID(MB->FindUIDByEntity 包装)。

Looks up the UID of an entity handle (wrapper over MB->FindUIDByEntity).

按 UID 查实体句柄(MB->FindEntityByUID 包装);命中还需 IsValid 确认。

Looks up an entity handle by UID (wrapper over MB->FindEntityByUID); a hit additionally requires IsValid.

判断玩家是否已完全加入:不在 late-join 队列、不在 resync 挂起集,且已绑定角色(FindPlayerCharacter 命中)。

Checks whether a player has fully joined: not in the late-join queue, not in the pending-resync set, and has a bound character (FindPlayerCharacter hit).

计算"当前 tick + K"(K = ceil(服务器动态输入缓冲 / 每 tick 毫秒))——服务器为客户端指定命令的目标执行 tick。无 GameMode 时返回 0。

Computes "current tick + K" (K = ceil(server dynamic input buffer / ms per tick)) — the server-side target execute tick for client commands. Returns 0 without a GameMode.

批量 UID → 句柄解析(逐项 LookupEntityByUniqueID)。不可解析的 ID 输出无效句柄占位,结果长度与输入对齐。

Batch UID → handle resolution (per-item LookupEntityByUniqueID). Unresolvable IDs become invalid-handle placeholders so the result stays length-aligned with the input.

UID → 实体句柄,委派 UMassBattleSubsystem::FindEntityByUID;主模拟子系统缺失时返回无效句柄。

UID → entity handle, delegated to UMassBattleSubsystem::FindEntityByUID; returns an invalid handle when the main sim subsystem is missing.

实体句柄 → UID,委派 UMassBattleSubsystem::FindUIDByEntity;主模拟子系统缺失时返回 -1。

Entity handle → UID, delegated to UMassBattleSubsystem::FindUIDByEntity; returns -1 when the main sim subsystem is missing.

把宿主(组件/actor)登记进 LockstepNetID → 宿主映射。由组件在 ID 分配(服务器)或 OnRep(客户端)时调用;ID ≥ 0 且宿主非空才写入。

Registers a host (component/actor) into the LockstepNetID → host map. Called by the component on ID assignment (server) or OnRep (client); only writes when the ID ≥ 0 and the host is non-null.

从宿主映射移除 LockstepNetID(组件销毁路径)。ID ≥ 0 才移除。

Removes a LockstepNetID from the host map (component teardown path). Only removes when the ID ≥ 0.

按 LockstepNetID 找宿主:ID < 0 直接返回 nullptr;弱引用失效(对象已销毁)返回 nullptr。由指令执行分支(GameState::ExecuteNetCommand 定位 Agent/Projectile/Loot 组件)与 UMassBattleFuncLib 使用。

Finds a host by LockstepNetID: IDs < 0 return nullptr immediately; dead weak references (destroyed objects) return nullptr. Used by the command-execution branches (GameState::ExecuteNetCommand locating Agent/Projectile/Loot components) and UMassBattleFuncLib.

服务器权威 LockstepNetID 分配器:FPlatformAtomics::InterlockedIncrement(&NextLockstepNetID)(从 -1 起,首次调用返回 0)。不碰实体 UID 分配(通用实体 UID 由 FEntityUIDAllocator 槽位分配器分配——2026-08-16 取代退役的 NextGlobalUID 计数器)。由 UMassBattleEntityComponentBase 在绑定初始化时调用。

Server-authoritative LockstepNetID allocator: FPlatformAtomics::InterlockedIncrement(&NextLockstepNetID) (starts at -1; the first call returns 0). Does not touch entity-UID allocation (general-entity UIDs come from the FEntityUIDAllocator slot allocator, which replaced the retired NextGlobalUID counter on 2026-08-16). Called by UMassBattleEntityComponentBase during binding initialization.

读取两个执行窗口标志:bInCommandExecution 在 UMassBattleSubsystem::Tick 的锁步命令执行循环周围置位(DequeueNetCommandsForTick → ExecuteNetCommand → OnNetCommandExecuted);bSnapshotRestoreContext 在 ProcessDeferredSnapshot 的任务重建广播周围置位。均仅游戏线程、无原子。

Reads the two execution-window flags: bInCommandExecution is set around the lockstep command-execution loop in UMassBattleSubsystem::Tick (DequeueNetCommandsForTick → ExecuteNetCommand → OnNetCommandExecuted); bSnapshotRestoreContext is set around the task-restore broadcast in ProcessDeferredSnapshot. Both are game-thread-only, no atomics.

注册跨实体句柄修复处理器:HandleFixupAppliers.Add(FragmentTypeName, MoveTemp(Applier))。恢复端 ApplyEntitySnapshotPayload 解析 Payload.HandleFixups 时按 fragment 类型名委托。处理器签名为 TFunction<void(UMassBattleSubsystem&, FEntityHandle, FEntityHandle, const FEntityHandleFixup&)>(类型别名 FHandleFixupApplier)。

Registers a cross-entity handle-fixup applier: HandleFixupAppliers.Add(FragmentTypeName, MoveTemp(Applier)). When the restore side ApplyEntitySnapshotPayload resolves Payload.HandleFixups, it delegates by fragment type name. The applier signature is TFunction<void(UMassBattleSubsystem&, FEntityHandle, FEntityHandle, const FEntityHandleFixup&)> (type alias FHandleFixupApplier).

按当前网络角色初始化 TCP 快照传输(幂等,可安全重复调用)。服务器(监听/专用):已活跃则跳过;存在但不活跃(上次启动失败)先拆除;生成会话令牌(RandRange(100000, 999999));显式端口冲突时回退 OS 分配,自动模式尝试 游戏端口+100..+109 再回退 OS 分配;绑定 OnLockstepDataBlockUploaded(上行块暂存 + 若有暂存命令立即汇聚)。客户端:已存在则跳过;绑定 OnSnapshotBytesReceived(反序列化失败向服务器报告 false,成功则 QueueSnapshotApply)与 OnLockstepDataBlockReceived(下行块缓存)。

Initializes the TCP snapshot transport for the current net role (idempotent, safe to call repeatedly). Server (listen/dedicated): skips when already active; tears down first when existing but inactive (a failed previous start); generates a session token (RandRange(100000, 999999)); falls back to an OS-assigned port on explicit-port conflict, and tries game-port +100..+109 in auto mode before the OS fallback; binds OnLockstepDataBlockUploaded (stages uplink blocks, converges a staged command immediately when one is waiting). Client: skips when it already exists; binds OnSnapshotBytesReceived (reports failure to the server on deserialization errors, otherwise QueueSnapshotApply) and OnLockstepDataBlockReceived (caches downlink blocks).

确保 TCP 传输存在且对当前网络模式活跃:客户端缺失则重试初始化;服务器缺失或不活跃则重试初始化;单机模式(尚未成为服务器/客户端)推迟并返回 false。由 AMassBattleNetworkPlayerControllerBase 与 AMassBattleNetworkGameModeBase 在发送快照/块前调用。

Ensures the TCP transport exists and is active for the current net mode: the client retries init when missing; the server retries when missing or inactive; standalone (not yet a server or client) defers and returns false. Called by AMassBattleNetworkPlayerControllerBase and AMassBattleNetworkGameModeBase before sending snapshots/blocks.

推进 TCP 传输(套接字收发包)并调用 PruneStaleBlocks() 清理超龄块。由 UMassBattleSubsystem::Tick 每逻辑帧调用。

Advances the TCP transport (socket send/receive) and calls PruneStaleBlocks() to drop aged-out blocks. Called every logic frame by UMassBattleSubsystem::Tick.

关闭并释放 TCP 传输对象(置空指针)。

Shuts down and frees the TCP transport object (nulls the pointer).

返回传输实例原始指针(供 GameMode/PlayerController 发送/接收);未初始化时为 nullptr。

Returns the raw transport instance pointer (for GameMode/PlayerController send/receive); nullptr when uninitialized.

按 PlayerId 查找玩家 ACharacter(possess 链推导,无中心映射):先查本地 PC 的 Pawn(PlayerState 匹配),再遍历世界全部 Character 的 PlayerState;PlayerId < 0 或世界缺失返回 nullptr。

Finds a player's ACharacter by PlayerId (possess-chain derived, no central map): first checks the local PC's pawn (PlayerState match), then iterates all Characters in the world by PlayerState; returns nullptr for PlayerId < 0 or a missing world.