UMassBattleAgentMoveProcessorFP
Source/MassBattle/Public/Processors/MassBattleAgentMoveProcessorFP.h
概述 Overview
Agent 移动与物理的定点数实现(与 UMassBattleAgentMoveProcessor 浮点实现互斥,由 UMassBattleSubsystem::bUseFixPointMath 门控:bUseFixPointMath = true 时本处理器运行,false 时浮点版本运行)。与浮点版本逐段镜像:同样的 11 个 Section、同样的 UniqueID 子帧分区与 Launch 处理,区别是核心标量/向量全部使用 FFix64 / FFixVector2 / FFixVector3——ORCA 约束线与线性规划(LP1/LP2/LP3)在定点域求解,保证跨架构 bit-exact(跨平台锁步确定性)。辅助结构体为 FP 变体(FEllipseParamsFP / FForecastDriveSpeedsFP / FSceneObstRVODataFP / FOrcaLineFP / FWallConstraintFP / FTrafficEncounterFP / FAgentMoveScratchContextFP / FPendingFlowFieldLoadFP),另含定点旋转辅助 Rotate2DFix。导航辅助(ProjectPointDownToNavmesh / QueryFlowFieldNav / TryFlyingFallbackOutsideField / ApplyFlowFieldReactionTime)签名与浮点版相同。
Agent movement & physics fixed-point implementation (mutually exclusive with the float UMassBattleAgentMoveProcessor, gated by UMassBattleSubsystem::bUseFixPointMath: this processor runs when true, the float one when false). Section-by-section mirror of the float version: the same 11 sections, the same UniqueID sub-frame partition and launch processing, except core scalars/vectors use FFix64 / FFixVector2 / FFixVector3 — ORCA constraint lines and the linear programs (LP1/LP2/LP3) solve in fixed point for cross-architecture bit-exactness (cross-platform lockstep determinism). Helper structs are FP variants (FEllipseParamsFP / FForecastDriveSpeedsFP / FSceneObstRVODataFP / FOrcaLineFP / FWallConstraintFP / FTrafficEncounterFP / FAgentMoveScratchContextFP / FPendingFlowFieldLoadFP), plus the fixed-point rotation helper Rotate2DFix. The navigation helpers (ProjectPointDownToNavmesh / QueryFlowFieldNav / TryFlyingFallbackOutsideField / ApplyFlowFieldReactionTime) keep the same float signatures as the float version.
继承 Inheritance
公开方法 Public Methods
构造函数。设置 bAutoRegisterWithProcessingPhases = false(手动派发)、bRequiresGameThreadExecution = true、ExecutionFlags = Standalone | Server | Client。
Constructor. Sets bAutoRegisterWithProcessingPhases = false (manually dispatched), bRequiresGameThreadExecution = true, and ExecutionFlags = Standalone | Server | Client.
Input
无参数。
No parameters.
Output
无返回值。副作用:注册为手动派发、游戏线程专用的处理器。
No return value. Side effect: registers as a manually-dispatched, game-thread-only processor.
初始化实体查询:组合与浮点版本完全一致——All<FAgentTag> + All<FScaling, FCollider, FTrace, FDefence, FPatrol, FChase, FReinforce, FMove, FReturn, FAttack, FAttacking, FDeath, FDying, FAgentEvent, FAgentDebug, FAgentController, FAvoidance, FBehaving>(MARO) + All<FLocating, FRotating, FDebuffing, FNavigation, FNavigating, FTracing, FAvoiding, FMoving, FReturning, FStatistics, FDeterminism, FEntityFlagFragment, FAnimating>(MARW) + All<FTrafficShared, FPhysicsShared, FAnimShared>(MARO)。
Initializes the entity query: identical composition to the float version — All<FAgentTag> + All<FScaling, FCollider, FTrace, FDefence, FPatrol, FChase, FReinforce, FMove, FReturn, FAttack, FAttacking, FDeath, FDying, FAgentEvent, FAgentDebug, FAgentController, FAvoidance, FBehaving>(MARO) + All<FLocating, FRotating, FDebuffing, FNavigation, FNavigating, FTracing, FAvoiding, FMoving, FReturning, FStatistics, FDeterminism, FEntityFlagFragment, FAnimating>(MARW) + All<FTrafficShared, FPhysicsShared, FAnimShared>(MARO).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
EntityManager | const TSharedRef<FMassEntityManager> | Mass 实体管理器,查询初始化目标。Mass entity manager; query initialization target. |
Output
无返回值。副作用:EntityQuery 注册进处理器。
No return value. Side effect: EntityQuery registered with the processor.
每 tick 执行入口。bUseFixPointMath 为 false 时直接返回(走浮点处理器)。流程与浮点版一致:排空 PendingFlowFieldLoads(FP 变体)→ 串行 Launch 分配(LaunchGatherer 按力大小升序确定性累加)→ 逐实体 11 个 Section(UniqueID 子帧分区):距离/接受半径 → 寻路(流场/A*/直线+路径修补)→ MoveState → 期望速度(行为倍率 × 减速 × 距离映射)→ 期望速度向量 → 速度注入(Launch)→ RVO2 避让(ComputeRVO2AvoidingVelocityFP / ComputeForceFieldAvoidingVelocityFP,ORCA 线性规划 LinearProgram1FP/2FP/3FP 全部定点域求解,FFix64 时间步)→ PBD(墙约束 FWallConstraintFP)→ 压力场 → Yaw(Creature/Aircraft/Vehicle,载具转向角与加减速,Rotate2DFix)→ Tilt → Z 轴积分。
Per-tick entry. Returns immediately when bUseFixPointMath is false (the float processor runs instead). Flow mirrors the float version: drain PendingFlowFieldLoads (FP variant) → serial launch distribution (LaunchGatherer, deterministic ascending-force accumulation) → per-entity 11 sections (UniqueID sub-frame partition): distance/acceptance radius → pathfinding (flow field / A* / straight line + path patching) → MoveState → desired speed (behavior multiplier × slow × distance map) → desired velocity → velocity injection (Launch) → RVO2 avoidance (ComputeRVO2AvoidingVelocityFP / ComputeForceFieldAvoidingVelocityFP, ORCA linear programs LinearProgram1FP/2FP/3FP all in fixed point with an FFix64 time step) → PBD (wall constraints FWallConstraintFP) → pressure field → Yaw (Creature/Aircraft/Vehicle; vehicle steering angle and accel/decel; Rotate2DFix) → Tilt → Z-axis integration.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
EntityManager | FMassEntityManager& | 实体管理器。Entity manager. |
Context | FMassExecutionContext& | 执行上下文,提供 fragment 视图与实体遍历。Execution context providing fragment views and entity iteration. |
Output
无返回值。副作用:与浮点版相同——写实体变换/移动/避让 fragment,消费 LaunchGatherer,向事件队列写入。
No return value. Side effects: same as the float version — writes transform/move/avoidance fragments, consumes LaunchGatherer, writes to event queues.
2D 向量按角度(度,FFix64)旋转的定点实现——FP 版本独有,浮点版本无对应函数。
Fixed-point 2D vector rotation by an angle in degrees (FFix64) — FP-only helper; the float version has no counterpart.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
V / Degrees | const FFixVector2 / FFix64 | 待旋转向量与旋转角度(度)。Vector to rotate and the rotation angle in degrees. |
Output
返回旋转后的定点向量。
Returns the rotated fixed-point vector.
成员变量 Members
椭圆参数的定点变体:SemiMajor / SemiMinor(FFix64)、MajorDir(FFixVector2)。
Fixed-point ellipse-params variant: SemiMajor / SemiMinor (FFix64), MajorDir (FFixVector2).
正反预测速度的定点变体(FFix64 Forward / Reverse)。
Fixed-point forecast drive speeds (FFix64 Forward / Reverse).
场景障碍 RVO 数据的定点变体(FFixVector3 最近点/法线,FFix64 距离),由 FHitResult 构造。
Fixed-point scene-obstacle RVO data (FFixVector3 closest point/normal, FFix64 distances), constructed from an FHitResult.
ORCA 约束线的定点变体(FFixVector2 point / direction)——FFix 字段保证跨架构 bit-exact ORCA。
Fixed-point ORCA constraint line (FFixVector2 point / direction) — FFix fields guarantee cross-architecture bit-exact ORCA.
统一墙约束的定点变体(FFixVector2 最近点/法线,FFix64 DistanceSq,bool bIsTouching 默认 false)。仅平面约束语义:段/盒/场景三类障碍在此统一为最近点 + agent 相对法线,求解器对三者一视同仁。
Fixed-point unified wall constraint (FFixVector2 closest point/normal, FFix64 DistanceSq, bool bIsTouching defaulting to false). Plane-constraint only: the segment / box / scene obstacle kinds all resolve to closest point + agent-relative normal here, so the solver treats them identically.
L1 遭遇分类缓存,浮点 FTrafficEncounter 的 FFix 镜像。每个采集到的 AgentRVONeighbors 槽位一条,由 ClassifyTrafficEncountersFP 在预解算偏置前每 Agent 填充一次;数值表达式与 FP 规则原内联版本完全一致,缓存路径 bit-exact。字段:RelPosLenSq(中心间距平方)、HeadingDot / ApproachDot(归一化点积,2.0 哨兵 = 无效)、ForwardDot / CrossHeadOn / CrossSide(前向/对头/侧让叉积)、YieldFx(L2 责任值 [0,1],机动幅度与 ORCA 责任比例共用)、EffRank(邻居交通档位镜像,整数)、bWillReachSelf / bAttackerFiltered。
L1 encounter-classification cache, the FFix mirror of the float FTrafficEncounter. One entry per gathered AgentRVONeighbors slot, filled once per agent by ClassifyTrafficEncountersFP right before the pre-solve biases; the value expressions match the FP rules' original inline versions exactly, so the cached path is bit-identical. Fields: RelPosLenSq (squared center distance), HeadingDot / ApproachDot (normalized dots; 2.0 sentinel = invalid), ForwardDot / CrossHeadOn / CrossSide (forward/head-on/side cross products), YieldFx (L2 responsibility share [0,1], consumed by both the maneuver magnitude weighting and the ORCA responsibility ratio), EffRank (cached mirror of the neighbor's traffic rank, plain int), bWillReachSelf / bAttackerFiltered.
线程本地临时上下文的定点变体:结构与 FAgentMoveScratchContext 对应(ORCA 线为 FOrcaLineFP,场景障碍为 FSceneObstRVODataFP,墙约束为 FWallConstraintFP);RVO 邻居仍用浮点 FCapsuleRVOData(数据源),PBD 与事件数组同浮点版。Reset() 语义相同。在此之上还带一组 FP 版交通规则 scratch 状态:TrafficEncounters(L1 遭遇缓存,见 FTrafficEncounterFP)与逐 Agent 路径坐标系(TrafficPathDirFx / TrafficPathRightFx / TrafficSelfLateralFromPathFx / TrafficGoalForwardAlongPathFx / TrafficSelfEffRank / bTrafficPathValid,由 ClassifyTrafficEncountersFP 在预解算偏置前填充);bSolverRangeCapped / SolverAgentDetectDist(制动距离封顶后的求解器触达,ORCA 循环据此跳过远距邻居);bSideStepObligationThisFrame(本帧侧让义务,求解后导出至 Moving 缓存)、bFlankActiveThisFrame、bSelfFarReturning(远归位者自身状态);bAnyForceHybridFFObst(任一采集障碍带 bForceHybridFF 时置位,使 Hybrid 求解器本帧保持 ForceField)。以上均在 Reset() 中逐帧清零,仅 scratch、不序列化。
Fixed-point thread-local scratch variant: structure mirrors FAgentMoveScratchContext (ORCA lines as FOrcaLineFP, scene obstacles as FSceneObstRVODataFP, wall constraints as FWallConstraintFP); RVO neighbors stay float FCapsuleRVOData (the data source), PBD and event arrays match the float version. Same Reset() semantics. On top of that it carries a set of FP-only traffic-rule scratch states: TrafficEncounters (the L1 encounter cache, see FTrafficEncounterFP) plus the per-agent path frame (TrafficPathDirFx / TrafficPathRightFx / TrafficSelfLateralFromPathFx / TrafficGoalForwardAlongPathFx / TrafficSelfEffRank / bTrafficPathValid, filled by ClassifyTrafficEncountersFP right before the pre-solve biases); bSolverRangeCapped / SolverAgentDetectDist (braking-range-limited solver reach; the ORCA loop skips gathered neighbors beyond it); bSideStepObligationThisFrame (side-step obligation this frame, exported post-solve to the Moving cache), bFlankActiveThisFrame, bSelfFarReturning (far-returner self state); bAnyForceHybridFFObst (set when any gathered obstacle carries bForceHybridFF, keeping the Hybrid solver on ForceField this frame). All are cleared per frame in Reset(); scratch-only, never serialized.
异步流场加载请求的命名变体(字段与浮点版相同,独立类型)。
Named variant of the async flow-field load request (same fields as the float version, distinct type).
主查询与 MPSC 流场加载队列(FP 变体)。
Main query and the MPSC flow-field load queue (FP variant).
管线角色 Pipeline Role
注册于 UMassBattleSubsystem 的 SimStages[4],与 UMassBattleAgentMoveProcessor 并列注册、互斥运行(bUseFixPointMath 决定哪个生效)。跨平台锁步场景(bDeterministic + bUseFixPointMath)下是实际的移动求解器——定点 ORCA/PBD 保证双端 bit-exact;同平台确定性重放(bDeterministic 单开)可走浮点版。其余管线关系(消费 LaunchGatherer / 网格快照,产物供 Render/Host)与浮点版一致。
Registered in UMassBattleSubsystem's SimStages[4], registered alongside UMassBattleAgentMoveProcessor with mutual exclusion (bUseFixPointMath decides which one runs). In cross-platform lockstep scenarios (bDeterministic + bUseFixPointMath) it is the actual movement solver — fixed-point ORCA/PBD keep both peers bit-exact; same-platform deterministic replay (bDeterministic alone) may use the float version. The remaining pipeline relationships (consumes LaunchGatherer / grid snapshot; outputs feed Render/Host) match the float version.