Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

GLTFDocument

继承： Resource < RefCounted < Object

派生： FBXDocument

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

描述

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

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

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

教程

属性

String	image_format	`"PNG"`
float	lossy_quality	`0.75`
RootNodeMode	root_node_mode	`0`

方法

Error	append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0)
Error	append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "")
Error	append_from_scene(node: Node, state: GLTFState, flags: int = 0)
GLTFObjectModelProperty	export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static
PackedByteArray	generate_buffer(state: GLTFState)
Node	generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true)
PackedStringArray	get_supported_gltf_extensions() static
GLTFObjectModelProperty	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
Error	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 场景根节点的名称，因为它不会被保存为节点。

属性说明

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

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