企业官网建设流程全解析

1. 项目缘起与整体设计思路

GeometryCore 这个项目，是我在连续做了三个 UE5 程序化建模工具之后，决定把散落在各个工程里的几何处理逻辑抽出来做成一个独立模块的产物。起因很直接：每次开新项目，只要涉及运行时改 Mesh，就得把之前写过的顶点操作、法线重算、UV 重映射、布尔运算这些代码重新抄一遍，抄到最后自己都分不清哪个版本是对的。与其继续复制粘贴，不如一次性做成一个可复用的几何处理引擎。

这个引擎要解决的核心问题，是让 UE5 里的 Mesh 操作从“编辑器里手动拖”变成“代码里可控可编程”。传统做法是美术在 DCC 工具里做好模型导入，运行时想改形状只能靠 Morph Target 或者骨骼动画，灵活性很差。而 GeometryCore 的目标是：给定一个FDynamicMesh3，我能在运行时对它做切割、合并、挤出、倒角、简化、平滑、重映射 UV、生成碰撞体，并且这些操作要能组合成流水线，像搭积木一样拼出复杂的几何效果。

为什么选FDynamicMesh3而不是UStaticMesh或UProceduralMeshComponent？这是整个项目最关键的选型决策。UStaticMesh是渲染资源，顶点数据在 GPU 侧，CPU 侧拿到的是一份只读的烘焙数据，改起来极其别扭。UProceduralMeshComponent虽然支持运行时改顶点，但它的数据结构是扁平的顶点数组加索引数组，没有边、没有面、没有邻接关系，做一次“找出所有共享某条边的三角形”这种操作就得自己建哈希表，写起来痛苦且容易出 bug。FDynamicMesh3是 UE5 Geometry Processing 模块里的核心数据结构，它维护了完整的顶点-边-三角形邻接关系，支持动态增删改，还自带属性层（Attribute Layer）来管理 UV、法线、颜色等通道。用它做几何算法，就像用带索引的数据库代替 CSV 文件，效率完全不是一个量级。

整个 GeometryCore 的架构分成四层。最底层是Mesh 数据层，封装FDynamicMesh3的创建、拷贝、序列化和属性管理。往上一层是基础算子层，实现单个几何操作，比如ExtrudeFaces、InsetFaces、BevelEdges、SimplifyMesh、Remesh这些。再往上是组合流水线层，把多个算子串成一条处理链，支持中间结果缓存和失败回滚。最顶层是蓝图暴露层，通过UBlueprintFunctionLibrary把常用操作暴露给蓝图，让不写 C++ 的同事也能用。

这个分层的好处是，算法逻辑和引擎耦合度低，单元测试好写。我可以在不启动编辑器的情况下，用纯 C++ 测试用例跑几百个 Mesh 操作，验证拓扑正确性。实测下来，这套结构让新算子的开发周期从平均两天缩短到半天，因为大部分时间花在算法本身，而不是跟引擎的数据结构搏斗。

提示：如果你只是想在编辑器里做静态建模，Geometry Script 插件已经够用了。GeometryCore 的价值在于运行时动态处理和批量流水线，这两点是编辑器工具覆盖不到的。

2. 核心数据结构与 FDynamicMesh3 实操要点

2.1 为什么 FDynamicMesh3 是几何处理的最优解

FDynamicMesh3的设计哲学是“以边为中心”。每个三角形由三条边组成，每条边连接两个顶点，边和三角形之间互相引用。这种结构让邻接查询变成 O(1) 操作：给定一个三角形 ID，能立刻拿到它的三条边；给定一条边，能立刻拿到它两侧的三角形。做几何算法时，这种邻接信息的获取速度直接决定了整体性能。

对比一下，如果用扁平的索引数组，想找“与三角形 A 共享顶点的所有三角形”，得遍历整个索引数组，复杂度 O(n)。而在FDynamicMesh3里，通过顶点到边的映射，再通过边到三角形的映射，两步就能拿到结果，复杂度 O(k)，k 是邻接三角形数量。对于一个十万面的 Mesh，前者可能要几毫秒，后者只要几微秒，差距是三个数量级。

