WalkingSurface 优化实现逻辑

00一句话总览与图集

WalkingSurface 的核心思路是：把静态可走地形的几何信息在 Editor 里离线烘焙成紧凑的只读结构，运行时用一次缓存友好的数据结构查询替代 UE 的 ComponentSweepMulti 物理扫掠。收益来自"预计算 + 缓存局部性 + 早退剪枝"，代价是必须严格界定"什么时候这个结果可信"，不可信就回退 UE。

图集索引

01烘焙侧：数据从哪来

运行时所有"快"都建立在 Editor 期的离线预计算上。烘焙器把场景中符合 Profile 的静态几何转成可查询的 Patch / Tile，并额外产出精度块与水平线索。图 10 / 图 11 / 图 12 与动图 7 先给出烘焙产物的空间几何形态（俯视与剖面，含线索生成），图 8 与动图 5 给出完整流水线，图 9 与动图 6（第 5 章）展开线索的运行时判定。

1.1 数据流

FWalkingSurfaceBuilder::BuildFull / BuildIncremental   ← EditorModule 绑定 GetBuildEntry() delegate
  └─ FromDataActor（拉取 Build_* 设置）
       └─ FWalkingSurfaceBaker::Bake(World, DataActor)         ★ 主烘焙，两阶段分桶
            ├─ 轮1 MergeOnly：三角面采集 → 可走面过滤 → 建全量平面池
            ├─ 轮2a ToStepA3 → 全局复判 → 轮2b AfterStepA3
            ├─ Grid 20cm / Tile 3200cm（32m，160×160 格）
            ├─ 边界：BoundarySimplify / WallEdgeAligner / ObstacleEdgeBake
            └─ CompactWallEdges → FinishBuild
                 ├─ Horizontal::BuildPatchPrecision → 精度块 + 水平线索
                 ├─ RunPostBakeFindFloorValidation
                 └─ MarkPackageDirty（随 .uasset 保存）
            ↓ 落盘（kBuildVersion = 13 / kPrecisionLayoutVersion = 18）
  AWalkingSurfaceData（Patches + Tiles + Precision + Clues）
            ↓ Runtime Build
  FWSHotArena（见第 2 章）

1.2 关键产物

版本与数据模型：kBuildVersion = 13（v6 起 Tile 由 16m 改为 32m，需重 Bake）、kPrecisionLayoutVersion = 18（精度块独立布局版本，旧精度块整块跳过而 Patches/Tiles 照常读取）。数据模型是平面片（FPlane 拟合平面 + int32 世界 cm 的 XY 顶点），不是栅格高度图；边界为 Boundaries[0] = Outer(CCW) + 几何洞。量化 0.5cm，无 LOD、无通用压缩。注意 Runtime.h:32 注释里的「1600cm / 16m」是 v6 之前的旧描述，实际常量为 3200cm（见第 6 章「注释漂移」）。

BlockEdge 的两代语义（容易混淆）：v5–v12 的 FGroundPatch::BlockEdges 由「Block cell 净空轮廓」派生，专供已退役的 ProbeForward / FEdgePrim，v13 已删除；当前生产形态的「G1 几何驱动重设计」是 WalkingSurfaceObstacleEdgeBake 的 FBlockEdge（直接取自真实非可走碰撞面的真实 Z 区间），再收敛为烘焙线索 FGroundClue + FGroundClueNode BVH。G1 的烘焙阶段：B1 采集 N.z < 0.71 的非可站立面（含朝下面）→ B2 面合并 → B3 足迹投影（真实 Z 区间 / 朝外法线，无栅格拉直）→ B4 可达性裁剪（唯一剔除规则）→ B5 共线合并 → B6 新结构 + 版本升级（01a-blockedge-audit.md:73-89）。

1.3 增量与重建

Editor 侧还有 DirtyTileTracker / GridBoundaryRebuild / BakerIncremental 支撑"只重建脏 tile"，以及 Stepwise 分步烘焙、CoplanarMerge 共面合并（夹角容差 5°）、PatchAssemble 组装。烘焙侧还有 Stepwise 分步（单步已删，仅合并模拟）、DirtyTileTracker 的 ClosureMask 增量闭包、Co-planarMerge 共面合并（夹角容差 5°）、PatchAssemble 组装。这些不影响运行时查询语义，但决定了重 Bake 后旧 handler 如何失效：Runtime 用 BuildGeneration_ 代际号让 per-agent 缓存自动作废（QueryTypes.h:56），旧 handler 的 sweep 回退、原 FindFloor 继续用一致快照（MoveInterface.h:59-62）。

