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...

Формат файлу TSCN

Формат файлу TSCN (текстова сцена) представляє одне дерево сцени всередині Godot. На відміну від бінарних файлів SCN, файли TSCN мають перевагу в тому, що вони здебільшого читаються людиною та легкі для керування системами контролю версій.

Формат файлу ESCN (експортована сцена) ідентичний формату файлу TSCN, але використовується для вказівки Godot, що файл було експортовано з іншої програми, і користувач не повинен редагувати його з Godot. На відміну від файлів SCN і TSCN, під час імпорту файли ESCN компілюються у двійкові файли SCN, які зберігаються в папці .godot/imported/. Це зменшує розмір даних і прискорює завантаження, оскільки двійкові формати завантажуються швидше порівняно з текстовими форматами.

Щоб зробити файли більш компактними, властивості, що дорівнюють значенню за замовчуванням, не зберігаються у файлах сцени/ресурсів. Їх можна записати вручну, але вони будуть видалені під час збереження файлу.

Для тих, хто шукає повний опис, розбір виконується у файлі resource_format_text.cpp у класі ResourceFormatLoaderText.

Примітка

Формати сцени та файлів ресурсів суттєво змінилися в Godot 4 із запровадженням UID на основі рядків замість інкрементних цілочисельних ідентифікаторів.

Дані сітки, скелета й анімації також зберігаються по-іншому порівняно з Godot 3. Ви можете прочитати про деякі зміни в цій статті: Переробка даних анімації для 4.0

Сцени та ресурси, збережені за допомогою Godot 4.x, містять format=3 у своєму заголовку, тоді як Godot 3.x замість цього використовує format=2.

Структура файлу

У файлі TSCN є п’ять основних розділів:

  1. Дескриптор файлу

  2. Зовнішні ресурси

  3. Внутрішні ресурси

  4. Вузли

  5. З'єднання

The file descriptor looks like [gd_scene format=3 uid="uid://cecaux1sm7mo0"] and should be the first entry in the file. Note that scenes saved before Godot 4.6 will also have a load_steps=<int> attribute in the file descriptor. This attribute is now deprecated and should be ignored if present.

uid - це унікальний ідентифікатор на основі рядка, що представляє сцену. Це використовується механізмом для відстеження файлів, які переміщуються, навіть коли редактор закрито. Сценарії також можуть завантажувати ресурси на основі UID за допомогою префікса шляху uid://, щоб не покладатися на шляхи файлової системи. Це дає змогу переміщатися по файлу в проекті, але мати можливість завантажувати його в сценарії без необхідності змінювати скрипт. Godot не використовує зовнішні файли для відстеження ідентифікаторів, що означає, що в проекті не потрібне центральне місце зберігання метаданих. Перегляньте цей запит на витягування для отримання детальної інформації.

Ці розділи мають відображатися в порядку, але їх може бути важко розрізнити. Єдиною відмінністю між ними є перший елемент у заголовку для всіх елементів розділу. Наприклад, заголовок усіх зовнішніх ресурсів має починатися з [ext_resource ...].

Файл TSCN може містити однорядкові коментарі, які починаються з крапки з комою (;). Однак коментарі буде відхилено під час збереження файлу за допомогою редактора Godot. Пробіли у файлі TSCN не є значущими (за винятком рядків), але сторонні пробіли будуть видалені під час збереження файлу.

Записи всередині файлу

Заголовок виглядає так: [<resource_type> key1=value1 key2=value2 key3=value3 ...], де resource_type є одним із:

  • ext_resource

  • sub_resource

  • node

  • connection

Під кожним заголовком міститься нуль або більше пар ключ = значення. Значеннями можуть бути складні типи даних, такі як масиви, перетворення, кольори тощо. Наприклад, Node3D виглядає так:

[node name="Cube" type="Node3D" unique_id=224283918]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 2, 3)

Дерево сцени

