Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

API бінарної серіалізації

Вступ

Godot has a serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is exposed via the global bytes_to_var() and var_to_bytes() functions, but it is also used in the get_var and store_var methods of FileAccess as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

Full Objects vs Object instance IDs

If a variable is serialized with full_objects = true, then any Objects contained in the variable will be serialized and included in the result. This is recursive.

If full_objects = false, then only the instance IDs will be serialized for any Objects contained in the variable.

Специфікація пакетів

Пакет розрахований на те, щоб завжди складатися з 4 байт. Усі значення закодовані у форматі little-endian. Всі пакети мають 4-байтовий заголовок, що представляє собою ціле число, яке вказує тип даних.

Для визначення типу використовуються найнижчі значення двох байтів, тоді як найбільше значення двох байтів містить мітки:

base_type = val & 0xFFFF;
flags = val >> 16;

Тип

Значення

0

нуль

1

bool

2

ціле число

3

десяткове число

4

текст

5

vector2

6

rect2

7

vector3

8

transform2d

9

площина

10

quaternion

11

aabb

12

basis

13

transform3d

14

колір

15

шлях вузла

16

rid

17

об'єкт

18

словник

19

масив

20

необроблений масив

21

int32 array

22

int64 array

23

float32 array

24

float64 array

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: десяткові

Якщо мітка не встановлена (flags == 0), десяткове число надсилається, як 32 розрядне з одинарною точністю:

Зміщення

Довжина

Тип

Опис

4

4

Float

Десяткове число одинарної точності стандарту IEEE 754

Якщо встановлена мітка ENCODE_FLAG_64 (flags & 1 == 1), десяткове число надсилається, як 64 - розрядне десяткове число подвійної точності:

Зміщення

Довжина

Тип

Опис

4

8

Float

Десяткове число подвійної точності стандарту IEEE 754

4: String

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина тексту (в байтах)

8

X

Байти

Текст закодований в UTF-8

Це поле вміщує до 4 байт.

5: Vector2

Зміщення

Довжина

Тип

Опис

4

4

Float

Координата X

8

4

Float

Координата Y

6: Rect2

Зміщення

Довжина

Тип

Опис

4

4

Float

Координата X

8

4

Float

Координата Y

12

4

Float

Розмір по X

16

4

Float

Розмір по Y

7: Vector3

Зміщення

Довжина

Тип

Опис

4

4

Float

Координата X

8

4

Float

Координата Y

12

4

Float

Координата Z

8: Transform2D

Зміщення

Довжина

Тип

Опис

4

4

Float

Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0]

8

4

Float

Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1]

12

4

Float

Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0]

16

4

Float

Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1]

20

4

Float

Компонент X оригінального вектора, доступ до якого здійснюється через [2][0]

24

4

Float

Компонент Y оригінального вектора, доступ до якого здійснюється через [2][1]

9: Plane

Зміщення

Довжина

Тип

Опис

4

4

Float

Нормаль по осі X

8

4

Float

Нормаль по осі Y

12

4

Float

Нормаль по осі Z

16

4

Float

Відстань

10: Quaternion

Зміщення

Довжина

Тип

Опис

4

4

Float

Уявний X

8

4

Float

Уявний Y

12

4

Float

Уявний Z

16

4

Float

Реальне W

11: AABB

Зміщення

Довжина

Тип

Опис

4

4

Float

Координата X

8

4

Float

Координата Y

12

4

Float

Координата Z

16

4

Float

Розмір по X

20

4

Float

Розмір по Y

24

4

Float

Розмір по Z

12: Basis

Зміщення

Довжина

Тип

Опис

4

4

Float

Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0]

8

4

Float

Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1]

12

4

Float

Компонент Z вектора стовпця X, доступ до якого здійснюється через [0][2]

16

4

Float

Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0]

20

4

Float

Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1]

24

4

Float

Компонент Z вектора стовпця Y, доступ до якого здійснюється через [1][2]

28

4

Float

X компонент вектора стовпця Z, доступ до якого здійснюється через [2][0]

32

4

Float

Компонент Y вектора стовпця Z, доступ до якого здійснюється через [2][1]

36

4

Float

Компонент Z вектора стовпця Z, доступ до якого здійснюється через [2][2]

