UMassBattleProjectileSubsystem

空构造函数,无初始化逻辑。

Empty constructor; no initialization logic.

USubsystem 生命周期入口。调用父类实现后预热 MassAPISubsystem / MassBattleSubsystem 缓存。

USubsystem lifecycle entry. Calls the parent implementation, then warms the MassAPISubsystem / MassBattleSubsystem caches.

USubsystem 生命周期出口。调用父类实现后清空三个缓存指针。

USubsystem lifecycle exit. Calls the parent implementation, then nulls the three cache pointers.

每帧 tick 入口(由 UMassBattleSubsystem::Tick 调用)。当前实现仅含 profiling 标记,无实际逻辑——弹丸模拟由 ProjectileMono 处理器驱动。

Per-frame tick entry (called by UMassBattleSubsystem::Tick). The current implementation only contains a profiling scope — projectile simulation is driven by the ProjectileMono processors.

静态访问器:从任意世界上下文对象解析 UWorld 并取其 Projectile 子系统。世界无效时返回 nullptr。

Static accessor: resolves UWorld from any world-context object and returns its Projectile subsystem; nullptr when the world is invalid.

静态访问器的引用版本:失败即 checkf 断言崩溃——用于「子系统必须存在」的不变式场景。

Reference version of the static accessor: fails via checkf assertion — for invariant paths where the subsystem must exist.

两个同构的惰性访问器:命中缓存直接返回;否则从当前世界取对应子系统并写入缓存。

Two isomorphic lazy accessors: return the cache on hit; otherwise fetch the subsystem from the current world and fill the cache.

把弹丸实体的 UniqueID → 句柄映射注册进全局表(UMassBattleSubsystem::RegisterUIDEntity)。UniqueID < 0、句柄无效时静默跳过。由 ProcessHostOpsQueues 弹丸段在批量生成后逐个调用,也是弹丸侧 UID 映射的注册口。

Registers a projectile entity's UniqueID → handle mapping into the global table (UMassBattleSubsystem::RegisterUIDEntity). Silently skips when UniqueID < 0 or the handle is invalid. Called per spawned projectile by the ProcessHostOpsQueues projectile stage; the registration entry point for the projectile side.

Static 模式弹丸模板构建。先调 InitializeCommonProjectileFragments 铺设公共 fragment(失败返回 false),再按模式添加:FLocating(Location = PreLocation = FromPoint)、FRotating(DA 默认)、FScaling(DA 默认 × Static.ScaleMult)、FProjectileMove_Static(DA 默认),最后 ApplyDamageConfiguration 铺设伤害/debuff。

Static-mode projectile template builder. Calls InitializeCommonProjectileFragments first for the common fragments (returns false on failure), then adds the mode-specific ones: FLocating (Location = PreLocation = FromPoint), FRotating (DA default), FScaling (DA default × Static.ScaleMult), FProjectileMove_Static (DA default), and finally ApplyDamageConfiguration for damage/debuff.

四个模式的 BP 生成入口(已弃用——提示改用 MassBattleFuncLib 对应函数)。统一流程:① 安全检查(子系统与 DA 有效,否则 Successful=false 并清空句柄);② 移动模式匹配检查(DA 的 MovementMode 必须与函数对应,不匹配即失败);③ [NET_GUARD] 锁步外守卫——网络模式下 UMassBattleNetworkSubsystem::IsOffLockstep 为真则拦截(Warning 日志,"网络模式下锁步外调用被拦截")并失败(命令缓冲版放行);④ 调对应 CreateProjectileTemplate_Xxx 构建模板(失败即返回);⑤ TryReuseProjectileFromPool 尝试复用池实体,失败则 BuildEntity 立即构建并补设 Activated 旗标(MonoProcessor 模拟循环以 Activated 为门);⑥ 若 FProjectileEvent.bGenerateBirthEvent 为真,把 FAppearData 推入 OnProjectileSpawnQueue;⑦ Successful=true。

