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 :ref:`bytes_to_var() <class_@GlobalScope_method_bytes_to_var>` and :ref:`var_to_bytes() <class_@GlobalScope_method_var_to_bytes>` functions, but it is also used in the get_var and store_var methods of :ref:`class_FileAccess` as well as the packet APIs for :ref:`class_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;

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: :ref:`bool<class_bool>`

2: :ref:`int<class_int>`

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

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

3: :ref:`float<class_float>`

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

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

4: :ref:`String<class_string>`

This field is padded to 4 bytes.

5: :ref:`Vector2<class_vector2>`

6: :ref:`Rect2<class_rect2>`

7: :ref:`Vector3<class_vector3>`

8: :ref:`Transform2D<class_transform2d>`

9: :ref:`Plane<class_plane>`

10: :ref:`Quaternion<class_quaternion>`

11: :ref:`AABB<class_aabb>`

12: :ref:`Basis<class_basis>`

13: :ref:`Transform3D<class_transform3d>`

14: :ref:`Color<class_color>`

15: :ref:`NodePath<class_nodepath>`

For old format:

Padded to 4 bytes.

For new format:

For each Name and Sub-Name

Every name string is padded to 4 bytes.

16: :ref:`RID<class_rid>` (unsupported)

17: :ref:`Object<class_object>`

An Object could be serialized in three different ways: as a null value, with full_objects = false, or with full_objects = true.

A null value

full_objects disabled

full_objects enabled

For each property:

18: :ref:`Dictionary<class_dictionary>`

Then what follows is, for amount of "elements", pairs of key and value, one after the other, using this same format.

19: :ref:`Array<class_array>`

Then what follows is, for amount of "elements", values one after the other, using this same format.

20: :ref:`PackedByteArray<class_PackedByteArray>`

The array data is padded to 4 bytes.

21: :ref:`PackedInt32Array<class_PackedInt32Array>`

22: :ref:`PackedInt64Array<class_PackedInt64Array>`

23: :ref:`PackedFloat32Array<class_PackedFloat32Array>`

24: :ref:`PackedFloat64Array<class_PackedFloat64Array>`

25: :ref:`PackedStringArray<class_PackedStringArray>`

For each String:

Every string is padded to 4 bytes.

26: :ref:`PackedVector2Array<class_PackedVector2Array>`

27: :ref:`PackedVector3Array<class_PackedVector3Array>`

28: :ref:`PackedColorArray<class_PackedColorArray>`