From 9ab8629913e166512448731f7295c3fc21a999e8 Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Sat, 6 Dec 2025 17:02:25 -0500 Subject: [PATCH 1/6] Update binary serialization documentation Update binary serialization documentation from Godot version < 4 to 4.5.1 --- tutorials/io/binary_serialization_api.rst | 796 ++++++++++++++++------ 1 file changed, 595 insertions(+), 201 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 09bd39bdb4d..1bc22d11e06 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -1,5 +1,3 @@ -:article_outdated: True - .. _doc_binary_serialization_api: Binary serialization API @@ -33,13 +31,16 @@ 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: +The header is structured as follows: + +- Byte 0 (bits 0-7): ``Variant::Type`` +- Byte 1 (bits 8-15): Unused +- Bytes 2-3 (bits 16-31): Additional data (type-specific flags) :: - base_type = val & 0xFFFF; - flags = val >> 16; + type = header & 0xFF; + flags = header >> 16; +--------+--------------------------+ | Type | Value | @@ -48,62 +49,116 @@ two bytes contain flags: +--------+--------------------------+ | 1 | bool | +--------+--------------------------+ -| 2 | integer | +| 2 | int | +--------+--------------------------+ | 3 | float | +--------+--------------------------+ -| 4 | string | +| 4 | String | ++--------+--------------------------+ +| 5 | Vector2 | ++--------+--------------------------+ +| 6 | Vector2i | ++--------+--------------------------+ +| 7 | Rect2 | ++--------+--------------------------+ +| 8 | Rect2i | ++--------+--------------------------+ +| 9 | Vector3 | +--------+--------------------------+ -| 5 | vector2 | +| 10 | Vector3i | +--------+--------------------------+ -| 6 | rect2 | +| 11 | Vector4 | +--------+--------------------------+ -| 7 | vector3 | +| 12 | Vector4i | +--------+--------------------------+ -| 8 | transform2d | +| 13 | Transform2D | +--------+--------------------------+ -| 9 | plane | +| 14 | Plane | +--------+--------------------------+ -| 10 | quaternion | +| 15 | Quaternion | +--------+--------------------------+ -| 11 | aabb | +| 16 | AABB | +--------+--------------------------+ -| 12 | basis | +| 17 | Basis | +--------+--------------------------+ -| 13 | transform3d | +| 18 | Transform3D | +--------+--------------------------+ -| 14 | color | +| 19 | Projection | +--------+--------------------------+ -| 15 | node path | +| 20 | Color | +--------+--------------------------+ -| 16 | rid | +| 21 | StringName | +--------+--------------------------+ -| 17 | object | +| 22 | NodePath | +--------+--------------------------+ -| 18 | dictionary | +| 23 | RID | +--------+--------------------------+ -| 19 | array | +| 24 | Object | +--------+--------------------------+ -| 20 | raw array | +| 25 | Callable | +--------+--------------------------+ -| 21 | int32 array | +| 26 | Signal | +--------+--------------------------+ -| 22 | int64 array | +| 27 | Dictionary | +--------+--------------------------+ -| 23 | float32 array | +| 28 | Array | +--------+--------------------------+ -| 24 | float64 array | +| 29 | PackedByteArray | +--------+--------------------------+ -| 25 | string array | +| 30 | PackedInt32Array | +--------+--------------------------+ -| 26 | vector2 array | +| 31 | PackedInt64Array | +--------+--------------------------+ -| 27 | vector3 array | +| 32 | PackedFloat32Array | +--------+--------------------------+ -| 28 | color array | +| 33 | PackedFloat64Array | +--------+--------------------------+ -| 29 | max | +| 34 | PackedStringArray | +--------+--------------------------+ +| 35 | PackedVector2Array | ++--------+--------------------------+ +| 36 | PackedVector3Array | ++--------+--------------------------+ +| 37 | PackedColorArray | ++--------+--------------------------+ +| 38 | PackedVector4Array | ++--------+--------------------------+ + +Header Flags +~~~~~~~~~~~~ + +The header's upper 16 bits contain type-specific flags: + ++------------------------------------------+-------------------------------------------+ +| Flag | Description | ++==========================================+===========================================+ +| ``ENCODE_FLAG_64 = (1 << 16)`` | Used for int, float, and math types to | +| | indicate 64-bit (double) precision | ++------------------------------------------+-------------------------------------------+ +| ``ENCODE_FLAG_OBJECT_AS_ID = (1 << 16)`` | Used for Object to indicate serialization | +| | as instance ID only | ++------------------------------------------+-------------------------------------------+ + +For typed containers (Array and Dictionary), additional flags indicate the +container's type information: + +**Array (bits 16-17):** + ++-------+--------------------------------------+ +| Value | Meaning | ++=======+======================================+ +| 0b00 | Untyped | ++-------+--------------------------------------+ +| 0b01 | Typed with builtin type | ++-------+--------------------------------------+ +| 0b10 | Typed with class name | ++-------+--------------------------------------+ +| 0b11 | Typed with script path | ++-------+--------------------------------------+ + +**Dictionary key type (bits 16-17) and value type (bits 18-19):** + +Same values as Array. 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, @@ -167,19 +222,21 @@ a 64-bit double precision number: 4: :ref:`String` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+----------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+============================+ -| 4 | 4 | Integer | String length (in bytes) | -+----------+-------+-----------+----------------------------+ -| 8 | X | Bytes | UTF-8 encoded string | -+----------+-------+-----------+----------------------------+ ++----------+-------+-----------+------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+==============================+ +| 4 | 4 | Integer | String length (in byte, N) | ++----------+-------+-----------+------------------------------+ +| 8 | N | Bytes | UTF-8 encoded string | ++----------+-------+-----------+------------------------------+ This field is padded to 4 bytes. 5: :ref:`Vector2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ @@ -188,24 +245,78 @@ This field is padded to 4 bytes. | 8 | 4 | Float | Y coordinate | +----------+-------+---------+----------------+ -6: :ref:`Rect2` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + ++----------+-------+---------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+================+ +| 4 | 8 | Double | X coordinate | ++----------+-------+---------+----------------+ +| 12 | 8 | Double | Y coordinate | ++----------+-------+---------+----------------+ + +6: :ref:`Vector2i` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+-------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+-------+-----------+----------------+ + +7: :ref:`Rect2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ -| 4 | 4 | Float | X coordinate | +| 4 | 4 | Float | X position | +----------+-------+---------+----------------+ -| 8 | 4 | Float | Y coordinate | +| 8 | 4 | Float | Y position | +----------+-------+---------+----------------+ | 12 | 4 | Float | X size | +----------+-------+---------+----------------+ | 16 | 4 | Float | Y size | +----------+-------+---------+----------------+ -7: :ref:`Vector3` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + ++----------+-------+---------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+================+ +| 4 | 8 | Double | X position | ++----------+-------+---------+----------------+ +| 12 | 8 | Double | Y position | ++----------+-------+---------+----------------+ +| 20 | 8 | Double | X size | ++----------+-------+---------+----------------+ +| 28 | 8 | Double | Y size | ++----------+-------+---------+----------------+ + +8: :ref:`Rect2i` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+================+ +| 4 | 4 | Integer | X position | ++----------+-------+-----------+----------------+ +| 8 | 4 | Integer | Y position | ++----------+-------+-----------+----------------+ +| 12 | 4 | Integer | X size | ++----------+-------+-----------+----------------+ +| 16 | 4 | Integer | Y size | ++----------+-------+-----------+----------------+ + +9: :ref:`Vector3` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ @@ -216,8 +327,81 @@ This field is padded to 4 bytes. | 12 | 4 | Float | Z coordinate | +----------+-------+---------+----------------+ -8: :ref:`Transform2D` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + ++----------+-------+---------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+================+ +| 4 | 8 | Double | X coordinate | ++----------+-------+---------+----------------+ +| 12 | 8 | Double | Y coordinate | ++----------+-------+---------+----------------+ +| 20 | 8 | Double | Z coordinate | ++----------+-------+---------+----------------+ + +10: :ref:`Vector3i` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+-------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+-------+-----------+----------------+ +| 12 | 4 | Integer | Z coordinate | ++----------+-------+-----------+----------------+ + +11: :ref:`Vector4` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + ++----------+-------+---------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+================+ +| 4 | 4 | Float | X coordinate | ++----------+-------+---------+----------------+ +| 8 | 4 | Float | Y coordinate | ++----------+-------+---------+----------------+ +| 12 | 4 | Float | Z coordinate | ++----------+-------+---------+----------------+ +| 16 | 4 | Float | W coordinate | ++----------+-------+---------+----------------+ + +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + ++----------+-------+---------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+================+ +| 4 | 8 | Double | X coordinate | ++----------+-------+---------+----------------+ +| 12 | 8 | Double | Y coordinate | ++----------+-------+---------+----------------+ +| 20 | 8 | Double | Z coordinate | ++----------+-------+---------+----------------+ +| 28 | 8 | Double | W coordinate | ++----------+-------+---------+----------------+ + +12: :ref:`Vector4i` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+-------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+-------+-----------+----------------+ +| 12 | 4 | Integer | Z coordinate | ++----------+-------+-----------+----------------+ +| 16 | 4 | Integer | W coordinate | ++----------+-------+-----------+----------------+ + +13: :ref:`Transform2D` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: +----------+-------+---------+---------------------------------------------------------------+ | Offset | Len | Type | Description | @@ -235,8 +419,12 @@ This field is padded to 4 bytes. | 24 | 4 | Float | The Y component of the origin vector, accessed via [2][1] | +----------+-------+---------+---------------------------------------------------------------+ -9: :ref:`Plane` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + +14: :ref:`Plane` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: +----------+-------+---------+---------------+ | Offset | Len | Type | Description | @@ -247,12 +435,16 @@ This field is padded to 4 bytes. +----------+-------+---------+---------------+ | 12 | 4 | Float | Normal Z | +----------+-------+---------+---------------+ -| 16 | 4 | Float | Distance | +| 16 | 4 | Float | Distance D | +----------+-------+---------+---------------+ -10: :ref:`Quaternion` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: + +15: :ref:`Quaternion` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+---------------+ | Offset | Len | Type | Description | +==========+=======+=========+===============+ @@ -265,17 +457,21 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Real W | +----------+-------+---------+---------------+ -11: :ref:`AABB` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +16: :ref:`AABB` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+----------------+ | Offset | Len | Type | Description | +==========+=======+=========+================+ -| 4 | 4 | Float | X coordinate | +| 4 | 4 | Float | X position | +----------+-------+---------+----------------+ -| 8 | 4 | Float | Y coordinate | +| 8 | 4 | Float | Y position | +----------+-------+---------+----------------+ -| 12 | 4 | Float | Z coordinate | +| 12 | 4 | Float | Z position | +----------+-------+---------+----------------+ | 16 | 4 | Float | X size | +----------+-------+---------+----------------+ @@ -284,34 +480,42 @@ This field is padded to 4 bytes. | 24 | 4 | Float | Z size | +----------+-------+---------+----------------+ -12: :ref:`Basis` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +17: :ref:`Basis` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+---------------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+===============================================================+ -| 4 | 4 | Float | The X component of the X column vector, accessed via [0][0] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 36 | 4 | Float | The Z component of the Z column vector, accessed via [2][2] | +----------+-------+---------+---------------------------------------------------------------+ -13: :ref:`Transform3D` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +18: :ref:`Transform3D` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +----------+-------+---------+---------------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+===============================================================+ @@ -340,7 +544,53 @@ This field is padded to 4 bytes. | 48 | 4 | Float | The Z component of the origin vector, accessed via [3][2] | +----------+-------+---------+---------------------------------------------------------------+ -14: :ref:`Color` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +19: :ref:`Projection` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + ++----------+-------+---------+------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+=========+==============================+ +| 4 | 4 | Float | x.x (Column 0, Row 0) | ++----------+-------+---------+------------------------------+ +| 8 | 4 | Float | x.y (Column 0, Row 1) | ++----------+-------+---------+------------------------------+ +| 12 | 4 | Float | x.z (Column 0, Row 2) | ++----------+-------+---------+------------------------------+ +| 16 | 4 | Float | x.w (Column 0, Row 3) | ++----------+-------+---------+------------------------------+ +| 20 | 4 | Float | y.x (Column 1, Row 0) | ++----------+-------+---------+------------------------------+ +| 24 | 4 | Float | y.y (Column 1, Row 1) | ++----------+-------+---------+------------------------------+ +| 28 | 4 | Float | y.z (Column 1, Row 2) | ++----------+-------+---------+------------------------------+ +| 32 | 4 | Float | y.w (Column 1, Row 3) | ++----------+-------+---------+------------------------------+ +| 36 | 4 | Float | z.x (Column 2, Row 0) | ++----------+-------+---------+------------------------------+ +| 40 | 4 | Float | z.y (Column 2, Row 1) | ++----------+-------+---------+------------------------------+ +| 44 | 4 | Float | z.z (Column 2, Row 2) | ++----------+-------+---------+------------------------------+ +| 48 | 4 | Float | z.w (Column 2, Row 3) | ++----------+-------+---------+------------------------------+ +| 52 | 4 | Float | w.x (Column 3, Row 0) | ++----------+-------+---------+------------------------------+ +| 56 | 4 | Float | w.y (Column 3, Row 1) | ++----------+-------+---------+------------------------------+ +| 60 | 4 | Float | w.z (Column 3, Row 2) | ++----------+-------+---------+------------------------------+ +| 64 | 4 | Float | w.w (Column 3, Row 3) | ++----------+-------+---------+------------------------------+ + +Total of 16 floats (64 bytes for single precision, 128 bytes for double). +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +20: :ref:`Color` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+--------------------------------------------------------------+ @@ -355,137 +605,207 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Alpha (0..1) | +----------+-------+---------+--------------------------------------------------------------+ -15: :ref:`NodePath` +21: :ref:`StringName` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Encoded identically to String (see type 4). + +22: :ref:`NodePath` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+-----------------------------------------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+===========+=========================================================================================+ -| 4 | 4 | Integer | String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) | +| 4 | 4 | Integer | Name count with new format flag (val & 0x80000000 != 0, NameCount = val & 0x7FFFFFFF) | +----------+-------+-----------+-----------------------------------------------------------------------------------------+ -For old format: -~~~~~~~~~~~~~~~ - -+----------+-------+---------+------------------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+========================+ -| 8 | X | Bytes | UTF-8 encoded string | -+----------+-------+---------+------------------------+ - -Padded to 4 bytes. +The old format is no longer supported and will return an error. For new format: ~~~~~~~~~~~~~~~ -+----------+-------+-----------+-------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=====================================+ -| 4 | 4 | Integer | Sub-name count | -+----------+-------+-----------+-------------------------------------+ -| 8 | 4 | Integer | Flags (absolute: val&1 != 0 ) | -+----------+-------+-----------+-------------------------------------+ ++----------+-------+-----------+--------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+============================================+ +| 8 | 4 | Integer | Sub-name count | ++----------+-------+-----------+--------------------------------------------+ +| 12 | 4 | Integer | Flags (bit 0: absolute, bit 1: property) | ++----------+-------+-----------+--------------------------------------------+ + +.. note:: -For each Name and Sub-Name + If bit 1 (property flag) is set, the sub-name count is incremented by 1 + internally. This is an obsolete format for backwards compatibility. -+----------+-------+-----------+------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+========================+ -| X+0 | 4 | Integer | String length | -+----------+-------+-----------+------------------------+ -| X+4 | X | Bytes | UTF-8 encoded string | -+----------+-------+-----------+------------------------+ +For each Name and Sub-Name (offsets are relative to the start of each string entry): + ++----------+-------+-----------+-----------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+=============================+ +| 0 | 4 | Integer | String length (in bytes, N) | ++----------+-------+-----------+-----------------------------+ +| 4 | N | Bytes | UTF-8 encoded string | ++----------+-------+-----------+-----------------------------+ Every name string is padded to 4 bytes. -16: :ref:`RID` (unsupported) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +23: :ref:`RID` +~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+-----------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+=================+ +| 4 | 8 | Integer | 64-bit RID ID | ++----------+-------+-----------+-----------------+ -17: :ref:`Object` +24: :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:: +An Object can be serialized in two ways, determined by the +``ENCODE_FLAG_OBJECT_AS_ID`` header flag (``flags & 1 == 1``). + +With ``ENCODE_FLAG_OBJECT_AS_ID`` set (instance ID only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------+-------+------------+-----------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+============+===================================+ +| 4 | 8 | Integer | The Object instance ID (64-bit) | ++----------+-------+------------+-----------------------------------+ + +If the instance ID is 0, it represents a null object. + +Without ``ENCODE_FLAG_OBJECT_AS_ID`` (full object) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This mode requires ``full_objects = true`` when decoding, otherwise an error +is returned. + +**Null object:** + ++----------+-------+-----------+--------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+============================================+ +| 4 | 4 | Integer | 0 (empty string length, indicating null) | ++----------+-------+-----------+--------------------------------------------+ + +**Non-null object:** + ++----------+-------+----------------+--------------------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+================+========================================================+ +| 4 | 4 | Integer | Class name (String length, N) | ++----------+-------+----------------+--------------------------------------------------------+ +| 8 | N | Bytes | Class name (UTF-8 encoded string, padded to 4 bytes) | ++----------+-------+----------------+--------------------------------------------------------+ +| 8+N | 4 | Integer | The number of properties that are serialized | ++----------+-------+----------------+--------------------------------------------------------+ + +For each property (offsets relative to the start of each property): + ++----------+-------+----------------+-----------------------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+================+===========================================================+ +| 0 | 4 | Integer | Property name (String length, N) | ++----------+-------+----------------+-----------------------------------------------------------+ +| 4 | N | Bytes | Property name (UTF-8 encoded string, padded to 4 bytes) | ++----------+-------+----------------+-----------------------------------------------------------+ +| 4+N+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 + calling ``Object._get_property_list``. See :ref:`PropertyUsageFlags` for the possible usage flags. -18: :ref:`Dictionary` +.. note:: + + If a property named ``script`` is present and its value is a String, it is + treated specially: the string is interpreted as a resource path to a Script, + which is loaded and assigned to the object. + +25: :ref:`Callable` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Callables cannot be meaningfully serialized. No additional data is written, +and decoding produces an empty Callable. + +26: :ref:`Signal` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------+-------+-----------+-------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+===============================+ +| 4 | 4 | Integer | Signal name string length (N) | ++----------+-------+-----------+-------------------------------+ +| 8 | N | Bytes | Signal name (UTF-8, padded) | ++----------+-------+-----------+-------------------------------+ +| 8+N | 8 | Integer | Object instance ID (64-bit) | ++----------+-------+-----------+-------------------------------+ + +27: :ref:`Dictionary` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+---------------------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=====================================================================+ -| 4 | 4 | Integer | val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) | -+----------+-------+-----------+---------------------------------------------------------------------+ +For typed dictionaries, the header flags indicate the type kind for both keys +and values (see Header Flags section). Depending on these flags, type +information is encoded before the element count. -Then what follows is, for amount of "elements", pairs of key and value, -one after the other, using this same format. +**Container Type Encoding (for each of key type and value type, if not NONE):** -19: :ref:`Array` +If type kind is ``BUILTIN`` (0b01): + ++----------+-------+-----------+----------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+============================+ +| 4 | 4 | Integer | Variant type ID | ++----------+-------+-----------+----------------------------+ + +If type kind is ``CLASS_NAME`` (0b10) or ``SCRIPT`` (0b11): + ++----------+-------+-----------+-----------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+===============================================+ +| 4 | 4 | Integer | Class name or script path string length (N) | ++----------+-------+-----------+-----------------------------------------------+ +| 8 | N | Bytes | Class name or script path (UTF-8, padded) | ++----------+-------+-----------+-----------------------------------------------+ + +Value type encoding, if applicable, immediately follows key type encoding. + +**Element count (immediately following all type information):** + ++----------+-------+-----------+----------------------------------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+======================================================================+ +| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | ++----------+-------+-----------+----------------------------------------------------------------------+ + +Then what follows is, for each element, a key-value pair encoded one after +the other using this same format. + +28: :ref:`Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+---------------------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=====================================================================+ -| 4 | 4 | Integer | val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) | -+----------+-------+-----------+---------------------------------------------------------------------+ +For typed arrays, the header flags indicate the element type kind (see Header +Flags section). The container type is encoded the same way as Dictionary. + +**Element count (immediately following type information, if any):** -Then what follows is, for amount of "elements", values one after the -other, using this same format. ++----------+-------+-----------+----------------------------------------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+======================================================================+ +| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | ++----------+-------+-----------+----------------------------------------------------------------------+ -20: :ref:`PackedByteArray` +Then what follows is, for each element, a value encoded using this same format. + +29: :ref:`PackedByteArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------+-------+-----------+------------------------+ @@ -498,7 +818,7 @@ other, using this same format. The array data is padded to 4 bytes. -21: :ref:`PackedInt32Array` +30: :ref:`PackedInt32Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------+-------+-----------+---------------------------+ @@ -509,40 +829,40 @@ The array data is padded to 4 bytes. | 8..8+length\*4 | 4 | Integer | 32-bit signed integer | +------------------+-------+-----------+---------------------------+ -22: :ref:`PackedInt64Array` +31: :ref:`PackedInt64Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------+-------+-----------+---------------------------+ | Offset | Len | Type | Description | +==================+=======+===========+===========================+ -| 4 | 8 | Integer | Array length (Integers) | +| 4 | 4 | Integer | Array length (Integers) | +------------------+-------+-----------+---------------------------+ | 8..8+length\*8 | 8 | Integer | 64-bit signed integer | +------------------+-------+-----------+---------------------------+ -23: :ref:`PackedFloat32Array` +32: :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 | -+------------------+-------+-----------+-------------------------------------------+ ++------------------+-------+-----------+-----------------------------------+ +| Offset | Len | Type | Description | ++==================+=======+===========+===================================+ +| 4 | 4 | Integer | Array length (Floats) | ++------------------+-------+-----------+-----------------------------------+ +| 8..8+length\*4 | 4 | Float | IEEE 754 single-precision float | ++------------------+-------+-----------+-----------------------------------+ -24: :ref:`PackedFloat64Array` +33: :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 | -+------------------+-------+-----------+-------------------------------------------+ ++------------------+-------+-----------+-----------------------------------+ +| Offset | Len | Type | Description | ++==================+=======+===========+===================================+ +| 4 | 4 | Integer | Array length (Floats) | ++------------------+-------+-----------+-----------------------------------+ +| 8..8+length\*8 | 8 | Float | IEEE 754 double-precision float | ++------------------+-------+-----------+-----------------------------------+ -25: :ref:`PackedStringArray` +34: :ref:`PackedStringArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+--------------------------+ @@ -551,47 +871,82 @@ The array data is padded to 4 bytes. | 4 | 4 | Integer | Array length (Strings) | +----------+-------+-----------+--------------------------+ -For each String: +For each String (offsets relative to start of each string entry): -+----------+-------+-----------+------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+========================+ -| X+0 | 4 | Integer | String length | -+----------+-------+-----------+------------------------+ -| X+4 | X | Bytes | UTF-8 encoded string | -+----------+-------+-----------+------------------------+ ++----------+-------+-----------+----------------------------------------+ +| Offset | Len | Type | Description | ++==========+=======+===========+========================================+ +| 0 | 4 | Integer | String length (N, including null term) | ++----------+-------+-----------+----------------------------------------+ +| 4 | N | Bytes | UTF-8 encoded string with null | ++----------+-------+-----------+----------------------------------------+ Every string is padded to 4 bytes. -26: :ref:`PackedVector2Array` +.. note:: + + Unlike regular String encoding, PackedStringArray encodes strings with a + null terminator included in the length. + +35: :ref:`PackedVector2Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + ++-------------------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++===================+=======+===========+================+ +| 4 | 4 | Integer | Array length | ++-------------------+-------+-----------+----------------+ +| 8+i\*8 | 4 | Float | X coordinate | ++-------------------+-------+-----------+----------------+ +| 12+i\*8 | 4 | Float | Y coordinate | ++-------------------+-------+-----------+----------------+ + +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + +-------------------+-------+-----------+----------------+ | Offset | Len | Type | Description | +===================+=======+===========+================+ | 4 | 4 | Integer | Array length | +-------------------+-------+-----------+----------------+ -| 8..8+length\*8 | 4 | Float | X coordinate | +| 8+i\*16 | 8 | Double | X coordinate | +-------------------+-------+-----------+----------------+ -| 8..12+length\*8 | 4 | Float | Y coordinate | +| 16+i\*16 | 8 | Double | Y coordinate | +-------------------+-------+-----------+----------------+ -27: :ref:`PackedVector3Array` +36: :ref:`PackedVector3Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + +--------------------+-------+-----------+----------------+ | Offset | Len | Type | Description | +====================+=======+===========+================+ | 4 | 4 | Integer | Array length | +--------------------+-------+-----------+----------------+ -| 8..8+length\*12 | 4 | Float | X coordinate | +| 8+i\*12 | 4 | Float | X coordinate | +--------------------+-------+-----------+----------------+ -| 8..12+length\*12 | 4 | Float | Y coordinate | +| 12+i\*12 | 4 | Float | Y coordinate | +--------------------+-------+-----------+----------------+ -| 8..16+length\*12 | 4 | Float | Z coordinate | +| 16+i\*12 | 4 | Float | Z coordinate | +--------------------+-------+-----------+----------------+ -28: :ref:`PackedColorArray` +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + ++--------------------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++====================+=======+===========+================+ +| 4 | 4 | Integer | Array length | ++--------------------+-------+-----------+----------------+ +| 8+i\*24 | 8 | Double | X coordinate | ++--------------------+-------+-----------+----------------+ +| 16+i\*24 | 8 | Double | Y coordinate | ++--------------------+-------+-----------+----------------+ +| 24+i\*24 | 8 | Double | Z coordinate | ++--------------------+-------+-----------+----------------+ + +37: :ref:`PackedColorArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------+-------+-----------+--------------------------------------------------------------+ @@ -599,11 +954,50 @@ Every string is padded to 4 bytes. +====================+=======+===========+==============================================================+ | 4 | 4 | Integer | Array length | +--------------------+-------+-----------+--------------------------------------------------------------+ -| 8..8+length\*16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | +| 8+i\*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) | +| 12+i\*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) | +| 16+i\*16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | +--------------------+-------+-----------+--------------------------------------------------------------+ -| 8..20+length\*16 | 4 | Float | Alpha (0..1) | +| 20+i\*16 | 4 | Float | Alpha (0..1) | +--------------------+-------+-----------+--------------------------------------------------------------+ + +.. note:: + + Colors are always encoded in single precision. + +38: :ref:`PackedVector4Array` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If no flags are set (flags == 0), the floats are sent as 32 bit single precision: + ++--------------------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++====================+=======+===========+================+ +| 4 | 4 | Integer | Array length | ++--------------------+-------+-----------+----------------+ +| 8+i\*16 | 4 | Float | X coordinate | ++--------------------+-------+-----------+----------------+ +| 12+i\*16 | 4 | Float | Y coordinate | ++--------------------+-------+-----------+----------------+ +| 16+i\*16 | 4 | Float | Z coordinate | ++--------------------+-------+-----------+----------------+ +| 20+i\*16 | 4 | Float | W coordinate | ++--------------------+-------+-----------+----------------+ + +If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. + ++--------------------+-------+-----------+----------------+ +| Offset | Len | Type | Description | ++====================+=======+===========+================+ +| 4 | 4 | Integer | Array length | ++--------------------+-------+-----------+----------------+ +| 8+i\*32 | 8 | Double | X coordinate | ++--------------------+-------+-----------+----------------+ +| 16+i\*32 | 8 | Double | Y coordinate | ++--------------------+-------+-----------+----------------+ +| 24+i\*32 | 8 | Double | Z coordinate | ++--------------------+-------+-----------+----------------+ +| 32+i\*32 | 8 | Double | W coordinate | ++--------------------+-------+-----------+----------------+ From 5cb741a284f1757ac5103d4457f4d359301abe8a Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Sun, 7 Dec 2025 18:28:22 -0500 Subject: [PATCH 2/6] Fix formatting of binary serialization API table --- tutorials/io/binary_serialization_api.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 1bc22d11e06..a66f31f4f1e 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -490,23 +490,23 @@ If no flags are set (flags == 0), the floats are sent as 32 bit single precision +----------+-------+---------+---------------------------------------------------------------+ | Offset | Len | Type | Description | +==========+=======+=========+===============================================================+ -| 4 | 4 | Float | The X component of the X column vector, accessed via [0][0] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 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] | +| 36 | 4 | Float | The Z component of the Z column vector, accessed via [2][2] | +----------+-------+---------+---------------------------------------------------------------+ If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. From 00eaffdace3507a489eba36dd4628e378841fa75 Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Mon, 8 Dec 2025 15:46:29 -0500 Subject: [PATCH 3/6] lots of cleanup of tables/wording, still want to do a few more --- tutorials/io/binary_serialization_api.rst | 1239 ++++++++++----------- 1 file changed, 562 insertions(+), 677 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index a66f31f4f1e..1f1e0faf0db 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -42,87 +42,87 @@ The header is structured as follows: type = header & 0xFF; flags = header >> 16; -+--------+--------------------------+ -| Type | Value | -+========+==========================+ -| 0 | null | -+--------+--------------------------+ -| 1 | bool | -+--------+--------------------------+ -| 2 | int | -+--------+--------------------------+ -| 3 | float | -+--------+--------------------------+ -| 4 | String | -+--------+--------------------------+ -| 5 | Vector2 | -+--------+--------------------------+ -| 6 | Vector2i | -+--------+--------------------------+ -| 7 | Rect2 | -+--------+--------------------------+ -| 8 | Rect2i | -+--------+--------------------------+ -| 9 | Vector3 | -+--------+--------------------------+ -| 10 | Vector3i | -+--------+--------------------------+ -| 11 | Vector4 | -+--------+--------------------------+ -| 12 | Vector4i | -+--------+--------------------------+ -| 13 | Transform2D | -+--------+--------------------------+ -| 14 | Plane | -+--------+--------------------------+ -| 15 | Quaternion | -+--------+--------------------------+ -| 16 | AABB | -+--------+--------------------------+ -| 17 | Basis | -+--------+--------------------------+ -| 18 | Transform3D | -+--------+--------------------------+ -| 19 | Projection | -+--------+--------------------------+ -| 20 | Color | -+--------+--------------------------+ -| 21 | StringName | -+--------+--------------------------+ -| 22 | NodePath | -+--------+--------------------------+ -| 23 | RID | -+--------+--------------------------+ -| 24 | Object | -+--------+--------------------------+ -| 25 | Callable | -+--------+--------------------------+ -| 26 | Signal | -+--------+--------------------------+ -| 27 | Dictionary | -+--------+--------------------------+ -| 28 | Array | -+--------+--------------------------+ -| 29 | PackedByteArray | -+--------+--------------------------+ -| 30 | PackedInt32Array | -+--------+--------------------------+ -| 31 | PackedInt64Array | -+--------+--------------------------+ -| 32 | PackedFloat32Array | -+--------+--------------------------+ -| 33 | PackedFloat64Array | -+--------+--------------------------+ -| 34 | PackedStringArray | -+--------+--------------------------+ -| 35 | PackedVector2Array | -+--------+--------------------------+ -| 36 | PackedVector3Array | -+--------+--------------------------+ -| 37 | PackedColorArray | -+--------+--------------------------+ -| 38 | PackedVector4Array | -+--------+--------------------------+ ++-----------+--------------------------+ +| Valu | Type Description | ++===========+==========================+ +| 0 (0x00) | null | ++-----------+--------------------------+ +| 1 (0x01) | bool | ++-----------+--------------------------+ +| 2 (0x02) | int | ++-----------+--------------------------+ +| 3 (0x03) | float | ++-----------+--------------------------+ +| 4 (0x04) | String | ++-----------+--------------------------+ +| 5 (0x05) | Vector2 | ++-----------+--------------------------+ +| 6 (0x06) | Vector2i | ++-----------+--------------------------+ +| 7 (0x07) | Rect2 | ++-----------+--------------------------+ +| 8 (0x08) | Rect2i | ++-----------+--------------------------+ +| 9 (0x09) | Vector3 | ++-----------+--------------------------+ +| 10 (0x0A) | Vector3i | ++-----------+--------------------------+ +| 11 (0x0B) | Vector4 | ++-----------+--------------------------+ +| 12 (0x0C) | Vector4i | ++-----------+--------------------------+ +| 13 (0x0D) | Transform2D | ++-----------+--------------------------+ +| 14 (0x0E) | Plane | ++-----------+--------------------------+ +| 15 (0x0F) | Quaternion | ++-----------+--------------------------+ +| 16 (0x10) | AABB | ++-----------+--------------------------+ +| 17 (0x11) | Basis | ++-----------+--------------------------+ +| 18 (0x12) | Transform3D | ++-----------+--------------------------+ +| 19 (0x13) | Projection | ++-----------+--------------------------+ +| 20 (0x14) | Color | ++-----------+--------------------------+ +| 21 (0x15) | StringName | ++-----------+--------------------------+ +| 22 (0x16) | NodePath | ++-----------+--------------------------+ +| 23 (0x17) | RID | ++-----------+--------------------------+ +| 24 (0x18) | Object | ++-----------+--------------------------+ +| 25 (0x19) | Callable | ++-----------+--------------------------+ +| 26 (0x1A) | Signal | ++-----------+--------------------------+ +| 27 (0x1B) | Dictionary | ++-----------+--------------------------+ +| 28 (0x1C) | Array | ++-----------+--------------------------+ +| 29 (0x1D) | PackedByteArray | ++-----------+--------------------------+ +| 30 (0x1E) | PackedInt32Array | ++-----------+--------------------------+ +| 31 (0x1F) | PackedInt64Array | ++-----------+--------------------------+ +| 32 (0x20) | PackedFloat32Array | ++-----------+--------------------------+ +| 33 (0x21) | PackedFloat64Array | ++-----------+--------------------------+ +| 34 (0x22) | PackedStringArray | ++-----------+--------------------------+ +| 35 (0x23) | PackedVector2Array | ++-----------+--------------------------+ +| 36 (0x24) | PackedVector3Array | ++-----------+--------------------------+ +| 37 (0x25) | PackedColorArray | ++-----------+--------------------------+ +| 38 (0x26) | PackedVector4Array | ++-----------+--------------------------+ Header Flags ~~~~~~~~~~~~ @@ -133,14 +133,13 @@ The header's upper 16 bits contain type-specific flags: | Flag | Description | +==========================================+===========================================+ | ``ENCODE_FLAG_64 = (1 << 16)`` | Used for int, float, and math types to | -| | indicate 64-bit (double) precision | +| | indicate 64-bit (long/double) precision | +------------------------------------------+-------------------------------------------+ | ``ENCODE_FLAG_OBJECT_AS_ID = (1 << 16)`` | Used for Object to indicate serialization | -| | as instance ID only | +| | as an instance ID only | +------------------------------------------+-------------------------------------------+ -For typed containers (Array and Dictionary), additional flags indicate the -container's type information: +For typed containers (Array and Dictionary), additional flags indicate the container's type information: **Array (bits 16-17):** @@ -149,7 +148,7 @@ container's type information: +=======+======================================+ | 0b00 | Untyped | +-------+--------------------------------------+ -| 0b01 | Typed with builtin type | +| 0b01 | Typed with built-in type | +-------+--------------------------------------+ | 0b10 | Typed with class name | +-------+--------------------------------------+ @@ -167,470 +166,368 @@ 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 +.. _nil-section: + +0: NIL ~~~~~~~ +null + 1: :ref:`bool` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+---------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+===========================+ -| 4 | 4 | Integer | 0 for False, 1 for True | -+----------+-------+-----------+---------------------------+ ++----------+----------+-----------+---------------------------+ +| Offset | Length | 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: +If no flags are set (flags == 0), the integer is serialized with a 32 bit integer: -+----------+-------+-----------+--------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+==========================+ -| 4 | 4 | Integer | 32-bit signed integer | -+----------+-------+-----------+--------------------------+ ++----------+----------+-----------+--------------------------+ +| Offset | Length | 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 | -+----------+-------+---------+-----------------------------------+ ++----------+----------+---------+-----------------------------------+ +| Offset | Length | 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 | -+----------+-------+---------+-----------------------------------+ +.. _string-section: 4: :ref:`String` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+==============================+ -| 4 | 4 | Integer | String length (in byte, N) | -+----------+-------+-----------+------------------------------+ -| 8 | N | Bytes | UTF-8 encoded string | -+----------+-------+-----------+------------------------------+ - -This field is padded to 4 bytes. ++----------+----------+-----------+--------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+============================================+ +| 4 | 4 | Integer | String length (in bytes, N) | ++----------+----------+-----------+--------------------------------------------+ +| 8 | N | Bytes | UTF-8 encoded string (padded to 4 bytes) | ++----------+----------+-----------+--------------------------------------------+ 5: :ref:`Vector2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 4 | Float | X coordinate | -+----------+-------+---------+----------------+ -| 8 | 4 | Float | Y coordinate | -+----------+-------+---------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 8 | Double | X coordinate | -+----------+-------+---------+----------------+ -| 12 | 8 | Double | Y coordinate | -+----------+-------+---------+----------------+ ++----------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+================+ +| 4 | 4 | Float | X coordinate | ++----------+----------+---------+----------------+ +| 8 | 4 | Float | Y coordinate | ++----------+----------+---------+----------------+ 6: :ref:`Vector2i` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+================+ -| 4 | 4 | Integer | X coordinate | -+----------+-------+-----------+----------------+ -| 8 | 4 | Integer | Y coordinate | -+----------+-------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+----------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+----------+-----------+----------------+ 7: :ref:`Rect2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 4 | Float | X position | -+----------+-------+---------+----------------+ -| 8 | 4 | Float | Y position | -+----------+-------+---------+----------------+ -| 12 | 4 | Float | X size | -+----------+-------+---------+----------------+ -| 16 | 4 | Float | Y size | -+----------+-------+---------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 8 | Double | X position | -+----------+-------+---------+----------------+ -| 12 | 8 | Double | Y position | -+----------+-------+---------+----------------+ -| 20 | 8 | Double | X size | -+----------+-------+---------+----------------+ -| 28 | 8 | Double | Y size | -+----------+-------+---------+----------------+ ++----------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+================+ +| 4 | 4 | Float | X position | ++----------+----------+---------+----------------+ +| 8 | 4 | Float | Y position | ++----------+----------+---------+----------------+ +| 12 | 4 | Float | X size | ++----------+----------+---------+----------------+ +| 16 | 4 | Float | Y size | ++----------+----------+---------+----------------+ 8: :ref:`Rect2i` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+================+ -| 4 | 4 | Integer | X position | -+----------+-------+-----------+----------------+ -| 8 | 4 | Integer | Y position | -+----------+-------+-----------+----------------+ -| 12 | 4 | Integer | X size | -+----------+-------+-----------+----------------+ -| 16 | 4 | Integer | Y size | -+----------+-------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | X position | ++----------+----------+-----------+----------------+ +| 8 | 4 | Integer | Y position | ++----------+----------+-----------+----------------+ +| 12 | 4 | Integer | X size | ++----------+----------+-----------+----------------+ +| 16 | 4 | Integer | Y size | ++----------+----------+-----------+----------------+ 9: :ref:`Vector3` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 4 | Float | X coordinate | -+----------+-------+---------+----------------+ -| 8 | 4 | Float | Y coordinate | -+----------+-------+---------+----------------+ -| 12 | 4 | Float | Z coordinate | -+----------+-------+---------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 8 | Double | X coordinate | -+----------+-------+---------+----------------+ -| 12 | 8 | Double | Y coordinate | -+----------+-------+---------+----------------+ -| 20 | 8 | Double | Z coordinate | -+----------+-------+---------+----------------+ ++----------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+================+ +| 4 | 4 | Float | X coordinate | ++----------+----------+---------+----------------+ +| 8 | 4 | Float | Y coordinate | ++----------+----------+---------+----------------+ +| 12 | 4 | Float | Z coordinate | ++----------+----------+---------+----------------+ 10: :ref:`Vector3i` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+================+ -| 4 | 4 | Integer | X coordinate | -+----------+-------+-----------+----------------+ -| 8 | 4 | Integer | Y coordinate | -+----------+-------+-----------+----------------+ -| 12 | 4 | Integer | Z coordinate | -+----------+-------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+----------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+----------+-----------+----------------+ +| 12 | 4 | Integer | Z coordinate | ++----------+----------+-----------+----------------+ 11: :ref:`Vector4` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 4 | Float | X coordinate | -+----------+-------+---------+----------------+ -| 8 | 4 | Float | Y coordinate | -+----------+-------+---------+----------------+ -| 12 | 4 | Float | Z coordinate | -+----------+-------+---------+----------------+ -| 16 | 4 | Float | W coordinate | -+----------+-------+---------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 8 | Double | X coordinate | -+----------+-------+---------+----------------+ -| 12 | 8 | Double | Y coordinate | -+----------+-------+---------+----------------+ -| 20 | 8 | Double | Z coordinate | -+----------+-------+---------+----------------+ -| 28 | 8 | Double | W coordinate | -+----------+-------+---------+----------------+ ++----------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+================+ +| 4 | 4 | Float | X coordinate | ++----------+----------+---------+----------------+ +| 8 | 4 | Float | Y coordinate | ++----------+----------+---------+----------------+ +| 12 | 4 | Float | Z coordinate | ++----------+----------+---------+----------------+ +| 16 | 4 | Float | W coordinate | ++----------+----------+---------+----------------+ 12: :ref:`Vector4i` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+================+ -| 4 | 4 | Integer | X coordinate | -+----------+-------+-----------+----------------+ -| 8 | 4 | Integer | Y coordinate | -+----------+-------+-----------+----------------+ -| 12 | 4 | Integer | Z coordinate | -+----------+-------+-----------+----------------+ -| 16 | 4 | Integer | W coordinate | -+----------+-------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | X coordinate | ++----------+----------+-----------+----------------+ +| 8 | 4 | Integer | Y coordinate | ++----------+----------+-----------+----------------+ +| 12 | 4 | Integer | Z coordinate | ++----------+----------+-----------+----------------+ +| 16 | 4 | Integer | W coordinate | ++----------+----------+-----------+----------------+ 13: :ref:`Transform2D` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+---------------------------------------------------------------+ -| 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] | -+----------+-------+---------+---------------------------------------------------------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: ++----------+----------+---------+-----------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+=========================================+ +| 4 | 4 | Float | The X component of the X Vector2 | ++----------+----------+---------+-----------------------------------------+ +| 8 | 4 | Float | The Y component of the X Vector2 | ++----------+----------+---------+-----------------------------------------+ +| 12 | 4 | Float | The X component of the Y Vector2 | ++----------+----------+---------+-----------------------------------------+ +| 16 | 4 | Float | The Y component of the Y Vector2 | ++----------+----------+---------+-----------------------------------------+ +| 20 | 4 | Float | The X component of the Origin Vector2 | ++----------+----------+---------+-----------------------------------------+ +| 24 | 4 | Float | The Y component of the Origin Vector2 | ++----------+----------+---------+-----------------------------------------+ 14: :ref:`Plane` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+---------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+===============+ -| 4 | 4 | Float | Normal X | -+----------+-------+---------+---------------+ -| 8 | 4 | Float | Normal Y | -+----------+-------+---------+---------------+ -| 12 | 4 | Float | Normal Z | -+----------+-------+---------+---------------+ -| 16 | 4 | Float | Distance D | -+----------+-------+---------+---------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision: ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | Normal X | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | Normal Y | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | Normal Z | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | Distance D | ++----------+----------+---------+---------------+ 15: :ref:`Quaternion` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+---------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+===============+ -| 4 | 4 | Float | Imaginary X | -+----------+-------+---------+---------------+ -| 8 | 4 | Float | Imaginary Y | -+----------+-------+---------+---------------+ -| 12 | 4 | Float | Imaginary Z | -+----------+-------+---------+---------------+ -| 16 | 4 | Float | Real W | -+----------+-------+---------+---------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | Imaginary X | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | Imaginary Y | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | Imaginary Z | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | Real W | ++----------+----------+---------+---------------+ 16: :ref:`AABB` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+----------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+================+ -| 4 | 4 | Float | X position | -+----------+-------+---------+----------------+ -| 8 | 4 | Float | Y position | -+----------+-------+---------+----------------+ -| 12 | 4 | Float | Z position | -+----------+-------+---------+----------------+ -| 16 | 4 | Float | X size | -+----------+-------+---------+----------------+ -| 20 | 4 | Float | Y size | -+----------+-------+---------+----------------+ -| 24 | 4 | Float | Z size | -+----------+-------+---------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. ++----------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+================+ +| 4 | 4 | Float | X position | ++----------+----------+---------+----------------+ +| 8 | 4 | Float | Y position | ++----------+----------+---------+----------------+ +| 12 | 4 | Float | Z position | ++----------+----------+---------+----------------+ +| 16 | 4 | Float | X size | ++----------+----------+---------+----------------+ +| 20 | 4 | Float | Y size | ++----------+----------+---------+----------------+ +| 24 | 4 | Float | Z size | ++----------+----------+---------+----------------+ 17: :ref:`Basis` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+---------------------------------------------------------------+ -| 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] | -+----------+-------+---------+---------------------------------------------------------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | x.x | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | x.y | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | x.z | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | y.x | ++----------+----------+---------+---------------+ +| 20 | 4 | Float | y.y | ++----------+----------+---------+---------------+ +| 24 | 4 | Float | y.z | ++----------+----------+---------+---------------+ +| 28 | 4 | Float | z.x | ++----------+----------+---------+---------------+ +| 32 | 4 | Float | z.y | ++----------+----------+---------+---------------+ +| 36 | 4 | Float | z.z | ++----------+----------+---------+---------------+ 18: :ref:`Transform3D` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+---------------------------------------------------------------+ -| 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] | -+----------+-------+---------+---------------------------------------------------------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | basis.x.x | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | basis.x.y | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | basis.x.z | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | basis.y.x | ++----------+----------+---------+---------------+ +| 20 | 4 | Float | basis.y.y | ++----------+----------+---------+---------------+ +| 24 | 4 | Float | basis.y.z | ++----------+----------+---------+---------------+ +| 28 | 4 | Float | basis.z.x | ++----------+----------+---------+---------------+ +| 32 | 4 | Float | basis.z.y | ++----------+----------+---------+---------------+ +| 36 | 4 | Float | basis.z.z | ++----------+----------+---------+---------------+ +| 40 | 4 | Float | origin.x | ++----------+----------+---------+---------------+ +| 44 | 4 | Float | origin.y | ++----------+----------+---------+---------------+ +| 48 | 4 | Float | origin.z | ++----------+----------+---------+---------------+ 19: :ref:`Projection` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+----------+-------+---------+------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+=========+==============================+ -| 4 | 4 | Float | x.x (Column 0, Row 0) | -+----------+-------+---------+------------------------------+ -| 8 | 4 | Float | x.y (Column 0, Row 1) | -+----------+-------+---------+------------------------------+ -| 12 | 4 | Float | x.z (Column 0, Row 2) | -+----------+-------+---------+------------------------------+ -| 16 | 4 | Float | x.w (Column 0, Row 3) | -+----------+-------+---------+------------------------------+ -| 20 | 4 | Float | y.x (Column 1, Row 0) | -+----------+-------+---------+------------------------------+ -| 24 | 4 | Float | y.y (Column 1, Row 1) | -+----------+-------+---------+------------------------------+ -| 28 | 4 | Float | y.z (Column 1, Row 2) | -+----------+-------+---------+------------------------------+ -| 32 | 4 | Float | y.w (Column 1, Row 3) | -+----------+-------+---------+------------------------------+ -| 36 | 4 | Float | z.x (Column 2, Row 0) | -+----------+-------+---------+------------------------------+ -| 40 | 4 | Float | z.y (Column 2, Row 1) | -+----------+-------+---------+------------------------------+ -| 44 | 4 | Float | z.z (Column 2, Row 2) | -+----------+-------+---------+------------------------------+ -| 48 | 4 | Float | z.w (Column 2, Row 3) | -+----------+-------+---------+------------------------------+ -| 52 | 4 | Float | w.x (Column 3, Row 0) | -+----------+-------+---------+------------------------------+ -| 56 | 4 | Float | w.y (Column 3, Row 1) | -+----------+-------+---------+------------------------------+ -| 60 | 4 | Float | w.z (Column 3, Row 2) | -+----------+-------+---------+------------------------------+ -| 64 | 4 | Float | w.w (Column 3, Row 3) | -+----------+-------+---------+------------------------------+ - -Total of 16 floats (64 bytes for single precision, 128 bytes for double). -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. ++----------+----------+---------+------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+==============================+ +| 4 | 4 | Float | x.x (Column 0, Row 0) | ++----------+----------+---------+------------------------------+ +| 8 | 4 | Float | x.y (Column 0, Row 1) | ++----------+----------+---------+------------------------------+ +| 12 | 4 | Float | x.z (Column 0, Row 2) | ++----------+----------+---------+------------------------------+ +| 16 | 4 | Float | x.w (Column 0, Row 3) | ++----------+----------+---------+------------------------------+ +| 20 | 4 | Float | y.x (Column 1, Row 0) | ++----------+----------+---------+------------------------------+ +| 24 | 4 | Float | y.y (Column 1, Row 1) | ++----------+----------+---------+------------------------------+ +| 28 | 4 | Float | y.z (Column 1, Row 2) | ++----------+----------+---------+------------------------------+ +| 32 | 4 | Float | y.w (Column 1, Row 3) | ++----------+----------+---------+------------------------------+ +| 36 | 4 | Float | z.x (Column 2, Row 0) | ++----------+----------+---------+------------------------------+ +| 40 | 4 | Float | z.y (Column 2, Row 1) | ++----------+----------+---------+------------------------------+ +| 44 | 4 | Float | z.z (Column 2, Row 2) | ++----------+----------+---------+------------------------------+ +| 48 | 4 | Float | z.w (Column 2, Row 3) | ++----------+----------+---------+------------------------------+ +| 52 | 4 | Float | w.x (Column 3, Row 0) | ++----------+----------+---------+------------------------------+ +| 56 | 4 | Float | w.y (Column 3, Row 1) | ++----------+----------+---------+------------------------------+ +| 60 | 4 | Float | w.z (Column 3, Row 2) | ++----------+----------+---------+------------------------------+ +| 64 | 4 | Float | w.w (Column 3, Row 3) | ++----------+----------+---------+------------------------------+ 20: :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) | -+----------+-------+---------+--------------------------------------------------------------+ ++----------+----------+---------+--------------------------------------------------------------+ +| Offset | Length | 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) | ++----------+----------+---------+--------------------------------------------------------------+ 21: :ref:`StringName` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Encoded identically to String (see type 4). +Serialized identically to :ref:`String `. 22: :ref:`NodePath` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+-----------------------------------------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=========================================================================================+ -| 4 | 4 | Integer | Name count with new format flag (val & 0x80000000 != 0, NameCount = val & 0x7FFFFFFF) | -+----------+-------+-----------+-----------------------------------------------------------------------------------------+ ++----------+----------+-----------+-----------------------------------------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=========================================================================================+ +| 4 | 4 | Integer | Name count with new format flag (val & 0x80000000 != 0, NameCount = val & 0x7FFFFFFF) | ++----------+----------+-----------+-----------------------------------------------------------------------------------------+ The old format is no longer supported and will return an error. For new format: ~~~~~~~~~~~~~~~ -+----------+-------+-----------+--------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+============================================+ -| 8 | 4 | Integer | Sub-name count | -+----------+-------+-----------+--------------------------------------------+ -| 12 | 4 | Integer | Flags (bit 0: absolute, bit 1: property) | -+----------+-------+-----------+--------------------------------------------+ ++----------+----------+-----------+--------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+============================================+ +| 8 | 4 | Integer | Sub-name count | ++----------+----------+-----------+--------------------------------------------+ +| 12 | 4 | Integer | Flags (bit 0: absolute, bit 1: property) | ++----------+----------+-----------+--------------------------------------------+ .. note:: @@ -639,39 +536,36 @@ For new format: For each Name and Sub-Name (offsets are relative to the start of each string entry): -+----------+-------+-----------+-----------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=============================+ -| 0 | 4 | Integer | String length (in bytes, N) | -+----------+-------+-----------+-----------------------------+ -| 4 | N | Bytes | UTF-8 encoded string | -+----------+-------+-----------+-----------------------------+ - -Every name string is padded to 4 bytes. ++----------+----------+-----------+---------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=========================================================+ +| 0 | 4 | Integer | Name/Sub-Name (String length, in bytes, N) | ++----------+----------+-----------+---------------------------------------------------------+ +| 4 | N | Bytes | Name/Sub-Name (UTF-8 encoded string, padded to 4 bytes) | ++----------+----------+-----------+---------------------------------------------------------+ 23: :ref:`RID` ~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+-----------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+=================+ -| 4 | 8 | Integer | 64-bit RID ID | -+----------+-------+-----------+-----------------+ ++----------+----------+-----------+-----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=================+ +| 4 | 8 | Integer | 64-bit RID ID | ++----------+----------+-----------+-----------------+ 24: :ref:`Object` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An Object can be serialized in two ways, determined by the -``ENCODE_FLAG_OBJECT_AS_ID`` header flag (``flags & 1 == 1``). +An Object can be serialized in two ways, determined by the ``ENCODE_FLAG_OBJECT_AS_ID`` header flag (``flags & 1 == 1``). -With ``ENCODE_FLAG_OBJECT_AS_ID`` set (instance ID only) +With ``ENCODE_FLAG_OBJECT_AS_ID`` set (Instance ID only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -+----------+-------+------------+-----------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+============+===================================+ -| 4 | 8 | Integer | The Object instance ID (64-bit) | -+----------+-------+------------+-----------------------------------+ ++----------+----------+------------+-----------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+============+===================================+ +| 4 | 8 | Integer | The Object instance ID (64-bit) | ++----------+----------+------------+-----------------------------------+ If the instance ID is 0, it represents a null object. @@ -683,35 +577,37 @@ is returned. **Null object:** -+----------+-------+-----------+--------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+============================================+ -| 4 | 4 | Integer | 0 (empty string length, indicating null) | -+----------+-------+-----------+--------------------------------------------+ ++----------+----------+-----------+------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+==============================+ +| 4 | 4 | Integer | 0 (Representing a nullptr) | ++----------+----------+-----------+------------------------------+ **Non-null object:** -+----------+-------+----------------+--------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+================+========================================================+ -| 4 | 4 | Integer | Class name (String length, N) | -+----------+-------+----------------+--------------------------------------------------------+ -| 8 | N | Bytes | Class name (UTF-8 encoded string, padded to 4 bytes) | -+----------+-------+----------------+--------------------------------------------------------+ -| 8+N | 4 | Integer | The number of properties that are serialized | -+----------+-------+----------------+--------------------------------------------------------+ - -For each property (offsets relative to the start of each property): - -+----------+-------+----------------+-----------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+================+===========================================================+ -| 0 | 4 | Integer | Property name (String length, N) | -+----------+-------+----------------+-----------------------------------------------------------+ -| 4 | N | Bytes | Property name (UTF-8 encoded string, padded to 4 bytes) | -+----------+-------+----------------+-----------------------------------------------------------+ -| 4+N+Z | W | | Property value, using this same format | -+----------+-------+----------------+-----------------------------------------------------------+ +Header: ++----------+------------+----------------+--------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+============+================+========================================================+ +| 4 | 4 | Integer | Class name (String length, in bytes, N) | ++----------+------------+----------------+--------------------------------------------------------+ +| 8 | N | Bytes | Class name (UTF-8 encoded string, padded to 4 bytes) | ++----------+------------+----------------+--------------------------------------------------------+ +| 8+N | 4 | Integer | The number of properties that are serialized (P) | ++----------+------------+----------------+--------------------------------------------------------+ + +Following this header is a contiguous block of key-value property entries, defined below, +where the offset is relative to the start of each property entry: + ++----------+------------+----------------+-----------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+============+================+===========================================================+ +| 0 | 4 | Integer | Property name (String length, in bytes, N) | ++----------+------------+----------------+-----------------------------------------------------------+ +| 4 | N | Bytes | Property name (UTF-8 encoded string, padded to 4 bytes) | ++----------+------------+----------------+-----------------------------------------------------------+ +| 4+N | | | Property value, using this same format | ++----------+------------+----------------+-----------------------------------------------------------+ .. note:: @@ -739,20 +635,20 @@ and decoding produces an empty Callable. 26: :ref:`Signal` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+-------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+===============================+ -| 4 | 4 | Integer | Signal name string length (N) | -+----------+-------+-----------+-------------------------------+ -| 8 | N | Bytes | Signal name (UTF-8, padded) | -+----------+-------+-----------+-------------------------------+ -| 8+N | 8 | Integer | Object instance ID (64-bit) | -+----------+-------+-----------+-------------------------------+ ++----------+----------+-----------+---------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=========================================================+ +| 4 | 4 | Integer | Signal name (String length, in bytes, N) | ++----------+----------+-----------+---------------------------------------------------------+ +| 8 | N | Bytes | Signal name (UTF-8 encoded string, padded to 4 bytes) | ++----------+----------+-----------+---------------------------------------------------------+ +| 8+N | 8 | Integer | Object instance ID (64-bit) | ++----------+----------+-----------+---------------------------------------------------------+ 27: :ref:`Dictionary` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For typed dictionaries, the header flags indicate the type kind for both keys +For typed dictionaries, the header flags indicate the variant type for both keys and values (see Header Flags section). Depending on these flags, type information is encoded before the element count. @@ -760,34 +656,34 @@ information is encoded before the element count. If type kind is ``BUILTIN`` (0b01): -+----------+-------+-----------+----------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+============================+ -| 4 | 4 | Integer | Variant type ID | -+----------+-------+-----------+----------------------------+ ++----------+----------+-----------+----------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+============================+ +| 4 | 4 | Integer | Variant type ID | ++----------+----------+-----------+----------------------------+ If type kind is ``CLASS_NAME`` (0b10) or ``SCRIPT`` (0b11): -+----------+-------+-----------+-----------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+===============================================+ -| 4 | 4 | Integer | Class name or script path string length (N) | -+----------+-------+-----------+-----------------------------------------------+ -| 8 | N | Bytes | Class name or script path (UTF-8, padded) | -+----------+-------+-----------+-----------------------------------------------+ ++----------+----------+-----------+--------------------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+====================================================================+ +| 4 | 4 | Integer | Class name/Script path (String length, in bytes, N) | ++----------+----------+-----------+--------------------------------------------------------------------+ +| 8 | N | Bytes | Class name/Script path (UTF-8 encoded string, padded to 4 bytes) | ++----------+----------+-----------+--------------------------------------------------------------------+ Value type encoding, if applicable, immediately follows key type encoding. **Element count (immediately following all type information):** -+----------+-------+-----------+----------------------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+======================================================================+ -| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | -+----------+-------+-----------+----------------------------------------------------------------------+ ++----------+----------+-----------+----------------------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+======================================================================+ +| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | ++----------+----------+-----------+----------------------------------------------------------------------+ -Then what follows is, for each element, a key-value pair encoded one after -the other using this same format. +Following this header is a contiguous block of key-value pairs, +encoded using the same serialization format defined in this document. 28: :ref:`Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -797,89 +693,96 @@ Flags section). The container type is encoded the same way as Dictionary. **Element count (immediately following type information, if any):** -+----------+-------+-----------+----------------------------------------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+======================================================================+ -| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | -+----------+-------+-----------+----------------------------------------------------------------------+ ++----------+----------+-----------+----------------------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+======================================================================+ +| 0 | 4 | Integer | val & 0x7FFFFFFF = element count, val & 0x80000000 = shared (bool) | ++----------+----------+-----------+----------------------------------------------------------------------+ -Then what follows is, for each element, a value encoded using this same format. +Following the element count is a contiguous block of values, +encoded using the same serialization format defined in this document. 29: :ref:`PackedByteArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+---------------+-------+-----------+------------------------+ -| Offset | Len | Type | Description | -+===============+=======+===========+========================+ -| 4 | 4 | Integer | Array length (Bytes) | -+---------------+-------+-----------+------------------------+ -| 8..8+length | 1 | Byte | Byte (0..255) | -+---------------+-------+-----------+------------------------+ ++---------------+----------+-----------+-------------------------------+ +| Offset | Length | Type | Description | ++===============+==========+===========+===============================+ +| 4 | 4 | Integer | Array length (L) | ++---------------+----------+-----------+-------------------------------+ +| 8 + i | 1 | Byte | Array element #i (0 <= i < L) | ++---------------+----------+-----------+-------------------------------+ The array data is padded to 4 bytes. 30: :ref:`PackedInt32Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+-------+-----------+---------------------------+ -| Offset | Len | Type | Description | -+==================+=======+===========+===========================+ -| 4 | 4 | Integer | Array length (Integers) | -+------------------+-------+-----------+---------------------------+ -| 8..8+length\*4 | 4 | Integer | 32-bit signed integer | -+------------------+-------+-----------+---------------------------+ ++------------------+----------+-----------+-------------------------------+ +| Offset | Length | Type | Description | ++==================+==========+===========+===============================+ +| 4 | 4 | Integer | Array length (L) | ++------------------+----------+-----------+-------------------------------+ +| 8 + i \* 4 | 4 | Integer | Array element #i (0 <= i < L) | ++------------------+----------+-----------+-------------------------------+ 31: :ref:`PackedInt64Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+-------+-----------+---------------------------+ -| Offset | Len | Type | Description | -+==================+=======+===========+===========================+ -| 4 | 4 | Integer | Array length (Integers) | -+------------------+-------+-----------+---------------------------+ -| 8..8+length\*8 | 8 | Integer | 64-bit signed integer | -+------------------+-------+-----------+---------------------------+ ++------------------+----------+-----------+-------------------------------+ +| Offset | Length | Type | Description | ++==================+==========+===========+===============================+ +| 4 | 4 | Integer | Array length (L) | ++------------------+----------+-----------+-------------------------------+ +| 8 + i \* 8 | 8 | Integer | Array element #i (0 <= i < L) | ++------------------+----------+-----------+-------------------------------+ 32: :ref:`PackedFloat32Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+-------+-----------+-----------------------------------+ -| Offset | Len | Type | Description | -+==================+=======+===========+===================================+ -| 4 | 4 | Integer | Array length (Floats) | -+------------------+-------+-----------+-----------------------------------+ -| 8..8+length\*4 | 4 | Float | IEEE 754 single-precision float | -+------------------+-------+-----------+-----------------------------------+ ++------------------+----------+-----------+-----------------------------------+ +| Offset | Length | Type | Description | ++==================+==========+===========+===================================+ +| 4 | 4 | Integer | Array length (L) | ++------------------+----------+-----------+-----------------------------------+ +| 8 + i \* 4 | 4 | Float | Array element #i (0 <= i < L) | ++------------------+----------+-----------+-----------------------------------+ 33: :ref:`PackedFloat64Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+-------+-----------+-----------------------------------+ -| Offset | Len | Type | Description | -+==================+=======+===========+===================================+ -| 4 | 4 | Integer | Array length (Floats) | -+------------------+-------+-----------+-----------------------------------+ -| 8..8+length\*8 | 8 | Float | IEEE 754 double-precision float | -+------------------+-------+-----------+-----------------------------------+ ++------------------+----------+-----------+-----------------------------------+ +| Offset | Length | Type | Description | ++==================+==========+===========+===================================+ +| 4 | 4 | Integer | Array length (L) | ++------------------+----------+-----------+-----------------------------------+ +| 8 + i \* 8 | 8 | Float | Array element #i (0 <= i < L) | ++------------------+----------+-----------+-----------------------------------+ 34: :ref:`PackedStringArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+-------+-----------+--------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+==========================+ -| 4 | 4 | Integer | Array length (Strings) | -+----------+-------+-----------+--------------------------+ ++----------+----------+-----------+--------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+==========================+ +| 4 | 4 | Integer | Array length (Strings) | ++----------+----------+-----------+--------------------------+ -For each String (offsets relative to start of each string entry): +Following the array length is a contiguous block of strings. -+----------+-------+-----------+----------------------------------------+ -| Offset | Len | Type | Description | -+==========+=======+===========+========================================+ -| 0 | 4 | Integer | String length (N, including null term) | -+----------+-------+-----------+----------------------------------------+ -| 4 | N | Bytes | UTF-8 encoded string with null | -+----------+-------+-----------+----------------------------------------+ +For each string entry (0 <= i < length): + +.. note:: + + Offsets below are relative to the start of each string entry. + ++----------+----------+-----------+----------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+========================================+ +| 0 | 4 | Integer | String length (N, including null term) | ++----------+----------+-----------+----------------------------------------+ +| 4 | N | Bytes | UTF-8 encoded string with null | ++----------+----------+-----------+----------------------------------------+ Every string is padded to 4 bytes. @@ -891,77 +794,69 @@ Every string is padded to 4 bytes. 35: :ref:`PackedVector2Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+-------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+===================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+-------------------+-------+-----------+----------------+ -| 8+i\*8 | 4 | Float | X coordinate | -+-------------------+-------+-----------+----------------+ -| 12+i\*8 | 4 | Float | Y coordinate | -+-------------------+-------+-----------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. - -+-------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+===================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+-------------------+-------+-----------+----------------+ -| 8+i\*16 | 8 | Double | X coordinate | -+-------------------+-------+-----------+----------------+ -| 16+i\*16 | 8 | Double | Y coordinate | -+-------------------+-------+-----------+----------------+ ++-------------------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++===================+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++-------------------+----------+-----------+----------------+ + +Following the array length is a contiguous block of Vector2's. + +For each Vector2 entry (0 <= i < length): + ++-------------------+----------+-----------+----------------+ +| 8 + i \* 8 | 4 | Float | X coordinate | ++-------------------+----------+-----------+----------------+ +| 12 + i \* 8 | 4 | Float | Y coordinate | ++-------------------+----------+-----------+----------------+ 36: :ref:`PackedVector3Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+--------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+====================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+-------+-----------+----------------+ -| 8+i\*12 | 4 | Float | X coordinate | -+--------------------+-------+-----------+----------------+ -| 12+i\*12 | 4 | Float | Y coordinate | -+--------------------+-------+-----------+----------------+ -| 16+i\*12 | 4 | Float | Z coordinate | -+--------------------+-------+-----------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. - -+--------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+====================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+-------+-----------+----------------+ -| 8+i\*24 | 8 | Double | X coordinate | -+--------------------+-------+-----------+----------------+ -| 16+i\*24 | 8 | Double | Y coordinate | -+--------------------+-------+-----------+----------------+ -| 24+i\*24 | 8 | Double | Z coordinate | -+--------------------+-------+-----------+----------------+ ++--------------------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++--------------------+----------+-----------+----------------+ + +Following the array length is a contiguous block of Vector3's. + +For each Vector3 entry (0 <= i < length): + ++--------------------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+================+ +| 8 + i \* 12 | 4 | Float | X coordinate | ++--------------------+----------+-----------+----------------+ +| 12 + i \* 12 | 4 | Float | Y coordinate | ++--------------------+----------+-----------+----------------+ +| 16 + i \* 12 | 4 | Float | Z coordinate | ++--------------------+----------+-----------+----------------+ 37: :ref:`PackedColorArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+--------------------+-------+-----------+--------------------------------------------------------------+ -| Offset | Len | Type | Description | -+====================+=======+===========+==============================================================+ -| 4 | 4 | Integer | Array length | -+--------------------+-------+-----------+--------------------------------------------------------------+ -| 8+i\*16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | -+--------------------+-------+-----------+--------------------------------------------------------------+ -| 12+i\*16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | -+--------------------+-------+-----------+--------------------------------------------------------------+ -| 16+i\*16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | -+--------------------+-------+-----------+--------------------------------------------------------------+ -| 20+i\*16 | 4 | Float | Alpha (0..1) | -+--------------------+-------+-----------+--------------------------------------------------------------+ ++--------------------+----------+-----------+--------------------------------------------------------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+==============================================================+ +| 4 | 4 | Integer | Array length | ++--------------------+----------+-----------+--------------------------------------------------------------+ + +Following the array length is a contiguous block of Colors. + +For each Color entry (0 <= i < length): + ++--------------------+----------+-----------+--------------------------------------------------------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+==============================================================+ +| 8 + i \* 16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | ++--------------------+----------+-----------+--------------------------------------------------------------+ +| 12 + i \* 16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | ++--------------------+----------+-----------+--------------------------------------------------------------+ +| 16 + i \* 16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | ++--------------------+----------+-----------+--------------------------------------------------------------+ +| 20 + i \* 16 | 4 | Float | Alpha (0..1) | ++--------------------+----------+-----------+--------------------------------------------------------------+ .. note:: @@ -970,34 +865,24 @@ If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bi 38: :ref:`PackedVector4Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the floats are sent as 32 bit single precision: - -+--------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+====================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+-------+-----------+----------------+ -| 8+i\*16 | 4 | Float | X coordinate | -+--------------------+-------+-----------+----------------+ -| 12+i\*16 | 4 | Float | Y coordinate | -+--------------------+-------+-----------+----------------+ -| 16+i\*16 | 4 | Float | Z coordinate | -+--------------------+-------+-----------+----------------+ -| 20+i\*16 | 4 | Float | W coordinate | -+--------------------+-------+-----------+----------------+ - -If flag ``ENCODE_FLAG_64`` is set (flags & 1 == 1), the floats are sent as 64 bit double precision. - -+--------------------+-------+-----------+----------------+ -| Offset | Len | Type | Description | -+====================+=======+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+-------+-----------+----------------+ -| 8+i\*32 | 8 | Double | X coordinate | -+--------------------+-------+-----------+----------------+ -| 16+i\*32 | 8 | Double | Y coordinate | -+--------------------+-------+-----------+----------------+ -| 24+i\*32 | 8 | Double | Z coordinate | -+--------------------+-------+-----------+----------------+ -| 32+i\*32 | 8 | Double | W coordinate | -+--------------------+-------+-----------+----------------+ ++--------------------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++--------------------+----------+-----------+----------------+ + +Following the array length is a contiguous block of Vector4's. + +For each Vector4 entry (0 <= i < length): + ++--------------------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++====================+==========+===========+================+ +| 8 + i \* 16 | 4 | Float | X coordinate | ++--------------------+----------+-----------+----------------+ +| 12 + i \* 16 | 4 | Float | Y coordinate | ++--------------------+----------+-----------+----------------+ +| 16 + i \* 16 | 4 | Float | Z coordinate | ++--------------------+----------+-----------+----------------+ +| 20 + i \* 16 | 4 | Float | W coordinate | ++--------------------+----------+-----------+----------------+ From d5f370027634c118ef6c7394fa17b79dbcf13043 Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Mon, 8 Dec 2025 16:02:19 -0500 Subject: [PATCH 4/6] Standardize all tables to 3 spaces padding per column --- tutorials/io/binary_serialization_api.rst | 646 +++++++++++----------- 1 file changed, 324 insertions(+), 322 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 1f1e0faf0db..c8659a7fc82 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -42,118 +42,118 @@ The header is structured as follows: type = header & 0xFF; flags = header >> 16; -+-----------+--------------------------+ -| Valu | Type Description | -+===========+==========================+ -| 0 (0x00) | null | -+-----------+--------------------------+ -| 1 (0x01) | bool | -+-----------+--------------------------+ -| 2 (0x02) | int | -+-----------+--------------------------+ -| 3 (0x03) | float | -+-----------+--------------------------+ -| 4 (0x04) | String | -+-----------+--------------------------+ -| 5 (0x05) | Vector2 | -+-----------+--------------------------+ -| 6 (0x06) | Vector2i | -+-----------+--------------------------+ -| 7 (0x07) | Rect2 | -+-----------+--------------------------+ -| 8 (0x08) | Rect2i | -+-----------+--------------------------+ -| 9 (0x09) | Vector3 | -+-----------+--------------------------+ -| 10 (0x0A) | Vector3i | -+-----------+--------------------------+ -| 11 (0x0B) | Vector4 | -+-----------+--------------------------+ -| 12 (0x0C) | Vector4i | -+-----------+--------------------------+ -| 13 (0x0D) | Transform2D | -+-----------+--------------------------+ -| 14 (0x0E) | Plane | -+-----------+--------------------------+ -| 15 (0x0F) | Quaternion | -+-----------+--------------------------+ -| 16 (0x10) | AABB | -+-----------+--------------------------+ -| 17 (0x11) | Basis | -+-----------+--------------------------+ -| 18 (0x12) | Transform3D | -+-----------+--------------------------+ -| 19 (0x13) | Projection | -+-----------+--------------------------+ -| 20 (0x14) | Color | -+-----------+--------------------------+ -| 21 (0x15) | StringName | -+-----------+--------------------------+ -| 22 (0x16) | NodePath | -+-----------+--------------------------+ -| 23 (0x17) | RID | -+-----------+--------------------------+ -| 24 (0x18) | Object | -+-----------+--------------------------+ -| 25 (0x19) | Callable | -+-----------+--------------------------+ -| 26 (0x1A) | Signal | -+-----------+--------------------------+ -| 27 (0x1B) | Dictionary | -+-----------+--------------------------+ -| 28 (0x1C) | Array | -+-----------+--------------------------+ -| 29 (0x1D) | PackedByteArray | -+-----------+--------------------------+ -| 30 (0x1E) | PackedInt32Array | -+-----------+--------------------------+ -| 31 (0x1F) | PackedInt64Array | -+-----------+--------------------------+ -| 32 (0x20) | PackedFloat32Array | -+-----------+--------------------------+ -| 33 (0x21) | PackedFloat64Array | -+-----------+--------------------------+ -| 34 (0x22) | PackedStringArray | -+-----------+--------------------------+ -| 35 (0x23) | PackedVector2Array | -+-----------+--------------------------+ -| 36 (0x24) | PackedVector3Array | -+-----------+--------------------------+ -| 37 (0x25) | PackedColorArray | -+-----------+--------------------------+ -| 38 (0x26) | PackedVector4Array | -+-----------+--------------------------+ ++-------------+----------------------+ +| Value | Type Description | ++=============+======================+ +| 0 (0x00) | null | ++-------------+----------------------+ +| 1 (0x01) | bool | ++-------------+----------------------+ +| 2 (0x02) | int | ++-------------+----------------------+ +| 3 (0x03) | float | ++-------------+----------------------+ +| 4 (0x04) | String | ++-------------+----------------------+ +| 5 (0x05) | Vector2 | ++-------------+----------------------+ +| 6 (0x06) | Vector2i | ++-------------+----------------------+ +| 7 (0x07) | Rect2 | ++-------------+----------------------+ +| 8 (0x08) | Rect2i | ++-------------+----------------------+ +| 9 (0x09) | Vector3 | ++-------------+----------------------+ +| 10 (0x0A) | Vector3i | ++-------------+----------------------+ +| 11 (0x0B) | Vector4 | ++-------------+----------------------+ +| 12 (0x0C) | Vector4i | ++-------------+----------------------+ +| 13 (0x0D) | Transform2D | ++-------------+----------------------+ +| 14 (0x0E) | Plane | ++-------------+----------------------+ +| 15 (0x0F) | Quaternion | ++-------------+----------------------+ +| 16 (0x10) | AABB | ++-------------+----------------------+ +| 17 (0x11) | Basis | ++-------------+----------------------+ +| 18 (0x12) | Transform3D | ++-------------+----------------------+ +| 19 (0x13) | Projection | ++-------------+----------------------+ +| 20 (0x14) | Color | ++-------------+----------------------+ +| 21 (0x15) | StringName | ++-------------+----------------------+ +| 22 (0x16) | NodePath | ++-------------+----------------------+ +| 23 (0x17) | RID | ++-------------+----------------------+ +| 24 (0x18) | Object | ++-------------+----------------------+ +| 25 (0x19) | Callable | ++-------------+----------------------+ +| 26 (0x1A) | Signal | ++-------------+----------------------+ +| 27 (0x1B) | Dictionary | ++-------------+----------------------+ +| 28 (0x1C) | Array | ++-------------+----------------------+ +| 29 (0x1D) | PackedByteArray | ++-------------+----------------------+ +| 30 (0x1E) | PackedInt32Array | ++-------------+----------------------+ +| 31 (0x1F) | PackedInt64Array | ++-------------+----------------------+ +| 32 (0x20) | PackedFloat32Array | ++-------------+----------------------+ +| 33 (0x21) | PackedFloat64Array | ++-------------+----------------------+ +| 34 (0x22) | PackedStringArray | ++-------------+----------------------+ +| 35 (0x23) | PackedVector2Array | ++-------------+----------------------+ +| 36 (0x24) | PackedVector3Array | ++-------------+----------------------+ +| 37 (0x25) | PackedColorArray | ++-------------+----------------------+ +| 38 (0x26) | PackedVector4Array | ++-------------+----------------------+ Header Flags ~~~~~~~~~~~~ The header's upper 16 bits contain type-specific flags: -+------------------------------------------+-------------------------------------------+ -| Flag | Description | -+==========================================+===========================================+ -| ``ENCODE_FLAG_64 = (1 << 16)`` | Used for int, float, and math types to | -| | indicate 64-bit (long/double) precision | -+------------------------------------------+-------------------------------------------+ -| ``ENCODE_FLAG_OBJECT_AS_ID = (1 << 16)`` | Used for Object to indicate serialization | -| | as an instance ID only | -+------------------------------------------+-------------------------------------------+ ++--------------------------------------------+---------------------------------------------+ +| Flag | Description | ++============================================+=============================================+ +| ``ENCODE_FLAG_64 = (1 << 16)`` | Used for int, float, and math types to | +| | indicate 64-bit (long/double) precision | ++--------------------------------------------+---------------------------------------------+ +| ``ENCODE_FLAG_OBJECT_AS_ID = (1 << 16)`` | Used for Object to indicate serialization | +| | as an instance ID only | ++--------------------------------------------+---------------------------------------------+ For typed containers (Array and Dictionary), additional flags indicate the container's type information: **Array (bits 16-17):** -+-------+--------------------------------------+ -| Value | Meaning | -+=======+======================================+ -| 0b00 | Untyped | -+-------+--------------------------------------+ -| 0b01 | Typed with built-in type | -+-------+--------------------------------------+ -| 0b10 | Typed with class name | -+-------+--------------------------------------+ -| 0b11 | Typed with script path | -+-------+--------------------------------------+ ++--------+----------------------------+ +| Value | Meaning | ++========+============================+ +| 0b00 | Untyped | ++--------+----------------------------+ +| 0b01 | Typed with built-in type | ++--------+----------------------------+ +| 0b10 | Typed with class name | ++--------+----------------------------+ +| 0b11 | Typed with script path | ++--------+----------------------------+ **Dictionary key type (bits 16-17) and value type (bits 18-19):** @@ -187,11 +187,11 @@ null If no flags are set (flags == 0), the integer is serialized with a 32 bit integer: -+----------+----------+-----------+--------------------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+==========================+ -| 4 | 4 | Integer | 32-bit signed integer | -+----------+----------+-----------+--------------------------+ ++----------+----------+-----------+-------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=========================+ +| 4 | 4 | Integer | 32-bit signed integer | ++----------+----------+-----------+-------------------------+ 3: :ref:`float` @@ -241,32 +241,32 @@ If no flags are set (flags == 0), the integer is serialized with a 32 bit intege 7: :ref:`Rect2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+----------+---------+----------------+ -| Offset | Length | Type | Description | -+==========+==========+=========+================+ -| 4 | 4 | Float | X position | -+----------+----------+---------+----------------+ -| 8 | 4 | Float | Y position | -+----------+----------+---------+----------------+ -| 12 | 4 | Float | X size | -+----------+----------+---------+----------------+ -| 16 | 4 | Float | Y size | -+----------+----------+---------+----------------+ ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | X position | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | Y position | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | X size | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | Y size | ++----------+----------+---------+---------------+ 8: :ref:`Rect2i` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+================+ -| 4 | 4 | Integer | X position | -+----------+----------+-----------+----------------+ -| 8 | 4 | Integer | Y position | -+----------+----------+-----------+----------------+ -| 12 | 4 | Integer | X size | -+----------+----------+-----------+----------------+ -| 16 | 4 | Integer | Y size | -+----------+----------+-----------+----------------+ ++----------+----------+-----------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+===============+ +| 4 | 4 | Integer | X position | ++----------+----------+-----------+---------------+ +| 8 | 4 | Integer | Y position | ++----------+----------+-----------+---------------+ +| 12 | 4 | Integer | X size | ++----------+----------+-----------+---------------+ +| 16 | 4 | Integer | Y size | ++----------+----------+-----------+---------------+ 9: :ref:`Vector3` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -376,21 +376,21 @@ If no flags are set (flags == 0), the integer is serialized with a 32 bit intege 16: :ref:`AABB` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+----------+---------+----------------+ -| Offset | Length | Type | Description | -+==========+==========+=========+================+ -| 4 | 4 | Float | X position | -+----------+----------+---------+----------------+ -| 8 | 4 | Float | Y position | -+----------+----------+---------+----------------+ -| 12 | 4 | Float | Z position | -+----------+----------+---------+----------------+ -| 16 | 4 | Float | X size | -+----------+----------+---------+----------------+ -| 20 | 4 | Float | Y size | -+----------+----------+---------+----------------+ -| 24 | 4 | Float | Z size | -+----------+----------+---------+----------------+ ++----------+----------+---------+---------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+===============+ +| 4 | 4 | Float | X position | ++----------+----------+---------+---------------+ +| 8 | 4 | Float | Y position | ++----------+----------+---------+---------------+ +| 12 | 4 | Float | Z position | ++----------+----------+---------+---------------+ +| 16 | 4 | Float | X size | ++----------+----------+---------+---------------+ +| 20 | 4 | Float | Y size | ++----------+----------+---------+---------------+ +| 24 | 4 | Float | Z size | ++----------+----------+---------+---------------+ 17: :ref:`Basis` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -451,56 +451,56 @@ If no flags are set (flags == 0), the integer is serialized with a 32 bit intege 19: :ref:`Projection` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+----------+---------+------------------------------+ -| Offset | Length | Type | Description | -+==========+==========+=========+==============================+ -| 4 | 4 | Float | x.x (Column 0, Row 0) | -+----------+----------+---------+------------------------------+ -| 8 | 4 | Float | x.y (Column 0, Row 1) | -+----------+----------+---------+------------------------------+ -| 12 | 4 | Float | x.z (Column 0, Row 2) | -+----------+----------+---------+------------------------------+ -| 16 | 4 | Float | x.w (Column 0, Row 3) | -+----------+----------+---------+------------------------------+ -| 20 | 4 | Float | y.x (Column 1, Row 0) | -+----------+----------+---------+------------------------------+ -| 24 | 4 | Float | y.y (Column 1, Row 1) | -+----------+----------+---------+------------------------------+ -| 28 | 4 | Float | y.z (Column 1, Row 2) | -+----------+----------+---------+------------------------------+ -| 32 | 4 | Float | y.w (Column 1, Row 3) | -+----------+----------+---------+------------------------------+ -| 36 | 4 | Float | z.x (Column 2, Row 0) | -+----------+----------+---------+------------------------------+ -| 40 | 4 | Float | z.y (Column 2, Row 1) | -+----------+----------+---------+------------------------------+ -| 44 | 4 | Float | z.z (Column 2, Row 2) | -+----------+----------+---------+------------------------------+ -| 48 | 4 | Float | z.w (Column 2, Row 3) | -+----------+----------+---------+------------------------------+ -| 52 | 4 | Float | w.x (Column 3, Row 0) | -+----------+----------+---------+------------------------------+ -| 56 | 4 | Float | w.y (Column 3, Row 1) | -+----------+----------+---------+------------------------------+ -| 60 | 4 | Float | w.z (Column 3, Row 2) | -+----------+----------+---------+------------------------------+ -| 64 | 4 | Float | w.w (Column 3, Row 3) | -+----------+----------+---------+------------------------------+ ++----------+----------+---------+-------------------------+ +| Offset | Length | Type | Description | ++==========+==========+=========+=========================+ +| 4 | 4 | Float | x.x (Column 0, Row 0) | ++----------+----------+---------+-------------------------+ +| 8 | 4 | Float | x.y (Column 0, Row 1) | ++----------+----------+---------+-------------------------+ +| 12 | 4 | Float | x.z (Column 0, Row 2) | ++----------+----------+---------+-------------------------+ +| 16 | 4 | Float | x.w (Column 0, Row 3) | ++----------+----------+---------+-------------------------+ +| 20 | 4 | Float | y.x (Column 1, Row 0) | ++----------+----------+---------+-------------------------+ +| 24 | 4 | Float | y.y (Column 1, Row 1) | ++----------+----------+---------+-------------------------+ +| 28 | 4 | Float | y.z (Column 1, Row 2) | ++----------+----------+---------+-------------------------+ +| 32 | 4 | Float | y.w (Column 1, Row 3) | ++----------+----------+---------+-------------------------+ +| 36 | 4 | Float | z.x (Column 2, Row 0) | ++----------+----------+---------+-------------------------+ +| 40 | 4 | Float | z.y (Column 2, Row 1) | ++----------+----------+---------+-------------------------+ +| 44 | 4 | Float | z.z (Column 2, Row 2) | ++----------+----------+---------+-------------------------+ +| 48 | 4 | Float | z.w (Column 2, Row 3) | ++----------+----------+---------+-------------------------+ +| 52 | 4 | Float | w.x (Column 3, Row 0) | ++----------+----------+---------+-------------------------+ +| 56 | 4 | Float | w.y (Column 3, Row 1) | ++----------+----------+---------+-------------------------+ +| 60 | 4 | Float | w.z (Column 3, Row 2) | ++----------+----------+---------+-------------------------+ +| 64 | 4 | Float | w.w (Column 3, Row 3) | ++----------+----------+---------+-------------------------+ 20: :ref:`Color` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+----------+----------+---------+--------------------------------------------------------------+ -| Offset | Length | 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) | -+----------+----------+---------+--------------------------------------------------------------+ ++----------+----------+---------+----------------------------------------------------------------+ +| Offset | Length | 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) | ++----------+----------+---------+----------------------------------------------------------------+ 21: :ref:`StringName` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -536,13 +536,13 @@ For new format: For each Name and Sub-Name (offsets are relative to the start of each string entry): -+----------+----------+-----------+---------------------------------------------------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+=========================================================+ -| 0 | 4 | Integer | Name/Sub-Name (String length, in bytes, N) | -+----------+----------+-----------+---------------------------------------------------------+ -| 4 | N | Bytes | Name/Sub-Name (UTF-8 encoded string, padded to 4 bytes) | -+----------+----------+-----------+---------------------------------------------------------+ ++----------+----------+-----------+-----------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+===========================================================+ +| 0 | 4 | Integer | Name/Sub-Name (String length, in bytes, N) | ++----------+----------+-----------+-----------------------------------------------------------+ +| 4 | N | Bytes | Name/Sub-Name (UTF-8 encoded string, padded to 4 bytes) | ++----------+----------+-----------+-----------------------------------------------------------+ 23: :ref:`RID` ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -561,11 +561,11 @@ An Object can be serialized in two ways, determined by the ``ENCODE_FLAG_OBJECT_ With ``ENCODE_FLAG_OBJECT_AS_ID`` set (Instance ID only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -+----------+----------+------------+-----------------------------------+ -| Offset | Length | Type | Description | -+==========+==========+============+===================================+ -| 4 | 8 | Integer | The Object instance ID (64-bit) | -+----------+----------+------------+-----------------------------------+ ++----------+----------+-----------+-----------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+===================================+ +| 4 | 8 | Integer | The Object instance ID (64-bit) | ++----------+----------+-----------+-----------------------------------+ If the instance ID is 0, it represents a null object. @@ -586,28 +586,28 @@ is returned. **Non-null object:** Header: -+----------+------------+----------------+--------------------------------------------------------+ -| Offset | Length | Type | Description | -+==========+============+================+========================================================+ -| 4 | 4 | Integer | Class name (String length, in bytes, N) | -+----------+------------+----------------+--------------------------------------------------------+ -| 8 | N | Bytes | Class name (UTF-8 encoded string, padded to 4 bytes) | -+----------+------------+----------------+--------------------------------------------------------+ -| 8+N | 4 | Integer | The number of properties that are serialized (P) | -+----------+------------+----------------+--------------------------------------------------------+ ++----------+----------+-----------+--------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+========================================================+ +| 4 | 4 | Integer | Class name (String length, in bytes, N) | ++----------+----------+-----------+--------------------------------------------------------+ +| 8 | N | Bytes | Class name (UTF-8 encoded string, padded to 4 bytes) | ++----------+----------+-----------+--------------------------------------------------------+ +| 8+N | 4 | Integer | The number of properties that are serialized (P) | ++----------+----------+-----------+--------------------------------------------------------+ Following this header is a contiguous block of key-value property entries, defined below, where the offset is relative to the start of each property entry: -+----------+------------+----------------+-----------------------------------------------------------+ -| Offset | Length | Type | Description | -+==========+============+================+===========================================================+ -| 0 | 4 | Integer | Property name (String length, in bytes, N) | -+----------+------------+----------------+-----------------------------------------------------------+ -| 4 | N | Bytes | Property name (UTF-8 encoded string, padded to 4 bytes) | -+----------+------------+----------------+-----------------------------------------------------------+ -| 4+N | | | Property value, using this same format | -+----------+------------+----------------+-----------------------------------------------------------+ ++----------+--------------+--------------+-----------------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==============+==============+===========================================================+ +| 0 | 4 | Integer | Property name (String length, in bytes, N) | ++----------+--------------+--------------+-----------------------------------------------------------+ +| 4 | N | Bytes | Property name (UTF-8 encoded string, padded to 4 bytes) | ++----------+--------------+--------------+-----------------------------------------------------------+ +| 4+N | | | Property value, using this same format | ++----------+--------------+--------------+-----------------------------------------------------------+ .. note:: @@ -656,11 +656,11 @@ information is encoded before the element count. If type kind is ``BUILTIN`` (0b01): -+----------+----------+-----------+----------------------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+============================+ -| 4 | 4 | Integer | Variant type ID | -+----------+----------+-----------+----------------------------+ ++----------+----------+-----------+-------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+===================+ +| 4 | 4 | Integer | Variant type ID | ++----------+----------+-----------+-------------------+ If type kind is ``CLASS_NAME`` (0b10) or ``SCRIPT`` (0b11): @@ -705,59 +705,59 @@ encoded using the same serialization format defined in this document. 29: :ref:`PackedByteArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+---------------+----------+-----------+-------------------------------+ -| Offset | Length | Type | Description | -+===============+==========+===========+===============================+ -| 4 | 4 | Integer | Array length (L) | -+---------------+----------+-----------+-------------------------------+ -| 8 + i | 1 | Byte | Array element #i (0 <= i < L) | -+---------------+----------+-----------+-------------------------------+ ++----------+----------+-----------+---------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+=================================+ +| 4 | 4 | Integer | Array length (L) | ++----------+----------+-----------+---------------------------------+ +| 8 + i | 1 | Byte | Array element #i (0 <= i < L) | ++----------+----------+-----------+---------------------------------+ The array data is padded to 4 bytes. 30: :ref:`PackedInt32Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+----------+-----------+-------------------------------+ -| Offset | Length | Type | Description | -+==================+==========+===========+===============================+ -| 4 | 4 | Integer | Array length (L) | -+------------------+----------+-----------+-------------------------------+ -| 8 + i \* 4 | 4 | Integer | Array element #i (0 <= i < L) | -+------------------+----------+-----------+-------------------------------+ ++--------------+----------+-----------+---------------------------------+ +| Offset | Length | Type | Description | ++==============+==========+===========+=================================+ +| 4 | 4 | Integer | Array length (L) | ++--------------+----------+-----------+---------------------------------+ +| 8 + i \* 4 | 4 | Integer | Array element #i (0 <= i < L) | ++--------------+----------+-----------+---------------------------------+ 31: :ref:`PackedInt64Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+----------+-----------+-------------------------------+ -| Offset | Length | Type | Description | -+==================+==========+===========+===============================+ -| 4 | 4 | Integer | Array length (L) | -+------------------+----------+-----------+-------------------------------+ -| 8 + i \* 8 | 8 | Integer | Array element #i (0 <= i < L) | -+------------------+----------+-----------+-------------------------------+ ++--------------+----------+-----------+---------------------------------+ +| Offset | Length | Type | Description | ++==============+==========+===========+=================================+ +| 4 | 4 | Integer | Array length (L) | ++--------------+----------+-----------+---------------------------------+ +| 8 + i \* 8 | 8 | Integer | Array element #i (0 <= i < L) | ++--------------+----------+-----------+---------------------------------+ 32: :ref:`PackedFloat32Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+----------+-----------+-----------------------------------+ -| Offset | Length | Type | Description | -+==================+==========+===========+===================================+ -| 4 | 4 | Integer | Array length (L) | -+------------------+----------+-----------+-----------------------------------+ -| 8 + i \* 4 | 4 | Float | Array element #i (0 <= i < L) | -+------------------+----------+-----------+-----------------------------------+ ++--------------+----------+-----------+---------------------------------+ +| Offset | Length | Type | Description | ++==============+==========+===========+=================================+ +| 4 | 4 | Integer | Array length (L) | ++--------------+----------+-----------+---------------------------------+ +| 8 + i \* 4 | 4 | Float | Array element #i (0 <= i < L) | ++--------------+----------+-----------+---------------------------------+ 33: :ref:`PackedFloat64Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------+----------+-----------+-----------------------------------+ -| Offset | Length | Type | Description | -+==================+==========+===========+===================================+ -| 4 | 4 | Integer | Array length (L) | -+------------------+----------+-----------+-----------------------------------+ -| 8 + i \* 8 | 8 | Float | Array element #i (0 <= i < L) | -+------------------+----------+-----------+-----------------------------------+ ++--------------+----------+-----------+---------------------------------+ +| Offset | Length | Type | Description | ++==============+==========+===========+=================================+ +| 4 | 4 | Integer | Array length (L) | ++--------------+----------+-----------+---------------------------------+ +| 8 + i \* 8 | 8 | Float | Array element #i (0 <= i < L) | ++--------------+----------+-----------+---------------------------------+ 34: :ref:`PackedStringArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -776,13 +776,13 @@ For each string entry (0 <= i < length): Offsets below are relative to the start of each string entry. -+----------+----------+-----------+----------------------------------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+========================================+ -| 0 | 4 | Integer | String length (N, including null term) | -+----------+----------+-----------+----------------------------------------+ -| 4 | N | Bytes | UTF-8 encoded string with null | -+----------+----------+-----------+----------------------------------------+ ++----------+----------+-----------+------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+==========================================+ +| 0 | 4 | Integer | String length (N, including null term) | ++----------+----------+-----------+------------------------------------------+ +| 4 | N | Bytes | UTF-8 encoded string with null | ++----------+----------+-----------+------------------------------------------+ Every string is padded to 4 bytes. @@ -794,69 +794,71 @@ Every string is padded to 4 bytes. 35: :ref:`PackedVector2Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+-------------------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+===================+==========+===========+================+ -| 4 | 4 | Integer | Array length | -+-------------------+----------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++----------+----------+-----------+----------------+ Following the array length is a contiguous block of Vector2's. For each Vector2 entry (0 <= i < length): -+-------------------+----------+-----------+----------------+ -| 8 + i \* 8 | 4 | Float | X coordinate | -+-------------------+----------+-----------+----------------+ -| 12 + i \* 8 | 4 | Float | Y coordinate | -+-------------------+----------+-----------+----------------+ ++---------------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++===============+==========+=========+================+ +| 8 + i \* 8 | 4 | Float | X coordinate | ++---------------+----------+---------+----------------+ +| 12 + i \* 8 | 4 | Float | Y coordinate | ++---------------+----------+---------+----------------+ 36: :ref:`PackedVector3Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+--------------------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+----------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++----------+----------+-----------+----------------+ Following the array length is a contiguous block of Vector3's. For each Vector3 entry (0 <= i < length): -+--------------------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+================+ -| 8 + i \* 12 | 4 | Float | X coordinate | -+--------------------+----------+-----------+----------------+ -| 12 + i \* 12 | 4 | Float | Y coordinate | -+--------------------+----------+-----------+----------------+ -| 16 + i \* 12 | 4 | Float | Z coordinate | -+--------------------+----------+-----------+----------------+ ++----------------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++================+==========+=========+================+ +| 8 + i \* 12 | 4 | Float | X coordinate | ++----------------+----------+---------+----------------+ +| 12 + i \* 12 | 4 | Float | Y coordinate | ++----------------+----------+---------+----------------+ +| 16 + i \* 12 | 4 | Float | Z coordinate | ++----------------+----------+---------+----------------+ 37: :ref:`PackedColorArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+--------------------+----------+-----------+--------------------------------------------------------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+==============================================================+ -| 4 | 4 | Integer | Array length | -+--------------------+----------+-----------+--------------------------------------------------------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++----------+----------+-----------+----------------+ Following the array length is a contiguous block of Colors. For each Color entry (0 <= i < length): -+--------------------+----------+-----------+--------------------------------------------------------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+==============================================================+ -| 8 + i \* 16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | -+--------------------+----------+-----------+--------------------------------------------------------------+ -| 12 + i \* 16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | -+--------------------+----------+-----------+--------------------------------------------------------------+ -| 16 + i \* 16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | -+--------------------+----------+-----------+--------------------------------------------------------------+ -| 20 + i \* 16 | 4 | Float | Alpha (0..1) | -+--------------------+----------+-----------+--------------------------------------------------------------+ ++----------------+----------+---------+----------------------------------------------------------------+ +| Offset | Length | Type | Description | ++================+==========+=========+================================================================+ +| 8 + i \* 16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) | ++----------------+----------+---------+----------------------------------------------------------------+ +| 12 + i \* 16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) | ++----------------+----------+---------+----------------------------------------------------------------+ +| 16 + i \* 16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) | ++----------------+----------+---------+----------------------------------------------------------------+ +| 20 + i \* 16 | 4 | Float | Alpha (0..1) | ++----------------+----------+---------+----------------------------------------------------------------+ .. note:: @@ -865,24 +867,24 @@ For each Color entry (0 <= i < length): 38: :ref:`PackedVector4Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+--------------------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+================+ -| 4 | 4 | Integer | Array length | -+--------------------+----------+-----------+----------------+ ++----------+----------+-----------+----------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+================+ +| 4 | 4 | Integer | Array length | ++----------+----------+-----------+----------------+ Following the array length is a contiguous block of Vector4's. For each Vector4 entry (0 <= i < length): -+--------------------+----------+-----------+----------------+ -| Offset | Length | Type | Description | -+====================+==========+===========+================+ -| 8 + i \* 16 | 4 | Float | X coordinate | -+--------------------+----------+-----------+----------------+ -| 12 + i \* 16 | 4 | Float | Y coordinate | -+--------------------+----------+-----------+----------------+ -| 16 + i \* 16 | 4 | Float | Z coordinate | -+--------------------+----------+-----------+----------------+ -| 20 + i \* 16 | 4 | Float | W coordinate | -+--------------------+----------+-----------+----------------+ ++----------------+----------+---------+----------------+ +| Offset | Length | Type | Description | ++================+==========+=========+================+ +| 8 + i \* 16 | 4 | Float | X coordinate | ++----------------+----------+---------+----------------+ +| 12 + i \* 16 | 4 | Float | Y coordinate | ++----------------+----------+---------+----------------+ +| 16 + i \* 16 | 4 | Float | Z coordinate | ++----------------+----------+---------+----------------+ +| 20 + i \* 16 | 4 | Float | W coordinate | ++----------------+----------+---------+----------------+ From ecfee4db23fae320cab339a0b0b7ec812247b937 Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Mon, 8 Dec 2025 16:06:50 -0500 Subject: [PATCH 5/6] notes --- tutorials/io/binary_serialization_api.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index c8659a7fc82..57228ab4d2c 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -139,6 +139,11 @@ The header's upper 16 bits contain type-specific flags: | | as an instance ID only | +--------------------------------------------+---------------------------------------------+ +.. note:: + + For integers and floats used in any of these data types, if the ENCODE_FLAG_64 flag is set + then the value is serialized as a 64-bit integer or double-precision float respectively. + For typed containers (Array and Dictionary), additional flags indicate the container's type information: **Array (bits 16-17):** @@ -185,8 +190,6 @@ null 2: :ref:`int` ~~~~~~~~~~~~~~~~~~~~~~~~ -If no flags are set (flags == 0), the integer is serialized with a 32 bit integer: - +----------+----------+-----------+-------------------------+ | Offset | Length | Type | Description | +==========+==========+===========+=========================+ From a415c871d15cb35129837036e2ca9a6cfdba10c8 Mon Sep 17 00:00:00 2001 From: KryziK <82416255+KryziK@users.noreply.github.com> Date: Mon, 8 Dec 2025 16:08:46 -0500 Subject: [PATCH 6/6] null term update --- tutorials/io/binary_serialization_api.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 57228ab4d2c..4f19edd2113 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -779,14 +779,13 @@ For each string entry (0 <= i < length): Offsets below are relative to the start of each string entry. -+----------+----------+-----------+------------------------------------------+ -| Offset | Length | Type | Description | -+==========+==========+===========+==========================================+ -| 0 | 4 | Integer | String length (N, including null term) | -+----------+----------+-----------+------------------------------------------+ -| 4 | N | Bytes | UTF-8 encoded string with null | -+----------+----------+-----------+------------------------------------------+ - ++----------+----------+-----------+----------------------------------------------------+ +| Offset | Length | Type | Description | ++==========+==========+===========+====================================================+ +| 0 | 4 | Integer | String length (N, including the null terminator) | ++----------+----------+-----------+----------------------------------------------------+ +| 4 | N | Bytes | UTF-8 encoded string with a null terminator | ++----------+----------+-----------+----------------------------------------------------+ Every string is padded to 4 bytes. .. note::