02热数据：为缓存行而设计

这是整个优化最"硬核"的部分：所有数据结构都围绕减少 cache miss 与指针追踪设计。目标是把逐帧查询从"多次散列 + 多次 scatter 读取"变成"一次连续内存上的顺序访问"。

2.1 一次连续分配（FWSHotArena）

// WalkingSurfaceRuntime.h:303-335（节选）
struct FWSHotArena
{
    uint8* Ptr = nullptr;  SIZE_T Size = 0, Used = 0;  bool bLargePages = false;
    void Allocate(SIZE_T Bytes, bool bTryLargePages);   // Windows: MEM_LARGE_PAGES，失败回退 64B 对齐
};
// 布局：[稠密热表][tile0 QueryBVH | tile0 凸块 blob][tile1 ...]  ← 一次分配，无拷贝

不可拷贝（内部视图指针指向本 arena），move-only。大页减少 TLB miss；连续布局让相邻 tile 的热数据物理相邻。

2.2 三条缓存行级优化

2.3 热路径零浮点（FWSInlinePoly）

// Runtime.h:91-108
struct FWSInlinePoly
{
    TArray<FIntPoint, TInlineAllocator<16>> Verts;  // int32 世界 cm（8B/顶点，原 double 16B）
    FIntPoint Center;  int64 R2;                     // 包围圆半径平方，早退用
    TArray<int64, TInlineAllocator<16>> EdgeSlopeX; // ((V[i].X-V[i-1].X)<<20)/(V[i].Y-V[i-1].Y)
};
// 量化误差 ≤ 0.5cm ≪ 烘焙 20cm grid；射线法全程 int32/int64，热路径无浮点

≤16 顶点内联存储，消除堆指针追踪的 cache miss；平面系数在 Build 期一次性折算为 A=−X/Z, B=−Y/Z, C=−W/Z，查询期只做 float 乘加、无 double、无除法，法线命中时现算一次（Runtime.h:110-120）。

2.4 索引与缓存

• 稠密 tile 索引：DenseTileIndex_ 规则网格直接寻址替代 TMap 哈希；TileIndex_ 仅作覆盖范围过大时的兜底（Runtime.h:602-610）。线索同理有扁平网格 ClueTileGrid_，无哈希。
• per-agent 查询缓存：FWalkingSurfaceQueryCache { LastTile, LastPatch, Generation }（QueryTypes.h:52-63）。Runtime 本体无 mutable 成员、无 agent 状态，因此查询可多线程并发；hint 短路失败自动回退完整路径，几何验证保证正确性。
• 查询预热：WarmupQueryData(Center, FootRadius)（Runtime.h:504-515）把足迹覆盖 tile 批量预取至 L1/L2，把串行 miss 转成并行加载。源码注释也诚实指出：数据预取无法消除 I-cache/BTB 的逐帧首次调用冷启动税，那是实测中耗时的主体。

03FindFloor 查询链

FindFloor 用世界 XY 定位到一个 Tile，再在 4-ary BVH 里剪枝出候选凸块，最后用平面解析式求 Z——全程没有物理 sweep、没有 double 除法。

3.1 两种查询模型

3.2 回退契约

3.3 精度消费三路径

EPrecisionPath（Runtime.h:381-393）：B3Only（逐顶点线性扫，仅作开销参照）/ Reference（B5 慢路径，逐顶点取偏差与模型偏差界）/ Fast（B5 槽位预展开，O(1) 取值，判定结果与 Reference 逐位一致）。默认 Fast——这是"精度不降、查询变 O(1)"的典型手法。

04Capsule FindFloor：Zsweep 与双点分离

要让 WS 的地面结果能直接透传给 CMC 消费，必须复刻 UE 胶囊 sweep 的几何语义，而不只是"采样一个地面高度"。

// WalkingSurfaceQueryTypes.h:16-40（字段语义）+ Runtime.h:481-489（Capsule 模式）
Zplane  = A·x + B·y + C                    // 拟合平面
N       = normalize(−A, −B, 1)
Zsweep  = Zplane + R·(|N| − 1)            // 胶囊底部触地时的底部 Z（内部择优基准）
Location.Z    = Zsweep + AgentHalfHeight − ShrinkHeight
ImpactPoint.Z = Zimpact = Zplane + R·(secθ − cosθ)  ⟺ Zsweep + R·(1 − cosθ)
ShrinkHeight  = max(AgentHalfHeight − AgentRadius, 0) × 0.1f   // 对齐 UE ComputeFloorDist 的 ShrinkScale=0.9

