企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

引言：为什么需要 TorusMesh

TorusMesh（环面网格，即甜甜圈形状）是 Godot Engine 官方文档中提供的内置**原始网格（PrimitiveMesh）**之一。它的价值在于：不需要在 Blender 等外部 DCC 工具中建模并导入，就能在引擎内直接生成一个参数化、可实时调整的环面几何体，适用于戒指、轮胎、甜甜圈、传送门边框、装饰环等常见造型。本文以 TorusMesh 类参考 为核心骨架，结合 PrimitiveMesh 类参考、CSG 关卡原型教程 与 LightmapGI 教程 等仓库资料，系统讲解它的 4 个核心参数、编辑器与代码两种创建方式、继承的进阶属性，以及烘焙光照、CSG 转换、导航性能等真实使用场景。

读完本文，你将掌握：如何用 TorusMesh 在编辑器和 GDScript/C# 中创建环面；四个参数（inner_radius、outer_radius、rings、ring_segments）对形状与性能的影响；以及如何把它接入光照烘焙和网格渲染管线。

1. TorusMesh 是什么：类层次与定位

根据 TorusMesh 类参考 第 13 行，TorusMesh的完整继承链为：

TorusMesh < PrimitiveMesh < Mesh < Resource < RefCounted < Object

• Resource意味着它是资源而非场景节点——它只描述几何数据，本身不进入场景树；
• Mesh是 Godot 中所有"基于顶点数组的几何体"的基类，几何体以surface（表面）为单位组织，每个 surface 有独立的顶点数组和材质（见 Mesh 类参考 第 24 行）；
• PrimitiveMesh是所有程序化原始网格的基类，负责把材质应用到网格上。它的子类还包括 BoxMesh、CapsuleMesh、CylinderMesh、PlaneMesh、SphereMesh 等，TorusMesh是其中之一（见 PrimitiveMesh 类参考 第 15 行）。

在 3D 场景中真正"画出"它的是节点MeshInstance3D——正如 3D 着色器入门教程 第 40～42 行所述：Godot 内置的 PrimitiveMesh 让你"无需导入网格，就能直接往场景里添加基础几何体"，而最常用的网格节点就是MeshInstance3D（同样的网格资源也可以被GPUParticles3D、MultiMeshInstance3D等节点复用）。

官方在 TorusMesh 类参考 第 15 行的描述只有一句话："Class representing a torus PrimitiveMesh."（表示一个环面原始网格的类）。它的全部精髓都集中在下面 4 个属性上。

2. 四个核心参数：从几何到性能的完整解析

这是本文的重中之重。原文档的属性表完整收录如下（默认值来自 TorusMesh 类参考 第 29～40 行）：

每个属性在引擎中都配套一对 getter/setter 方法（见原文档第 59～60、76～77、93～94、110～111 行），即：

• set_inner_radius(value: float)/get_inner_radius()
• set_outer_radius(value: float)/get_outer_radius()
• set_ring_segments(value: int)/get_ring_segments()
• set_rings(value: int)/get_rings()

2.1 inner_radius 与 outer_radius：环的粗细与大小

从命名和默认值（0.5 与 1.0）可以推断出 Godot 对环面几何的定义：inner_radius是环面中心孔洞的半径（从环面中轴到管壁内沿），outer_radius是环面的最外沿半径。二者共同决定环管本身的粗细：

• 管壁厚度 =outer_radius - inner_radius（默认 0.5）；
• 环的中心线半径（major radius）=(inner_radius + outer_radius) / 2（默认 0.75）；
• 管截面半径（minor radius）=(outer_radius - inner_radius) / 2（默认 0.25）。

实际调整技巧：

• 增大差值会得到更粗的"轮胎"，差值趋近于 0 时环面退化为细铁丝圈；
• inner_radius必须小于outer_radius，否则几何无效，会出现自交或退化三角面；
• 想做大环时只调大outer_radius会导致管壁同时变粗，应同时等比增大inner_radius保持比例，或直接整体放大节点 Transform 的 Scale。

2.2 rings 与 ring_segments：细分密度决定圆滑度与面数

• rings（默认64）：环绕主轴的切片数量，即把整个环沿圆周切成多少段，决定环在水平方向上的圆滑度；
• ring_segments（默认32）：每个环截面（tube 横截面）的边数，决定管壁在截面方向上的圆滑度。

两者的几何关系可以这样理解：环面是由"管截面多边形沿主轴旋转"扫掠而成的，ring_segments决定截面的多边形边数，rings决定沿旋转路径放置多少个截面。因此：

• 整体顶点规模大致与rings × ring_segments成正比（默认 64 × 32）；
• 渲染三角面数（除去极点共享等因素）约为此规模的 2 倍量级；
• 提高任一参数都会让环面更圆滑，但不是越高越好——会线性增加顶点数与渲染开销。

