🔹 Overview | 概述

SurfaceAI is a surface-based navigation system for Unreal Engine 5.
It automatically samples points on static meshes, analyzes surface topology,
and builds navigation graphs that can be used for pathfinding, AI movement,
or large-screen visualization of 3D environments.

SurfaceAI 是一个专为虚幻引擎 5 设计的 基于表面的导航系统。
它能自动在静态网格上进行点采样、分析表面拓扑结构，
并生成可用于 寻路、AI移动 或 三维可视化系统 的导航图数据。

⚙️ Core Features | 核心功能1️⃣ Surface Sampling System

表面采样系统

• Automatically samples navigation points across multiple UStaticMeshComponents.

• Supports configurable grid step sizes (StepX, StepY, StepZ).

• Supports bounding box expansion and trace-based filtering to ensure surface precision.

• Points automatically adjust to stay at a fixed distance (TraceLength) from the surface.

➡️ 自动在多个静态网格上进行采样，
支持自定义步长（StepX, StepY, StepZ），
支持扩展采样边界与射线过滤，
并能自动调整点位置，保持与表面固定距离（TraceLength）。

2️⃣ Intelligent Node Filtering

智能点过滤机制

• Removes points inside meshes or redundant interior layers.

• Keeps only boundary, edge, and isolated points.

• Optionally filters points by normal direction (e.g. facing upward surfaces only).

➡️ 自动排除网格内部点与冗余点层，
仅保留边界、边缘或孤立点，
并可根据法线方向过滤（如仅保留朝上的表面）。

3️⃣ Normal & Surface Detection

法线与表面检测

• Extracts accurate vertex normals from mesh LOD data (StaticMeshVertexBuffer).

• Projects points onto the closest surface position.

• Ensures normals are consistent with mesh topology, even on curved or tilted surfaces.

➡️ 从网格 LOD 数据中提取精确的顶点法线，
自动计算每个点在网格表面的最近投影，
保证在复杂曲面或倾斜面上法线方向正确。

4️⃣ Graph Construction

导航图构建

• Builds node-to-node connectivity (Edges) based on spatial proximity.

• Supports configurable MergeDistance to control graph density.

• Performs collision checks to prevent links passing through meshes.

• Each node and edge is saved in a USurfaceNavGraph DataAsset.

➡️ 自动根据空间距离建立节点连通关系，
通过 MergeDistance 控制图的密度，
使用物理检测防止穿透网格，
并将结果保存为 USurfaceNavGraph 数据资产。

5️⃣ Pathfinding Support

寻路支持

• Includes built-in pathfinding via BFS / Dijkstra-style traversal.

• Returns full waypoint list between start and end positions.

• Ensures path stays on connected surface regions (no mesh penetration).

➡️ 内置基于 BFS / Dijkstra 的寻路算法，
能计算任意两点间可达路径，返回完整路径节点列表，
保证路径不会穿越网格内部。

6️⃣ Editor Integration

编辑器集成

• Fully integrated with Unreal Editor via an Editor Module.

• Provides one-click graph generation and visualization tools.

• Supports saving results as .uasset DataAssets (AutoGraph01.uasset).

• Automatically skips invalid (level-private) references when saving.

➡️ 深度集成到 Unreal 编辑器，支持一键生成与可视化，
可直接保存结果为 .uasset 数据资源，
并自动跳过无效（关卡内部）引用。

7️⃣ Visualization & Debugging

可视化与调试

• Visualizes all nodes and edges in 3D viewport.

• Customizable colors (NodeColor) and lifetime (DrawTime).

• Supports per-mesh graph isolation and debug overlays.

➡️ 在 3D 视口中可视化所有节点与边，
可自定义颜色与持续时间，
支持单独显示每个网格的导航节点与调试叠加。

8️⃣ Modular Data Design

模块化数据结构

• FSurfaceNavNode: stores position, surface point, normal, and source mesh info.

• FSurfaceNavEdge: stores node indices and path cost.

• USurfaceNavGraph: holds the entire graph, nodes + edges + parameters.

➡️ 模块化的数据结构设计：
FSurfaceNavNode 存储点信息与法线，
FSurfaceNavEdge 存储连线关系与代价，
USurfaceNavGraph 保存整个导航图及参数。