GLTFDocument
继承： Resource < RefCounted < Object
派生： FBXDocument
用于在 Godot 中导入和导出 glTF 文件的类。
描述
GLTFDocument 支持从 glTF 文件、缓冲区或 Godot 场景中读取数据。然后可以将该数据写入文件系统、缓冲区或用于创建 Godot 场景。
glTF 场景中的所有数据都存储在 GLTFState 类中。GLTFDocument 处理状态对象，但本身不包含任何场景数据。GLTFDocument 有成员变量来存储如图像格式等导出配置设置，但在其他方面是无状态的。可以使用相同的 GLTFDocument 对象和不同的 GLTFState 对象以相同的设置处理多个场景。
通过扩展 GLTFDocumentExtension 类并通过 register_gltf_document_extension() 将其注册到 GLTFDocument，则可以使用任意功能来扩展 GLTFDocument。这允许自定义数据被导入和导出。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
方法
append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) |
|
append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") |
|
append_from_scene(node: Node, state: GLTFState, flags: int = 0) |
|
export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static |
|
generate_buffer(state: GLTFState) |
|
generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) |
|
get_supported_gltf_extensions() static |
|
import_object_model_property(state: GLTFState, json_pointer: String) static |
|
void |
register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static |
void |
unregister_gltf_document_extension(extension: GLTFDocumentExtension) static |
write_to_filesystem(state: GLTFState, path: String) |
枚举
enum RootNodeMode: 🔗
RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0
将 Godot 场景的根节点视为 glTF 文件的根节点，并通过 GODOT_single_root glTF 扩展将其标记为单根节点。如果实现不支持 GODOT_single_root，这将与 ROOT_NODE_MODE_KEEP_ROOT 进行相同的解析。
RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1
将 Godot 场景的根节点视为 glTF 文件的根节点，但不要将其标记为任何特殊的东西。导入 Godot 时会生成一个额外的根节点。这仅使用普通 glTF 功能。这相当于 Godot 4.1 及更早版本中的行为。
RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2
将 Godot 场景的根节点视为 glTF 场景的名称，并将其所有子节点添加为 glTF 文件的根节点。这仅使用普通 glTF 功能。这避免了额外的根节点，但只会保留 Godot 场景根节点的名称，因为它不会被保存为节点。
enum VisibilityMode: 🔗
VisibilityMode VISIBILITY_MODE_INCLUDE_REQUIRED = 0
如果场景中包含不可见节点，则会包含这些节点，使用 KHR_node_visibility 将它们标记为不可见，要求导入器将这些节点处理为不可见。缺点：如果导入器不支持 KHR_node_visibility 就无法导入该文件。
VisibilityMode VISIBILITY_MODE_INCLUDE_OPTIONAL = 1
如果场景中包含不可见节点，则会包含这些节点，使用 KHR_node_visibility 将它们标记为不可见，但并不对导入器施加任何要求。缺点：如果导入器不支持 KHR_node_visibility，本应不可见的对象就会可见。
VisibilityMode VISIBILITY_MODE_EXCLUDE = 2
如果场景中包含不可见节点，则导出的场景中不包含这些节点。与 Godot 4.4 及之前版本的行为一致。缺点：导出后的文件中不存在不可见节点。
属性说明
String fallback_image_format = "None" 🔗
回退图像格式的用户友好名称，用于导出 glTF 文件，包括写入文件和写入字节数组。
该选项只能在“None”“PNG”“JPEG”中选择一个，只有在 image_format 不是“None”“PNG”“JPEG”三者之一时会用到。如果希望有多个扩展图像格式，可以使用 GLTFDocumentExtension 类来实现——此属性只适合在使用自定义图像格式时提供基本的 glTF 回退图像。
float fallback_image_quality = 0.25 🔗
回退图像的质量，可能不存在。对于 PNG 文件而言，会根据这个系数缩小图像的宽高。对于 JPEG 文件而言，则是图像的失真质量。建议使用较低的值，因为在 glTF 文件中包含多个高质量图像会抵消使用更高效图像格式所带来的文件大小优势。
导出图像格式的用户友好名称，用于导出 glTF 文件，包括写入文件和写入字节数组。
默认情况下，Godot 允许在“None”“PNG”“JPEG”“Lossless WebP”“Lossy WebP”中选择一个。可以在 GLTFDocumentExtension 类中添加对更多图像格式的支持。一个扩展类可以提供对特定格式的多种选项，甚至可以提供一个同时使用多种格式的选项。
如果 image_format 是有损图像格式，则这决定了该图像的有损质量。在 0.0 到 1.0 范围内，其中 0.0 是最低质量，1.0 是最高质量。1.0 的有损质量不同于无损质量。
RootNodeMode root_node_mode = 0 🔗
void set_root_node_mode(value: RootNodeMode)
RootNodeMode get_root_node_mode()
导出时如何处理根节点。默认和推荐值为 ROOT_NODE_MODE_SINGLE_ROOT。
注意：无论 glTF 文件如何导出，导入时，根节点类型和名称都可以在场景导入设置选项卡中被覆盖。
VisibilityMode visibility_mode = 0 🔗
void set_visibility_mode(value: VisibilityMode)
VisibilityMode get_visibility_mode()
导出时如何处理节点的可见性。如果所有节点都可见，则该设置不做任何事情。默认推荐值为 VISIBILITY_MODE_INCLUDE_REQUIRED，使用 KHR_node_visibility 扩展。
方法说明
Error append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) 🔗
接受定义 glTF 的 PackedByteArray，将数据导入通过 state 参数给定的 GLTFState 对象。
注意：base_path 代表 append_from_buffer() 寻找依赖项的位置，可以为空。
Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗
接受 glTF 文件的路径，将文件路径处的数据导入通过 state 参数给定的 GLTFState 对象。
注意：base_path 代表 append_from_file() 寻找依赖项的位置，可以为空。
Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗
接收一个 Godot 引擎的场景节点，并通过 state 参数将其及其后代导出到给定的 GLTFState 对象。
GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗
确定给定 Godot node_path 与生成的 glTF 文件中相应的 glTF 对象模型 JSON 指针之间的映射。该映射的详细信息以 GLTFObjectModelProperty 对象的形式返回。可以通过 GLTFDocumentExtension._import_object_model_property() 回调方法提供额外的映射。
PackedByteArray generate_buffer(state: GLTFState) 🔗
通过 state 参数接收一个 GLTFState 对象，并返回一个 glTF PackedByteArray。
Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗
通过 state 参数接收一个 GLTFState 对象，并返回一个 Godot 引擎的场景节点。
bake_fps 参数会覆盖 state 中的 bake_fps。
PackedStringArray get_supported_gltf_extensions() static 🔗
返回所有支持的 glTF 扩展列表，包括引擎直接支持的扩展和用户插件注册的 GLTFDocumentExtension 类支持的扩展。
注意：如果在注册 GLTFDocumentExtension 之前运行该方法，则列表中不会包含它所对应的扩展。请确保在注册所有扩展后再运行该方法。如果在引擎启动时运行该方法，请考虑在调用g该方法之前等待一帧，确保所有扩展都已注册。
GLTFObjectModelProperty import_object_model_property(state: GLTFState, json_pointer: String) static 🔗
确定给定 glTF 对象模型 json_pointer 与生成的 Godot 场景中相应的 Godot 节点路径之间的映射。该映射的详细信息以 GLTFObjectModelProperty 对象的形式返回。可以通过 GLTFDocumentExtension._export_object_model_property() 回调方法提供额外的映射。
void register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static 🔗
使用 GLTFDocument 注册给定的 GLTFDocumentExtension 实例。如果 first_priority 为 true，则该扩展将被首先运行。否则，它将被最后运行。
注意：与 GLTFDocument 本身一样，所有 GLTFDocumentExtension 类都必须是无状态的才能正常运行。如果需要存储数据，使用 GLTFState 或 GLTFNode 中的 set_additional_data 和 get_additional_data 方法。
void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗
将给定的 GLTFDocumentExtension 实例取消注册。
Error write_to_filesystem(state: GLTFState, path: String) 🔗
通过 state 参数接收一个 GLTFState 对象，并将一个 glTF 文件写入文件系统。
注意：glTF 文件的扩展名决定了它是一个 .glb 二进制文件还是一个 .gltf 文本文件。