13: Transform3D

Зміщення

Довжина

Тип

Опис

4

4

Float

Компонент X вектора стовпця X, доступ до якого здійснюється через [0][0]

8

4

Float

Компонент Y вектора стовпця X, доступ до якого здійснюється через [0][1]

12

4

Float

Компонент Z вектора стовпця X, доступ до якого здійснюється через [0][2]

16

4

Float

Компонент X вектора стовпця Y, доступ до якого здійснюється через [1][0]

20

4

Float

Компонент Y вектора стовпця Y, доступ до якого здійснюється через [1][1]

24

4

Float

Компонент Z вектора стовпця Y, доступ до якого здійснюється через [1][2]

28

4

Float

X компонент вектора стовпця Z, доступ до якого здійснюється через [2][0]

32

4

Float

Компонент Y вектора стовпця Z, доступ до якого здійснюється через [2][1]

36

4

Float

Компонент Z вектора стовпця Z, доступ до якого здійснюється через [2][2]

40

4

Float

Компонент X оригінального вектора, доступ до якого здійснюється через [3][0]

44

4

Float

Компонент Y оригінального вектора, доступ до якого здійснюється через [3][1]

48

4

Float

Компонент Z оригінального вектора, доступ до якого здійснюється через [3][2]

14: Color

Зміщення

Довжина

Тип

Опис

4

4

Float

Червоний (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів)

8

4

Float

Зелений (як правило, 0..1, може бути вище 1 для дуже яскравих кольорів)

12

4

Float

Синій (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів)

16

4

Float

Альфа (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

An Object could be serialized in three different ways: as a null value, with full_objects = false, or with full_objects = true.

A null value

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Zero (32-bit signed integer)

full_objects disabled

Зміщення

Довжина

Тип

Опис

4

8

Integer (ціле)

The Object instance ID (64-bit signed integer)

full_objects enabled

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Class name (String length)

8

X

Байти

Class name (UTF-8 encoded string)

X+8

4

Integer (ціле)

Кількість властивостей, які серіалізуються

За кожну власність:

Зміщення

Довжина

Тип

Опис

Y

4

Integer (ціле)

Property name (String length)

Y+4

Z

Байти

Property name (UTF-8 encoded string)

Y+4+Z

W

<variable>

Property value, using this same format

Примітка

Not all properties are included. Only properties that are configured with the PROPERTY_USAGE_STORAGE flag set will be serialized. You can add a new usage flag to a property by overriding the _get_property_list method in your class. You can also check how property usage is configured by calling Object._get_property_list See PropertyUsageFlags for the possible usage flags.

18: Dictionary

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

Відповідно вся кількість "елементів", пар ключа і значення, один за одним використовують той самий формат.

19: Array

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

Відповідно, для кількості "елементів", значень один за одним, використовується той самий формат.

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-bit IEEE 754 single-precision float

24: PackedFloat64Array

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина масиву (Десяткові числа)

8..8+довжина*8

8

Integer (ціле)

64-bit IEEE 754 double-precision float

25: PackedStringArray

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина масиву (Текст)

Для кожного Тексту:

Зміщення

Довжина

Тип

Опис

X+0

4

Integer (ціле)

Довжина тексту

X+4

X

Байти

Текст закодований в UTF-8

Кожен текст вкладається в 4 байти.

26: PackedVector2Array

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина масиву

8..8+довжина*8

4

Float

Координата X

8..12+довжина*8

4

Float

Координата Y

27: PackedVector3Array

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина масиву

8..8+довжина*12

4

Float

Координата X

8..12+довжина*12

4

Float

Координата Y

8..16+довжина*12

4

Float

Координата Z

28: PackedColorArray

Зміщення

Довжина

Тип

Опис

4

4

Integer (ціле)

Довжина масиву

8..8+довжина*16

4

Float

Червоний (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів)

8..12+довжина*16

4

Float

Зелений (як правило, 0..1, може бути вище 1 для дуже яскравих кольорів)

8..16+довжина*16

4

Float

Синій (зазвичай 0..1, може бути вище 1 для дуже яскравих кольорів)

8..20+довжина*16

4

Float

Альфа (0..1)