:article_outdated: True .. _doc_binary_serialization_api: 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() ` and :ref:`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; +--------+--------------------------+ | Type | Value | +========+==========================+ | 0 | null | +--------+--------------------------+ | 1 | bool | +--------+--------------------------+ | 2 | integer | +--------+--------------------------+ | 3 | float | +--------+--------------------------+ | 4 | string | +--------+--------------------------+ | 5 | vector2 | +--------+--------------------------+ | 6 | rect2 | +--------+--------------------------+ | 7 | vector3 | +--------+--------------------------+ | 8 | transform2d | +--------+--------------------------+ | 9 | plane | +--------+--------------------------+ | 10 | quaternion | +--------+--------------------------+ | 11 | aabb | +--------+--------------------------+ | 12 | basis | +--------+--------------------------+ | 13 | transform3d | +--------+--------------------------+ | 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, 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+-----------+---------------------------+ | Offset | Len | Type | Description | +==========+=======+===========+===========================+ | 4 | 4 | Integer | 0 for False, 1 for True | +----------+-------+-----------+---------------------------+ 2: :ref:`int` ^^^^^^^^^^^^^^^^^^^^^^^^ If no flags are set (flags == 0), the integer is sent as a 32 bit integer: +----------+-------+-----------+--------------------------+ | Offset | Len | Type | Description | +==========+=======+===========+==========================+ | 4 | 4 | Integer | 32-bit signed integer | +----------+-------+-----------+--------------------------+ If flag ``ENCODE_FLAG_64`` is set (``flags & 1 == 1``), the integer is sent as a 64-bit integer: +----------+-------+-----------+--------------------------+ | Offset | Len | Type | Description | +==========+=======+===========+==========================+ | 4 | 8 | Integer | 64-bit signed integer | +----------+-------+-----------+--------------------------+ 3: :ref:`float` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If no flags are set (flags == 0), the float is sent as a 32 bit single precision: +----------+-------+---------+-----------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+===================================+ | 4 | 4 | Float | IEEE 754 single-precision float | +----------+-------+---------+-----------------------------------+ If flag ``ENCODE_FLAG_64`` is set (``flags & 1 == 1``), the float is sent as a 64-bit double precision number: +----------+-------+---------+-----------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+===================================+ | 4 | 8 | Float | IEEE 754 double-precision float | +----------+-------+---------+-----------------------------------+ 4: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ | 4 | 4 | Float | X coordinate | +----------+-------+---------+----------------+ | 8 | 4 | Float | Y coordinate | +----------+-------+---------+----------------+ 6: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ | 4 | 4 | Float | X coordinate | +----------+-------+---------+----------------+ | 8 | 4 | Float | Y coordinate | +----------+-------+---------+----------------+ | 12 | 4 | Float | Z coordinate | +----------+-------+---------+----------------+ 8: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+---------------+ | 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:`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: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+---------------------------------------------------------------+ | 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:`Transform3D` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+---------------------------------------------------------------+ | 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+---------+--------------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+==============================================================+ | 4 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | +----------+-------+---------+--------------------------------------------------------------+ | 8 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | +----------+-------+---------+--------------------------------------------------------------+ | 12 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | +----------+-------+---------+--------------------------------------------------------------+ | 16 | 4 | Float | Alpha (0..1) | +----------+-------+---------+--------------------------------------------------------------+ 15: :ref:`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` (unsupported) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17: :ref:`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 """""""""""" +----------+-------+------------+-------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+============+=================================================+ | 4 | 4 | Integer | Zero (32-bit signed integer) | +----------+-------+------------+-------------------------------------------------+ ``full_objects`` disabled """"""""""""""""""""""""" +----------+-------+------------+-------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+============+=================================================+ | 4 | 8 | Integer | The Object instance ID (64-bit signed integer) | +----------+-------+------------+-------------------------------------------------+ ``full_objects`` enabled """""""""""""""""""""""" +----------+-------+----------------+----------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+================+==========================================================+ | 4 | 4 | Integer | Class name (String length) | +----------+-------+----------------+----------------------------------------------------------+ | 8 | X | Bytes | Class name (UTF-8 encoded string) | +----------+-------+----------------+----------------------------------------------------------+ | X+8 | 4 | Integer | The number of properties that are serialized | +----------+-------+----------------+----------------------------------------------------------+ For each property: +----------+-------+----------------+----------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+================+==========================================================+ | Y | 4 | Integer | Property name (String length) | +----------+-------+----------------+----------------------------------------------------------+ | Y+4 | Z | Bytes | Property name (UTF-8 encoded string) | +----------+-------+----------------+----------------------------------------------------------+ | Y+4+Z | W | | Property value, using this same format | +----------+-------+----------------+----------------------------------------------------------+ .. Note:: Not all properties are included. Only properties that are configured with the :ref:`PROPERTY_USAGE_STORAGE` flag set will be serialized. You can add a new usage flag to a property by overriding the :ref:`_get_property_list` method in your class. You can also check how property usage is configured by calling ``Object._get_property_list`` See :ref:`PropertyUsageFlags` for the possible usage flags. 18: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------+-----------+---------------------------------------------------------------------+ | 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------+-------+-----------+------------------------+ | 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------+-------+-----------+---------------------------+ | Offset | Len | Type | Description | +==================+=======+===========+===========================+ | 4 | 4 | Integer | Array length (Integers) | +------------------+-------+-----------+---------------------------+ | 8..8+length\*4 | 4 | Integer | 32-bit signed integer | +------------------+-------+-----------+---------------------------+ 22: :ref:`PackedInt64Array` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------+-------+-----------+---------------------------+ | Offset | Len | Type | Description | +==================+=======+===========+===========================+ | 4 | 8 | Integer | Array length (Integers) | +------------------+-------+-----------+---------------------------+ | 8..8+length\*8 | 8 | Integer | 64-bit signed integer | +------------------+-------+-----------+---------------------------+ 23: :ref:`PackedFloat32Array` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------+-------+-----------+-------------------------------------------+ | Offset | Len | Type | Description | +==================+=======+===========+===========================================+ | 4 | 4 | Integer | Array length (Floats) | +------------------+-------+-----------+-------------------------------------------+ | 8..8+length\*4 | 4 | Integer | 32-bit IEEE 754 single-precision float | +------------------+-------+-----------+-------------------------------------------+ 24: :ref:`PackedFloat64Array` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------+-------+-----------+-------------------------------------------+ | Offset | Len | Type | Description | +==================+=======+===========+===========================================+ | 4 | 4 | Integer | Array length (Floats) | +------------------+-------+-----------+-------------------------------------------+ | 8..8+length\*8 | 8 | Integer | 64-bit IEEE 754 double-precision float | +------------------+-------+-----------+-------------------------------------------+ 25: :ref:`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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------+-------+-----------+----------------+ | 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------+-------+-----------+----------------+ | 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` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------+-------+-----------+--------------------------------------------------------------+ | Offset | Len | Type | Description | +====================+=======+===========+==============================================================+ | 4 | 4 | Integer | Array length | +--------------------+-------+-----------+--------------------------------------------------------------+ | 8..8+length\*16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | +--------------------+-------+-----------+--------------------------------------------------------------+ | 8..12+length\*16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | +--------------------+-------+-----------+--------------------------------------------------------------+ | 8..16+length\*16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | +--------------------+-------+-----------+--------------------------------------------------------------+ | 8..20+length\*16 | 4 | Float | Alpha (0..1) | +--------------------+-------+-----------+--------------------------------------------------------------+