UMassBattleBPTaskAgentsMoveTo

主工厂。锁步门控:UMassBattleNetworkSubsystem::IsOffLockstep 为真(网络会话且不在命令执行内)时拒绝并返回 nullptr。创建实例、铸 MyTaskID(计数器为 UMassBattleSubsystem::NextMoveToTaskID,按 World 落位,跳过 0)、缓存全部参数;Location 模式把目标抬升到 agent 中心 Z(LiftGoalToAgentCenterZ);每 agent 建立跟踪行;工厂内即 RegisterTask(快照采集 tick 当帧创建的任务在引擎激活前就要被采到)。

Main factory. Lockstep gate: rejects with nullptr when UMassBattleNetworkSubsystem::IsOffLockstep is true (networked session outside command execution). Creates the instance, mints MyTaskID (counter is UMassBattleSubsystem::NextMoveToTaskID, world-scoped, skipping 0), caches all parameters; Location mode lifts goals to agent-center Z (LiftGoalToAgentCenterZ); builds a tracking row per agent; registers via RegisterTask inside the factory (a task created on the snapshot-capture tick must be captured before the engine activates it).

模板化创建:经模板实例(UMassBattleBPTaskTemplateBase 子类)创建任务、记录模板键、绑定 delegate(模板类 BP 绘制的 BindMoveToTask)。附加守卫:任务重建窗口(IsTaskRebuildInProgress)拒绝 BP 创建;工厂不得自行 Activate(async 节点展开会调用一次 Activate,双激活会杀死任务——Location 模式首次激活清空 Locations,第二次命中 "Goal array is empty")。

Template-based creation: creates the task via the template instance (UMassBattleBPTaskTemplateBase subclass), records the template key, and binds the delegates (BP-drawn BindMoveToTask on the template class). Extra guards: the task-rebuild window (IsTaskRebuildInProgress) rejects BP creation; the factory must NOT activate (the async node expansion calls Activate() once; double activation kills the task — Location mode empties Locations on first activate, the second hits "Goal array is empty").

按模板合并的蓝图节点:把同一模板类创建的全部活跃 MoveTo 任务按配置签名归组,每组并入该签名最旧(任务 ID 最小)的任务——同模板下不同参数的任务各自归组。零记账:无需任务对象、无需 agent 列表,是 CreateAgentsMoveToTask 在高频出兵流(RTS 兵营)中的天然搭档——每次出兵照常创建,随后调一次本节点,每次出兵的任务折叠为一个执行体。门控:与其它创建入口相同的锁步门控(IsOffLockstep),且任务重建窗口(IsTaskRebuildInProgress)内拒绝。候选集来自子系统注册表(注册表序 = 创建序,TemplateKey 穿越 resync),双端解析结果一致;签名比较逐位精确、任务 ID 经快照同步,分组确定。不要把 BindMoveToTask 的 Task 参数存进模板 BP 变量(模板变量是锁步变量,引用类型被跳过,resync 后变野引用,后续合并会发散)。注意:Location 目标模式下合并不同集合点的任务功能上安全(每个 agent 自带已解析目标,事件仍路由到各自来源任务的委托),但同集合点出兵归批可使事件批次的 agent 数组连续。

Template-based merge Blueprint node: groups ALL active MoveTo tasks created from one template class by config signature and folds each group into that signature's oldest task (lowest task ID) — tasks created with different parameters from the same template each get their own group. Zero bookkeeping: no task objects, no agent lists — the natural companion to CreateAgentsMoveToTask in high-frequency spawn flows (RTS barracks): create per-spawn, then call this once and every per-spawn task folds into one executor. Gated by the same lockstep gate as the other creation entries (IsOffLockstep), and rejected while a task rebuild is in progress (IsTaskRebuildInProgress). The candidate set comes from the subsystem registry (registry order = creation order, TemplateKeys survive resync), so both peers resolve the identical set; the signature comparison is bit-exact and task IDs are snapshot-synced, so the grouping is deterministic. Do NOT hold the Task param of BindMoveToTask in template BP variables (template variables are lockstep variables where reference types are skipped — a stored task object goes stale after resync and subsequent merges would diverge). Note: in Location goal mode merging tasks with different rally points is functionally safe (each agent carries its own resolved goal; events still route to each origin task's delegates), but batching same-rally spawns keeps agent arrays contiguous per event batch.

