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