UMassBattleProjectileComponent
Source/MassBattle/Public/Components/MassBattleProjectileComponent.h
概述 Overview
把 Actor 绑定到 Mass 抛射物实体的组件,派生自 UMassBattleEntityComponentBase。核心职责:从 ProjectileConfigAsset 经 UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset 构建模板,按 MovementMode(Static / Interped / Ballistic / Tracking)分派到对应的 SpawnProjectile_*_FromTemplate 生成;组件字段携带生成参数(目标位置/实体/速度/初始方向、发起者、忽略碰撞实体、乘数);锁步会话(IsLockstepSession(),会话驱动——客户端始终走锁步栈,服务器/单机读网络 GameMode 的 bEnableNetworkSync)时走服务器驱动的 ProjectileComponent.Spawn 锁步指令路径;绑定经实体 FProjectileEventRT.BindingComponentPtr(组件反查也走该字段);快照恢复后按 OwningProjectileUniqueID 重链。
Binds an Actor to a Mass projectile entity; derived from UMassBattleEntityComponentBase. Core responsibilities: builds the template from ProjectileConfigAsset via UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset, dispatching by MovementMode (Static / Interped / Ballistic / Tracking) to the matching SpawnProjectile_*_FromTemplate; component fields carry the spawn parameters (target location/entity/velocity, initial direction, instigator, ignored entities, multipliers); in a lockstep session (IsLockstepSession(), session-driven — clients always ride the lockstep stack; server/standalone read the network GameMode's bEnableNetworkSync) routing goes through the server-driven ProjectileComponent.Spawn lockstep command path; binding goes through the entity's FProjectileEventRT.BindingComponentPtr (component lookup too); after snapshot restore re-links by OwningProjectileUniqueID.
继承 Inheritance
公开方法 Public Methods
Projectile 版本的三向变换同步(Blueprint 名 "Sync Transform Entity To Actor",与 Agent 同名;直贴版本——投射物无自由偏航/相对刚性处理,每 tick 自动调用)。结构与 Loot 版本一致:前置检查(同步模式非全 None、相对变换已捕获、实体/片段有效)→ 默认清 FMoving.bComponentDrivenPosition → UpdateFastForwardState + EffectiveSyncMode → 位置/旋转/缩放三轴按方向执行。与 Agent 的差异:ComponentToEntity 写实体时同样清除线速度并置组件驱动标志(阻止 MoveProcessor 对抗);锁步会话跳过任意轴 ComponentToEntity 写回;FF 期间实体权威。累积后经 SetWorldTransform/SetActorTransform 原子应用。
Projectile version of the three-way transform sync (Blueprint name "Sync Transform Entity To Actor", same as Agent; direct copy variant — projectiles have no free-yaw/relative-rig handling, called automatically every tick). Structurally identical to the Loot version: precondition checks (sync modes not all None, relative transforms captured, entity/fragments valid) → clears FMoving.bComponentDrivenPosition by default → UpdateFastForwardState + EffectiveSyncMode → location/rotation/scale per direction. Agent differences: ComponentToEntity entity writes also clear linear velocity and set the component-driven flag (gates MoveProcessor); lockstep sessions skip any-axis ComponentToEntity write-back; FF is entity-authoritative. Accumulated updates apply atomically via SetWorldTransform/SetActorTransform.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InDeltaTime | float | 增量时间提示(0 = 使用上一 tick 的值);当前实现未使用该参数。Delta time hint (0 = use the value from the last tick); currently unused by the implementation. |
Output
无返回值。副作用:按同步方向写 FLocating/FRotating/FScaling 或组件/Actor 变换;FMoving 速度与组件驱动标志;切换 Owner ReplicateMovement。
No return value. Side effects: writes FLocating/FRotating/FScaling or component/actor transforms per direction; FMoving velocity and the component-driven flag; toggles the Owner's ReplicateMovement.
从实体句柄反查绑定组件:读实体 FProjectileEventRT.BindingComponentPtr。任何环节失败(世界无效、MA 缺失、句柄无效、无 FProjectileEventRT、指针为空)返回 nullptr。
Looks up the bound component from an entity handle: reads FProjectileEventRT.BindingComponentPtr on the entity. Returns nullptr when any step fails (invalid world, missing MA, invalid handle, no FProjectileEventRT, null pointer).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
WorldContext | UObject* | 世界上下文(DefaultToSelf)。World context (DefaultToSelf). |
EntityHandle | FEntityHandle | 要查找的实体句柄。The entity handle to look up. |
Output
返回绑定组件,未找到或无效时 nullptr。
Returns the bound component, or nullptr when not found or invalid.
手动初始化并生成抛射物实体。已初始化时警告并返回 true;锁步会话走服务器驱动路径(有权威调用 RequestLockstepSpawn,客户端返回 false);本地路径:构建模板 → SpawnProjectileFromTemplate。
Manually initializes and spawns the projectile entity. Already-initialized: warns and returns true; lockstep sessions route through the server-driven path (authority calls RequestLockstepSpawn, clients return false); local path: build template → SpawnProjectileFromTemplate.
Input
无参数。
No parameters.
Output
返回是否成功;失败原因见 Warning 日志。
Returns success; failure reasons are in Warning logs.
从 ProjectileConfigAsset 经 UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset 构建模板数据;模板可在 Blueprint 中修改后再生成。资产缺失、子系统获取失败或模板构建失败时返回无效模板(含 Warning 日志)。
Builds template data from ProjectileConfigAsset via UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset; the template can be modified in Blueprint before spawning. Returns an invalid template (with Warning logs) when the asset is missing, the subsystem cannot be fetched, or template creation fails.
Input
无参数。
No parameters.
Output
返回 FEntityTemplateData;失败时 IsValid() 为 false。
Returns FEntityTemplateData; IsValid() false on failure.
按 MovementMode 分派生成抛射物并绑定组件。各模式对应:Static → SpawnProjectile_Static_FromTemplate;Interped → SpawnProjectile_Interped_FromTemplate(带 TargetLocation/TargetEntity);Ballistic → SpawnProjectile_Ballistic_FromTemplate(带 TargetVelocity);Tracking → SpawnProjectile_Tracking_FromTemplate(带 InitialDirection)。未知模式返回无效句柄。生成成功后:写 FProjectileEventRT.BindingComponentPtr = this,EventReceiveActor 缺省填 owner;捕获初始相对变换;广播 OnProjectileInitialized。
Spawns a projectile by dispatching on MovementMode and binds the component. Modes: Static → SpawnProjectile_Static_FromTemplate; Interped → SpawnProjectile_Interped_FromTemplate (with TargetLocation/TargetEntity); Ballistic → SpawnProjectile_Ballistic_FromTemplate (with TargetVelocity); Tracking → SpawnProjectile_Tracking_FromTemplate (with InitialDirection). Unknown modes return an invalid handle. On success: writes FProjectileEventRT.BindingComponentPtr = this, fills EventReceiveActor with the owner when empty; captures initial relative transforms; broadcasts OnProjectileInitialized.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
TemplateData | const FEntityTemplateData& | 实体模板(来自 CreateTemplateFromConfig 或修改后)。Entity template (from CreateTemplateFromConfig or modified). |
Output
返回生成的实体句柄(有效才算成功);失败时无效句柄。副作用:绑定 fragment、事件广播。
Returns the spawned entity handle (valid on success); invalid on failure. Side effects: fragment binding, event broadcast.
惰性访问器:缓存命中直接返回;否则经 GetWorld() 取 UMassBattleProjectileSubsystem 并缓存。
Lazy accessor: returns the cache on hit; otherwise fetches UMassBattleProjectileSubsystem from GetWorld() and caches it.
Input
无参数。
No parameters.
Output
返回子系统指针(世界缺失时可能为 nullptr)。副作用:写缓存。
Returns the subsystem pointer (may be nullptr without a world). Side effect: fills the cache.
用既有实体初始化组件(对象池/重绑路径):已绑定则直接返回。写入 FProjectileEventRT.BindingComponentPtr = this,EventReceiveActor 缺省填 owner;保存并恢复用户同步模式后捕获初始相对变换;清 bPendingRebind;广播 OnProjectileInitialized。
Initializes the component with an existing entity (pooling/rebind path): returns when already bound. Writes FProjectileEventRT.BindingComponentPtr = this, fills EventReceiveActor with the owner when empty; captures initial relative transforms around a save/restore of the user sync modes; clears bPendingRebind; broadcasts OnProjectileInitialized.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InEntityHandle | FEntityHandle | 要绑定的实体。The entity to bind. |
Output
无返回值。副作用:绑定指针写入、相对变换捕获、事件广播。
No return value. Side effects: binding-pointer write, relative-transform capture, event broadcast.
解绑实体:实体仍有效时清 FProjectileEventRT.BindingComponentPtr(仅当指向本组件)与 EventReceiveActor(仅当指向本 owner);清零句柄与 bIsMassInitialized;同步模式重置为 None。
Unbinds the entity: while the entity is valid, clears FProjectileEventRT.BindingComponentPtr (only when it points at this component) and EventReceiveActor (only when it points at this owner); zeroes the handle and bIsMassInitialized; resets sync modes to None.
Input
无参数。
No parameters.
Output
无返回值。副作用:上述解绑与复位。
No return value. Side effects: the unbinding and resets above.
仅服务器入口:构建并广播 ProjectileComponent.Spawn 锁步指令(镜像 AgentComponent)。载荷:IntPayload = [LockstepNetID]、NamePayload = [DataAsset 路径]、FloatPayload = [位置 XYZ, 四元数 XYZW](组件位置即出生点,无需脚部偏移换算)。经 SendLockstepCommandToClients 广播并本地入队。
Server-only entry: builds and broadcasts the ProjectileComponent.Spawn lockstep command (mirrors AgentComponent). Payload: IntPayload = [LockstepNetID], NamePayload = [DataAsset path], FloatPayload = [location XYZ, quaternion XYZW] (the component location is the spawn point — no foot-offset conversion). Broadcasts and enqueues locally via SendLockstepCommandToClients.
Input
无参数。
No parameters.
Output
无返回值。副作用:广播一条锁步生成指令。
No return value. Side effect: broadcasts one lockstep spawn command.
锁步指令执行路径(镜像 AgentComponent::SpawnLockstepAgent_Internal):两端同一 ExecuteTick 调用,实体 UID 本地分配(ExpectedUniqueID 未使用 —— 本地分配即锁步身份)。已初始化时直接返回 true(幂等 —— 快照重建/重传);从指令载荷覆写模板变换(位置精确)后走 SpawnProjectileFromTemplate,成功则从实体同步 OwningProjectileUniqueID。
Lockstep command-execution path (mirrors AgentComponent::SpawnLockstepAgent_Internal): called on both peers at the same ExecuteTick; the entity UID is allocated locally (ExpectedUniqueID unused — local allocation IS the lockstep identity). Already-initialized returns true immediately (idempotent — snapshot rebuild / re-delivery); overrides the template transform from the command payload (position accuracy) then runs SpawnProjectileFromTemplate, syncing OwningProjectileUniqueID from the entity on success.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
ExpectedUniqueID | int32 | 期望 UID(当前未使用)。Expected UID (currently unused). |
SpawnTransform | const FTransform& | 生成变换(来自指令载荷)。Spawn transform (from the command payload). |
Output
返回是否生成成功。副作用:实体生成、UID 缓存写入。
Returns spawn success. Side effects: entity spawn, UID cache write.
快照恢复后的重链实现:无锁步契约(OwningProjectileUniqueID < 0)时直接返回。按生成时捕获的 UID 经 MB->FindEntityByUID 反查重建实体;未找到则置 bPendingRebind = true 每帧重试。找到后:保存同步模式 → DeinitializeFromEntity(无前置检查,链接中调用安全)→ InitializeWithEntity → 恢复同步模式。
Rebind implementation after snapshot restore: returns immediately without a lockstep contract (OwningProjectileUniqueID < 0). Looks up the rebuilt entity by the UID captured at spawn via MB->FindEntityByUID; not found sets bPendingRebind = true for per-frame retry. On success: saves sync modes → DeinitializeFromEntity (no precondition guard — safe while linked) → InitializeWithEntity → restores sync modes.
Input
无参数。
No parameters.
Output
无返回值。副作用:重绑与事件广播。
No return value. Side effects: rebinding and event broadcast.
① 调用基类(锁步 ID 预分配等);② 锁步会话路径:服务器 + Auto 模式且未被门控 1 拦截(owner 未复制时不注册)时向 GameMode 注册(RegisterPendingLockstepProjectileSpawn),tick 边界冲刷;随后返回;③ 非锁步:已初始化或未配置资产则休眠;Auto 模式直接 ManualInitialize(),Manual 模式等待显式调用。
① Calls the base (lockstep ID pre-allocation etc.); ② lockstep-session path: server + Auto mode and not gate-1 blocked (non-replicated owner never registers) registers with the GameMode (RegisterPendingLockstepProjectileSpawn) for the tick-boundary flush, then returns; ③ non-lockstep: dormant when already initialized or without a config asset; Auto mode calls ManualInitialize() directly, Manual mode waits for an explicit call.
Input
无参数。
No parameters.
Output
无返回值。副作用:锁步注册 / 自动生成 / 休眠分流。
No return value. Side effects: lockstep registration / auto spawn / dormant split.
① 基类先注销宿主注册表;② 未初始化则返回;③ 锁步会话(IsLockstepSession()):服务器广播 ProjectileComponent.Despawn 锁步指令(双端同一 ExecuteTick 标 PendingDestroy),本地仅解绑;④ 非锁步:本地标 PendingDestroy 并入销毁队列。
① Base unregisters the host registry first; ② returns when not initialized; ③ lockstep session (IsLockstepSession()): the server broadcasts the ProjectileComponent.Despawn lockstep command (both peers mark PendingDestroy at the same ExecuteTick), local side only unbinds; ④ non-lockstep: marks PendingDestroy locally and enqueues destruction.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
EndPlayReason | EEndPlayReason::Type | 结束播放原因。End-play reason. |
Output
无返回值。副作用:销毁实体(本地)或广播 Despawn 指令(网络)并解绑。
No return value. Side effects: entity destruction (local) or Despawn command broadcast (network) plus unbinding.
成员变量 Members
初始化模式:Auto / Manual(枚举定义于 MassBattleEnums.h;工具提示提及的 "Disabled" 值在枚举中不存在)。
Initialization mode: Auto / Manual (enum in MassBattleEnums.h; the "Disabled" value in the tooltip does not exist in the enum).
抛射物配置数据资产,模板构建的数据源。未设置时组件休眠(等池化系统调用 InitializeWithEntity)。
Projectile configuration data asset, the template data source. Unset keeps the component dormant (waiting for pooling InitializeWithEntity).
抛射物运动模式(Static / Interped / Ballistic / Tracking),生成时决定分派到哪个 SpawnProjectile_*_FromTemplate。注意:数据资产中对应字段默认值为 Ballistic,两者默认值不同。
Projectile movement mode (Static / Interped / Ballistic / Tracking), deciding which SpawnProjectile_*_FromTemplate runs at spawn. Note: the corresponding DataAsset field defaults to Ballistic — the defaults differ.
目标位置(用于 Interped / Ballistic / Tracking 模式)。
Target location (for Interped / Ballistic / Tracking modes).
目标实体(用于 Tracking 模式)。
Target entity (for Tracking mode).
目标速度,用于提前量预测(用于 Ballistic 模式)。
Target velocity for prediction (for Ballistic mode).
初始方向(用于 Tracking 模式)。
Initial direction (for Tracking mode).
发起者实体(抛射物的所有者),生成时传给生成器。
Instigator entity (owner of the projectile), passed to the spawner at spawn.
碰撞忽略的实体集合,生成时传给生成器。
Entities to ignore for collision, passed to the spawner at spawn.
抛射物乘数(见 Fragments/ProjectileHostConfig.h 的 FProjectileMultipliers):Static / Interped / Ballistic / Tracking 四组按模式使用。
Projectile multipliers (see FProjectileMultipliers in Fragments/ProjectileHostConfig.h): four groups — Static / Interped / Ballistic / Tracking — used per mode.
实体绑定完成事件,生成/重绑成功时广播。
Entity-bound event, broadcast on successful spawn/rebind.
实体 UID 在锁步生成时两端本地分配(不复制 —— 锁步保证两端一致);快照重绑时按此值反查实体。
Entity UID allocated locally on both peers at lockstep spawn time (NOT replicated — lockstep keeps both ends equal); snapshot rebind looks the entity up by this value.
惰性缓存的抛射物子系统指针。
Lazily-cached projectile subsystem pointer.
管线角色 Pipeline Role
本地路径:BeginPlay(Auto)→ ManualInitialize → CreateTemplateFromConfig(经 UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset)→ SpawnProjectileFromTemplate 按 MovementMode 分派到 SpawnProjectile_Static/Interped/Ballistic/Tracking_FromTemplate。锁步路径:服务器经 RegisterPendingLockstepProjectileSpawn 注册,GameMode tick 边界冲刷广播 ProjectileComponent.Spawn;双端同一 ExecuteTick 执行 SpawnLockstepProjectileAtTransform。模拟侧:ProjectileMonoProcessor 每帧推进并把 OnProjectileHit/Death 事件推入 UMassBattleSubsystem 事件队列,UMassBattleProjectileSubsystem 的生成路径也直接推 OnProjectileSpawn 事件。快照恢复后经 RebindToEntity(按 OwningProjectileUniqueID 经 FindEntityByUID)重链;销毁时服务器广播 ProjectileComponent.Despawn。
Local path: BeginPlay (Auto) → ManualInitialize → CreateTemplateFromConfig (via UMassBattleProjectileSubsystem::MakeProjectileTemplateFromDataAsset) → SpawnProjectileFromTemplate dispatches by MovementMode to SpawnProjectile_Static/Interped/Ballistic/Tracking_FromTemplate. Lockstep path: the server registers via RegisterPendingLockstepProjectileSpawn; the GameMode flushes at the tick boundary, broadcasting ProjectileComponent.Spawn; both peers execute SpawnLockstepProjectileAtTransform at the same ExecuteTick. Simulation side: ProjectileMonoProcessor advances each frame and pushes OnProjectileHit/Death events into the UMassBattleSubsystem event queues, while the UMassBattleProjectileSubsystem spawn paths push OnProjectileSpawn events directly. After snapshot restore, RebindToEntity re-links (by OwningProjectileUniqueID via FindEntityByUID); on destruction the server broadcasts ProjectileComponent.Despawn.