Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

API de serialização binária

Introdução

Godot has a serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is exposed via the global bytes_to_var() and var_to_bytes() functions, but it is also used in the get_var and store_var methods of FileAccess as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

Full Objects vs Object instance IDs

If a variable is serialized with full_objects = true, then any Objects contained in the variable will be serialized and included in the result. This is recursive.

If full_objects = false, then only the instance IDs will be serialized for any Objects contained in the variable.

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

quaternion

11

aabb

12

basis

13

transform3d

14

cor

15

node path (caminho do nó)

16

rid

17

object

18

dictionary

19

array (matriz)

20

raw array (matriz bruta)

21

int32 array

22

int64 array

23

float32 array

24

float64 array

25

string array (matriz de strings)

26

vector2 array (matriz vetor2)

27

vector3 array (matriz vector3)

28

color array (matriz de cores)

29

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

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

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

An Object could be serialized in three different ways: as a null value, with full_objects = false, or with full_objects = true.

A null value

Deslocamento

Len

Tipo

Descrição

4

4

Inteiro

Zero (32-bit signed integer)

full_objects disabled

Deslocamento

Len

Tipo

Descrição

4

8

Inteiro

The Object instance ID (64-bit signed integer)

full_objects enabled

Deslocamento

Len

Tipo

Descrição

4

4

Inteiro

Class name (String length)

8

X

Bytes

Class name (UTF-8 encoded string)

X+8

4

Inteiro

The number of properties that are serialized

For each property:

Deslocamento

Len

Tipo

Descrição

Y

4

Inteiro

Property name (String length)

Y+4

Z

Bytes

Property name (UTF-8 encoded string)

Y+4+Z

W

<variable>

Property value, using this same format

Nota

Not all properties are included. Only properties that are configured with the PROPERTY_USAGE_STORAGE flag set will be serialized. You can add a new usage flag to a property by overriding the _get_property_list method in your class. You can also check how property usage is configured by calling Object._get_property_list See PropertyUsageFlags for the possible usage flags.

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

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

Deslocamento

Len

Tipo

Descrição

4

4

Inteiro

Array length (Integers)

8..8+comprimento*4

4

Inteiro

32-bit signed integer

22: PackedInt64Array

Deslocamento

Len

Tipo

Descrição

4

8

Inteiro

Array length (Integers)

8..8+comprimento*8

8

Inteiro

64-bit signed integer

23: PackedFloat32Array

Deslocamento

Len

Tipo

Descrição

4

4

Inteiro

Array length (Floats)

8..8+comprimento*4

4

Inteiro

32-bit IEEE 754 single-precision float

24: PackedFloat64Array

Deslocamento

Len

Tipo

Descrição

4

4

Inteiro

Array length (Floats)

8..8+comprimento*8

8

Inteiro

64-bit IEEE 754 double-precision float

25: PackedStringArray

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.

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

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)