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	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	цвет
15	node path
16	rіd
17	объект
18	словарь
19	array
20	raw array
21	int32 array
22	int64 array
23	float32 array
24	float64 array
25	string array
26	vector2 array
27	vector3 array
28	color array
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	IEEE 754 double-precision float

4: String

Отступ	Длина	Тип	Описание
4	4	Integer	String length (in bytes)
8	X	Байт	UTF-8 encoded string

Это поле укладывается в 4 байта.

5: Vector2

Отступ	Длина	Тип	Описание
4	4	Float	X coordinate
8	4	Float	Y coordinate

6: Rect2

Отступ	Длина	Тип	Описание
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	X size
16	4	Float	Y size

7: Vector3

Отступ	Длина	Тип	Описание
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate

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 coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate
16	4	Float	X size
20	4	Float	Y size
24	4	Float	Z size

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	Red (typically 0..1, can be above 1 for overbright colors)
8	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
12	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
16	4	Float	Альфа (0..1)

15: NodePath

Отступ	Длина	Тип	Описание
4	4	Integer	String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

Для старого формата:

Отступ	Длина	Тип	Описание
8	X	Байт	UTF-8 encoded string

Укладывается в 4 байта.

Для нового формата:

Отступ	Длина	Тип	Описание
4	4	Integer	Sub-name count
8	4	Integer	Флаги (абсолютные: val&1 != 0 )

Для каждого Имени и Под-Имени

Отступ	Длина	Тип	Описание
X+0	4	Integer	String length
X+4	X	Байт	UTF-8 encoded string

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

16: RID (unsupported)

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	The number of properties that are serialized

For each property:

Отступ	Длина	Тип	Описание
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)

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

19: Array

Отступ	Длина	Тип	Описание
4	4	Integer	val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

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

20: PackedByteArray

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Bytes)
8..8+длина	1	Байт	Байт (0..255)

Данные массива укладываются в 4 байта.

21: PackedInt32Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Integers)
8..8+длина*4	4	Integer	32-битное знаковое целое число

22: PackedInt64Array

Отступ	Длина	Тип	Описание
4	8	Integer	Array length (Integers)
8..8+длина*8	8	Integer	64-битное знаковое целое число

23: PackedFloat32Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Floats)
8..8+длина*4	4	Integer	32-bit IEEE 754 single-precision float

24: PackedFloat64Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length (Floats)
8..8+длина*8	8	Integer	64-bit IEEE 754 double-precision float

25: PackedStringArray

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

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

Отступ	Длина	Тип	Описание
X+0	4	Integer	String length
X+4	X	Байт	UTF-8 encoded string

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

26: PackedVector2Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length
8..8+длина*8	4	Float	X coordinate
8..12+длина*8	4	Float	Y coordinate

27: PackedVector3Array

Отступ	Длина	Тип	Описание
4	4	Integer	Array length
8..8+длина*12	4	Float	X coordinate
8..12+длина*12	4	Float	Y coordinate
8..16+длина*12	4	Float	Z coordinate

28: PackedColorArray

Отступ	Длина	Тип	Описание
4	4	Integer	Array length
8..8+длина*16	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8..12+длина*16	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
8..16+длина*16	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
8..20+длина*16	4	Float	Альфа (0..1)