合并壳状态查询:IsMergedShell 在本任务被并入执行体后返回 true——本任务已休眠(不再 tick、不活跃),但其委托仍由执行体为其 agent 触发(按 OriginTaskID 路由);GetExecutorTaskID 返回作为合并壳时的执行体任务 ID(否则为 0)。

Merged-shell state queries: IsMergedShell returns true once this task was merged into an executor — it is dormant (no tick, inactive), but its delegates still fire for its agents (routed by OriginTaskID on the executor); GetExecutorTaskID returns the executor task ID while acting as a merged shell (0 otherwise).

壳的 resync 重建与终结路径,均由系统内部调用。OnShellRebuilt(Shell):resync 后重链重建壳——执行体与壳两条记录都重建完成后由 RebuildTasksFromSnapshot 调用,把壳重新挂回执行体的 MergedShells 注册表,剩余 agent 数由执行体 TrackedAgents 的 OriginTaskID 重新推导(对采集/重建顺序不敏感)。FinishShell:壳的终结路径——以壳自己的失败累积广播 OnTaskEnd、注销、标记可销毁;壳的最后一个 agent 结束时由执行体调用,或由 RebuildTasksFromSnapshot 处理孤儿壳记录(payload 中无执行体)。

Shell resync-rebuild and terminal paths, both called internally by the system. OnShellRebuilt(Shell): re-links a rebuilt shell after resync — called by RebuildTasksFromSnapshot once both the executor and shell records exist, re-attaching the shell to the executor's MergedShells registry; the remaining-agent count is re-derived from the executor's TrackedAgents OriginTaskIDs (robust against capture/rebuild ordering). FinishShell: the shell terminal path — broadcasts OnTaskEnd with the shell's own accumulated failures, deregisters, marks ready to destroy; called by the executor when the shell's last agent resolves, or by RebuildTasksFromSnapshot for an orphaned shell record (no executor in the payload).

resync 快照重建入口(仅 UMassBattleSubsystem::RebuildTasksFromSnapshot 调用):同锁步门控(resync 恢复窗口绕过 IsOffLockstep),经 RestoreFromSnapshot 填充状态后返回。

Resync snapshot rebuild entry (called by UMassBattleSubsystem::RebuildTasksFromSnapshot only): same lockstep gate (the resync restore window bypasses IsOffLockstep), fills state via RestoreFromSnapshot and returns.

任务 ID 计数器访问器——经快照 payload 在双端同步。计数器按 World 落位(2026-09-12 PIE desync 修复起):位于 UMassBattleSubsystem::NextMoveToTaskID(每 World 一份),不再是本类的进程级 static——PIE 同时承载两个世界时,共享计数器会使 ActiveMoveToTaskID 按 World 分叉导致 hash desync。世界上下文取不到子系统时读取返回 0、写入无操作。

Task-ID counter accessors — synced across peers through the snapshot payload. The counter is world-scoped (since the 2026-09-12 PIE desync fix): it lives on UMassBattleSubsystem::NextMoveToTaskID (one per world), no longer a process-static on this class — with PIE hosting two worlds at once, a shared counter forked ActiveMoveToTaskID per world and desynced the hash. If the subsystem cannot be resolved from the world context, the read returns 0 and the write is a no-op.

激活:校验目标数组非空(FlowField 模式除外)与自定义路径非空,预解析 Actor/Entity 目标;逐 agent 过滤无效/濒死实体;Custom 模式分配路径并设首航点为目标;置 AStarMovingToFlag + BPTaskMoveToFlag(bMoveToLocked = !bCanInterrupt);命令接管:重置 FBehaving 为 Idle、终止进行中的 Return、清行为旗标与残留索敌目标;写 Moving(ActiveMoveToTaskID / Goal / bMovingToGoal / MoveState=None)与 Navigating(RequestedNavMode,FlowField 模式覆盖流场与图层并快照恢复值,Custom → Direct);广播 OnTaskStart;清空 Locations 数组(已解析进跟踪行);记录可视化墙钟起点;注册 MassBattleTick。