性能经验（结合下文导航性能说明可进一步印证）：

• 用作远景装饰或高模近景，可保持 64/32 默认值；
• 用作碰撞提示、遮挡体、低模原型，可降到rings=16, ring_segments=8甚至更低；
• 值设得过大（如 256×256）在移动端会带来明显的网格生成与绘制成本。

对比参考：同为 CSG 体系的 CSGTorus3D 类参考 中，对应参数默认值仅为ring_sides=6、sides=8（第 48～50 行），可见"渲染用的 PrimitiveMesh"与"原型用的 CSG"在默认细分密度上有意做了不同取舍——前者追求圆滑，后者追求轻量。

3. 在编辑器中创建与调整 TorusMesh

在 Godot 编辑器中使用 TorusMesh 与其它 PrimitiveMesh 完全一致：

1. 在场景中添加MeshInstance3D节点；
2. 在检查器（Inspector）中点击Mesh属性的<empty>，选择New TorusMesh；
3. 展开该资源，即可实时编辑Inner Radius、Outer Radius、Rings、Ring Segments四个属性，视口会即时刷新预览。

材质设置：PrimitiveMesh基类自带material属性（见 PrimitiveMesh 类参考 第 41 行），可直接在网格资源上指定材质。但正如 3D 着色器入门教程 第 53～56 行所强调：

如果把材质设置在网格（Mesh）本身上，所有共享该网格的 MeshInstance3D 都会共用同一份材质；如果想让多个实例各自使用不同材质，则应把材质设置在MeshInstance3D 节点上（通过节点上的材质覆盖功能）。

这一差异对 TorusMesh 尤其重要——如果你用同一个环面资源做一批颜色各异的甜甜圈，请把材质挂在节点上而不是资源上，避免被迫为每种颜色复制网格资源。

4. 用代码创建 TorusMesh：GDScript 与 C#

TorusMesh是RefCounted派生的资源对象，可以直接在脚本中new()创建并配置。

4.1 基础用法：生成并挂到场景

# 创建一个环面网格资源 var torus_mesh = TorusMesh.new() torus_mesh.inner_radius = 0.5 # 孔洞半径 torus_mesh.outer_radius = 1.0 # 最外沿半径 torus_mesh.rings = 64 # 主轴切片数（圆滑度） torus_mesh.ring_segments = 32 # 管截面边数（圆滑度） # 挂到网格节点上显示 var mesh_instance = MeshInstance3D.new() mesh_instance.mesh = torus_mesh add_child(mesh_instance)

对应的 C# 写法：

var torusMesh = new TorusMesh(); torusMesh.InnerRadius = 0.5f; torusMesh.OuterRadius = 1.0f; torusMesh.Rings = 64; torusMesh.RingSegments = 32; var meshInstance = new MeshInstance3D(); meshInstance.Mesh = torusMesh; AddChild(meshInstance);

修改属性后无需手动重建——PrimitiveMesh基类会在属性变化时自动重新生成几何（其公开方法request_update()也可用于显式请求基于属性的更新，见 PrimitiveMesh 类参考 第 212 行）。

4.2 进阶：把环面转成 ArrayMesh 再加工

PrimitiveMesh.get_mesh_arrays()会返回构成该网格表面的网格数组（mesh arrays）。原文档在 PrimitiveMesh 类参考 第 181～201 行给出了官方示例——把结果传给ArrayMesh.add_surface_from_arrays()就能创建自定义网格：

var t = TorusMesh.new() t.inner_radius = 0.5 t.outer_radius = 1.0 var arr_mesh = ArrayMesh.new() arr_mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, t.get_mesh_arrays())

var t = new TorusMesh(); t.InnerRadius = 0.5f; t.OuterRadius = 1.0f; var arrMesh = new ArrayMesh(); arrMesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, t.GetMeshArrays());

这一步的意义在于：ArrayMesh是真正的"可编辑顶点数据"网格（Mesh 类参考 的子类），拿到数组后你可以修改顶点位置、附加法线/切线/UV、与其它几何合并，甚至实现"以环面为基础再程序化变形"的需求。这与 3D 入门教程 第 330～335 行介绍的"通过ArrayMesh直接生成自定义几何体"是同一套管线。

5. 继承自 PrimitiveMesh 的进阶属性

TorusMesh本身没有方法，但它继承了PrimitiveMesh的全部能力。以下 5 个属性对环面实战尤其有用（原文见 PrimitiveMesh 类参考 第 31～44 行的属性表）：

flip_faces的实用场景：制作"只从内侧看"的环面隧道内壁；而custom_aabb在环面上配合顶点着色器做波纹、扭转变形时，能防止包围盒过小而把网格裁掉。

