API бінарної серіалізації

Вступ

Godot має простий API серіалізації на основі Variant. Він використовується для ефективного перетворення типів даних у масив байтів. Цей API використовується в функціях get_var і store_var з File, а також API пакетів для PacketPeer. Цей формат не використовується для бінарних сцен і ресурсів.

Специфікація пакетів

The packet is designed to be always padded to 4 bytes. All values are little-endian-encoded. All packets have a 4-byte header representing an integer, specifying the type of data.

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

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	макс.

Following this is the actual packet contents, which varies for each type of packet. Note that this assumes Godot is compiled with single-precision floats, which is the default. If Godot was compiled with double-precision floats, the length of "Float" fields within data structures should be 8, and the offset should be (offset - 4) * 2 + 4. The "float" type itself always uses double precision.

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: десяткові

If no flags are set (flags == 0), the float is sent as a 32 bit single precision:

Зміщення	Довжина	Тип	Опис
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	Imaginary X
8	4	Float	Imaginary Y
12	4	Float	Imaginary Z
16	4	Float	Real 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)