FDynamicMesh3还支持属性层。默认情况下，顶点位置存在VertexPositions里，但 UV、法线、颜色这些是存在独立的属性层里的。属性层的设计很巧妙：它不直接绑定到顶点或三角形，而是绑定到“元素”（Element），元素可以是顶点、边、三角形或者角（Corner）。这种灵活性让同一个 Mesh 可以有多套 UV 布局，或者在不同区域用不同的材质，而不用复制整个 Mesh 数据。

2.2 创建与初始化 Mesh 的几种方式

实际项目里，Mesh 的来源五花八门，GeometryCore 需要支持多种初始化路径。最常见的是从UStaticMesh转换：调用UE::Geometry::CopyMeshFromStaticMesh，把烘焙好的渲染数据转成FDynamicMesh3。这个过程会丢失一些编辑器专有信息，但顶点、三角形、UV、法线这些核心数据都能保留。

第二种是从UProceduralMeshComponent转换。因为 ProceduralMesh 的数据是扁平的，转换时需要重建邻接关系，FDynamicMesh3提供了AppendVertex和AppendTriangle接口，但逐个添加效率很低。更好的做法是先用FDynamicMesh3::Reserve预分配空间，然后批量添加。我实测过，对于一个五万面的 Mesh，逐个添加要 200 多毫秒，预分配后批量添加只要 30 毫秒左右。

第三种是从零构建。比如做一个参数化的几何体，直接算好顶点坐标和三角形索引，然后一次性构建。这种场景下，要注意顶点顺序和法线朝向。FDynamicMesh3默认使用右手坐标系，三角形顶点按逆时针排列时法线朝外。如果顺序反了，法线会朝内，渲染出来就是黑的。我踩过这个坑，调了半天才发现是顶点顺序问题。

// 从零构建一个简单的四边形 FDynamicMesh3 Mesh; Mesh.EnableAttributes(); int32 V0 = Mesh.AppendVertex(FVector3d(0, 0, 0)); int32 V1 = Mesh.AppendVertex(FVector3d(100, 0, 0)); int32 V2 = Mesh.AppendVertex(FVector3d(100, 100, 0)); int32 V3 = Mesh.AppendVertex(FVector3d(0, 100, 0)); // 逆时针顺序，法线朝 +Z Mesh.AppendTriangle(V0, V1, V2); Mesh.AppendTriangle(V0, V2, V3);

2.3 属性层的管理与常见陷阱

属性层是FDynamicMesh3里最容易出问题的地方。默认情况下，EnableAttributes()会创建一个主属性层，包含 UV、法线、颜色等通道。但如果你在添加三角形之前没有设置好属性层的元素类型，后面再改就很麻烦。

举个例子，UV 属性可以绑定到顶点、角或三角形。绑定到顶点时，一个顶点只有一个 UV 坐标，适合连续曲面；绑定到角时，每个三角形的每个角都有独立 UV，适合有接缝的模型。如果你一开始用顶点绑定，后来发现需要接缝，就得重建整个属性层，所有 UV 数据都会丢失。我的经验是，对于程序化生成的 Mesh，默认用角绑定，虽然内存占用高一点，但灵活性最好，后期调整空间大。

另一个坑是属性层的索引映射。当你对 Mesh 做简化或重网格化时，顶点数量会变，属性层的索引也需要同步更新。FDynamicMesh3提供了一些工具函数来处理这种映射，但并不是所有算子都会自动维护属性层。比如SimplifyMesh默认会保留 UV，但如果你用的是自定义的简化算法，就得自己处理属性插值。我建议在流水线里加一个验证步骤，每次操作后检查属性层元素数量是否和 Mesh 元素数量匹配，不匹配就报错，避免错误累积到后面才暴露。

注意：FDynamicMesh3的拷贝是深拷贝，但属性层的拷贝需要显式调用CopyAttributes。如果你直接赋值 Mesh 对象，属性层可能不会正确复制，导致 UV 丢失。这个坑我踩过两次，现在养成了习惯，拷贝后立刻检查属性层。

3. 核心算子实现与流水线搭建

3.1 挤出、内插与倒角的参数计算

