Binary serialization API

Introducción

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.

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.

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

entero

3

real

4

string

5

vector2

6

rect2

7

vector3

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

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

1: bool

Offset

Len

Tipo

Descripción

4

4

Entero

0 for False, 1 for True

2: int

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

Offset

Len

Tipo

Descripción

4

4

Entero

Entero firmado de 32 bits

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

Offset

Len

Tipo

Descripción

4

8

Entero

Entero de 64 bits con signo

3: float

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

Offset

Len

Tipo

Descripción

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:

Offset

Len

Tipo

Descripción

4

8

Float

IEEE 754 double-precision float

4: String

Offset

Len

Tipo

Descripción

4

4

Entero

String length (in bytes)

8

X

Bytes

UTF-8 encoded string

This field is padded to 4 bytes.

5: Vector2

Offset

Len

Tipo

Descripción

4

4

Float

Coordenada X

8

4

Float

Coordenada Y

6: Rect2

Offset

Len

Tipo

Descripción

4

4

Float

Coordenada X

8

4

Float

Coordenada Y

12

4

Float

X size

16

4

Float

Y size

7: Vector3

Offset

Len

Tipo

Descripción

4

4

Float

Coordenada X

8

4

Float

Coordenada Y

12

4

Float

Coordenada Z

8: Transform2D

Offset

Len

Tipo

Descripción

4

4

Float

La componente X del vector columna X, accedido mediante [0][0]

8

4

Float

La componente Y del vector columna X, accedido mediante [0][1]

12

4

Float

La componente X del vector columna Y, accedido mediante [1][0]

16

4

Float

La componente Y del vector columna Y, accedido mediante [1][1]

20

4

Float

La componente X del vector origin, accedido mediante [2][0]

24

4

Float

La componente Y del vector origin, accedido mediante [2][1]

9: Plane

Offset

Len

Tipo

Descripción

4

4

Float

Normal X

8

4

Float

Normal Y

12

4

Float

Normal Z

16

4

Float

Distance

10: Quat

Offset

Len

Tipo

Descripción

4

4

Float

Imaginary X

8

4

Float

Imaginary Y

12

4

Float

Imaginary Z

16

4

Float

Real W

11: AABB

Offset

Len

Tipo

Descripción

4

4

Float

Coordenada X

8

4

Float

Coordenada Y

12

4

Float

Coordenada Z

16

4

Float

X size

20

4

Float

Y size

24

4

Float

Z size

12: Basis

Offset

Len

Tipo

Descripción

4

4

Float

La componente X del vector columna X, accedido mediante [0][0]

8

4

Float

La componente Y del vector columna X, accedido mediante [0][1]

12

4

Float

La componente Z del vector columna X, accedido mediante [0][2]

16

4

Float

La componente X del vector columna Y, accedido mediante [1][0]

20

4

Float

La componente Y del vector columna Y, accedido mediante [1][1]

24

4

Float

La componente Z del vector columna Y, accedido mediante [1][2]

28

4

Float

La componente X del vector columna Z, accedido mediante [2][0]

32

4

Float

La componente Y del vector columna Z, accedido mediante [2][1]

36

4

Float

La componente Z del vector columna Z, accedido mediante [2][2]

13: Transform

Offset

Len

Tipo

Descripción

4

4

Float

La componente X del vector columna X, accedido mediante [0][0]

8

4

Float

La componente Y del vector columna X, accedido mediante [0][1]

12

4

Float

La componente Z del vector columna X, accedido mediante [0][2]

16

4

Float

La componente X del vector columna Y, accedido mediante [1][0]

20

4

Float

La componente Y del vector columna Y, accedido mediante [1][1]

24

4

Float

La componente Z del vector columna Y, accedido mediante [1][2]

28

4

Float

La componente X del vector columna Z, accedido mediante [2][0]

32

4

Float

La componente Y del vector columna Z, accedido mediante [2][1]

36

4

Float

La componente Z del vector columna Z, accedido mediante [2][2]

40

4

Float

La componente X del vector origin, accedido mediante [3][0]

44

4

Float

La componente Y del vector origin, accedido mediante [3][1]

48

4

Float

La componente Z del vector origin, accedido mediante [3][2]

14: Color

Offset

Len

Tipo

Descripción

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

Offset

Len

Tipo

Descripción

4

4

Entero

String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

For old format:

Offset

Len

Tipo

Descripción

8

X

Bytes

UTF-8 encoded string

Padded to 4 bytes.

For new format:

Offset

Len

Tipo

Descripción

4

4

Entero

Sub-name count

8

4

Entero

Flags (absolute: val&1 != 0 )

For each Name and Sub-Name

Offset

Len

Tipo

Descripción

X+0

4

Entero

Longitud de la cuerda

X+4

X

Bytes

UTF-8 encoded string

Every name string is padded to 4 bytes.

16: RID (unsupported)

17: Object (unsupported)

18: Dictionary

Offset

Len

Tipo

Descripción

4

4

Entero

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

Offset

Len

Tipo

Descripción

4

4

Entero

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

Offset

Len

Tipo

Descripción

4

4

Entero

Array length (Bytes)

8..8+length

1

Byte

Byte (0..255)

The array data is padded to 4 bytes.

21: PoolIntArray

Offset

Len

Tipo

Descripción

4

4

Entero

Array length (Integers)

8..8+length*4

4

Entero

Entero firmado de 32 bits

22: PoolRealArray

Offset

Len

Tipo

Descripción

4

4

Entero

Array length (Floats)

8..8+length*4

4

Entero

32-bits IEEE 754 float

23: PoolStringArray

Offset

Len

Tipo

Descripción

4

4

Entero

Array length (Strings)

For each String:

Offset

Len

Tipo

Descripción

X+0

4

Entero

Longitud de la cuerda

X+4

X

Bytes

UTF-8 encoded string

Every string is padded to 4 bytes.

24: PoolVector2Array

Offset

Len

Tipo

Descripción

4

4

Entero

Longitud de la matriz

8..8+length*8

4

Float

Coordenada X

8..12+length*8

4

Float

Coordenada Y

25: PoolVector3Array

Offset

Len

Tipo

Descripción

4

4

Entero

Longitud de la matriz

8..8+length*12

4

Float

Coordenada X

8..12+length*12

4

Float

Coordenada Y

8..16+length*12

4

Float

Coordenada Z

26: PoolColorArray

Offset

Len

Tipo

Descripción

4

4

Entero

Longitud de la matriz

8..8+length*16

4

Float

Red (typically 0..1, can be above 1 for overbright colors)

8..12+length*16

4

Float

Green (typically 0..1, can be above 1 for overbright colors)

8..16+length*16

4

Float

Blue (typically 0..1, can be above 1 for overbright colors)

8..20+length*16

4

Float

Alpha (0..1)