API de serialização binária

Introdução

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.

Especificação do pacote

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.

The lowest value two bytes are used to determine the type, while the highest value two bytes contain flags:

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

Tipo	Valor
0	null
1	bool
2	inteiro
3	float
4	string
5	vector2
6	rect2
7	vector3
8	transform2d
9	plano
10	quat
11	aabb
12	basis
13	transform
14	cor
15	node path (caminho do nó)
16	rid
17	object
18	dictionary
19	array (matriz)
20	raw array (matriz bruta)
21	int array (matriz int)
22	real array (matriz real)
23	string array (matriz de strings)
24	vector2 array (matriz vetor2)
25	vector3 array (matriz vector3)
26	color array (matriz de cores)
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 (nulo)

1: bool

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	0 para falso (False), 1 para verdadeiro (True)

2: int

Se nenhum sinalizador (flag) for definido (flags == 0), o inteiro é enviado como um inteiro de 32 bits:

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	32-bit signed integer

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the integer is sent as a 64-bit integer:

Deslocamento	Len	Tipo	Descrição
4	8	Inteiro	64-bit signed integer

3: float

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

Deslocamento	Len	Tipo	Descrição
4	4	Float	IEEE 754 single-precision float

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the float is sent as a 64-bit double precision number:

Deslocamento	Len	Tipo	Descrição
4	8	Float	IEEE 754 double-precision float

4: String

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	String length (in bytes)
8	X	Bytes	UTF-8 encoded string

This field is padded to 4 bytes.

5: Vector2

Deslocamento	Len	Tipo	Descrição
4	4	Float	Coordenada X
8	4	Float	Coordenada Y

6: Rect2

Deslocamento	Len	Tipo	Descrição
4	4	Float	Coordenada X
8	4	Float	Coordenada Y
12	4	Float	tamanho x
16	4	Float	tamanho Y

7: Vector3

Deslocamento	Len	Tipo	Descrição
4	4	Float	Coordenada X
8	4	Float	Coordenada Y
12	4	Float	Coordenada Z

8: Transform2D

Deslocamento	Len	Tipo	Descrição
4	4	Float	The X component of the X column vector, accessed via [0][0]
8	4	Float	The Y component of the X column vector, accessed via [0][1]
12	4	Float	The X component of the Y column vector, accessed via [1][0]
16	4	Float	The Y component of the Y column vector, accessed via [1][1]
20	4	Float	The X component of the origin vector, accessed via [2][0]
24	4	Float	The Y component of the origin vector, accessed via [2][1]

9: Plane

Deslocamento	Len	Tipo	Descrição
4	4	Float	Normal X
8	4	Float	Normal Y
12	4	Float	Normal Z
16	4	Float	Distância

10: Quat

Deslocamento	Len	Tipo	Descrição
4	4	Float	X Imaginário
8	4	Float	Y imaginário
12	4	Float	Z imaginário
16	4	Float	Real W

11: AABB

Deslocamento	Len	Tipo	Descrição
4	4	Float	Coordenada X
8	4	Float	Coordenada Y
12	4	Float	Coordenada Z
16	4	Float	tamanho x
20	4	Float	tamanho Y
24	4	Float	tamanho Z

12: Basis

Deslocamento	Len	Tipo	Descrição
4	4	Float	The X component of the X column vector, accessed via [0][0]
8	4	Float	The Y component of the X column vector, accessed via [0][1]
12	4	Float	The Z component of the X column vector, accessed via [0][2]
16	4	Float	The X component of the Y column vector, accessed via [1][0]
20	4	Float	The Y component of the Y column vector, accessed via [1][1]
24	4	Float	The Z component of the Y column vector, accessed via [1][2]
28	4	Float	The X component of the Z column vector, accessed via [2][0]
32	4	Float	The Y component of the Z column vector, accessed via [2][1]
36	4	Float	The Z component of the Z column vector, accessed via [2][2]

13: Transform

Deslocamento	Len	Tipo	Descrição
4	4	Float	The X component of the X column vector, accessed via [0][0]
8	4	Float	The Y component of the X column vector, accessed via [0][1]
12	4	Float	The Z component of the X column vector, accessed via [0][2]
16	4	Float	The X component of the Y column vector, accessed via [1][0]
20	4	Float	The Y component of the Y column vector, accessed via [1][1]
24	4	Float	The Z component of the Y column vector, accessed via [1][2]
28	4	Float	The X component of the Z column vector, accessed via [2][0]
32	4	Float	The Y component of the Z column vector, accessed via [2][1]
36	4	Float	The Z component of the Z column vector, accessed via [2][2]
40	4	Float	The X component of the origin vector, accessed via [3][0]
44	4	Float	The Y component of the origin vector, accessed via [3][1]
48	4	Float	The Z component of the origin vector, accessed via [3][2]

14: Color

Deslocamento	Len	Tipo	Descrição
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	Alpha (0..1)

15: NodePath

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

Para o formato antigo:

Deslocamento	Len	Tipo	Descrição
8	X	Bytes	UTF-8 encoded string

Padded to 4 bytes.

Para novo formato:

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Contagem de subnomes
8	4	Inteiro	Flags (absolute: val&1 != 0 )

Para cada Nome e Subnome

Deslocamento	Len	Tipo	Descrição
X+0	4	Inteiro	Tamanho de string
X+4	X	Bytes	UTF-8 encoded string

Every name string is padded to 4 bytes.

16: RID (sem suporte)

17: Object (sem suporte)

18: Dictionary

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	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

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	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

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Array length (Bytes)
8..8+comprimento	1	Byte	Byte (0..255)

The array data is padded to 4 bytes.

21: PoolIntArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Array length (Integers)
8..8+comprimento*4	4	Inteiro	32-bit signed integer

22: PoolRealArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Array length (Floats)
8..8+comprimento*4	4	Inteiro	32-bits IEEE 754 float

23: PoolStringArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Array length (Strings)

Para cada String:

Deslocamento	Len	Tipo	Descrição
X+0	4	Inteiro	Tamanho de string
X+4	X	Bytes	UTF-8 encoded string

Every string is padded to 4 bytes.

24: PoolVector2Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da matriz
8..8+comprimento*8	4	Float	Coordenada X
8..12+comprimento*8	4	Float	Coordenada Y

25: PoolVector3Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da matriz
8..8+comprimento*12	4	Float	Coordenada X
8..12+comprimento*12	4	Float	Coordenada Y
8..16+comprimento*12	4	Float	Coordenada Z

26: PoolColorArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da matriz
8..8+comprimento*16	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8..12+comprimento*16	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
8..16+comprimento*16	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
8..20+comprimento*16	4	Float	Alpha (0..1)