Binary serialization 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 class_File as well as the packet APIs for class_PacketPeer. This format is not used for binary scenes and resources.

Packet specification

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 Вектор
6 rect2
7 Вектор
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 макс.

Following this is the actual packet contents, which varies for each type of packet:

0: null

1: bool

Зміщення <title>LEN</title> Тип Опис
4 4 Integer 0 for False, 1 for True

2: int

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Signed, 32-Bit Integer

3: float/real

Зміщення <title>LEN</title> Тип Опис
4 4 Float IEE 754 32-Bits Float

4: String

Зміщення <title>LEN</title> Тип Опис
4 4 Integer String Length (in Bytes)
8 X Байтів UTF-8 Encoded String

This field is padded to 4 bytes.

5: Vector2

Зміщення <title>LEN</title> Тип Опис
4 4 Float Координата X
8 4 Float Координата Y

6: Rect2

Зміщення <title>LEN</title> Тип Опис
4 4 Float Координата X
8 4 Float Координата Y
12 4 Float Розмір за X
16 4 Float Розмір за Y

7: Vector3

Зміщення <title>LEN</title> Тип Опис
4 4 Float Координата X
8 4 Float Координата Y
12 4 Float Координата Z

8: Transform2D

Зміщення <title>LEN</title> Тип Опис
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

Зміщення <title>LEN</title> Тип Опис
4 4 Float Звичайний (1024x768)
8 4 Float Normal Y
12 4 Float Normal Z
16 4 Float Відстань

10: Quat

Зміщення <title>LEN</title> Тип Опис
4 4 Float Imaginary X
8 4 Float Imaginary Y
12 4 Float Imaginary Z
16 4 Float Real W

11: AABB

Зміщення <title>LEN</title> Тип Опис
4 4 Float Координата X
8 4 Float Координата Y
12 4 Float Координата Z
16 4 Float Розмір за X
20 4 Float Розмір за Y
24 4 Float Z Size

12: Basis

Зміщення <title>LEN</title> Тип Опис
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

Зміщення <title>LEN</title> Тип Опис
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

Зміщення <title>LEN</title> Тип Опис
4 4 Float Червоний
8 4 Float Зелений
12 4 Float Синій
16 4 Float альфа

15: NodePath

Зміщення <title>LEN</title> Тип Опис
4 4 Integer String Length, or New Format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

For old format:

Зміщення <title>LEN</title> Тип Опис
8 X Байтів UTF-8 Encoded String

Padded to 4 bytes.

For new format:

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Sub-Name Count
8 4 Integer Flags (absolute: val&1 != 0 )

For each Name and Sub-Name

Зміщення <title>LEN</title> Тип Опис
X+0 4 Integer String Length
X+4 X Байтів UTF-8 Encoded String

Every name string is padded to 4 bytes.

16: RID (unsupported)

17: Object (unsupported)

18: Dictionary

Зміщення <title>LEN</title> Тип Опис
4 4 Integer val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

Then what follows is, for amount of «elements», pairs of key and value, one after the other, using this same format.

19: Array

Зміщення <title>LEN</title> Тип Опис
4 4 Integer val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

Then what follows is, for amount of «elements», values one after the other, using this same format.

20: PoolByteArray

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length (Bytes)
Довжина 1 Байт Байт

The array data is padded to 4 bytes.

21: PoolIntArray

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length (Integers)
Довжина 4 Integer 32 Bits Signed Integer

22: PoolRealArray

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length (Floats)
Довжина 4 Integer 32 Bits IEE 754 Float

23: PoolStringArray

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length (Strings)

For each String:

Зміщення <title>LEN</title> Тип Опис
X+0 4 Integer String Length
X+4 X Байтів UTF-8 Encoded String

Every string is padded to 4 bytes.

24: PoolVector2Array

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length
Довжина 4 Float Координата X
Довжина 4 Float Координата Y

25: PoolVector3Array

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length
Довжина 4 Float Координата X
Довжина 4 Float Координата Y
Довжина 4 Float Координата Z

26: PoolColorArray

Зміщення <title>LEN</title> Тип Опис
4 4 Integer Array Length
Довжина 4 Float Червоний
Довжина 4 Float Зелений
Довжина 4 Float Синій
Довжина 4 Float альфа