Activation: validates non-empty goal arrays (except FlowField mode) and custom paths, pre-resolves Actor/Entity goals; filters dead/dying agents; Custom mode assigns paths and sets the first waypoint as the goal; sets AStarMovingToFlag + BPTaskMoveToFlag (bMoveToLocked = !bCanInterrupt); command takeover: resets FBehaving to Idle, terminates in-flight Return, clears behavior flags and the stale trace target; writes Moving (ActiveMoveToTaskID / Goal / bMovingToGoal / MoveState=None) and Navigating (RequestedNavMode; FlowField mode overrides the field and layer, snapshotting restore values; Custom → Direct); broadcasts OnTaskStart; empties the Locations array (already resolved into tracking rows); records the visualization wall-clock start; registers with MassBattleTick.

快照恢复激活路径(bRestoringFromSnapshot 时 Activate 走此分支):对重建实体复检(死亡/濒死语义同常规 Activate),仅补写快照注册表未覆盖的 fragment 字段(FlowField 覆盖写 ptr + _Previous 同写,防 MoveProcessor 变更检测触发假重载);绝不重初始化快照状态。重置可视化墙钟预算并注册 tick。

Snapshot-restore activation path (taken by Activate when bRestoringFromSnapshot): re-validates agents against rebuilt entities (same dead/dying semantics as normal Activate) and re-claims only fragment fields the snapshot registry does not cover (the FlowField override writes ptr + _Previous together to prevent MoveProcessor change detection from triggering a false reload); never re-initializes snapshot state. Restarts the visualization wall-clock budget and registers the tick.

采集当前运行状态到快照记录(注册表驱动,由 UMassBattleSubsystem::CaptureTaskRecords 调用):任务类型/ID/模板键、目标配置(Actor 存路径、Entity 存 UID、Location 为空——重建时从 per-agent 值回填)、导航配置、每 agent 运行状态(目标/卡住/路径跟踪)、累计失败 UID。

Captures current runtime state into a snapshot record (registry-driven, called by UMassBattleSubsystem::CaptureTaskRecords): task type/ID/template key, goal config (Actor paths, Entity UIDs, Locations empty — refilled from per-agent values on rebuild), navigation config, per-agent runtime state (goal/stuck/path tracking), and accumulated failed UIDs.

resync 终止:退订 tick + 可选 OnTaskEnd(bBroadcastOnTaskEnd=false 用于将从快照重建的任务——它们会"重生",结束事件是假结束)+ 标记销毁,不写 fragment(fragment 状态由快照 blob 权威)。清空 TrackedAgents 使 GC 延迟的 BeginDestroy→Cleanup 零写入;注销任务。

Resync termination: deregisters the tick + optional OnTaskEnd (bBroadcastOnTaskEnd=false for tasks that will be rebuilt from the snapshot — they "respawn", the end event would be a false end) + ready-to-destroy, WITHOUT fragment writes (fragment state is snapshot-blob authoritative). Empties TrackedAgents so the deferred GC BeginDestroy→Cleanup pass writes nothing; unregisters the task.

从快照记录恢复运行状态(由 CreateMoveToTaskFromSnapshot 调用):任务 ID 必须与服务器存活任务一致(fragment 所有权检测匹配);目标配置按类型重建(Actor 经 FindObject 路径解析、Entity 经 UID 反解、Location 从 per-agent 值回填);导航配置恢复;跟踪行直接填充不重新推导;注册任务。

Restores runtime state from a snapshot record (called by CreateMoveToTaskFromSnapshot): the task ID must equal the surviving server task's (fragment ownership checks match); goal config rebuilt per type (Actor via FindObject path resolution, Entity via UID, Location refilled from per-agent values); navigation config restored; tracking rows directly filled, no re-derivation; task registered.

