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	ByteArray
23	IntArray
24	FloatArray
25	StringArray
26	Vector2Array
27	Vector3Array
28	ColorArray

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

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

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

24: class_FloatArray¶

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

25: class_StringArray¶

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

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

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

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)