此外 FWalkingSurfaceFindFloorParams（QueryTypes.h:143-161）提供 bMatchUEImpactNormal：命中法线不可站立时按 UE FindMostOpposingFace 口径改取接触点附近最平的 patch 法线（停位不变）。GP CMC 走 IsAuthoritativeFloor 采信规则，保持 false。

05SweepHorizontal：只读查询替代物理扫掠

这是"优化实现"的主角，也是旧设计中 ProbeForward 的当前等价物。只读复用 QueryBVH / ConvexBlob + 精度槽位 + 烘焙线索，不调用 FindFloor、不改 Z，返回 Clear / Hit / Fallback 三态。

5.1 求解链（Runtime.h:526-534）

5.2 结果与回退类型

// WalkingSurfaceQueryTypes.h:163-194
enum class EWalkingSurfaceSweepResult : uint8 { Clear, Hit, Fallback };
enum class EWalkingSurfaceSweepFallback : uint8 {
    None, MissingData, InvalidInput, OutsideCoverage,
    VerticalSurface,        // 前方触到竖直阻挡的接触边（墙脚）
    UncollectedSurface,     // 台阶侧面、陡坡、碎石等 patch 未表达的静态几何
    SmallTriangle, StepA3Pruned, CoveredPruned, GridExcluded, UnsupportedGeometry,
    NoGroundSupport,        // 起点悬空 / 离开可走面
    InitialOverlap,         // 起点已与地面模型重叠
    OuterBoundaryContact,   // 首命中落在 patch 外边 / 顶点上
    PrecisionBudget, RoundShape, BudgetExceeded
};

FWalkingSurfaceSweepHit（QueryTypes.h:196-215）字段与 UE FHitResult 同口径：Time / Distance / Location / ImpactPoint / Normal / ImpactNormal / bBlockingHit / bStartPenetrating。但不含 Actor / Component / PhysMaterial / FaceIndex——上层若需要这些元数据，必须回退 UE。

5.3 对外接口

FWalkingSurfaceMove（MoveInterface.h:67-128）是纯静态工具类；FWalkingSurfaceMoveHandler 是 move-only 的不透明句柄，内部独占 Runtime 共享引用、agent 参数缓存与 per-agent 查询缓存。公开方法：Register / Unregister / UpdateAgentShape / SetFindFloorParams / FindFloor / HasSweepData / GetSweepCollisionFilter / SweepHorizontal / SweepHorizontalWithFallback。

06MoveAlongFloor：单步迭代（已退役的旧设计）

本章是历史方案，不是当前生产实现。当前代码中 MoveAlongFloor 已退役，仅剩 EWalkingSurfaceMoveResult 枚举与 StepLength / MinProgressEps 配置残留；其「沿地面走一段」的职责由 SweepHorizontal + GP CMC 的落位逻辑承担（见第 5、8 章）。保留本章是为了说明方案演进与迭代常量的来龙去脉。

以下常量在当前代码中仍定义于 FWalkingSurfaceRuntimeConfig，但已无对应的 MoveAlongFloor 实现消费，属配置残留。

// WalkingSurfaceTypes.h:23-95 + Runtime.h:35-53
kGridCellSize        = 20.f;    // 烘焙栅格单格边长（cm），全局对齐
kTileWorldSizeX/Y    = 3200.f;  // 32m；v6 起由 16m 改为 32m（需重 Bake）
kTileGridSizeX/Y     = 160;     // 每 tile 160×160 格
StepLength           = 100.f;   // MoveAlongFloor 迭代步长（1m）
MinProgressEps       = 1.f;     // 单步允许位移 < 1cm 视为探测失败
kCollectSlopeCos     = 0.015f;  // ≈89.1° 采集阈值
kStandableSlopeCos   = 0.71f;   // 可站立法线余弦
kBuildVersion = 13;  kPrecisionLayoutVersion = 18;
kMaxSweepLengthCm    = 256.f;  // Runtime.cpp:42-43 单次水平扫掠位移上限

