FlowField.h

启用每帧 Tick;创建默认场景根与四个组件:Volume(无碰撞盒体,不参与导航)、ISM_Arrows(无碰撞、无阴影、不接收贴花、不参与导航的方向箭头实例化网格)、Decal_Cells(格子贴花,相对旋转 (90,0,0))、Billboard(编辑器图标)。

Enables per-frame tick; creates the default scene root and four components: Volume (non-colliding box, no navigation participation), ISM_Arrows (non-colliding, no shadows, no decals, no navigation — instanced arrow mesh), Decal_Cells (cell decal, relative rotation (90,0,0)), and Billboard (editor icon).

编辑器构造回调:调用父类后调用 DrawDebug()——编辑器里改动配置即触发整条生成管线重算。

Editor construction callback: calls the parent, then DrawDebug() — touching configuration in the editor triggers a full generation-pipeline recalculation.

每帧回调(构造函数启用 Tick)。当前唯一逻辑:当 drawGraphEdgesInGame 开启且本场为已导入基底的 NavMesh 同步场时,逐帧绘制复制品的真实多边形轮廓(锁步端真正寻路的网格,而非引擎 navmesh):银色 = 普通地面多边形(区域代价 1),橙色 = 代价被 modifier 改动的地面多边形,品红线段 = NavLink(离网连接端点连线)。单帧调试线(无累积),大网格开销高,需显式开启。仅 Game/PIE 世界绘制。

Per-frame callback (tick enabled by the constructor). Its only current logic: with drawGraphEdgesInGame on and this field being a synced NavMesh field with an imported substrate, draws per-frame one-shot debug lines of the replica's actual polygon outlines (the mesh the lockstep peers really path over — not the engine navmesh): silver = normal ground poly (area cost 1), orange = ground poly whose cost was touched by a modifier, magenta segment = NavLink (off-mesh connection endpoints). No accumulation; heavy on large meshes and strictly opt-in. Draws in Game/PIE worlds only.

编辑器调试入口:先 InitFlowField(Construction),在 bEditorLiveUpdate 开启时执行完整重算管线——GetGoalLocation → GetAllModifiers → Grid 分支(CreateGrid → ModifyGrid → ModifyCost → CalculateFlowField → 存 BaseDirArray → ModifyFlowField → DrawCells → DrawArrows)/NavMesh 分支(CalculateFlowField_NavMesh → 存 BaseNavMeshDirMap → ModifyFlowField_NavMesh → DrawArrows → DebugDrawNavMeshAreaCosts)。

Editor debug entry: first InitFlowField(Construction); with bEditorLiveUpdate on, runs the full recalculation pipeline — GetGoalLocation → GetAllModifiers → Grid branch (CreateGrid → ModifyGrid → ModifyCost → CalculateFlowField → store BaseDirArray → ModifyFlowField → DrawCells → DrawArrows) / NavMesh branch (CalculateFlowField_NavMesh → store BaseNavMeshDirMap → ModifyFlowField_NavMesh → DrawArrows → DebugDrawNavMeshAreaCosts).

运行时完整更新入口(同步)。bFullRebuild 为 true 时从环境查询重建整张网格,并重扫 modifier(重扫基底 = 运行时注册,Include/Attach 条目在其上合并去重——重扫不再抹掉运行时注册);否则沿用现有网格,只整合目标/修改器变化后重算。流程与 DrawDebug 一致,初始化模式按 bIsBeginPlay 取 BeginPlay/Runtime。末尾 bIsBeginPlay = false。Grid 模式下 bFullRebuild 时跳过 ModifyGrid(全新网格不含修改)。同步场守卫:已导入基底(bSyncedSubstrate)时——NavMesh 模式任何端都只在导入复制品上重洪泛方向(目标/修改器刷新,绝不触碰基底字节;目标取流内快照),客户端 Grid 场的本地构建被忽略(一次性 Warning),服务器重建 Grid 场则退出同步模式(需重新导出基底)。

Runtime full-update entry (synchronous). With bFullRebuild true, rebuilds the entire grid from environment queries and rescans modifiers (the rescan base = runtime registrations, with Include/Attach entries merged on top, deduplicated — rescans no longer wipe runtime registrations); otherwise reuses the existing grid, integrating only goal/modifier changes before recalculating. The flow matches DrawDebug, with the init mode picked as BeginPlay/Runtime from bIsBeginPlay. Ends with bIsBeginPlay = false. In Grid mode a full rebuild skips ModifyGrid (the fresh grid carries no modifications). Synced-field guard: with an imported substrate (bSyncedSubstrate) — NavMesh mode re-floods directions on the imported replica on ANY peer (goal/modifier refresh; substrate bytes are never touched; goals come from the stream snapshot), a client-side Grid build is ignored (one-shot Warning), and a server-side Grid rebuild leaves synced mode (re-export the substrate to re-sync).

定时更新入口:nextTickTimeLeft <= 0 时调用 UpdateFlowField(bFullRebuild),随后调用 UpdateTimer() 推进定时器(间隔 = RefreshInterval,按世界 DeltaSeconds 倒计时)。

Timed update entry: calls UpdateFlowField(bFullRebuild) when nextTickTimeLeft <= 0, then UpdateTimer() to advance the timer (interval = RefreshInterval, counted down by world delta seconds).

检查两点间路径是否有效。已导入基底的 NavMesh 同步场:经复制品 A*(FindPathReplica)测试,绝不查引擎;普通 NavMesh 模式:用 TestPathSync 在导航系统上做同步可达性测试;Grid 模式:不做完整寻路(成本太高),仅验证两端点都是有效格子且非障碍(type != Obstacle 且 cost != 255)。

Checks whether a path from Start to End is valid. A synced NavMesh field with an imported substrate tests via the replica A* (FindPathReplica), never the engine; regular NavMesh mode: synchronous reachability test via TestPathSync on the navigation system; Grid mode: no full pathfinding (too expensive for a reachability check), only verifies both endpoints are valid non-obstacle cells (type != Obstacle and cost != 255).

解析并缓存 RecastNavMesh:① 缓存命中直接返回;② 非游戏线程返回 nullptr(缓存仅限游戏线程写入);③ TargetNavMeshName 非空时按名字搜索场景中的 RecastNavMesh;④ 未找到回退到导航系统默认 NavMesh;⑤ 找到后写入 CachedRecastNavMesh(const_cast 缓存)。

Resolves and caches the RecastNavMesh: ① returns the cache on hit; ② returns nullptr off the game thread (cache writes are game-thread only); ③ with a non-empty TargetNavMeshName, searches the scene by name; ④ falls back to the navigation system's default NavMesh; ⑤ caches the result into CachedRecastNavMesh (via const_cast).

NavMesh 模式「未能生成流场」的诊断入口:递增 NavMeshFlowMissingStreak,仅当失败连续持续(达到 3 次)且尚未记录过时,输出一条 LogTemp Error 日志(含原因与连续失败次数)。world/地图加载期间的单次失败(导航系统或 navmesh 尚未就绪)是预期瞬态,保持静默;成功生成一次后清零重置(重新武装)。由 CalculateFlowField_NavMesh 的各失败分支调用。

Diagnostics entry for "NavMesh mode produced no flow field": increments NavMeshFlowMissingStreak and — only when the failure persists (streak reaches 3) and hasn't been logged yet — emits one LogTemp Error (with the reason and the streak count). Single-shot failures during world/map init (navigation system or navmesh not ready yet) are expected transients and stay silent; a successful generation resets the counters (re-arms). Called from the failure branches of CalculateFlowField_NavMesh.

NavMesh 模式未配置目标的一次性 LogTemp Warning:此时不生成任何流向——这是合法用法(流场仅作高度场/个体寻路使用);如需流向请配置 GoalActors/GoalLocations。由 CalculateFlowField_NavMesh 在目标集为空时调用,成功生成后重置可再次告警。

