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(). Це дозволяє імпортувати й експортувати спеціальні дані.
Посібники
Властивості
String |
|
|
|
||
String |
|
|
|
||
|
||
|
||
|
Методи
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 |
|
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 |
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. Це буде поданий тим самим, як ROOT_NODE_MODE_KEEP_ROOT, якщо реалізація не підтримує GODOT_single_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
Import the texture maps in the glTF file as they are, without trying to fit them into specific texture slots suitable for Godot's built-in materials. This may be desirable if using the glTF file with custom shaders, but may not display correctly with Godot's built-in materials. This is equivalent to the behavior in Godot 4.6 and earlier.
TextureMapMode TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL = 1
Import the texture maps in the glTF file remapped to the most suitable texture slots based on Godot's StandardMaterial3D class. This is the default behavior.
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
If true, generate vertex tangents using Mikktspace if the input meshes don't have tangent data. When possible, it's recommended to let the 3D modeling software generate tangents on export instead of relying on this option. Tangents are required for correct display of normal and height maps, along with any material/shader features that require tangents.
If you don't need material features that require tangents, disabling this can reduce output file size and speed up importing if the source 3D file doesn't contain tangents.
ImportFlags IMPORT_FLAG_USE_NAMED_SKIN_BINDS = 16
If checked, use named Skins for animation. The MeshInstance3D node contains 3 properties of relevance here: a skeleton NodePath pointing to the Skeleton3D node (usually ..), a mesh, and a skin:
The Skeleton3D node contains a list of bones with names, their pose and rest, a name, and a parent bone.
The mesh is all of the raw vertex data needed to display a mesh. In terms of the mesh, it knows how vertices are weight-painted and uses some internal numbering often imported from 3D modeling software.
The skin contains the information necessary to bind this mesh onto this Skeleton3D. For each of the internal bone IDs chosen by the 3D modeling software, it contains two things. Firstly, a matrix known as the Bind Pose Matrix, Inverse Bind Matrix, or IBM for short. Secondly, the Skin contains each bone's name (if this flag is enabled), or the bone's index within the Skeleton3D list (if this flag is disabled).
Together, this information is enough to tell Godot how to use the bone poses in the Skeleton3D node to render the mesh from each MeshInstance3D. Note that each MeshInstance3D may share binds, as is common in models exported from Blender, or each MeshInstance3D may use a separate Skin object, as is common in models exported from other tools such as Maya.
ImportFlags IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS = 32
Ignore meshes and materials on import. When importing a scene as an AnimationLibrary, this flag is always enabled.
ImportFlags IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION = 64
Якщо true, стиснення сітки не буде використовуватися. З огляду на те, що ви помітили блоковані артефакти у ваших сітчастих нормах або УФ, або якщо у вас є сітки, які більше, ніж кілька тисяч метрів в кожному напрямку.
Описи властивостей
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 🔗
Якість резервного зображення, якщо таке є. Для файлів 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. Один клас розширення може надавати кілька параметрів для використання певного формату або навіть параметр, який використовує кілька форматів одночасно.
Якщо пам'ятати зображення_формат є форматом образу, це визначає якість втрати зображення. 0.0 to 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()
How to handle texture maps during import. The default and recommended value is TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL, which automatically remaps from glTF's flexible texture map system to the more specific texture map slots in Godot's StandardMaterial3D class. Alternatively, TEXTURE_MAP_MODE_DO_NOT_REMAP can be used to preserve the original texture maps from the glTF file, which may be desirable if using the glTF file with custom shaders, but may not display correctly with Godot's built-in materials.
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.
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.
Параметри параметра fix_fps наділяє пекарні_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.