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 |
нуль |
1 |
bool |
2 |
ціле число |
3 |
десяткове число |
4 |
текст |
5 |
vector2 |
6 |
rect2 |
7 |
vector3 |
8 |
transform2d |
9 |
площина |
10 |
quaternion |
11 |
aabb |
12 |
basis |
13 |
transform3d |
14 |
колір |
15 |
шлях вузла |
16 |
rid |
17 |
об'єкт |
18 |
словник |
19 |
масив |
20 |
необроблений масив |
21 |
int32 array |
22 |
int64 array |
23 |
float32 array |
24 |
float64 array |
25 |
масив з текстів |
26 |
масив з vector2 |
27 |
масив з vector3 |
28 |
масив з кольорів |
29 |
макс. |
Нижче наведено фактичний вміст пакета, який варіюється для кожного типу пакета. Зауважте, що тут припускається, що Godot скомпільований за замовчуванням, з десятковими одинарної точності. Якщо Godot був скомпільований з десятковими подвійними точності, довжина полів "Float" в структурах даних повинна бути 8, а зміщення повинно бути (offset - 4) * 2 + 4
. Сам тип "float" завжди використовує подвійну точність.
0: нуль¶
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: десяткові¶
Якщо мітка не встановлена (flags == 0), десяткове число надсилається, як 32 розрядне з одинарною точністю:
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Float |
Десяткове число одинарної точності стандарту IEEE 754 |
Якщо встановлена мітка ENCODE_FLAG_64
(flags & 1 == 1
), десяткове число надсилається, як 64 - розрядне десяткове число подвійної точності:
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
8 |
Float |
Десяткове число подвійної точності стандарту IEEE 754 |
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 |
Розмір по X |
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 |
Розмір по X |
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¶
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 (ціле) |
Кількість властивостей, які серіалізуються |
За кожну власність:
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
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) |
Відповідно вся кількість "елементів", пар ключа і значення, один за одним використовують той самий формат.
19: Array¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Відповідно, для кількості "елементів", значень один за одним, використовується той самий формат.
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 (ціле) |
Довжина масиву (Десяткові числа) |
8..8+довжина*4 |
4 |
Integer (ціле) |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Десяткові числа) |
8..8+довжина*8 |
8 |
Integer (ціле) |
64-bit IEEE 754 double-precision float |
25: PackedStringArray¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Текст) |
Для кожного Тексту:
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
X+0 |
4 |
Integer (ціле) |
Довжина тексту |
X+4 |
X |
Байти |
Текст закодований в UTF-8 |
Кожен текст вкладається в 4 байти.
26: PackedVector2Array¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*8 |
4 |
Float |
Координата X |
8..12+довжина*8 |
4 |
Float |
Координата Y |
27: PackedVector3Array¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*12 |
4 |
Float |
Координата X |
8..12+довжина*12 |
4 |
Float |
Координата Y |
8..16+довжина*12 |
4 |
Float |
Координата Z |
28: PackedColorArray¶
Зміщення |
Довжина |
Тип |
Опис |
---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
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) |