UMassBattleSubsystem

子系统初始化入口。四件事:① 调用 FFix64::InitializeLUT() 初始化定点三角查找表(跨平台确定性数学);② 注册 FCoreDelegates::OnEndFrame / OnBeginFrame 回调——帧控制必须在 Mass 处理图之外运行(同步 EntityManager API 在 IsProcessing() 期间被禁止);③ 禁用 UE 的 per-actor 调试文本上限(默认 128,高实体数下行为标签会静默丢弃);④ 创建并持有全部 13 个处理器实例(SimStages 9 个 + GridUpdateProcessor + NetworkProcessor + 渲染组 2 个),各处理器 CallInitialize 后存入 OwnedProcessors(UPROPERTY GC 根,仅靠 Outer 不够——UE GC 标记父对象时不会自动标记子对象)。

Subsystem initialization. Four jobs: ① FFix64::InitializeLUT() for the fixed-point trig lookup tables (cross-platform deterministic math); ② registers FCoreDelegates::OnEndFrame / OnBeginFrame callbacks — frame control must run outside the Mass processing graph (synchronous EntityManager APIs are forbidden while IsProcessing()); ③ disables UE's per-actor debug-text cap (default 128 — behavior labels get silently dropped at high entity counts); ④ creates and owns all 13 processor instances (9 in SimStages + GridUpdateProcessor + NetworkProcessor + 2 render processors), each CallInitialized and stored in OwnedProcessors (a UPROPERTY GC root — Outer alone is insufficient since UE GC does not auto-mark children).

子系统销毁入口:注销两个帧回调,清空全部子系统缓存指针、事件 gatherer、调试队列、资产注册队列与注册表、渲染器映射,最后 OwnedProcessors.Reset() 释放 13 个处理器实例。

Subsystem teardown: removes both frame callbacks, clears all subsystem cache pointers, event gatherers, debug queues, asset registration queues/maps, renderer maps, and finally OwnedProcessors.Reset() releases the 13 processor instances.

每引擎帧主入口(TG_PostUpdateWork,所有模拟阶段之后)。流程:① 前置子系统有效性校验(9 个子系统任一为空则整帧跳过);② 若 bShouldTickProcessors 且 SimStages 非空——预冲刷命令缓冲、重置 Host 池统计,然后按 6 阶段链逐阶段 RunProcessorsView 派发(每阶段独立 FProcessingContext,作用域退出应用延迟命令),阶段间 ResolvePendingSpawns(),并 EMA 记录整子帧 SimStages 墙钟供 move 分区均衡器;③ Subtick3 维护段(见下);④ 渲染处理器(FxRender/AgentRender)最后运行并打墙钟戳 LastLogicTickWallTime;⑤ HostSub->UpdateHostRenderInterp 与 HostMonoProcessor->TickCpuInterp 每引擎帧运行;⑥ 追帧完成检测——到达 FastForwardTargetTick 时校验 hash、广播 FastForwardCompleted 事件、解除暂停。

Per-engine-frame main entry (runs at TG_PostUpdateWork, after all sim phases). Flow: ① upfront validation — if any of the 9 subsystems is null the whole tick is skipped; ② when bShouldTickProcessors and SimStages is non-empty — pre-flush command buffer, reset Host pool tick stats, then dispatch the 6-stage chain via RunProcessorsView per stage (each stage owns an FProcessingContext whose destructor applies deferred commands), calling ResolvePendingSpawns() between stages, and EMA-record the whole-subtick SimStages wall time for the move partition rebalancer; ③ Subtick3 maintenance block (below); ④ render processors (FxRender/AgentRender) run last and stamp LastLogicTickWallTime; ⑤ HostSub->UpdateHostRenderInterp and HostMonoProcessor->TickCpuInterp run every engine frame; ⑥ fast-forward completion check — at FastForwardTargetTick verifies the hash, broadcasts FastForwardCompleted and releases the pause.

UTickableWorldSubsystem 要求的 profiling 入口,返回本子系统的快速声明 cycle stat。

Profiling entry required by UTickableWorldSubsystem; returns the quick-declared cycle stat for this subsystem.

静态访问器:从任意世界上下文对象解析 UWorld 并取其子系统。空指针提前退出(匹配 UMassAPISubsystem::GetPtr)——避免 PIE 关闭时 BP 异步任务持空 WorldContext 触发无谓的日志噪音。

Static accessor: resolves the UWorld from any world-context object and returns its subsystem. Early-outs on null to match UMassAPISubsystem::GetPtr — avoids noisy log spam at PIE shutdown when BP async tasks hold a null WorldContext.

静态访问器引用版本:取不到即 checkf 断言——用于「子系统必须存在」的不变式场景。

Reference version of the static accessor: checkf assertion when unavailable — for invariant paths where the subsystem must exist.

9 个惰性访问器(同名私有缓存成员)。首次调用时从 GetWorld() 取子系统并写入 CurrentWorld 与对应缓存成员;后续直接命中缓存。Loot 版本例外:仅在取到非空子系统时才写缓存——world 拆除/重连期间子系统集合切换产生的瞬态 null 不得永久毒化缓存,否则后续模板恢复路径永远跳过 loot 分支,客户端卡死 PauseForServerSnapshot。

Nine lazy accessors (each with a private cache member). On first call they fetch the subsystem from GetWorld() and fill CurrentWorld plus the matching cache member; later calls hit the cache. Loot is the exception: the cache is only written when the fetched subsystem is non-null — a transient null (world teardown / subsystem collection mid-swap during rejoin) must not poison the cache permanently, or the template-recovery fallback skips the loot branch and the client sticks at PauseForServerSnapshot.

分配下一个通用实体 UID:EntityUIDAllocator.Allocate() 的薄封装(保留历史 API 名,~30 个调用点零改动)。槽位分配器:2^24 槽占用位图、最小空闲槽、循环利用——上界是同时存在实体数而非累计生成数。仅限游戏线程串行 drain(无锁契约;历史计数器的并行原子递增已随计数器退役)。所有通用实体类型(Agent/Projectile/Loot/Debuff/Host/Fx)共用;障碍物 UID 走 UMassBattleObstSubsystem 的独立槽位空间。

