
文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载GLTFPhysicsShape是 Godot 引擎 glTF 模块中专门用于表示 glTF 物理碰撞形状的中间类它在OMI_physics_shape与OMI_collider两种 glTF 扩展数据与 Godot 自身的CollisionShape3D节点、Shape3D资源之间建立双向转换桥梁。本文将基于官方类参考文档classes/class_gltfphysicsshape.rst完整讲解该类的 7 个属性、6 个方法、六种形状类型与 Godot 物理形状的映射关系并给出可实际运行的 GDScript 示例帮助读者掌握在运行时加载/保存含物理形状的 glTF 场景以及理解 Godot 编辑器导入流程中碰撞形状的生成原理。一、类定位glTF 物理扩展与 Godot 物理体系的中间层GLTFPhysicsShape继承自Resource其完整继承链为Resource→RefCounted→Object是一个可复用的资源对象。官方描述见 类文档明确指出它的职责Represents a physics shape as defined by theOMI_physics_shapeorOMI_colliderglTF extensions. This class is an intermediary between the glTF data and Godots nodes, and its abstracted in a way that allows adding support for different glTF physics extensions in the future.翻译过来即该类的实例代表一个由OMI_physics_shape或OMI_colliderglTF 扩展定义的物理形状是 glTF 数据与 Godot 节点之间的中间人并且其抽象设计使得未来可以方便地接入更多不同的 glTF 物理扩展。这一定位决定了GLTFPhysicsShape的两个核心能力方向导入方向glTF → Godot从 glTF 扩展数据以Dictionary形式存在解析出物理形状再转换为 Godot 的CollisionShape3D节点或Shape3D资源导出方向Godot → glTF从 Godot 现有的CollisionShape3D节点或Shape3D资源反推出形状描述并序列化为符合OMI_physics_shape格式的Dictionary。从源码结构看对应的 XML 源为 Godot 引擎modules/gltf/doc_classes/GLTFPhysicsShape.xml该类属于 Godot 的 glTF 模块与姊妹类GLTFPhysicsBodyclasses/class_gltfphysicsbody.rst配合使用GLTFPhysicsBody负责物理刚体层面的信息质量、速度、惯性、运动类型等而GLTFPhysicsShape负责几何形状层面的信息类型、尺寸、半径、高度、网格索引等。1.1 与 GLTFDocument / GLTFState 的整体流程在 Godot 的 glTF 支持体系中GLTFDocument负责实际的加载与生成逻辑GLTFState保存被加载场景的状态详见 classes/class_gltfdocument.rst 与 classes/class_gltfstate.rst。可以推断在GLTFDocument生成场景树的过程中遇到节点挂载了物理扩展时会通过GLTFPhysicsShape.from_dictionary()解析扩展数据再通过to_node()/to_resource()生成对应的 Godot 碰撞节点而在导出场景时则反向通过from_node()/from_resource()收集 Godot 中的碰撞形状再用to_dictionary()序列化回扩展格式。这种字典解析 → 中间对象 → 节点/资源的三段式设计正是该类被称为中间层的原因。二、属性详解7 个属性完整覆盖六种形状GLTFPhysicsShape共定义 7 个属性它们并非总是同时生效——每个属性只在特定形状类型下才被使用。下表完整列出属性、默认值与适用范围属性类型默认值仅用于哪些 shape_typeshape_typeString所有形状标识形状类型本身sizeVector3Vector3(1, 1, 1)boxradiusfloat0.5capsule、cylinder、sphereheightfloat2.0capsule、cylinderimporter_meshImporterMesh—hull、trimeshmesh_indexint-1hull、trimeshis_triggerboolfalse所有形状触发语义独立于几何下面逐一展开说明。2.1 shape_type形状类型标识类型String默认值访问器set_shape_type(value)/get_shape_type()shape_type声明了该形状实例所代表的类型合法的取值共有六种box、capsule、cylinder、sphere、hull、trimesh。其中box立方体、capsule胶囊体、cylinder圆柱体、sphere球体是四类基础图元形状用少量标量参数即可完整描述hull凸包与trimesh凹面三角网格是两类网格派生形状需要引用 glTF 文件中的网格数据。shape_type是其他属性生效与否的总开关下文每个属性都会说明其所属的形状类型。2.2 size立方体的尺寸类型Vector3默认值Vector3(1, 1, 1)访问器set_size(value)/get_size()适用类型仅boxsize表示形状的尺寸单位是米。文档特别强调当形状类型为box时它表示立方体的diameter直径/边长即各轴方向的完整长度而不是半边长。该值不应为负数。2.3 radius图元形状的半径类型float默认值0.5访问器set_radius(value)/get_radius()适用类型capsule、cylinder、sphereradius表示形状的半径单位是米同时服务于胶囊体、圆柱体和球体三种图元。文档明确要求该值不应为负数。默认值0.5意味着默认球体的直径为 1 米与size默认值Vector3(1, 1, 1)保持一致的尺度。2.4 height胶囊体与圆柱体的高度类型float默认值2.0访问器set_height(value)/get_height()适用类型仅capsule、cylinderheight表示形状的高度单位是米。文档给出了两条约束该值不应为负数对于capsule胶囊体高度应至少为半径的两倍即height radius * 2。这一约束源于胶囊体的几何构成——胶囊体由一段圆柱体和两端半球组成若高度小于直径几何上将无法构成有效的胶囊形状。而圆柱体则没有这一限制高度可以小于直径。2.5 importer_mesh网格派生形状的网格资源类型ImporterMesh访问器set_importer_mesh(value)/get_importer_mesh()适用类型hull、trimesh当形状类型为hull凸包或trimesh凹面三角网格时需要通过importer_mesh引用形状的网格资源。这里使用的ImporterMesh见 classes/class_importermesh.rst是 Godot 导入阶段的网格资源类型与运行时使用的ArrayMesh类似但保存的是 LOD、阴影网格等导入步骤之前的原始几何数据——正因为形状生成发生在导入流程中所以使用ImporterMesh而非ArrayMesh。2.6 mesh_index网格在 glTF 文件中的索引类型int默认值-1访问器set_mesh_index(value)/get_mesh_index()适用类型hull、trimeshmesh_index记录该形状所用网格在 glTF 文件中的索引对应 glTF 的meshes数组下标。默认值-1表示未指定或无网格。从数据结构上可以推断mesh_index与importer_mesh是配套使用的——mesh_index是 glTF 侧的身份标识用于在扩展字典中记录引用关系而importer_mesh是 Godot 侧的实际资源用于生成物理形状时读取顶点数据。2.7 is_trigger触发器语义类型bool默认值false访问器set_is_trigger(value)/get_is_trigger()is_trigger表示该形状是否是一个触发器trigger。文档给出了两个关键信息语义映射在 Godot 中触发器形状应作为Area3D节点的子节点而非PhysicsBody3D因为Area3D提供的是重叠检测而非物理阻挡见 classes/class_area3d.rst使用方式is_trigger是唯一一个不会在to_node()方法中使用的属性——to_node()只负责生成CollisionShape3D节点本身而is_trigger的用途是在调用方决定把生成的节点添加到哪个父节点Area3D还是物理刚体时作为判断依据。这一设计将形状几何与形状语义解耦让调用方拥有更大的组织节点树的自由度。三、方法详解双向转换的六种途径GLTFPhysicsShape提供 6 个方法构成三组对称的转换能力字典 ↔ 实例、节点 ↔ 实例、资源 ↔ 实例。3.1 从字典解析from_dictionarystatic GLTFPhysicsShape from_dictionary(dictionary: Dictionary)静态方法通过解析给定的Dictionary创建一个新的GLTFPhysicsShape实例。这个字典的格式正是OMI_physics_shape或OMI_collider扩展在 glTF JSON 中定义的格式——即读取 glTF 文件时扩展对象被解析为Dictionary后直接传入此方法。这是导入流程的入口。3.2 序列化为字典to_dictionaryDictionary to_dictionary() const与from_dictionary对称将当前GLTFPhysicsShape实例序列化为一个Dictionary。文档明确说明其输出格式符合OMI_physics_shape扩展定义。这是导出流程的出口——Godot 将场景中的物理形状收集起来后通过此方法生成符合 glTF 扩展规范的 JSON 数据。该方法带const修饰不会修改实例的任何成员变量。3.3 从节点解析from_nodestatic GLTFPhysicsShape from_node(shape_node: CollisionShape3D)静态方法从给定的 GodotCollisionShape3D节点创建一个新的GLTFPhysicsShape实例。CollisionShape3D见 classes/class_collisionshape3d.rst是为CollisionObject3D父节点提供Shape3D的节点类型它持有实际的形状资源。此方法的作用是反向收集当用户把 glTF 场景导入 Godot 并生成了CollisionShape3D节点树后导出时可以通过遍历节点树、对每个CollisionShape3D调用此方法恢复出 glTF 侧的形状描述。3.4 转换为节点to_nodeCollisionShape3D to_node(cache_shapes: bool false)将当前GLTFPhysicsShape实例转换为一个 GodotCollisionShape3D节点。cache_shapes参数默认false用于控制是否缓存生成的形状资源——在导入大量形状时启用缓存可以避免重复创建相同的Shape3D资源从而节省内存并加快导入速度。如前所述此方法不会处理is_trigger属性生成的节点具体挂载到Area3D还是物理刚体之下由调用方根据is_trigger决定。3.5 从资源解析from_resourcestatic GLTFPhysicsShape from_resource(shape_resource: Shape3D)静态方法从给定的 GodotShape3D资源创建一个新的GLTFPhysicsShape实例。与from_node的区别在于输入粒度Shape3D见 classes/class_shape3d.rst是 Godot 所有 3D 碰撞形状的抽象基类直接从形状资源而非节点提取信息。这在处理非节点形式持有的形状例如程序中直接构造的BoxShape3D、SphereShape3D等资源时更为直接。3.6 转换为资源to_resourceShape3D to_resource(cache_shapes: bool false)将当前GLTFPhysicsShape实例转换为一个 GodotShape3D资源。与to_node的关系是to_node内部通常会创建一个CollisionShape3D节点并把to_resource的结果赋给其shape属性。cache_shapes参数含义与to_node一致。四、形状类型与 Godot 物理形状的映射关系综合shape_type的六种取值与 Godot 的物理形状体系Shape3D的继承者列表见 classes/class_shape3d.rst可以整理出如下映射关系glTF shape_type语义对应的 Godot 形状使用的属性box立方体BoxShape3Dsizesphere球体SphereShape3Dradiuscapsule胶囊体CapsuleShape3Dradiusheightheight ≥ 2 × radiuscylinder圆柱体CylinderShape3Dradiusheighthull凸包ConvexPolygonShape3Dimporter_meshmesh_indextrimesh凹面三角网格ConcavePolygonShape3Dimporter_meshmesh_index值得注意的是性能特征Shape3D的文档中明确指出基础图元形状尤其是SphereShape3D的碰撞检测最快ConvexPolygonShape3D较慢而ConcavePolygonShape3D最慢。因此在设计 glTF 物理场景时优先使用图元形状仅在几何确实复杂时才退而使用凸包或三角网格可以显著提升物理性能。五、实战在运行时加载与保存含物理形状的 glTF 场景GLTFPhysicsShape并不仅服务于编辑器导入流程它同样工作在运行时。官方教程 tutorials/io/runtime_file_loading_and_saving.rst 中的3D scenes一节演示了如何在导出后的游戏中通过GLTFDocument与GLTFState加载 glTF 场景# 加载一个现有的 glTF 场景。 # GLTFState 用于存储被加载场景的状态。 # GLTFDocument 负责把 glTF 数据加载进 Godot 节点树 # 它支持 glTF 的光照、相机等功能也包括物理扩展。 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)) # 保存一个新的 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) # 输出 path 的扩展名.gltf 或 .glb决定文本或二进制格式。 # GLTFDocument.generate_buffer() 还可用于保存到内存。 gltf_document_save.write_to_filesystem(gltf_state_save, path)这段代码在运行时加载/保存场景时其中挂载了OMI_physics_shape扩展的节点就会被GLTFPhysicsShape处理——加载时生成CollisionShape3D子节点保存时重新序列化回扩展数据。具体而言GLTFDocument.generate_scene()内部会使用GLTFPhysicsShape.from_dictionary()解析扩展、to_node()生成碰撞节点GLTFDocument.append_from_scene()与write_to_filesystem()则会使用from_node()/from_resource()收集形状、to_dictionary()序列化。使用时的几点注意事项基路径从文件加载时基路径自动设为文件所在目录而从缓冲区buffer加载时必须手动设置GLTFState.base_path见 classes/class_gltfstate.rst否则外部资源无法正确加载二进制优先.glb二进制格式写入更快、体积更小优先用于运行时加载.gltf文本格式更易调试触发器处理加载后如果is_trigger为true需要手动将生成的CollisionShape3D作为Area3D的子节点加入场景才能获得触发器语义例如传感器、拾取区域、进入检测。5.1 在编辑器中导入含物理形状的 glTF在编辑器流程中用户只需在导入选项Import tab中启用 glTF 物理扩展的导入支持即可在导入 glTF 文件后于场景中得到CollisionShape3D节点树。整个过程的内部链路为glTF JSON → 扩展字典 →GLTFPhysicsShape.from_dictionary()→to_resource()生成Shape3D→to_node()包装为CollisionShape3D。正因为importer_mesh使用的是导入阶段的ImporterMesh所以形状生成发生在网格 LOD、阴影网格生成等后续导入步骤之前保证了物理形状使用的是原始几何数据。六、最佳实践与注意事项汇总综合官方文档的约束与 Godot 物理体系特性使用GLTFPhysicsShape时建议遵循以下实践按形状类型只设置相关属性size、radius、height、importer_mesh、mesh_index各有明确的适用范围对其他类型设置无效值不会产生预期的形状严格校验数值范围size、radius均不得为负capsule的高度不得小于半径的两倍否则无法构成有效胶囊几何优先使用图元形状四类图元box/sphere/capsule/cylinder碰撞检测开销远低于凸包与三角网格应优先选择合理利用缓存批量导入时给to_node()/to_resource()传入cache_shapes true可复用相同的Shape3D资源减少内存占用与构建开销触发器语义独立处理is_trigger不参与to_node()的生成逻辑需要在挂载节点时根据该值选择Area3D作为父节点理解字典格式的兼容性from_dictionary()/to_dictionary()遵循OMI_physics_shape格式未来若引入新的 glTF 物理扩展得益于类的抽象设计可在保持 API 不变的前提下扩展支持。七、总结GLTFPhysicsShape是 Godot 引擎 glTF 物理支持的核心数据类型它以字典 ↔ 实例 ↔ 节点/资源三层双向转换的抽象设计将OMI_physics_shape/OMI_collider扩展定义的六种物理形状box、capsule、cylinder、sphere、hull、trimesh无缝映射到 Godot 的Shape3D体系同时服务于编辑器导入流程与运行时加载/保存场景。理解其 7 个属性的适用范围与 6 个方法的对称转换关系是正确使用 Godot glTF 物理管线、以及未来扩展自定义 glTF 物理扩展的基础。延伸阅读物理刚体层面的对应类见 classes/class_gltfphysicsbody.rst碰撞节点与形状基类见 classes/class_collisionshape3d.rst 与 classes/class_shape3d.rstglTF 场景运行时加载的完整示例见 tutorials/io/runtime_file_loading_and_saving.rst。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 官方文档深度解读GLTFDocument 类——glTF 2.0 场景的运行时导入与导出完全指南Godot 官方文档深度解读GLTFDocument 类——glTF 2.0 场景的运行时导入与导出完全指南 导读 本文围绕 Godot 引擎内置的 GLTF文档教程游戏开发Godot CollisionShape3D 完全指南3D 物理碰撞体的形状节点与实战用法Godot CollisionShape3D 完全指南3D 物理碰撞体的形状节点与实战用法 导读 CollisionShape3D 是 Godot Engin文档教程游戏开发Apkmod自动化脚本编写如何批量处理多个APK文件进行安全审计Apkmod自动化脚本编写如何批量处理多个APK文件进行安全审计 想要高效地进行Android应用安全审计Apkmod自动化脚本编写技巧让你轻松实现批量AP上一篇Duilib高DPI开发陷阱常见问题与解决方案汇总下一篇Glaze与GSAP协同开发为什么这个轻量级框架能让你的动画代码减少60%创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
拿不准这条消息跟你有没有关系?
工种不同、批次不同,要求可能差很多。打电话把你的情况说清楚,我们按信阳、平顶山本地的口径给你捋一遍。