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	fallback_image_format	`"None"`
float	fallback_image_quality	`0.25`
String	image_format	`"PNG"`
float	lossy_quality	`0.75`
RootNodeMode	root_node_mode	`0`
TextureMapMode	texture_map_mode	`1`
VisibilityMode	visibility_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 场景根节点的名称，因为它不会被保存为节点。

enum TextureMapMode: 🔗

TextureMapMode TEXTURE_MAP_MODE_DO_NOT_REMAP = 0

直接导入 glTF 文件中的纹理贴图，而不尝试将其适配到适合 Godot 内置材质的特定纹理槽位中。如果将 glTF 文件与自定义着色器一起使用，这可能很理想；但在 Godot 的内置材质中可能无法正确显示。此设置等同于 Godot 4.6 及更早版本中的行为。

TextureMapMode TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL = 1

将 glTF 文件中的纹理贴图重新映射到基于 Godot StandardMaterial3D 类的最合适的纹理槽位中。这是默认行为。

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 及之前版本的行为一致。缺点：导出后的文件中不存在不可见节点。

flags ImportFlags: 🔗

ImportFlags IMPORT_FLAG_GENERATE_TANGENT_ARRAYS = 8

如果设为 true，当输入的网格体（meshes）没有切线数据时，将使用 Mikktspace 算法来生成顶点切线。如果条件允许，更推荐让 3D 建模软件在导出模型时直接生成切线，而不是依赖这个选项。法线贴图（normal maps）和高度贴图（height maps），以及任何需要切线的材质或着色器（shader）功能，都必须要有切线数据才能正确显示。

如果你不需要那些依赖切线的材质功能，禁用此选项可以在源 3D 文件不包含切线的情况下，减小输出文件的大小，并加快导入速度。

ImportFlags IMPORT_FLAG_USE_NAMED_SKIN_BINDS = 16

如果勾选此项，动画将使用带名称的 Skin（皮肤）资源。MeshInstance3D（网格实例 3D）节点在这里包含 3 个关键属性：一个指向 Skeleton3D（骨骼 3D）节点的骨架 NodePath（节点路径，通常是 ..）、一个网格（mesh），以及一个皮肤（skin）。

Skeleton3D 节点包含一个骨骼列表，其中记录了骨骼的名称、姿态（pose）和静止状态（rest），以及父级骨骼的信息。
网格（mesh）包含了显示模型所需的所有原始顶点数据。就网格本身而言，它知道顶点是如何进行权重绘制（weight-painted）的，并且使用了一些通常从 3D 建模软件导入的内部编号。
皮肤（skin）包含了将这个网格绑定到该 Skeleton3D 上所需的必要信息。对于 3D 建模软件选定的每一个内部骨骼 ID，它都包含两项内容。首先，是一个被称为“绑定姿态矩阵”、“反向绑定矩阵”或简称 IBM 的矩阵。其次，Skin 还包含每根骨骼的名称（如果启用了此标志），或者包含该骨骼在 Skeleton3D 列表中的索引（如果禁用了此标志）。

综合这些信息，就足以告诉 Godot 如何利用 Skeleton3D 节点中的骨骼姿态，来渲染每个 MeshInstance3D。请注意，每个 MeshInstance3D 可以共享绑定信息（这在从 Blender 导出的模型中很常见），或者每个 MeshInstance3D 也可以使用独立的 Skin 对象（这在从 Maya 等其他工具导出的模型中很常见）。

ImportFlags IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS = 32

在导入时忽略网格（Meshes）和材质（Materials）。当将场景作为 AnimationLibrary（动画库）进行导入时，此选项会始终处于启用状态。

ImportFlags IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION = 64

如果为 true，则不会使用网格压缩。如果你在网格法线或 UV 中发现块状伪影，或者如果你的网格在每个方向都大于几千米，请考虑启用。

属性说明

String fallback_image_format = "None" 🔗

void set_fallback_image_format(value: String)
String get_fallback_image_format()

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

该选项只能在“None”“PNG”“JPEG”中选择一个，只有在 image_format 不是“None”“PNG”“JPEG”三者之一时会用到。如果希望有多个扩展图像格式，可以使用 GLTFDocumentExtension 类来实现——此属性只适合在使用自定义图像格式时提供基本的 glTF 回退图像。

float fallback_image_quality = 0.25 🔗

void set_fallback_image_quality(value: float)
float get_fallback_image_quality()

回退图像的质量，可能不存在。对于 PNG 文件而言，会根据这个系数缩小图像的宽高。对于 JPEG 文件而言，则是图像的失真质量。建议使用较低的值，因为在 glTF 文件中包含多个高质量图像会抵消使用更高效图像格式所带来的文件大小优势。

String image_format = "PNG" 🔗

void set_image_format(value: String)
String get_image_format()

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

默认情况下，Godot 允许在“None”“PNG”“JPEG”“Lossless WebP”“Lossy 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()

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

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

TextureMapMode texture_map_mode = 1 🔗

void set_texture_map_mode(value: TextureMapMode)
TextureMapMode get_texture_map_mode()

导入时如何处理纹理贴图。默认且推荐的值是 TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL，它会自动将 glTF 灵活的纹理映射系统重新映射到 Godot 的 StandardMaterial3D 类中更具体的纹理贴图槽位。或者，可以使用 TEXTURE_MAP_MODE_DO_NOT_REMAP 来保留 glTF 文件中的原始纹理贴图，这在将 glTF 文件与自定义着色器一起使用时可能很理想，但在 Godot 的内置材质中可能无法正确显示。

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