IMassBattleAgentInterface
Source/MassBattle/Public/Interfaces/MassBattleAgentInterface.h
概述 Overview
agent 生命周期/行为事件的对外回调接口(全部为 BlueprintCallable + BlueprintNativeEvent,实现方通常为 FAgentEvent.EventReceiveActor 绑定的 Actor)。声明 12 个事件:出生(OnAppear)、移动(OnMove)、索敌(OnTrace)、攻击(OnAttack)、受击(OnHit)、死亡(OnDeath)、休眠(OnSleep)、巡逻(OnPatrol)、追逐(OnChase)、动画状态(OnAnimStateChange)、统计(OnStatisticsChange)、对象池(OnPool)。事件载荷结构(全部带 SelfEntity + UniqueID 公共字段)定义于 MassBattleStructs.h。分发路径:各处理器在并行段把事件推入 UMassBattleSubsystem 的 On*Queue,ProcessEventQueues 串行消费并 Execute_On* 分发给实现接口的 Actor。
Outward callback interface for agent lifecycle/behavior events (all BlueprintCallable + BlueprintNativeEvent; implementers are usually the Actor bound as FAgentEvent.EventReceiveActor). Declares 12 events: appear (OnAppear), move (OnMove), trace (OnTrace), attack (OnAttack), hit (OnHit), death (OnDeath), sleep (OnSleep), patrol (OnPatrol), chase (OnChase), animation state (OnAnimStateChange), statistics (OnStatisticsChange), pool (OnPool). The payload structs (all carrying the common SelfEntity + UniqueID fields) are defined in MassBattleStructs.h. Dispatch path: processors push events into the On*Queue of UMassBattleSubsystem from parallel sections; ProcessEventQueues drains serially and dispatches Execute_On* to Actors implementing the interface.
接口方法 Interface Methods
对象池事件:由 MassBattleSubsystem 事件队列触发——单位实体从对象池取出或归还时(State = PoolSpawn 出池 / PoolRecycle 入池)。可用于获取/释放时的初始化与重置(如重置外观或状态)。
Pool event: raised by the MassBattleSubsystem event queue when the agent entity is taken from or returned to the agent object pool (State = PoolSpawn / PoolRecycle). Use for acquire/release setup such as resetting visuals or state.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FPoolData& | 含 SelfEntity(被池管理的实体)、State(池事件状态,默认 PoolSpawn)、UniqueID。Contains SelfEntity (the pooled entity), State (pool event state, default PoolSpawn), UniqueID. |
Output
无返回值。无内置副作用(行为由实现方决定)。
No return value. No built-in side effects (behavior is up to the implementer).
移动事件:单位移动状态变化时触发(Moving 移动中 / Arrived 已到达 / Returning 被推离后返回,见 EMoveEventState)。仅通知,无返回值。事件由 MassBattleAgentMoveProcessor(FP 变体同理)在并行段推入 OnMoveQueue。
Move event: raised when the agent's movement state changes (Moving / Arrived / Returning, see EMoveEventState) — a fire-and-forget notification with no return value. Pushed into OnMoveQueue from the parallel section by MassBattleAgentMoveProcessor (and the FP variant).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FMoveData& | 含 SelfEntity(执行移动的实体)、State(移动事件状态,默认 Arrived)、UniqueID。Contains SelfEntity (the moving entity), State (move event state, default Arrived), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
索敌事件:实体索敌状态变化时触发(如找到/丢失目标)。事件由 MassBattleAgentTraceProcessor 推入 OnTraceQueue。
Trace event: triggered when the entity's target-acquisition state changes (e.g. target found / lost). Pushed into OnTraceQueue by MassBattleAgentTraceProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FTraceData& | 含 SelfEntity(执行索敌的实体)、State(事件状态,默认 Begin)、TraceResult(被找到/丢失的实体句柄)、UniqueID。Contains SelfEntity (the tracing entity), State (event state, default Begin), TraceResult (the entity found or lost), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
攻击事件:实体攻击状态变化时触发(如瞄准中/发射/完成)。事件由 MassBattleAgentBehaviorProcessor 推入 OnAttackQueue。
Attack event: triggered when the entity's attack state changes (e.g. aiming / firing / finished). Pushed into OnAttackQueue by MassBattleAgentBehaviorProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FAttackData& | 含 SelfEntity(执行攻击的实体)、State(攻击事件状态,默认 Aiming)、AttackTarget(主要目标)、DmgResults(本次攻击的伤害结果列表)、UniqueID。Contains SelfEntity (the attacking entity), State (attack event state, default Aiming), AttackTarget (primary target), DmgResults (damage result list from this attack), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
出生事件:单位实体生成到世界时触发一次(出池之后)。可用于出场时的外观初始化。事件由 MassBattleAgentBehaviorProcessor 推入 OnAppearQueue。
Appear event: raised once when the agent entity is spawned into the world (after pool acquire); use for first-frame appearance setup. Pushed into OnAppearQueue by MassBattleAgentBehaviorProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FAppearData& | 含 SelfEntity(刚出现/生成的实体)与 UniqueID。Contains SelfEntity (the entity that just appeared/spawned) and UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
受击事件:实体被击中/受伤时触发。载荷可经 FDmgResult 构造函数从伤害结果转换(带暴击/致死标记、伤害方向与位置、随击减益信息)。事件由 MassBattleAgentReactionProcessor 等伤害应用路径推入 OnHitQueue。
Hit event: triggered when the entity is hit/damaged. The payload can be constructed from an FDmgResult (carrying critical/kill flags, hit direction and location, accompanying debuff info). Pushed into OnHitQueue by the damage-application path such as MassBattleAgentReactionProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FHitData& | 含 SelfEntity(被击中的实体)、InstigatorEntity(引发击中的实体)、CauserEntity(导致击中的实体,如弹丸)、IsCritical、IsKill、DmgDealt、HitDirection、HitLocation、DebuffInfo、UniqueID。Contains SelfEntity (the hit entity), InstigatorEntity, CauserEntity (e.g. a projectile), IsCritical, IsKill, DmgDealt, HitDirection, HitLocation, DebuffInfo, UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
死亡事件:单位死亡时触发——血量耗尽、寿命到期、自杀攻击或低于 KillZ(见 EDeathEventState)。可在此播放死亡特效/音效;实体本身由子系统回收。事件由死亡处理路径推入 OnDeathQueue。
Death event: raised when the agent dies — health depleted, lifespan expired, suicide attack or below KillZ (see EDeathEventState). Trigger death VFX/sounds here; the entity itself is recycled by the subsystem. Pushed into OnDeathQueue by the death-processing path.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FDeathData& | 含 SelfEntity(死亡的实体)、InstigatorEntity(导致死亡的实体)、State(死亡事件状态,默认 OutOfHealth)、UniqueID。Contains SelfEntity (the dead entity), InstigatorEntity (the entity responsible), State (death event state, default OutOfHealth), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
动画状态变化事件:实体动画状态机切换时触发,载荷含旧/新状态与当前动画播放信息(索引、速率、进度、是否循环)。事件由 MassBattleAgentRenderProcessor 推入 OnAnimStateChangeQueue。
Animation state change event: triggered when the entity's animation state machine switches; the payload carries the previous/new states and current animation playback info (index, rate, progress, looping). Pushed into OnAnimStateChangeQueue by MassBattleAgentRenderProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FAnimStateChangeData& | 含 SelfEntity、PreviousState(旧动画状态,默认 Idle)、NewState(新动画状态)、AnimData(选中的动画数据:索引/长度/起始帧/结束帧)、CurrentAnimInfo(播放信息,FAnimEventData)、UniqueID。Contains SelfEntity, PreviousState (default Idle), NewState, AnimData (selected animation data: index/length/start frame/end frame), CurrentAnimInfo (FAnimEventData), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
统计变化事件:实体统计数据变化时触发,载荷携带完整 FStatistics fragment 快照。事件由 MassBattleAgentReactionProcessor 推入 OnStatisticsChangeQueue。
Statistics change event: triggered when the entity's statistics change; the payload carries a full FStatistics fragment snapshot. Pushed into OnStatisticsChangeQueue by MassBattleAgentReactionProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FStatisticsData& | 含 SelfEntity、Statistics(当前统计数据 fragment 快照)、UniqueID。Contains SelfEntity, Statistics (current statistics fragment snapshot), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
休眠事件:实体进入/退出休眠时触发。事件由 MassBattleAgentBehaviorProcessor 推入 OnSleepQueue。
Sleep event: triggered when the entity enters/exits sleep. Pushed into OnSleepQueue by MassBattleAgentBehaviorProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FSleepData& | 含 SelfEntity、State(休眠事件状态,默认 Enter)、UniqueID。Contains SelfEntity, State (sleep event state, default Enter), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
巡逻事件:实体巡逻状态变化时触发(进入/退出/巡逻中/等待中)。事件由 MassBattleAgentMoveProcessor/MassBattleAgentBehaviorProcessor 推入 OnPatrolQueue。
Patrol event: triggered when the entity's patrol state changes (enter/exit/patrolling/waiting). Pushed into OnPatrolQueue by MassBattleAgentMoveProcessor/MassBattleAgentBehaviorProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FPatrolData& | 含 SelfEntity、State(巡逻事件状态,默认 Enter)、UniqueID。Contains SelfEntity, State (patrol event state, default Enter), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
追逐事件:实体追逐状态变化时触发(进入/退出/追逐中/已追到)。事件由 MassBattleAgentMoveProcessor/MassBattleAgentBehaviorProcessor 推入 OnChaseQueue。
Chase event: triggered when the entity's chase state changes (enter/exit/chasing/reached). Pushed into OnChaseQueue by MassBattleAgentMoveProcessor/MassBattleAgentBehaviorProcessor.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Data | const FChaseData& | 含 SelfEntity、State(追逐事件状态,默认 Enter)、UniqueID。Contains SelfEntity, State (chase event state, default Enter), UniqueID. |
Output
无返回值。无内置副作用。
No return value. No built-in side effects.
管线角色 Pipeline Role
事件流:各处理器并行段(索敌 TraceProcessor、移动 MoveProcessor/MoveProcessorFP、行为 BehaviorProcessor、受击/统计 ReactionProcessor、动画 RenderProcessor)把事件推入 UMassBattleSubsystem 的 On*Queue → ProcessEventQueues 串行消费,对每个事件按接收者解析其 FAgentEvent/FAgentEventRT.EventReceiveActor(经 FAgentController/绑定指针),调用对应 IMassBattleAgentInterface::Execute_On*(Actor, Data)(见 MassBattleSubsystem.cpp 的 ProcessQueue 段,12 个队列逐一映射)。
Event flow: processor parallel sections (trace TraceProcessor, move MoveProcessor/MoveProcessorFP, behavior BehaviorProcessor, hit/statistics ReactionProcessor, animation RenderProcessor) push events into the On*Queue of UMassBattleSubsystem → ProcessEventQueues drains serially, resolving each event's receiver via FAgentEvent/FAgentEventRT.EventReceiveActor (through FAgentController/binding pointers) and calling the matching IMassBattleAgentInterface::Execute_On*(Actor, Data) (see the ProcessQueue section of MassBattleSubsystem.cpp, mapping all 12 queues).
补充说明 Notes
FReinforceData 结构存在于 MassBattleStructs.h(支援事件载荷),但本接口未声明对应的 OnReinforce 事件 —— 接口与载荷结构列表并不一一对应。
FReinforceData exists in MassBattleStructs.h (reinforce event payload), but this interface declares no corresponding OnReinforce event — the interface and the payload struct list do not map one-to-one.