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