专题 01-clarify.md 关键事实 #6 描述的旧设计：MoveAlongFloor 每步 = FindFloor 锚定 → ProbeForward 探测（圆柱中心 = 地面 + 半高）→ 允许位移 < MinProgressEps(1cm) 判失败 → 提交 XY → 终点再 FindFloor 锚定保证贴地；3P 外推每帧约 10cm ≪ StepLength 100cm，因此单次迭代；无滑墙、只截断，与 3P 现状行为同构。

EWalkingSurfaceMoveResult（QueryTypes.h:65-71）：Completed（走完全程）/ Partial（被阻挡，OutNewLocation 为最远可达点）/ Failed（起步即失败，原地）。

07采信边界与回退

优化的成败不在"查得快"，而在"知道什么时候不能信"。两道闸门：FindFloor 的 IsAuthoritativeFloor 与 SweepHorizontal 的 FallbackReason。

// WalkingSurfaceQueryTypes.h:95-127
constexpr float kFloorWalkableNormalMargin = 0.02f;
constexpr float kFloorTrustMinDist         = 1.8f;
constexpr float kFloorTrustMaxDist         = 2.5f;
FORCEINLINE bool IsAuthoritativeFloor(const FVector& HitNormal, float FloorDist, float WalkableFloorZ,
                                      float TrustMinDist = 1.8f, float TrustMaxDist = 2.5f)
{
    return HitNormal.Z >= WalkableFloorZ + 0.02f
        && FloorDist >= TrustMinDist && FloorDist <= TrustMaxDist;
}

为什么是 1.8~2.5：UE 的 AdjustFloorHeight 把稳态 FloorDist 维持在 [MIN_FLOOR_DIST 1.9, MAX_FLOOR_DIST 2.4]，两端各放宽 0.1cm 浮点余量。稳态贴地时 UE 不做位移，WS 与 UE 等价；区间外（上坡/下台阶/下坡过渡帧）CMС 本来就要做 AdjustFloorHeight 物理 sweep，回退只增加同量级一次查询，且避免 WS 因看不到立面/陡坡而"悬停在坡上行走"或"停位偏高"。

7.1 GP CMC 里的实际采信/回退

08GP CMC 生产接入

专题 README 里"未接生产 GP"的结论已经过时：GPCharacterMovementComponent.cpp 里已经落地了完整接入，只是 CVar 默认 0（关闭），处于可随时灰度/回退的状态。

8.1 接入点

NewSimulateMovement → MoveSmooth → (deferred scope 内唯一一次带 sweep 的移动)
  └─ if (!SimProxyMoveSmoothSweep_WalkingSurface(Delta, Hit))     // :11641
        SimProxyMoveSmoothSweepUE(Delta, MoveQuat, Hit);           // UE 路径

// 另一条独立接入（地面检测）：
FindFloor_WalkingSurface(CapsuleLocation, DownDist, OutFloorResult, SweepRadius)  // :11825
  ├─ EnsureWalkingSurfaceHandler() → FWalkingSurfaceMove::Register(..., Capsule)   // :11761-11789
  ├─ FWalkingSurfaceMove::FindFloor(*Handler, WSStart, WSHit, WSDownDist)          // :11884
  └─ IsAuthoritativeFloor(...) → 不权威则回退物理                                  // :11927

8.2 CVar 矩阵（GP CMC :265-368）

8.3 统计与观测

FWalkingSurfaceSweepRuntimeStats（GP CMC :11254-11276）累计 Calls / WSMove / UEMove / NonHorizontal / Incompatible / HoverRelaxed / HoverClear / HitConsumed / HitRejected 等，控制台命令 gp.Movement.WalkingSurfaceHorizontalSweep.Stats 打印耗时直方图。Runtime 侧另有 FSweepStats（SupportNodes / Convex / GapSkipped / Sweeps / NearMiss / BudgetHit）与 FClueQueryStats（Nodes / Candidates / PlanePruned / Exact / HitTile）用于开销归因（Runtime.h:415-425）。

09优化前后与实测

收益不是"WS 查询比一次 sweep 快多少"这么简单，而是净收益 = 干净帧占比 × (Sweep − WS 查询) − 回退帧占比 × WS 查询，还要扣掉 I-cache 冷启动税。

9.1 两条路径对照

9.2 专题实测结论（3p-movesmooth-sweep-skip）

10风险台账与当前状态

11代码索引与常量