API двоичной сериализации

Введение

Godot имеет простой API сериализации, основанный на Variant. Он используется для эффективного преобразования типов данных в массив байтов. Этот API используется в функциях get_var и store_var из class_File`, а также в API пакетов для class_PacketPeer`. Этот формат не используется для бинарных сцен и ресурсов.

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

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

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

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

Тип	Значение
0	null
1	bool
2	integer
3	float
4	string
5	vector2
6	rect2
7	vector3
8	transform2d
9	plane
10	quat
11	aabb
12	basis
13	transform
14	цвет
15	node path
16	rid
17	object
18	dictionary
19	array
20	raw array
21	int array
22	real array
23	string array
24	vector2 array
25	vector3 array
26	color array
27	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: Quat

Сдвиг	Длина	Тип	Описание
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: Transform

Сдвиг	Длина	Тип	Описание
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 (unsupported)

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: PoolByteArray

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

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

21: PoolIntArray

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

22: PoolRealArray

Сдвиг	Длина	Тип	Описание
4	4	Integer	Array length (Floats)
8..8+length*4	4	Integer	32 Битное IEEE 754 Число с плавающей точкой

23: PoolStringArray

Сдвиг	Длина	Тип	Описание
4	4	Integer	Array length (Strings)

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

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

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

24: PoolVector2Array

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

25: PoolVector3Array

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

26: PoolColorArray

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