Blueprint spawn entries for the four modes (deprecated — use the MassBattleFuncLib counterparts). Common flow: ① safety checks (subsystem and DA valid, else Successful=false and the handle is cleared); ② movement-mode match check (the DA's MovementMode must match the function, mismatch fails); ③ [NET_GUARD] off-lockstep guard — in networked mode, UMassBattleNetworkSubsystem::IsOffLockstep blocks with a Warning ("blocked off-lockstep in networked mode"); ④ builds the template via the matching CreateProjectileTemplate_Xxx (returns on failure); ⑤ TryReuseProjectileFromPool reuses a pooled entity, falling back to immediate BuildEntity plus the Activated flag (the MonoProcessor sim loop is gated on Activated); ⑥ if FProjectileEvent.bGenerateBirthEvent, pushes FAppearData into OnProjectileSpawnQueue; ⑦ Successful=true.

四个模式的延迟生成入口(命令缓冲版,锁步指令路径)。流程与 BP 版相同(安全/模式匹配/锁步外守卫),差别在第 ⑤ 步:不走池,直接 BuildEntityDefer(CommandBuffer, TemplateData) 延迟构建;出生事件与 Successful 处理相同。

Deferred spawn entries for the four modes (command-buffer version, the lockstep command path). The flow matches the BP versions (safety / mode match / off-lockstep guard) except step ⑤: no pool reuse — it builds deferred via BuildEntityDefer(CommandBuffer, TemplateData); the birth event and Successful handling are identical.

Interped 模式弹丸模板构建。公共片段后:目标位置解析(ToTarget 有效时以其 FLocating 位置覆盖 ToPoint);散布(TargetLocationSpreadXY/Z > 0 时用施害者 RandomStream 确定性圆内随机点 + Z 随机,写入 TargetOffset 并叠加到 ToPoint);FProjectileMoving_Interped(BirthTime = 模拟时间、FromPoint、ToPoint、Target、TargetOffset);FRotating 朝向 = (FinalToPoint - FromPoint) 方向;FScaling × Interped.ScaleMult;FProjectileMove_Interped(Speed × SpeedMult);偏移乘数 = 外部乘数 × 距离重映射(XOffsetRangeMap 分段映射)× 随机乘数(施害者流);最后铺设伤害/debuff。

Interped-mode projectile template builder. After the common fragments: target resolution (a valid ToTarget's FLocating overrides ToPoint); spread (when TargetLocationSpreadXY/Z > 0, a deterministic in-circle random point plus Z random from the instigator's RandomStream, written into TargetOffset and added to ToPoint); FProjectileMoving_Interped (BirthTime = simulation time, FromPoint, ToPoint, Target, TargetOffset); FRotating facing the (FinalToPoint - FromPoint) direction; FScaling × Interped.ScaleMult; FProjectileMove_Interped (Speed × SpeedMult); offset multipliers = external mult × distance remap (XOffsetRangeMap piecewise map) × random mult (instigator stream); then damage/debuff.

Ballistic 模式弹丸模板构建。与其它模式不同,不经过 InitializeCommonProjectileFragments,而是完整内联公共铺设(EntityFlag/SubType/Event(+RT)/Visualizing/Spawn 级联注册/Determinism/Params/继承伤害与 debuff(专用 thread_local 存储)/ParamsRT),因为轨迹必须先于模板算出、失败须提前返回。流程:目标位置解析与散布 → 按 SolveMode(FromSpeed / FromPitch)调 SolveProjectileVelocityFromSpeedWithPrediction / FromPitchWithPrediction 求解初速度(含 Gravity/Speed/Pitch 倍率)——求解失败直接返回 false → 铺设 FLocating、FRotating(朝向初速度方向)、FScaling × Ballistic.ScaleMult、FProjectileMove_Ballistic(Speed/MaxSpeed × SpeedMult、Gravity × GravityMult、Pitch × PitchMult)、FProjectileMoving_Ballistic(BirthTime/FromPoint/ToPoint/InitialVelocity)→ ApplyDamageConfiguration → 标签。

Ballistic-mode projectile template builder. Unlike the other modes, it does not go through InitializeCommonProjectileFragments — the common layout is fully inlined (EntityFlag/SubType/Event(+RT)/Visualizing/cascade registration/Determinism/Params/inherited damage & debuff (dedicated thread_local storage)/ParamsRT) because the trajectory must be solved before the template exists and failures must return early. Flow: target resolution and spread → per SolveMode (FromSpeed / FromPitch), solve the initial velocity via SolveProjectileVelocityFromSpeedWithPrediction / FromPitchWithPrediction (with Gravity/Speed/Pitch multipliers) — a failed solve returns false → lays out FLocating, FRotating (facing the initial velocity), FScaling × Ballistic.ScaleMult, FProjectileMove_Ballistic (Speed/MaxSpeed × SpeedMult, Gravity × GravityMult, Pitch × PitchMult), FProjectileMoving_Ballistic (BirthTime/FromPoint/ToPoint/InitialVelocity) → ApplyDamageConfiguration → tags.

Tracking 模式弹丸模板构建。公共片段后:目标位置与目标速度解析(FLocating + FMoving.CurrentVelocity);FLocating;FRotating 朝向 = 传入 Direction;FScaling × Tracking.ScaleMult;FProjectileMove_Tracking(Speed/MaxSpeed × SpeedMult、Acceleration/LateralAcceleration × 对应倍率);FProjectileMoving_Tracking(FromPoint、ToPoint、Target、FlightDirection、CurrentSpeed = 基准速度 × SpeedMult、bHasValidTarget);散布写入 TargetOffset 并叠加 ToPoint;最后铺设伤害/debuff。

Tracking-mode projectile template builder. After the common fragments: target location and target velocity resolution (FLocating + FMoving.CurrentVelocity); FLocating; FRotating facing the passed Direction; FScaling × Tracking.ScaleMult; FProjectileMove_Tracking (Speed/MaxSpeed × SpeedMult, Acceleration/LateralAcceleration × their multipliers); FProjectileMoving_Tracking (FromPoint, ToPoint, Target, FlightDirection, CurrentSpeed = base speed × SpeedMult, bHasValidTarget); spread written into TargetOffset and added to ToPoint; then damage/debuff.

按数据资产构建 archetype-only 弹丸模板(DA 静态状态,无逐生成数据):公共 fragment(EntityFlag/SubType/Event(+RT)/Visualizing/Spawn 级联资产注册/Determinism(未播种,序列 ID 在生成时处理)/Params/ParamsRT(仅预印 PoolDataAsset,使 FromTemplate 路径死亡时能按 DA 回池)/Locating/FRotating 占位)+ 按 MovementMode 的移动 fragment + 按 DamageMode 的伤害/debuff fragment + 标签(FProjectileTag + FMainType(Projectile) + SubType tag)。网络模式下额外:FNetworkTag + FNetworking.Key = DA 路径名(捕获 TemplateKey 与恢复 LoadObject 兜底的单一来源,镜像 agent 版),并幂等注册 RegisterNetworkTemplateData。供 ProjectileArchetypeTemplateCache(Host 子系统 BatchCreate)、ProjectileComponent、FuncLib 与网络侧预注册使用。

Builds an archetype-only projectile template from the data asset (DA-static state, no per-spawn data): common fragments (EntityFlag/SubType/Event(+RT)/Visualizing/cascade asset registration/Determinism (unseeded — the sequence ID is handled at spawn)/Params/ParamsRT (only PoolDataAsset pre-stamped so FromTemplate spawns can route back to the per-DA pool on death)/Locating/FRotating placeholders) + movement fragments per MovementMode + damage/debuff fragments per DamageMode + tags (FProjectileTag + FMainType(Projectile) + SubType tag). In networked mode additionally: FNetworkTag + FNetworking.Key = the DA pathname (single source for capture TemplateKey and restore LoadObject fallback, mirroring the agent version), idempotently registered via RegisterNetworkTemplateData. Used by ProjectileArchetypeTemplateCache (Host subsystem BatchCreate), ProjectileComponent, FuncLib and network-side pre-registration.

从 UMassBattleHostSubsystem::ProjectilePoolsByDataAsset 弹一个休眠实体并为本 BP 路径生成复用。把 InstanceTemplate 携带的每个 per-instance fragment 拷贝到池实体上(archetype 匹配——新鲜 BP 构建与处理器池填充同源于同一 DA 派生模板);随后重置逐复用运行时状态(插值初始化 bInterpInitialized=false + CachedVelocity 清零、FProjectileEventRT 清空、bBornFired=false——保证 OnBirth 事件重放——PoolDataAsset 重新盖章);最后清 PendingDestroy 设 Activated。池空时返回无效句柄——调用方回落 BuildEntity。

Pops a dormant entity from UMassBattleHostSubsystem::ProjectilePoolsByDataAsset and reuses it for this BP-path spawn. Copies every per-instance fragment carried by InstanceTemplate onto the pooled entity (archetype matches because both fresh BP builds and processor-pool fills originate from the same DA-derived template); then resets per-reuse runtime state (interp init bInterpInitialized=false + CachedVelocity zeroed, FProjectileEventRT cleared, bBornFired=false so OnBirth re-fires, PoolDataAsset re-stamped); finally clears PendingDestroy and sets Activated. Returns an invalid handle when the pool is empty — the caller falls back to BuildEntity.

四个模式的 锁步指令路径生成入口(由 MassBattleProjectileComponent 的 Spawn 指令执行端在两端同一 ExecuteTick 调用;组件直调路径由组件自身锁步守卫拦截)。开头即 [RULE7] 守卫:模板无效或锁步外(IsOffLockstep)→ Error 日志("请改接到锁步 CommandTag")并返回(Successful 保持 false)。随后拷贝模板为实例:重新播种 UID(AllocNextUID;Ballistic 版提前分配一次——既作散布种子也作实体身份,不浪费假 UID)、写 ParamsRT(IgnoreEntities/Instigator)、可选继承事件接收者、写 Locating;按模式写朝向/移动/散布(FromTemplate 的散布优先用弹丸自身播种流,退化到施害者流);乘数作用到 Scaling 与三种 Damage fragment;恢复 ParamsRT 中的 PoolDataAsset 走 TryReuseProjectileFromPool,失败 BuildEntity + 设 Activated;出生事件投递;最后注册 UID 映射(MB->RegisterUIDEntity)。Successful=true。

The four lockstep command path spawn entries (called by the MassBattleProjectileComponent Spawn command execution on both peers at the same ExecuteTick; component direct-call paths are gated by the component's own lockstep guards). Opens with the [RULE7] guard: an invalid template or off-lockstep (IsOffLockstep) logs an Error ("wire it to a lockstep CommandTag instead") and returns with Successful false. Then the template is copied into an instance: UID re-seeded (AllocNextUID; the Ballistic version allocates once early — used as both the spread seed and entity identity, no phantom UID wasted), ParamsRT written (IgnoreEntities/Instigator), optional event-receiver inheritance, Locating written; per-mode orientation/movement/spread (the FromTemplate spread prefers the projectile's own seeded stream, falling back to the instigator's); multipliers applied to Scaling and all three Damage fragments; PoolDataAsset recovered from ParamsRT for TryReuseProjectileFromPool, falling back to BuildEntity + Activated; birth event enqueued; finally the UID mapping is registered (MB->RegisterUIDEntity). Successful=true.

给定俯仰角求解弹丸初速度(重力符号内部取反)。相对俯仰 = 指向目标的视线俯仰 + 传入俯仰角,钳制 ±89.9°;用弹道方程分母 distance2D·sin(2a) - 2·ΔZ·cos²(a) 求 v₀²;分母近零(浮点安全)或 v₀² < 0(无实数解)时失败。成功时 LaunchVelocity = 视线方向旋转(俯仰替换为 FinalPitch)矢量 × 初速。

Solves the launch velocity for a given pitch angle (gravity sign inverted internally). Relative pitch = the look-at pitch toward the target plus the passed pitch, clamped to ±89.9°; v₀² from the trajectory denominator distance2D·sin(2a) - 2·ΔZ·cos²(a); fails when the denominator is near zero (float safety) or v₀² < 0 (no real solution). On success LaunchVelocity = the look-at rotation (pitch replaced by FinalPitch) vector × initial speed.

给定初速求解发射俯仰。判别式 v⁴ - g·(g·x² + 2·y·v²) < 0 无实数解;水平距离近零时走纯垂直分支(目标在上方须 v² ≥ 2gh;下方直接垂直向下;重合无解)。双解(高抛/低抛)按 bFavorHighArc 选择——高抛选水平速度分量小的解,低抛选大的;最终 LaunchVelocity = 朝向目标水平方向旋转(应用选定俯仰)× 初速。

Solves the launch pitch for a given speed. A negative discriminant v⁴ - g·(g·x² + 2·y·v²) means no real solution; near-zero horizontal distance uses the pure-vertical branch (target above requires v² ≥ 2gh; below launches straight down; coincident points are unsolvable). The two solutions (high/low arc) are chosen by bFavorHighArc — high arc picks the smaller horizontal speed component, low arc the larger; final LaunchVelocity = the horizontal look-at rotation (with the selected pitch applied) × speed.

Pitch 版的迭代预测求解:每轮对当前预测位置解一次初速,用飞行时间 t = distance2D / (cos(a)·v₀) 更新预测位置 ToPoint + TargetVelocity·t;迭代期间任一轮无解即失败。末轮 LaunchVelocity 保留。

Iterative-prediction variant of the pitch solver: each iteration solves the initial velocity against the current predicted position, then updates the prediction to ToPoint + TargetVelocity·t using the flight time t = distance2D / (cos(a)·v₀); any unsolvable iteration fails. LaunchVelocity keeps the last iteration's value.

Speed 版的迭代预测求解:每轮对当前预测位置求判别式与双解(逻辑同无预测版),飞行时间 t = distance2D / (cos(pitch)·v),更新预测位置 ToPoint + TargetVelocity·t;仅最后一轮把 LaunchVelocity 写入输出。垂直分支处理同无预测版。

Iterative-prediction variant of the speed solver: each iteration computes the discriminant and the two solutions against the current predicted position (logic as the non-predicted version), with flight time t = distance2D / (cos(pitch)·v), updating the prediction to ToPoint + TargetVelocity·t; only the last iteration writes LaunchVelocity. Vertical-branch handling matches the non-predicted version.

Interped 模式在指定时刻的位置计算。目标有效时 ToPoint(引用)被覆写为 目标位置 + TargetOffset;时长 = 距离 / 速度,Alpha 钳制 [0,1](时长为 0 且已过初始时刻 → Alpha=1);基础位置 = FromPoint→ToPoint 线性插值;再叠加三轴偏移曲线(XOffset/YOffset/ZOffset 运行时曲线在 Alpha 处取值 × 各自乘数)——X 沿水平右向量、Y 沿水平前向量、Z 垂直。到达判定:当前位置与 ToPoint 距离平方 ≤ KINDA_SMALL_NUMBER。

Interped-mode position at a given time. With a valid target, ToPoint (by reference) is overwritten with target location + TargetOffset; duration = distance / speed, Alpha clamped to [0,1] (zero duration past the initial time → Alpha=1); base position = linear lerp FromPoint→ToPoint; then three offset curves are layered (XOffset/YOffset/ZOffset runtime curves evaluated at Alpha × their multipliers) — X along the horizontal right vector, Y along the horizontal forward vector, Z vertical. Arrival: squared distance from the current position to ToPoint ≤ KINDA_SMALL_NUMBER.

Ballistic 模式在指定时刻的位置计算。位移 = 初速度 × Δt,再叠加 0.5·g·Δt²;当前位置 = FromPoint + 位移。到达判定:当前位置相对发射点在目标方向上的投影比例 ≥ 1(越过目标点)。

Ballistic-mode position at a given time. Displacement = initial velocity × Δt plus 0.5·g·Δt²; current position = FromPoint + displacement. Arrival: the projection scalar of the current position onto the target direction ≥ 1 (past the target point).

Tracking 模式单步位置计算(7 步):① 更新目标状态——目标有效时读 FLocating(+ TargetOffset)与 FMoving 速度(仅 bPredictTargetMovement),并覆写 ToPoint 引用;② 判定跟踪/直飞——无有效目标则保持当前方向直飞(不转向不跟踪);③ 瞄准点——启用预测且目标速度非零时按 距离/当前速度 × PredictionMultiplier 预估拦截时间并前移瞄准点;④ 物理转向约束——ω = 侧向加速度/速度(度/秒),每帧最大转角 = ω·Δt,超出则按比例对当前/期望方向四元数 Slerp(更快 → 转弯半径更大,符合导弹物理);侧向加速度为 0 时瞬时转向;⑤ 速度更新——有加速度则逼近 MaxSpeed,否则恒为 MaxSpeed;⑥ 新位置 = 当前位置 + 新方向 × 新速度 × Δt;⑦ 到达判定——与瞄准点距离 ≤ ArrivalThreshold。起始即在 ArrivalThreshold 内时立即到达并返回。

Tracking-mode single-step position update (7 steps): ① target state — with a valid target, read FLocating (+ TargetOffset) and FMoving velocity (only when bPredictTargetMovement), overwriting the ToPoint reference; ② track vs. fly-straight — no valid target keeps the current course (no turning, no tracking); ③ aim point — with prediction enabled and non-zero target velocity, estimate the intercept time via distance / current speed × PredictionMultiplier and lead the aim point; ④ physics-based turn constraint — ω = lateral acceleration / speed (deg/s), max turn per frame = ω·Δt; exceeding it Slerps between current and desired quaternions by the ratio (faster → wider turn radius, matching missile physics); zero lateral acceleration turns instantly; ⑤ speed update — with acceleration, approach MaxSpeed; otherwise constant MaxSpeed; ⑥ new position = current + new direction × new speed × Δt; ⑦ arrival — distance to the aim point ≤ ArrivalThreshold. Starting within ArrivalThreshold arrives immediately and returns.

四种模式模板构建共享的公共 fragment 铺设(除 Ballistic 内联版外)。顺序:FEntityFlagFragment; FSubType = DA; FProjectileEvent(DA 默认,可选继承事件接收者——agent 经 FAgentEvent、弹丸经 FProjectileEvent)+ FProjectileEventRT; FProjectileVisualizing; FProjectileSpawn = DA 默认并对 OnBirth/OnHit/OnRemoval 三级联配置逐个预热资产注册表(RegisterProjectileConfigAssets 等——使级联触发时不再命中 LoadSynchronous); FDeterminism(PreAssignedUniqueID ≥ 0 用其播种,否则 AllocNextUID;用 UID seed 一次,永不 reseed); FProjectileParams(DA 默认,可选继承追踪查询——agent 经 FTrace、弹丸经 FProjectileParams);继承伤害/debuff(agent 直取 FDamage/FDebuff;弹丸按 Point/Radial/Beam 形态转换到 thread_local FDamage/FDebuff 暂存后返回指针——须跨函数作用域存活); FProjectileParamsRT(DA 默认 + IgnoreEntities + Instigator + PoolDataAsset 盖章(死亡后回 ProjectilePoolsByDataAsset 的依据)+ bBornFired=false);标签 FProjectileTag + FMainType(Projectile) + SubType 标签。

Shared common-fragment layout for the four mode template builders (except the Ballistic inlined version). Order: FEntityFlagFragment; FSubType = DA; FProjectileEvent (DA default, optional inherited event receiver — agent via FAgentEvent, projectile via FProjectileEvent) + FProjectileEventRT; FProjectileVisualizing; FProjectileSpawn = DA default with every cascade config in OnBirth/OnHit/OnRemoval pre-warmed into the asset registry (RegisterProjectileConfigAssets etc. — so cascades never hit LoadSynchronous at fire time); FDeterminism (seeded from PreAssignedUniqueID when ≥ 0, else AllocNextUID; seeded once from the UID, never reseeded); FProjectileParams (DA default, optional inherited trace query — agent via FTrace, projectile via FProjectileParams); inherited damage/debuff (agents via direct FDamage/FDebuff pointers; projectiles are converted from the Point/Radial/Beam shapes into thread_local FDamage/FDebuff storage whose pointers must outlive the call); FProjectileParamsRT (DA default + IgnoreEntities + Instigator + the PoolDataAsset stamp (the death-time route back into ProjectilePoolsByDataAsset) + bBornFired=false); tags FProjectileTag + FMainType(Projectile) + SubType tag.

按 DamageMode(Point / Radial / Beam)铺设伤害与 debuff fragment:先拷贝 DA 默认(Damage_X / Debuff_X),再叠加继承(有 InheritedDamage/InheritedDebuff 时全部字段覆写;Radial/Beam 无继承时 Query 回退 ProjectileParams.Query),最后 Damage *= DmgMultiplier。

Lays out the damage and debuff fragments per DamageMode (Point / Radial / Beam): copies the DA defaults (Damage_X / Debuff_X), overlays inheritance (all fields overwritten when InheritedDamage/InheritedDebuff present; Radial/Beam fall back to ProjectileParams.Query without inheritance), and finally applies Damage *= DmgMultiplier.