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

Введение

Godot has a simple serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is used in the functions get_var and store_var of File as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

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

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:

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

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

1: bool

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

2: int

Сдвиг Длина Тип Описание
4 8 Integer 64-bit signed integer

3: float

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

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-bit signed integer

22: PoolRealArray

Сдвиг Длина Тип Описание
4 4 Integer Array length (Floats)
8..8+length*4 4 Integer 32-bits IEEE 754 float

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)