The scene tree is made up of… nodes! The heading of each node consists of its name, parent, a unique ID (used to track nodes even if they are moved or renamed), and most of the time, a type. For example: [node name="PlayerCamera" type="Camera" parent="Player/Head" unique_id=1697057368]

Note that unique_id is only present in scenes saved with Godot 4.6 or later. Therefore, it is not guaranteed to be present.

Інші дійсні ключові слова включають:

  • instance

  • instance_placeholder

  • owner

  • index (встановлює порядок появи в дереві; якщо його немає, успадковані вузли матимуть перевагу над звичайними)

  • groups

  • node_paths (lists names of properties exported as a Node type, but referenced as a NodePath in the file)

Перший вузол у файлі, який також є коренем сцени, не повинен мати запис parent="Path/To/Node" у своєму заголовку. Усі файли сцени повинні мати точно один корінь сцени. Якщо цього не станеться, Godot не зможе імпортувати файл. Батьківський шлях інших вузлів має бути абсолютним, але не повинен містити ім’я кореня сцени. Якщо вузол є прямим дочірнім елементом кореня сцени, шлях має бути ".". Ось приклад дерева сцени (але без вмісту вузла):

[node name="Player" type="Node3D" unique_id=1155673912]                    ; The scene root
[node name="Arm" type="Node3D" parent="." unique_id=1010797352]            ; Parented to the scene root
[node name="Hand" type="Node3D" parent="Arm" unique_id=536436825]          ; Child of "Arm"
[node name="Finger" type="Node3D" parent="Arm/Hand" unique_id=1732647084]  ; Child of "Hand"

Порада

Щоб полегшити сприйняття структури файлу, ви можете зберегти файл із будь-яким даним вузлом або ресурсом, а потім перевірити його самостійно у зовнішньому редакторі. Ви також можете вносити поступові зміни в редактор Godot і залишати зовнішній текстовий редактор відкритим у файлі .tscn або .tres з увімкненим автоматичним перезавантаженням, щоб побачити, які зміни.

Ось приклад сцени, що містить м’яч на основі RigidBody3D із зіткненням, візуальними елементами (сітка + світло) і камерою, пов’язаною з RigidBody3D:

[gd_scene format=3 uid="uid://cecaux1sm7mo0"]

[sub_resource type="SphereShape3D" id="SphereShape3D_tj6p1"]

[sub_resource type="SphereMesh" id="SphereMesh_4w3ye"]