挤出（Extrude）是最常用的算子之一。给定一组面，沿法线方向移动一定距离，然后生成侧面连接原始边界和新边界。FDynamicMesh3没有直接的挤出函数，需要自己实现。核心步骤是：先找到选中面的边界边，然后为每条边界边创建一个新顶点，新顶点位置是原顶点沿面法线偏移的结果，最后用这些新顶点构建侧面三角形。

参数计算里最关键的是偏移方向。如果直接用面法线，对于非平面区域，相邻面的法线不同，挤出的侧面会扭曲。更好的做法是用顶点法线的平均值，或者用边界边的切向和面法线的叉积来算。我试过三种方案，最后发现对于大多数场景，用面法线的面积加权平均效果最稳，既不会过度平滑，也不会产生尖锐折角。

内插（Inset）是在面内部生成一个缩小的面，然后用四边形环连接原始边界。缩小的比例参数需要根据面的形状来调整。对于狭长面，固定比例会导致内插面退化成一条线。我的做法是计算面的内切圆半径，然后用内切圆半径乘以一个系数作为内插距离，这样无论面形状如何，内插面都能保持合理的面积。

倒角（Bevel）是最复杂的算子。它需要在边的两侧各生成一条新边，然后用四边形或三角形填充。倒角的宽度参数如果超过相邻面的最小边长，就会产生自交。我在实现时加了一个预检查：遍历所有选中边，计算每条边到相邻面其他边的最小距离，如果倒角宽度超过这个距离的一半，就自动钳制。这个钳制逻辑救了我很多次，否则用户输入一个大宽度，整个 Mesh 就炸了。

3.2 布尔运算的鲁棒性处理

布尔运算是几何处理里出了名的难做。两个 Mesh 求交、求并、求差，听起来简单，实际上要处理共面、退化三角形、数值精度等一堆问题。GeometryCore 的布尔运算基于 BSP 树实现，但直接套用经典算法在 UE5 里会碰到浮点精度问题。

我的解决方案是引入一个“容差层”。在布尔运算前，先把两个 Mesh 的顶点坐标量化到一定精度，比如 0.001 厘米。这样共面判断和交点计算就稳定多了。量化会损失一些精度，但对于大多数游戏场景，0.001 厘米的误差肉眼根本看不出来。量化后，再用 BSP 树做分割和重组，最后把结果顶点反量化回原始精度范围。

另一个关键是处理退化三角形。布尔运算会产生面积接近零的三角形，这些三角形如果不清理，后续的法线计算和渲染都会出问题。我在流水线里加了一个RemoveDegenerateTriangles步骤，阈值设为 1e-6 平方厘米。实测下来，这个步骤能去掉 90% 以上的退化面，剩下的用CompactMesh合并重复顶点后基本就干净了。

3.3 流水线的组合与回滚机制

单个算子再强，也架不住复杂需求。比如“先简化，再平滑，然后沿法线挤出，最后生成碰撞体”，这一串操作如果中间某步失败，整个 Mesh 就废了。所以 GeometryCore 的流水线层设计了事务机制：每一步操作前，先拷贝一份当前 Mesh 的快照；操作成功后，丢弃快照；操作失败，从快照恢复。

快照的代价是内存和拷贝时间。对于一个十万面的 Mesh，一次深拷贝大概 5 毫秒，内存占用 10 MB 左右。如果流水线有十步，峰值内存可能到 100 MB。对于运行时场景，这个开销有点大。我的优化策略是：只对可能失败的步骤做快照，比如布尔运算和倒角；对于挤出、内插这种几乎不会失败的步骤，跳过快照。另外，快照可以用增量方式，只记录被修改的元素，而不是整个 Mesh。这个优化我还在做，目前用全量快照加步骤级开关，已经能满足大部分需求。

流水线的另一个设计点是参数传递。每个算子有自己的参数结构体，流水线需要把这些参数序列化，方便保存和加载。我用FInstancedStruct来存参数，这样新增算子时不用改流水线的核心代码，只要注册新的参数类型就行。这个设计让流水线的扩展性好了很多，现在加一个新算子，从写算法到接入流水线，半天就能搞定。

4. 常见问题排查与性能优化实录

4.1 法线翻转与光照异常

