UMassBattleDebuffSubsystem
Source/MassBattle/Public/Subsystems/MassBattleDebuffSubsystem.h
概述 Overview
Debuff 实体(减速 FSlowDebuff、持续伤害 FTemporalDmgDebuff)的生成管理中心。核心模式:并行收集、串行排空——伤害应用在并行段把生成请求推入 FParallelGatherer,由 ProcessDebuffSpawnQueues 在游戏线程按确定性元组排序后统一分配 UID 并构建实体,保证锁步双端 UID 分配顺序完全一致。
Central manager for debuff entity spawning (slow FSlowDebuff and temporal damage FTemporalDmgDebuff). Core pattern: parallel gather, serial drain — damage application pushes spawn requests into FParallelGatherer from parallel sections; ProcessDebuffSpawnQueues then drains them on the game thread in a deterministic sorted order, assigning UIDs and building entities so UID allocation order is identical across lockstep peers.
继承 Inheritance
结构体 Structs
减速 debuff 的生成请求记录。伤害应用并行段收集,由 ProcessDebuffSpawnQueues 串行排空。排序元组(TargetUID → InstigatorID → CauserUID → DmgDealt → DmgType)与 DmgGatherer 一致,保证 UID 分配顺序跨端一致。
Spawn request record for slow debuffs. Gathered in parallel from damage application, drained serially by ProcessDebuffSpawnQueues. The sort tuple (TargetUID → InstigatorID → CauserUID → DmgDealt → DmgType) matches the DmgGatherer so UID allocation order is identical across peers.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
TargetUID | int32 | -1 | debuff 目标的实体 UID(-1 = 无效)。排序元组第一键。Entity UID of the debuff target (-1 = invalid). First key of the sort tuple. |
InstigatorID | int32 | -1 | 施害者(instigator)ID,用于伤害归属。Instigator ID, used for damage attribution. |
CauserUID | int32 | -1 | 造成伤害实体的 UID(施法者/causer)。UID of the entity that caused the damage (the causer). |
DmgDealt | float | 0.f | 本次造成的伤害数值,参与排序元组。Amount of damage dealt; participates in the sort tuple. |
DmgType | EDmgType | Normal | 伤害类型(见 Fragments/Damage.h)。Damage type (see Fragments/Damage.h). |
Target | FEntityHandle | — | 目标实体句柄,spawn 时用于读取 FNetworkTag 判断走网络分支还是本地分支。Target entity handle; read at spawn time to decide between the networked and local branch via FNetworkTag. |
Debuff | FSlowDebuff | — | 完整的 debuff fragment 数据,随实体一起构建。Full debuff fragment payload, built together with the entity. |
持续伤害 debuff 的生成请求记录,字段与 FSlowDebuffSpawnRequest 完全相同,仅 Debuff 字段类型为 FTemporalDmgDebuff。
Spawn request record for temporal damage debuffs. Fields are identical to FSlowDebuffSpawnRequest except the Debuff payload is FTemporalDmgDebuff.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
TargetUID | int32 | -1 | debuff 目标的实体 UID。Entity UID of the debuff target. |
InstigatorID | int32 | -1 | 施害者 ID。Instigator ID. |
CauserUID | int32 | -1 | 造成伤害实体的 UID。UID of the causer entity. |
DmgDealt | float | 0.f | 本次造成的伤害数值。Amount of damage dealt. |
DmgType | EDmgType | Normal | 伤害类型。Damage type. |
Target | FEntityHandle | — | 目标实体句柄。Target entity handle. |
Debuff | FTemporalDmgDebuff | — | 持续伤害 debuff fragment 数据。Temporal damage debuff fragment payload. |
公开方法 Public Methods
USubsystem 生命周期入口,当前仅调用父类实现,无额外初始化逻辑。
USubsystem lifecycle entry. Currently only calls the parent implementation; no extra initialization logic.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Collection | FSubsystemCollectionBase& | 子系统集合,由引擎传入。Subsystem collection provided by the engine. |
Output
无返回值。无副作用(仅转发父类)。
No return value. No side effects (forwards to parent only).
USubsystem 生命周期出口。清空两个并行 gatherer(SlowDebuffSpawns / TemporalDmgDebuffSpawns)后调用父类实现。
USubsystem lifecycle exit. Resets both parallel gatherers (SlowDebuffSpawns / TemporalDmgDebuffSpawns), then calls the parent implementation.
Input
无参数。
No parameters.
Output
无返回值。副作用:释放两个 gatherer 持有的请求缓冲。
No return value. Side effect: releases the request buffers held by both gatherers.
每帧 tick 入口。当前实现仅包含 TRACE_CPUPROFILER_EVENT_SCOPE_STR profiling 标记与一条 ID 溢出检查的占位注释,尚无实际逻辑。
Per-frame tick entry. The current implementation only contains a TRACE_CPUPROFILER_EVENT_SCOPE_STR profiling scope and a placeholder comment about ID overflow checking; no actual logic yet.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
DeltaTime | float | 本帧时间步长(秒),当前未被使用。Frame delta time in seconds; currently unused. |
Output
无返回值,无副作用。
No return value, no side effects.
静态访问器:从任意世界上下文对象解析出 UWorld,再取其 Debuff 子系统。世界无效时返回 nullptr(不崩溃)。
Static accessor: resolves the UWorld from any world-context object and returns its Debuff subsystem. Returns nullptr if the world is invalid (does not crash).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
WorldContext | const UObject* | 任意 UObject 世界上下文(通过 GEngine->GetWorldFromContextObject 解析)。Any UObject world context (resolved via GEngine->GetWorldFromContextObject). |
Output
返回子系统指针;世界上下文无效时返回 nullptr。
Returns the subsystem pointer, or nullptr when the world context is invalid.
静态访问器的引用版本:失败即 checkf 断言崩溃——用于「子系统必须存在」的不变式场景。请勿用于可能取不到世界的路径。
Reference version of the static accessor: fails via checkf assertion — for invariant paths where the subsystem must exist. Do not use where the world may be unavailable.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
WorldContext | const UObject* | 任意 UObject 世界上下文。Any UObject world context. |
Output
返回子系统引用;取不到时触发 checkf 断言("Failed to get UMassBattleDebuffSubsystem from world context.")。
Returns a subsystem reference; triggers a checkf assertion ("Failed to get UMassBattleDebuffSubsystem from world context.") when unavailable.
惰性访问并缓存 UMassAPISubsystem:命中缓存直接返回;否则从当前世界取子系统并写入 MassAPISubsystem / CurrentWorld 缓存。
Lazily accesses and caches UMassAPISubsystem: returns the cache on hit; otherwise fetches the subsystem from the current world and fills the MassAPISubsystem / CurrentWorld cache.
Input
无参数。
No parameters.
Output
返回 UMassAPISubsystem 指针(世界不存在时可能为 nullptr)。副作用:写入两个缓存成员。
Returns the UMassAPISubsystem pointer (may be nullptr if the world is missing). Side effect: fills the two cache members.
模板 spawn 入口:先经 UMassBattleSubsystem::AllocNextUID() 分配 UID 写入 Debuff.UniqueID,再委托给 SpawnDebuffEntityWithUID。适用于 UID 在调用点即时分配的单条 spawn 场景(非排空路径)。
Template spawn entry: allocates a UID via UMassBattleSubsystem::AllocNextUID() into Debuff.UniqueID, then delegates to SpawnDebuffEntityWithUID. For single immediate spawns where the UID is assigned at the call site (not the drain path).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
MA | UMassAPISubsystem& | Mass API 子系统,提供 BuildEntityDefer / Defer / HasTag。Mass API subsystem providing BuildEntityDefer / Defer / HasTag. |
CommandBuffer | FMassCommandBuffer& | 延迟命令缓冲,实体 build 命令写入其中。Deferred command buffer receiving the entity build command. |
Target | const FEntityHandle | debuff 目标实体(用于读 FNetworkTag)。Debuff target entity (read for FNetworkTag). |
Debuff | TFragment& | debuff fragment 载荷(引用,UniqueID 会被本函数覆写)。Debuff fragment payload (by reference; UniqueID is overwritten by this function). |
Output
返回新实体的延迟 FMassEntityHandle。副作用:修改 Debuff.UniqueID、消费一个全局 UID 序号。
Returns the deferred FMassEntityHandle of the new entity. Side effects: mutates Debuff.UniqueID, consumes one global UID sequence number.
以预分配 UID 构建 debuff 实体——串行排空路径专用(UID 顺序由 ProcessDebuffSpawnQueues 的排序决定,绝不依赖并行线程调度)。按目标是否带 FNetworkTag 分两支:网络分支额外携带 FNetworkTag + FNetworking(Key),使 debuff 命中网络子查询、快照捕获使用已注册骨架模板 Key;本地分支无网络标记。两支都带 FDebuffTag + FMainType(Debuff) + FDeterminism(UID 种子)。
Builds a debuff entity with a pre-assigned UID — for the serial drain path only (UID order is decided by the ProcessDebuffSpawnQueues sort, never by parallel thread scheduling). Two branches based on whether the target carries FNetworkTag: the networked branch adds FNetworkTag + FNetworking(Key) so the debuff matches network sub-queries and snapshot capture uses the registered skeleton template key; the local branch carries no network markers. Both branches include FDebuffTag + FMainType(Debuff) + FDeterminism(UID seed).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
MA | UMassAPISubsystem& | Mass API 子系统。Mass API subsystem. |
CommandBuffer | FMassCommandBuffer& | 延迟命令缓冲。Deferred command buffer. |
Target | const FEntityHandle | debuff 目标实体,用于 HasTag<FNetworkTag> 判断。Debuff target entity, used for the HasTag<FNetworkTag> check. |
Debuff | TFragment& | debuff fragment 载荷。Debuff fragment payload. |
AssignedUID | const int32 | 预分配的 UID,写入 Debuff.UniqueID 并作为 FDeterminism 种子。Pre-assigned UID; written to Debuff.UniqueID and used as the FDeterminism seed. |
Output
返回新实体的延迟句柄。注意:实体尚未 build,故不在 spawn 处注册 UID——由 UMassBattleNetworkProcessor 每 tick 从其 debuff 查询注册(查询命中即实体已 build)。
Returns the deferred handle of the new entity. Note: the entity is not built yet, so UID registration is deferred — UMassBattleNetworkProcessor registers it each tick from its debuff query (query match implies the entity is built).
并行收集的 debuff 生成请求的串行排空入口(由 ProcessHostOpsQueues 调用)。流程:① Merge() 合并各线程本地槽;② 若 UMassBattleSubsystem::bDeterministic 开启且请求数 > 1,按确定性元组排序——TargetUID → InstigatorID → CauserUID → DmgDealt → DmgType(int32 比较);③ 逐一调用 SpawnDebuffEntityWithUID(UID 在排空时串行分配);④ Reset() 清空 gatherer。两类 debuff(减速/持续伤害)各自独立完成同一流程。
Serial drain entry for parallel-gathered debuff spawn requests (called from ProcessHostOpsQueues). Flow: ① Merge() merges per-thread slots; ② if UMassBattleSubsystem::bDeterministic is on and more than one request exists, sort by the deterministic tuple — TargetUID → InstigatorID → CauserUID → DmgDealt → DmgType (compared as int32); ③ spawn each via SpawnDebuffEntityWithUID (UIDs allocated serially during the drain); ④ Reset() the gatherer. Both debuff kinds (slow / temporal damage) run the same flow independently.
Input
无参数(请求来自成员 gatherer)。
No parameters (requests come from the member gatherers).
Output
无返回值。副作用:消费全部排队请求并清空两个 gatherer、分配若干全局 UID、向命令缓冲写入实体 build 命令。
No return value. Side effects: consumes all queued requests and resets both gatherers, allocates global UIDs, and writes entity build commands into the command buffer.
模板 Key 映射的单一来源:spawn 时写入 FNetworking.Key 与快照注册表的模板 Key 都取自本函数,两侧原子同步。FSlowDebuff → "Debuff_Slow";FTemporalDmgDebuff → "Debuff_TemporalDmg";其它类型 → NAME_None。
Single source of the template key mapping: both the spawn-time FNetworking.Key and the snapshot registry template key come from this function, so the two sides stay atomically in sync. FSlowDebuff → "Debuff_Slow"; FTemporalDmgDebuff → "Debuff_TemporalDmg"; anything else → NAME_None.
Input
无参数(仅模板参数 TFragment,编译期 if constexpr 分派)。
No parameters (compile-time if constexpr dispatch on TFragment only).
Output
返回模板对应的 FName Key;未支持类型返回 NAME_None。
Returns the FName key for the template; NAME_None for unsupported types.
构建 debuff 骨架模板——仅身份(archetype 组合),运行时状态由快照 blob 恢复时覆盖。组合:FDebuffTag + FNetworkTag + FMainType(Debuff) + TFragment + FDeterminism + FNetworking(Key)。纪律:组合必须与 SpawnDebuffEntityWithUID 的网络分支完全一致,否则恢复出的 debuff 会掉出处理器查询。
Builds a debuff skeleton template — identity only (archetype composition); runtime state is overwritten by the snapshot blob on restore. Composition: FDebuffTag + FNetworkTag + FMainType(Debuff) + TFragment + FDeterminism + FNetworking(Key). Rule: the composition MUST match the networked branch of SpawnDebuffEntityWithUID exactly, otherwise restored debuffs fall out of processor queries.
Input
无参数(仅模板参数)。
No parameters (template only).
Output
返回 FEntityTemplateData(内部 FMassEntityTemplateData 以 MakeShared 共享)。
Returns FEntityTemplateData (inner FMassEntityTemplateData is shared via MakeShared).
把两个 debuff 骨架模板幂等注册进网络快照注册表(RegisterNetworkTemplateData,重复进入返回已有注册)。由 UMassBattleNetworkSubsystem::Initialize 调用一次——发生在任何 peer 应用任何快照之前。
Idempotently registers both debuff skeleton templates into the network snapshot registry (RegisterNetworkTemplateData; re-entry returns the existing registration). Called once from UMassBattleNetworkSubsystem::Initialize — before any snapshot is applied on any peer.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Net | UMassBattleNetworkSubsystem& | 网络子系统,提供 RegisterNetworkTemplateData。Network subsystem providing RegisterNetworkTemplateData. |
WorldContext | const UObject* | 世界上下文,透传给注册调用。World context, forwarded to the registration call. |
Output
无返回值。副作用:注册表中出现 Debuff_Slow / Debuff_TemporalDmg 两个模板 Key。
No return value. Side effect: registry gains the Debuff_Slow / Debuff_TemporalDmg template keys.
成员变量 Members
减速 debuff 生成请求的并行收集器(thread-local 槽位,无锁)。伤害应用并行段 push,ProcessDebuffSpawnQueues 串行 Merge/排序/排空。公开成员——由 ProcessSingleEntityDamageAndDebuff 直接写入。
Parallel gatherer for slow debuff spawn requests (thread-local slots, lock-free). Pushed from the damage-application parallel section; merged/sorted/drained serially by ProcessDebuffSpawnQueues. Public member — written directly by ProcessSingleEntityDamageAndDebuff.
持续伤害 debuff 生成请求的并行收集器,用法与 SlowDebuffSpawns 相同。
Parallel gatherer for temporal damage debuff spawn requests; same usage as SlowDebuffSpawns.
私有缓存:首次 GetMassAPISubsystem 时记录当前世界。
Private cache: records the current world on the first GetMassAPISubsystem call.
私有缓存:UMassAPISubsystem 惰性指针。
Private cache: lazily-resolved UMassAPISubsystem pointer.
管线角色 Pipeline Role
在 MassBattle 管线中的位置:伤害应用(ProcessSingleEntityDamageAndDebuff,并行段)收集请求 → 宿主操作排空(ProcessHostOpsQueues)调用 ProcessDebuffSpawnQueues 串行排空 → 实体在命令缓冲 build 后由 UMassBattleNetworkProcessor 每 tick 从 debuff 查询注册 UID 入网 → 快照捕获/恢复走注册的骨架模板 Key(Debuff_Slow / Debuff_TemporalDmg)。模板注册发生在 UMassBattleNetworkSubsystem::Initialize,先于任何快照应用。
Position in the MassBattle pipeline: damage application (ProcessSingleEntityDamageAndDebuff, parallel section) gathers requests → host-ops drain (ProcessHostOpsQueues) calls ProcessDebuffSpawnQueues for the serial drain → once the entity is built via the command buffer, UMassBattleNetworkProcessor registers its UID from its debuff query each tick → snapshot capture/restore uses the registered skeleton template keys (Debuff_Slow / Debuff_TemporalDmg). Template registration happens in UMassBattleNetworkSubsystem::Initialize, before any snapshot is applied.