Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

API de serialização binária

Introdução

O Godot possui uma API de serialização baseada em Variant. Ela é usada para converter tipos de dados em um array de bytes de forma eficiente. Essa API é exposta pelas funções globais bytes_to_var() e var_to_bytes(), mas também é usada nos métodos get_var e store_var de FileAccess, bem como nas APIs de pacotes de PacketPeer. Esse formato não é usado para cenas e recursos binários.

Objetos Completos vs IDs de Instância de Objeto

Se uma variável for serializada com full_objects = true, então quaisquer Objetos contidos na variável serão serializados e incluídos no resultado. Isso é recursivo.

Se full_objects = false, então apenas os IDs de instância serão serializados para quaisquer Objetos contidos na variável.

Especificação do pacote

O pacote é projetado para ser sempre alinhado a 4 bytes. Todos os valores são codificados em little-endian. Todos os pacotes possuem um cabeçalho de 4 bytes representando um inteiro que especifica o tipo de dado.

Os dois bytes de menor valor são usados para determinar o tipo, enquanto os dois bytes de maior valor contêm 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	quaternion (quaternião)
11	aabb
12	basis
13	transformação 3d
14	cor
15	node path (caminho do nó)
16	rid
17	object
18	dictionary
19	array (matriz)
20	raw array (matriz bruta)
21	array de int32
22	array de int64
23	array de float32
24	array de float64
25	string array (matriz de strings)
26	vector2 array (matriz vetor2)
27	vector3 array (matriz vector3)
28	color array (matriz de cores)
29	max

Em seguida vem o conteúdo real do pacote, que varia para cada tipo de pacote. Observe que isso assume que o Godot foi compilado com floats de precisão simples, que é o padrão. Se o Godot tiver sido compilado com precisão dupla, o tamanho dos campos "Float" dentro das estruturas de dados deve ser 8, e o deslocamento deve ser (offset - 4) * 2 + 4. O tipo "float" em si sempre usa precisão dupla.

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	inteiro com sinal de 32 bits

Se a flag ENCODE_FLAG_64 estiver definida (flags & 1 == 1), o inteiro é enviado como um inteiro de 64 bits:

Deslocamento	Len	Tipo	Descrição
4	8	Inteiro	Inteiro com sinal de 64 bits

3: float

Se nenhuma flag estiver definida (flags == 0), o float é enviado como precisão simples de 32 bits:

Deslocamento	Len	Tipo	Descrição
4	4	Float	Float de precisão simples IEEE 754

Se a flag ENCODE_FLAG_64 estiver definida (flags & 1 == 1), o float é enviado como um número de precisão dupla de 64 bits:

Deslocamento	Len	Tipo	Descrição
4	8	Float	Float de precisão dupla IEEE 754

4: String

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da string (em bytes)
8	X	Bytes	String codificada em UTF-8

Este campo é preenchido (padded) até 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	O componente X do vetor da coluna X, acessado via [0][0]
8	4	Float	O componente Y do vetor da coluna X, acessado via [0][1]
12	4	Float	O componente X do vetor da coluna Y, acessado via [1][0]
16	4	Float	O componente Y do vetor da coluna Y, acessado via [1][1]
20	4	Float	O componente X do vetor de origem, acessado via [2][0]
24	4	Float	O componente Y do vetor de origem, acessado 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: Quaternion

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	O componente X do vetor da coluna X, acessado via [0][0]
8	4	Float	O componente Y do vetor da coluna X, acessado via [0][1]
12	4	Float	O componente Z do vetor da coluna X, acessado via [0][2]
16	4	Float	O componente X do vetor da coluna Y, acessado via [1][0]
20	4	Float	O componente Y do vetor da coluna Y, acessado via [1][1]
24	4	Float	O componente Z do vetor da coluna Y, acessado via [1][2]
28	4	Float	O componente X do vetor da coluna Z, acessado via [2][0]
32	4	Float	O componente Y do vetor da coluna Z, acessado via [2][1]
36	4	Float	O componente Z do vetor da coluna Z, acessado via [2][2]

13: Transform3D

