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