[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_k54se"]
albedo_color = Color(1, 0.639216, 0.309804, 1)

[node name="Ball" type="RigidBody3D" unique_id=1358867382]

[node name="CollisionShape3D" type="CollisionShape3D" parent="." unique_id=1279975976]
shape = SubResource("SphereShape3D_tj6p1")

[node name="MeshInstance3D" type="MeshInstance3D" parent="." unique_id=558852834]
mesh = SubResource("SphereMesh_4w3ye")
surface_material_override/0 = SubResource("StandardMaterial3D_k54se")

[node name="OmniLight3D" type="OmniLight3D" parent="." unique_id=1581292810 node_paths=PackedStringArray("follow_node")]
light_color = Color(1, 0.698039, 0.321569, 1)
omni_range = 10.0
follow_node = NodePath("..")

[node name="Camera3D" type="Camera3D" parent="." unique_id=795715540]
transform = Transform3D(1, 0, 0, 0, 0.939693, 0.34202, 0, -0.34202, 0.939693, 0, 1, 3)

Шлях до вузла

Деревоподібної структури недостатньо для представлення всієї сцени. Godot використовує структуру NodePath(Path/To/Node) для посилання на інший вузол або атрибут вузла будь-де в дереві сцени. Шляхи відносяться до поточного вузла, при цьому NodePath(".") вказує на поточний вузол, а NodePath("") не вказує на жодний вузол.

Наприклад, MeshInstance3D використовує NodePath(), щоб вказати на свій скелет. Подібним чином доріжки анімації використовують NodePath(), щоб вказувати на властивості вузла для анімації.

NodePath також може вказувати на властивість за допомогою суфікса :property_name і навіть вказувати на певний компонент для векторних, трансформаційних і колірних типів. Це використовується ресурсами анімації для вказівки на певні властивості для анімації. Наприклад, NodePath("MeshInstance3D:scale.x") вказує на x компонент властивості scale Vector3 у MeshInstance3D.

Наприклад, властивість skeleton у вузлі MeshInstance3D під назвою mesh вказує на його батьківського елемента Armature01:

[node name="mesh" type="MeshInstance3D" parent="Armature01" unique_id=1638249225]
skeleton = NodePath("..")

Скелет 3D

Вузол class_Skeleton3D успадковує вузол Node3D, але також може мати список кісток, описаний у парах ключ-значення у форматі кістки/<id>/<атрибут> = значення. Атрибути кісток складаються з:

  • position: Vector3

  • rotation: Кватерніон

  • scale: Vector3

Усі ці атрибути необов’язкові. Наприклад, кістка може визначати лише положення або обертання без визначення інших властивостей.

Ось приклад вузла скелета з двома кістками:

[node name="Skeleton3D" type="Skeleton3D" parent="PlayerModel/Robot_Skeleton" index="0" unique_id=542985694]
bones/1/position = Vector3(0.114471, 2.19771, -0.197845)
bones/1/rotation = Quaternion(0.191422, -0.0471201, -0.00831942, 0.980341)
bones/2/position = Vector3(-2.59096e-05, 0.236002, 0.000347473)
bones/2/rotation = Quaternion(-0.0580488, 0.0310587, -0.0085914, 0.997794)
bones/2/scale = Vector3(0.9276, 0.9276, 0.9276)

Кісткове кріплення 3D

Вузол BoneAttachment3D є проміжним вузлом для опису деякого вузла, який є батьківським для однієї кістки у вузлі Skeleton. BoneAttachment має властивість bone_name = "name of bone", а також властивість для відповідного індексу кістки.

Приклад вузла Marker3D, доданого до кістки в Skeleton:

[node name="GunBone" type="BoneAttachment3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D" index="5" unique_id=63481392]
transform = Transform3D(0.333531, 0.128981, -0.933896, 0.567174, 0.763886, 0.308015, 0.753209, -0.632331, 0.181604, -0.323915, 1.07098, 0.0497144)
bone_name = "hand.R"
bone_idx = 55

[node name="ShootFrom" type="Marker3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D/GunBone" unique_id=679926736]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.4, 0)

Анімований Гравець

Вузол AnimationPlayer працює з однією або кількома бібліотеками анімації, що зберігаються в ресурсах AnimationLibrary. Бібліотека анімації — це набір окремих ресурсів Animation, структура яких задокументована тут.

Цей розподіл між самими анімаціями та бібліотеками анімацій було зроблено в Godot 4, щоб анімації можна було імпортувати окремо від 3D-сіток, що є звичайним робочим процесом у програмному забезпеченні для 3D-анімації. Перегляньте оригінальний запит на витягування для деталей.

Якщо назва бібліотеки порожня, то вона виступає в якості єдиного джерела анімації для цього AnimationPlayer. Це дозволяє використовувати <animation_name> безпосередньо для відтворення анімації зі скрипта. Якщо ви даєте назву бібліотеці, то ви повинні відтворювати її як <library_name>/<animation_name>. Це забезпечує зворотну сумісність і зберігає існуючий робочий процес, якщо ви не хочете використовувати кілька бібліотек анімації.

Ресурси

Ресурси - це компоненти, які складають вузли. Наприклад, вузол MeshInstance3D матиме супровідний ресурс ArrayMesh. Ресурс ArrayMesh може бути внутрішнім або зовнішнім щодо файлу TSCN.

