UMassBattleFuncLib

为一组目标坐标获取或创建托管(自动回收)流场层——任务合并的 layer 级孪生:相同目标反复调用复用同一存活层(按确定性目标哈希匹配,-0.0 规范化;复用层还可被本次获取「救活」,冲刷时复查 UserCount);无存活匹配则创建并同步计算。层按 MoveTo 任务引用计数(任务激活时获取、结束时释放),无任务使用时在串行 tick 窗口自动销毁。与 AgentsMoveTo 同锁步门控:必须在 ExecuteNetCommand 内调用,保证层 ID 与内容双端一致——锁步外调用、流场无效 / 目标为空、或任务重建窗口(IsTaskRebuildInProgress)期间调用均记日志并返回无效句柄。返回的句柄须连同同一个 FlowField actor 一起传给 AgentsMoveTo / CreateAgentsMoveToTask(FlowField 模式);任务带 layer 必须带 FlowField,否则被任务拒绝。

Get-or-create a managed (auto-released) flow-field layer for a set of goal locations — the layer-level twin of task merging: repeated calls with the same goals reuse the SAME live layer (matched by a deterministic goal hash with -0.0 canonicalized; a reused pending-destroy layer is revived by the acquire, UserCount re-checked at flush); no live match → create + compute synchronously. The layer is reference-counted per MoveTo task (the task acquires on activate, releases on end) and destroys itself in the serial tick window once no task uses it. Lockstep-gated like AgentsMoveTo: must be called inside ExecuteNetCommand so layer IDs and content stay identical on both peers — off-lockstep calls, a null FlowField / empty goals, or the task-rebuild window (IsTaskRebuildInProgress) log and return an invalid handle. Pass the returned handle into AgentsMoveTo / CreateAgentsMoveToTask (FlowField mode) together with the SAME FlowField actor; a layer handle without a task FlowField is rejected by the task.

把伤害结果列表转实体句柄数组:每个结果的 DamagedEntity 必加;InstigatorEntity 仅在当前 play world 的 UMassAPISubsystem 判定有效时加入。

Converts damage results to an entity-handle array: every DamagedEntity is added; InstigatorEntity is added only when valid per the current play world's UMassAPISubsystem.

把追踪结果列表转实体句柄数组:每个结果的 Entity 依序加入。

Converts trace results to an entity-handle array: each result's Entity in order.

伤害结果 → FEntityArray(仅 DamagedEntity)。

Damage results → FEntityArray (only DamagedEntity).

追踪结果 → FEntityArray(每个结果的 Entity)。

