FFCPathingComponent.h

启用组件 Tick,但 bStartWithTickEnabled = false——仅在开始移动后(StartFlowFieldFollowing / StartPathFollowing 成功)才启用,静止时零开销。

Enables the component tick but with bStartWithTickEnabled = false — ticking is enabled only after movement starts (a successful StartFlowFieldFollowing / StartPathFollowing), so idle components cost nothing.

每帧驱动:① Idle 直接返回;② 超时检查——剩余时间归零则先拷贝 OnFailed 委托、StopMovement(清空绑定)、再广播失败;③ 到达检查——HasReachedGoal() 为真则拷贝 OnSuccess、停止、广播成功;④ 按状态分发到 TickFlowFieldFollowing / TickPathFollowing;⑤ 有方向时 ApplyMovement;⑥ 开启调试时 DrawDebug()。注意广播前先拷贝委托并停止——StopMovement 会清空委托绑定。

Per-frame driver: ① returns immediately when Idle; ② timeout check — when the remaining time hits zero, copies the OnFailed delegate, calls StopMovement (clearing bindings), then broadcasts failure; ③ goal check — when HasReachedGoal() is true, copies OnSuccess, stops, and broadcasts success; ④ dispatches by state to TickFlowFieldFollowing / TickPathFollowing; ⑤ applies movement when a direction exists; ⑥ calls DrawDebug() when debug is enabled. Note the delegate is copied before broadcasting and movement is stopped first — StopMovement clears delegate bindings.

设置用于导航的流场弱引用,覆盖之前分配的流场。

Sets the flow field weak reference to use for navigation, overriding any previously assigned field.

返回当前流场指针(弱引用解析,可能为 nullptr)。

Returns the current flow field pointer (resolved from the weak reference; may be nullptr).

开始流场跟随模式。流程:① 流场或 Owner 无效 → 广播 OnFailed;② QueryNavigationAdvanced(OwnerLocation, SearchRadius) 查询结果无效 → 广播失败;③ 已在目标(bIsAtGoal 或二维距离 ≤ AcceptanceRadius)→ 广播 OnSuccess;④ 否则进入 FlowField 状态、记录目标与初始方向、按 Timeout > 0 设置超时、启用 Tick。

Starts flow field following mode. Flow: ① invalid flow field or owner → broadcast OnFailed; ② invalid QueryNavigationAdvanced(OwnerLocation, SearchRadius) result → broadcast failure; ③ already at goal (bIsAtGoal or 2D distance ≤ AcceptanceRadius) → broadcast OnSuccess; ④ otherwise enter the FlowField state, store the goal and initial direction, arm the timeout when Timeout > 0, and enable ticking.

开始向固定位置做个体寻路。流程:① 无流场 → NoFlowField;② 无 Owner → Failed;③ 已在目标半径内 → AlreadyAtGoal;④ 按 bUseNavMeshPathfinding 选 FindPathNavMesh 或 FindPathAStar(惰性创建共享 FFlowfieldScratchContext),无路径或路径点不足 → Failed;⑤ 进入 Path 状态,用 GetSteeringDirection 计算初始转向,设置超时,清空目标 Actor,记录 LastPlannedGoalLocation,启用 Tick → Success。

Starts individual pathfinding to a fixed location. Flow: ① no flow field → NoFlowField; ② no owner → Failed; ③ already within the acceptance radius → AlreadyAtGoal; ④ picks FindPathNavMesh or FindPathAStar per bUseNavMeshPathfinding (lazily creating a shared FFlowfieldScratchContext); no path or fewer than 2 points → Failed; ⑤ enters the Path state, computes the initial steering via GetSteeringDirection, arms the timeout, clears the goal actor, records LastPlannedGoalLocation, and enables ticking → Success.

向目标 Actor 做个体寻路:先以 Actor 当前位置调用 StartPathFollowing,成功后把 GoalActor 记为目标并记录初始规划位置——之后目标移动超过 GoalActorReplanThreshold 时自动重规划。

Pathfinding to a goal actor: first calls StartPathFollowing with the actor's current location; on success, stores the actor as GoalActor and records the initial planned location — subsequent goal movement beyond GoalActorReplanThreshold triggers automatic replanning.

停止一切移动并复位状态:状态置 Idle、方向清零、路径清空、超时清除、目标 Actor 复位,清空 OnSuccess / OnFailed 的全部绑定,并关闭组件 Tick。

Stops all movement and resets state: state to Idle, direction zeroed, path cleared, timeout cleared, goal actor reset, all OnSuccess / OnFailed bindings cleared, and the component tick disabled.

是否处于移动状态(状态 != Idle)。

Whether the component is moving (state != Idle).

