文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载引言为什么需要 TorusMeshTorusMesh环面网格即甜甜圈形状是 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 ObjectResource意味着它是资源而非场景节点——它只描述几何数据本身不进入场景树Mesh是 Godot 中所有基于顶点数组的几何体的基类几何体以surface表面为单位组织每个 surface 有独立的顶点数组和材质见 Mesh 类参考 第 24 行PrimitiveMesh是所有程序化原始网格的基类负责把材质应用到网格上。它的子类还包括 BoxMesh、CapsuleMesh、CylinderMesh、PlaneMesh、SphereMesh 等TorusMesh是其中之一见 PrimitiveMesh 类参考 第 15 行。在 3D 场景中真正画出它的是节点MeshInstance3D——正如 3D 着色器入门教程 第 4042 行所述Godot 内置的 PrimitiveMesh 让你无需导入网格就能直接往场景里添加基础几何体而最常用的网格节点就是MeshInstance3D同样的网格资源也可以被GPUParticles3D、MultiMeshInstance3D等节点复用。官方在 TorusMesh 类参考 第 15 行的描述只有一句话Class representing a torus PrimitiveMesh.表示一个环面原始网格的类。它的全部精髓都集中在下面 4 个属性上。2. 四个核心参数从几何到性能的完整解析这是本文的重中之重。原文档的属性表完整收录如下默认值来自 TorusMesh 类参考 第 2940 行属性类型默认值含义原文档原文inner_radiusfloat0.5环面的内半径The inner radius of the torusouter_radiusfloat1.0环面的外半径The outer radius of the torusring_segmentsint32构成环面每个环的边数The number of edges each ring of the torus is constructed ofringsint64构成环面的切片数量The number of slices the torus is constructed of每个属性在引擎中都配套一对 getter/setter 方法见原文档第 5960、7677、9394、110111 行即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 默认值用作碰撞提示、遮挡体、低模原型可降到rings16, ring_segments8甚至更低值设得过大如 256×256在移动端会带来明显的网格生成与绘制成本。对比参考同为 CSG 体系的 CSGTorus3D 类参考 中对应参数默认值仅为ring_sides6、sides8第 4850 行可见渲染用的 PrimitiveMesh与原型用的 CSG在默认细分密度上有意做了不同取舍——前者追求圆滑后者追求轻量。3. 在编辑器中创建与调整 TorusMesh在 Godot 编辑器中使用 TorusMesh 与其它 PrimitiveMesh 完全一致在场景中添加MeshInstance3D节点在检查器Inspector中点击Mesh属性的empty选择New TorusMesh展开该资源即可实时编辑Inner Radius、Outer Radius、Rings、Ring Segments四个属性视口会即时刷新预览。材质设置PrimitiveMesh基类自带material属性见 PrimitiveMesh 类参考 第 41 行可直接在网格资源上指定材质。但正如 3D 着色器入门教程 第 5356 行所强调如果把材质设置在网格Mesh本身上所有共享该网格的 MeshInstance3D 都会共用同一份材质如果想让多个实例各自使用不同材质则应把材质设置在MeshInstance3D 节点上通过节点上的材质覆盖功能。这一差异对 TorusMesh 尤其重要——如果你用同一个环面资源做一批颜色各异的甜甜圈请把材质挂在节点上而不是资源上避免被迫为每种颜色复制网格资源。4. 用代码创建 TorusMeshGDScript 与 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 类参考 第 181201 行给出了官方示例——把结果传给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 入门教程 第 330335 行介绍的通过ArrayMesh直接生成自定义几何体是同一套管线。5. 继承自 PrimitiveMesh 的进阶属性TorusMesh本身没有方法但它继承了PrimitiveMesh的全部能力。以下 5 个属性对环面实战尤其有用原文见 PrimitiveMesh 类参考 第 3144 行的属性表属性类型默认值作用materialMaterial空当前原始网格使用的材质flip_facesboolfalse为true时翻转每个三角形的顶点顺序从而渲染背面效果等同于在 BaseMaterial3D 的cull_mode中使用CULL_FRONTadd_uv2boolfalse为true时按uv2_padding生成 UV2 坐标——UV2 是光照贴图lightmap烘焙所必需的uv2_paddingfloat2.0add_uv2开启时沿网格接缝处 UV2 的像素填充量填充越小越能利用贴图空间纹素密度更高但可能沿边出现可见的光照渗漏lightmap bleeding。若无法确定贴图尺寸按 1024×1024 计算custom_aabbAABB零 AABB用自定义包围盒覆盖默认值用于视锥剔除当着色器偏移顶点时尤其有用可避免意外的裁剪flip_faces的实用场景制作只从内侧看的环面隧道内壁而custom_aabb在环面上配合顶点着色器做波纹、扭转变形时能防止包围盒过小而把网格裁掉。6. 实战环面在光照烘焙中的经典用法[TorusMesh] 与光照烘焙最相关的应用来自 LightmapGI 教程 第 182198 行默认情况下PrimitiveMesh 不生成 UV2为了省资源因为这些网格可能是在游戏运行时才创建的在检查器中选中环面网格资源并开启Add UV2引擎就会程序化生成 UV2让环面既能接收也能贡献烘焙光照默认的UV2 Padding2.0已经过调校能在大多数情况下避免光照渗漏、又不浪费贴图边缘空间如果只对某个网格出现渗漏可以单独调大该值文档中给出的一个典型创意用法把一个带自发光emissive材质的环面隐藏起来作为贴合环面形状的区域光area light——烘焙后它会按环的形状照亮周围场景第 189190 行。这正是 TorusMesh 这种参数化形状独有的价值难以用手工建模精确还原的环形光源用环面 emissive 材质几秒钟就能搭出来。需要注意此功能只对 BoxMesh、CylinderMesh、TorusMesh 这类原始网格有效第 184185 行。如果你用的是 CSG 环面CSGTorus3D则需先把 CSG 烘焙成 MeshInstance3D 才能参与光照烘焙详见下一节。7. 与 CSGTorus3D 的对比及转换Godot 中还有另一个环面CSGTorus3DCSG 体系的环面节点。两者极易混淆本文一并厘清维度TorusMeshPrimitiveMeshCSGTorus3DCSG 节点类层次PrimitiveMesh Mesh ResourceCSGPrimitive3D CSGShape3D GeometryInstance3D Node3D Node见 CSGTorus3D 类参考 第 13 行本质网格资源数据场景节点可参与布尔运算环参数inner_radius0.5、outer_radius1.0、rings64、ring_segments32inner_radius0.5、outer_radius1.0、sides8、ring_sides6、smooth_facestrue同上第 4252 行细分默认值较高圆滑渲染较低轻量原型用途直接渲染的网格关卡原型、布尔建模并/交/差关键区别与代价CSG 的布尔能力如用环面从盒子上挖出一个洞见 CSG 关卡原型教程 第 814 行与第 26 行视频配图是 TorusMesh 不具备的但 CSGTorus3D 类参考 第 24 行明确警告创建 CSG 节点相比直接用 MeshInstance3D PrimitiveMesh 有显著的 CPU 开销在游戏运行期移动 CSG 节点代价也很大应避免。转换路径自 Godot 4.4 起可以在 3D 编辑器工具栏选择CSG Bake Mesh Instance把 CSG 节点及其子节点烘焙成 MeshInstance3DCSG 教程 第 343356 行带来四个收益可烘焙光照贴图UV2 可在 MeshInstance3D 上生成、可烘焙遮挡剔除、场景加载更快、节点变换更新性能更好。注意烘焙后原 CSG 节点不会自动隐藏需要手动隐藏防止几何重叠并建议保留原 CSG 节点以便日后修改几何。如果你最终想要的只是一个渲染用的圆滑环面直接在 MeshInstance3D 上新建 TorusMesh 是最省 CPU 的选择。8. 性能与使用边界提醒最后集中说明与 TorusMesh 相关的性能/使用注意事项细分与面数顶点规模随rings × ring_segments增长。做原型或大量复用如栅栏阵列时建议降低细分用材质与法线表现细节而不是盲目堆面数。导航网格Godot 导航性能优化指南明确指出应优先使用边数尽量少的简单形状避免圆形、球体或环面这类弧形轮廓见 导航性能优化教程 第 23 行——环面的导航网格生成与寻路代价偏高若场景需要大量可寻路区域请用简化多边形近似。运行时创建PrimitiveMesh 默认不生成 UV2 正是为了省资源这些网格常在游戏运行时创建见 LightmapGI 教程 第 192 行只有需要参与光照烘焙时才开启Add UV2。静态几何优先程序化网格适合不经常更新的静态几何3D 入门教程 第 337339 行若需要频繁更新的简单几何则应考虑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 教程。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐douyin-downloader 实战指南抖音批量下载工具无水印视频、主页保存与直播录制douyin downloader 实战指南抖音批量下载工具无水印视频、主页保存与直播录制 douyin downloader 是一个开源免费的抖音下载工具网页爬虫CLIGodot PlaneMesh 平面网格完全指南从属性详解到细分、UV 与实战应用Godot PlaneMesh 平面网格完全指南从属性详解到细分、UV 与实战应用 导读 PlaneMesh 是 Godot 引擎中最常用的基础几何体Pri文档教程游戏开发Godot RibbonTrailMesh 完全指南粒子拖尾网格参数详解与曲线塑形实战Godot RibbonTrailMesh 完全指南粒子拖尾网格参数详解与曲线塑形实战 RibbonTrailMesh 是 Godot 引擎中用于生成带状r文档教程游戏开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考