FxHostConfig.h
Source/MassBattle/Public/Fragments/FxHostConfig.h
概述 Overview
特效(FX)宿主的生成配置集合。作者配置 FFxConfig(Niagara/Cascade 资产、合批子类型/风格索引、插值模式、延迟/寿命/概率等)与 FFxConfig_Attack(攻击场景,多 SpawnOrigin);运行时 fragment FFxConfig_Final 经转换构造注入,附加随机流、归属句柄、已生成组件追踪与对象池生命周期。文件末尾的命令结构 FFxOptCommand 与两个迁移模板函数 MigrateFxConfigSubType / MigrateFxConfigStyleType(PostLoad 旧资产迁移用)。
FX-host spawn configuration collection. Authored configs FFxConfig (Niagara/Cascade assets, batched subtype/style indices, interpolation mode, delay/lifespan/probability) and FFxConfig_Attack (attack scenario, adds SpawnOrigin); the runtime fragment FFxConfig_Final is injected via converting constructors, adding a random stream, ownership handles, spawned-component tracking and pooling lifecycle. The file ends with the command struct FFxOptCommand and two migration templates MigrateFxConfigSubType / MigrateFxConfigStyleType (PostLoad legacy migration).
FFxConfig USTRUCT
通用 FX 生成配置(非 fragment)。含合批(SubType_Index / StyleType_Index,给特效渲染器筛选用)与非合批(软引用 Niagara/Cascade 资产)两条路径。默认 bLockstepNetworked = true。
Generic FX spawn config (not a fragment). Supports both batched (SubType_Index / StyleType_Index, used by the effect renderer for filtering) and unbatched (soft-referenced Niagara/Cascade assets) paths. Defaults bLockstepNetworked = true.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bEnable | bool | true | 启用。Enable. |
SubType | EESubType | None | 已废弃——仅供旧资产反序列化,改用 SubType_Index。Deprecated — kept for legacy asset deserialization only; use SubType_Index. |
SubType_Index | int32 | -1 | 合批特效的子类型,给特效渲染器做筛选用;设置为 -1 为不使用(Clamp -1..255)。Subtype of batched effects, used for filtering by the effect renderer; -1 disables (Clamp -1..255). |
StyleType | EEStyleType | Style0 | 已废弃——仅供旧资产反序列化,改用 StyleType_Index。Deprecated — kept for legacy asset deserialization only; use StyleType_Index. |
StyleType_Index | int32 | 0 | 风格索引,以 int32 形式传入合批 NS,自行使用(Clamp 0..255)。Style index passed into the batched NS as an int32, use at your own will (Clamp 0..255). |
SoftNiagaraAsset | TSoftObjectPtr<UNiagaraSystem> | — | 非合批特效 Niagara 资产软引用。Unbatched Niagara effect asset (soft reference). |
SoftCascadeAsset | TSoftObjectPtr<UParticleSystem> | — | 非合批特效 Cascade 资产软引用。Unbatched Cascade effect asset (soft reference). |
NiagaraAsset / CascadeAsset | TObjectPtr | nullptr | 运行时解析的硬引用资产(非蓝图编辑)。Runtime-resolved hard references (not editable). |
Transform | FTransform3f | Identity | 偏移量。Offset. |
bAttached | bool | false | 附着。Attached. |
bDespawnWhenNoParent | bool | true | 附着点失效后自毁。仅当 bEnable 且 bAttached 为 true 时可编辑。Destroy when the attachment point becomes invalid. Editable only when both bEnable and bAttached are true. |
bLockstepNetworked | bool | true | 该宿主是否参与网络同步(snapshot/hash/resync)。同步与不同步宿主在池中共存——弹池按 FNetworkTag 匹配槽位。仅当 bEnable 为 true 时可编辑。Whether this host participates in network sync (snapshot/hash/resync). Sync and non-sync hosts coexist in pools — slots are matched by FNetworkTag at pop time. Editable only when bEnable is true. |
Delay | float | 0 | 延时生成。Spawn delay. |
LifeSpan | float | 5 | 生成后存活时长(秒),负值为无限长。Lifespan after spawn (seconds); negative for infinite. |
BindToAnimIndex | int32 | -1 | 绑定动画索引:>= 0 时仅在使用该动画索引时生成;-1 则对所有动画生成。Animation binding: >= 0 spawns only when that animation index is used; -1 for all animations. |
SpawnProbability | FVector4f | (0, 1, 10000, 1) | 生成概率参数(X=AgentCountMin, Y=SpawnProbabilityAtMin, Z=AgentCountMax, W=SpawnProbabilityAtMax)。Spawn probability parameters (X=Min agent count, Y=prob at Min, Z=Max count, W=prob at Max). |
AgentBehaviorState | EAgentBehaviorState | None | 该特效关联的 Agent 行为状态。Agent behavior state this FX is associated with. |
InterpMode | EInterpMode | GPU | 合批特效插值模式:GPU = Niagara Custom HLSL(仅 GPU 发射器);CPU = 逐帧 VInterpTo(任意发射器)。仅对附着的合批特效生效(bEnable + bAttached + SubType_Index ≥ 0),否则灰掉。Batched FX interpolation mode: GPU = Niagara Custom HLSL (GPU emitter only); CPU = per-frame VInterpTo (any emitter). Only applies to attached batched FX (bEnable + bAttached + SubType_Index >= 0); grayed otherwise. |
FFxConfig_Attack USTRUCT
攻击命中时刻使用的 FX 生成配置(非 fragment),与 FFxConfig 字段完全一致,额外多出 SpawnOrigin。
FX spawn config for the attack hit moment (not a fragment); fields identical to FFxConfig plus SpawnOrigin.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
SpawnOrigin | ESpawnOrigin | AtSelf | 生成原点(例如在自身位置、在目标位置)。Spawn origin (e.g. AtSelf, AtTarget). |
bEnable 等其余字段 | 同 FFxConfig | 同左 | 字段与 FFxConfig 完全相同(含 InterpMode / bLockstepNetworked)。Fields identical to FFxConfig (including InterpMode / bLockstepNetworked). |
FFxConfig_Final USTRUCT
FX 宿主运行时 fragment(FA_MassBattleBaseFragment 派生)。由 FFxConfig 或 FFxConfig_Attack 经转换构造注入。前部为配置字段,后部(RandomStream 起)为运行时状态:随机流、归属句柄、已生成组件/实体追踪(含配对 FX 实体 PairedFxEntity)、生命周期标志与对象池字段,并提供组件释放静态方法与清理/复位方法。经 MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE 声明为不可平凡拷贝。
FX-host runtime fragment (derived from FA_MassBattleBaseFragment). Injected from FFxConfig or FFxConfig_Attack via converting constructors. The leading fields are config; the trailing block (from RandomStream) is runtime state: random stream, ownership handles, spawned component/entity tracking (including the paired FX entity PairedFxEntity), lifecycle flags and pooling fields, plus static component-release helpers and clear/reset methods. Declared via MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bEnable … bLockstepNetworked | 同 FFxConfig_Attack | 同左 | 配置段:与 FFxConfig_Attack 相同的字段(含 SpawnOrigin / InterpMode)。Config block: same fields as FFxConfig_Attack (including SpawnOrigin / InterpMode). |
RandomStream | FRandomStream | — | 概率检查的随机流(运行时)。Random stream for probability checks (runtime). |
OwnerEntity | FEntityHandle | — | 生成者实体。Owner entity. |
AttachToEntity | FEntityHandle | — | 要附着到的实体。Entity to attach to. |
SpawnTransform | FTransform | — | 生成变换(运行时计算)。Spawn transform (computed at runtime). |
SpawnEventParentTransform | FTransform | Identity | 生成请求时刻(出生/销毁瞬间)捕获的父级世界变换。与 SpawnTransform 不同,不会被逐帧父级解析(HostMonoProcessor)覆盖——供 FX 注册把首帧锚定到诚实的事件位置(锁步确定性渲染晚 1+ tick)。快照注册表字段。Event-time parent world transform captured at the spawn request (birth/death moment). Unlike SpawnTransform it is NEVER overwritten by the per-frame parent resolve (HostMonoProcessor), so the FX registration can anchor its first rendered frame to the honest event position (deterministic lockstep renders 1+ ticks late). Snapshot registry field. |
SpawnEventWorldTransform | FTransform | Identity | 事件时刻 FX 自身世界变换(= 请求时 SpawnTransform,父级 × 相对,含偏移)。供 burst(非附着)注册把首帧锚定到诚实的事件位置;永不被逐帧父级解析覆盖。快照注册表字段。Event-time FX WORLD transform captured at the spawn request (= the request SpawnTransform, parent × relative, offset included). Used by the burst (non-attached) registration so the first rendered frame shows the honest event position; NEVER overwritten by the per-frame parent resolve. Snapshot registry field. |
InitialRelativeTransform | FTransform3f | Identity | 初始相对变换。Initial relative transform. |
bInitialized / bSpawned / bIsPooled / bShouldDestroy | bool | false | 初始化 / 已生成 / 来自对象池 / 下一帧销毁 标志。Initialized / spawned / pooled / destroy-next-tick flags. |
LaunchSpeed | float | 0 | 发射速度(运行时)。Launch speed (runtime). |
PoolCountdown | float | 15.0f | 对象池保留倒计时(秒)。Pool retention countdown (seconds). |
bNeedsSpawnRefresh | bool | false | resync 后瞬态:恢复端置位,HostMonoProcessor 刷新段消费——只重发 UObject 组件生成 op,不重跑概率(会双消费 RandomStream.FRand)也不重激活配对 FX 实体(已随快照恢复)。不进任何注册表。Post-resync transient: set by restore, consumed by the HostMonoProcessor refresh pass — re-issues the UObject component spawn op WITHOUT re-running probability and WITHOUT re-activating the paired FX entity (already restored). Never enters any registry. |
PairedFxEntity | FEntityHandle | — | 与宿主在池创建时配对的预分配 FX 实体。生命周期绑定宿主:随宿主创建/销毁,经 FEntityFlagFragment 激活/停用而非实体创建/销毁。快照注册表字段(恢复按 UID 解析)。Pre-allocated FX entity paired with this host at pool creation. Lifecycle bound to the host; activated/deactivated via FEntityFlagFragment instead of entity create/destroy. Snapshot registry field (restore resolves via UID). |
SpawnedNiagaraSystem / SpawnedCascadeSystem | TObjectPtr | nullptr | 当前主特效组件指针。Current primary effect component pointers. |
SpawnedNiagaraSystems / SpawnedCascadeSystems / SpawnedFxEntities | TArray | 空 | 已生成组件/实体的追踪列表,池复用时即时清理。Tracked spawned components/entities for eager cleanup on pool reuse. |
方法 Methods
释放单个 Niagara 组件:立即停用(DeactivateImmediate)后归还对象池(ReleaseToPool)。组件无效时直接返回。
Releases a single Niagara component: DeactivateImmediate then ReleaseToPool. Returns early when the component is invalid.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Component | UNiagaraComponent* | 待释放的组件。Component to release. |
Output
无返回值。副作用:组件停用并归还池(或跳过)。
No return value. Side effects: component deactivated and pooled (or skipped).
释放单个 Cascade 组件,按池化方式分三支:ManualRelease 直接归还池;ManualRelease_OnComplete 立即停用;其它方式停用后销毁组件。
Releases a single Cascade component with three branches by pooling method: ManualRelease pools directly; ManualRelease_OnComplete deactivates immediately; otherwise deactivates and destroys the component.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Component | UParticleSystemComponent* | 待释放的组件。Component to release. |
Output
无返回值。副作用:按池化方式归还/停用/销毁。
No return value. Side effects: pooled / deactivated / destroyed per pooling method.
释放所有追踪的组件并清空数组(主组件与列表全部处理),复用池中 Host 前调用。
Releases all tracked components (both primary pointers and the lists) and empties the arrays. Called before reusing a pooled host.
Input
无参数。
No parameters.
Output
无返回值。副作用:全部组件释放,主指针置空,三个追踪数组清空。
No return value. Side effects: all components released, primary pointers nulled, the three tracking arrays emptied.
复位运行时状态以复用:标志清零、bIsPooled=true、PoolCountdown=InPoolIdleTTL、组件/实体追踪清空、句柄清空。InPoolIdleTTL 为统一池闲置倒计时(HostSubsystem 的 PoolIdleLifeSpan),默认值 15 保证非回收调用点行为不变——宿主回收路径由 MassBattleHostMonoProcessor 传入 ini 配置的 PoolIdleLifeSpan。PairedFxEntity 刻意不清除——随池槽位持续存在。
Resets runtime state for reuse: flags cleared, bIsPooled=true, PoolCountdown=InPoolIdleTTL, component/entity tracking emptied, handles cleared. InPoolIdleTTL is the unified pool idle countdown (the HostSubsystem's PoolIdleLifeSpan); the 15.0f default keeps non-recycle call sites unchanged — host-recycle paths pass the ini-configured PoolIdleLifeSpan from MassBattleHostMonoProcessor. PairedFxEntity is intentionally NOT cleared — it persists with the pool slot.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InPoolIdleTTL | float | 池闲置倒计时(秒),写入 PoolCountdown;默认 15。Pool idle countdown (seconds), written into PoolCountdown; default 15. |
Output
无返回值。副作用:运行时状态复位(保留 PairedFxEntity)。
No return value. Side effects: runtime state reset (PairedFxEntity kept).
FFxOptCommand USTRUCT
命令缓冲记录:宿主实体对 UObject 特效组件的操作请求(默认 Spawn)。由宿主逻辑写入,宿主处理器消费执行;第二个构造可携带已生成的组件指针。
Command-buffer record: a host entity's operation request on UObject FX components (default Spawn). Written by host logic, consumed by the host processor; the second constructor carries the spawned component pointers.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
Entity | FMassEntityHandle | — | 操作关联的宿主实体。Host entity associated with the operation. |
OperationType | EUObjectOptType | Spawn | 操作类型。Operation type. |
OwnerUniqueID | int32 | -1 | 所属实体 UID,-1 为无效。Owner entity UID; -1 = invalid. |
NiagaraComponent / CascadeComponent | TObjectPtr | nullptr | 操作涉及的组件指针(可选)。Component pointers involved (optional). |
迁移模板 Migrations
把废弃的 EESubType(枚举值 = 索引+1,None = 0)复制到 int32 SubType_Index:None → -1(渲染器键空间从 0 开始 = SubType0)。由数据资产 PostLoad 迁移调用。
Copies the deprecated EESubType (enum value = index + 1, None = 0) into int32 SubType_Index: None → -1 (renderer key space starts at 0 = SubType0). Used by data asset PostLoad migrations.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Configs | TArray<TFxConfig>& | 待迁移的配置数组(原地修改)。Config array to migrate (modified in place). |
Output
无返回值。副作用:每个配置的 SubType_Index 被覆写。
No return value. Side effect: each config's SubType_Index overwritten.
把废弃的 EEStyleType(Style0=0..Style31=31,无偏移无 None)复制到 int32 StyleType_Index。由数据资产 PostLoad 迁移调用。
Copies the deprecated EEStyleType (Style0=0..Style31=31, no offset, no None) into int32 StyleType_Index. Used by data asset PostLoad migrations.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Configs | TArray<TFxConfig>& | 待迁移的配置数组(原地修改)。Config array to migrate (modified in place). |
Output
无返回值。副作用:每个配置的 StyleType_Index 被覆写。
No return value. Side effect: each config's StyleType_Index overwritten.
管线角色 Pipeline Role
FFxConfig_Final 由宿主子系统在 FX 宿主实体创建时从作者配置转换注入;FFxOptCommand 由宿主逻辑写入命令缓冲,MassBattleHostMonoProcessor 消费执行组件生成/销毁;Reset() / ClearSpawnedObjects() 在宿主回池复用时调用。PairedFxEntity 在池创建时预分配,经 FEntityFlagFragment 激活/停用,随快照恢复(按 UID 解析)。
FFxConfig_Final is injected from authored config by the host subsystem at FX-host entity creation; FFxOptCommand is written to the command buffer by host logic and consumed by MassBattleHostMonoProcessor for component spawn/destroy; Reset() / ClearSpawnedObjects() run on host pool reuse. PairedFxEntity is pre-allocated at pool creation, activated/deactivated via FEntityFlagFragment, and restored with the snapshot (resolved by UID).