API бінарної серіалізації¶
Вступ¶
Godot має простий API серіалізації на основі Variant. Він використовується для ефективного перетворення типів даних у масив байтів. Цей API використовується в функціях get_var і store_var з File, а також API пакетів для PacketPeer. Цей формат не використовується для бінарних сцен і ресурсів.
Специфікація пакетів¶
Пакет розрахований на те, щоб завжди складатися з 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 |
quat |
11 |
aabb |
12 |
basis |
13 |
3д перетворення |
14 |
колір |
15 |
шлях вузла |
16 |
rid |
17 |
об'єкт |
18 |
словник |
19 |
масив |
20 |
необроблений масив |
21 |
масив з цілих чисел |
22 |
real array |
23 |
масив з текстів |
24 |
масив з vector2 |
25 |
масив з vector3 |
26 |
масив з кольорів |
27 |
макс. |
Нижче наведено фактичний вміст пакета, який варіюється для кожного типу пакета. Зауважте, що тут припускається, що 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: Quat¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
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: 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 |
Червоний (зазвичай 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 не підтримується)¶
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: PoolByteArray¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Байти) |
8..8+довжина |
1 |
Байт |
Байт (0..255) |
Дані масиву вкладаються в 4 байти.
21: PoolIntArray¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (цілі числа) |
8..8+довжина*4 |
4 |
Integer (ціле) |
Ціле число помічене, як 32-розрядне |
22: PoolRealArray¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Десяткові числа) |
8..8+довжина*4 |
4 |
Integer (ціле) |
32-розрядне десяткове число формату IEEE 754 |
23: PoolStringArray¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву (Текст) |
Для кожного Тексту:
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
X+0 |
4 |
Integer (ціле) |
Довжина тексту |
X+4 |
X |
Байти |
Текст закодований в UTF-8 |
Кожен текст вкладається в 4 байти.
24: PoolVector2Array¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*8 |
4 |
Float |
Координата X |
8..12+довжина*8 |
4 |
Float |
Координата Y |
25: PoolVector3Array¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
4 |
4 |
Integer (ціле) |
Довжина масиву |
8..8+довжина*12 |
4 |
Float |
Координата X |
8..12+довжина*12 |
4 |
Float |
Координата Y |
8..16+довжина*12 |
4 |
Float |
Координата Z |
26: PoolColorArray¶
Зміщення |
Довжина |
Тип |
Опис |
|---|---|---|---|
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) |