Посилання на ресурси обробляються унікальними ідентифікаторами на основі рядків у заголовку ресурсу. Це відрізняється від властивості uid, яку також має кожен зовнішній ресурс (але не субресурси).

External resources and internal resources are referred to with ExtResource("id") and SubResource("id"), respectively. Because there are different methods to refer to internal and external resources, you can have the same ID for both an internal and external resource.

Наприклад, щоб звернутися до ресурсу [ext_resource type="Material" uid="uid://c4cp0al3ljsjv" path="res://material.tres" id="1_7bt6s"], потрібно використовувати ExtResource("1_7bt6s").

Зовнішні ресурси

Зовнішні ресурси – це посилання на ресурси, які не містяться в самому файлі TSCN. Зовнішній ресурс складається з шляху, типу, UID (використовується для зіставлення розташування його файлової системи з унікальним ідентифікатором) та ID (використовується для посилання на ресурс у файлі сцени).

Godot завжди створює абсолютні шляхи відносно каталогу ресурсів і, таким чином, із префіксом res://, але шляхи відносно розташування файлу TSCN також є дійсними.

Ось декілька прикладів зовнішніх ресурсів:

[ext_resource type="Texture2D" uid="uid://ccbm14ebjmpy1" path="res://gradient.tres" id="2_eorut"]
[ext_resource type="Material" uid="uid://c4cp0al3ljsjv" path="material.tres" id="1_7bt6s"]

Подібно до файлів TSCN, файл TRES може містити однорядкові коментарі, що починаються з крапки з комою (;). Однак при збереженні ресурсу за допомогою редактора Godot коментарі будуть видалені. Пробіли у файлі TRES незначні (за винятком рядків), але сторонні пробіли будуть відкинуті під час збереження файлу.

Внутрішні ресурси

Файл TSCN може містити сітки, матеріали та інші дані. Вони містяться в розділі внутрішні ресурси файлу. Заголовок внутрішнього ресурсу виглядає подібно до заголовків зовнішніх ресурсів, за винятком того, що він не має шляху. Внутрішні ресурси також мають пари key=value під кожним заголовком. Наприклад, форма зіткнення капсули виглядає так:

[sub_resource type="CapsuleShape3D" id="CapsuleShape3D_fdxgg"]
radius = 1.0
height = 3.0

Деякі внутрішні ресурси містять посилання на інші внутрішні ресурси (наприклад, сітку з матеріалом). У цьому випадку посилання на ресурс має бути перед посиланням на нього. Це означає, що порядок у розділі внутрішніх ресурсів файлу має значення.

ArrayMesh

ArrayMesh складається з кількох поверхонь, які містяться в масиві _surfaces (зверніть увагу на підкреслення на початку). Дані кожної поверхні зберігаються в словнику з такими ключами:

  • aabb: обчислена обмежувальна рамка, вирівняна по осі для видимості.

  • attribute_data: дані атрибутів вершин, такі як нормалі, дотичні, кольори вершин, UV1, UV2 і спеціальні дані вершин.

  • bone_aabbs: вирівняна по осі обмежувальна рамка кожної кістки для видимості.

  • format: формат буфера поверхні.

  • index_count: кількість індексів на поверхні. Він має відповідати розміру index_data.

  • index_data: дані індексу, які визначають, які вершини з vertex_data малюються.

  • lods: варіації рівня деталізації, збережені у вигляді масиву. Кожен рівень LOD представляє два значення в масиві. Перше значення — це відсоток простору на екрані, для якого найбільше підходить рівень LOD (довжина краю); друге значення — це список індексів, які слід намалювати для даного рівня LOD.

  • material: матеріал, який використовується для малювання поверхні.

  • name: назва поверхні. Це можна використовувати в сценаріях і імпортовано з 3D DCC.

  • primitive: примітивний тип поверхні, що відповідає переліку Godot Mesh.PrimitiveType. 0 = точки, 1 = лінії, 2 = смуга лінії, 3 = трикутники (найчастіше), 4 = смуга трикутника.

  • skin_data: дані про вагу кісток.

  • vertex_count: кількість вершин на поверхні. Він має відповідати розміру vertex_data.

  • vertex_data: Дані позиції вершини.