One-shot LogTemp Warning for NavMesh mode with no goals configured: no flow directions are produced — this is legal usage (the flow field serves as a height field / individual pathfinding only); add GoalActors/GoalLocations if flow directions are needed. Called by CalculateFlowField_NavMesh when the goal set is empty; reset by a successful generation so it can warn again.

世界位置 → 网格坐标。把位置变换到 Actor 的相对系(旋转 -actorRot.Yaw + offsetLoc),按 cellSize 取整;越界时返回 false 但输出仍钳制到 [0, xNum-1] × [0, yNum-1]。

World location → grid coord. Transforms the location into the actor's relative frame (rotate -actorRot.Yaw + offsetLoc) and rounds by cellSize; out of bounds returns false while the output is still clamped to [0, xNum-1] × [0, yNum-1].

世界位置 → 格子数组索引。经 WorldToGrid(钳制)+ CoordToIndex 计算;网格未初始化(bIsBeginPlay)时输出 0 并返回 false;越界时索引钳制到 [0, CellCount-1] 但返回 false。

World location → cell array index. Computed via WorldToGrid (clamping) + CoordToIndex; when the grid is uninitialized (bIsBeginPlay) outputs 0 and returns false; out of bounds clamps the index to [0, CellCount-1] but returns false.

网格坐标 → 数组索引:Z 忽略,X * yNum + Y。NavMesh 模式恒返回 0。

Grid coord → array index: Z ignored, X * yNum + Y. Always returns 0 in NavMesh mode.

取世界位置对应的格子引用。NavMesh 模式:把位置投影到导航网格(ProjectPointToNavigation,extent 默认取 PathStopSearchDist,水平 500 兜底),跳过 off-mesh 连接,从 NavMeshCellMap 按 NodeRef 查找;Grid 模式:钳制坐标取 CurrentCellsArray 中对应格,越界时仍返回钳制格的引用但 bOutIsValid = false(注释说明钳制格数据有效)。网格未初始化时返回 DefaultCell 且无效。

Returns the cell reference at a world location. NavMesh mode: projects the location onto the nav mesh (ProjectPointToNavigation, default extent from PathStopSearchDist with a 500 horizontal fallback), skips off-mesh connections, and looks up NavMeshCellMap by NodeRef; Grid mode: clamps the coord and returns the corresponding CurrentCellsArray cell — out of bounds still returns the clamped cell's reference with bOutIsValid = false (the comment notes clamped cell data is valid). Returns DefaultCell (invalid) when the grid is uninitialized.

取网格坐标对应的格子引用。NavMesh 模式:CurrentCellsArray 非空时返回第 0 项(占位目标格);Grid 模式:坐标与索引都有效时返回对应格,越界钳制返回但 bOutIsValid = false。

Returns the cell reference for a grid coord. NavMesh mode: returns element 0 of CurrentCellsArray (the placeholder goal cell) when non-empty; Grid mode: returns the cell when both the coord and index are valid; out of bounds returns the clamped cell with bOutIsValid = false.

取位置周围半径内的平均流场方向。Grid 模式:遍历半径覆盖的格子(用格边界相交检测),对与圆相交的格方向求和平均(Z 清零归一化);无有效格时按 PathStopSearchDist.X 做环形螺旋搜索最近 Ground 格,返回指向它的方向。NavMesh 模式:直接返回该位置的精确方向;投影失败时按 PathStopSearchDist 搜索最近 NavMesh 点并返回指向它的方向。均失败返回零向量。

Returns the average flow field direction within a radius around a location. Grid mode: walks the cells the circle covers (cell-boundary intersection test), sums and averages the directions of intersecting cells (Z zeroed then normalized); with no valid cells, spiral-searches the nearest Ground cell within PathStopSearchDist.X and returns the direction toward it. NavMesh mode: returns the exact direction at the location; when projection fails, searches the nearest NavMesh point within PathStopSearchDist and returns the direction toward it. Returns a zero vector when everything fails.

单格导航查询的便捷入口:直接转发到 QueryNavigationAdvanced(Location, 0.0f, SearchExtent, nullptr)。

Convenience entry for single-cell navigation queries: forwards directly to QueryNavigationAdvanced(Location, 0.0f, SearchExtent, nullptr).

