文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载导读GLTFMesh 是 Godot 引擎 glTF 模块中用于承载 glTF 3D 网格数据的核心容器类它把 glTF 文件中每个 mesh 对象顶点、混合变形、材质完整映射为 Godot 可以消费的ImporterMesh与材质列表。本文以该类的官方类参考文档为主体结合仓库内GLTFState、GLTFNode、GLTFDocument与GLTFDocumentExtension等关联类文档及运行时加载教程完整讲解其继承体系、全部属性与方法的语义、在导入/导出管线中的位置以及如何通过set_additional_data/get_additional_data在无状态扩展架构中保存每网格状态。读完本文你将掌握 GLTFMesh 在 Godot glTF 管线中的数据结构本质并能在此基础上编写自己的 glTF 文档扩展。类定位GLTFMesh 在 Godot glTF 管线中扮演什么角色继承体系与类职责GLTFMesh继承自Resource进而继承RefCounted与Object也就是说它是典型的资源类可以被引用计数管理、可被序列化适合作为 glTF 状态数据的一部分长期存在。官方类文档对其描述如下GLTFMesh represents a glTF mesh. GLTFMesh handles 3D mesh data imported from glTF files. It includes properties for blend channels, blend weights, instance materials, and the mesh itself.简单说每一个 glTF 文件中的mesh对象在 Godot 内部都对应一个GLTFMesh实例它集中存放该网格的几何数据、混合变形blend shape / morph target权重、实例化材质以及网格原始名称。在 glTF 状态结构中的位置GLTFMesh本身并不单独存在而是作为 GLTFStateRepresents all data of a glTF file中多个平行资源数组的一员被索引引用。从GLTFState类参考可以看到get_meshes() / set_meshes()获取或设置整个 glTF 文件中全部GLTFMesh的数组即GLTFNode.mesh索引所指的目标get_nodes() / set_nodes()全部GLTFNode其mesh属性保存指向GLTFMesh数组的整数索引同理get_materials()、get_skins()、get_skeletons()等分别管理材质、蒙皮与骨架数据。因此一个 glTF 网格的引用链条是GLTFState.meshes数组 →GLTFNode.mesh整数索引→GLTFMesh实例 → 其内部meshImporterMesh与instance_materialsMaterial数组。从 GLTFNode 的类参考也能印证mesh属性描述为 If this glTF node is a mesh, the index of the GLTFMesh in the GLTFState that describes the meshs properties. If -1, this node is not a mesh.这种状态集中存储 索引互相引用的设计是 Godot glTF 模块的总体架构后续小节会说明这对扩展开发者的意义。GLTFMesh 的四个属性数据结构的核心骨架GLTFMesh的全部成员都是属性没有复杂行为。以下四个属性构成了该类的完整数据面属性类型默认值语义blend_weightsPackedFloat32ArrayPackedFloat32Array()网格各混合变形通道blend channel的权重数组instance_materialsArray[Material][]该网格使用的材质对象数组meshImporterMesh—网格几何数据本身original_nameString网格在 glTF 文件中的原始名称每个属性都提供标准的set_/get_访问器如set_blend_weights/get_blend_weights可以直接在 GDScript 或 C# 中读写。下面逐一展开。blend_weights混合变形的权重通道签名PackedFloat32Array blend_weights PackedFloat32Array()访问器set_blend_weights(value)与get_blend_weights()。blend_weights是一个浮点数组表示网格各混合变形通道的当前权重。它直接对应 glTF 2.0 规范中 mesh primitive 的 morph target 权重weights字段。当一个模型包含形变目标Blender 中叫 shape keys即 morph targets时导入后这些权重会被保留在GLTFMesh上用于驱动MeshInstance3D的形变。需要特别注意的是官方文档给出的classref_noteThe returned array iscopiedand any changes to it will not update the original property value. See PackedFloat32Array for more details.也就是说get_blend_weights()返回的是拷贝直接修改返回的数组不会写回原属性要真正更新权重必须整体调用set_blend_weights()。这是PackedFloat32Array这类值类型数组在 Godot 中的通用行为编辑器中导入网格、或运行时修改形变权重时都应遵循这一模式。instance_materials网格的材质实例列表签名Array[Material] instance_materials []访问器set_instance_materials(value)与get_instance_materials()。该属性保存网格使用的所有Material对象。glTF 的 mesh primitive 通过 material 索引引用材质而 Godot 在导入时把这些材质解析为Material资源并放入instance_materials数组供后续创建MeshInstance3D时按 surface 分配。从源码结构看一个ImporterMesh的每个 surface 对应一个材质槽位二者通过数组顺序对齐。mesh真正的几何数据容器签名ImporterMesh mesh访问器set_mesh(value)与get_mesh()。mesh属性持有的是ImporterMesh对象——这是 Godot 导入管线的中间网格格式在生成最终的Mesh如ArrayMesh之前保存着顶点、法线、UV、骨骼权重等全部几何信息。ImporterMesh的存在意味着GLTFMesh处于尚未完全转换为运行时 Mesh的导入中间态GLTFDocument读取 glTF 数据后先填充GLTFMesh再由后续步骤把ImporterMesh转换为场景中MeshInstance3D可用的Mesh。original_name保留 glTF 原始命名签名String original_name 访问器set_original_name(value)与get_original_name()。original_name保存网格在 glTF 文件里的原名。这在名称去重、导入映射、调试以及与 DCC数字内容创作软件原始资源对齐时非常有用。glTF 中节点名可能重复Godot 场景要求唯一名称因此原始名与去重后的最终名是分开管理的——GLTFState中恰好也有get_unique_names()用来管理唯一的节点/网格名称。两个方法为无状态扩展提供每网格储物柜GLTFMesh只有两个方法且二者成对出现set_additional_data(extension_name, additional_data)与get_additional_data(extension_name)。它们的出现并非偶然而是 Godot glTF 扩展机制的重要一环。为什么需要 additional_dataGLTFDocumentExtension 必须无状态先看官方类文档对 GLTFDocumentExtension 的关键说明All GLTFDocumentExtension classes are duplicated when beginning the import or export process. Except for configuration values, these classes must be stateless in order to function properly. If you need to store data, use theset_additional_dataandget_additional_datamethods in GLTFState or GLTFNode.也就是说扩展类在每次导入/导出开始时会被复制且除配置值外必须保持无状态。那么自定义 glTF 扩展如KHR_materials_variants、自定义扩展数据在导入/导出各阶段产生的中间状态存到哪里答案就是挂在各类状态对象GLTFState、GLTFNode、GLTFMesh等上的附加数据储物柜。get_additional_data的官方描述明确指出Gets additional arbitrary data in this GLTFMesh instance. This can be used to keep per-node state data in GLTFDocumentExtension classes, which is important because they are stateless.注意这里文档写作 per-node state data实际语义是per-GLTFMesh每网格状态数据每个GLTFMesh实例都能独立保存一份扩展专属数据。两个方法的语义细节get_additional_data(extension_name: StringName) - Variant返回指定扩展名关联的数据。参数应当使用扩展类的名称不必与 glTF 文件中的扩展名字符串一致因为这是 Godot 内部的命名空间标识。若从未set过返回null。set_additional_data(extension_name: StringName, additional_data: Variant) - void写入任意Variant数据。第一个参数同样是扩展类名称第二个参数可以是任何你想保存的内容字典、数组、自定义资源均可。典型用法是在GLTFDocumentExtension的_parse_node_extensions或_parse_mesh_extensions阶段解析出自定义数据后set_additional_data(MyExtension, data)暂存在_generate_scene_node阶段再get_additional_data(MyExtension)取出并应用到生成的 Godot 节点上。这样既绕开了扩展类的无状态限制又把数据作用域精确控制在单个网格上避免不同网格互相污染。实战串联GLTFMesh 在 glTF 导入/导出流程中的生命周期运行时加载 glTF 场景的标准流程GLTFMesh 并非你手动 new 出来的类而是由GLTFDocument在解析 glTF 文件时自动创建并填充。官方 runtime_file_loading_and_saving 教程给出的核心代码展示了完整调用链GDScript 版# 加载GLTFState 存储文件状态GLTFDocument 负责解析 var gltf_document_load GLTFDocument.new() var gltf_state_load GLTFState.new() var error gltf_document_load.append_from_file(/path/to/file.gltf, gltf_state_load) if error OK: var gltf_scene_root_node gltf_document_load.generate_scene(gltf_state_load) add_child(gltf_scene_root_node) else: show_error(Couldnt load glTF scene (error code: %s). % error_string(error)) # 保存把 Godot 场景转换回 glTF var gltf_document_save : GLTFDocument.new() var gltf_state_save : GLTFState.new() gltf_document_save.append_from_scene(gltf_scene_root_node, gltf_state_save) # 输出路径扩展名为 .gltf 时写文本格式为 .glb 时写二进制格式 gltf_document_save.write_to_filesystem(gltf_state_save, path)在这条链路上GLTFMesh处于中间环节append_from_file()解析 glTF JSON为每个 mesh 创建GLTFMesh并放入GLTFState.meshes对应set_meshes()每个引用该 mesh 的节点在GLTFNode.mesh记录索引generate_scene()遍历节点把GLTFMesh.meshImporterMesh转换为场景网格把instance_materials分配到各 surface把blend_weights写入MeshInstance3D的形变状态反向导出时append_from_scene()把场景中的MeshInstance3D数据回填为GLTFMeshwrite_to_filesystem()再序列化为 glTF。一个值得注意的实操细节同样来自官方教程从 buffer 加载如append_from_buffer时没有文件路径可推断必须在调用前手动设置GLTFState.base_path否则外部贴图等依赖无法正确解析。从文件加载时 base path 会自动设为文件所在目录。编辑器导入流程与网格级配置在编辑器中glTF 导入有两个额外步骤生成 Godot 场景后ResourceImporterScene会应用你在 Import 面板与 Advanced Import Settings 中设置的参数再保存为 Godot 场景文件。正如 available_formats 所描述这些网格级导入选项如 Generate LODs、Lightmap UV、Shadow Meshes 等最终都作用于GLTFMesh.mesh所承载的ImporterMesh。此外该文档还给出与 blend shape 直接相关的导出注意事项If your model contains blend shapes (also known as shape keys and morph targets), your glTF export settingData Armature Export Deformation Bones Onlyneeds to be configured toEnabled. Exporting non-deforming bones anyway will lead to incorrect shading.也就是说blend_weights与混合变形能否正确工作还依赖你在 Blender 导出 glTF 时的骨架设置。这类跨工具约束提醒我们GLTFMesh 数据面虽简单但其正确性由完整的导入导出生态共同保证。编写自定义扩展用 additional_data 扩展 GLTFMesh 状态基于前文我们可以给出一个可直接落地的扩展编写骨架。目标在导入阶段为每个网格保存自定义元数据并在生成场景时读取。extends GLTFDocumentExtension const EXT_NAME : MyMeshExtension func _parse_mesh_extensions(state: GLTFState, gltf_mesh: GLTFMesh) - Error: # 解析 glTF mesh 上的自定义扩展数据并暂存到该 GLTFMesh 上 var json: Dictionary state.json var meshes: Array json.get(meshes, []) if gltf_mesh.get_original_name() in meshes: var meta : { custom_flag: true, notes: parsed from glTF extension } gltf_mesh.set_additional_data(EXT_NAME, meta) return OK func _generate_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_node: Node) - Node: if scene_node is MeshInstance3D: var mesh_index: int gltf_node.mesh if mesh_index 0: var gltf_mesh: GLTFMesh state.get_meshes()[mesh_index] var data gltf_mesh.get_additional_data(EXT_NAME) if data ! null: # 把暂存数据应用到生成的 Godot 节点 scene_node.set_meta(my_mesh_extension, data) return scene_node要点归纳扩展键使用类内常量StringName不必等于 glTF 文件中的扩展名数据作用域是单个GLTFMesh不同网格互不干扰读取时机_generate_scene_node晚于写入时机_parse_mesh_extensions且扩展类自身保持无状态注册方式为GLTFDocument.register_gltf_document_extension(MyMeshExtension.new())。这一模式与GLTFState、GLTFNode上同名的additional_data机制完全一致构成了整个 glTF 模块无状态扩展 有状态对象储物柜的统一架构。总结与进一步探索GLTFMesh虽然只有四个属性和两个方法却是理解 Godot glTF 数据流的关键一环它以ImporterMesh保存几何以instance_materials管理材质以blend_weights承载混合变形权重以original_name保留原始命名并通过additional_data机制把自定义扩展数据挂载到每个网格实例上。结合 GLTFState全文件数据、GLTFNode节点与索引引用和 GLTFDocument导入导出执行器一起阅读可以完整勾勒出 Godot glTF 模块的架构全貌。如果想继续深入建议依次阅读GLTFDocument 类参考掌握append_from_file、generate_scene、append_from_scene、write_to_filesystem等完整调用链GLTFDocumentExtension 类参考了解可覆盖的虚拟方法及各阶段语义运行时文件加载与保存教程获取可运行的 glTF 运行时导入/导出示例glTF 导入格式说明查看编辑器导入流程与 Blender 导出注意事项。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Qodot将经典游戏地图带入Godot引擎的桥梁Qodot将经典游戏地图带入Godot引擎的桥梁 项目介绍 Qodot是一款专为Godot 3.x引擎设计的开源插件旨在为开发者提供对Quake .map探索maya-glTF解锁Maya到glTF的无缝桥梁探索maya glTF解锁Maya到glTF的无缝桥梁 在数字内容创作的世界里高效、标准的资产交流至关重要。今天我们向您隆重介绍 maya glTF ——图形学开发工具Godot引擎场景实例化教程从入门到实践Godot引擎场景实例化教程从入门到实践 什么是场景实例化 在Godot引擎中场景实例化 Instancing 是一种强大的设计模式它允许开发者将游戏对象文档教程游戏开发上一篇三步完成网页视频下载猫抓cat-catch浏览器资源嗅探新手指南下一篇Kronos Docker容器化一键部署的开发与生产环境配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考