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...
API бінарної серіалізації
Вступ
Godot має API серіалізації на основі Variant. Він використовується для ефективного перетворення типів даних у масив байтів. Цей API доступний через глобальні функції bytes_to_var() та var_to_bytes(), але він також використовується в методах get_var та store_var класу FileAccess, а також у API пакетів для class_PacketPeer. Цей формат не використовується для бінарних сцен та ресурсів.
Повні об’єкти та ідентифікатори екземплярів об’єктів
Якщо змінну серіалізовано за допомогою full_objects = true, тоді будь-які об’єкти, що містяться в змінній, будуть серіалізовані та включені в результат. Це рекурсивно.
Якщо full_objects = false, то лише ідентифікатори екземплярів будуть серіалізовані для будь-яких об’єктів, що містяться у змінній.
Специфікація пакетів
Пакет розрахований на те, щоб завжди складатися з 4 байт. Усі значення закодовані у форматі little-endian. Всі пакети мають 4-байтовий заголовок, що представляє собою ціле число, яке вказує тип даних.
Два байти з найменшим значенням використовуються для визначення типу, тоді як два байти з найвищим значенням містять прапорці:
base_type = val & 0xFFFF;
flags = val >> 16;
Тип |
Значення |
|---|---|
0 |
нуль |
1 |
bool |
2 |
ціле число |
3 |
десяткове число |
4 |
текст |
5 |
vector2 |
6 |
rect 2 |
7 |
vector3 |
8 |
перетворення 2d |
9 |
площина |
10 |
кватерніон |
11 |
aabb |
12 |
основа |
13 |
перетворення 3d |
14 |
колір |
15 |
шлях вузла |
16 |
позбутися |
17 |
об'єкт |
18 |
словник |
19 |
масив |
20 |
необроблений масив |
21 |
масив int32 |
22 |
масив int64 |
23 |
масив float32 |
24 |
масив float64 |
25 |
масив з текстів |
26 |
масив з vector2 |
27 |
масив з vector3 |
28 |
масив з кольорів |
29 |
макс. |
Нижче наведено фактичний вміст пакета, який варіюється для кожного типу пакета. Зауважте, що тут припускається, що Godot скомпільований за замовчуванням, з десятковими одинарної точності. Якщо Godot був скомпільований з десятковими подвійними точності, довжина полів "Float" в структурах даних повинна бути 8, а зміщення повинно бути (offset - 4) * 2 + 4. Сам тип "float" завжди використовує подвійну точність.
0: нуль
1: bool
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
0 для False, 1 для True |
2: int
Якщо мітки не встановлені (flags == 0), ціле число надсилається як 32-розрядне ціле число:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Ціле число помічене, як 32-розрядне |
Якщо встановлена мітка ENCODE_FLAG_64 (flags & 1 == 1), ціле число надсилається, як 64-розрядне ціле число:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
8 |
Integer (ціле) |
Ціле число відмічене, як 64-розрядне |
3: float
Якщо мітка не встановлена (flags == 0), десяткове число надсилається, як 32 розрядне з одинарною точністю:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Десяткове число одинарної точності стандарту IEEE 754 |
Якщо встановлена мітка ENCODE_FLAG_64 (flags & 1 == 1), десяткове число надсилається, як 64 - розрядне десяткове число подвійної точності:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
8 |
Поплавок |
Десяткове число подвійної точності стандарту IEEE 754 |
4: String
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина тексту (в байтах) |
8 |
X |
Байти |
Текст закодований в UTF-8 |
Це поле вміщує до 4 байт.
5: Vector2
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Координата X |
8 |
4 |
Поплавок |
Координата Y |
6: Rect2
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Координата X |
8 |
4 |
Поплавок |
Координата Y |
12 |
4 |
Поплавок |
Розмір по X |
16 |
4 |
Поплавок |
Розмір по Y |
7: Vector3
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Координата X |
8 |
4 |
Поплавок |
Координата Y |
12 |
4 |
Поплавок |
Координата Z |
8: Transform2D
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0] |
8 |
4 |
Поплавок |
Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1] |
12 |
4 |
Поплавок |
Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0] |
16 |
4 |
Поплавок |
Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1] |
20 |
4 |
Поплавок |
Компонент X оригінального вектора, доступ до якого здійснюється через [2][0] |
24 |
4 |
Поплавок |
Компонент Y оригінального вектора, доступ до якого здійснюється через [2][1] |
9: Plane
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Нормаль по осі X |
8 |
4 |
Поплавок |
Нормаль по осі Y |
12 |
4 |
Поплавок |
Нормаль по осі Z |
16 |
4 |
Поплавок |
Відстань |
10: Quaternion
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Уявний X |
8 |
4 |
Поплавок |
Уявний Y |
12 |
4 |
Поплавок |
Уявний Z |
16 |
4 |
Поплавок |
Реальне W |
11: AABB
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Координата X |
8 |
4 |
Поплавок |
Координата Y |
12 |
4 |
Поплавок |
Координата Z |
16 |
4 |
Поплавок |
Розмір по X |
20 |
4 |
Поплавок |
Розмір по Y |
24 |
4 |
Поплавок |
Розмір по Z |
12: Basis
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0] |
8 |
4 |
Поплавок |
Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1] |
12 |
4 |
Поплавок |
Компонент Z вектора стовпця X, доступ до якого здійснюється через [0][2] |
16 |
4 |
Поплавок |
Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0] |
20 |
4 |
Поплавок |
Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1] |
24 |
4 |
Поплавок |
Компонент Z вектора стовпця Y, доступ до якого здійснюється через [1][2] |
28 |
4 |
Поплавок |
X компонент вектора стовпця Z, доступ до якого здійснюється через [2][0] |
32 |
4 |
Поплавок |
Компонент Y вектора стовпця Z, доступ до якого здійснюється через [2][1] |
36 |
4 |
Поплавок |
Компонент Z вектора стовпця Z, доступ до якого здійснюється через [2][2] |
13: Transform3D
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0] |
8 |
4 |
Поплавок |
Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1] |
12 |
4 |
Поплавок |
Компонент Z вектора стовпця X, доступ до якого здійснюється через [0][2] |
16 |
4 |
Поплавок |
Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0] |
20 |
4 |
Поплавок |
Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1] |
24 |
4 |
Поплавок |
Компонент Z вектора стовпця Y, доступ до якого здійснюється через [1][2] |
28 |
4 |
Поплавок |
X компонент вектора стовпця Z, доступ до якого здійснюється через [2][0] |
32 |
4 |
Поплавок |
Компонент Y вектора стовпця Z, доступ до якого здійснюється через [2][1] |
36 |
4 |
Поплавок |
Компонент Z вектора стовпця Z, доступ до якого здійснюється через [2][2] |
40 |
4 |
Поплавок |
Компонент X оригінального вектора, доступ до якого здійснюється через [3][0] |
44 |
4 |
Поплавок |
Компонент Y оригінального вектора, доступ до якого здійснюється через [3][1] |
48 |
4 |
Поплавок |
Компонент Z оригінального вектора, доступ до якого здійснюється через [3][2] |
14: Color
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Поплавок |
Червоний (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів) |
8 |
4 |
Поплавок |
Зелений (як правило, 0..1, може бути вище 1 для дуже яскравих кольорів) |
12 |
4 |
Поплавок |
Синій (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів) |
16 |
4 |
Поплавок |
Альфа (0..1) |
15: NodePath
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина тексту, або новий формат (val&0x80000000!=0 і NameCount=val&0x7FFFFFFF) |
Для старого формату:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
8 |
X |
Байти |
Текст закодований в UTF-8 |
Вміщає до 4 байт.
Для нового формату:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Кількість під-імен |
8 |
4 |
Integer (ціле) |
Мітки (абсолютні: val&1 != 0 ) |
Для кожного Імені та Під-Імені
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
X+0 |
4 |
Integer (ціле) |
Довжина тексту |
X+4 |
X |
Байти |
Текст закодований в UTF-8 |
Кожний текст імені вкладається в 4 байти.
16: RID (не підтримується)
17: Object
Об’єкт можна серіалізувати трьома різними способами: як нульове значення, за допомогою full_objects = false або full_objects = true.
Нульове значення
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Нуль (32-розрядне ціле число зі знаком) |
full_objects вимкнено
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
8 |
Integer (ціле) |
Ідентифікатор екземпляра об’єкта (64-розрядне ціле число зі знаком) |
full_objects увімкнено
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Назва класу (довжина рядка) |
8 |
X |
Байти |
Назва класу (рядок у кодуванні UTF-8) |
X+8 |
4 |
Integer (ціле) |
Кількість властивостей, які серіалізуються |
За кожну власність:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
Ю |
4 |
Integer (ціле) |
Назва властивості (довжина рядка) |
Y+4 |
З |
Байти |
Назва властивості (рядок у кодуванні UTF-8) |
Y+4+Z |
В |
<змінна> |
Значення властивості, використовуючи той самий формат |
Примітка
Не всі властивості включені. Буде серіалізовано лише властивості, налаштовані за допомогою прапорця PROPERTY_USAGE_STORAGE. Ви можете додати новий прапор використання до властивості, перевизначивши метод _get_property_list у вашому класі. Ви також можете перевірити, як налаштовано використання властивостей, викликавши Object._get_property_list. Перегляньте PropertyUsageFlags для можливих позначок використання.
18: Dictionary
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
val&0x7FFFFFFF = елементи, val&0x80000000 = спільний (булевий) |
Відповідно вся кількість "елементів", пар ключа і значення, один за одним використовують той самий формат.
19: Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
val&0x7FFFFFFF = елементи, val&0x80000000 = спільний (булевий) |
Відповідно, для кількості "елементів", значень один за одним, використовується той самий формат.
20: PackedByteArray
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Байти) |
8..8+довжина |
1 |
Байт |
Байт (0..255) |
Дані масиву вкладаються в 4 байти.
21: PackedInt32Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (цілі числа) |
8..8+довжина*4 |
4 |
Integer (ціле) |
Ціле число помічене, як 32-розрядне |
22: PackedInt64Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
8 |
Integer (ціле) |
Довжина масиву (цілі числа) |
8..8+довжина*8 |
8 |
Integer (ціле) |
Ціле число відмічене, як 64-розрядне |
23: PackedFloat32Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Десяткові числа) |
8..8+довжина*4 |
4 |
Integer (ціле) |
32-розрядний IEEE 754 одинарної точності з плаваючою точкою |
24: PackedFloat64Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Десяткові числа) |
8..8+довжина*8 |
8 |
Integer (ціле) |
64-розрядний IEEE 754 з плаваючою точкою подвійної точності |
25: PackedStringArray
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Текст) |
Для кожного Тексту:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
X+0 |
4 |
Integer (ціле) |
Довжина тексту |
X+4 |
X |
Байти |
Текст закодований в UTF-8 |
Кожен текст вкладається в 4 байти.
26: PackedVector2Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*8 |
4 |
Поплавок |
Координата X |
8..12+довжина*8 |
4 |
Поплавок |
Координата Y |
27: PackedVector3Array
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*12 |
4 |
Поплавок |
Координата X |
8..12+довжина*12 |
4 |
Поплавок |
Координата Y |
8..16+довжина*12 |
4 |
Поплавок |
Координата Z |
28: PackedColorArray
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*16 |
4 |
Поплавок |
Червоний (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів) |
8..12+довжина*16 |
4 |
Поплавок |
Зелений (як правило, 0..1, може бути вище 1 для дуже яскравих кольорів) |
8..16+довжина*16 |
4 |
Поплавок |
Синій (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів) |
8..20+довжина*16 |
4 |
Поплавок |
Альфа (0..1) |