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
Класс для импорта и экспорта файлов glTF в Godot и из него.
Описание
GLTFDocument поддерживает чтение данных из файла glTF, буфера или сцены Godot. Затем эти данные можно записать в файловую систему, буфер или использовать для создания сцены Godot.
Все данные в сцене glTF хранятся в классе GLTFState. GLTFDocument обрабатывает объекты состояния, но не содержит никаких данных самой сцены. GLTFDocument имеет переменные-члены для хранения параметров конфигурации экспорта, таких как формат изображения, но в остальном не имеет состояния. Несколько сцен можно обрабатывать с теми же настройками, используя тот же объект GLTFDocument и разные объекты GLTFState.
GLTFDocument можно расширить с помощью произвольной функциональности, расширив класс GLTFDocumentExtension и зарегистрировав его в GLTFDocument через register_gltf_document_extension(). Это позволяет импортировать и экспортировать пользовательские данные.
Обучающие материалы
Свойства
|
||
|
||
|
||
|
||
|
||
|
||
|
Методы
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 и отмечать его как единственный корневой узел с помощью расширения glTF GODOT_single_root. Это будет проанализировано так же, как ROOT_NODE_MODE_KEEP_ROOT, если реализация не поддерживает GODOT_single_root.
RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1
Обрабатывайте корневой узел сцены Godot как корневой узел файла glTF, но не помечайте его как что-то особенное. При импорте в Godot будет сгенерирован дополнительный корневой узел. Это использует только функции vanilla 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, переназначив их на наиболее подходящие слоты текстур в соответствии с классом StandardMaterial3D 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 и более ранних версиях. Недостаток: невидимые узлы не будут существовать в экспортированном файле.
flags ImportFlags: 🔗
ImportFlags IMPORT_FLAG_GENERATE_TANGENT_ARRAYS = 8
Если true, сгенерируйте касательные вершины с помощью Mikktspace, если входные сетки не содержат данных о касательных. По возможности рекомендуется позволить программному обеспечению для 3D-моделирования генерировать касательные при экспорте, а не полагаться на эту опцию. Касательные необходимы для корректного отображения карт нормалей и высот, а также любых функций материала/шейдера, требующих касательных.
Если вам не нужны функции материала, требующие касательных, отключение этой опции может уменьшить размер выходного файла и ускорить импорт, если исходный 3D-файл не содержит касательных.
ImportFlags IMPORT_FLAG_USE_NAMED_SKIN_BINDS = 16
Если этот параметр отмечен, используйте именованные Skin для анимации. Узел MeshInstance3D содержит 3 важных свойства: скелет NodePath, указывающий на узел Skeleton3D (обычно ..), сетку и скин:
Узел Skeleton3D содержит список костей с именами, их позами и состояниями покоя, имя и родительскую кость.
Сетка содержит все необходимые данные о вершинах для отображения сетки. С точки зрения сетки, она знает, как происходит распределение весов вершин, и использует некоторую внутреннюю нумерацию, часто импортируемую из программного обеспечения для 3D-моделирования.
Скин содержит информацию, необходимую для привязки этой сетки к этому Skeleton3D. Для каждого из внутренних идентификаторов костей, выбранных программным обеспечением для 3D-моделирования, он содержит две вещи. Во-первых, матрицу, известную как матрица привязки позы, обратная матрица привязки или сокращенно IBM. Во-вторых, Skin содержит имя каждой кости (если этот флаг включен) или индекс кости в списке Skeleton3D (если этот флаг отключен).
Вместе эта информация достаточна, чтобы сообщить Godot, как использовать позы костей в узле Skeleton3D и для рендеринга сетки каждого MeshInstance3D. Обратите внимание, что каждый MeshInstance3D может использовать общие привязки, как это часто бывает в моделях, экспортированных из Blender, или каждый MeshInstance3D может использовать отдельный объект Skin, как это часто бывает в моделях, экспортированных из других инструментов, таких как Maya.
ImportFlags IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS = 32
Игнорировать сетки и материалы при импорте. При импорте сцены в формате AnimationLibrary этот флаг всегда включен.
ImportFlags IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION = 64
Если true, сжатие сетки не будет использоваться. Рассмотрите возможность включения, если вы заметили блочные артефакты в нормалях сетки или UV, или если у вас есть сетки, которые больше нескольких тысяч метров в каждом направлении.
Описания свойств
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 — это формат изображения с потерями (lossy), это определяет качество изображения с потерями. В диапазоне от 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 на более специфические слоты текстурных карт в классе StandardMaterial3D Godot. В качестве альтернативы можно использовать 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) 🔗
Принимает PackedByteArray, определяющий glTF, и импортирует данные в заданный объект GLTFState через параметр state.
Примечание: base_path сообщает append_from_buffer(), где найти зависимости, и может быть пустым.
Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗
Берет путь к файлу glTF и импортирует данные по этому пути к файлу в указанный объект GLTFState через параметр state.
Примечание: Параметр base_path сообщает append_from_file(), где искать зависимости, и может быть пустым.
Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗
Берет узел сцены Godot Engine и экспортирует его и его потомков в заданный объект GLTFState через параметр state.
GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗
Определяет сопоставление между заданным Godot node_path и соответствующим указателем(ями) JSON объектной модели glTF в сгенерированном файле glTF. Подробности этого сопоставления возвращаются в объекте GLTFObjectModelProperty. Дополнительные сопоставления могут быть предоставлены с помощью метода обратного вызова GLTFDocumentExtension._import_object_model_property().
PackedByteArray generate_buffer(state: GLTFState) 🔗
Принимает объект GLTFState через параметр state и возвращает glTF PackedByteArray.
Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗
Принимает объект GLTFState через параметр state и возвращает узел сцены Godot Engine.
Параметр bake_fps переопределяет bake_fps в state.
PackedStringArray get_supported_gltf_extensions() static 🔗
Возвращает список всех поддерживаемых расширений glTF, включая расширения, поддерживаемые непосредственно движком, и расширения, поддерживаемые пользовательскими плагинами, регистрирующими классы GLTFDocumentExtension.
Примечание: Если этот метод запущен до регистрации GLTFDocumentExtension, его расширения не будут включены в список. Обязательно запускайте этот метод только после регистрации всех расширений. Если вы запускаете его при запуске движка, рассмотрите возможность ожидания кадра перед вызовом этого метода, чтобы убедиться, что все расширения зарегистрированы.
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 🔗
Регистрирует заданный экземпляр GLTFDocumentExtension с GLTFDocument. Если first_priority равен true, это расширение будет запущено первым. В противном случае оно будет запущено последним.
Примечание: Как и сам GLTFDocument, все классы GLTFDocumentExtension должны быть без состояния для правильной работы. Если вам нужно сохранить данные, используйте методы set_additional_data и get_additional_data в GLTFState или GLTFNode.
void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗
Отменяет регистрацию указанного экземпляра GLTFDocumentExtension.
Error write_to_filesystem(state: GLTFState, path: String) 🔗
Принимает объект GLTFState через параметр state и записывает файл glTF в файловую систему.
Примечание: Расширение файла glTF определяет, является ли он двоичным файлом .glb или текстовым файлом .gltf.