GLTFDocument

继承： Resource < RefCounted < Object

派生： FBXDocument

用于在 Godot 中导入和导出 glTF 文件的类。

描述

GLTFDocument 支持从 glTF 文件、缓冲区或 Godot 场景中读取数据。然后可以将该数据写入文件系统、缓冲区或用于创建 Godot 场景。

GLTF 场景中的所有数据都存储在 GLTFState 类中。GLTFDocument 处理状态对象，但本身不包含任何场景数据。GLTFDocument 有成员变量来存储如图像格式等导出配置设置，但在其他方面是无状态的。可以使用相同的 GLTFDocument 对象和不同的 GLTFState 对象以相同的设置处理多个场景。

通过扩展 GLTFDocumentExtension 类并通过 register_gltf_document_extension 将其注册到 GLTFDocument，则可以使用任意功能来扩展 GLTFDocument。这允许自定义数据被导入和导出。

教程

• 运行时文件加载与保存

• glTF ‘鸭子是什么？’ 指南

• Khronos glTF 规范

属性

方法

枚举

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 场景根节点的名称，因为它不会被保存为节点。

属性说明

String image_format = "PNG" 🔗

• void set_image_format(value: String)

• String get_image_format()

导出图像格式的用户友好名称。这被用于导出 GLTF 文件，包括写入文件和写入字节数组。

默认情况下，Godot 允许以下选项：“无”、“PNG”、“JPEG”、“无损 WebP”和“有损 WebP”。可以使用 GLTFDocumentExtension 类添加对更多图像格式的支持。

float lossy_quality = 0.75 🔗

• void set_lossy_quality(value: float)

• float get_lossy_quality()

如果 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()

导出时如何处理根节点。详见 RootNodeMode。默认和推荐值为 ROOT_NODE_MODE_SINGLE_ROOT。

注意：无论 glTF 文件如何导出，导入时，根节点类型和名称都可以在场景导入设置选项卡中被覆盖。

方法说明

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 对象。

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。

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 文本文件。