6. 实战：环面在光照烘焙中的经典用法

[TorusMesh] 与光照烘焙最相关的应用，来自 LightmapGI 教程 第 182～198 行：

• 默认情况下，PrimitiveMesh 不生成 UV2（为了省资源，因为这些网格可能是在游戏运行时才创建的）；
• 在检查器中选中环面网格资源并开启Add UV2，引擎就会程序化生成 UV2，让环面既能接收也能贡献烘焙光照；
• 默认的UV2 Padding=2.0已经过调校，能在大多数情况下避免光照渗漏、又不浪费贴图边缘空间；如果只对某个网格出现渗漏，可以单独调大该值；
• 文档中给出的一个典型创意用法：把一个带自发光（emissive）材质的环面隐藏起来，作为"贴合环面形状的区域光（area light）"——烘焙后它会按环的形状照亮周围场景（第 189～190 行）。这正是 TorusMesh 这种参数化形状独有的价值：难以用手工建模精确还原的"环形光源"，用环面 + emissive 材质几秒钟就能搭出来。

需要注意：此功能只对 BoxMesh、CylinderMesh、TorusMesh 这类原始网格有效（第 184～185 行）。如果你用的是 CSG 环面（CSGTorus3D），则需先把 CSG 烘焙成 MeshInstance3D 才能参与光照烘焙（详见下一节）。

7. 与 CSGTorus3D 的对比及转换

Godot 中还有另一个"环面"：CSGTorus3D（CSG 体系的环面节点）。两者极易混淆，本文一并厘清：

关键区别与代价：CSG 的布尔能力（如"用环面从盒子上挖出一个洞"，见 CSG 关卡原型教程 第 8～14 行与第 26 行视频配图）是 TorusMesh 不具备的；但 CSGTorus3D 类参考 第 24 行明确警告：创建 CSG 节点相比直接用 MeshInstance3D + PrimitiveMesh 有显著的 CPU 开销，在游戏运行期移动 CSG 节点代价也很大，应避免。

转换路径：自 Godot 4.4 起，可以在 3D 编辑器工具栏选择CSG > Bake Mesh Instance，把 CSG 节点及其子节点烘焙成 MeshInstance3D（CSG 教程 第 343～356 行），带来四个收益：可烘焙光照贴图（UV2 可在 MeshInstance3D 上生成）、可烘焙遮挡剔除、场景加载更快、节点变换更新性能更好。注意：烘焙后原 CSG 节点不会自动隐藏，需要手动隐藏防止几何重叠；并建议保留原 CSG 节点以便日后修改几何。如果你最终想要的只是一个"渲染用的圆滑环面"，直接在 MeshInstance3D 上新建 TorusMesh 是最省 CPU 的选择。

8. 性能与使用边界提醒

最后集中说明与 TorusMesh 相关的性能/使用注意事项：

1. 细分与面数：顶点规模随rings × ring_segments增长。做原型或大量复用（如栅栏阵列）时建议降低细分，用材质与法线表现细节，而不是盲目堆面数。
2. 导航网格：Godot 导航性能优化指南明确指出，应优先使用边数尽量少的简单形状，避免圆形、球体或环面这类弧形轮廓（见 导航性能优化教程 第 23 行）——环面的导航网格生成与寻路代价偏高，若场景需要大量可寻路区域，请用简化多边形近似。
3. 运行时创建：PrimitiveMesh 默认不生成 UV2 正是为了省资源（这些网格常在游戏运行时创建，见 LightmapGI 教程 第 192 行）；只有需要参与光照烘焙时才开启Add UV2。
4. 静态几何优先：程序化网格适合"不经常更新"的静态几何（3D 入门教程 第 337～339 行）；若需要频繁更新的简单几何，则应考虑ImmediateMesh。

结语

TorusMesh是 Godot 内置原始网格中最"雕塑感"的一员：仅凭 4 个参数（inner_radius、outer_radius、rings、ring_segments）就能在编辑器或代码中生成任意粗细、任意圆滑度的环面。结合 PrimitiveMesh 基类的material、flip_faces、add_uv2/uv2_padding能力，它可以胜任装饰造型、环形区域光、隧道内壁乃至程序化网格加工（转 ArrayMesh）等任务；而通过与 CSGTorus3D 的对比，你也能明确"渲染用环面"与"原型布尔用环面"的取舍边界。相关的完整属性参考与更多 3D 工作流，可继续阅读仓库中的 TorusMesh 类参考、PrimitiveMesh 类参考、Mesh 类参考、CSG 关卡原型教程 与 LightmapGI 教程。

• 文档
• 教程
• 游戏开发