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

Введение

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

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

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

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

base_type = val & 0xFFFF;
flags = val >> 16;

Тип

Значение

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

цвет

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

После этого следует фактическое содержимое пакета, которое различается для каждого типа пакета. Обратите внимание, что здесь предполагается, что 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: Quat

Сдвиг

Длина

Тип

Описание

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

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

Array length (Bytes)

8..8+length

1

Байт

Байт (0..255)

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

21: PoolIntArray

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length (Integers)

8..8+length*4

4

Integer

32-битное знаковое целое число

22: PoolRealArray

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length (Floats)

8..8+length*4

4

Integer

32 Битное IEEE 754 Число с плавающей точкой

23: PoolStringArray

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length (Strings)

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

Сдвиг

Длина

Тип

Описание

X+0

4

Integer

String length

X+4

X

Байт

UTF-8 encoded string

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

24: PoolVector2Array

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length

8..8+length*8

4

Float

X coordinate

8..12+length*8

4

Float

Y coordinate

25: PoolVector3Array

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length

8..8+length*12

4

Float

X coordinate

8..12+length*12

4

Float

Y coordinate

8..16+length*12

4

Float

Z coordinate

26: PoolColorArray

Сдвиг

Длина

Тип

Описание

4

4

Integer

Array length

8..8+length*16

4

Float

Red (typically 0..1, can be above 1 for overbright colors)

8..12+length*16

4

Float

Green (typically 0..1, can be above 1 for overbright colors)

8..16+length*16

4

Float

Blue (typically 0..1, can be above 1 for overbright colors)

8..20+length*16

4

Float

Альфа (0..1)