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 matrix32
9 plane
10 quaternion
11 aabb (rect3)
12 matrix3x3
13 transform (matrix 4x3)
14 color
15 image
16 node path
17 rid (unsupported)
18 object (unsupported)
19 input event
20 dictionary
21 array
22 byte array
23 int array
24 float array
25 string array
26 vector2 array
27 vector3 array
28 color array

Following this is the actual packet contents, which varies for each type of packet:

0: null

1: bool

Offset Len Type Description
4 4 Integer 0 for False, 1 for True

2: integer

Offset Len Type Description
4 4 Integer Signed, 32-Bit Integer

3: float

Offset Len Type Description
4 4 Float IEE 754 32-Bits 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: matrix32

Offset Len Type Description
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [1][0]
16 4 Float [1][1]
20 4 Float [2][0]
24 4 Float [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

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 (rect3)

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

Offset Len Type Description
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]

13: transform (matrix 4x3)

Offset Len Type Description
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]
40 4 Float [3][0]
44 4 Float [3][1]
48 4 Float [3][2]

14: color

Offset Len Type Description
4 4 Float Red (0..1)
8 4 Float Green (0..1)
12 4 Float Blue (0..1)
16 4 Float Alpha (0..1)

15: image

Offset Len Type Description
4 4 Integer Format (see FORMAT_* in “Image”:class_image
8 4 Integer Mip-Maps (0 means no mip-maps).
12 4 Integer Width (Pixels)
16 4 Integer Height (Pixels)
20 4 Integer Data Length
24..24+DataLength 1 Byte Image Data

This field is padded to 4 bytes.

16: node path

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.

17: rid (unsupported)

18: object (unsupported)

19: input event

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

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

22: byte array

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.

23: int array

Offset Len Type Description
4 4 Integer Array Length (Integers)
8..8+length*4 4 Integer 32 Bits Signed Integer

24: float array

Offset Len Type Description
4 4 Integer Array Length (Floats)
8..8+length*4 4 Integer 32 Bits IEE 754 Float

25: string array

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 is padded to 4 bytes.

26: vector2 array

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

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

Offset Len Type Description
4 4 Integer Array Length
8..8+length*16 4 Float Red (0..1)
8..12+length*16 4 Float Green (0..1)
8..16+length*16 4 Float Blue (0..1)
8..20+length*16 4 Float Alpha (0..1)