Ось приклад ArrayMesh, збереженого у власному файлі .tres. Для стислості деякі поля були скорочені за допомогою ...:

[gd_resource type="ArrayMesh" format=3 uid="uid://dww8o7hsqrhx5"]

[ext_resource type="Material" path="res://player/model/playerobot.tres" id="1_r3bjq"]

[resource]
resource_name = "player_Sphere_016"
_surfaces = [{
"aabb": AABB(-0.207928, 1.21409, -0.14545, 0.415856, 0.226569, 0.223374),
"attribute_data": PackedByteArray(63, 121, ..., 117, 63),
"bone_aabbs": [AABB(0, 0, 0, -1, -1, -1), ..., AABB(-0.207928, 1.21409, -0.14545, 0.134291, 0.226569, 0.223374)],
"format": 7191,
"index_count": 1224,
"index_data": PackedByteArray(30, 0, ..., 150, 4),
"lods": [0.0382013, PackedByteArray(33, 1, ..., 150, 4)],
"material": ExtResource("1_r3bjq"),
"name": "playerobot",
"primitive": 3,
"skin_data": PackedByteArray(15, 0, ..., 0, 0),
"vertex_count": 1250,
"vertex_data": PackedByteArray(196, 169, ..., 11, 38)
}]
blend_shape_mode = 0

Анімація

Кожна анімація має такі властивості:

  • length: тривалість анімації в секундах. Зауважте, що ключові кадри можуть бути розміщені за межами [0; length] інтервал, але вони можуть не мати ефекту залежно від вибраного режиму інтерполяції.

  • loop_mode: 0 = відсутність циклу, 1 = обертання циклу, 2 = затиснуте цикл.

  • step: Розмір кроку, який використовується під час редагування цієї анімації в редакторі. Це використовується лише в редакторі; це жодним чином не впливає на відтворення анімації.

Кожен трек описується списком пар ключ-значення у форматі tracks/<id>/<attribute>. Кожен трек містить:

  • type: тип доріжки. Це визначає, які типи властивостей можуть бути анімовані цією доріжкою, і як вона буде представлена користувачеві в редакторі. Дійсні типи: value (загальний трек властивості), position_3d, rotation_3d, scale_3d, blend_shape (оптимізовані доріжки 3D-анімації), method ( треки виклику методу), bezier (доріжки кривої Безьє), audio (доріжки відтворення аудіо), animation (доріжки, які відтворюють інші анімації).

  • imported: true, якщо доріжка була створена з імпортованої 3D-сцени, false, якщо вона була створена користувачем вручну в редакторі Godot або за допомогою сценарію.

  • enabled: true, якщо трек діє, false, якщо він був вимкнений у редакторі.

  • path: Шлях до властивості вузла, на який впливатиме трек. Властивість записується після шляху вузла з роздільником :.

  • interp: режим інтерполяції для використання. 0 = найближчий, 1 = лінійний, 2 = кубічний, 3 = лінійний кут, 4 = кубічний кут.

  • loop_wrap: true, якщо доріжка призначена для обертання, коли анімація повторюється, false, якщо доріжка закріплюється за першим/останнім ключовим кадром.

  • keys: значення доріжки анімації. Структура цього атрибута залежить від типу.

Ось сцена, що містить AnimationPlayer, який зменшує масштаб куба з часом за допомогою загальної доріжки властивостей. Робочий процес AnimationLibrary не використовувався, тому бібліотека анімації має порожнє ім’я (але анімація все ще має назву scale_down). Зауважте, що трек RESET не було створено в цьому AnimationPlayer для стислості:

[gd_scene format=3 uid="uid://cdyt3nktp6y6"]

