godot-docs/learning/features/misc/binary_serialization_api.rst

.. _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      | 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: :ref:`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: :ref:`class_IntArray`
~~~~~~~~~~~~~

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

24: :ref:`class_FloatArray`
~~~~~~~~~~~~~~~

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

25: :ref:`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: :ref:`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: :ref:`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: :ref:`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)   |
+--------------------+-------+-----------+----------------+