godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-07 02:12:07 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
0f4a5ae4ee4a46188b8ddc39078c0f2c17434d5c
godot-docs/reference/binary_serialization_api.rst
eska 0f4a5ae4ee Fix character references
2016-02-11 18:39:20 +01:00

494 lines
19 KiB
ReStructuredText
Raw Blame History

.. _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 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 | 4 | Float | Y Coordinate |
| 8..12+length_8 | | | |
+-------------------------------------------+-------+-----------+----------------+
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) | 4 | Float | Green (0..1) |
| 8..12+length_16 | | | |
+--------------------------------------------+-------+-----------+----------------+
| 8..16+length_16\|4\|Float\| Blue (0..1) | 4 | Float | Alpha (0..1) |
| 8..20+length_16 | | | |
+--------------------------------------------+-------+-----------+----------------+
Reference in New Issue View Git Blame Copy Permalink