Trace results → FEntityArray (each result's Entity).

句柄数组(或单个句柄)包装成 FEntityArray。

Wraps a handle array (or a single handle) into an FEntityArray.

从 UMassBattleAgentComponent 取其实体句柄;组件为空返回无效句柄。

Gets the entity handle from a UMassBattleAgentComponent; returns an invalid handle when the component is null.

EBattleFlags ↔ EEntityFlags 直接转换(两个枚举的 uint8 数值匹配)。已弃用——改用 FName 旗标注册表。

Direct EBattleFlags ↔ EEntityFlags conversion (the two enums share matching uint8 values). Deprecated — use the FName-based flag registry instead.

数组版 flag 转换,逐元素 static_cast。

Array version of the flag conversion, element-wise static_cast.

把 flag 数组转 FName 数组:经 UMassAPIFlagSettings::FlagRegistry 反向查找,找不到时回退为枚举成员名字符串。Battle 版本跳过 ≥ EBattleFlags_MAX 的条目。

Converts flag arrays to FName arrays: reverse lookup in UMassAPIFlagSettings::FlagRegistry, falling back to the enum member name string. The Battle version skips entries at or beyond EBattleFlags_MAX.

委托 FMassBattleQuery::ToEntityQuery() 转换(flag 经注册表反查为 FName 列表;忽略障碍物与优先级)。

Delegates to FMassBattleQuery::ToEntityQuery() (flags reverse-looked-up to FName lists; obstacles and priorities ignored).

反方向转换:复制组合列表;FName flag 经注册表正查为 EBattleFlags(未找到或越界 → EBattleFlags_MAX,跳过);ObstacleList 保持默认(空);结果 MarkCacheDirty()。

Reverse conversion: copies the composition lists; FName flags are forward-looked-up to EBattleFlags (not found or out of range → EBattleFlags_MAX, skipped); ObstacleList stays default (empty); the result calls MarkCacheDirty().

复制 Tags / Fragments / MutableSharedFragments / ConstSharedFragments,BattleFlags 逐元素 static_cast 到 Flags。

Copies Tags / Fragments / MutableSharedFragments / ConstSharedFragments; BattleFlags cast element-wise into Flags.

反方向转换:Flags 中值小于 EBattleFlags_MAX 的条目转回 BattleFlags,越界丢弃。

Reverse conversion: Flags entries below EBattleFlags_MAX convert back to BattleFlags; out-of-range entries are dropped.

把 SourceArray 中目标数组不存在的元素追加到 TargetArray(按 Identical 判定重复)。快速路径:元素类型支持哈希(CPF_HasGetValueTypeHash,含 FEntityHandle)时构建哈希 → 索引多重映射,把 O(N×M) 线性扫描降到期望 O(N+M);慢速回退:不可哈希类型走 O(N×M) Identical 扫描。

Appends elements of SourceArray not already present in the target (duplicates judged by Identical). Fast path: when the element type supports hashing (CPF_HasGetValueTypeHash, including FEntityHandle), builds a hash → index multimap, dropping the O(N×M) linear scan to expected O(N+M); slow fallback: non-hashable types use the O(N×M) Identical scan.

从 TargetArray 移除 ItemsToRemove 中出现的所有元素。快速路径:哈希标记 + 单趟原地稳定压缩(CopyCompleteValue 处理复杂类型);慢速回退:从尾到头逐元素 O(N×M) 扫描。

Removes all elements of TargetArray that appear in ItemsToRemove. Fast path: hash marking + a single in-place stable compaction walk (CopyCompleteValue handles complex types); slow fallback: tail-to-head O(N×M) scan.

按闭区间 [StartIndex, EndIndex](含两端)裁切 wildcard 数组,输出类型跟随输入。非法范围(负数、倒置或越界)输出 Error 日志与空数组。逐字节拷贝——两个数组共享同一元素类型与布局。

Trims a wildcard array by the closed range [StartIndex, EndIndex] (inclusive); the output type follows the input. Invalid ranges (negative, inverted, or out of bounds) log an Error and output an empty array. Byte-wise copy — both arrays share the same element type and layout.

已弃用的 flag 三件套:枚举转换后转发到 UMassAPIFuncLib::HasFlag_Entity / SetFlag_Entity / ClearFlag_Entity。FlagToTest >= EBattleFlags_MAX 时直接返回 false(不调用 API)。改用 SetMassFlag / ClearMassFlag 节点。

Deprecated flag trio: converts the enum and forwards to UMassAPIFuncLib::HasFlag_Entity / SetFlag_Entity / ClearFlag_Entity. Returns false without calling the API when FlagToTest >= EBattleFlags_MAX. Use the SetMassFlag / ClearMassFlag nodes instead.

选中 agent,转发到 UMassBattleAgentSubsystem::SelectAgents。网络模式下为端侧本地操作:锁步外执行(即时本地反馈——无服务器往返)、设置本地 Selected/BeingSelect flag(快照恢复时剥离、resync 后由 LocalVisualRegistry 重放)、生成本地视觉宿主(UID=-1、无 FNetworkTag——永不进快照/hash/网络池)。权威游戏效果(移动/攻击等任务)请把选中的 agent UID 走锁步命令路径(ExecuteNetCommand)发送。

Selects agents, forwarded to UMassBattleAgentSubsystem::SelectAgents. In networked mode this is a peer-local operation: runs off-lockstep (instant local feedback — no server round-trip), sets the local-only Selected/BeingSelect flags (stripped from snapshot restore, replayed from LocalVisualRegistry after resync), and spawns local-only visual hosts (UID=-1, no FNetworkTag — never in snapshot/hash/network pools). For authoritative gameplay effects (move/attack tasks), send the selected agent UIDs through the lockstep command path (ExecuteNetCommand).

取消选中,转发到 UMassBattleAgentSubsystem::DeselectAgents;语义与 SelectAgents 相同(端侧本地)。

Deselects agents, forwarded to UMassBattleAgentSubsystem::DeselectAgents; semantics match SelectAgents (peer-local).

为实体播放指定索引的动作蒙太奇(转发到 Agent 子系统):把 FAnimating fragment 切换到 Montage 状态。AnimIndex 为 255(INVALID)时从共享 OtherAnimData 随机选槽(RNG 在模拟侧消耗,保持确定性并进入网络快照)。实体缺少 FAnimating 时忽略。

Plays the montage at the given animation index on the entity (forwarded to the Agent subsystem): switches the FAnimating fragment to the Montage state. AnimIndex 255 (INVALID) picks a random slot from the shared OtherAnimData (the RNG is consumed on the sim side so it stays deterministic and enters the network snapshot). Ignored when the entity lacks FAnimating.

把 agent / actor / Niagara 系统 / Cascade 粒子附着到目标实体(被附着对象的视觉以 RelativeTransform 跟随 AttachToEntity;经 FAgentHostConfig / FActorSpawnConfig / FFxConfig 配置宿主生命周期与视觉设置),转发到 Agent 子系统。网络语义:AttachAgentToAgent 的宿主是模拟实体——必须在锁步命令路径内调用(锁步外生成会导致 hash 发散);AttachActorToAgent 锁步外调用安全(actor 宿主纯本地生成,UID=-1、无 FNetworkTag,并登记供 resync 重链);AttachNiagara/Cascade 自动分流——锁步窗口内生成同步 FX 宿主,锁步外(BP 直调)纯本地,FX 永不破坏确定性。

Attaches an agent / actor / Niagara system / Cascade particle to the target entity (the attached visual follows AttachToEntity at RelativeTransform; host lifetime and visual settings via FAgentHostConfig / FActorSpawnConfig / FFxConfig), forwarded to the Agent subsystem. Network semantics: the agent host of AttachAgentToAgent is a simulation entity — it MUST be called inside the lockstep command path (an off-lockstep agent host would diverge the hash); AttachActorToAgent is safe off-lockstep (the actor host spawns local-only, UID=-1, no FNetworkTag, registered for resync re-link); AttachNiagara/Cascade auto-split — a synchronized FX host inside the lockstep window, local-only off-lockstep (BP direct call), so FX never corrupts determinism.

读取实体位置(FLocating):当前 / 上一帧 / 初始三个位置同时输出。

Reads the entity location (FLocating): current / previous / initial locations out together.

返回多个实体的平均位置;子系统不可用返回 ZeroVector。

Returns the average location of the entities; ZeroVector when the subsystem is unavailable.

读取实体旋转:欧拉角 / 四元数 / 前向方向三个输出。

Reads the entity rotation: rotator / quat / forward direction outputs.

读取实体缩放:标量 / 渲染缩放 / 抖动乘数三个输出。

Reads the entity scale: scalar / render scale / jiggle multiplier outputs.

读取实体完整变换;子系统不可用返回 Identity。

Reads the entity's full transform; Identity when the subsystem is unavailable.

读取实体的前向 / 上 / 右方向向量与速度;子系统不可用返回 ZeroVector。

Reads the entity's forward / up / right vectors and velocity; ZeroVector when the subsystem is unavailable.

写入实体的位置 / 旋转 / 缩放 / 线速度 / 角速度(转发到 Agent 子系统,写入对应 fragment)。

Writes the entity's location / rotation / scale / linear velocity / angular velocity (forwarded to the Agent subsystem, writing the matching fragments).

设置 agent 队伍:更新 FTeam.index 并交换队伍 tag(FTeam0Tag..FTeam255Tag,触发 archetype 迁移),同步 PreviousIndex。失败(MA 缺失 / 句柄无效 / 索引越界 [0,255] / 缺 FTeam fragment)记录 Warning 并返回,不触发 OnFinished;状态已一致时直接触发 OnFinished 完成(无迁移)。bDeferred 为 true 时把整个操作经命令缓冲延迟到 flush 执行(flush 时重新校验)。

Sets the agent's team: updates FTeam.index and swaps the team tag (FTeam0Tag..FTeam255Tag, triggering archetype migration), keeping PreviousIndex in sync. On failure (MA missing / invalid handle / index out of range [0,255] / missing FTeam fragment) logs a Warning and returns without firing OnFinished; when the state is already consistent, fires OnFinished immediately (no migration). With bDeferred true, the whole operation is queued via the command buffer and runs at flush (validations re-run at flush).

设置 agent 子类别:更新 FSubType.Index 并交换子类别 tag(FSubType0Tag..FSubType255Tag,触发 archetype 迁移)。失败与延迟语义与 SetAgentTeam 完全一致。

Sets the agent's subtype: updates FSubType.Index and swaps the subtype tag (FSubType0Tag..FSubType255Tag, triggering archetype migration). Failure and deferred semantics identical to SetAgentTeam.

以 Origin 为球心、Radius 为半径的球形索敌(区域内 agent 集合)。

Sphere targeting centered at Origin with Radius (the set of agents inside the volume).

从 Start 到 End 的球体扫掠索敌(扫掠路径上的 agent 集合)。

Sphere sweep targeting from Start to End (agents along the swept path).

扇形索敌:Origin + Direction 定向、Radius 半径、Height 高度、Angle 张开角(度,默认 360 = 全向)。

Sector targeting: Origin + Direction orientation, Radius, Height, and Angle opening angle in degrees (default 360 = omnidirectional).

盒形索敌(Trace 静态盒 / Sweep 扫掠盒):Range3D 半范围 + Orientation 朝向。

Box targeting (static box / swept box): Range3D half-extents + Orientation.

胶囊索敌(Trace 静态胶囊 / Sweep 扫掠胶囊):查询以 Origin 为中心、半径 Radius、轴杆半高 HalfHeight、轴向沿 Orientation 朝上的胶囊(Trace),或该胶囊自 Start 扫掠至 End 覆盖的体积(Sweep)。命中判定为精确测试:agent 碰撞体胶囊与查询胶囊(静态:两轴段距离 ≤ Radius + agent 碰撞体半径;扫掠:胶囊轴与扫掠段的精确闵可夫斯基和,再膨胀 agent 碰撞体半径)相交。零长度扫掠(Start == End)退化为静态胶囊检测。用于竖立光柱、站桩 AoE 体积、竖向光束检测(Trace)与冲刺、冲锋、大幅竖向挥砍走廊(Sweep)。

Capsule targeting (Trace = static capsule / Sweep = swept capsule): queries a capsule centered at Origin with radius Radius, shaft half-height HalfHeight, axis along Orientation's up (Trace), or the volume covered by sweeping that capsule from Start to End (Sweep). Hits use an exact test: the agent's collider capsule must intersect the query capsule (Trace: axis-segment distance ≤ Radius + agent collider radius; Sweep: the exact Minkowski sum of the capsule axis and the sweep segment, inflated by the agent's collider radius). Zero-length sweeps (Start == End) degenerate to the static capsule test. Use Trace for upright light pillars, standing AoE volumes and vertical beam checks; Sweep for lunge, charge and wide vertical swing corridors.

视野追踪:输入 FViewTracePoints(起始位置 + 选择点集),对点集构建视野体积索敌。

View trace: takes FViewTracePoints (start location + selection points) and targets agents inside the view volume built from the points.

锥形索敌:Origin + Direction、Length 长度、Angle 半角(度)。

Cone targeting: Origin + Direction, Length, and Angle half-angle in degrees.

按 SortMode 与 SortOrigin 原地排序实体句柄数组(转发到 HashGrid 子系统)。

Sorts the entity-handle array in place by SortMode and SortOrigin (forwarded to the HashGrid subsystem).

在指定位置生成合批视觉特效("Batched" 指以 SubType 为键的 Niagara 合批渲染系统)。AttachToEntity 有效时附着到实体(覆盖 SpawnLocation/Rotation);OwnerEntity 为可选归属实体。网络模式下锁步外的 BP 调用会以纯本地方式生成 FX 宿主(视觉不破坏确定性)并登记供 resync 重链。

Spawns batched visual effects at the given location ("Batched" refers to the batched rendering system keyed by SubType for Niagara batching). When AttachToEntity is valid the FX attaches to it (overriding SpawnLocation/Rotation); OwnerEntity is an optional owning entity. In networked mode an off-lockstep BP call spawns the FX host local-only (visuals never corrupt determinism) and registers it for resync re-link.

四种运动模式的投射物生成(转发到 UMassBattleProjectileSubsystem):Static(停留在 FromPoint 不飞行——地雷 / 陷阱 / 炮台锚点)、Interped(位置随时间由 FromPoint 插值至 ToPoint/ToTarget,并由配置的逐轴偏移曲线塑形)、Ballistic(按 FromPitch 或 FromSpeed 模式解算发射初速、利用 TargetVelocity 做预测迭代,使抛物线落在目标)、Tracking(沿 Direction 发射后以速度 / 前向加速度 / 横向转向加速度追踪 ToTarget,可选移动预测)。资产的 MovementMode 必须与节点模式匹配,否则生成失败。FromPoint 为发射点,Instigator 为发起者,IgnoreEntities 为碰撞排除集。网络模式下锁步外调用会被拦截——请走锁步命令路径生成。

Projectile spawning in four motion modes (forwarded to UMassBattleProjectileSubsystem): Static (stays at FromPoint with no flight — mine / trap / turret anchor), Interped (position interpolated from FromPoint toward ToPoint/ToTarget over time, shaped by the config's per-axis offset curves), Ballistic (launch velocity solved in FromPitch or FromSpeed mode with TargetVelocity prediction iterations so the free-fall arc lands on the target), Tracking (launches along Direction, then homes in on ToTarget with speed / forward acceleration / lateral turn acceleration and optional movement prediction). The asset's MovementMode must match the node's mode or the spawn fails. FromPoint is the launch point, Instigator the launcher, IgnoreEntities the collision exclusion set. In networked mode off-lockstep calls are blocked — spawn through the lockstep command path.

弹道速度解算(转发到 Projectile 子系统;1.19.20 起 C++/BP 节点名首字母改为小写 solve…):给定发射点 / 目标点 / 重力,由俯仰角(PitchAngle 叠加到直视仰角,钳制 ±89.9°)或固定初速度(可带 bFavorHighArc 选高抛解,垂直特例直接处理)解出 LaunchVelocity——无实数解 / 判别式为负时 Succeed=false 且不写 LaunchVelocity;WithPrediction 版本每轮迭代重新瞄准 ToPoint + TargetVelocity × 飞行时间 补偿目标运动,任一轮无解即失败。

Trajectory solving (forwarded to the Projectile subsystem; as of 1.19.20 the C++/BP node names start lowercase, solve…): given launch point / target / gravity, solves LaunchVelocity from a pitch angle (PitchAngle added to the look-at pitch, clamped to ±89.9°) or a fixed speed (with bFavorHighArc selecting the high-arc solution; vertical special cases handled directly) — when no real solution exists / the discriminant is negative, Succeed=false and LaunchVelocity is left untouched; the WithPrediction variants re-aim at ToPoint + TargetVelocity × flight time each iteration to compensate target motion, failing when any iteration has no solution.

四种模式的模板版投射物生成:以 TemplateData(预构建的 FEntityTemplateData,来自 MakeProjectileTemplateFromDataAsset 或注册表)替代配置资产。

Template-based projectile spawning in the four modes: replaces the config asset with a prebuilt TemplateData (from MakeProjectileTemplateFromDataAsset or the registry).

对 Entities 列表施加点伤害 + debuff(转发到 UMassBattleSubsystem):DmgInstigator(引发者)/ DmgCauser(致害者)/ HitFromLocation(击打方向来源)与 FDamage_Point / FDebuff_Point 配置;结果写入 DamageResults。

Applies point damage + debuff to the Entities list (forwarded to UMassBattleSubsystem): DmgInstigator / DmgCauser / HitFromLocation plus FDamage_Point / FDebuff_Point configs; results go into DamageResults.

以 Origin 为球心的范围伤害 + debuff:FDamage_Radial / FDebuff_Radial 内含半径、衰减等;KeepCount 限制结果数量。

Radial damage + debuff centered at Origin: FDamage_Radial / FDebuff_Radial carry radius, falloff, etc.; KeepCount limits the result count.

线段扫掠伤害 + debuff:StartLocation → EndLocation,FDamage_Beam / FDebuff_Beam。

Beam (segment sweep) damage + debuff: StartLocation → EndLocation with FDamage_Beam / FDebuff_Beam.

清空已注册资产缓存(转发到 UMassBattleSubsystem)。

Clears the registered-asset cache (forwarded to UMassBattleSubsystem).

已弃用——用 SetSimConfig 替代。设置步长 / 安全步长 / 帧分摊 / 确定性,转发到 UMassBattleSubsystem::SetTimingConfig。

Deprecated — use SetSimConfig instead. Sets step time / safe step time / frame spreading / determinism, forwarded to UMassBattleSubsystem::SetTimingConfig.

设置模拟配置(转发到 UMassBattleSubsystem::SetSimConfig):步长 / 安全步长 / 帧分摊 / 确定性。请在生成 agent 之前设置——游戏中途修改影响后续 tick。定点数学开关(MoveProcessorFP)属 WIP 功能,不在此暴露——由子系统 bUseFixPointMath 属性控制(仅 C++,对 BP 隐藏);旧版此处的 bInFixPointMath 参数已移除。

Sets the sim config (forwarded to UMassBattleSubsystem::SetSimConfig): step time / safe step time / frame spreading / determinism. Apply before spawning agents — changing mid-game affects subsequent ticks. The fixed-point math switch (MoveProcessorFP) is a WIP feature and is NOT exposed here — it is controlled by the subsystem's bUseFixPointMath property (C++ only, hidden from BP); the former bInFixPointMath parameter has been removed.

暂停 / 恢复游戏逻辑 tick(转发到 UMassBattleSubsystem::PauseGame / ResumeGame)。暂停期间逻辑 tick 停止推进——agent、投射物与锁步指令冻结;引擎时间不暂停。恢复时逻辑 tick 从冻结处继续;未处于用户暂停时 Resume 为无操作(不会清除网络失步恢复类暂停)。

Pauses / resumes the game logic tick (forwarded to UMassBattleSubsystem::PauseGame / ResumeGame). While paused the logic tick stops advancing — agents, projectiles and lockstep commands freeze; engine time is not paused. Resuming advances the logic tick from where it froze; Resume is a no-op when the game was not user-paused (does not clear network-desync recovery pauses).

综合暂停判定——只要逻辑 tick 冻结不推进即返回 true(用户暂停 / 网络失步恢复 / 等待服务器追帧);子系统缺失返回 false。

Composite pause check — true whenever the logic tick is frozen for ANY reason (user pause, network desync recovery pause, server catch-up wait); false when the subsystem is missing.

注入式手动 resync 触发——强制本地/服务器快照 resync + 快进(FF),绕过自然失步检测,用于测试/调试(转发到 UMassBattleNetworkSubsystem::TriggerLocalResync / TriggerServerResync)。

Injection-style manual resync triggers — force a local/server snapshot resync + fast-forward, bypassing natural desync detection, for testing/debugging (forwarded to UMassBattleNetworkSubsystem::TriggerLocalResync / TriggerServerResync).

设置确定性校验的目标 tick 列表与日志开关(位置 / 旋转 / 追踪结果),用于对比双端状态。

Sets the determinism-verification target tick list and log toggles (location / rotation / trace result) for cross-peer state comparison.

把 DeltaTime 追加进 DeltaTimeBuffer,对 Duration 秒窗口求平均 FPS(UMassBattleSubsystem::CalculateAverageFPS 静态实现)。

Appends DeltaTime into DeltaTimeBuffer and computes the average FPS over the Duration-second window (static UMassBattleSubsystem::CalculateAverageFPS).

返回全局实体与池化对象计数快照(结构见 FMassBattleGlobalCounts):实体计数按 tag 空查询 / FAgentTag / FProjectileTag / FLootTag / FBatchedFxTag 统计(池内实体保留 tag,故两者皆计);宿主与组件计数经单次遍历 FHostControllerTag 查询按 config fragment 分型得出,音频组件另加宿主子系统的池内数量。每次调用遍历 EntityManager——按 UI 频率调用,勿每模拟 tick 调用。

Returns a snapshot of global entity and pooled-object counters (see FMassBattleGlobalCounts): entity counts come from tag queries — empty / FAgentTag / FProjectileTag / FLootTag / FBatchedFxTag (pooled entities keep their tags, so both are counted); host and component counts come from a single walk over the FHostControllerTag query dispatched by config fragment, with pooled audio components added from the host subsystem. Each call walks the EntityManager — call at UI cadence, not per simulation tick.

返回各池状态快照(结构见 FMassBattlePoolState):全部 7 个宿主池(含 FxCPU——LogPoolStats 不打印它)+ 投射物 / 战利品实体池 + 音频组件池。开销极低——仅 volatile 读计数器,不遍历 EntityManager(允许滞后一 tick)。Spawns / FromPool / Fresh 每 HostSubsystem::ExecuteTick 重置。

Returns a per-pool state snapshot (see FMassBattlePoolState): all 7 host pools (FxCPU included — LogPoolStats misses it) + the projectile / loot entity pools + the audio component pool. Very cheap — direct volatile counter reads, no EntityManager walk (may be one tick stale). Spawns / FromPool / Fresh reset every HostSubsystem::ExecuteTick.

打印各对象池统计(九个池开关:actor/fx/sound/projectile/agent/loot 宿主池 + projectile/loot 实体池 + audio 组件池)。

Logs pool statistics (nine pool toggles: actor/fx/sound/projectile/agent/loot host pools + projectile/loot entity pools + audio component pool).

已弃用——BP 用户请用 MakeTemplateDataFromDataAsset(按资产类型自动分发)。C++ 内部生成路径继续直接使用。从 agent 配置资产构建 FEntityTemplateData。

Deprecated — BP users should call MakeTemplateDataFromDataAsset (auto-dispatches by asset type). C++ internal spawn paths keep using this directly. Builds FEntityTemplateData from an agent config asset.

按资产类型自动分发:UMassBattleAgentConfigDataAsset → agent 模板;UMassBattleProjectileConfigDataAsset → 投射物模板;UMassBattleLootConfigDataAsset → 战利品模板;未知类型记 Warning 并返回空模板。资产无效直接返回空模板。

Auto-dispatches by asset type: UMassBattleAgentConfigDataAsset → agent template; UMassBattleProjectileConfigDataAsset → projectile template; UMassBattleLootConfigDataAsset → loot template; unknown types log a Warning and return an empty template. Invalid assets return an empty template directly.

把模板数据注册进网络快照注册表(转发到 UMassBattleNetworkSubsystem::RegisterNetworkTemplateData),返回实际 Key(Key 为空时自动生成)。

Registers template data into the network snapshot registry (forwarded to UMassBattleNetworkSubsystem::RegisterNetworkTemplateData), returning the actual key (auto-generated when Key is empty).

按 Key 获取已注册快照模板;Key 未注册时 bFound=false 并返回空模板。

Gets a registered snapshot template by key; bFound=false with an empty template when the key is not registered.

按 Key 注销快照模板(转发到网络子系统)。

Unregisters a snapshot template by key (forwarded to the network subsystem).

已弃用(同 agent 版理由)。从投射物配置资产构建模板。

Deprecated (same rationale as the agent version). Builds a template from a projectile config asset.

向服务器发送锁步指令(客户端侧)。自动分流:大负载(≥ MassBattle.AutoFloodSwitchBytes,默认 16KB)透明切到 TCP 块 + UDP 引用命令;小负载走 UDP RPC。薄封装:从 WorldContext 解析第一个 PlayerController 并转发到 AMassBattleNetworkPlayerControllerBase::SendLockstepCommandToServer。ExtraDeferTicks 把执行推迟到基准 + K 缓冲之外(ExecuteTick = 基准 + K + ExtraDeferTicks)。

Sends a lockstep command to the server (client side). Auto-flood: large payloads (≥ MassBattle.AutoFloodSwitchBytes, default 16KB) transparently switch to a TCP block + UDP reference command; small payloads use a UDP RPC. Thin wrapper: resolves the first PlayerController from the WorldContext and forwards to AMassBattleNetworkPlayerControllerBase::SendLockstepCommandToServer. ExtraDeferTicks defers execution beyond the K-buffer (ExecuteTick = base + K + ExtraDeferTicks).

向所有客户端广播锁步指令(服务器侧)。自动分流语义同 SendLockstepCommandToServer;从 WorldContext 解析 GameMode 并转发到 AMassBattleNetworkGameModeBase::SendLockstepCommandToClients。

Broadcasts a lockstep command to all clients (server side). Auto-flood semantics identical to SendLockstepCommandToServer; resolves the GameMode from the WorldContext and forwards to AMassBattleNetworkGameModeBase::SendLockstepCommandToClients.

【NavMesh-A* 失步修复】导出流场基底(场自身数据结构——Grid 格子 / NavMesh 图,紧凑量化)并锁步广播到全端:全端(含服务器)导入同一份字节并本地计算路径——引擎 navmesh 查询链彻底退出锁步路径。仅服务器端可用(从 WorldContext 解析 GameMode,转发到 AMassBattleNetworkGameModeBase::SendLockstepCommandToClients_RebuildFlowField);服务器构建流场后调用,重建后再次调用。晚加入者自动补发;补发幂等。

[NavMesh-A* desync fix] Exports a flow field's substrate (its own data structure — Grid cells / NavMesh graph, compactly quantized) and lockstep-broadcasts it to every peer: every peer (server included) imports the SAME bytes and computes paths locally — the engine navmesh query chain leaves the lockstep path entirely. Server-side only (resolves the GameMode from the world context and forwards to AMassBattleNetworkGameModeBase::SendLockstepCommandToClients_RebuildFlowField); call after the server builds the field and again after any rebuild. Late joiners are re-fed automatically; re-delivery is idempotent.

调试用网络环境模拟——一次调用同时损伤两条路径:UE 的 UDP RPC 流量(设置 net.PktLag / net.PktLagVariance / net.PktLoss / net.PktDuplicate 引擎 cvar,进程级)与自定义 TCP 快照 / 锁步块路径(FMassBattleSnapshotTcpTransport 的到期队列 + 逐帧丢弃 + 令牌桶限速,进程级静态)。TCP 控制帧(认证 / 心跳)永远直发;TCP 侧刻意无重复 / 乱序旋钮(TCP 设计上去重且保序)。PIE 单进程一次调用即覆盖两条路径的双方向;独立多进程:在想受影响的进程上各调用。启用时记一条响亮 Warning;全零设置或 Clear 关闭(Clear 同时把 net.PktLag 系列归零);Get 读取当前生效的 TCP 路径设置。仅 TCP 路径的镜像 cvar:MassBattle.NetEmulation.*。

Debug network-environment emulation — one call impairs BOTH paths at once: UE's UDP RPC traffic (sets the net.PktLag / net.PktLagVariance / net.PktLoss / net.PktDuplicate engine cvars, process-wide) and the custom TCP snapshot / lockstep-block path (due-time queue + per-frame drop + token-bucket throttle inside FMassBattleSnapshotTcpTransport, process-global statics). TCP control frames (auth / heartbeat) always bypass; the TCP side deliberately has no duplicate/reorder knobs (TCP dedupes and preserves order by design). In PIE one call covers both directions of both paths (single process); standalone multi-process: call on each process you want impaired. Enabling logs a loud Warning; all-zero settings or Clear disable (Clear also resets the net.PktLag family to 0); Get reads the currently effective TCP-path settings. Mirror cvars for the TCP path alone: MassBattle.NetEmulation.*.

大世界坐标编码/解码:把 64 位 double FVector 拆成三个 int32 格子坐标 + 三个 float 偏移,在锁步负载中保留 float 精度(int32 格子精确保存大数,float 偏移只带格子内余量)。GridSize 写死 10000,两端必须一致。仅当远离世界原点时才有必要——靠近原点直接 float 转换已足够精确。输出可直接接入 SendLockstepCommand 的 IntPayload/FloatPayload。解码输入不足 3 项时记 Error 并返回 ZeroVector。

Large-world-coordinate codec: splits a 64-bit double FVector into three int32 grid coords plus three float offsets, preserving float precision in the lockstep payload (int32 cells hold the magnitude exactly, float offsets carry only the sub-cell remainder). GridSize is hard-coded to 10000 and must match on both ends. Only necessary far from the world origin — near it, a plain float cast is precise enough. Outputs plug directly into SendLockstepCommand's IntPayload/FloatPayload. Decoding with fewer than 3 entries logs an Error and returns ZeroVector.

批量版本:编码 N 个坐标为 3*N int32 + 3*N float(X,Y,Z 每坐标交错);解码 3*N 对还原 N 个坐标。解码时 int/float 数量不等记 Error 并取最小值组数。

Batch variants: encode N locations into 3*N int32 + 3*N float (X,Y,Z interleaved per location); decode 3*N pairs back to N locations. Decoding with mismatched int/float counts logs an Error and decodes the min group count.

立即生成:以预构建模板(BaseTemplate)在矩形/圆形区域生成 agent,返回实体句柄数组。

Immediate spawn: generates agents in a rectangular/circular region from a prebuilt template (BaseTemplate), returning the entity-handle array.

立即生成:以配置资产(DataAsset)构建模板后在矩形/圆形区域生成。

Immediate spawn: builds the template from a config asset (DataAsset), then generates in a rectangular/circular region.

延迟版:把生成请求排队,由 UMassBattleAgentSubsystem::ExecuteTick 批量处理。Substeps 控制分摊(0 = 单 tick 全部生成;>0 = 分摊到 Substeps+1 个 tick);OnFinished 在所有生成完成后触发并携带句柄。

Deferred versions: queue the spawn request for batch processing in UMassBattleAgentSubsystem::ExecuteTick. Substeps controls spreading (0 = all spawns in one tick; >0 = spread across Substeps+1 ticks); OnFinished fires when all spawning completes with the handles.

设置生成器随机种子(转发到 Agent 子系统)——决定出生随机性(乘数范围 / 形状随机偏移)的确定性来源。

Sets the spawner random seed (forwarded to the Agent subsystem) — the determinism source for spawn randomness (multiplier ranges / shape random offsets).

激活/停用单个或多个 agent:设置/清除 ActivatedFlag。轻量操作——不触发 archetype 迁移。

Activates/deactivates one or more agents by setting/clearing the ActivatedFlag. Lightweight — no archetype migration.

生成战利品实体(转发到 Agent 子系统):LootConfigDataAsset 配置、SpawnTransform 生成变换、FLootMultipliers_Ballistic 抛物线乘数、Spawner 归属实体(记为拥有者)。战利品自生成变换起按抛物线弹出,随后可被拾取。网络模式下锁步外的 BP 调用被拦截(战利品宿主会消耗全局 UID——请走锁步命令路径生成)。

Spawns a loot entity (forwarded to the Agent subsystem): LootConfigDataAsset, SpawnTransform, FLootMultipliers_Ballistic ballistic multipliers, and the Spawner owning entity (recorded as owner). The loot flies out on a ballistic arc from the spawn transform, then becomes collectible. In networked mode off-lockstep BP calls are blocked (loot hosts consume the global UID — spawn via the lockstep command path).

使 agent 的导航(FNavigation)改为跟随给定流场,而非逐 agent 寻路(转发到 Agent 子系统);传 nullptr 停止使用流场。流场在被引用期间必须保持存活。

Directs the agent's navigation (FNavigation) to follow the given flow field instead of per-agent pathfinding (forwarded to the Agent subsystem); pass nullptr to stop using flow fields. The flow field must stay alive while referenced.

设置接收该实体游戏事件(死亡、受击、生成通知)的 Actor:写入 agent 的 FAgentEvent 或投射物的 FProjectileEvent fragment(转发到对应子系统)。该 Actor 须实现对应的事件接口。

Sets the actor that receives this entity's gameplay events (death, hit, spawn notifications): writes the receiver into the agent's FAgentEvent or the projectile's FProjectileEvent fragment (forwarded to the matching subsystem). The actor must implement the corresponding event interface.

用实体句柄数组做重叠检测:把 Current 与 Accumulated 转 TSet 后并行(MBParallelFor)求差——新增(在 Current 不在 Accumulated)写入 BeginOverlaps,离开(反之)写入 EndOverlaps;然后原地稳定移除 EndOverlaps 并把 BeginOverlaps 追加进 Accumulated。确定性保证:TSet 只用 Contains()(与桶布局无关),并行写互斥槽位,输出按输入索引序生成——输入有序则输出确定。

Overlap detection on entity-handle arrays: converts Current and Accumulated to TSets and computes the difference in parallel (MBParallelFor) — newcomers (in Current, not in Accumulated) go to BeginOverlaps, leavers (the reverse) to EndOverlaps; then removes EndOverlaps in-place stably and appends BeginOverlaps into Accumulated. Determinism: TSet is only queried via Contains() (bucket layout irrelevant), the parallel pass writes disjoint per-index slots, and all output loops walk inputs in index order — deterministic inputs yield deterministic outputs.

同 ProcessOverlap_EntityArray,但输入为 FTraceResult 数组——身份只按 Entity 判定(TSet 存句柄而非完整结果),其余流程一致。

Same as ProcessOverlap_EntityArray but on FTraceResult arrays — identity is judged by Entity only (the TSet stores handles, not full results); the rest of the flow is identical.

对 agents 设置 bStopActiveMovement,使 MoveProcessor 把它们减速到零。不清除目标或 MoveTo 标志。

Sets bStopActiveMovement on the agents, causing the MoveProcessor to decelerate them to zero. Does not clear goals or MoveTo flags.

立即停止 agents 的全部移动:速度清零、清除目标、清除 MoveTo 标志、重置寻路状态。

Immediately stops all movement on the agents: zeros velocity, clears goals, clears MoveTo flags, and resets pathfinding state.

立即切换 agent 的活跃行为(EBehaviorState,转发到 Agent 子系统):清除全部行为旗标,重置各行为 fragment(巡逻 / 攻击 / 增援 / 返回)与移动目标,然后激活目标状态。配置 fragment 未启用的行为(以及 Return 请求)降级为 Idle。无效句柄、濒死 agent 或移动锁定的 agent(目标非 Idle 时)返回 false。

Immediately switches an agent's active behavior (EBehaviorState, forwarded to the Agent subsystem): clears every behavior flag, resets the per-behavior fragments (patrol/attack/reinforce/return) and movement-to-goal, then activates the target state. Behaviors whose config fragment is disabled (and Return requests) degrade to Idle. Returns false for invalid handles, dying agents, or MoveTo-locked agents (unless switching to Idle).

生成矩形网格阵型的逐 agent 目标位置。内部:清空输出 → 校验 MA/World/agents → 委托 UMassBattleFormationAlgorithms::GenerateGridFormationImpl。agent 按当前空间位置(读 FLocating.Location)分配槽位以保持相对顺序、避免交叉路径;分配模式 KeepFormation(保持空间排列)或 ReformTheLine(就近分配槽位);可视化经 LineBatchComponent,Shipping 可见。

Generates per-agent goal locations arranged in a rectangular grid formation. Internally: resets the output → validates MA/World/agents → delegates to UMassBattleFormationAlgorithms::GenerateGridFormationImpl. Agents are assigned to grid slots based on their current spatial position (reads FLocating.Location) to preserve relative ordering and avoid crossing paths; KeepFormation preserves spatial arrangement, ReformTheLine assigns nearest slots; visualization renders via LineBatchComponent, visible in Shipping.

生成圆形/多边形阵型的逐 agent 目标位置(极坐标网格模式)。内部结构同 GenerateGridFormation,委托 GenerateCircularFormationImpl。

Generates per-agent goal locations in a circular/polygonal formation (polar-grid mode). Internal structure mirrors GenerateGridFormation, delegating to GenerateCircularFormationImpl.

生成三角(楔形)阵型的逐 agent 目标位置:与 agent 生成系统共用同一形状数据结构(FAgentSpawnTriangleShapeData,定义于 MassBattleStructs.h——行自 1 槽顶点沿 ShapeDirection 递增到底边)。agent 按当前空间位置(读 FLocating.Location)分配阵型槽位以保持相对排列、避免路径交叉。内部结构同 GenerateGridFormation,委托 UMassBattleFormationAlgorithms::GenerateTriangleFormationImpl。

Generates per-agent goal locations arranged in a triangular (wedge) formation: uses the same shape-data struct family as the agent spawning system (FAgentSpawnTriangleShapeData, defined in MassBattleStructs.h — rows grow from a 1-slot apex along ShapeDirection to the base). Agents are assigned to formation slots based on their current spatial position (reads FLocating.Location) to preserve relative ordering and avoid crossing paths. Internal structure mirrors GenerateGridFormation, delegating to UMassBattleFormationAlgorithms::GenerateTriangleFormationImpl.

潜伏动作:延迟到给定数量的 MassBattle 模拟 tick 过去后继续。同一节点重复触发(仍在计数中)被忽略(与引擎 Delay 一致)。NumTicks <= 0 时下一个 MassBattle tick 即完成。实现:经 FLatentActionManager 注册 FMassBattleDelayTicksLatentAction,每帧用 UMassBattleSubsystem::GetTickCount() 比较目标值。

Latent action: delays until the given number of MassBattle simulation ticks have elapsed. Re-triggering the same node while it is already counting is ignored (matches engine Delay). NumTicks <= 0 completes on the next MassBattle tick. Implementation: registers FMassBattleDelayTicksLatentAction via FLatentActionManager, comparing against UMassBattleSubsystem::GetTickCount() each frame.

设置/查询 agent 控制模式:AI(恢复寻路/行为)或 PlayerDriven。查询失败返回 AI。

Sets/queries the agent control mode: AI (resume pathfinding/behavior) or PlayerDriven. The query returns AI on failure.

向 agent 添加移动输入,镜像 UPawnMovementComponent::AddMovementInput:每帧累积,由移动处理器消费。Scale 缩放方向向量;bForce 强制添加。

Adds movement input to an agent, mirroring UPawnMovementComponent::AddMovementInput: accumulates input per frame, consumed by the move processor. Scale scales the direction; bForce forces the addition.

经共享注册表把锁步 NetID 解析为绑定宿主(agent/projectile/loot 组件,或 replicated actor)。返回 UObject 需自行 Cast;bFound=false 当 ID 未知或宿主已注销。

Resolves a lockstep NetID to its bound host (agent/projectile/loot component, or a replicated actor) via the shared registry. Cast the returned UObject yourself; bFound=false when the ID is unknown or the host is gone.

检查是否启用了网络模式(UMassBattleSubsystem::bNetworkedMode);子系统缺失返回 false。

Checks whether networked mode is enabled (UMassBattleSubsystem::bNetworkedMode); false when the subsystem is missing.

获取目标执行 tick(CurrentTick + InputBufferTicks);子系统缺失返回 0。

Gets the target execution tick (CurrentTick + InputBufferTicks); 0 when the subsystem is missing.

把 FEntityHandle 转 UniqueID:经 UMassBattleSubsystem::FindUIDByEntity 反查;无效/不可解析 → -1 且 bFound=false。

Converts an FEntityHandle to its UniqueID via UMassBattleSubsystem::FindUIDByEntity; invalid/unresolvable → -1 with bFound=false.

批量版:逐个转换,无效/不可解析句柄输出 -1 占位——输出长度与输入对齐。可直接接入 SendLockstepCommand 的 IntPayload。

Batch version: converts each handle; invalid/unresolvable handles become -1 placeholders so the output stays length-aligned with the input. Plugs directly into SendLockstepCommand's IntPayload.

把 UniqueID 转 FEntityHandle:经 UMassBattleSubsystem::FindEntityByUID 正查;不可解析 → 无效句柄且 bFound=false。

Converts a UniqueID to its FEntityHandle via UMassBattleSubsystem::FindEntityByUID; unresolvable → an invalid handle with bFound=false.

批量版:经网络子系统的 ResolveUniqueIDs 逐个解析;不可解析的 ID 输出无效句柄占位,长度与输入对齐。

Batch version: resolves each ID via the network subsystem's ResolveUniqueIDs; unresolvable IDs become invalid-handle placeholders, length-aligned with the input.

检查玩家是否已完成 late-join 并完全进入游戏(转发到网络子系统)。

Checks whether a player has completed late-join and is fully in the game (forwarded to the network subsystem).

获取当前网络诊断统计(FMassBattleNetworkStats,转发到网络子系统);缺失返回默认结构。

Gets the current network diagnostic stats (FMassBattleNetworkStats, forwarded to the network subsystem); default struct when missing.

获取指定客户端的延迟(毫秒);子系统缺失返回 0。

Gets the ping for a specific client (milliseconds); 0 when the subsystem is missing.

记录逐实体失步诊断(仅编辑/开发,转发到网络子系统)。

Logs detailed per-entity desync diagnostics (editor/dev only, forwarded to the network subsystem).

把屏幕矩形(Start + WidthHeight)的四个角反投影到 Distance 处的世界点。先归一化矩形边界(与 WidthHeight 符号无关),按相机视角逆时针输出四角(供视野追踪构建法线向内的视锥平面);任一角的反投影失败返回 false。无世界或 PlayerController 返回 false。

Deprojects the four corners of a screen rect (Start + WidthHeight) to world points at Distance. Normalizes the rect bounds first (sign-independent of WidthHeight), outputs the four corners counter-clockwise from the camera's view (so view-trace frustum planes get inward-facing normals); returns false if any corner deprojects fail. False without a world or PlayerController.