法线问题是最高频的 bug。表现是模型一部分亮一部分暗，或者整体发黑。原因通常有三个：三角形顶点顺序反了、法线没有重算、法线属性层绑定错误。

排查顺序应该是：先检查三角形顶点顺序。在FDynamicMesh3里，可以用GetTriNormal拿到三角形的几何法线，然后和顶点法线属性对比。如果几何法线和顶点法线方向相反，说明顶点顺序反了。修复方法是调用ReverseTriOrientation翻转三角形。

如果顶点顺序没问题，但光照还是不对，就检查法线属性层。FDynamicMesh3的法线可以存在顶点上，也可以存在角上。如果存在角上，但渲染时按顶点读取，就会读到错误的数据。用HasVertexNormals和HasTriangleNormals检查属性层类型，确保和渲染管线的预期一致。

最后一个可能是法线没有重算。做了挤出或布尔运算后，新生成的三角形法线可能是零向量。调用RecomputeNormals可以修复，但要注意这个函数会覆盖已有的法线数据。如果模型有自定义的平滑组，重算会破坏平滑效果。我的做法是：只在检测到零法线或法线长度异常时才重算，否则保留原始法线。

4.2 性能瓶颈定位与优化

GeometryCore 的性能瓶颈通常出现在三个地方：邻接查询、属性层操作和内存分配。

邻接查询慢，往往是因为用了错误的 API。比如GetVtxTriangles会返回一个数组，如果在一个循环里反复调用，每次都会分配新数组。更好的做法是用GetVtxTriangles的迭代器版本，或者预先分配一个数组复用。我实测过，在一个万次循环里，复用数组比每次新建数组快 40%。

属性层操作慢，通常是因为频繁的GetAttribute和SetAttribute调用。这些函数内部有虚函数分发和边界检查，单次调用不慢，但百万次调用就很可观。优化方法是批量操作：先用GetAttribute拿到属性层的原始指针，然后直接读写内存，最后再标记属性层为脏。这个优化能把属性操作的速度提升五到十倍。

内存分配是隐藏的性能杀手。FDynamicMesh3在增删元素时会动态调整内部数组，频繁的增删会导致大量内存分配和拷贝。解决方案是预分配：在开始操作前，用Reserve预留足够的顶点、边、三角形空间。预留多少？我的经验是，对于挤出操作，预留原始面数的两倍；对于布尔运算，预留两个 Mesh 面数之和的三倍。预留多了浪费内存，预留少了会触发扩容，扩容的代价比多预留大得多。

4.3 常见问题速查表

提示：这张表是我从过去半年的 bug 记录里整理出来的，覆盖了 80% 以上的常见问题。遇到新问题时，先查表，再调试，能省不少时间。

5. 与 Geometry Script 的协作与边界划分

5.1 Geometry Script 能做什么，不能做什么

Geometry Script 是 UE5 官方提供的蓝图几何脚本库，封装了大量常用操作，比如ApplyMeshBoolean、ApplyMeshExtrude、ApplyMeshRemesh等。对于快速原型和简单工具，Geometry Script 完全够用，而且不用写 C++，蓝图里拖几个节点就能跑。

但 Geometry Script 的局限也很明显。第一，它的算子粒度比较粗，很多参数不可调。比如布尔运算的容差是固定的，遇到特殊模型容易失败。第二，它不支持自定义算子。如果你想实现一个特殊的倒角算法，Geometry Script 没有扩展点，只能绕过去用 C++ 重写整个流程。第三，它的性能优化空间有限。蓝图节点的开销比 C++ 函数调用大，对于大规模 Mesh 处理，差距很明显。

GeometryCore 的定位不是替代 Geometry Script，而是补充它的不足。简单操作直接用 Geometry Script，快速出效果；复杂操作或者需要精细控制的场景，用 GeometryCore。两者可以混用：先用 Geometry Script 做粗加工，导出FDynamicMesh3，再用 GeometryCore 做精加工，最后转回UStaticMesh或UProceduralMeshComponent。

5.2 数据在两者之间的流转

FDynamicMesh3是 Geometry Script 和 GeometryCore 之间的通用货币。Geometry Script 的节点内部也是操作FDynamicMesh3，只是外面包了一层蓝图接口。所以从 Geometry Script 拿到FDynamicMesh3很简单，用GetDynamicMesh节点就行。反过来，把FDynamicMesh3传给 Geometry Script，用SetDynamicMesh节点。

