505 lines
20 KiB
ReStructuredText
505 lines
20 KiB
ReStructuredText
.. _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 | byte array |
|
|
+--------+--------------------------+
|
|
| 23 | int array |
|
|
+--------+--------------------------+
|
|
| 24 | float array |
|
|
+--------+--------------------------+
|
|
| 25 | string array |
|
|
+--------+--------------------------+
|
|
| 26 | vector2 array |
|
|
+--------+--------------------------+
|
|
| 27 | vector3 array |
|
|
+--------+--------------------------+
|
|
| 28 | color array |
|
|
+--------+--------------------------+
|
|
|
|
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: byte array
|
|
~~~~~~~~~~~~~~
|
|
|
|
+---------------+-------+-----------+------------------------+
|
|
| 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: int array
|
|
~~~~~~~~~~~~~
|
|
|
|
+------------------+-------+-----------+---------------------------+
|
|
| Offset | Len | Type | Description |
|
|
+==================+=======+===========+===========================+
|
|
| 4 | 4 | Integer | Array Length (Integers) |
|
|
+------------------+-------+-----------+---------------------------+
|
|
| 8..8+length\*4 | 4 | Integer | 32 Bits Signed Integer |
|
|
+------------------+-------+-----------+---------------------------+
|
|
|
|
24: float array
|
|
~~~~~~~~~~~~~~~
|
|
|
|
+------------------+-------+-----------+---------------------------+
|
|
| Offset | Len | Type | Description |
|
|
+==================+=======+===========+===========================+
|
|
| 4 | 4 |Integer | Array Length (Floats) |
|
|
+------------------+-------+-----------+---------------------------+
|
|
| 8..8+length\*4 | 4 |Integer | 32 Bits IEE 754 Float |
|
|
+------------------+-------+-----------+---------------------------+
|
|
|
|
25: string array
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
+----------+-------+-----------+--------------------------+
|
|
| 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: vector2 array
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+-------------------+-------+-----------+----------------+
|
|
| 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: vector3 array
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+--------------------+-------+-----------+----------------+
|
|
| 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: color array
|
|
~~~~~~~~~~~~~~~
|
|
|
|
+--------------------+-------+-----------+----------------+
|
|
| 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) |
|
|
+--------------------+-------+-----------+----------------+
|