Binary serialization API

Introduction

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.

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;

Type

Value

0

null

1

bool

2

integer

3

float

4

string

5

vector2

6

rect2

7

vector3

8

transform2d

9

plane

10

quaternion

11

aabb

12

basis

13

transform3d

14

color

15

node path

16

rid

17

object

18

dictionary

19

array

20

raw array

21

int32 array

22

int64 array

23

float32 array

24

float64 array

25

string array

26

vector2 array

27

vector3 array

28

color array

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

1: bool

Offset

Len

Type

Description

4

4

Integer

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

Type

Description

4

4

Integer

32-bit signed integer

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

Offset

Len

Type

Description

4

8

Integer

64-bit signed integer

3: float

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

Offset

Len

Type

Description

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

Type

Description

4

8

Float

IEEE 754 double-precision float

4: String

Offset

Len

Type

Description

4

4

Integer

String length (in bytes)

8

X

Bytes

UTF-8 encoded string

This field is padded to 4 bytes.

5: Vector2

Offset

Len

Type

Description

4

4

Float

X coordinate

8

4

Float

Y coordinate

6: Rect2

Offset

Len

Type

Description

4

4

Float

X coordinate

8

4

Float

Y coordinate

12

4

Float

X size

16

4

Float

Y size

7: Vector3

Offset

Len

Type

Description

4

4

Float

X coordinate

8

4

Float

Y coordinate

12

4

Float

Z coordinate

8: Transform2D

Offset

Len

Type

Description

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

Offset

Len

Type

Description

4

4

Float

Normal X

8

4

Float

Normal Y

12

4

Float

Normal Z

16

4

Float

Distance

10: Quaternion