流转过程中要注意属性层的兼容性。Geometry Script 默认使用角绑定的 UV 和法线，如果你的 GeometryCore 算子用了顶点绑定，传过去可能会出问题。我的做法是统一用角绑定，在 GeometryCore 的输入输出接口里做一次转换，确保两边一致。

另一个注意点是坐标系。Geometry Script 和 GeometryCore 都用 UE 的左手坐标系，但有些 DCC 工具导出的是右手坐标系，导入时已经转过了，不用重复转。我遇到过一个问题：从外部文件加载的 Mesh 在 Geometry Script 里显示正常，但传到 GeometryCore 后法线反了。查了半天发现是加载时做了一次坐标系转换，GeometryCore 又做了一次，负负得正，反而错了。后来在接口层加了一个标志位，明确标记是否已经转换过，问题就解决了。

5.3 混合流水线的设计模式

实际项目里，我常用的模式是“Geometry Script 粗加工 + GeometryCore 精加工 + Geometry Script 输出”。比如做一个程序化建筑生成器：先用 Geometry Script 的AppendBox生成基本体块，然后用 GeometryCore 做布尔挖洞和倒角，最后用 Geometry Script 的SetDynamicMesh转回UStaticMesh并生成碰撞。

这种混合模式的好处是各取所长。Geometry Script 的基本体生成和最终输出很成熟，不用自己写；GeometryCore 在中间做精细控制，弥补 Geometry Script 的不足。坏处是数据转换有开销，每次进出都要拷贝一次 Mesh。对于实时生成，这个开销可能成为瓶颈。我的优化是尽量减少转换次数，把多个 GeometryCore 操作串成一条流水线，只在流水线两端做转换。

注意：Geometry Script 的SetDynamicMesh会触发渲染资源重建，这个操作比较重。如果每帧都调用，帧率会掉得很厉害。我的做法是攒够一批修改再统一提交，或者用UProceduralMeshComponent做中间层，避免频繁重建UStaticMesh。

6. 实际项目中的落地经验

6.1 程序化地形雕刻工具

第一个落地项目是一个程序化地形雕刻工具。用户在地形上画一笔，工具根据笔刷形状和强度，对地形 Mesh 做局部挤出或凹陷。这个需求用传统的高度图做不了，因为高度图只能上下移动顶点，做不了悬崖和洞穴。用 GeometryCore 就灵活多了：笔刷覆盖的面先做细分，然后沿笔刷法线挤出，边缘做平滑过渡。

实现时最大的挑战是性能。地形 Mesh 有几十万面，每次笔刷操作都要在几百毫秒内完成，否则用户感觉卡顿。我的优化策略是空间分区：把地形分成 64x64 的块，每块独立处理。笔刷只影响相邻的几块，其他块不动。这样每次操作只处理几千面，速度就上来了。另外，细分和挤出用多线程并行，进一步压缩时间。最终实测，单次笔刷操作在 50 毫秒以内，交互很流畅。

6.2 运行时建筑破坏系统

第二个项目是运行时建筑破坏。玩家用武器打墙，墙上出现弹孔和裂缝，打多了整面墙碎掉。这个需求的核心是布尔运算和碎片生成。弹孔用圆柱体做布尔差，裂缝用平面切割，整面墙碎掉时用 Voronoi 分割生成碎片。

布尔运算的鲁棒性在这里至关重要。墙的 Mesh 有内外两层，中间是空的，布尔运算时经常把内外层搞混。我的解决方案是先把墙的 Mesh 做一次CompactMesh，合并重复顶点，确保拓扑干净。然后布尔运算前，检查两个 Mesh 的包围盒是否相交，不相交直接跳过，省时间。碎片生成用 Voronoi 图，每个碎片是一个凸包，用FDynamicMesh3的ConvexHull算法生成。碎片数量控制在 20 到 50 之间，太多会卡，太少效果不好。

6.3 参数化家具配置器