Allocates the next general-entity UID — a thin wrapper over EntityUIDAllocator.Allocate() (the historical API name is kept so ~30 call sites stay untouched). The slot allocator: a 2^24-slot occupancy bitmap, first-free-slot, with recycling — bounded by concurrent entities, never by cumulative spawns. Game-thread serial drain only (lockless contract; the old counter's parallel atomic increment retired with the counter). All general entity types (Agent/Projectile/Loot/Debuff/Host/Fx) share it; obstacle UIDs use UMassBattleObstSubsystem's separate slot space.

UID → 句柄的 O(1) 查找(全局唯一,无需类型参数)。UID < 0 或未注册时返回无效句柄。

O(1) UID → handle lookup (UIDs are globally unique, no type parameter needed). Returns an invalid handle for UID < 0 or unregistered UIDs.

句柄 → UID 的 O(1) 查找。先经 IsValid 前置校验(经 Mass API 子系统),句柄无效或未注册返回 -1。

O(1) handle → UID lookup. Validates the handle first via IsValid (through the Mass API subsystem); returns -1 for invalid or unregistered handles.

hash 折叠路径快速版:跳过 IsValid 前置检查。TMap 键是 (Index, Serial),失效句柄天然 miss;锁步双端句柄有效性一致,折叠保持确定性。

Fast variant for the hash-fold path: skips the IsValid pre-check. Since the TMap key is (Index, Serial), stale handles miss naturally, and lockstep peers agree on handle validity, so the fold stays deterministic.

建立 UID ↔ 句柄双向注册(两个 TMap 各写一条)。UID < 0 时直接返回。由各生成点与快照恢复路径调用(如 MassBattleNetworkProcessor 每 tick 从查询注册、MassBattleAgentSubsystem 生成后注册)。

Registers a UID ↔ handle pair in both directions (one entry in each TMap). Returns immediately when UID < 0. Called from every spawn point and the snapshot-restore path (e.g. MassBattleNetworkProcessor registering from its query each tick, MassBattleAgentSubsystem after spawning).

撤销 UID ↔ 句柄注册。仅在双向值均匹配时才移除(防止旧句柄误删新注册),两条映射分别校验。

Removes a UID ↔ handle registration. Only removes when both directions match (prevents a stale handle from deleting a newer registration); each map is checked separately.

一次性重建全局 UID 映射。映射实际为增量维护(每次生成与快照恢复都写入),此处仅清空两个 TMap。

One-shot rebuild of the global UID maps. The maps are maintained incrementally (written at every spawn and snapshot restore), so this only empties both TMaps.

将 UniqueID 与 ResyncGeneration 混合(UniqueID ^ (Gen << 24)),使每次 resync 后 GPU 身份令牌变化,强制跳变而非从旧占有者数据插值。网络子系统不可用时 Gen 取 0。

Mixes UniqueID with ResyncGeneration (UniqueID ^ (Gen << 24)) so the GPU identity token changes after every resync, forcing a snap instead of interpolating from stale previous-occupant data. Gen is 0 when the network subsystem is unavailable.

BP 异步任务(AgentsMoveTo / AgentsChaseAttack)的注册/注销。注册前先移除同实例与失效弱引用(幂等);以弱引用存储,访问时惰性清理。任务在工厂注册,在 Cleanup/FinishTask/BeginDestroy 注销。

Registration/unregistration for BP async tasks (AgentsMoveTo / AgentsChaseAttack). Register first removes any stale weak refs and duplicates (idempotent); tasks are held as weak references, pruned lazily on access. Tasks register in their factory and unregister in Cleanup/FinishTask/BeginDestroy.

采集全部注册任务为快照记录:Task->CaptureSnapshot 逐任务写入 FAgentTaskSnapshotRecord。仅采集有效(非 pending-kill)任务——幻影记录会使 resync 复活已销毁对象。采集后按 (TaskType → MyTaskID) 确定性排序,双端排序结果一致。由 UMassBattleNetworkSubsystem::CacheLatestSnapshot 调用。

Captures every registered task into snapshot records via Task->CaptureSnapshot. Only valid (non-pending-kill) tasks are captured — a phantom record would make resync resurrect a dead object. Records are then sorted deterministically by (TaskType → MyTaskID) so both peers produce identical ordering. Called from UMassBattleNetworkSubsystem::CacheLatestSnapshot.

resync 恢复窗口内重建全部注册任务(追帧之前)。流程:① 本地数组拷贝有效指针(终止过程会中途改注册表,range-for 会漏);② 按类独立判定成员——(TaskType, MyTaskID) 命中快照记录的任务静默终止(下方重生,OnTaskEnd 是假结束),未命中的残留任务带 OnTaskEnd 终止(服务器在快照点前已结束);③ 逐记录重建:模板(按 Record.TemplateKey 解析)→ Create*TaskFromSnapshot(保留 ID)→ Bind*Task(delegate 重绑)→ Activate;模板解析失败/为空降级为无绑定创建;④ 每个服务于重建任务的模板收到 OnResyncRecovered 通知,未实现钩子的模板打一次性警告;⑤ 全程 bTaskRebuildInProgress = true,期间拒绝 BP 侧任务创建。由 UMassBattleNetworkSubsystem::ProcessDeferredSnapshot 调用。

Rebuilds every registered task from snapshot records (inside the resync restore window, before fast-forward). Flow: ① copies valid pointers to local arrays (termination mutates the registry mid-iteration; a range-for would skip entries); ② per-class membership check — tasks whose (TaskType, MyTaskID) appears in the records are terminated SILENTLY (they respawn below — OnTaskEnd would be a false end); unmatched residuals are terminated WITH OnTaskEnd (the server ended them before the snapshot); ③ rebuilds each record: template (by Record.TemplateKey) → Create*TaskFromSnapshot (ID preserved) → Bind*Task (delegate rebind) → Activate; unresolvable/empty templates degrade to unbound creation; ④ every template that served a rebuilt task gets OnResyncRecovered; templates without the hook get a one-shot warning; ⑤ bTaskRebuildInProgress stays true throughout, rejecting BP-side task creation. Called from UMassBattleNetworkSubsystem::ProcessDeferredSnapshot.

把任务模板 BP 类路径(Key)解析为缓存实例:LoadClass + NewObject(outer = 本子系统,使模板处理器内 GetWorld() 可用)+ 缓存。首次解析后把 Key 插入 SortedTemplateKeys(LexicalLess 插入排序,模板终身注册不删除,缓存序终生有效)。Key 为空或类加载失败返回 nullptr 并打警告。

Resolves a task template BP class path (Key) to a cached instance: LoadClass + NewObject (outer = this subsystem, so GetWorld() works inside template handlers) + cache. On first resolution the Key is insert-sorted into SortedTemplateKeys (templates are registered once and never removed, so the cached order stays valid for the subsystem lifetime). Returns nullptr with a warning for empty keys or failed class loads.

把所有缓存的 LockstepVarStore 实例折叠进哈希 H。迭代 SortedTemplateKeys(注册时插入排序,双端确定性序——TMap 迭代序不确定),无同步变量的模板跳过,每个实例先以模板键字符串作盐(MixBytesInto)再 FoldInto(H)。由 MassBattleNetworkProcessor 与 NetworkSubsystem 在实体折叠同点调用;采集(CaptureVarStoreBlobs)必须同 tick 执行,保证 ServerHashAtCapture 与 payload 一致。

Folds every cached LockstepVarStore instance into the hash H. Iterates SortedTemplateKeys (insert-sorted at registration — a deterministic order across peers; TMap iteration order is not); templates without synced fields contribute zero. Each instance is first salted with its template key string (MixBytesInto), then FoldInto(H). Called by MassBattleNetworkProcessor and NetworkSubsystem at the same point as the per-entity fold; CaptureVarStoreBlobs must run on the same tick so ServerHashAtCapture matches the payload values.

把所有缓存的 LockstepVarStore 实例采集为逐实例快照条目(与折叠相同的确定性键序,采集与折叠在采集 tick 必须逐位一致)。无同步变量的模板跳过。由网络处理器在采集 tick 调用。

Captures every cached LockstepVarStore instance into per-instance snapshot entries (same deterministic key order as the fold — capture and fold must agree bit-for-bit on the captured tick). Templates without synced fields are skipped. Called by the network processor on capture ticks.

IsTaskRebuildInProgress 返回重建标志(重建窗口内 BP 侧任务创建被拒绝,防止仅本端存在的分叉任务);HasAnyRegisteredTasks 返回两个弱引用数组是否有非零条目。

IsTaskRebuildInProgress returns the rebuild flag (BP-side task creation is rejected during the rebuild window to prevent peer-only divergent tasks); HasAnyRegisteredTasks returns whether either weak-reference array is non-empty.

FCoreDelegates::OnBeginFrame 入口(Initialize 注册),在任何 tick 组 / Mass 阶段管理器之前触发——必须在 Mass 处理图之外运行,因为内部调用同步 EntityManager API(AgentSub->ExecuteTick 的 BatchCreateEntities / 锁步生成),这些在 IsProcessing() 期间被禁止。读取 FApp::GetDeltaTime(),按 MassBattle.EnableTimeDilation CVar 决定是否乘世界膨胀,然后调 PreProcessorFrameSetup。

FCoreDelegates::OnBeginFrame entry (registered in Initialize), firing before any tick group / Mass phase manager — it must run outside the Mass processing graph because it calls synchronous EntityManager APIs (BatchCreateEntities via AgentSub->ExecuteTick / lockstep spawns), which are forbidden while IsProcessing(). Reads FApp::GetDeltaTime(), applies world dilation only when the MassBattle.EnableTimeDilation CVar allows, then calls PreProcessorFrameSetup.

每引擎帧先于所有模拟处理器的帧控制入口(原 Tick 顶部逻辑迁移至此)。顺序:① 子系统有效性校验(MA/Net/AgentSub);② 暂停帧刷新 GPU 外推时钟(RefreshPausedRenderClock);③ 网络模式下 Net->TickSnapshotTcpTransport() 接收 TCP 数据;④ 暂停分支——失步恢复(应用延迟快照、冷却到期转硬失步、按冷却窗口 ServerRequestResync、超时升级),硬停帧直接返回;⑤ 主动锁步上限——UpdateNetworkClientPacing,客户端严重超前时挂起等待服务器(补放冻结期间到达的命令、广播 PauseForServerToCatchUp/ResumeAfterServerCatchUp 事件);⑥ 缓存 DeltaTime 与调试相机位置(Simulate 模式编辑器视口优先,回退 PlayerController);⑦ bFrameSpreading 运行时切换检测与状态重置;⑧ 时间步进决策(首帧同步调用,追帧强制逻辑帧);⑨ 子帧激活与 LastSubFrameIndex 记录;⑩ Subtick0 设置——TickCount++、网络锁步下 SimulationTime = TickCount × StepTime 确定性重算、GridUpdateProcessor->RebuildAllGrids 网格重建、广播 MassBattleTick 与 AFlowField::OnSimulationTick、AgentSub->ExecuteTick 同步生成、锁步指令出队(DequeueNetCommandsForTick → ExecuteNetCommand,迟到指令即失步进入恢复);⑪ 置 bIsSimulationTick。

Per-engine-frame frame-control entry that runs before all sim processors (moved from the top of the old Tick). Order: ① subsystem validation (MA/Net/AgentSub); ② paused frames refresh the GPU extrapolation clock (RefreshPausedRenderClock); ③ in networked mode Net->TickSnapshotTcpTransport() receives TCP data; ④ pause branch — desync recovery (apply deferred snapshots, escalate to hard desync after cooldown, ServerRequestResync on the request cooldown, timeout escalation), hard-stopped frames return early; ⑤ proactive lockstep ceiling — UpdateNetworkClientPacing; when the client runs far ahead it suspends waiting for the server (replays commands that arrived while frozen, broadcasts PauseForServerToCatchUp/ResumeAfterServerCatchUp); ⑥ caches DeltaTime and the debug camera location (Simulate-mode editor viewport first, PlayerController fallback); ⑦ runtime-toggle detection and reset for bFrameSpreading; ⑧ time-stepping decision (first frame runs synchronously; fast-forward forces a logic frame every engine frame); ⑨ sub-frame activation and LastSubFrameIndex recording; ⑩ Subtick0 setup — TickCount++, deterministic SimulationTime = TickCount × StepTime rebase under network lockstep, GridUpdateProcessor->RebuildAllGrids grid rebuild, MassBattleTick and AFlowField::OnSimulationTick broadcasts, AgentSub->ExecuteTick synchronous spawns, and lockstep command dequeue (DequeueNetCommandsForTick → ExecuteNetCommand; any late command is a desync entering recovery); ⑪ sets bIsSimulationTick.

非帧分散模式的时间步进决策。暂停时置 bShouldTickProcessors=false 返回。固定步长(或网络锁步客户端):AccumulatedTime += DeltaTime × PacingRatio,达到 EffectiveStepTime 时消费一步并置模拟标志;累计超 StepTime × 2 × 膨胀 的失效保护清零(防止大卡顿后的追帧死循环)。可变步长:每帧都是逻辑帧,CalculatedStepTime = min(DeltaTime, SafeStepTime × 膨胀);网络锁步下强制用 SafeStepTime 作固定步长(不应用膨胀——锁步端必须使用相同步长)。

Time-stepping decision for non-frame-spread mode. Paused sets bShouldTickProcessors=false and returns. Fixed step (or networked lockstep client): AccumulatedTime += DeltaTime × PacingRatio; consuming one step when it reaches EffectiveStepTime; a failsafe resets accumulation above StepTime × 2 × dilation (prevents a catch-up death spiral after huge hitches). Variable step: every frame is a logic frame with CalculatedStepTime = min(DeltaTime, SafeStepTime × dilation); under network lockstep the fixed SafeStepTime is forced regardless of local dilation — lockstep peers must use identical step times.

帧分散模式的时间推进。累计 FrameSpreadAccumulatedTime;逻辑帧进行中则 CurrentSubFrame++,达 COUNT 时结束(置 bHasCompletedLogicFrame)。固定步长下累计达 StepTime 启动新逻辑帧,可变步长下前一逻辑帧完成即启动。不变量:一个逻辑帧严格等于 COUNT 个引擎帧——新帧请求停留在累计器中,当前帧推进完才生效。每引擎帧 ActiveSubFrameMask 只含当前子帧一位;空闲引擎帧掩码为 0(仅渲染插值)。

Time advancement for frame-spread mode. Accumulates FrameSpreadAccumulatedTime; an in-flight logic frame advances CurrentSubFrame++ and ends at COUNT (setting bHasCompletedLogicFrame). Fixed step starts a new logic frame when the accumulator reaches StepTime; variable step starts as soon as the previous frame completes. Invariant: a logic frame is ALWAYS exactly COUNT engine ticks — a due new frame stays parked in the accumulator until the in-flight one finishes. Each engine tick ActiveSubFrameMask holds exactly the current sub-frame bit; idle engine ticks get mask 0 (render interpolation only).

FCoreDelegates::OnEndFrame 回调:为下一帧推进步长,使所有处理器在整帧内看到一致的 bShouldTickProcessors。首帧跳过(防同 DeltaTime 双推进);追帧期间跳过。帧分散:EMA 记录刚执行的子帧墙钟(α=0.25)、每逻辑帧执行 move 分区动态均衡(比较整子帧 SimStages 耗时,Subtick1 含 Behavior/Projectile/Reaction 固定基线,阈值 ±1 且 EMA+边界抑制振荡)、仅渲染帧按平均逻辑子帧时长 FPlatformProcess::Sleep 调步。非帧分散:固定步长下记录逻辑帧墙钟、EMA 估计每逻辑帧渲染数,渲染帧按每渲染预算睡眠使帧时间均匀。

FCoreDelegates::OnEndFrame callback: advances time stepping for the NEXT frame so all processors see the same bShouldTickProcessors throughout the frame. Skipped on the first frame (prevents double-advancing with the same DeltaTime) and during fast-forward. Frame-spread: EMA-records the wall duration of the sub-frame that just ran (α=0.25), runs the dynamic move-partition rebalancer once per logic frame (compares WHOLE-subtick SimStages durations — Subtick1 carries the fixed Behavior/Projectile/Reaction baseline; threshold shifts ±1 with EMA + hysteresis bounds to prevent oscillation), and render-only frames sleep to the average logic sub-frame duration for pacing. Non-frame-spread: fixed step records logic-frame wall time, EMA-estimates renders per logic frame, and render frames sleep to a per-render budget so frame times stay evenly spaced.

暂停帧渲染时钟刷新:暂停期间模拟不推送渲染数组,User.LogicTickTime 冻结而 Niagara SystemAge 持续增长,GPU 帧外推会失控使 VAT 动画继续播放。本函数遍历所有 AgentRenderer 的 spawn 批次,把 Niagara 的 User.LogicTickTime 设为当前世界时间,使外推保持 ≈0,冻结的 CPU 帧值停留在画面上。

Paused-frame render clock refresh: paused frames push no render arrays, so User.LogicTickTime would freeze while the Niagara SystemAge keeps advancing — the GPU frame extrapolation runs away and VAT animations keep playing. This walks every AgentRenderer spawn batch and sets the Niagara User.LogicTickTime to the current world time, keeping the extrapolation ≈0 so the frozen CPU frame values hold on screen.

模拟阶段之间的生成冲刷:先 ProcessAssetRegistrationQueues() 加载新生成配置引用的软资源,再 MA->FlushCommandBuffer() 应用上一阶段入队的延迟 Mass 命令(含 ProcessHostOpsQueues 与非处理器代码的 Defer)。可每帧多次安全调用(各 op 队列段后自重置,Merge 只取增量)。注:宿主 op 队列的实际消费已移至 Subtick3 引擎帧(每逻辑帧一次,所有模拟阶段之后)。

Spawn resolution between sim stages: first ProcessAssetRegistrationQueues() loads soft assets referenced by new spawn configs, then MA->FlushCommandBuffer() applies deferred Mass commands queued during the previous stage (including those from ProcessHostOpsQueues and non-processor code). Safe to call multiple times per frame (each op queue resets after its section; Merge takes only the delta). Note: the actual host-op drain moved to the Subtick3 engine tick (once per logic frame, after every sim stage).

子帧门控:请求开始一个子帧消费。仅当该子帧已调度、等于当前派发子帧、且 (TickCount, Frame, ConsumerName) 键在本 tick 未被消费过时返回 true(每个消费者每 tick 每子帧至多通过一次)。SubFrameGateTick 变化时重置消费集合。

Sub-frame gate: requests to start consuming a sub-frame. Returns true only when the sub-frame is scheduled, matches the currently-dispatching sub-frame, and the (TickCount, Frame, ConsumerName) key has not been consumed this tick (each consumer passes at most once per sub-frame per tick). The consumed set resets whenever SubFrameGateTick changes.

游戏暂停总控(用户暂停):幂等切换 bGamePaused,在边沿广播网络事件——暂停/恢复角色按 NetMode 判定(NM_Client → PauseLocalSim/ResumeLocalSim,其余 → PauseServerSim/ResumeServerSim)。蓝图经 MassBattleFuncLib 调用。

Master game-pause controls (user pause): idempotently toggle bGamePaused and broadcast a network event on the edge — the role is picked by NetMode (NM_Client → PauseLocalSim/ResumeLocalSim, otherwise → PauseServerSim/ResumeServerSim). Blueprint entry via MassBattleFuncLib.

三级暂停查询(内联)。IsUserPaused:仅 bGamePaused。用于网络恢复暂停必须豁免的检查(失步 ack——网络暂停的客户端在恢复中而非卡死)。IsGamePaused:综合暂停——用户暂停、或网络失步暂停(排除追帧,追帧期间模拟实际在推进)、或等待服务器追帧(bPauseWaitServerActive)。IsSimulationPaused:总闸——用户暂停或网络 bSimulationPaused,为真时模拟处理器全部不执行;刻意不含 bPauseWaitServerActive(它经调速追赶路径冻结 tick 推进,不得进入恢复分支)。

Three-level pause query (inline). IsUserPaused: bGamePaused only — for checks that network recovery pauses must be exempt from (desync acking: a network-paused client is recovering, not stuck). IsGamePaused: composite — user pause, or network desync pause (fast-forward excluded — FF actively advances the sim), or the server-catch-up wait (bPauseWaitServerActive). IsSimulationPaused: master gate — user pause or network bSimulationPaused; when true no sim processors execute. Deliberately excludes bPauseWaitServerActive (it freezes tick advancement via the pacing catch-up path and must not enter the recovery branch).

一次性配置模拟参数:固定/可变步长、帧分散、确定性、定点数学。蓝图经 MassBattleFuncLib::SetSimConfig 转发。

Configures simulation parameters in one call: fixed/variable step, frame spreading, determinism, and fixed-point math. Forwarded from MassBattleFuncLib::SetSimConfig for Blueprint.

已弃用(UE_DEPRECATED(5.8, "Use SetSimConfig instead")):旧版四参配置接口,仅改写步长/帧分散/确定性,不含定点数学开关。

Deprecated (UE_DEPRECATED(5.8, "Use SetSimConfig instead")): the old four-parameter config entry; sets step/safe-step/frame-spreading/determinism only, without the fixed-point toggle.

一组只读内联访问器。GetRenderInterpElapsed:自 LastLogicTickWallTime(渲染处理器上次写入 GPU 插值输入的墙钟)以来的秒数,钳制 [0, MaxClamp],驱动 Niagara 预测外推;仅视觉/非确定性,不进模拟哈希。ShouldTickProcessors/GetCalculatedStepTime/GetSimulationTime/GetTickCount:处理器使用的本帧步长与模拟时钟(用 SimulationTime 而非 GetWorld()->GetTimeSeconds() 保证确定性计时)。IsSimulationTick:本引擎帧游戏 tick 是否推进(bIsSimulationTick)——MassEntity 处理器每引擎帧都运行,此标志防止跳过的帧上重复处理同一游戏 tick。IsSubFrameScheduled:查询指定子帧本引擎帧是否调度;非帧分散时等于 bShouldTickProcessors,帧分散时查 ActiveSubFrameMask 位。IsSubFrameActive:兼容查询,与 Scheduled 相同。ShouldDeterministicSort:返回 bDeterministic。GetAgentPhysicsIterations:WIP,恒返回 1。GetGridUpdateProcessor:网络子系统 post-resync 重建用。GetWorldTimeDilation:WorldSettings 有效膨胀,钳制 ≥ 0,用于模拟时长转墙钟(调试绘制等)。

A set of read-only inline accessors. GetRenderInterpElapsed: seconds since LastLogicTickWallTime (when the render processors last wrote GPU interp inputs), clamped to [0, MaxClamp], drives Niagara prediction extrapolation; visual-only/non-deterministic — never enters the sim hash. ShouldTickProcessors/GetCalculatedStepTime/GetSimulationTime/GetTickCount: the per-frame step and sim clock for processors (use SimulationTime instead of GetWorld()->GetTimeSeconds() for deterministic timing). IsSimulationTick: whether the game tick advances this engine frame (bIsSimulationTick) — MassEntity processors run every engine frame; the flag guards against double-processing the same game tick on skipped frames. IsSubFrameScheduled: whether the given sub-frame is scheduled this engine tick; equals bShouldTickProcessors without frame spreading, otherwise checks the ActiveSubFrameMask bit. IsSubFrameActive: compatibility query, same as Scheduled. ShouldDeterministicSort: returns bDeterministic. GetAgentPhysicsIterations: WIP, always returns 1. GetGridUpdateProcessor: used by the network subsystem for post-resync rebuild. GetWorldTimeDilation: effective WorldSettings dilation clamped ≥ 0, for converting dilated sim durations back to wall-clock seconds (debug drawing etc.).

确定性验证:SetDeterminismVerifyTicks 配置要验证的 tick 集与要记录的维度(位置/旋转/索敌结果);ExecuteDeterminismVerification(私有,由 ProcessAssetRegistrationQueues 在处理器全部完成后调用)在目标 tick 上查询全部 FAgentTag 实体、按 UID 排序,分别折叠位置/旋转/索敌哈希(索敌含目标 UID 与 FTracing::TimeLeft 冷却)并 Verbose 级输出,供跨端比对。

Determinism verification: SetDeterminismVerifyTicks configures the target ticks and the dimensions to log (location/rotation/trace result); ExecuteDeterminismVerification (private; called from ProcessAssetRegistrationQueues after all processors complete) queries all FAgentTag entities at target ticks, sorts by UID, folds location/rotation/trace hashes (trace includes the target UID and the FTracing::TimeLeft cooldown), and logs them at Verbose level for cross-peer comparison.

把注册队列中的软引用加载为硬引用并写入注册表(由 ResolvePendingSpawns 在阶段间调用)。弹丸数据资产特殊处理:先排空弹丸队列,再对新加载的每个资产遍历其 OnBirth/OnHit/OnRemoval 级联链(子弹丸/actor 类/Niagara/Cascade/音效),把引用的软引用重新入队;迭代排空直到队列稳定(级联孙辈全覆盖),最后通用排空其余 6 个队列。末尾执行确定性验证。

Loads soft refs from the registration queues into hard refs in the registry (called from ResolvePendingSpawns between stages). Projectile data assets get special handling: the projectile queue is drained first, then each newly-loaded asset's cascade chain (OnBirth/OnHit/OnRemoval: child projectile assets, actor classes, Niagara, Cascade, sounds) is walked and re-enqueued; the loop drains iteratively until the queue settles (grandchildren covered), then the generic drain covers the remaining six queues. Determinism verification runs at the end.

清空全部已注册资源指针(允许 GC)并排空待注册队列(不加载)。另停用并销毁 Host 子系统所有音频组件池(2D/3D)的组件,防止悬挂组件残留在世界中。战斗状态重置或换关时调用。

Clears all registered asset pointers (allowing GC) and drains the pending registration queues without loading. Also stops and destroys every audio component in the Host subsystem's 2D/3D pools so no dangling components stay attached to the world. Call when resetting the battle state or changing levels.

5 个资产预注册模板:确保软引用到达注册表一次并成为热循环可用的硬指针(免 LoadSynchronous)。每个 helper:① 在对应 Registered 映射中查找软指针,命中则拷入本地硬指针字段;② 未命中则 LoadSynchronous 并把软指针入队,下一帧 ProcessAssetRegistrationQueues 写入映射。局部 Config(template fragment,非 DataAsset)被修改,数据资产本身永不被触碰。

Five asset pre-registration templates: ensure soft refs reach the registry once and become hard pointers the hot loop can use without LoadSynchronous. Each helper: ① looks the soft ptr up in the matching Registered map and copies it into the local hard-ptr field if found; ② otherwise LoadSynchronouss and enqueues the soft ptr so ProcessAssetRegistrationQueues adds it next frame. The local Config (a template fragment, not the data asset) is mutated; the data asset itself is never touched.

遍历通用 Spawn 内容结构(FAppear/FHit/FDeath/FProjectileSpawnContent/FLootSpawnContent 等含 SpawnActor + SpawnFx + PlaySound 数组的结构):逐项调用对应 Register* 模板。带 Projectile 的重载额外遍历 SpawnProjectile 数组。模板化使所有变体配置(FFxConfig vs FFxConfig_Attack 等)免重载。

Walks a generic Spawn-content struct (anything with SpawnActor + SpawnFx + PlaySound TArray fields, e.g. FAppear/FHit/FDeath/FProjectileSpawnContent/FLootSpawnContent), calling the matching Register* template per item. The WithProjectile overload additionally walks the SpawnProjectile array. Templated so all variant configs (FFxConfig vs FFxConfig_Attack, etc.) work without overloads.

把 TSoftObjectPtr 解析为 TObjectPtr 并注册防 GC。软引用为 null 返回 nullptr;注册表命中且类型正确直接返回;条目过期或类型错误则移除重解析;解析成功后写入 RegisteredRuntimeObjectPtrs(键 = FSoftObjectPath,跨类型 TSoftObjectPtr 通用)。解析失败返回 nullptr。

Resolves a TSoftObjectPtr to a TObjectPtr and registers it to prevent GC. Null soft ptrs return nullptr; a registry hit with the correct type returns the cached value; stale or wrong-typed entries are removed and re-resolved; successful resolutions are stored in RegisteredRuntimeObjectPtrs (keyed by FSoftObjectPath, generic across TSoftObjectPtr specializations). Failed loads return nullptr.

快照恢复路径:注册已解析的 UObject 防 GC。幂等(TMap::Add 同键覆盖)。不做 LoadSynchronous——调用方须已通过 FSoftObjectPath::ResolveObject() 解析路径。参数任一无效即返回。

Snapshot-restore path: registers an already-resolved UObject to prevent GC. Idempotent (TMap::Add overwrites the same key). Does NOT LoadSynchronous — the caller must have resolved the path via FSoftObjectPath::ResolveObject(). Returns when either parameter is invalid.

为单个实体解析运行时对象指针(快照恢复后 raw 指针为 null 的补救)。覆盖五对:① FNavigation → FNavigating(FlowField 软→硬,解析失败时保持 _Previous 过期,让 MoveProcessor 每帧懒加载重试);② FAgentEvent → FAgentEventRT(事件接收者;软引用为 null 时保留组件赋值的默认接收者——置空会冲掉 InitializeWithEntity 的赋值,客户端事件永不派发);③ FLootEvent → FLootEventRT;④ FProjectileEvent → FProjectileEventRT;⑤ FLootParamsRT/FLootConfig_Final 的 FlowField 软→硬。由 AgentComponent、AgentSubsystem、NetworkSubsystem 在恢复路径调用。

Resolves runtime object pointers for a single entity (remedy after snapshot restore leaves raw ptrs null). Covers five pairs: ① FNavigation → FNavigating (FlowField soft→hard; on failed resolve _Previous stays stale so the MoveProcessor's per-frame lazy load retries until the asset is ready); ② FAgentEvent → FAgentEventRT (event receiver; a null soft ref keeps the component-assigned default receiver — nulling it would clobber InitializeWithEntity's assignment and events would never dispatch on the client); ③ FLootEvent → FLootEventRT; ④ FProjectileEvent → FProjectileEventRT; ⑤ the FlowField soft→hard of FLootParamsRT/FLootConfig_Final. Called from AgentComponent, AgentSubsystem and NetworkSubsystem on the restore path.

从 template 自带 soft ptr 初始化 template runtime 指针缓存(FNavigation → FNavigating、FAgentEvent → FAgentEventRT 两对)。template 为空直接返回。

Initializes template runtime pointer caches from template-owned soft ptrs (the FNavigation → FNavigating and FAgentEvent → FAgentEventRT pairs). Returns immediately for empty templates.

销毁队列排空:EntitiesToDestroyQueue.Merge() 后,bDeterministic 时按 UID 排序(本地实体 UID=-1 用 MIN_INT 排前;禁止 Entity.Index fallback——resync 重建后双端句柄序不同,排序必须只用 UID,否则销毁序分叉),然后逐条 MA.Defer().DestroyEntity,最后 Reset。由 Tick 的 Subtick3 段每逻辑帧调用。

Destruction queue drain: after EntitiesToDestroyQueue.Merge(), sorts by UID when bDeterministic (local-only entities with UID=-1 sort first via MIN_INT; NO Entity.Index fallback — handle order diverges between peers after resync rebuild, so the sort must use UIDs only, or the destroy order diverges), then MA.Defer().DestroyEntity per entry and Reset. Called once per logic frame from the Tick Subtick3 block.

BP 事件队列排空(每逻辑帧一次,确定性批处理)。流程:① Merge 全部 18 个事件 gatherer;② bDeterministic 时各队列按 UniqueID 排序;③ 逐事件经实体的事件 fragment 对(FAgentEvent/FAgentEventRT 等)解析接收者 Actor(软引用变更时经 ResolveAndRegisterRuntimeObjectPtr 重解析),接收者实现对应接口(UMassBattleAgentInterface / UMassBattleProjectileInterface / UMassBattleLootInterface)才派发 Execute_OnXxx。实体无效或接收者无效则跳过;最后逐队列 Reset。

BP event queue drain (once per logic frame for deterministic batching). Flow: ① merges all 18 event gatherers; ② sorts each queue by UniqueID when bDeterministic; ③ per event, resolves the receiver actor through the entity's event fragment pair (FAgentEvent/FAgentEventRT etc.; a changed soft ref triggers re-resolution via ResolveAndRegisterRuntimeObjectPtr) and dispatches Execute_OnXxx only when the receiver implements the matching interface (UMassBattleAgentInterface / UMassBattleProjectileInterface / UMassBattleLootInterface). Invalid entities or receivers are skipped; each queue is reset afterwards.

调试绘制队列排空(每逻辑帧一次)。Merge 后:① 时长按世界膨胀逆系数换算(DrawDebug* 需要真实秒数,处理器入队的是模拟时长);② 每队列先按实体 FDeterminism.UniqueID 无条件排序(保证 MaxCount 裁剪的稳定确定性,世界空间项 MAX_int32 排最后);③ MaxCount 过滤——按 UID 排名,入选实体绘制完整调试集,排名超出整组剔除(入选实体不闪烁);④ 逐项调用对应 DrawDebug* API(编辑器门控 ENABLE_DRAW_DEBUG)。LineBatcher 镜像队列(Duration > 0 走 WorldPersistent 批处理器,否则走每帧批处理器)不经过滤/排序,Shipping 可见,用于编队可视化等常驻绘制。

Debug draw queue drain (once per logic frame). After merging: ① durations are converted by the inverse world dilation (DrawDebug* wants real seconds; processors enqueue sim-time durations); ② each queue is sorted unconditionally by entity FDeterminism.UniqueID (stable, deterministic MaxCount culling; world-space items get MAX_int32 and sort last); ③ MaxCount culling — entities ranked by UID draw their FULL debug set, entities beyond their MaxCount are culled entirely (selected entities never flicker mid-set); ④ items are drawn via the matching DrawDebug* API (gated by ENABLE_DRAW_DEBUG in the editor). The LineBatcher mirror queues (Duration > 0 routes to the WorldPersistent batcher, otherwise the per-frame batcher) bypass filtering/sorting — Shipping-visible, used for formation visualization and other always-on rendering.

绘制三维扇形(顶面/底面弧 + 半径线 + 侧棱)。参数非法(World 空 / 角度 ≤ 0 / 半径 ≤ 0 / 高度 ≤ 0)直接返回;角度钳制 [1°, 360°];方向近零时回退前向。360° 时跳过半径与侧棱(完整圆柱扇形)。

Draws a 3D sector (top/bottom arcs + radius lines + side edges). Returns immediately on invalid parameters (null World / angle ≤ 0 / radius ≤ 0 / height ≤ 0); angle clamps to [1°, 360°]; a near-zero direction falls back to the forward vector. At 360° the radius lines and side edges are skipped (full cylinder sector).

点伤害 + debuff 应用。流程:① 用 TSet 去重目标并跳过 IgnoreEntities 与无效实体;② 逐个经 MA.MatchQuery(Overlapper, Damage.Query) 查询匹配过滤;③ bDeterministic 时按 UID 预提取键排序(SortByPreExtractedKeys,本地实体 MIN_INT 排前,无 Entity.Index fallback);④ 逐目标计算击退方向(目标位置 − HitFromLocation 的 2D 归一化),调用共享逻辑 ProcessSingleEntityDamageAndDebuff——内部处理抗性乘数(按 FDefence)、暴击(确定性种子 = TargetUID ^ CauserUID<<8 ^ InstigatorID<<16,每目标自掷骰子)、钳制伤害到剩余生命、致命判定,并向 DmgGatherer/LaunchGatherer/debuff gatherer 收集结果。默认重载经 MA.Defer() 取共享命令缓冲;Context 重载经 Context.Defer()。

Point damage + debuff application. Flow: ① dedupes targets via a TSet and skips IgnoreEntities and invalid entities; ② filters each through MA.MatchQuery(Overlapper, Damage.Query); ③ when bDeterministic, sorts by pre-extracted UID keys (SortByPreExtractedKeys; local entities first via MIN_INT; no Entity.Index fallback); ④ per target computes the knockback direction (2D-normalized target − HitFromLocation) and calls the shared ProcessSingleEntityDamageAndDebuff — which applies resistance multipliers (from FDefence), crit (deterministic seed = TargetUID ^ CauserUID<<8 ^ InstigatorID<<16; each target rolls its own dice), clamps damage to remaining health, detects kills, and gathers into DmgGatherer/LaunchGatherer/debuff gatherers. The default overload uses the shared command buffer via MA.Defer(); the Context overload uses Context.Defer().

径向(球形)伤害 + debuff。经 HashGridSub->SphereTraceForAgents 在网格中查找半径 Damage.DmgRadius 内的目标(KeepCount 限制返回数,-1 = 不限制),命中空则返回。确定性排序后逐目标计算衰减——距离测到碰撞体表面(中心距 − 碰撞半径 × 缩放),在 [0, DmgRadius] 上 1→0 钳制映射,Damage.bUseFalloff/Debuff.bUseFalloff 分别启用伤害/击退衰减;其余共享逻辑同点伤害。

Radial (sphere) damage + debuff. Queries targets within Damage.DmgRadius via HashGridSub->SphereTraceForAgents (KeepCount limits the results; -1 = unlimited), returning when nothing is hit. After the deterministic sort, per-target falloff is computed — distance measured to the collider surface (center distance − collider radius × scale), clamped-mapped 1→0 over [0, DmgRadius]; Damage.bUseFalloff/Debuff.bUseFalloff enable damage/knockback falloff independently. The remaining shared logic matches point damage.

光束(扫掠)伤害 + debuff。经 HashGridSub->SphereSweepForAgents 在 StartLocation → EndLocation 间以 Damage.DmgRadius 半径扫掠查目标(KeepCount 限制)。衰减距离用点到直线距离(FMath::PointDistToLine,目标到光束轴的距离)减去碰撞体表面,再钳制映射 1→0。

Beam (sweep) damage + debuff. Queries targets via HashGridSub->SphereSweepForAgents sweeping radius Damage.DmgRadius along StartLocation → EndLocation (KeepCount limits results). The falloff distance uses the point-to-line distance (FMath::PointDistToLine, target to the beam axis) minus the collider surface, then clamp-mapped 1→0.

暴击判定:Stream.FRand() < Probability 则伤害乘 damageMult 并标记暴击,否则原值返回。随机流由调用方按确定性种子构造。

Crit roll: when Stream.FRand() < Probability the damage is multiplied by damageMult and flagged as critical, otherwise returned unchanged. The stream is seeded deterministically by the caller.

把飘字配置写入所有者实体的 FTextPop fragment(加锁追加)。所有者缩放乘到 Scale 中。实体无 FTextPop 时静默跳过。由 MassBattleAgentReactionProcessor 在受击处理时调用。

Appends a text-pop config to the owner entity's FTextPop fragment (locked append). The owner's scale multiplies into Scale. Silently skipped when the entity lacks FTextPop. Called by MassBattleAgentReactionProcessor during hit handling.

滑动窗口平均 FPS:把本帧增量追加进缓冲,累积超窗口时长时从头移除旧帧(至少保留 1 帧),返回 帧数 / 总时长。缓冲由调用方持有。

Sliding-window average FPS: appends the frame delta to the buffer, removes oldest frames from the head while the total exceeds the window (keeping at least one), and returns frames / total time. The buffer is owned by the caller.

本地偏移变换转世界:世界旋转旋转本地位置得世界偏移,叠加世界位置;世界旋转乘本地旋转得最终旋转;缩放沿用本地。

Converts a local offset transform to world: the world rotation rotates the local location into a world offset added to the world location; the final rotation is world × local; scale is carried from the local transform.

编辑器专用诊断(整函数 WITH_EDITOR 门控):输出宿主/实体/音频组件池的当前大小与本 tick 分配明细(总生成数、其中来自池、其中全新构建),9 个 bool 各控制一个池。计数器在 UMassBattleHostSubsystem::ExecuteTick 重置——从 BP 在 tick 之后调用即可看到本 tick 活动。全部经 HostSub->GetPoolCount/GetTotal*PoolSize 与 HostPoolTickStats 等统计成员读取。

Editor-only diagnostic (the whole body is WITH_EDITOR-gated): logs current size and this-tick allocation breakdown for the host/entity/audio component pools (total spawns, of which from pool, of which freshly built); nine bools each toggle one pool. Counters reset every UMassBattleHostSubsystem::ExecuteTick — call from BP after the tick to see this tick's activity. Reads via HostSub->GetPoolCount/GetTotal*PoolSize and the HostPoolTickStats stat members.