返回当前移动状态。

Returns the current movement state.

返回当前转向方向(归一化二维方向);空闲(StopMovement 复位后)为零向量。

Returns the current steering direction (normalized 2D); zero when idle (reset by StopMovement).

返回到当前目标(可能为目标 Actor 当前位)的二维距离。Owner 已销毁时返回 -1.0f 表示无效。

Returns the 2D distance to the current goal (which may be the goal actor's current location). Returns -1.0f when the owner is gone, signaling invalid.

返回当前记录的目标位置(FlowField 模式下每帧从导航结果更新;Path 模式下为路径目标,追踪 Actor 时随 Actor 更新)。

Returns the current recorded goal location (updated each frame from the navigation result in FlowField mode; the path goal in Path mode, refreshed from the tracked actor when following one).

FlowField 模式每帧逻辑:流场或 Owner 失效 → 停止并广播失败;否则 QueryNavigationAdvanced(OwnerLocation, SearchRadius) 查询:结果无效(丢失流场)→ 停止并广播失败;有效则更新 GoalLocation 与 CurrentDirection(流场目标可动态变化)。

Per-frame logic for FlowField mode: invalid flow field or owner → stop and broadcast failure; otherwise QueryNavigationAdvanced(OwnerLocation, SearchRadius) — an invalid result (lost the flow field) stops and broadcasts failure; a valid one updates GoalLocation and CurrentDirection (flow field goals can change dynamically).

Path 模式每帧逻辑:① Owner 无效或路径点不足 → 停止并广播失败;② 追踪 Actor 时更新目标并检查 ShouldReplanPath(),需要则 ReplanPath();③ 用 GetSteeringDirection 更新转向与路径索引;④ 无有效路径时直接指向目标(GetSafeNormal2D)。

Per-frame logic for Path mode: ① invalid owner or too few path points → stop and broadcast failure; ② when tracking an actor, updates the goal and checks ShouldReplanPath(), replanning via ReplanPath() when needed; ③ updates steering and the path index via GetSteeringDirection; ④ with no valid path, points straight at the goal (GetSafeNormal2D).

判断是否到达目标:Owner 无效返回 false;追踪 Actor 时用其当前位,否则用记录目标;二维距离 ≤ AcceptanceRadius 即为到达。

Determines whether the goal is reached: false when the owner is invalid; uses the goal actor's current location when tracking one, otherwise the recorded goal; reached when the 2D distance ≤ AcceptanceRadius.

应用移动:位移 = Direction * MoveSpeed * DeltaTime,直接 Owner->SetActorLocation(sweep 开启)。源码注释说明这是简化实现——需要物理/碰撞的复杂移动应由使用者用方向驱动自己的移动系统(如 CharacterMovementComponent)。

Applies movement: displacement = Direction * MoveSpeed * DeltaTime, applied directly via Owner->SetActorLocation (sweep on). The source comment notes this is a simple implementation — for complex movement (physics, collision), users should drive their own movement system (e.g. CharacterMovementComponent) with the direction.

判断是否需要重规划:未追踪 Actor 时恒 false;追踪时目标 Actor 当前位与 LastPlannedGoalLocation 的二维距离超过 GoalActorReplanThreshold 即为需要。

Whether the path needs replanning: always false when not tracking an actor; when tracking, true when the goal actor's current location moved more than GoalActorReplanThreshold (2D) from LastPlannedGoalLocation.

重规划到当前目标(追踪 Actor 时用其当前位,否则用记录目标):重新执行 NavMesh / Grid A* 寻路;成功(路径 ≥ 2 点)则更新目标、LastPlannedGoalLocation、重置路径索引并返回 true,否则返回 false 保持旧路径。

Replans to the current goal (the goal actor's current location when tracking one, otherwise the recorded goal): re-runs NavMesh / Grid A* pathfinding; on success (≥ 2 path points) updates the goal, LastPlannedGoalLocation, resets the path index, and returns true; otherwise returns false and keeps the old path.

调试可视化:绿色球(目标 + 接受半径)、黄色圆(Owner 接受半径)、青色箭头(当前方向)、白色虚线(到目标的连线);Path 模式下绘制路径线段(已完成=蓝 / 当前段=橙 / 未到达=红)、路径点(当前目标点半径 = PathRadius、品红)、当前目标点半径圆,以及包含状态、距离、超时信息的调试文本。

Debug visualization: green sphere (goal + acceptance radius), yellow circle (owner's acceptance radius), cyan arrow (current direction), white dashed line (to the goal); in Path mode also path segments (completed = blue / current = orange / upcoming = red), waypoints (current target sized PathRadius, magenta), the current target's radius circle, and a debug text with state, distance, and timeout info.