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 常见问题速查表问题现象可能原因排查方法解决方案模型部分发黑三角形顶点顺序反了对比几何法线和顶点法线调用ReverseTriOrientationUV 错乱属性层索引未同步更新检查属性层元素数量重建属性层或手动映射布尔运算结果有洞共面判断失败检查容差设置量化顶点坐标后重试挤出侧面扭曲法线方向不一致检查面法线分布用面积加权平均法线简化后 UV 拉伸简化未保留 UV 边界检查简化参数启用 UV 边界保护内存持续增长快照未释放检查流水线事务确保成功后释放快照操作后 Mesh 不可见包围盒未更新检查BoundingBox调用UpdateBoundingBox提示这张表是我从过去半年的 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内部有大量动态数组如果拷贝后忘记释放内存会持续增长。我养成了用TUniquePtrFDynamicMesh3管理生命周期的习惯避免手动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 错位、拓扑断裂一眼就能看出来。