第三个项目是参数化家具配置器。用户选一个沙发款式，调整尺寸、颜色、材质，实时看到 3D 预览。这个需求的关键是参数化建模：沙发的每个部件（座垫、靠背、扶手、腿）都是参数化生成的，尺寸变化时 Mesh 要跟着变。

用 GeometryCore 做这个很合适。每个部件是一个独立的FDynamicMesh3，参数变化时重新生成对应的部件，然后合并成一个完整的沙发 Mesh。合并用AppendMesh，注意属性层的合并：不同部件的 UV 和材质要正确映射到合并后的 Mesh 上。我的做法是给每个部件分配一个材质 ID，合并时把材质 ID 写入三角形的属性层，渲染时根据材质 ID 选择不同的材质。

这个项目的性能要求不高，因为家具面数少，几千面而已。但用户体验要求高：调整参数时不能有卡顿，预览要实时更新。我的优化是缓存：参数没变的部件不重新生成，只重新生成变化的部件。比如只调颜色，那所有部件的几何都不变，只更新材质属性。这样大部分操作都是毫秒级完成。

6.4 踩过的坑与经验总结

第一个坑是浮点精度。不同平台的浮点精度可能不一样，PC 上跑得好好的算法，打包到移动端就出问题。我的解决方案是统一用double做几何计算，只在最后输出时转成float。FDynamicMesh3默认用double存顶点位置，这个设计很明智，省了我很多事。

第二个坑是内存泄漏。FDynamicMesh3内部有大量动态数组，如果拷贝后忘记释放，内存会持续增长。我养成了用TUniquePtr<FDynamicMesh3>管理生命周期的习惯，避免手动delete。另外，流水线的快照也要及时释放，我加了一个定时清理机制，超过一定时间的快照自动回收。

第三个坑是线程安全。FDynamicMesh3不是线程安全的，多线程同时读写同一个 Mesh 会崩溃。我的做法是每个线程操作自己的 Mesh 副本，最后在主线程合并。合并时要注意顺序，不同线程的修改可能有冲突，需要设计好合并策略。对于独立区域的修改，直接AppendMesh就行；对于重叠区域的修改，得用更复杂的合并逻辑，我目前是用锁串行化重叠区域的操作，简单但有效。

第四个坑是版本兼容。UE5 的不同小版本之间，Geometry Processing 模块的 API 可能有变化。比如FDynamicMesh3的某个函数签名改了，或者某个枚举值变了。我的应对策略是封装一层适配层，把版本相关的代码隔离出来，升级引擎时只改适配层，不动核心算法。这个策略在从 UE5.1 升到 UE5.3 时救了我，只改了几十行适配代码，核心的几千行算法一行没动。

提示：如果你打算在项目里重度使用 GeometryCore，建议从第一天就建立单元测试。几何算法的 bug 很隐蔽，肉眼看不出来，但测试用例能抓到。我写了 200 多个测试用例，覆盖了各种边界情况，每次改代码跑一遍，心里踏实很多。

7. 后续扩展方向与个人体会

GeometryCore 目前覆盖了大部分常用几何操作，但还有几个方向值得继续做。一个是 GPU 加速，把部分算子移到 Compute Shader 里，利用 GPU 的并行能力处理大规模 Mesh。另一个是机器学习辅助的几何处理，比如用神经网络做 Mesh 简化或修复，在保持视觉质量的前提下减少面数。还有一个是更完善的属性层系统，支持自定义属性通道，让用户能存任意数据在 Mesh 上。

我个人在实际操作中的体会是，几何处理这件事，算法本身只占三成，七成是工程问题：数据结构选型、内存管理、线程安全、版本兼容、性能优化。很多教程只讲算法，不讲工程，导致照着做出来的东西跑得慢、容易崩、不好维护。GeometryCore 的价值就在于把这些工程问题都处理好了，让使用者能专注于业务逻辑，而不是跟底层细节搏斗。

最后分享一个小技巧：如果你在调试几何算法时遇到诡异的结果，先把 Mesh 导出成 OBJ 文件，用 MeshLab 或 Blender 打开看看。可视化能帮你快速定位问题，比在代码里打印顶点坐标高效得多。我很多次都是靠这个方法发现问题的，比如法线翻转、UV 错位、拓扑断裂，一眼就能看出来。