[sub_resource type="Animation" id="Animation_r2qdp"]
resource_name = "scale_down"
length = 1.5
loop_mode = 2
step = 0.05
tracks/0/type = "value"
tracks/0/imported = false
tracks/0/enabled = true
tracks/0/path = NodePath("Box:scale")
tracks/0/interp = 1
tracks/0/loop_wrap = true
tracks/0/keys = {
"times": PackedFloat32Array(0, 1),
"transitions": PackedFloat32Array(1, 1),
"update": 0,
"values": [Vector3(1, 1, 1), Vector3(0, 0, 0)]
}

[sub_resource type="AnimationLibrary" id="AnimationLibrary_4qx36"]
_data = {
"scale_down": SubResource("Animation_r2qdp")
}

[sub_resource type="BoxMesh" id="BoxMesh_u688r"]

[node name="Node3D" type="Node3D" unique_id=2076735200]

[node name="AnimationPlayer" type="AnimationPlayer" parent="." unique_id=2139773137]
autoplay = "scale_down"
libraries = {
"": SubResource("AnimationLibrary_4qx36")
}

[node name="Box" type="MeshInstance3D" parent="." unique_id=711004519]
mesh = SubResource("BoxMesh_u688r")

Для відстежування універсальної властивості value, keys – це словник, що містить 3 масиви з позиціями в times (PackedFloat32Array), значеннями полегшення в transitions (PackedFloat32Array) та значеннями в values (Array). Існує додаткова властивість update, яка є цілим числом зі значеннями 0 = безперервний, 1 = дискретний, 2 = захоплення.

Ось другий ресурс анімації, який використовує доріжки 3D Position і 3D Rotation. Ці треки (на додаток до треку 3D Scale) замінюють треки Transform із Godot 3. Вони оптимізовані для швидкого відтворення та, за бажанням, можуть бути стиснуті.

Недоліком цих оптимізованих типів відстеження є те, що вони не можуть використовувати користувацькі значення easing. Натомість усі ключові кадри використовують лінійну інтерполяцію. Тим не менш, ви все ще можете вибрати використання найближчої або кубічної інтерполяції для всіх ключових кадрів у певній доріжці, змінивши режим інтерполяції доріжки.

[sub_resource type="Animation" id="Animation_r2qdp"]
resource_name = "move_and_rotate"
length = 1.5
loop_mode = 2
step = 0.05
tracks/0/type = "position_3d"
tracks/0/imported = false
tracks/0/enabled = true
tracks/0/path = NodePath("Box")
tracks/0/interp = 1
tracks/0/loop_wrap = true
tracks/0/keys = PackedFloat32Array(0, 1, 0, 0, 0, 1.5, 1, 1.5, 1, 0)
tracks/1/type = "rotation_3d"
tracks/1/imported = false
tracks/1/enabled = true
tracks/1/path = NodePath("Box")
tracks/1/interp = 1
tracks/1/loop_wrap = true
tracks/1/keys = PackedFloat32Array(0, 1, 0.211, -0.047, 0.211, 0.953, 1.5, 1, 0.005, 0.976, -0.216, 0.022)

Для доріжок 3D-позиції, обертання та масштабування, keys є масивом PackedFloat32Array, усі значення якого зберігаються у послідовності.

У наведеному нижче візуальному посібнику T — це час ключового кадру в секундах від початку анімації, E — це перехід ключового кадру (наразі завжди 1). Для тривимірних треків позиції та масштабу X, Y, Z є координатами Vector3. Для тривимірних доріжок обертання X, Y, Z і W є координатами кватерніону.

# For 3D position and scale, which use Vector3:
tracks/<id>/keys = PackedFloat32Array(T, E,   X, Y, Z,      T, E,   X, Y, Z, ...)

# For 3D rotation, which use Quaternion:
tracks/<id>/keys = PackedFloat32Array(T, E,   X, Y, Z, W,      T, E,   X, Y, Z, W, ...)