Work in progress

The content of this page was not yet updated for Godot 4.4 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 имеет API сериализации, основанный на Variant. Он используется для эффективного преобразования типов данных в массив байтов. Этот API доступен через глобальные функции bytes_to_var() и var_to_bytes(), а также в методах get_var и store_var класса FileAccess, а также в пакетных API для PacketPeer. Этот формат не используется для двоичных сцен и ресурсов.

Полные Objects vs Object instance IDs

Если переменная сериализована с full_objects = true, то все объекты, содержащиеся в этой переменной, будут сериализованы и включены в результат. Это рекурсивно.

Если full_objects = false, то для всех объектов, содержащихся в переменной, будут сериализованы только идентификаторы экземпляров.

Пакетная сериализация

Пакет спроектирован всегда укладываться в 4 байта. Все значения закодированы от младшего к старшему(little endian). Все пакеты имеют целочисленный заголовок в 4 байта, определяющий тип данных.

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

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

Тип	Значение
0	null
1	bool
2	integer
3	float
4	string
5	vector2
6	rеct2
7	vector3
8	trаnsform2d
9	plаne
10	quaternion (кватернион)
11	аabb
12	bаsis
13	transform3d
14	color (цвет)
15	node path (путь к узлу)
16	rіd
17	object (объект)
18	dictionary (словарь)
19	array (массив)
20	raw array (необработанный массив)
21	int32 array
22	int64 array
23	float32 array
24	float64 array
25	строковый массив
26	vector2 массив
27	vector3 массив
28	цветовая матрица
29	max

После этого следует фактическое содержимое пакета, которое различается для каждого типа пакета. Обратите внимание, что здесь предполагается, что Godot скомпилирован с плавающей точкой одинарной точности, что является значением по умолчанию. Если Godot был скомпилирован с плавающей точкой двойной точности, длина полей "Float" в структурах данных должна быть 8, а смещение должно быть (смещение - 4) * 2 + 4. Сам тип "float" всегда использует двойную точность.

0: null

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), то float передается как 32-битное число одинарной точности:

Отступ	Длина	Тип	Описание
4	4	Float	IEEE 754 одноточечное число с плавающей запятой

Если установлен флаг ENCODE_FLAG_64 (flags & 1 == 1), то float передается как 64-битное число двойной точности:

Отступ	Длина	Тип	Описание
4	8	Float	IЕEE 754 32-Битное Число с плавающей точкой

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	размер Х
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	размер Х
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

Объект может быть сериализован тремя различными способами: как нулевое значение, с full_objects = false или с full_objects = true.

A null value (Нулевое значение)

Отступ	Длина	Тип	Описание
4	4	Integer	Zero (32-битное знаковое целое число)

full_objects отключены

Отступ	Длина	Тип	Описание
4	8	Integer	ID экземпляра объекта (64-битное знаковое целое число)

full_objects включен

Отступ	Длина	Тип	Описание
4	4	Integer	Имя класса (Длина строки)
8	X	Байт	Class name (строка в кодировке UTF-8)
X+8	4	Integer	Количество сериализованных свойств

Для каждого объекта недвижимости:

Отступ	Длина	Тип	Описание
Y	4	Integer	Имя свойства (Длина строки)
Y+4	Z	Байт	Имя свойства (Строка в кодировке UTF-8)
Y+4+Z	W	<variable>	Стоимость недвижимости, используя тот же формат

Примечание

Включены не все свойства. Сериализуются только свойства, настроенные с установленным флагом PROPERTY_USAGE_STORAGE. Вы можете добавить новый флаг использования к свойству, переопределив метод _get_property_list в вашем классе. Вы также можете проверить, как настроено использование свойства, вызвав Object._get_property_list. См. PropertyUsageFlags для получения информации о возможных флагах использования.

18: Dictionary

Отступ	Длина	Тип	Описание
4	4	Integer	val&0x7FFFFFFF = элементы, val&0x80000000 = общий (bool)

Из этого следует, что количество "elements", пар ключ/значение, один за другим, использует тот же формат.

19: Array

Отступ	Длина	Тип	Описание
4	4	Integer	val&0x7FFFFFFF = элементы, val&0x80000000 = общий (bool)

Из этого следует, что количество "elements", значений одним за другим, использует тот же формат.

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	Длина массива (Floats)
8..8+длина*4	4	Integer	32-bit IEEE 754 одинарной точности float

24: PackedFloat64Array

Отступ	Длина	Тип	Описание
4	4	Integer	Длина массива (Floats)
8..8+длина*8	8	Integer	64-bit IEEE 754 двойной точности float

25: PackedStringArray

Отступ	Длина	Тип	Описание
4	4	Integer	Длина массива (Strings)

Для каждой Строки:

Отступ	Длина	Тип	Описание
X+0	4	Integer	Длина строки
X+4	X	Байт	Строка в кодировке UTF-8

Каждая строка укладывается в 4 байта.

26: PackedVector2Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Длина Массива)
8..8+длина*8	4	Float	Координата по оси X
8..12+длина*8	4	Float	Координата по оси Y

27: PackedVector3Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Длина Массива)
8..8+длина*12	4	Float	Координата по оси X
8..12+длина*12	4	Float	Координата по оси Y
8..16+длина*12	4	Float	Координата по оси Z

28: PackedColorArray

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Длина Массива)
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)