Deslocamento	Len	Tipo	Descrição
4	4	Float	O componente X do vetor da coluna X, acessado via [0][0]
8	4	Float	O componente Y do vetor da coluna X, acessado via [0][1]
12	4	Float	O componente Z do vetor da coluna X, acessado via [0][2]
16	4	Float	O componente X do vetor da coluna Y, acessado via [1][0]
20	4	Float	O componente Y do vetor da coluna Y, acessado via [1][1]
24	4	Float	O componente Z do vetor da coluna Y, acessado via [1][2]
28	4	Float	O componente X do vetor da coluna Z, acessado via [2][0]
32	4	Float	O componente Y do vetor da coluna Z, acessado via [2][1]
36	4	Float	O componente Z do vetor da coluna Z, acessado via [2][2]
40	4	Float	O componente X do vetor de origem, acessado via [3][0]
44	4	Float	O componente Y do vetor de origem, acessado via [3][1]
48	4	Float	O componente Z do vetor de origem, acessado via [3][2]

14: Color

Deslocamento	Len	Tipo	Descrição
4	4	Float	Vermelho (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
8	4	Float	Verde (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
12	4	Float	Azul (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
16	4	Float	Alpha (0..1)

15: NodePath

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da string, ou novo formato (val&0x80000000!=0 e NameCount=val&0x7FFFFFFF)

Para o formato antigo:

Deslocamento	Len	Tipo	Descrição
8	X	Bytes	String codificada em UTF-8

Preenchido até 4 bytes.

Para novo formato:

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

Para cada Nome e Subnome

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

Toda string de nome é preenchida até 4 bytes.

16: RID (sem suporte)

17: Object

Um Objeto pode ser serializado de três maneiras diferentes: como um valor nulo, com full_objects = false ou com full_objects = true.

Um valor nulo

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Zero (inteiro com sinal de 32 bits)

full_objects desativado

Deslocamento	Len	Tipo	Descrição
4	8	Inteiro	O ID da instância do Objeto (inteiro com sinal de 64 bits)

full_objects ativado

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Nome da classe (tamanho da String)
8	X	Bytes	Nome da classe (string codificada em UTF-8)
X+8	4	Inteiro	O número de propriedades que são serializadas

Para cada propriedade:

Deslocamento	Len	Tipo	Descrição
Y	4	Inteiro	Nome da propriedade (tamanho da String)
Y+4	Z	Bytes	Nome da propriedade (string codificada em UTF-8)
Y+4+Z	W	<variável>	Valor da propriedade, usando este mesmo formato

Nota

Nem todas as propriedades são incluídas. Apenas as propriedades configuradas com a flag PROPERTY_USAGE_STORAGE definida serão serializadas. Você pode adicionar uma nova flag de uso a uma propriedade sobrescrevendo o método _get_property_list na sua classe. Você também pode verificar como o uso da propriedade está configurado chamando Object._get_property_list. Veja PropertyUsageFlags para as flags de uso possíveis.

18: Dictionary

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	val&0x7FFFFFFF = elementos, val&0x80000000 = compartilhado (bool)

O que se segue então é, para a quantidade de "elementos", pares de chave e valor, um após o outro, usando este mesmo formato.

19: Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	val&0x7FFFFFFF = elementos, val&0x80000000 = compartilhado (bool)

O que se segue então é, para a quantidade de "elementos", valores um após o outro, usando este mesmo formato.

20: PackedByteArray

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

Os dados do array são preenchidos até 4 bytes.

21: PackedInt32Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento do array (Inteiros)
8..8+comprimento*4	4	Inteiro	inteiro com sinal de 32 bits

22: PackedInt64Array

Deslocamento	Len	Tipo	Descrição
4	8	Inteiro	Comprimento do array (Inteiros)
8..8+comprimento*8	8	Inteiro	Inteiro com sinal de 64 bits

23: PackedFloat32Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento do array (Floats)
8..8+comprimento*4	4	Inteiro	Float de precisão simples IEEE 754 de 32 bits

24: PackedFloat64Array

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento do array (Floats)
8..8+comprimento*8	8	Inteiro	Float de precisão dupla IEEE 754 de 64 bits

25: PackedStringArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento do array (Strings)

Para cada String:

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

Toda string é preenchida até 4 bytes.

26: PackedVector2Array

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

27: PackedVector3Array

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

28: PackedColorArray

Deslocamento	Len	Tipo	Descrição
4	4	Inteiro	Comprimento da matriz
8..8+comprimento*16	4	Float	Vermelho (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
8..12+comprimento*16	4	Float	Verde (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
8..16+comprimento*16	4	Float	Azul (tipicamente 0..1, pode ser superior a 1 para cores superbrilhantes)
8..20+comprimento*16	4	Float	Alpha (0..1)