高级导航查询(半径插值)。NavMesh 模式:① 投影到网格,跳过 off-mesh 连接;② SearchRadius = 0 单格返回 dir/GoalWorldLoc/dist;③ > 0 时用 findPolysAroundCircle 收集附近多边形(复用 Context 的 dtNavMeshQuery 或栈上新建),按到共享边距离(直接邻居)或最近点(兜底)加权平均方向,SampledCellsHash 为采样多边形哈希;④ 投影失败按 PathStopSearchDist 兜底投影。Grid 模式:① 未初始化返回无效;② 单格查询(钳制格,数据有效);③ 半径查询——按格中心二维距离加权平均(权重 1/(1+d/R)),跳过 cost ≥ 255 或非 Ground 格,hash 为采样索引组合;④ 无命中时环形螺旋搜索最近 Ground 格。`

Advanced navigation query with radius-based interpolation. NavMesh mode: ① projects onto the mesh, skipping off-mesh connections; ② SearchRadius = 0 returns the single cell's dir/GoalWorldLoc/dist; ③ with > 0, collects nearby polygons via findPolysAroundCircle (reusing the Context's dtNavMeshQuery or a stack query), weighting by distance to the shared edge (direct neighbors) or the closest point (fallback); SampledCellsHash hashes the sampled polygons; ④ on projection failure, falls back via PathStopSearchDist. Grid mode: ① uninitialized returns invalid; ② single-cell query (clamped cell, data valid); ③ radius query — 2D distance-weighted average by cell center (weight 1/(1+d/R)), skipping cost ≥ 255 or non-Ground cells, hash combines sampled indices; ④ with no hits, spiral-searches the nearest Ground cell.

创建新层:分配 NextLayerID++ 的 ID,保存层名与目标,存入 FlowFieldLayers,返回句柄。注意创建后需调用 UpdateLayer 计算。

Creates a new layer: allocates an ID from NextLayerID++, stores the name and goals, inserts into FlowFieldLayers, and returns the handle. Note UpdateLayer must be called afterwards to compute it.

销毁层并释放其数据(从 FlowFieldLayers 移除)。无效句柄静默无操作。

Destroys a layer and frees its data (removes it from FlowFieldLayers). Invalid handles are silent no-ops.

检查层句柄是否有效:句柄自身有效且 FlowFieldLayers 中存在该 ID。

Checks whether a layer handle is valid: the handle is valid and the ID exists in FlowFieldLayers.

更新已有层的目标并置 bIsValid = false 使其失效——之后需调用 UpdateLayer 重算。无效句柄输出 Warning 日志。

Updates an existing layer's goals and invalidates it (bIsValid = false) — call UpdateLayer afterwards to recalculate. Invalid handles emit a Warning log.

(重)计算指定层(同步)。流程:解析目标 Actor 位置 → 与目标位置合并;无目标则置无效返回。Grid 模式:目标转网格坐标(钳制,含网格外),把 CurrentCellsArray 拷贝到临时数组并清零计算字段,以层目标调用 CalculateFlowField,提取 GridOverlay/BaseDirArray,再套用方向修改器写回。NavMesh 模式:目标投影到网格多边形(ProjectPointToNavigation),以层目标调用 CalculateNavMeshFlow,提取 NavMeshOverlay/BaseNavMeshDirMap,套用方向修改器。成功置 bIsValid = true。默认层(网格/导航)必须先初始化。

(Re)computes a layer synchronously. Flow: resolves goal actor locations → merges with goal locations; no goals → invalid and return. Grid mode: converts goals to grid coords (clamped, including off-grid), copies CurrentCellsArray into a temp array with computed fields zeroed, runs CalculateFlowField with the layer's goals, extracts GridOverlay/BaseDirArray, then applies the direction modifiers back. NavMesh mode: projects goals onto the mesh (ProjectPointToNavigation), runs CalculateNavMeshFlow with the layer's goals, extracts NavMeshOverlay/BaseNavMeshDirMap, applies the direction modifiers. Sets bIsValid = true on success. The default layer (grid/navmesh) must already be initialized.

单格查询指定层:转发到 QueryNavigationAdvancedLayer(Location, LayerHandle, 0.0f, SearchExtent, nullptr)。

Single-cell query on a specific layer: forwards to QueryNavigationAdvancedLayer(Location, LayerHandle, 0.0f, SearchExtent, nullptr).

指定层的高级查询。层不存在或未计算(bIsValid = false)时返回无效。NavMesh 模式:投影位置后从 Layer->NavMeshOverlay 按 NodeRef 取叠加数据(无半径插值)。Grid 模式:单格查询取 GridOverlay[Index];半径查询按格中心二维距离加权平均(权重 1/(1+d/R)),跳过 cost == 255 或 dist == 65535 的格子,最近格决定目标信息。

Advanced query on a specific layer. Invalid when the layer is missing or not computed (bIsValid = false). NavMesh mode: projects the location and reads the overlay from Layer->NavMeshOverlay by NodeRef (no radius interpolation). Grid mode: single-cell query reads GridOverlay[Index]; radius query computes a 2D distance-weighted average by cell center (weight 1/(1+d/R)), skipping cells with cost == 255 or dist == 65535, with the closest cell deciding the goal metadata.

为层增加一个使用者(一个 MoveTo 任务)——按任务计数,非按 agent:任务的 agent 共享一层,先于任务结束统一结算。层不存在时输出 LogTemp Warning 并返回 false。

Acquires one layer user (one MoveTo task) — task-level counting, not per agent: a task's agents share one layer and resolve before the task ends. A missing layer logs a LogTemp Warning and returns false.

释放一个层使用者。托管(自动回收)层计数归零时入队待销毁(PendingLayerDestroys),绝不即时删除——并行移动阶段的 worker 线程还在读 FlowFieldLayers;冲刷时会复查计数,期间被重新 Acquire 的层得以存活(如 resync 后任务重建重新取层)。层不存在或计数已为 0(重复释放/未获取就释放)时输出 Warning 并返回 false,计数钳制不为负。

Releases one layer user. When an auto-release (managed) layer's count reaches 0 it is QUEUED for deferred destruction (PendingLayerDestroys), never removed inline — worker threads query FlowFieldLayers during the parallel move stages; the flush re-checks the count, so a layer re-acquired meanwhile survives (e.g. task rebuild after resync re-acquires its layers). A missing layer, or a count already at 0 (double release / release without acquire), warns and returns false with the count clamped at zero.

待销毁层的静态冲刷:遍历 LiveInstances 中全部存活实例(顺手清理失效弱引用),逐个调用其 FlushPendingLayerDestroys。必须在并行移动阶段之外的游戏线程串行窗口执行——由 UMassBattleSubsystem 在其串行窗口调用(任务重建窗口内抑制)。

Static drain of pending layer destroys: iterates every live instance in LiveInstances (pruning stale weak references along the way) and calls each one's FlushPendingLayerDestroys. MUST run on the game thread OUTSIDE the parallel move stages — called by UMassBattleSubsystem from its serial window (suppressed during the task-rebuild window).

创建托管(自动回收)层:经 CreateLayer 创建后标记 bAutoRelease 与 ManagedGoalHash,并同步 UpdateLayer 计算。LayerName 为 None 时自动由哈希命名(MBManaged_<hash>)。GoalHash 为 0 或目标为空时返回无效句柄。

Creates a managed (auto-release) layer: creates it via CreateLayer, stamps bAutoRelease and ManagedGoalHash, then computes synchronously with UpdateLayer. A None LayerName auto-derives from the hash (MBManaged_<hash>). A zero GoalHash or empty goals returns an invalid handle.

更新托管层的目标 + 哈希并同步重算——单用 SetLayerGoals 会留下一段失效窗(它只置失效不重算),本函数在同一调用内闭合。层不存在或 GoalHash 为 0 时返回 false。

Updates a managed layer's goals + hash and recomputes synchronously — SetLayerGoals alone leaves an invalid window (it only invalidates), which this closes in one call. Returns false for a missing layer or a zero GoalHash.

按目标哈希查找存活托管层——UMassBattleFuncLib::GetOrAcquireFlowFieldLayer 的复用路径:命中即复用(必要时先 UpdateManagedLayerGoals),未命中则创建。只匹配 bAutoRelease 的层;哈希为 0 直接返回 false。

Finds a live managed layer by goal hash — the reuse path of UMassBattleFuncLib::GetOrAcquireFlowFieldLayer: a hit is reused (with an UpdateManagedLayerGoals first when needed), a miss creates one. Matches only bAutoRelease layers; a zero hash returns false immediately.

读取层的在用使用者数(诊断用,BlueprintPure)。

Reads a layer's live user count (diagnostics; BlueprintPure).

只读层查找:直接在 FlowFieldLayers 中按 LayerID 取指针,不存在为 nullptr(内联实现)。

Read-only layer lookup: a direct FlowFieldLayers find by LayerID; nullptr when absent (inline).

本实例的待销毁层冲刷(静态 FlushAllPendingLayerDestroys 的实例级实现):逐项复查 UserCount == 0 且 bAutoRelease 才从 FlowFieldLayers 移除——入队后被重新 Acquire 的层存活;无论是否移除,队列条目都会被清掉(再次归零的层会在下次 Release 重新入队)。

Instance-level drain of pending layer destroys (what the static FlushAllPendingLayerDestroys calls): re-checks UserCount == 0 and bAutoRelease before removing a layer from FlowFieldLayers — layers re-acquired since queuing survive; the queue entry is dropped either way (a layer hitting zero again re-queues on its next release).

初始化几何与可视化状态:① Construction/BeginPlay 模式重置定时器与 bIsGridDirty,NavMesh 模式缓存 NavMesh 并收集 NavLink;② 钳制 cellSize/flowFieldSize/initialCost,重算 xNum/yNum、缓存 actorLoc/actorRot/offsetLoc/relativeLoc;③ 设置 Volume 盒体范围与贴花尺寸;④ 按模式创建/更新动态材质(CellDMI/ArrowDMI)并写入 XNum/YNum/CellSize/Offset/Yaw 参数;⑤ 按 GenerationMode 与绘制开关切换 Volume/贴花/箭头(及 NavMesh 多边形的填充/边线)可见性。

Initializes geometry and visualization state: ① in Construction/BeginPlay modes resets the timer and bIsGridDirty, caching the NavMesh and collecting NavLinks in NavMesh mode; ② clamps cellSize/flowFieldSize/initialCost, recomputes xNum/yNum and caches actorLoc/actorRot/offsetLoc/relativeLoc; ③ sets the Volume box extent and decal size; ④ creates/updates the dynamic materials (CellDMI/ArrowDMI) per mode and writes the XNum/YNum/CellSize/Offset/Yaw parameters; ⑤ toggles Volume/decal/arrow visibility (and NavMesh poly fill/edge drawing) per generation mode and draw toggles.

收集目标:解析 GoalActors 的当前位置填入 GoalActorLocations,把目标 Actor 位置与 GoalLocations 合并后经 WorldToGrid 转为 GoalGridCoords。

Collects goals: resolves GoalActors current locations into GoalActorLocations, merges them with GoalLocations, and converts all into GoalGridCoords via WorldToGrid.

创建/重建整张网格:bIsGridDirty 为 false 时直接返回;否则清空 InitialCellsArray/CurrentCellsArray,按 xNum × yNum 逐格调用 EnvQuery 填充初始格数据,末尾清 bIsGridDirty。

Creates/rebuilds the whole grid: returns immediately when bIsGridDirty is false; otherwise clears InitialCellsArray/CurrentCellsArray, fills initial cell data cell by cell via EnvQuery over xNum × yNum, then clears bIsGridDirty.

向本场注册 modifier(运行时推送——或 BP 手动按需)。按类型分派到 RuntimeGridModifiers/RuntimeCostModifiers/RuntimeDirModifiers,并同步进入活动列表(GridModifiers/CostModifiers/DirModifiers,AddUnique 去重),方向/成本列表注册后按 priority 重排——UpdateFlowField/ModifyGrid 当帧即可见到。幂等(Include/Attach 成员重复注册无害,Contains 守卫使副作用只在真新增时触发);与 GetAllModifiers 一致地盖写 modifier 的 FlowField 反向指针;重扫不丢(GetAllModifiers 以运行时注册为基底再合并)。NavMesh 模式下注册 Cost/Grid modifier 仍输出 Warning(不支持)。背景:GetAllModifiers 只认 Include 列表与挂场子 Actor 两个来源,运行时独立 spawn 的 modifier 原本要付一次 full rebuild 才能被看见——推模式取代之;全部 modifier 家族都是空间圈选型(体积/样条),注册到同世界全部场在圈外零开销。

Registers a modifier with this field (runtime push — or manual on-demand from BP). Dispatches by type into RuntimeGridModifiers/RuntimeCostModifiers/RuntimeDirModifiers and simultaneously enters the active lists (GridModifiers/CostModifiers/DirModifiers, AddUnique-deduped); direction/cost lists are re-sorted by priority after registration — UpdateFlowField/ModifyGrid see it the same frame. Idempotent (Include/Attach members re-register harmlessly; a Contains guard fires side effects only on true additions); stamps the modifier's FlowField back-pointer like GetAllModifiers; survives rescans (GetAllModifiers merges on top of the runtime set). Registering Cost/Grid modifiers in NavMesh mode still warns (unsupported). Background: GetAllModifiers only sees the Include list and attached child actors — a runtime-spawned standalone modifier used to require paying a full rebuild to be seen; the push model replaces that. All modifier flavors are spatial (volume/spline-scoped), so registering with every same-world field is free outside their shape.

移除一个运行时/手动注册(幂等):从对应的运行时集合与活动列表同时移除。Include/Attach 成员关系不动——那些条目在下次 GetAllModifiers 重扫时会回来。

Removes a runtime/manual registration (idempotent): drops it from both the matching runtime set and the active list. Include/Attach membership is untouched — those entries return on the next GetAllModifiers rescan.

收集场景中的修改器:重扫基底 = 运行时/手动注册(推模式的 Runtime*Modifiers 集合),再遍历 IncludeModifiers 与挂在本 Actor 下的子 Actor,在其上合并去重并回填 FlowField 软引用——full rebuild 重扫不再抹掉运行时注册;方向与成本修改器(合并整体)按 priority 升序重排,应用顺序不因来源失稳。NavMesh 模式下对 Cost/Grid 修改器输出 Warning(不支持)。

Collects scene modifiers: the rescan base = runtime/manual registrations (the push model's Runtime*Modifiers sets), then iterates IncludeModifiers and child actors attached under this actor, merging deduped on top with their FlowField soft references back-filled — a full-rebuild rescan no longer wipes runtime registrations; the merged direction and cost lists are re-sorted ascending by priority so application order stays source-stable. In NavMesh mode, warns about Cost/Grid modifiers (unsupported).

同步应用全部启用的网格修改器:清空 GridModifiedSet,依序调用每个修改器的 ApplyGridModification(this, GridModifiedSet)(跳过 bEnable = false)。

Applies all enabled grid modifiers synchronously: clears GridModifiedSet, then calls each modifier's ApplyGridModification(this, GridModifiedSet) in order (skipping bEnable = false).

异步应用全部启用的网格修改器:逻辑与 ModifyGrid 相同,但调用 ApplyGridModificationAsync——各修改器通过 EnvQueryAsync 发起异步 trace 并递增 TraceRemaining;全部完成后由 UpdateCellMap 触发 DoneAllTracesDelegate。

Applies all enabled grid modifiers asynchronously: same logic as ModifyGrid, but calls ApplyGridModificationAsync — modifiers launch async traces via EnvQueryAsync and increment TraceRemaining; when all finish, UpdateCellMap triggers DoneAllTracesDelegate.

应用成本修改:① InCurrentCellsArray = InInitialCellsArray 拷贝;② 目标格 cost 置 0;③ 依序调用启用的成本修改器;④ 叠加静态 ExtraCosts(键 = 格子索引,值相加后钳制 [0,255])。

Applies cost modifications: ① copies InInitialCellsArray into InCurrentCellsArray; ② zeroes the goal cells' cost; ③ calls enabled cost modifiers in order; ④ overlays static ExtraCosts (key = cell index, value added then clamped to [0,255]).

Grid 模式的核心求解器。Phase 1 积分场(Dijkstra):目标格 dist = 0 入最小堆,按 Style 决定邻居顺序(AdjacentFirst 对角线先行校验 / DiagonalFirst 仅四邻),跳过越界、障碍(bIgnoreInternalObstacleCells 时)、坡度超 maxWalkableAngle 的邻居;newDist = 邻居cost + 当前dist 更小则更新并继承目标坐标。Phase 2 方向场(ParallelFor 并行):cost 255 或 dist 65535 置零方向;开启 bStraightFirst 时用 Bresenham 视线检查(Bresenham 线上任一格 cost 255 或与基础数组 cost 不一致即无视线),有视线则直接指向目标;否则在 8 邻居中取 dist 最小的格(邻接/对角有效性校验 + 坡度校验),指向该格。

The core solver for Grid mode. Phase 1 integration field (Dijkstra): goal cells start at dist = 0 in a min-heap; neighbor order follows Style (AdjacentFirst checks diagonals first / DiagonalFirst uses only four neighbors); skips out-of-bounds, obstacle (bIgnoreInternalObstacleCells on) and over-maxWalkableAngle slope neighbors; a smaller newDist = neighbor.cost + current.dist updates the cell and inherits the goal coord. Phase 2 direction field (ParallelFor): cost 255 or dist 65535 cells get a zero direction; with bStraightFirst a Bresenham line-of-sight check runs (any cell on the line with cost 255 or differing from the base array's cost kills LOS), pointing directly at the goal when clear; otherwise the 8-neighbor cell with the smallest dist is chosen (diagonal validity + slope checks) and pointed at.

NavMesh 模式求解入口:清空 NavMeshCellMap;构造占位目标格(首目标位置,存 CurrentCellsArray[0]);把目标合并后投影到网格得到目标多边形集合;初始化面积成本上下文;调用静态 CalculateNavMeshFlow 完成 Dijkstra 积分场(多边形中心/共享边中点计距、面积成本、NavLink 单向/双向规则)+ 并行方向场(string pulling 射线 + 拓扑一致性校验、NextPolyRef 直连、直接链接邻居与空间对角搜索)。

NavMesh-mode solver entry: clears NavMeshCellMap; builds the placeholder goal cell (first goal location, stored in CurrentCellsArray[0]); merges goals, projects them onto the mesh to get the goal polygon set; initializes the area-cost context; then calls the static CalculateNavMeshFlow for the Dijkstra integration field (polygon centers / shared-edge midpoints for distance, area costs, one-way/bidirectional NavLink rules) plus the parallel direction field (string pulling raycast + topological consistency check, NextPolyRef direct links, direct-link neighbors and spatial diagonal search).

Grid 模式应用方向修改器:清空 InDirModifiedSet,依序调用启用的方向修改器(跳过 bEnable = false)。

Applies direction modifiers in Grid mode: clears InDirModifiedSet, then calls each enabled direction modifier in order (skipping bEnable = false).

NavMesh 模式应用方向修改器:清空 InDirModifiedSet,依序调用各修改器的 ApplyDirectionModification_NavMesh。

Applies direction modifiers in NavMesh mode: clears InDirModifiedSet, then calls each modifier's ApplyDirectionModification_NavMesh in order.

把格子数据烘焙成瞬时纹理并交给贴花材质:构造 xNum × yNum 的 transient UTexture2D,每格写 RGBA——A = 非 Empty, R = cost, G = 被网格修改(GridModifiedSet),B = dist 归一化到最大距离;随后把纹理参数写入 CellDMI。仅在对应绘制开关开启时执行。

Bakes cell data into a transient texture for the decal material: builds an xNum × yNum transient UTexture2D, writing RGBA per cell — A = non-Empty, R = cost, G = grid-modified (GridModifiedSet), B = dist normalized to the maximum distance; then writes the texture parameter into CellDMI. Runs only when the matching draw toggle is on.

重建 ISM 箭头实例(每次绘制全量重建)。Grid 模式:每格按 normal 对齐方向(先对齐法线再平面内旋转),高度按坡度偏移(越陡抬越高),Empty 格隐藏、无方向格染红(custom data 2)、被方向修改的格染蓝(1)、其余白色(0)。NavMesh 模式(仅编辑器宏内):逐多边形地面射线定位、贴表面定向,跳过 NavLink;未覆盖的多边形(无流场/不可达)渲染红点。实例自定义数据经 SetCustomDataValue 写入。

Rebuilds the ISM arrow instances (full rebuild every draw). Grid mode: per cell, aligns the direction to the normal (normal-align then in-plane rotate), offsets height by slope (steeper = higher); Empty cells are hidden, direction-less cells tint red (custom data 2), direction-modified cells blue (1), the rest white (0). NavMesh mode (inside an editor-only macro): per polygon, ground-trace positions with surface-aligned orientation, skipping NavLinks; uncovered polygons (no flow field / unreachable) render as red dots. Instance custom data is written via SetCustomDataValue.

推进定时器:nextTickTimeLeft <= 0 时重置为 RefreshInterval(钳制 ≥ 0),否则按世界 DeltaSeconds 递减。

Advances the timer: resets nextTickTimeLeft to RefreshInterval (clamped ≥ 0) when it is ≤ 0, otherwise decrements it by the world delta seconds.

单格环境查询(同步):按 gridCoord 计算格心世界位置;开启 traceGround 时向 groundObjectType 做线 trace——命中则取撞击点高度/法线,坡度超 maxWalkableAngle 判为障碍,否则(开启 traceObstacles)再做球体 trace(半径 cellSize/2)判障碍;未命中地面为 Empty。未开启地面 trace 时格高取 actorLoc.Z + flowFieldSize.Z/2,同样按 traceObstacles 判障碍。未命中障碍时 cost = initialCost(255 时 type = Obstacle)。

Single-cell environment query (synchronous): computes the cell-center world location from gridCoord; with traceGround on, line-traces groundObjectType — a hit takes the impact height/normal, cells steeper than maxWalkableAngle become obstacles, otherwise (with traceObstacles on) a sphere trace (radius cellSize/2) decides obstacles; a miss makes the cell Empty. Without ground tracing the cell height is actorLoc.Z + flowFieldSize.Z/2, again obstacle-checked per traceObstacles. Without obstacle hits, cost = initialCost (type = Obstacle when 255).

单格环境查询(异步):与 EnvQuery 同语义,但经 AsyncLineTraceByObjectType / AsyncSweepByObjectType 发起(弱引用捕获 this,避免销毁后回调);每个 trace 完成经 lambda 按同规则判定,通过 DoneTraceDelegate(即 UpdateCellMap)交回结果并递减 TraceRemaining。

Single-cell environment query (asynchronous): same semantics as EnvQuery but launched via AsyncLineTraceByObjectType / AsyncSweepByObjectType (capturing a weak reference to this to survive destruction); each completion lambda applies the same rules and hands the result back through DoneTraceDelegate (i.e. UpdateCellMap), which decrements TraceRemaining.

取位置处的地面插值位置与法线。NavMesh 模式:ProjectPointToNavigation 投影到网格表面,再对中心与 ±X 三个采样点做三角形法线混合(中心权重 2,两侧各 1),输出连续法线。Grid 模式:连续网格坐标下对 4 邻格做双线性插值(位置与法线均插值,法线中间步骤归一化);四邻任一无效即失败。失败时输出置零/向上并返回 false。

Gets the interpolated ground location and normal at a location. NavMesh mode: projects onto the mesh surface via ProjectPointToNavigation, then blends triangle normals sampled at the center and ±X (center weight 2, sides 1) for a continuous normal. Grid mode: bilinear interpolation of the four neighbor cells at continuous grid coords (both location and normal; normals normalized at intermediate steps); any invalid neighbor fails. On failure outputs zero/up and returns false.

按 TraceMode 取地面位置与法线:FlowField 用 GetInterpedWorldLocation(半径 = InSelfRadius);CapsuleSweep 从自身位置向 KillZ 做胶囊体对象扫描(complex trace);FlowFieldOrCapsuleSweep 先流场插值、失败再胶囊扫描。胶囊扫描的命中点/法线取自 HitResult。

Gets the ground location and normal per TraceMode: FlowField uses GetInterpedWorldLocation (radius = InSelfRadius); CapsuleSweep capsule-sweeps from the self location down to KillZ (complex trace); FlowFieldOrCapsuleSweep tries the flow field first and falls back to the capsule sweep. Capsule hit point/normal come from the HitResult.

Grid A* 个体寻路。流程:① 网格未初始化返回 false;② 起终点经 WorldToGrid 钳制,网格外位置若钳制到障碍格则螺旋找最近 Ground 格;③ 同格直连 [Start, Goal];④ Context.Prepare 惰性清场;⑤ 网格内起终点在障碍格内时触发「紧急路径」(启发权重 ×2、允许穿越障碍格 cost 5、对角障碍不拦截);⑥ bStraightFirst 且非紧急时做 Bresenham 视线检查,通畅直接返回 [Start, Goal];⑦ 主循环用上下文内建最小堆,按 Style 决定 8 邻顺序(对角 cost √2),邻居启发为网格曼哈顿距离;⑧ 到达目标后回溯路径——路径点取途经格中心(不含目标格中心),末尾直连真实 GoalLocation,并把末点 Z 对齐前一点。失败返回 false 且路径清空。

Grid A* individual pathfinding. Flow: ① uninitialized grid returns false; ② start/goal coords are clamped via WorldToGrid; off-grid positions clamped onto obstacle cells spiral-search for the nearest Ground cell; ③ same cell connects directly [Start, Goal]; ④ Context.Prepare lazily clears; ⑤ on-grid start/goal inside obstacle cells trigger an "emergency path" (heuristic weight ×2, obstacle cells passable at cost 5, diagonal obstacles not blocking); ⑥ with bStraightFirst and non-emergency, a Bresenham LOS check returns [Start, Goal] directly when clear; ⑦ the main loop uses the context's built-in min-heap, with 8-neighbor order per Style (diagonal cost √2) and grid Manhattan-distance heuristics; ⑧ on reaching the goal, back-traces — path points are intermediate cell centers (the goal cell center excluded), the real GoalLocation connects at the end, and the last point's Z aligns with its predecessor. Returns false with an empty path on failure.

NavMesh 个体寻路。流程:① 无导航系统/默认 NavData 返回 false;② 目标投影到网格(PathStopSearchDist extent);③ bStraightFirst 时做表面射线 LOS + 拓扑一致性校验(终点多边形 == 目标投影多边形),通畅直接返回 [Start, 投影目标];④ FindPathSync(允许部分路径)常规寻路,路径点替换首点为真实起点;⑤ 失败时离网恢复:起终点投影到网格,在投影端点间寻路,再拼接离网补丁段——首尾替换为真实起终点并修剪与起终点重合的冗余点。任一端投影失败返回 false。

NavMesh individual pathfinding. Flow: ① no navigation system / default NavData returns false; ② projects the goal onto the mesh (PathStopSearchDist extent); ③ with bStraightFirst, a surface raycast LOS plus topological consistency check (end polygon == the goal projection's polygon) returns [Start, projected goal] directly when clear; ④ FindPathSync (partial paths allowed) runs the normal search, with the first point replaced by the real start; ⑤ on failure, off-mesh recovery: projects start/goal onto the mesh, paths between the projected endpoints, then splices the off-mesh patch segments — the ends are replaced by the real start/goal and redundant points collapsed onto them are pruned. Returns false when either end fails to project.

锁步基底同步的导出(仅服务器端有意义,实现于 FlowFieldSync.cpp):把已构建的基底序列化为紧凑量化流——Grid 模式序列化格子数据(cost/type/世界 Z/法线,厘米量化),NavMesh 模式(v3 线格式)原样上传服务器原始 tile blob(dtCreateNavMeshData 输出的原始字节),全端可用 Detour 自有 addTile 解析器重建逐字节一致的 dtNavMesh 复制品(拓扑、detail 网格、BVtree、离网连接与量化顶点高度原样过线)。同时一次性捕获目标集快照(导出时刻解析 GoalActors)。场未构建(bIsBeginPlay)或尺寸/navmesh 缺失时返回 false。由 AMassBattleNetworkGameModeBase::SendLockstepCommandToClients_RebuildFlowField 调用(导出后服务器同样自导入)。

Export side of lockstep substrate sync (server-only meaningful; implemented in FlowFieldSync.cpp): serializes the built substrate into a compact quantized stream — Grid mode writes the cell data (cost/type/world Z/normals, centimeter-quantized); NavMesh mode (v3 wire format) ships the server's original tile blobs verbatim (the raw bytes dtCreateNavMeshData emitted), from which every peer rebuilds a byte-identical dtNavMesh replica via Detour's own addTile parser (topology, detail meshes, BVtree, off-mesh connections and quantized vertex heights cross the wire intact). Also captures the goal-set snapshot ONCE (GoalActors resolved at export time). Returns false when the field isn't built (bIsBeginPlay) or the dims/navmesh are missing. Called by AMassBattleNetworkGameModeBase::SendLockstepCommandToClients_RebuildFlowField (which then self-imports on the server too).

用导入基底替换场数据(全端——服务器也重导入自己的导出,全端持有相同字节)。校验魔数/版本与流布局后:Grid 模式按流内 xNum/yNum/cellSize/位置/朝向重建两个格子数组(世界 XY 为 EnvQuery 构造的精确逆推导);NavMesh 模式从 tile blob 重建完整 dtNavMesh 复制品(SyncedReplicaMesh),此后引擎 navmesh 查询被禁用(FindPath 分派到 FindPathAStar/FindPathReplica)。洪泛用流内目标快照(SyncedGoalLocations)、绝不读本地 GoalActors(晚加入端 goal actor 尚未解析,读本地会分叉)。幂等(收窄):同版本补发仅在目标洪泛已完成(bSyncedFloodApplied)时跳过;未洪泛的同版本补发只在现行基底上重跑洪泛(复制品 PolyRef 保持稳定)。成功尾部置位 bSyncedSubstrate/版本/模式,并清 bIsBeginPlay/bIsGridDirty(查询就绪闸)。调用方:AMassBattleNetworkGameModeBase(服务器自导入)、AMassBattleNetworkGameStateBase(命令执行,全量/差分选择)、UMassBattleNetworkSubsystem(晚加入补发)。

Replaces the field's data with the imported substrate (both peers — the server re-imports its own export so every peer holds identical bytes). After validating magic/version and stream layout: Grid mode rebuilds both cell arrays from the stream's xNum/yNum/cellSize/origin/yaw (world XY derived as the exact inverse of EnvQuery's construction); NavMesh mode rebuilds the full dtNavMesh replica (SyncedReplicaMesh) from the tile blobs, and from then on engine navmesh queries are forbidden (FindPath dispatches to FindPathAStar/FindPathReplica). Flooding uses the in-stream goal snapshot (SyncedGoalLocations), never local GoalActors (late-join imports run before goal actors resolve; reading locals forked peers). Idempotent (narrowed): re-delivery of the same version skips only when the goal flood ran to completion (bSyncedFloodApplied); an unflooded same-version re-delivery re-runs JUST the flood on the standing substrate (replica PolyRefs stay stable). The success tail stamps bSyncedSubstrate/version/mode and clears bIsBeginPlay/bIsGridDirty (the queries-ready gate). Callers: AMassBattleNetworkGameModeBase (server self-import), AMassBattleNetworkGameStateBase (command execution, full/delta selection), UMassBattleNetworkSubsystem (late-join re-delivery).

在现行基底上应用差分流('FFD1',见 FlowFieldSync.h):Grid 格子就地更新;NavMesh tile 在复制品上经 removeTile/addTile 换版(全端同序 ⇒ PolyRef salt 历史一致)。补丁后以流内目标重跑洪泛并推进版本。前置校验:本地必须已同步且版本恰为差分的 BaseHash(不匹配返回 false——晚加入跳过差分/分叉链只能全量重发,由调用方决定)、位置/朝向 identity 不得漂移、魔数/版本必须匹配。由 AMassBattleNetworkGameStateBase 在命令执行处按命令类型选择全量或差分导入。

Applies a delta stream ('FFD1' — see FlowFieldSync.h) on top of the standing substrate: Grid cells are updated in place; NavMesh tiles are swapped via removeTile/addTile on the replica (identical order on every peer ⇒ identical PolyRef salt history). The stream-goal flood re-runs after the patch and the version advances. Preconditions: the local field must already be synced with the version EXACTLY matching the delta's BaseHash (a mismatch returns false — a late joiner that skipped deltas or a forked chain is repairable only by a full re-send, at the caller's discretion), the origin/yaw identity must not have drifted, and magic/version must match. AMassBattleNetworkGameStateBase picks full vs delta import per command type at command execution.

全量与差分两条导入路径共用的流内目标洪泛(差分路径加入时从 ImportSubstrateBytes 提取):只以 SyncedGoalLocations 洪泛,绝不读本地 GoalActors(导出快照在流里,构造性免竞态)。NavMesh 模式调 CalculateFlowField_NavMesh(复制品感知,以流内目标洪泛复制品);Grid 模式把流目标转网格坐标后调 CalculateFlowField,并做方向修改器对齐(地图摆放的修改器双端一致存在,无解析竞态)与基准方向存档。无目标场视为成功(洪泛不属基底契约);成功置 bSyncedFloodApplied。

The stream-goal flood shared by both import paths (full + delta; extracted from ImportSubstrateBytes when the delta path joined): floods ONLY from SyncedGoalLocations, never local GoalActors (the export-time snapshot lives in the stream — race-free by construction). NavMesh mode calls CalculateFlowField_NavMesh (replica-aware: floods the replica from the stream goals); Grid mode converts the stream goals to grid coords and calls CalculateFlowField, plus direction-modifier parity (map-placed modifiers exist identically on both peers — no resolution race) and base-direction archiving. A goal-less field counts as success (flooding is not part of the substrate contract); success stamps bSyncedFloodApplied.

同步 dtNavMesh 复制品上的确定性 A*(2026-09-09 NavMesh-A* 失步结论的产物):在相同字节上跑 Detour 自有 findPath + findStraightPath(走廊拉绳)——无引擎而有引擎级路径形状,全端构造确定。查询过滤器取导入的 SyncedAreaCosts 表(modifier 代价如同服务器引擎查询一样塑形 A*;NavArea_Null 多边形被阻断)。流程:双端点 findNearestPoly 投影(离网起终点与引擎对齐;投影到离网连接视为无效);bStraightFirst 时表面射线捷径(无墙命中且终点多边形与目标投影一致则直接两点返回);主路径走廊 A* + 拉绳,接受部分路径(镜像 FindPathNavMesh 的 AllowPartialPaths),首点替换为真实起点。每次调用栈上新建查询对象(KI-011:废除跨调用复用,构造性消灭跨端/跨线程残留状态)。Context 参数当前实现未使用(预留)。

Deterministic A* on the synced dtNavMesh replica (product of the 2026-09-09 NavMesh-A* desync conclusion): runs Detour's own findPath + findStraightPath (corridor string-pull) over identical bytes — engine-level path shapes without the engine, construction-deterministic on every peer. The query filter comes from the imported SyncedAreaCosts table (modifier costs shape the A* exactly like the server's engine queries; NavArea_Null polys are blocked). Flow: findNearestPoly projects both endpoints (engine-parity for off-mesh starts/goals; a con as the nearest poly counts as no valid spot); with bStraightFirst, a surface-raycast shortcut (no wall hit and the end poly matches the goal projection returns two points directly); the main path is corridor A* + string-pull, partial results accepted (mirroring FindPathNavMesh's AllowPartialPaths), first point replaced by the true start. A fresh stack query per call (KI-011: scratch-query reuse removed — kills all cross-call/cross-thread carry-over state by construction). The Context parameter is unused in the current implementation (reserved).

释放复制品网格(dtFreeNavMesh,连同 tile blob 由 DT_TILE_FREE_DATA 生命周期托管一并释放)并置空指针。调用时机:重导入、EndPlay、BeginDestroy(幂等——EndPlay 可能未跑,世界拆除时兜底)。

Frees the replica mesh (dtFreeNavMesh, releasing the tiles and their blobs via the DT_TILE_FREE_DATA lifecycle) and nulls the pointer. Called on re-import, EndPlay, and BeginDestroy (idempotent — EndPlay may not run during world teardown).

本场一切查询应使用的 dtNavMesh:同步 NavMesh 基底激活时为 SyncedReplicaMesh(可能为空——导入失败或未送达);否则解析引擎网格(GetRecastNavMesh 的 RecastMesh;世界无 navmesh 时为 nullptr)。

The dtNavMesh every query on this field should use: the SyncedReplicaMesh when a synced NavMesh substrate is active (may be null — import failed or not yet delivered); otherwise the engine mesh (GetRecastNavMesh's RecastMesh; nullptr when the world has no navmesh at all).

把世界点投影到活动网格(findNearestPoly + 隐式最近点,半范围为 UE 单位,UE→Recast 坐标转换)——同步时原生走复制品,否则走引擎网格(引擎投影的统一替代,兼容两种载体)。过滤器在同步 NavMesh 场取导入的 SyncedAreaCosts(全端一致;NavArea_Null 阻断)。传入 Context 时复用其 dtNavMeshQuery(网格变化时重新 init),否则栈上新建。范围内无多边形返回 false。

Projects a world point onto the active detour mesh (findNearestPoly + implicit closest point, half extents in UE units, UE→Recast axis conversion) — replica-native when synced, otherwise the engine mesh (a unified replacement for the engine projection, covering both carriers). The filter takes the imported SyncedAreaCosts on a synced NavMesh field (identical on every peer; NavArea_Null blocks). With a Context, its dtNavMeshQuery is reused (re-inited on mesh change); otherwise a stack query is built. Returns false when no poly is in range.

ImportSubstrateBytes 生效后为真(内联读 bSyncedSubstrate)——消费方可据此避开引擎查询。

True once ImportSubstrateBytes has been applied (inline read of bSyncedSubstrate) — consumers can avoid engine queries with it.

已应用基底版本(全量流体的 ContentHash,差分使其前进;0 = 从未同步)。BP 诊断用——跨端对比该值可发现分叉的版本链(哈希在 BP 侧截断为 int32,值域远够)。

The applied substrate version (the full stream's body ContentHash; deltas advance it; 0 = never synced). A BP diagnosis aid — comparing it across peers spots a forked version chain (the hash is truncated to int32 on the BP side, well within range).

统一寻路入口。已导入基底(bSyncedSubstrate)时引擎查询被禁用——NavMesh 同步场转发 FindPathReplica(在导入字节上本地计算),Grid 同步场转发 FindPathAStar;否则 NavMesh 模式转发 FindPathNavMesh,Grid 模式转发 FindPathAStar。

Unified pathfinding entry. With an imported substrate (bSyncedSubstrate) engine queries are forbidden — a synced NavMesh field forwards to FindPathReplica (computing locally on the imported bytes) and a synced Grid field to FindPathAStar; otherwise NavMesh mode forwards to FindPathNavMesh and Grid mode to FindPathAStar.

静态路径转向助手(简化版路径跟随:指向当前段,到达后推进)。流程:① 路径点不足时无路径——直接指向目标并置 bHasPath = false/bIsGoalNearEnd = true;② 钳制路径索引;③ 若 Agent 被推离当前段起点较远(3 × PathRadius),向后搜索最近的早期段并回退索引;④ 推进:当前目标点被越过(点积 < 0,与 UE PathFollowingComponent 的判定一致)或进入接受半径(终点用 AcceptanceRadius,中间点用 PathRadius)即推进,最多 5 次;⑤ 转向 = 指向当前段终点(GetSafeNormal2D),零方向时依次兜底段方向、目标方向;⑥ 更新 bIsCurrentNearPath(距当前段 ≤ 2 × PathRadius)与 bIsGoalNearEnd(目标距路径末点 ≤ AcceptanceRadius)。MoveSpeed/LookAheadDistance 当前未使用。

Static path-steering helper (simplified path following: point at the current segment, advance when reached). Flow: ① too few path points → no path: point straight at the goal with bHasPath = false/bIsGoalNearEnd = true; ② clamps the path index; ③ when the agent is pushed far from the current segment start (> 3 × PathRadius), searches backward for the closest earlier segment and rewinds; ④ advance: the current target counts as reached when passed (dot product < 0, matching UE's PathFollowingComponent check) or within the acceptance radius (final point uses AcceptanceRadius, intermediate points PathRadius), up to 5 iterations; ⑤ steering = direction to the current segment end (GetSafeNormal2D), falling back to the segment direction then the goal when zero; ⑥ updates bIsCurrentNearPath (within 2 × PathRadius of the current segment) and bIsGoalNearEnd (goal within AcceptanceRadius of the path's last point). MoveSpeed/LookAheadDistance are currently unused.

初始化面积成本上下文:bEnabled = bUseNavMeshAreaCosts,MaxMultiplier = MaxAreaCostMultiplier;关闭时保持默认(全 1.0)。开启时:① 从 NavMesh 的 64 个面积 ID 查面积类 CDO,取其 DefaultCost;② 应用 AreaCostOverrides(钳制 [0.1, 255])。供 Dijkstra 与可视化使用(>1000 视为不可通行,×100 惩罚)。

Initializes the area cost context: bEnabled = bUseNavMeshAreaCosts, MaxMultiplier = MaxAreaCostMultiplier; disabled keeps the defaults (all 1.0). When enabled: ① queries the NavMesh's 64 area IDs for the area class CDO and reads its DefaultCost; ② applies AreaCostOverrides (clamped to [0.1, 255]). Used by Dijkstra and visualization (costs > 1000 treated as impassable with a ×100 penalty).

编辑器调试:在 bDebugDrawAreaCosts 且 NavMesh 模式下,遍历 Detour 网格的地面多边形,对非默认成本(≠1.0)的多边形按成本梯度上色(绿 1.0 → 黄 5.0 → 红 10.0+)。注意当前实现只计算了颜色与中心点,未找到实际 DrawDebug 调用的完整代码路径。

Editor debug: with bDebugDrawAreaCosts in NavMesh mode, walks the Detour mesh's ground polygons and colors non-default-cost (≠1.0) polygons by a cost gradient (green 1.0 → yellow 5.0 → red 10.0+). Note the current implementation computes colors and centers but the full DrawDebug call path is not present.

异步 trace 完成回调(绑定到 DoneTraceDelegate):把结果写回 InitialCellsArray[CoordToIndex(NewCell.gridCoord)],加入 GridModifiedSet,递减 TraceRemaining;归零时执行 DoneAllTracesDelegate(推进异步更新的下一步)。

Async trace completion callback (bound to DoneTraceDelegate): writes the result back into InitialCellsArray[CoordToIndex(NewCell.gridCoord)], adds it to GridModifiedSet, and decrements TraceRemaining; at zero, fires DoneAllTracesDelegate (advancing the async update).

收集场景中的 NavLinkProxy 并建立 NavLinkCache:清空缓存;遍历所有 NavLinkProxy 的 PointLinks,把链接端点变换到世界后与 Detour 网格的 off-mesh 连接按端点距离匹配(50cm 容差,含反向匹配)得到链接 PolyRef;把两端投影到导航网格并验证为地面多边形,记录 LeftGroundPolyRef/RightGroundPolyRef;存入缓存并置 bNavLinkCacheInitialized = true。无代理时缓存直接标记为已初始化。

Collects NavLinkProxies from the scene and builds NavLinkCache: clears the cache; for every NavLinkProxy's PointLinks, transforms the link endpoints to world space and matches them against the Detour mesh's off-mesh connections by endpoint distance (50 cm tolerance, reversed matching included) to obtain the link poly ref; projects both ends onto the nav mesh, verifying ground polygons, recording LeftGroundPolyRef/RightGroundPolyRef; stores the entry and sets bNavLinkCacheInitialized = true. With no proxies, the cache is marked initialized immediately.

从缓存查询 NavLink 方向(无回退,找不到即失败):缓存未初始化 → CacheNotInitialized;PolyRef 为 0 → InvalidPolyRef;缓存无此条或无效 → NotFound;命中则填 OutData(方向/端点/来源名),并按查询点与端点的 3 米距离阈值置 bIsAtLeftEnd/bIsAtRightEnd,返回 Success。

Queries NavLink direction from the cache (no fallback — fails loudly): cache not initialized → CacheNotInitialized; poly ref 0 → InvalidPolyRef; entry missing or invalid → NotFound; on hit fills OutData (direction/endpoints/source name), sets bIsAtLeftEnd/bIsAtRightEnd by the 3 m distance threshold from the query point, and returns Success.

编辑器调试工具(头文件 UFUNCTION 已注释):校验缓存条目的 bIsValid 与来源代理有效性,统计有效/无效数量。当前实现只统计,无日志输出或其它动作。

Editor debug tool (UFUNCTION commented out in the header): validates each cache entry's bIsValid and source proxy validity, counting valid/invalid entries. The current implementation only counts — no logging or other action.

节点工厂:校验世界上下文与流场(无效返回 nullptr);创建动作对象,保存流场弱引用、MaxTicksToComplete 与 bFullRebuild,注册到 GameInstance;把流场的 DoneTraceDelegate 绑定到 UpdateCellMap、DoneAllTracesDelegate 绑定到本对象的 AsyncUpdateStep2。

Node factory: validates the world context and flow field (returns nullptr when invalid); creates the action, stores the flow field weak reference, MaxTicksToComplete and bFullRebuild, and registers with the game instance; binds the flow field's DoneTraceDelegate to UpdateCellMap and DoneAllTracesDelegate to this object's AsyncUpdateStep2.

节点启动:① MaxTicksToComplete > 0 时走同步预备——InitFlowField/GetGoalLocation,NavMesh 模式直接 AsyncUpdateStep2,Grid 模式按需收集修改器/建格/同步修改网格后进 Step2;② 否则走默认异步路径 AsyncUpdateStep1(下帧游戏线程执行预备)。

Node activation: ① with MaxTicksToComplete > 0, runs the synchronous prep — InitFlowField/GetGoalLocation; NavMesh mode goes straight to AsyncUpdateStep2; Grid mode collects modifiers/creates the grid/synchronously modifies it as needed, then Step2; ② otherwise the default async path runs AsyncUpdateStep1 (prep on the game thread next frame).

异步预备(游戏线程,下帧执行):InitFlowField/GetGoalLocation;NavMesh 模式直接 Step2;Grid 模式按需收集修改器/建格,非全量重建时走 ModifyGridAsync 发起异步 trace——TraceRemaining == 0(无 trace)时直接 Step2,否则等 DoneAllTracesDelegate。

Async prep (game thread, next frame): InitFlowField/GetGoalLocation; NavMesh mode goes straight to Step2; Grid mode collects modifiers / creates the grid as needed, and for non-full rebuilds runs ModifyGridAsync to launch async traces — with TraceRemaining == 0 (no traces) Step2 runs directly, otherwise it waits for DoneAllTracesDelegate.

计算与应用:① NavMesh 模式——游戏线程准备目标多边形与面积成本上下文,构造计算 lambda(调 CalculateNavMeshFlow,无 line trace)与应用 lambda(写回 NavMeshCellMap、存基准方向、套方向修改器、重建占位目标格、按开关重绘箭头、清 bIsBeginPlay、广播 OnCompleted);MaxTicksToComplete > 0 时 offload 线程池并订阅 OnSimulationTick,否则后台线程计算 + 游戏线程应用。② Grid 模式——捕获格数组/修改器/目标,计算 lambda(ModifyCost → CalculateFlowField → 存 BaseDirArray → ModifyFlowField)与应用 lambda(写回三个数组、按开关重绘、清标记、广播、销毁),分发同上。

Computation and application: ① NavMesh mode — the game thread prepares goal polygons and the area cost context, builds a calculate lambda (calls CalculateNavMeshFlow, no line trace) and an apply lambda (writes back NavMeshCellMap, stores base directions, applies direction modifiers, rebuilds the placeholder goal cell, redraws arrows per toggles, clears bIsBeginPlay, broadcasts OnCompleted); with MaxTicksToComplete > 0 it offloads to the thread pool and subscribes to OnSimulationTick, otherwise a background thread computes and the game thread applies. ② Grid mode — captures the cell arrays/modifiers/goals; the calculate lambda runs ModifyCost → CalculateFlowField → stores BaseDirArray → ModifyFlowField; the apply lambda writes back the three arrays, redraws per toggles, clears the marker, broadcasts and destroys; dispatch as above.

限 tick 模式下的模拟 tick 回调:递增 ElapsedTicks;流场失效则解绑、销毁;future 就绪则应用结果(与 ApplyTask 相同的写回逻辑)、解绑、重置 future、广播 OnCompleted 并销毁;未就绪但已达到 MaxTicksToComplete 时置 Context.bAbortStep = true 让宿主中止模拟步等待。

Simulation tick callback in tick-limited mode: increments ElapsedTicks; an invalid flow field unbinds and destroys; a ready future applies the result (same write-back logic as ApplyTask), unbinds, resets the future, broadcasts OnCompleted and destroys; when not ready but at MaxTicksToComplete, sets Context.bAbortStep = true so the host aborts the simulation step and waits.