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) |