.. _doc_binary_serialization_api:

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 :ref:`class_File`
as well as the packet APIs for :ref:`class_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. If instead doubles are used, the length of "Float" fields within
data structures should be 8, and the offset should be (offset - 4) * 2 + 4.
The "float" type itself is always double precision.

0: null
~~~~~~~

1: :ref:`bool<class_bool>`
~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------+-------+-----------+---------------------------+
| Offset   | Len   | Type      | Description               |
+==========+=======+===========+===========================+
| 4        | 4     | Integer   | 0 for False, 1 for True   |
+----------+-------+-----------+---------------------------+

2: :ref:`int<class_int>`
~~~~~~~~~~~~~~~~~~~~~~~~

+----------+-------+-----------+--------------------------+
| Offset   | Len   | Type      | Description              |
+==========+=======+===========+==========================+
| 4        | 8     | Integer   | Signed, 64-bit Integer   |
+----------+-------+-----------+--------------------------+

3: :ref:`float<class_float>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------+-------+---------+-----------------------------------+
| Offset   | Len   | Type    | Description                       |
+==========+=======+=========+===================================+
| 4        | 8     | Float   | IEEE 754 Double-precision Float   |
+----------+-------+---------+-----------------------------------+

4: :ref:`String<class_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: :ref:`Vector2<class_vector2>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------+-------+---------+----------------+
| Offset   | Len   | Type    | Description    |
+==========+=======+=========+================+
| 4        | 4     | Float   | X Coordinate   |
+----------+-------+---------+----------------+
| 8        | 4     | Float   | Y Coordinate   |
+----------+-------+---------+----------------+

6: :ref:`Rect2<class_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: :ref:`Vector3<class_vector3>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------+-------+---------+----------------+
| Offset   | Len   | Type    | Description    |
+==========+=======+=========+================+
| 4        | 4     | Float   | X Coordinate   |
+----------+-------+---------+----------------+
| 8        | 4     | Float   | Y Coordinate   |
+----------+-------+---------+----------------+
| 12       | 4     | Float   | Z Coordinate   |
+----------+-------+---------+----------------+

8: :ref:`Transform2D<class_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: :ref:`Plane<class_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: :ref:`Quat<class_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: :ref:`AABB<class_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: :ref:`Basis<class_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: :ref:`Transform<class_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: :ref:`Color<class_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: :ref:`NodePath<class_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: :ref:`RID<class_rid>` (unsupported)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

17: :ref:`Object<class_object>` (unsupported)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

18: :ref:`Dictionary<class_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: :ref:`Array<class_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: :ref:`PackedByteArray<class_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: :ref:`PackedInt32Array<class_PackedInt32Array>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

22: :ref:`PackedInt64Array<class_PackedInt64Array>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+------------------+-------+-----------+---------------------------+
| Offset           | Len   | Type      | Description               |
+==================+=======+===========+===========================+
| 4                | 8     | Integer   | Array Length (Integers)   |
+------------------+-------+-----------+---------------------------+
| 8..8+length\*8   | 8     | Integer   | 64 Bits Signed Integer    |
+------------------+-------+-----------+---------------------------+

23: :ref:`PackedFloat32Array<class_PackedFloat32Array>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+------------------+-------+-----------+-------------------------------------------+
| Offset           | Len   | Type      | Description                               |
+==================+=======+===========+===========================================+
| 4                | 4     | Integer   | Array Length (Floats)                     |
+------------------+-------+-----------+-------------------------------------------+
| 8..8+length\*4   | 4     | Integer   | 32 Bits IEEE 754 Single-precision float   |
+------------------+-------+-----------+-------------------------------------------+

24: :ref:`PackedFloat64Array<class_PackedFloat64Array>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+------------------+-------+-----------+-------------------------------------------+
| Offset           | Len   | Type      | Description                               |
+==================+=======+===========+===========================================+
| 4                | 4     | Integer   | Array Length (Floats)                     |
+------------------+-------+-----------+-------------------------------------------+
| 8..8+length\*8   | 8     | Integer   | 64 Bits IEEE 754 Double-precision float   |
+------------------+-------+-----------+-------------------------------------------+

25: :ref:`PackedStringArray<class_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: :ref:`PackedVector2Array<class_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: :ref:`PackedVector3Array<class_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: :ref:`PackedColorArray<class_PackedColorArray>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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