Binary serialization API

Introduction

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:

Type Value
0 null
1 bool
2 integer
3 float
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 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

Offset Len Type Description
4 8 Integer 64-bit signed integer

3: float

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

Offset Len Type Description
4 4 Float Imaginary X
8 4 Float Imaginary Y
12 4 Float Imaginary Z
16 4 Float Real W

11: AABB

Offset Len Type Description
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float Z coordinate
16 4 Float X size
20 4 Float Y size
24 4 Float Z size

12: Basis

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

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

Offset Len Type Description
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 Type Description
4 4 Integer String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

For old format:

Offset Len Type Description
8 X Bytes UTF-8 encoded string

Padded to 4 bytes.

For new format:

Offset Len Type Description
4 4 Integer Sub-name count
8 4 Integer Flags (absolute: val&1 != 0 )

For each Name and Sub-Name

Offset Len Type Description
X+0 4 Integer String length
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 Type Description
4 4 Integer 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 Type Description
4 4 Integer 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

Offset Len Type Description
4 4 Integer Array length (Bytes)
8..8+length 1 Byte Byte (0..255)

The array data is padded to 4 bytes.

21: PackedInt32Array

Offset Len Type Description
4 4 Integer Array length (Integers)
8..8+length*4 4 Integer 32-bit signed integer

22: PackedInt64Array

Offset Len Type Description
4 8 Integer Array length (Integers)
8..8+length*8 8 Integer 64-bit signed integer

23: PackedFloat32Array

Offset Len Type Description
4 4 Integer Array length (Floats)
8..8+length*4 4 Integer 32-bit IEEE 754 single-precision float

24: PackedFloat64Array

Offset Len Type Description
4 4 Integer Array length (Floats)
8..8+length*8 8 Integer 64-bit IEEE 754 double-precision float

25: PackedStringArray

Offset Len Type Description
4 4 Integer Array length (Strings)

For each String:

Offset Len Type Description
X+0 4 Integer String length
X+4 X Bytes UTF-8 encoded string

Every string is padded to 4 bytes.

26: PackedVector2Array

Offset Len Type Description
4 4 Integer Array length
8..8+length*8 4 Float X coordinate
8..12+length*8 4 Float Y coordinate

27: PackedVector3Array

Offset Len Type Description
4 4 Integer Array length
8..8+length*12 4 Float X coordinate
8..12+length*12 4 Float Y coordinate
8..16+length*12 4 Float Z coordinate

28: PackedColorArray

Offset Len Type Description
4 4 Integer Array length
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)