MassBattleStructs.h
Source/MassBattle/Public/MassBattleStructs.h
概述 Overview
MassBattle 的集中数据结构定义文件。按用途分:查询与模板(FMassBattleQuery 带 All/Any/None 组合 + 优先级 + 128 位 flag 查询的惰性缓存查询结构、FMassBattleTemplate 蓝图实体模板)、战斗结果(FDmgResult / FHitDebuffInfo / FLaunchResult / FStatsResult / FLootClaimRequest 等并行收集→串行仲裁的 gatherer 载荷)、事件回调数据(F*Data 系列,携 UID 与事件时刻锚点的事件载荷)、Debug 绘制配置(FDebug*Config 系列,可骑 FParallelGatherer 收集后串行排空)、生成形状(FAgentSpawnRectangleShapeData / FAgentSpawnTriangleShapeData / FAgentSpawnPolygonShapeData)、网络(FMassBattleNetCommand 锁步指令容器、EFFSubstrateSyncMode 流场基底重发策略、FMassBattleNetEmulationSettings 调试网络环境模拟、FEntityHandleFixup 快照恢复句柄重映射)。确定性纪律贯穿全文:跨实体载荷一律用 UniqueID 而非 FEntityHandle 做排序键与引用。
Central data-structure file of MassBattle. By purpose: queries and templates (FMassBattleQuery — a lazily-cached query struct with All/Any/None composition, priority levels, and 128-bit flag queries; FMassBattleTemplate — Blueprint entity template), combat results (FDmgResult / FHitDebuffInfo / FLaunchResult / FStatsResult / FLootClaimRequest, etc. — parallel-gather → serial-arbitrate gatherer payloads), event callback data (the F*Data family, event payloads carrying UIDs and event-time anchors), debug-draw configs (the FDebug*Config family, rideable on FParallelGatherer for serial drain), spawn shapes (FAgentSpawnRectangleShapeData / FAgentSpawnTriangleShapeData / FAgentSpawnPolygonShapeData), networking (FMassBattleNetCommand lockstep command container, EFFSubstrateSyncMode flow-field substrate re-send strategy, FMassBattleNetEmulationSettings debug network-environment emulation, FEntityHandleFixup snapshot-restore handle remapping). Determinism discipline runs through everything: cross-entity payloads use UniqueID rather than FEntityHandle for sort keys and references.
FInheritFromInstigator USTRUCT
从发起者(spawning agent)向投射物继承参数的配置。整合所有继承开关,提供更干净的 API 和更好的可维护性。
Configuration for inheriting parameters from the instigator (spawning agent) to projectiles. Consolidates all inheritance flags for a cleaner API and better maintainability.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bInheritTraceQuery | bool | true | 从发起者的 FTrace fragment 继承追踪查询。Inherit the trace query from the instigator's FTrace fragment. |
bInheritDamage | bool | true | 从发起者的 FDamage fragment 继承所有伤害参数(伤害、百分比伤害、暴击倍数、暴击概率、伤害类型、伤害半径、查询、障碍检查、衰减)。Inherit all damage parameters from the instigator's FDamage fragment (Damage, PercentDmg, CritDmgMult, CritProbability, DmgType, DmgRadius, Query, bCheckObstacle, bUseFalloff). |
bInheritDebuff | bool | true | 从发起者的 FDebuff fragment 继承所有减益参数(击退、延时伤害、减速、衰减)。Inherit all debuff parameters from the instigator's FDebuff fragment (LaunchParams, TemporalDmgParams, SlowParams, bUseFalloff). |
bInheritEventReceiver | bool | true | 从发起者继承事件接收者。Inherit the event receiver from the instigator. |
FInheritFromSpawner USTRUCT
从生成者 agent 向战利品继承参数的配置(死亡掉落等)。镜像 projectile 侧的 FInheritFromInstigator,只保留对 loot 有意义的字段,由 FLootConfig_Final.InheritFromSpawner 携带。注意:故意不做 SubType 继承——SubType 命名空间是各实体类型独立定义的用户清单(继承 agent 索引会指向无关的 loot 子类型筛选)。
Configuration for inheriting parameters from the spawner agent to loot (drop-on-death etc.). Mirrors the projectile-side FInheritFromInstigator, keeping only the fields that make sense for loot; carried by FLootConfig_Final.InheritFromSpawner. NOTE: no SubType inheritance on purpose — SubType namespaces are independent per-entity-type user-defined lists (an inherited agent index would point at an unrelated loot subtype filter).
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bInheritEventReceiver | bool | true | 从生成者 agent 继承事件接收者——软引用取自 FAgentEvent,运行时裸 actor 取自 FAgentEventRT 兜底(组件绑定的 agent 接收者只有裸 actor)。Inherit the event receiver from the spawner agent — soft ptr from FAgentEvent, raw runtime actor from FAgentEventRT as fallback (component-bound agents carry the receiver only as a raw actor). |
bInheritFlowField | bool | true | 掉落时从生成者 agent 继承流场(地面检测来源)——取自死亡 agent 的 FNavigating/FNavigation。关闭则 loot 的 FlowField 为 null(地面检测走回退路径)。Inherit the spawner agent's FlowField (ground detection source) at drop time — taken from the dying agent's FNavigating/FNavigation. When off, the loot's FlowField stays null (ground detection falls back). |
FPriorityComposition USTRUCT
单个优先级级别的组合包装结构,包含构成该优先级 Any 组合的 fragments/tags。
Wrapper struct for a single priority level's composition, holding the fragments/tags that form an Any composition for this priority level.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Compositions | TArray<TObjectPtr<UScriptStruct>> | 空 | 此优先级的碎片/标签(Any 组合)。Fragments/tags for this priority level (Any composition). |
方法 Methods
判断组合列表是否为空。
Checks whether the composition list is empty.
Input
无参数。
No parameters.
Output
返回 Compositions.IsEmpty()。
Returns Compositions.IsEmpty().
FMassBattleQuery USTRUCT
独立查询结构,包含 FEntityQuery 的全部功能,并新增 MassBattle 特有的障碍物列表与 128 位 flag 查询。核心模式是脏标记 + 惰性重建:数据数组(AllList / AnyList / NoneList / Battle*FlagsList)被修改后置脏,访问缓存(GetAllComposition / GetAllFlagsBitmask 等)时按需重建,避免每次查询都做反射转换。提供 C++ 构造函数、链式 Fluent API(All / Any / None / Obstacles)与 ToEntityQuery() 转换(把 EBattleFlags 经 FlagRegistry 换算为 FName 标志列表)。
Standalone query struct with all FEntityQuery functionality plus MassBattle-specific obstacle lists and 128-bit flag queries. Core pattern is dirty-flag + lazy rebuild: mutating the data arrays (AllList / AnyList / NoneList / Battle*FlagsList) marks caches dirty; accessors (GetAllComposition / GetAllFlagsBitmask, etc.) rebuild on demand, avoiding reflection conversion on every query. Provides C++ constructors, a chained fluent API (All / Any / None / Obstacles), and ToEntityQuery() conversion (mapping EBattleFlags to FName flag lists via FlagRegistry).
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
AllList | TArray<TObjectPtr<UScriptStruct>> | 空 | 组合查询:AND,实体必须具备此列表中的所有碎片/标签。Composition query: AND — the entity must have ALL of these fragments/tags. |
AnyList | TArray<TObjectPtr<UScriptStruct>> | 空 | 组合查询:OR,实体必须具备至少一个碎片/标签。Composition query: OR — the entity must have AT LEAST ONE of these fragments/tags. |
NoneList | TArray<TObjectPtr<UScriptStruct>> | 空 | 组合查询:NOT,实体不能具备任何这些碎片/标签。警告:默认比 All/Any 更慢——网格查询对 None 无格级快速拒绝,只能逐实体检查。可选位集快速拒绝:MassBattleHashGridSubsystem.bEnableIntersectionComposition(项目设置 MassBattle|HashGrid|Agent,或 DefaultMassBattle.ini),默认关,每 agent 注册约 +20% 开销;None 查询占主导时开启。Composition query: NOT — the entity must have NONE of these fragments/tags. WARNING: slower than All/Any by default — grid queries check None per entity (no cell-level quick rejection). Opt-in fast reject: bEnableIntersectionComposition on MassBattleHashGridSubsystem (Project Settings > MassBattle > HashGrid, or DefaultMassBattle.ini) — off by default, ~20% extra per-agent registration; enable when None queries dominate. |
PriorityComposition | TArray<FPriorityComposition> | 空 | 优先级组合过滤器,索引 0 为最高优先级。匹配更早优先级的实体优先于匹配更晚级别的更近实体。留空禁用优先级过滤(零开销)。Priority composition filter (index 0 = highest priority). Entities matching earlier priority levels are preferred over closer entities matching later levels. Leave empty to disable priority filtering (zero overhead). |
BattleAllFlagsList | TArray<EBattleFlags> | 空 | 标志位查询:AND,实体必须拥有所有这些标志。Flag query: AND — the entity must have ALL of these flags. |
BattleAnyFlagsList | TArray<EBattleFlags> | 空 | 标志位查询:OR,实体必须拥有至少一个标志。Flag query: OR — the entity must have AT LEAST ONE of these flags. |
BattleNoneFlagsList | TArray<EBattleFlags> | 空 | 标志位查询:NOT,实体不能拥有任何这些标志。Flag query: NOT — the entity must have NONE of these flags. |
ObstacleList | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 用于障碍物检测的对象类型列表。List of object types used for obstacle detection. |
AllComposition / AnyComposition / NoneComposition | FMassArchetypeCompositionDescriptor (private, mutable) | — | 私有缓存:由对应列表惰性构建的组合描述符。Private caches: composition descriptors lazily built from the corresponding lists. |
AllFlagsBitmask_Cache … NoneFlagsBitmaskHigh_Cache | int64 (private, mutable) | 0 | 私有缓存:标志位掩码(低位 0-63 与高位 64-127 各三份,对应 All/Any/None)。Private caches: flag bitmasks (low 0-63 and high 64-127, three each for All/Any/None). |
bIsAllCompDirty … bIsFlagsCacheDirty | bool (private, mutable) | false | 私有脏标记:列表被修改后置脏,访问缓存时惰性重建。Private dirty flags: set on list mutation; caches rebuild lazily on access. |
方法 Methods
默认构造,全部缓存标记为脏。
Default constructor, marking all caches dirty.
Input
无参数。
No parameters.
Output
无返回值。副作用:置全部脏标记。
No return value. Side effect: all dirty flags set.
带缓存控制:为 true 时置脏;为 false 时全部脏标记清为 false(假定列表此后不再修改)。
Constructor with cache control: marks dirty when true; clears all dirty flags when false (assuming the lists will not be modified afterwards).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
bUpdateCache | bool | 是否把缓存置为待重建状态。Whether to mark the caches for rebuild. |
Output
无返回值。副作用:设置四个脏标记。
No return value. Side effect: sets the four dirty flags.
便捷 C++ 构造:用 MoveTemp 搬入三组列表,置脏后立即 UpdateCache()。
Convenience C++ constructor: moves in the three lists, marks dirty, then updates the cache immediately.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InAnd | TArray<TObjectPtr<UScriptStruct>> | AND 组合列表。AND composition list. |
InOr | TArray<TObjectPtr<UScriptStruct>> | OR 组合列表。OR composition list. |
InNot | TArray<TObjectPtr<UScriptStruct>> | NOT 组合列表。NOT composition list. |
Output
无返回值。副作用:搬入数据并构建缓存。
No return value. Side effect: moves in data and builds caches.
与上一构造函数相同,但由 bUpdateCache 决定是否立即重建缓存。
Same as the previous constructor, but whether caches rebuild immediately is controlled by bUpdateCache.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InAnd | TArray<TObjectPtr<UScriptStruct>> | AND 组合列表。AND composition list. |
InOr | TArray<TObjectPtr<UScriptStruct>> | OR 组合列表。OR composition list. |
InNot | TArray<TObjectPtr<UScriptStruct>> | NOT 组合列表。NOT composition list. |
bUpdateCache | bool | 是否立即重建缓存。Whether to rebuild caches immediately. |
Output
无返回值。副作用:搬入数据;按需构建缓存。
No return value. Side effect: moves in data; builds caches on demand.
完整 C++ 构造:三组组合 + 障碍物对象类型列表,置脏并立即重建缓存。
Full C++ constructor: three composition lists plus the obstacle object-type list; marks dirty and rebuilds caches immediately.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InAnd | TArray<TObjectPtr<UScriptStruct>> | AND 组合列表。AND composition list. |
InOr | TArray<TObjectPtr<UScriptStruct>> | OR 组合列表。OR composition list. |
InNot | TArray<TObjectPtr<UScriptStruct>> | NOT 组合列表。NOT composition list. |
InObstacles | TArray<TEnumAsByte<EObjectTypeQuery>> | 障碍物对象类型列表。Obstacle object-type list. |
Output
无返回值。副作用:搬入数据并构建缓存。
No return value. Side effect: moves in data and builds caches.
链式 Fluent API:把模板参数(必须是 FMassFragment / FMassTag / FMassChunkFragment / FMassSharedFragment / FMassConstSharedFragment 派生)加入 AND 列表,置 bIsAllCompDirty。重载提供左值(返回引用)与右值(返回 MoveTemp)两种链式形态。
Fluent API: adds the template args (must derive from FMassFragment / FMassTag / FMassChunkFragment / FMassSharedFragment / FMassConstSharedFragment, checked at compile time) to the AND list and sets bIsAllCompDirty. Overloads provide lvalue (reference) and rvalue (MoveTemp) chaining.
Input
模板参数 TArgs:组件类型列表(编译期 CheckType static_assert)。
Template args TArgs: component types (compile-time CheckType static_assert).
Output
返回自身引用(支持链式调用)。副作用:向 AllList 添加条目并置脏。
Returns a self reference for chaining. Side effect: appends to AllList and marks dirty.
与 All 相同,但加入 OR 列表并置 bIsAnyCompDirty。
Same as All, but appends to the OR list and sets bIsAnyCompDirty.
Input
模板参数 TArgs:组件类型列表。
Template args TArgs: component types.
Output
返回自身引用。副作用:向 AnyList 添加条目并置脏。
Returns a self reference. Side effect: appends to AnyList and marks dirty.
与 All 相同,但加入 NOT 列表并置 bIsNoneCompDirty。
Same as All, but appends to the NOT list and sets bIsNoneCompDirty.
Input
模板参数 TArgs:组件类型列表。
Template args TArgs: component types.
Output
返回自身引用。副作用:向 NoneList 添加条目并置脏。
Returns a self reference. Side effect: appends to NoneList and marks dirty.
设置障碍物检测的对象类型列表——覆盖先前 ObstacleList 中的任何值。
Sets the object-type list for obstacle detection, overwriting any previous ObstacleList values.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InObstacles | std::initializer_list<TEnumAsByte<EObjectTypeQuery>> | 一个或多个 EObjectTypeQuery 枚举值。One or more EObjectTypeQuery values. |
Output
返回自身引用。副作用:清空并重填 ObstacleList。
Returns a self reference. Side effect: clears and refills ObstacleList.
从此战斗查询构造基础 FEntityQuery:复制组合列表,把 Battle*FlagsList 经 UMassAPIFlagSettings::FlagRegistry 反查为 FName 标志列表(查不到时用 StaticEnum 的名字字符串),忽略 MassBattle 特有参数(ObstacleList / PriorityComposition)。结果查询调用 MarkCacheDirty()。
Builds a base FEntityQuery from this battle query: copies the composition lists, converts Battle*FlagsList to FName flag lists via reverse lookup in UMassAPIFlagSettings::FlagRegistry (falling back to the StaticEnum name string), and ignores MassBattle-specific parameters (ObstacleList / PriorityComposition). The result calls MarkCacheDirty().
Input
无参数。
No parameters.
Output
返回配置好的 FEntityQuery;flag 大于 EBattleFlags_MAX 的条目映射为 NAME_None。
Returns a configured FEntityQuery; entries at or beyond EBattleFlags_MAX map to NAME_None.
组合描述符访问器:脏时经 BuildCompositionFromStructs(按结构体运行时类型分拣进 Fragments / Tags / ChunkFragments / SharedFragments / ConstSharedFragments 位集)重建,然后返回缓存。
Composition descriptor accessors: rebuild via BuildCompositionFromStructs (sorting structs by runtime type into Fragments / Tags / ChunkFragments / SharedFragments / ConstSharedFragments bitsets) when dirty, then return the cache.
Input
无参数。
No parameters.
Output
返回对应组合描述符的常量引用。副作用:必要时重建缓存并清脏。
Returns a const reference to the composition descriptor. Side effect: rebuilds and clears the cache when dirty.
标志位掩码访问器(六个:All/Any/None × Low/High)。脏时经 BuildFlagsCache 重建:每个 flag 按数值位(≥64 进高位,否则进低位)置位;>= EBattleFlags_MAX 的条目忽略。
Flag bitmask accessors (six: All/Any/None × Low/High). When dirty, rebuilds via BuildFlagsCache: each flag sets its numeric bit (≥64 into the high mask, otherwise low); entries at or beyond EBattleFlags_MAX are ignored.
Input
无参数。
No parameters.
Output
返回缓存的 int64 掩码。
Returns the cached int64 bitmask.
返回优先级级别数量(PriorityComposition.Num())。
Returns the number of priority levels (PriorityComposition.Num()).
Input
无参数。
No parameters.
Output
返回优先级级别数。
Returns the priority level count.
取指定索引的优先级级别(0 = 最高优先级);索引无效返回 nullptr。
Gets the priority level at the given index (0 = highest priority); returns nullptr when the index is invalid.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Index | int32 | 优先级级别索引。Priority level index. |
Output
返回该级别的指针;无效索引返回 nullptr。
Returns the level pointer, or nullptr for an invalid index.
判断是否启用了优先级过滤(PriorityComposition 非空)。
Checks whether priority filtering is enabled (non-empty PriorityComposition).
Input
无参数。
No parameters.
Output
返回是否启用优先级过滤。
Returns whether priority filtering is enabled.
把所有缓存标记为脏(组合与标志位全部)。
Marks all caches dirty (composition and flags).
Input
无参数。
No parameters.
Output
无返回值。副作用:置全部四个脏标记。
No return value. Side effect: sets all four dirty flags.
判断查询是否为空——所有数组(AllList / AnyList / NoneList / 三个 flag 列表 / PriorityComposition 中全部级别)均为空。
Checks whether the query is empty — all arrays (AllList / AnyList / NoneList / the three flag lists / every level of PriorityComposition) are empty.
Input
无参数。
No parameters.
Output
返回查询是否无任何要求。
Returns whether the query has no requirements.
FMassBattleTemplate USTRUCT
MassBattle 专用模板结构,镜像 FEntityTemplate 但使用 TArray<EBattleFlags> 便于在战斗上下文中编辑。
A specialized template struct for MassBattle mirroring FEntityTemplate, but using TArray<EBattleFlags> for easier editing in battle contexts.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Tags | TArray<FInstancedStruct> | 空 | 要添加到实体的 tag 列表(BaseStruct 限定 MassTag)。List of tags to add to the entity (BaseStruct restricted to MassTag). |
Fragments | TArray<FInstancedStruct> | 空 | 带初始值的 fragment 列表(BaseStruct 限定 MassFragment)。List of fragments with their initial values (BaseStruct restricted to MassFragment). |
MutableSharedFragments | TArray<FInstancedStruct> | 空 | 可变 shared fragment 列表(BaseStruct 限定 MassSharedFragment)。List of mutable shared fragments (BaseStruct restricted to MassSharedFragment). |
ConstSharedFragments | TArray<FInstancedStruct> | 空 | 常量 shared fragment 列表(BaseStruct 限定 MassConstSharedFragment)。List of constant shared fragments (BaseStruct restricted to MassConstSharedFragment). |
BattleFlags | TArray<EBattleFlags> | 空 | 实体初始战斗标志列表,会被转换为 FEntityTemplate 的 Flags。List of initial battle flags, converted to FEntityTemplate Flags. |
FObjectTypes USTRUCT
对象类型列表包装,用于追踪查询。
Object-type list wrapper for trace queries.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
ObjectTypes | TArray<TEnumAsByte<ECollisionChannel>> | 空 | 用于追踪查询的对象类型列表。List of object types for trace queries. |
FViewTracePoints USTRUCT
视野追踪的输入点集:起始位置 + 用于选择实体的点集。
View-trace input points: a start location plus the set of points used for selecting entities.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
ViewPoint | FVector | ZeroVector | 视野追踪的起始位置。The starting location of the view trace. |
SelectionPoints | TArray<FVector> | 空 | 用于在视野追踪中选择实体的点集。The set of points used for selecting entities within the view trace. |
FTraceResult USTRUCT
追踪结果:命中实体的句柄、位置信息与确定性排序缓存字段。非 UPROPERTY 字段 CachedDistSq / CachedUniqueID / PriorityLevel 用于追踪处理器内部排序。
Trace result: the hit entity's handle, location info, and cached fields for deterministic sorting. The non-UPROPERTY fields CachedDistSq / CachedUniqueID / PriorityLevel are used internally by the trace processor for sorting.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Entity | FEntityHandle | — | 碰撞发生时,被追踪对象的实体句柄。The entity handle of the targeted object when a collision occurs. |
EntityLocation | FVector | ZeroVector | 碰撞发生时,被追踪对象的位置。The location of the targeted object when a collision occurs. |
ShapeLocation | FVector | ZeroVector | 碰撞发生时,追踪图形的位置。The location of the tracing shape when a collision occurs. |
HitLocation | FVector | ZeroVector | 追踪图形与被追踪对象的碰撞点。The collision point between the tracing shape and the targeted object. |
CachedDistSq | float (非 UPROPERTY)float (non-UPROPERTY) | -1.0f | 缓存的距离平方,用于确定性排序。Cached squared distance for deterministic sorting. |
CachedUniqueID | int32 (非 UPROPERTY)int32 (non-UPROPERTY) | -1 | 缓存的 UniqueID,用于确定性排序。Cached UniqueID for deterministic sorting. |
PriorityLevel | int32 (非 UPROPERTY)int32 (non-UPROPERTY) | -1 | 该结果的优先级级别(0 = 最高)。禁用优先级过滤或实体不匹配任何优先级时为 -1。Priority level of this result (0 = highest); -1 when priority filtering is disabled or the entity matches no priority. |
FHitDebuffInfo USTRUCT
受击事件中应用的 debuff 信息,包含抵抗与衰减计算后的实际应用值。
Information about debuffs applied during a hit event, holding the actual values applied after resistance and falloff calculations.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bLaunched | bool | false | 是否应用了击退。Whether knockback was applied. |
LaunchForce | FVector | ZeroVector | 应用的击退力。The launch/knockback force applied. |
bTemporalDmgApplied | bool | false | 是否应用了延时伤害(DoT)。Whether temporal damage (DoT) was applied. |
TemporalDmgTotal | float | 0.f | 延时伤害总量。Total temporal damage to be dealt over time. |
TemporalDmgSegments | int32 | 0 | 伤害分段数。Number of damage segments. |
TemporalDmgInterval | float | 0.f | 伤害间隔(秒)。Interval between damage ticks in seconds. |
bSlowed | bool | false | 是否应用了减速。Whether slow was applied. |
SlowDuration | float | 0.f | 减速持续时间(秒)。Duration of the slow effect in seconds. |
SlowStrength | float | 0.f | 减速强度(0-1)。Strength of the slow effect (0-1). |
方法 Methods
判断是否应用了任何 debuff(击退 / 延时伤害 / 减速任一为 true)。
Returns whether any debuff was applied (launch / temporal damage / slow).
Input
无参数。
No parameters.
Output
返回三个标志的或。
Returns the OR of the three flags.
FDmgResult USTRUCT
伤害结果记录,由伤害应用并行段收集、串行仲裁后分发(事件、统计、debuff)。InstigatorEntity(引发者)与 CauserEntity(弹丸/爆炸等实际致害者)区分开;InstigatorID 用于确定性排序。
Damage result record, gathered in the damage-application parallel section and dispatched after serial arbitration (events, stats, debuffs). InstigatorEntity (the one whose action led to the damage) is distinguished from CauserEntity (e.g. a projectile or explosion); InstigatorID serves deterministic sorting.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
DamagedEntity | FEntityHandle | — | 受到伤害的实体。The entity that received damage. |
InstigatorEntity | FEntityHandle | — | 造成伤害的实体(引发该伤害的实体)。The entity responsible for instigating the damage. |
CauserEntity | FEntityHandle | — | 实际导致伤害的实体(弹丸或爆炸实体)。The entity that caused the damage (e.g. a projectile or explosion). |
InstigatorID | int32 | -1 | 发起者的 Agent ID,用于确定性排序。The Agent ID of the instigator, for deterministic sorting. |
IsCritical | bool | false | 是否暴击。True if the damage was a critical hit. |
IsKill | bool | false | 该伤害是否导致目标死亡。True if this damage resulted in the target's death. |
DmgDealt | float | 0 | 造成的伤害值。The amount of damage dealt. |
HitDirection | FVector | ZeroVector | 从致害者位置指向 agent 位置的向量(击打方向)。Vector from the causer location pointing to the agent location. |
HitLocation | FVector | ZeroVector | 受击点位置。The location of the actual hit point. |
DebuffInfo | FHitDebuffInfo | — | 随此伤害应用的减益信息。Information about debuffs applied with this damage. |
FLaunchResult USTRUCT
击退/击飞 debuff 应用的结果记录,由 LaunchGatherer 用于确定性击退处理。
Result struct for launch/knockback debuff application, used by LaunchGatherer for deterministic knockback processing.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
TargetEntity | FEntityHandle | — | 将受到击退力的实体。The entity that will receive the launch force. |
InstigatorID | int32 | -1 | 发起者的 Agent ID,用于确定性排序。The Agent ID of the instigator, for deterministic sorting. |
LaunchForce | FVector3f | ZeroVector | 要施加的击退力。The launch/knockback force to apply. |
方法 Methods
三参构造,直接初始化三个成员。
Three-argument constructor initializing all members.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InTarget | FEntityHandle | 目标实体。Target entity. |
InInstigatorID | int32 | 发起者 ID。Instigator ID. |
InLaunchForce | FVector3f | 击退力。Launch force. |
Output
无返回值。
No return value.
FPressureDeposit USTRUCT
每帧每 agent 发射的压力沉积记录:经 FParallelGatherer 收集,合并后以并行原子加累加到块稀疏单元场(精确整数和可交换——顺序无关,无需排序)。块寻址位于以 PressureGridOrigin 锚定的绝对格网上:BlockCoord = floor((WorldPos - Origin) / BlockWorldSize),同一世界位置在每端映射到相同的 (块, 格)。AgentUniqueID 仅作诊断归因(不再是排序键:沉积按顺序无关方式求和)。
Pressure-field deposit emitted by each agent each frame: gathered via FParallelGatherer, merged, then summed into the block-sparse cell field by parallel atomic adds (exact integer sums commute — order-independent, no sort needed). Block addressing lives on the absolute lattice anchored at PressureGridOrigin: BlockCoord = floor((WorldPos - Origin) / BlockWorldSize), so the same world position maps to the same (block, cell) on every peer. AgentUniqueID is diagnostic attribution only (no longer a sort key: deposits are summed order-independently).
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
BlockX | int32 | INDEX_NONE | 绝对格网上的块坐标 X(块世界尺寸 = PressureGridDimensions × PressureCellSize,默认 512m)。Block coordinate X on the absolute lattice (block world size = PressureGridDimensions × PressureCellSize, default 512m). |
BlockY | int32 | INDEX_NONE | 块坐标 Y。Block coordinate Y. |
LocalIdx | int32 | INDEX_NONE | 块 Front 缓冲内的线性化单元索引。Linearized cell index within the block's Front buffer. |
Amount | float | 0.f | 要加到单元的密度量。Amount of density to add to the cell. |
AgentUniqueID | int32 | -1 | 发起 agent 的 UniqueID——诊断归因用(不再是排序键:沉积按顺序无关方式求和)。Source agent's UniqueID — diagnostic attribution (no longer a sort key: deposits are summed order-independently). |
方法 Methods
五参构造,直接初始化全部成员。
Five-argument constructor initializing all members.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InBlockX | int32 | 块坐标 X。Block coordinate X. |
InBlockY | int32 | 块坐标 Y。Block coordinate Y. |
InLocalIdx | int32 | 块内线性化单元索引。Linearized cell index within the block. |
InAmount | float | 密度量。Density amount. |
InAgentUniqueID | int32 | 来源 agent UID。Source agent UID. |
Output
无返回值。
No return value.
FStatsResult USTRUCT
统计累加的结果记录,由 StatsGatherer 用于确定性统计处理。DamageDelta(float)要求确定性累加顺序;KillsDelta / ScoreDelta(int32)可任意顺序累加。
Result struct for statistics accumulation, used by StatsGatherer for deterministic statistics processing. DamageDelta (float) requires a deterministic accumulation order; KillsDelta and ScoreDelta (int32) can be accumulated in any order.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
TargetEntity | FEntityHandle | — | 将获得统计数据的实体。The entity that will receive the statistics credit. |
TargetID | int32 | -1 | 目标实体的 UniqueID,用于确定性排序。The UniqueID of the target entity, for deterministic sorting. |
DamageDelta | float | 0.0f | 要添加到 TotalDamage 的伤害量。Damage dealt to add to TotalDamage. |
KillsDelta | int32 | 0 | 要添加到 TotalKills 的击杀数。Kills to add to TotalKills. |
ScoreDelta | int32 | 0 | 要添加到 TotalScore 的分数。Score to add to TotalScore. |
方法 Methods
五参构造(KillsDelta / ScoreDelta 带默认值 0)。
Five-argument constructor (KillsDelta / ScoreDelta default to 0).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InTarget | FEntityHandle | 统计目标实体。Statistics target entity. |
InTargetID | int32 | 目标 UID。Target UID. |
InDamageDelta | float | 伤害增量。Damage delta. |
InKillsDelta | int32 | 击杀增量(默认 0)。Kills delta (default 0). |
InScoreDelta | int32 | 分数增量(默认 0)。Score delta (default 0). |
Output
无返回值。
No return value.
FLootClaimRequest USTRUCT
战利品认领意图:并行段(ReactionProcessor)收集,串行按 (LootUID, CollectorUID) 排序仲裁——每战利品最小 CollectorUID 获胜。镜像 FDmgResult 的 gather → 排序 → 串行消费范式;取代循环内竞争的 Collector 写入。DistSq 为公平主键(最近者赢)。
Loot claim intent gathered in parallel from ReactionProcessor; arbitrated serially by the (LootUID, CollectorUID) sort — min CollectorUID per loot wins. Mirrors the FDmgResult gather → sort → serial-flush pattern; replaces the racy in-loop Collector write. DistSq is the primary fairness key (nearest wins).
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
LootEntity | FEntityHandle | — | 被认领的战利品实体。The loot entity being claimed. |
LootUID | int32 | -1 | 排序主键,按战利品分组。Primary deterministic sort key, grouping claims per loot. |
CollectorEntity | FEntityHandle | — | 认领战利品的 agent 实体。The agent entity claiming the loot. |
CollectorUID | int32 | -1 | 排序决胜次键。Tie-break sort key. |
DistSq | float | 0.f | 认领时收集者到战利品的距离平方——公平主键(最近者赢)。确定性:双方位置均为锁步模拟值;并行 lane 计算,供串行仲裁使用。Squared distance from collector to loot at claim time — primary fairness key (nearest wins). Deterministic: both positions are lockstep-simulated; computed in the parallel lane for the serial arbitration. |
方法 Methods
四参构造(不含 DistSq,保持默认 0)。
Four-argument constructor (without DistSq, left at default 0).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InLoot | FEntityHandle | 战利品实体。Loot entity. |
InLootUID | int32 | 战利品 UID。Loot UID. |
InCollector | FEntityHandle | 收集者实体。Collector entity. |
InCollectorUID | int32 | 收集者 UID。Collector UID. |
Output
无返回值。
No return value.
FEntityArray USTRUCT
实体句柄数组的简单包装,供蓝图参数使用。
Simple wrapper around an array of entity handles for Blueprint parameters.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Entities | TArray<FEntityHandle> | 空 | 实体句柄数组。An array of entity handles. |
FSpawnerMult USTRUCT
生成器乘数配置:旧版浮点乘数(仅序列化保留,迁移后恢复默认值)与新版范围乘数(每实体生成时在 [X,Y] 范围内随机取值)并存,由 MigrateLegacyMultipliers() 完成一次迁移(bMigratedMultipliersToRange 为哨兵)。
Spawner multiplier config: legacy float multipliers (serialization only, reset to default after migration) coexist with the new range multipliers (per-agent random value within [X, Y] at spawn), migrated once by MigrateLegacyMultipliers() (guarded by the bMigratedMultipliersToRange sentinel).
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
HealthMult | float (旧版)float (legacy) | 1.f | 旧版血量乘数——仅序列化保留,迁移后恢复默认值。Legacy health multiplier — serialization only, reset after migration. |
MoveSpeedMult | float (旧版)float (legacy) | 1.f | 旧版移动速度乘数。Legacy move-speed multiplier. |
DamageMult | float (旧版)float (legacy) | 1.f | 旧版伤害乘数。Legacy damage multiplier. |
ScaleMult | float (旧版)float (legacy) | 1.f | 旧版尺寸乘数。Legacy scale multiplier. |
HealthMultRange | FVector2D | (1, 1) | 每单位血量乘数范围 [最小值, 最大值]。Health multiplier range [min, max] picked per agent. |
MoveSpeedMultRange | FVector2D | (1, 1) | 每单位移动速度乘数范围 [最小值, 最大值]。Move-speed multiplier range [min, max] picked per agent. |
DamageMultRange | FVector2D | (1, 1) | 每单位伤害乘数范围 [最小值, 最大值]。Damage multiplier range [min, max] picked per agent. |
ScaleMultRange | FVector2D | (1, 1) | 每单位尺寸乘数范围 [最小值, 最大值]。Scale multiplier range [min, max] picked per agent. |
bMigratedMultipliersToRange | bool (哨兵)bool (sentinel) | false | 数据迁移哨兵:已迁移则为 true,防止重复迁移。Data-migration sentinel: true once migrated, preventing double migration. |
方法 Methods
将旧版浮点乘数迁移至新版范围:若旧值非默认(≠1)且新范围仍为默认(1,1),则拷贝旧值到 X=Y 并把旧值重置为默认。完成后置哨兵。由 UMassBattleAgentComponent::PostLoad 调用。
Migrates legacy float multipliers to the new ranges: if a legacy value is non-default (≠1) and the range is still default (1,1), copies the legacy value into X=Y and resets the legacy value to default. Sets the sentinel when done. Called from UMassBattleAgentComponent::PostLoad.
Input
无参数。
No parameters.
Output
无返回值。副作用:可能改写四个范围成员并重置旧值,置 bMigratedMultipliersToRange。
No return value. Side effect: may rewrite the four range members, reset legacy values, and set bMigratedMultipliersToRange.
事件回调数据 Event Callback Data
以下 F*Data 结构为各行为/能力事件回调的载荷,由对应处理器在事件触发时填充并经事件系统分发。每个都携带 SelfEntity(事件主体)与 UniqueID(确定性标识,非 UPROPERTY)。
The following F*Data structs are payloads for behavior/capability event callbacks, filled by the corresponding processors when events fire and dispatched through the event system. Each carries SelfEntity (the event subject) and UniqueID (deterministic identifier, non-UPROPERTY).
FAppearData USTRUCT
出生事件的回调数据。
Appear event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 刚刚出现/生成的实体。The entity that has just appeared/spawned. |
EventLocation | FVector | ZeroVector | 事件时刻锚点——事件在模拟管线内发生那一刻的实体位置,发射时在 lane 内捕获。锁步下 BP 派发晚于事件(post-sim),实体可能已移动;BP 处理器生成 FX 应使用此值而非重读实时变换。Event-time anchor — the entity's position at the moment the event fired inside the sim pipeline, captured in-lane at emission. In lockstep the BP dispatch runs later in the frame (post-sim) when the entity may already have moved; FX spawned from BP handlers should use this instead of re-reading the live transform. |
EventRotation | FRotator | ZeroRotator | 实体出现那一刻的朝向(事件时刻,非派发时刻)。Event-time rotation when the entity appeared (NOT dispatch-time). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FTraceData USTRUCT
索敌事件的回调数据。
Trace event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 执行追踪的实体。The entity performing the trace. |
State | ETraceEventState | Begin | 追踪事件状态(开始 / 成功结束 / 失败结束)。Trace event state (Begin / End_Succeed / End_Fail). |
TraceResult | FEntityHandle | — | 追踪结果的实体句柄(被找到或丢失的实体)。Entity handle of the trace result (the entity found or lost). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FMoveData USTRUCT
移动事件的回调数据。
Move event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 执行移动操作的实体。The entity that has performed a move action. |
State | EMoveEventState | Arrived | 移动事件状态(移动中 / 到达 / 返回)。Move event state (Moving / Arrived / Returning). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FSleepData USTRUCT
休眠事件的回调数据。
Sleep event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 进入/退出休眠的实体。The entity that entered/exited sleep. |
State | ESleepEventState | Enter | 休眠事件状态(进入 / 退出)。Sleep event state (Enter / Exit). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FPatrolData USTRUCT
巡逻事件的回调数据。
Patrol event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 执行巡逻的实体。The entity performing patrol. |
State | EPatrolEventState | Enter | 巡逻事件状态(进入 / 退出 / 巡逻中 / 等待中)。Patrol event state (Enter / Exit / Patrolling / Waiting). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FChaseData USTRUCT
追逐事件的回调数据。
Chase event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 执行追逐的实体。The entity performing chase. |
State | EChaseEventState | Enter | 追逐事件状态(进入 / 退出 / 追逐中 / 已追到)。Chase event state (Enter / Exit / Chasing / Reached). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FReinforceData USTRUCT
支援事件的回调数据。
Reinforce event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 执行支援的实体。The entity performing reinforce. |
State | EReinforceEventState | Enter | 支援事件状态(进入 / 退出)。Reinforce event state (Enter / Exit). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FAttackData USTRUCT
攻击事件的回调数据,携带本次攻击的伤害结果列表。
Attack event callback data, carrying the damage results of this attack.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 正在执行攻击的实体。The entity that is performing the attack. |
State | EAttackEventState | Aiming | 攻击事件状态(瞄准中 / 开始 / 击中 / 冷却 / 各种结束原因)。Attack event state (Aiming / Begin / Hit / Cooling / end reasons). |
AttackTarget | FEntityHandle | — | 攻击的主要目标。The primary target of the attack. |
DmgResults | TArray<FDmgResult> | 空 | 本次攻击的伤害结果列表。List of damage results from this attack. |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FHitData USTRUCT
受击事件的回调数据,含从 FDmgResult 构造的便捷构造函数。
Hit event callback data, with a convenience constructor from FDmgResult.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 被击中/受伤的实体。The entity that was hit/damaged. |
InstigatorEntity | FEntityHandle | — | 引发击中的实体。The entity that instigated the hit. |
CauserEntity | FEntityHandle | — | 导致击中的实体(例如弹丸)。The entity that caused the hit (e.g. a projectile). |
IsCritical | bool | false | 是否暴击。True if the hit was a critical hit. |
IsKill | bool | false | 本次击中是否导致目标死亡。True if this hit resulted in the target's death. |
DmgDealt | float | 0 | 本次击中造成的伤害值。The amount of damage dealt by this hit. |
HitDirection | FVector | ZeroVector | 击打方向。Vector from causer location pointing to the agent location. |
HitLocation | FVector | ZeroVector | 受击点位置。The location of the actual hit point. |
DebuffInfo | FHitDebuffInfo | — | 随此击中应用的减益信息。Information about debuffs applied with this hit. |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
方法 Methods
从 FDmgResult 构造:拷贝受击/发起者/致害者句柄、暴击与击杀标志、伤害值、击打方向/位置与 debuff 信息。
Constructs from an FDmgResult: copies the damaged/instigator/causer handles, crit and kill flags, damage value, hit direction/location, and debuff info.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
DmgResult | const FDmgResult& | 来源伤害结果。Source damage result. |
Output
无返回值。副作用:初始化全部成员(UniqueID 保持 -1)。
No return value. Side effect: initializes all members (UniqueID stays -1).
FDeathData USTRUCT
死亡事件的回调数据。
Death event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 死亡的实体。The entity that died. |
InstigatorEntity | FEntityHandle | — | 导致死亡的实体。The entity responsible for the death. |
State | EDeathEventState | OutOfHealth | 死亡事件状态/原因(血量耗尽等)。Death event state/reason (e.g. OutOfHealth). |
EventLocation | FVector | ZeroVector | 事件时刻锚点(见 FAppearData::EventLocation)。BP 处理器生成死亡 FX 应使用此值(死亡 tick 位置)而非派发时变换。Event-time anchor (see FAppearData::EventLocation). Death FX spawned from BP handlers should use this (the death-tick position), not the dispatch-time transform. |
EventRotation | FRotator | ZeroRotator | 实体死亡那一刻的朝向。Event-time rotation when the entity died. |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FPoolData USTRUCT
对象池事件的回调数据。
Pool event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 由对象池管理的实体。The entity being managed by the pool. |
State | EPoolEventState | PoolSpawn | 对象池事件状态(生成 / 返回)。Pool event state (Spawned / Returned). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FStatisticsData USTRUCT
统计数据事件的回调数据。
Statistics event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 统计数据所属的实体。The entity whose statistics are being referenced. |
Statistics | FStatistics | — | 当前统计数据 fragment 数据(见 Fragments/Statistics.h)。The current statistics fragment data (see Fragments/Statistics.h). |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FAnimEventData USTRUCT
动画事件数据,包含当前动画播放信息,由 OnAnimStateChange 事件使用。
Animation event data containing current animation playback info, used by the OnAnimStateChange event.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
AnimIndex | int32 | -1 | 当前动画索引。The current animation index. |
AnimPlayRate | float | 1.0f | 当前动画播放速率。The current animation playback rate. |
AnimProgressRatio | float | 0.0f | 当前动画进度比例(0.0 到 1.0)。The current animation progress ratio (0.0 to 1.0). |
bIsLooping | bool | false | 当前动画是否循环播放。Whether the current animation is looping. |
方法 Methods
四参构造。
Four-argument constructor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InAnimIndex | int32 | 动画索引。Animation index. |
InPlayRate | float | 播放速率。Play rate. |
InProgressRatio | float | 进度比例。Progress ratio. |
InIsLooping | bool | 是否循环。Whether looping. |
Output
无返回值。
No return value.
FAnimStateChangeData USTRUCT
动画状态变更事件的回调数据。
Animation state change event callback data.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SelfEntity | FEntityHandle | — | 动画状态发生改变的实体。The entity whose animation state changed. |
PreviousState | EAnimState | Idle | 之前的动画状态。The previous animation state. |
NewState | EAnimState | Idle | 新的动画状态。The new animation state. |
AnimData | FVector4f | Zero | 选中的动画数据(索引、长度、起始帧、结束帧)。The selected animation data (Index, Length, StartFrame, EndFrame). |
CurrentAnimInfo | FAnimEventData | — | 当前动画播放信息。Current animation playback info. |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
FDestructionData USTRUCT
销毁事件的内部数据(无 UPROPERTY 暴露)。
Internal destruction event data (no UPROPERTY exposure).
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Entity | FEntityHandle | — | 被销毁的实体。The destroyed entity. |
UniqueID | int32 | -1 | 实体唯一 ID。Entity unique ID. |
bFireTerminalEvents | bool | false | KI-003:true = 入队现场从未(也绝不会)发出该实体的终态事件——销毁队列消费方(UMassBattleSubsystem)须在销毁实体前恰好补发一次。默认 false:处理器入队现场要么已内联发过生命周期事件(死亡/拾取/到期/移除),要么是刻意的静默 despawn(DestroyTag)或对象池驱逐;debuff/host 实体不携带事件片段。只有三个绑定组件的 EndPlay 路径(实体存活期间 Actor 被销毁)置 true。KI-003: true = the enqueue site never fired (and never will fire) the entity's terminal event — the destroy-queue consumer (UMassBattleSubsystem) must backfill it exactly once, right before destroying the entity. Default false: every processor enqueue site already fired its lifecycle event inline (death / collect / expiry / remove) or is a deliberate silent despawn (DestroyTag) or a pool eviction; debuff/host entities carry no event fragments. Only the three binding-component EndPlay paths (actor destroyed while entity live) set it. |
方法 Methods
两参构造(UniqueID 默认 -1)。
Two-argument constructor (UniqueID defaults to -1).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InEntity | FEntityHandle | 实体句柄。Entity handle. |
InUniqueID | int32 | 唯一 ID(默认 -1)。Unique ID (default -1). |
Output
无返回值。
No return value.
调试绘制配置 Debug Draw Configs
以下 FDebug*Config 结构为调试绘制请求,可骑 FParallelGatherer 收集后由 UMassBattleSubsystem::ProcessDrawDebugQueues 串行排空。通用字段:UniqueID(确定性排序)、Entity(产生此绘制的实体,无效 = 不过滤选择)、Duration(0 = 一帧)。
The following FDebug*Config structs are debug-draw requests, gathered on FParallelGatherer and drained serially by UMassBattleSubsystem::ProcessDrawDebugQueues. Common fields: UniqueID (deterministic sort), Entity (the producing entity; invalid = no selection filter), Duration (0 = one frame).
FDebugPointConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Location | FVector | ZeroVector | 点的世界位置。World location of the point. |
Color | FColor | Red | 点的颜色。Color of the point. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
Size | float | 1.f | 点的大小/线宽。Size/thickness of the point. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体(无效 = 不过滤选择)。Producing entity (invalid = no selection filter). |
FDebugLineConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
StartLocation | FVector | ZeroVector | 线的起点。Starting location of the line. |
EndLocation | FVector | ZeroVector | 线的终点。Ending location of the line. |
Color | FColor | Red | 线的颜色。Color of the line. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.f | 线的粗细。Thickness of the line. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugArrowConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
StartLocation | FVector | ZeroVector | 箭头的起点。Starting location of the arrow. |
EndLocation | FVector | ZeroVector | 箭头的终点。Ending location of the arrow. |
Color | FColor | Red | 箭头的颜色。Color of the arrow. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.f | 箭头线的粗细。Thickness of the arrow line. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugSphereConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Radius | float | 100.f | 球体半径。Radius of the sphere. |
Location | FVector | ZeroVector | 球体中心的世界位置。World location of the sphere center. |
Color | FColor | Red | 球体线框的颜色。Color of the sphere wireframe. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.f | 线框粗细。Wireframe line thickness. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugCapsuleConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Location | FVector | ZeroVector | 胶囊体的世界位置。World location of the capsule center. |
Rotation | FRotator | ZeroRotator | 胶囊体的旋转。Rotation of the capsule. |
Radius | float | 100.f | 胶囊体半径。Radius of the capsule. |
Height | float | 100.f | 胶囊体半高。Half-height of the capsule. |
Color | FColor | Red | 线框颜色。Wireframe color. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.f | 线框粗细。Wireframe line thickness. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugSectorConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Radius | float | 100.f | 扇形弧的半径。Radius of the sector arc. |
Height | float | 100.f | 扇形体的高度。Height of the sector volume. |
Angle | float | 100.f | 扇形弧的张开角度(度)。Angle of the sector arc (degrees). |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
Location | FVector | ZeroVector | 扇形原点的世界位置。World location of the sector origin. |
Direction | FVector | OneVector | 扇形的前进方向。Forward direction of the sector. |
Color | FColor | Red | 线框颜色。Wireframe color. |
LineThickness | float | 0.f | 线框粗细。Wireframe line thickness. |
DepthPriority | int32 | 0 | 调试绘制的深度优先级。Depth priority of the debug draw. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugCircleConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Radius | float | 100.f | 圆的半径。Radius of the circle. |
Location | FVector | ZeroVector | 圆心点的世界位置。World location of the circle center. |
Color | FColor | Red | 线框颜色。Wireframe color. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.f | 线框粗细。Wireframe line thickness. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FTraceDrawDebugConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bDrawDebugShape | bool | false | 是否绘制追踪形状的调试可视化。Whether to draw the trace shape debug visualization. |
Color | FColor | Red | 调试追踪形状的颜色。Color of the debug trace shape. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 1.f | 调试形状线的粗细。Thickness of the debug shape lines. |
HitPointSize | float | 1.f | 碰撞点标记的大小。Size of the hit point marker. |
FDebugBoxConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Center | FVector | ZeroVector | 盒子中心的世界位置。World location of the box center. |
HalfExtents | FVector | (50, 50, 50) | 盒子沿 X、Y、Z 的半范围大小。Half extent size of the box along X, Y, Z. |
Rotation | FQuat | Identity | 盒子的旋转。Rotation of the box. |
Color | FColor | Green | 线框颜色。Wireframe color. |
Duration | float | 0.0f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.0f | 线框粗细。Wireframe line thickness. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugConeConfig USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Origin | FVector | ZeroVector | 锥体原点的世界位置。World location of the cone origin. |
Direction | FVector | ForwardVector | 锥体的方向向量。Direction vector of the cone. |
Length | float | 100.f | 锥体的长度。Length of the cone. |
Angle | float | 45.f | 锥体半角(度)。Half angle of the cone (degrees). |
Color | FColor | Green | 线框颜色。Wireframe color. |
Duration | float | 0.0f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 0.0f | 线框粗细。Wireframe line thickness. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
FDebugStringConfig USTRUCT
文本调试绘制请求,与其它 FDebug*Config 镜像,可骑 FParallelGatherer。由 UMassBattleSubsystem::ProcessDrawDebugQueues 用 DrawDebugString 排空(仅编辑器——文本没有 LineBatcher 等价物)。
Text debug-draw request mirroring the other FDebug*Config structs so it can ride a FParallelGatherer. Drained from UMassBattleSubsystem::ProcessDrawDebugQueues with DrawDebugString (editor-only — there is no LineBatcher equivalent for text).
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Location | FVector | ZeroVector | 文本锚点的世界位置。World location of the text anchor. |
Text | FString | 空 | 文本内容。Text content. |
Color | FColor | White | 文本颜色。Color of the text. |
Duration | float | 0.f | 显示时间(0 = 一帧)。Display duration (0 = one frame). |
FontScale | float | 1.f | 字体缩放。Font scale. |
bDrawShadow | bool | true | 是否绘制阴影。Whether to draw a drop shadow. |
Entity | FEntityHandle | — | 产生此绘制的实体。Producing entity. |
UniqueID | int32 | 0 | 确定性排序用唯一 ID。Unique ID for deterministic sort. |
可视化配置 Visualization Configs
FFormationVisualizationConfig USTRUCT
阵型生成的可视化配置。通过 ULineBatchComponent 绘制,在 Shipping 构建中也可见。各开关受 bEnabled 的 EditCondition 控制。
Visualization config for formation generation. Drawn via ULineBatchComponent so it shows in Shipping builds. Each toggle is gated by bEnabled via EditCondition.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bEnabled | bool | false | 启用可视化绘制。Enable visualization drawing. |
bDrawStart | bool | true | 在每个 Agent 的起始位置绘制圆圈。Draw a circle at each agent's start position. |
bDrawConnection | bool | true | 绘制从起始到终点的箭头。Draw an arrow from start to end position. |
bDrawEnd | bool | true | 在每个 Agent 的终点位置绘制圆圈。Draw a circle at each agent's end position. |
Color | FColor | Green | 可视化形状的颜色。Color of the visualization shapes. |
Duration | float | 5.f | 可视化形状的显示时间(0 = 一帧)。Display duration (0 = one frame). |
LineThickness | float | 2.f | 可视化线的粗细。Thickness of the visualization lines. |
FAgentTaskVisualizationConfig USTRUCT
AgentsMoveTo / AgentsChaseAttack 任务的逐帧可视化配置。通过 ULineBatchComponent 绘制,Shipping 可见。默认值适用于逐帧重绘(Duration = 0 表示仅一帧,每个 tick 刷新一次)。
Per-tick visualization config for AgentsMoveTo / AgentsChaseAttack tasks. Drawn via ULineBatchComponent so it stays visible in Shipping builds. Defaults are tuned for per-frame redraw (Duration = 0 = one frame, refreshed each tick).
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bEnabled | bool | false | 启用可视化绘制。Enable visualization drawing. |
bDrawAgentMarker | bool | true | 在每个 Agent 的当前位置绘制圆圈。Draw a circle at each agent's current position. |
bDrawConnection | bool | true | 从 Agent 到其目标位置绘制箭头。Draw an arrow from agent to its goal/target location. |
bDrawGoalMarker | bool | true | 在每个 Agent 的目标位置绘制球体。Draw a sphere at each agent's goal/target location. |
Color | FColor | Cyan | 可视化形状的颜色。Color of the visualization shapes. |
Duration | float | 0.f | 任务每个引擎帧重绘多少秒(实时秒)。线条本身只持续一个引擎帧并每帧重绘——Duration 仅限制总绘制时长。0 = 任务运行期间始终绘制(无时间限制)。How long (in real seconds) the task keeps redrawing lines each engine tick. Lines themselves live for exactly one engine frame and are refreshed every tick — Duration only bounds the total draw window. 0 = draw for the task's entire lifetime (no time limit). |
LineThickness | float | 2.f | 可视化线的粗细。Thickness of the visualization lines. |
GoalMarkerRadius | float | 30.f | 目标位置球体的半径。Radius of the goal-marker sphere. |
生成形状 Spawn Shapes
ESpawnPositioningMode UENUM
定义生成数量小于可用位置时的位置选择方式。
Defines how spawn positions are selected when the spawn count is less than the available positions.
| 值 Value | 说明 Description |
|---|---|
Sequential | 从开头顺序选择位置(前 N 个)。Select positions sequentially from the beginning (first N positions). |
Random | 随机选择(打乱后取 N 个)。Select positions randomly (shuffle and take N positions). |
FAgentSpawnRectangleShapeData USTRUCT
矩形生成区域定义:区域大小、网格间距、朝向、地面/障碍物追踪参数与坡度限制。
Rectangular spawn region definition: region size, grid spacing, orientation, ground/obstacle trace parameters, and a slope limit.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Region | FVector2D | (1000, 1000) | 矩形区域大小。Region size. |
Spacing | FVector2D | (100, 100) | 网格间距(X/Y)。Grid spacing (X/Y). |
SizingMode | EFormationSizingMode (非 UPROPERTY) | FitAgents | 已禁用的模式选择,为生成器中的 Fixed 分支保留。阵型尺寸仅 FitAgents(见 MassBattleFormationAlgorithms.cpp 的 bFormationFitAgentsOnly)。不对蓝图公开。Disabled mode selector, retained for the Fixed branches in the generators. Formation sizing is FitAgents-only (bFormationFitAgentsOnly in MassBattleFormationAlgorithms.cpp). Not exposed to Blueprint. |
SlotCountMargin | float | 1.f | 目标槽位数 = ceil(Agent 数 × Margin) + 大单位自动额外槽位(按半径估算多槽 blocker)。大于 1.0 在其上再加人为余量。Clamp 1.0–4.0。Target slot count = ceil(NumAgents × Margin) + automatic large-agent extra (blockers covering multiple slots are estimated from radii). Above 1.0 adds intentional slack on top. Clamped 1.0–4.0. |
KeepFormationRotateDeg | float | 0.f | KeepFormation 相对旋转角(度),平移后绕排列质心旋转。0(默认)= 纯平移——保持世界朝向。仅作用于平移路径(不涉及晶格);ReformTheLine 忽略。Clamp -180–180。KeepFormation relative rotation (degrees) applied to the kept arrangement AROUND ITS CENTROID after translation. 0 (default) = pure translation — world orientation kept. Applies to the translation path only (no lattice involved); ReformTheLine ignores it. Clamped -180–180. |
ShapeDirection | FVector | ForwardVector | 矩形阵型的朝向前方方向。Region.X 沿此方向延伸。The forward facing direction of the rectangular formation. Region.X extends along this direction. |
Offset | float | 0.f | 网格放置后每个点的随机偏移。Random offset applied to each point after grid placement. |
PositioningMode | ESpawnPositioningMode | Random | 生成数量小于可用位置时的选择方式。How to select positions when spawn count is less than available positions. |
GroundObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 地面检测的对象类型。Ground trace object types. |
ObstacleObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 障碍物检测的对象类型。Obstacle trace object types. |
GroundTraceHeightRange | FVector2D | (1000, -1000) | 向下追踪的高度范围:X = 起始高度偏移,Y = 结束高度偏移。Height range for the downward trace: X = start height offset, Y = end height offset. |
MaxSlope | float | 0.f | 最大允许地面坡度(度)。比此更陡的表面拒绝该位置。0 = 不限制坡度。Maximum allowed ground slope in degrees. Surfaces steeper than this reject the position. 0 = no slope limit. |
FAgentSpawnTriangleShapeData USTRUCT
三角形(楔形)阵型区域定义:行从 1 个槽位的顶点(朝 ShapeDirection)递增到底边;第 j 行有 j+1 个槽位(行内间距 Spacing.X),行距 Spacing.Y。布局按包围盒居中。
Defines a triangular (wedge) region for formations: rows grow from a 1-slot apex (pointing along ShapeDirection) to the base; row j holds j+1 slots spaced Spacing.X, rows pitch Spacing.Y. The layout is centered on the shape's bounding box.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Region | FVector2D | (1000, 1000) | X = 底边宽度,Y = 高度(形状局部轴)。行数以先耗尽者为准。X = base width, Y = height (shape-local axes). Row count is capped by whichever runs out first. |
Spacing | FVector2D | (100, 100) | X = 行内槽位间距,Y = 行距。X = within-row slot pitch, Y = row pitch. |
SizingMode | EFormationSizingMode (非 UPROPERTY) | FitAgents | 已禁用的模式选择,为生成器中的 Fixed 分支保留。阵型尺寸仅 FitAgents(见 MassBattleFormationAlgorithms.cpp 的 bFormationFitAgentsOnly)。不对蓝图公开。Disabled mode selector, retained for the Fixed branches in the generators. Formation sizing is FitAgents-only (bFormationFitAgentsOnly in MassBattleFormationAlgorithms.cpp). Not exposed to Blueprint. |
SlotCountMargin | float | 1.f | 目标槽位数 = ceil(Agent 数 × Margin) + 大单位自动额外槽位(按半径估算多槽 blocker)。大于 1.0 在其上再加人为余量。Clamp 1.0–4.0。Target slot count = ceil(NumAgents × Margin) + automatic large-agent extra (blockers covering multiple slots are estimated from radii). Above 1.0 adds intentional slack on top. Clamped 1.0–4.0. |
KeepFormationRotateDeg | float | 0.f | KeepFormation 相对旋转角(度),平移后绕排列质心旋转。0(默认)= 纯平移——保持世界朝向。仅作用于平移路径(不涉及晶格);ReformTheLine 忽略。Clamp -180–180。KeepFormation relative rotation (degrees) applied to the kept arrangement AROUND ITS CENTROID after translation. 0 (default) = pure translation — world orientation kept. Applies to the translation path only (no lattice involved); ReformTheLine ignores it. Clamped -180–180. |
ShapeDirection | FVector | ForwardVector | 三角形的朝向前方方向——顶点朝此方向。The forward facing direction of the triangle — the apex points this way. |
Offset | float | 0.f | 网格放置后每个点的随机偏移。Random offset applied to each point after grid placement. |
GroundObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 地面检测的对象类型。Ground trace object types. |
ObstacleObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 障碍物检测的对象类型。Obstacle trace object types. |
GroundTraceHeightRange | FVector2D | (1000, -1000) | 向下追踪的高度范围:X = 起始高度偏移,Y = 结束高度偏移。Height range for the downward trace: X = start height offset, Y = end height offset. |
MaxSlope | float | 0.f | 最大允许地面坡度(度)。比此更陡的表面拒绝该位置。0 = 不限制坡度。Maximum allowed ground slope in degrees. Surfaces steeper than this reject the position. 0 = no slope limit. |
FAgentSpawnPolygonShapeData USTRUCT
通用圆形、多边形或扇形生成区域定义(原 FMassShapeData 改名)。支持外/内半径(空心环形)、扇形角度、多边形边数、网格或随机散布。
Versatile circular, polygonal, or sector-based spawn region (renamed from FMassShapeData). Supports outer/inner radii (hollow ring), sector angle, polygon side count, and grid or random scatter.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
OuterRadius | float | 1000.f | 从原点到形状最远点的距离。Distance from Origin to the furthest point of the shape. |
InnerRadius | float | 0.f | 从原点到内边的距离。0 = 实心形状;>0 = 空心(甜甜圈/框架)。Distance from Origin to the inner edge. 0 = solid shape; >0 = hollow (donut/frame). |
ShapeDirection | FVector | ForwardVector | 形状的朝向前方方向,用于定向圆弧(如朝北的半圆)。The forward facing direction of the shape, used to orient arcs (e.g. a semi-circle facing North). |
SectorAngle | float | 360.0f | 生成圆弧的可接受角度(度)。360 = 整圆/圆环;180 = 半圆。Acceptable angle of the spawn arc in degrees. 360 = full ring/circle; 180 = half ring/semi-circle. |
Segments | int32 | 36 | 形状边数。< 3 或 > 32 视为圆。3 = 三角形,4 = 方形/菱形,6 = 六边形。Number of sides for the shape. < 3 or > 32 treated as a circle. 3 = triangle, 4 = square/rhombus, 6 = hexagon. |
PolygonRotation | float | 0.0f | 多边形自身的旋转偏移(度)(如把菱形转成方形)。Rotation offset (degrees) for the polygon itself (e.g. to turn a diamond into a square). |
Spacing | FVector2D | ZeroVector | 结构化放置的网格间距(X/Y)。两者都为 0 时改用随机散布。Grid spacing for structured spawn placement (X/Y). If both are 0, uses random scatter instead. |
SizingMode | EFormationSizingMode (非 UPROPERTY) | FitAgents | 已禁用的模式选择,为生成器中的 Fixed 分支保留。阵型尺寸仅 FitAgents(见 MassBattleFormationAlgorithms.cpp 的 bFormationFitAgentsOnly)。不对蓝图公开。Disabled mode selector, retained for the Fixed branches in the generators. Formation sizing is FitAgents-only (bFormationFitAgentsOnly in MassBattleFormationAlgorithms.cpp). Not exposed to Blueprint. |
SlotCountMargin | float | 1.f | 目标槽位数 = ceil(Agent 数 × Margin) + 大单位自动额外槽位(按半径估算多槽 blocker)。大于 1.0 在其上再加人为余量。Clamp 1.0–4.0。Target slot count = ceil(NumAgents × Margin) + automatic large-agent extra (blockers covering multiple slots are estimated from radii). Above 1.0 adds intentional slack on top. Clamped 1.0–4.0. |
KeepFormationRotateDeg | float | 0.f | KeepFormation 相对旋转角(度),平移后绕排列质心旋转。0(默认)= 纯平移——保持世界朝向。仅作用于平移路径(不涉及晶格);ReformTheLine 忽略。Clamp -180–180。KeepFormation relative rotation (degrees) applied to the kept arrangement AROUND ITS CENTROID after translation. 0 (default) = pure translation — world orientation kept. Applies to the translation path only (no lattice involved); ReformTheLine ignores it. Clamped -180–180. |
Offset | float | 0.f | 网格放置后每个点的随机偏移(0 = 无偏移)。Random offset applied to each point after grid placement (0 = no offset). |
PositioningMode | ESpawnPositioningMode | Random | 生成数量小于可用位置时的选择方式。How to select positions when spawn count is less than available positions. |
GroundObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 地面检测的对象类型。Ground trace object types. |
ObstacleObjectTypes | TArray<TEnumAsByte<EObjectTypeQuery>> | 空 | 障碍物检测的对象类型。Obstacle trace object types. |
GroundTraceHeightRange | FVector2D | (1000, -1000) | 向下追踪的高度范围。Height range for the downward trace. |
MaxSlope | float | 0.f | 最大允许地面坡度(度)。0 = 不限制。Maximum allowed ground slope in degrees. 0 = no slope limit. |
网络结构 Network Structs
EFFSubstrateSyncMode UENUM
流场基底重发策略——SendLockstepCommandToClients_RebuildFlowField 的 SyncMode 参数(UMassBattleFuncLib 蓝图函数与 AMassBattleNetworkGameModeBase 上的 C++ 版本,默认 Auto)。
Flow-field substrate re-send strategy — the SyncMode parameter of SendLockstepCommandToClients_RebuildFlowField (both the UMassBattleFuncLib Blueprint function and the C++ version on AMassBattleNetworkGameModeBase; defaults to Auto).
| 值 Value | 说明 Description |
|---|---|
Full | 恒发全量基底流(增量之前的既有行为;安全基线)。Always send the FULL substrate stream (pre-delta behavior; the safe baseline). |
Incremental | 优先发差分流(仅变更格子/变更 NavMesh tile + 目标集)。无可用基准或差分无法构造(identity / 网格缩放 / navmesh 重初始化)时自动回退全量;本地版本与基准脱节的端经修复通道请求全量重发。Prefer the DELTA stream (only changed Grid cells / changed NavMesh tiles + goal set). Falls back to full automatically when no usable base exists or the delta cannot be built (identity / grid resize / navmesh re-init); a peer whose applied version missed the base requests a full re-send through the repair path. |
Auto | 服务器比较差分与全量字节数取小者发送(差分达到 MassBattle.FF.DeltaToFullRatio × 全量即弃用)。首次发送必为全量(无基准)。Server compares delta vs full size and sends whichever is smaller (delta rejected once it reaches MassBattle.FF.DeltaToFullRatio × full). First send is always full (no base). |
FMassBattleNetCommand USTRUCT
通用网络指令容器,用于确定性锁步多人游戏。实体引用使用 UniqueID 而非 FEntityHandle(实体索引在不同机器上可能不一致)。各游戏模式在 Blueprint 中自行定义 CommandTag 约定和荷载编码。
Generic network command container for deterministic lockstep multiplayer. Entity references use UniqueID rather than FEntityHandle because entity indices are not guaranteed to be identical across machines. Each game mode defines its own CommandTag convention and payload encoding in Blueprint.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
CommandTag | FName | — | 路由标签,游戏模式自行定义(如 "RTS.Move" / "TD.PlaceTower" / "RL.Fire")。Route tag defined per game mode (e.g. "RTS.Move" / "TD.PlaceTower" / "RL.Fire"). |
PlayerIndex | int32 | 0 | 发起玩家索引。Issuing player index. |
IssuedTick | int32 | 0 | 指令发起的 tick。Tick when the command was issued. |
ExecuteTick | int32 | 0 | 目标执行 tick = IssuedTick + InputBufferTicks。Target execution tick = IssuedTick + InputBufferTicks. |
IntPayload | TArray<int32> | 空 | 整数荷载——游戏模式自行解释。Payload — interpreted per game mode. |
FloatPayload | TArray<float> | 空 | 浮点荷载。Float payload. |
BytePayload | TArray<uint8> | 空 | 字节荷载——紧凑量化数据。Byte payload — for compact quantized data. |
NamePayload | TArray<FName> | 空 | 名称载荷——携带 FName 值(模板键、资产引用等)。Name payload — carries FName values (template keys, asset refs, etc.). |
SequenceInTick | int32 | 0 | 每 tick 的命令序列号——区分同一 IssuedTick 的多条命令。Per-tick sequence number for command dedup — disambiguates multiple commands at the same IssuedTick. |
ServerExecSequence | int32 | 0 | 服务器分配的 per-ExecuteTick 序号——所有客户端确定一致。Server-assigned per-ExecuteTick order — deterministic across all clients. |
DataBlockId | int32 | -1 | 大负载 TCP 块引用。>=0 表示真实负载走 TCP 块(自动分流),使用前校验 DataBlockCrc。Large-payload TCP block reference. >=0 means the real payload travels in a TCP-transferred data block (auto-flood switch); verify DataBlockCrc before use. |
DataBlockCrc | int32 | 0 | 块未压缩负载的 CRC32,以 int32 存储。CRC32 of the block's uncompressed payload, stored as int32. |
ExtraDeferTicks | int32 | 0 | 超出标准 K 缓冲的额外推迟执行 tick 数(ExecuteTick = 基准 + K + ExtraDeferTicks)。调用方控制的延迟——可用于大块传输余量或分阶段指令。Extra ticks to defer execution beyond the standard K-buffer (ExecuteTick = base + K + ExtraDeferTicks). Caller-controlled delay — useful for large-block transit headroom or staged/sequenced commands. |
bLocalIssued | bool (BlueprintReadOnly) | false | 端本地发起标记:仅在本机玩家发起该命令的机器上为 TRUE。命令进入本机队列时自动盖章(EnqueueNetCommand:服务器盖章的 PlayerIndex 与本机本地玩家 PlayerState->GetPlayerId() 比对),快照恢复合并后重盖;线上传输值无意义(按默认 false 传输,每端接收时重盖)。蓝图只读——纯视觉/UI 路由用途;绝不用于需要各端一致的逻辑(刻意机器本地,与 LocalDeferCount 同类)。PEER-LOCAL origin marker: TRUE only on the machine whose local player issued this command. Stamped automatically when the command enters this machine's queue (EnqueueNetCommand: server-stamped PlayerIndex vs this machine's local PlayerState->GetPlayerId()) and re-stamped after snapshot-restore merges; the wire value is meaningless (travels as default false, every peer restamps on receipt). Read-only for BP — a pure visual/UI routing aid; NEVER use it for logic that must agree across peers (deliberately machine-local, like LocalDeferCount). |
LocalDeferCount | int32 (非 UPROPERTY) | 0 | 纯本地延迟重试计数(刻意非 UPROPERTY——不序列化、不发送):spawn 处理器因目标组件尚未复制而重入队指令时递增;超上限(见 GameStateBase defer 分支)则报错丢弃,不再无限重试。随 defer 路径的本地结构体拷贝存活。LOCAL-ONLY defer-retry bookkeeping (deliberately NOT a UPROPERTY — never serialized, never sent): incremented each time a spawn handler re-enqueues a command because its target component hasn't replicated yet; past the cap (see the GameStateBase defer branches) the command is dropped with an error instead of retrying forever. Survives the local struct copy in the defer path. |
EMassBattleNetLossMode UENUM
模拟丢包率的丢失语义——对应真实传输对丢包的反应方式。仅作用于 TCP 路径;UDP 丢包语义由引擎控制(reliable 重发)。
Loss semantics for the emulation drop chance — mirrors how real transports react to packet loss. TCP path only; UDP loss semantics are engine-controlled (reliable retransmission).
| 值 Value | 说明 Description |
|---|---|
RetransmitLate | 帧经 RetransmitDelayMs 后重发,期间队头阻塞所在 socket——真实 Reliable/TCP 行为:没有东西永久丢失,只是迟到(可能已过 ExecuteTick)。Frame is retransmitted after RetransmitDelayMs, head-of-line blocking its socket meanwhile — realistic Reliable/TCP behavior: nothing is lost forever, it just arrives LATE (past ExecuteTick). |
PermanentDiscard | 帧被丢弃永不到达——人为最坏情况,压测缺块 → desync → resync 恢复链。Frame is discarded and never arrives — synthetic worst case stressing missing-block → desync → resync recovery. |
FMassBattleNetEmulationSettings USTRUCT
调试用网络环境模拟设置——一次调用(UMassBattleFuncLib::SetNetworkEmulation / ClearNetworkEmulation / GetNetworkEmulation)同时影响两条传输:UE 的 UDP RPC 路径(net.PktLag / net.PktLagVariance / net.PktLoss / net.PktDuplicate cvar)与自定义 TCP 快照/lockstep 块路径(到期队列 + 帧丢弃 + 令牌桶限速,见 FMassBattleSnapshotTcpTransport)。控制帧(TCP 认证/心跳)永远直发。PIE 单进程承载服务器 + 客户端——一次调用覆盖两条路径的双方向;独立多进程:在想受影响的进程上各调用(影响该进程的出站方向)。TCP 侧刻意无重复/乱序旋钮——TCP 设计上去重且保序;此类效果用 UDP 旋钮。
Debug network-environment emulation settings — one call (UMassBattleFuncLib::SetNetworkEmulation / ClearNetworkEmulation / GetNetworkEmulation) impairs BOTH transports at once: UE's UDP RPC path (net.PktLag / net.PktLagVariance / net.PktLoss / net.PktDuplicate cvars) and the custom TCP snapshot/lockstep-block path (due-time queue + frame drop + token-bucket throttle, see FMassBattleSnapshotTcpTransport). Control frames (TCP auth/heartbeat) always bypass. PIE hosts server + client in one process — both directions of both paths are covered by one call; standalone multi-process: call on each process you want impaired (that process's outbound). The TCP side deliberately has no duplicate/reorder knobs — TCP dedupes and preserves order by design; use the UDP knobs for those effects.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
LatencyMs | float | 0.f | 单向附加延迟(毫秒)。0 = 关闭。One-way added latency in ms. 0 = none. |
JitterMs | float | 0.f | 在 LatencyMs 基础上的 ± 抖动(毫秒)。实际延迟 = Latency + rand[-Jitter, +Jitter],下限 0。+/- jitter in ms added on top of LatencyMs (actual delay = Latency + rand[-Jitter, +Jitter], clamped >= 0). |
DropPercent | float | 0.f | 丢包/丢帧百分比 0-100。UDP:逐包(net.PktLoss——引擎重发 reliable RPC,效果即迟到)。TCP:发送时逐帧丢包事件——语义由 LossMode 决定(延迟重发或永久丢弃)。Packet/frame drop percentage 0-100. UDP: per-packet (net.PktLoss — the engine retransmits reliable RPCs, so the effect is late arrival). TCP: per-frame loss EVENTS at send time — semantics per LossMode (retransmit-late or permanent). |
LossMode | EMassBattleNetLossMode | RetransmitLate | 丢失语义。RetransmitLate(默认,真实):丢失帧等待 RetransmitDelayMs 后重发,期间队头阻塞所在 socket(没有东西永久丢失,只是迟到——可能已过 ExecuteTick,压测迟到命令/迟到块汇聚路径)。PermanentDiscard:帧永不到达(压测缺块 → desync → resync 恢复链)。仅 TCP 路径。Loss semantics. RetransmitLate (default, realistic): a lost frame waits RetransmitDelayMs then retransmits, head-of-line blocking its socket meanwhile (nothing lost forever, just late — possibly past ExecuteTick, exercising the late-command / late-block convergence paths). PermanentDiscard: frame never arrives (stresses missing-block → desync → resync recovery). TCP path only. |
RetransmitDelayMs | float | 200.f | 丢失帧重发前的等待(LossMode=RetransmitLate)——模拟一个 RTO 周期。每次重发会再次掷丢包判定,连续丢失按真实概率叠加。Wait before a lost frame retransmits (LossMode=RetransmitLate) — models one RTO round. Each retransmission attempt rolls the drop chance again, so repeated loss compounds realistically. |
DuplicatePercent | float | 0.f | 重复包百分比 0-100——仅 UDP 路径(net.PktDuplicate);TCP 设计上去重,该值在 TCP 侧被忽略。Duplicated-packet percentage 0-100 — UDP path only (net.PktDuplicate); TCP dedupes by design so this is ignored there. |
BandwidthLimitKBs | int32 | 0 | TCP 数据帧出站带宽上限(KB/s,令牌桶)。0 = 不限。较低值可压测大块的分块饥饿 + 重组超时路径。Outbound bandwidth cap in KB/s for TCP data frames (token bucket). 0 = unlimited. Lower values exercise chunk starvation + reassembly timeout paths on large blocks. |
RandomSeed | int32 | 0 | 丢包/抖动判定的随机种子。0 = 按时间播种(不可复现);非 0 = 跨运行可复现的损伤序列。RNG seed for drop/jitter decisions. 0 = time-seeded (non-reproducible); nonzero = reproducible impairment sequence across runs. |
FMassBattleNetCommandBundle USTRUCT
带冗余的指令束。每个束携带主指令 + 前 1-2 条已发送指令,用于非可靠 RPC 通道的概率性丢包恢复。
Bundled command with piggyback redundancy for loss recovery. Each bundle carries the primary command plus 1-2 previously sent commands for probabilistic loss recovery on unreliable RPC channels.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Primary | FMassBattleNetCommand | — | 主指令。Primary command. |
RedundantCommands | TArray<FMassBattleNetCommand> | 空 | 前序指令冗余([0] = 前 1 帧,[1] = 前 2 帧)。Previous commands for redundancy ([0] = 1 frame before, [1] = 2 frames before). |
FEntityHandleFixup USTRUCT
实体句柄引用修正——快照恢复后将 FEntityHandle 字段重映射到本地新句柄。捕获期间,结构性的跨实体句柄被解析为 UniqueID 对;恢复期间,这些 fixup 把句柄重映射到新生成的本地实体。
Entity handle reference fixup — remaps FEntityHandle fields after snapshot restore. During capture, structural cross-entity handles are resolved to UniqueID pairs. During restore, these fixups remap handles to the newly spawned local entities.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SourceUniqueID | int32 | -1 | 句柄源实体的 UniqueID。UniqueID of the handle's source entity. |
FragmentTypeName | FName | — | 持有句柄的 fragment 类型名。Fragment type name holding the handle. |
FieldName | FName | — | 字段名。Field name. |
FieldOffset | int32 | -1 | fragment 结构内 FEntityHandle 字段的字节偏移。Byte offset of the FEntityHandle field within the fragment struct. |
TargetUniqueID | int32 | -1 | 句柄指向目标的 UniqueID。UniqueID of the handle's target. |
FMassBattleNetworkStats USTRUCT
每帧网络诊断信息。
Per-frame network diagnostics.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
ClientPings | TMap<int32, float> | 空 | 每客户端延迟(毫秒)。Per-client ping in milliseconds. |
CommandQueueDepth | int32 | 0 | 指令队列积压深度。Pending command queue depth. |
LastTickHash | int64 | 0 | 上一 tick 的状态哈希。Previous tick's state hash. |
TotalDesyncs | int32 | 0 | 累计失步次数。Total desync events detected. |
LastSnapshotSizeBytes | int32 | 0 | 最近快照大小(字节)。Size of the last snapshot in bytes. |
bIsFastForwarding | bool | false | 是否正在快进追帧。Whether currently fast-forwarding (catching up). |
自定义路径与移动失败判定 Custom Path & Move Fail Condition
FMBCustomPath USTRUCT
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Points | TArray<FVector> | 空 | 自定义路径点数组。Custom path point array. |
FMBMoveFailCondition USTRUCT
移动失败判定条件:目标半径内判到达;低于卡住速度阈值并持续超过卡住时间限制判失败。
Move-failure criteria: arrival within the fail radius; failure when speed stays below the stuck velocity threshold for longer than the stuck time limit.
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
FailRadius | float | 3000.0f | 判定到达/失败的半径(ClampMin=0)。Radius used to judge arrival/failure (ClampMin=0). |
StuckVelocityThreshold | float | 100.0f | 卡住速度阈值(ClampMin=0)。Stuck velocity threshold (ClampMin=0). |
StuckTimeLimit | float | 10.0f | 卡住时间限制,秒(ClampMin=0)。Stuck time limit in seconds (ClampMin=0). |
补充说明 Notes
FMassBattleSnapshotEntity 与 FMassBattleSnapshotProjectile 已移除——快照中由 FEntityTemplateData 取代(文件末尾注释)。文件还包含 FMBCustomPath(自定义路径点数组)与 FMBMoveFailCondition(移动失败判定:失败半径 / 卡住速度阈值 / 卡住时间限制)两个辅助结构。
FMassBattleSnapshotEntity and FMassBattleSnapshotProjectile were removed — replaced by FEntityTemplateData in snapshots (end-of-file comment). The file also holds two helpers: FMBCustomPath (custom path point array) and FMBMoveFailCondition (move-failure criteria: fail radius / stuck velocity threshold / stuck time limit).