API двоичной сериализации

Введение

Godot имеет простой API сериализации основанный на Variant. Он используется эффективной конвертации типов данных в массивы байтов. Этот API используется в функциях get_var и store_var класса class_File а также в пакетном API для класса class_PacketPeer. Этот формат не используется для двоичных сцен и ресурсов.

Пакетная сериализация

Пакет спроектирован так чтобы всегда укладываться в 4 байта. Все значения закодированы от младшего к старшему(little endian). Все пакеты имеют целочисленный заголовок в 4 байта, определяющий тип данных:

Тип Значение
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 color
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

Далее показано содержание пакетов, которое отличается для каждого типа пакета:

0: null

1: bool

Сдвиг Длина Тип Описание
4 4 Integer 0 для False, 1 для True

2: int

Сдвиг Длина Тип Описание
4 4 Integer 32-битное Целое, со знаком

3: float/real

Сдвиг Длина Тип Описание
4 4 Float IEE 754 32-Битное Число с плавающей точкой

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 [0][0]
8 4 Float [0][1]
12 4 Float [1][0]
16 4 Float [1][1]
20 4 Float [2][0]
24 4 Float [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 [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]

13: Transform

Сдвиг Длина Тип Описание
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]
40 4 Float [3][0]
44 4 Float [3][1]
48 4 Float [3][2]

14: Color

Сдвиг Длина Тип Описание
4 4 Float Красный (0..1)
8 4 Float Зелёный (0..1)
12 4 Float Синий (0..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 (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 Длина Массива (в Байтах)
8..8+length 1 Байт Байт (0..255)

Данные массива укладываются в 4 байта.

21: PoolIntArray

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива (Целые числа)
8..8+length*4 4 Integer 32 Битное Целое Число

22: PoolRealArray

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива (Числа с плавающей точкой)
8..8+length*4 4 Integer 32 Битное IEE 754 Число с плавающей точкой

23: PoolStringArray

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива (Строки)

Для каждой Строки:

Сдвиг Длина Тип Описание
X+0 4 Integer Длина строки
X+4 X Байт Закодированная в UTF-8 Строка

Каждая строка укладывается в 4 байта.

24: PoolVector2Array

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива
8..8+length*8 4 Float Координата по оси X
8..12+length*8 4 Float Координата по оси Y

25: PoolVector3Array

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива
8..8+length*12 4 Float Координата по оси X
8..12+length*12 4 Float Координата по оси Y
8..16+length*12 4 Float Координата по оси Z

26: PoolColorArray

Сдвиг Длина Тип Описание
4 4 Integer Длина Массива
8..8+length*16 4 Float Красный (0..1)
8..12+length*16 4 Float Зелёный (0..1)
8..16+length*16 4 Float Синий (0..1)
8..20+length*16 4 Float Альфа (0..1)