逐帧驱动(注册于 UMassBattleSubsystem::MassBattleTick)。Phase A 并行分类(MBParallelFor Unbalanced,每 agent 只写自身槽位 + 自身实体 fragment,不相交内存——并行==串行,确定性不依赖 bDeterministic):① 死亡/无效 → Fail;② 所有权转移(ActiveMoveToTaskID != MyTaskID)→ Transfer;③ 更新目标(FlowField 模式回读 Moving.Goal;Actor/Entity 从缓存解析,失效 → 在当前处落脚并 Fail);④ 调试绘制;⑤ 挂起/恢复(bCanInterrupt 时行为旗标存在 → 置 bMoveToSuspended 挂起,行为结束恢复并重新认领);⑥ 到达判定(自身 FMove::XY::AcceptanceRadius,地面 3D / 飞行 2D;Entity 目标带碰撞体时形状感知——到胶囊表面距离;Custom 模式推进航点,末端按 OneWay/Looped/PingPong 处理);⑦ 卡住检测(AverageSpeed < StuckVelocityThreshold 累计 StuckTimeLimit,且距目标 ≤ FailRadius → Fail 并就地落脚)。Phase B 串行(倒序遍历)应用数组级副作用并广播 OnAgentSuccess / OnAgentFail / OnAgentInterrupt / OnAgentTransfer;重建可视化线段;全部解决后 Cleanup + FinishTask。

Per-frame tick driver (registered with UMassBattleSubsystem::MassBattleTick). Phase A parallel classification (MBParallelFor Unbalanced; each agent writes only its own slot + its own entity's fragments — disjoint memory, parallel == serial, determinism does not depend on bDeterministic): ① dead/invalid → Fail; ② ownership transfer (ActiveMoveToTaskID != MyTaskID) → Transfer; ③ goal update (FlowField mode reads back Moving.Goal; Actor/Entity resolved from cache, invalid → settle in place and Fail); ④ debug drawing; ⑤ suspend/resume (bCanInterrupt: behavior flags present → set bMoveToSuspended and suspend; behavior ends → resume and re-claim); ⑥ arrival check (own FMove::XY::AcceptanceRadius, 3D on ground / 2D when flying; shape-aware for Entity goals with a collider — distance to capsule surface; Custom mode advances waypoints, end handled per OneWay/Looped/PingPong); ⑦ stuck detection (AverageSpeed < StuckVelocityThreshold accumulating StuckTimeLimit, within ≤ FailRadius of the goal → Fail and settle in place). Phase B serial (reverse order) applies array-level side effects and broadcasts OnAgentSuccess / OnAgentFail / OnAgentInterrupt / OnAgentTransfer; rebuilds visualization lines; when all agents resolve → Cleanup + FinishTask.

置/清 AStarMovingToFlag + BPTaskMoveToFlag 并写 Moving.bMoveToLocked;ClearAgentFlags 带所有权守卫(仅当 ActiveMoveToTaskID == MyTaskID 或 0 时释放),恢复导航模式与任务前流场/图层(快照值直接恢复,零帧空窗)。worker 安全重载由调用方传入已解析的 UMassAPISubsystem*(线程上不做 UObject 查找)。

Sets/clears AStarMovingToFlag + BPTaskMoveToFlag and writes Moving.bMoveToLocked; ClearAgentFlags has an ownership guard (releases only when ActiveMoveToTaskID == MyTaskID or 0), restores the nav mode and the pre-task flow field/layer (snapshotted values restored directly, zero-frame gap). Worker-safe overloads take a caller-resolved UMassAPISubsystem* (no UObject lookup off the game thread).

Cleanup:释放全部剩余 agent 的锁、退订 tick、注销任务、清可视化缓存;FinishTask:用累计失败 UID 广播 OnTaskEnd 并标记可销毁——所有终止路径的最后一步。

Cleanup: releases every remaining agent's lock, deregisters the tick, unregisters the task, clears visualization caches; FinishTask: broadcasts OnTaskEnd with the accumulated failed UIDs and marks ready to destroy — the final hop of every termination path.

引擎 tick 渲染路径:IsTickable 仅当有内容可绘制(bIsActive && CachedVizLines.Num() > 0);Tick 每渲染帧重新提交可视化线段(含墙钟预算闸门)——MassBattle tick 重建 CachedVizLines(逻辑 + 并行预计算),引擎 tick 重新提交,渲染频率高于模拟频率时不闪烁。

Engine-tick render path: IsTickable only when there is something to draw (bIsActive && CachedVizLines.Num() > 0); Tick re-submits the visualization lines every render frame (with the wall-clock budget gate) — the MassBattle tick rebuilds CachedVizLines (logic + parallel pre-compute), the engine tick re-submits, so rendering never blinks when the render rate exceeds the sim rate.