Work in progress
The content of this page was not yet updated for Godot
4.2
and may be outdated. If you know how to improve this page or you can confirm
that it's up to date, feel free to open a pull request.
Binary serialization API¶
Introduzione¶
Godot has a serialization API based on Variant. It's used for
converting data types to an array of bytes efficiently. This API is exposed
via the global bytes_to_var()
and var_to_bytes() functions,
but it is also used in the get_var
and store_var
methods of
FileAccess as well as the packet APIs for PacketPeer.
This format is not used for binary scenes and resources.
Full Objects vs Object instance IDs¶
If a variable is serialized with full_objects = true
, then any Objects
contained in the variable will be serialized and included in the result. This
is recursive.
If full_objects = false
, then only the instance IDs will be serialized for
any Objects contained in the variable.
Packet specification¶
The packet is designed to be always padded to 4 bytes. All values are little-endian-encoded. All packets have a 4-byte header representing an integer, specifying the type of data.
The lowest value two bytes are used to determine the type, while the highest value two bytes contain flags:
base_type = val & 0xFFFF;
flags = val >> 16;
Tipo |
Valore |
---|---|
0 |
null |
1 |
bool |
2 |
integer |
3 |
float |
4 |
string |
5 |
vector2 |
6 |
rect2 |
7 |
vector3 |
8 |
transform2d |
9 |
plane |
10 |
quaternion |
11 |
aabb |
12 |
basis |
13 |
transform3d |
14 |
color |
15 |
node path |
16 |
rid |
17 |
object |
18 |
dictionary |
19 |
array |
20 |
raw array |
21 |
int32 array |
22 |
int64 array |
23 |
float32 array |
24 |
float64 array |
25 |
string array |
26 |
vector2 array |
27 |
vector3 array |
28 |
color array |
29 |
max |
Following this is the actual packet contents, which varies for each type of
packet. Note that this assumes Godot is compiled with single-precision floats,
which is the default. If Godot was compiled with double-precision floats, the
length of "Float" fields within data structures should be 8, and the offset
should be (offset - 4) * 2 + 4
. The "float" type itself always uses double
precision.
0: null¶
1: bool¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
0 per False, 1 per True |
2: int¶
If no flags are set (flags == 0), the integer is sent as a 32 bit integer:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
32-bit signed integer |
If flag ENCODE_FLAG_64
is set (flags & 1 == 1
), the integer is sent as
a 64-bit integer:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
8 |
Numero intero |
64-bit signed integer |
3: float¶
If no flags are set (flags == 0), the float is sent as a 32 bit single precision:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
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:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
8 |
Float |
IEEE 754 double-precision float |
4: String¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
String length (in bytes) |
8 |
X |
Bytes |
UTF-8 encoded string |
This field is padded to 4 bytes.
5: Vector2¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
6: Rect2¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
12 |
4 |
Float |
X size |
16 |
4 |
Float |
Y size |
7: Vector3¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
12 |
4 |
Float |
Z coordinate |
8: Transform2D¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
The X component of the X column vector, accessed via [0][0] |
8 |
4 |
Float |
The Y component of the X column vector, accessed via [0][1] |
12 |
4 |
Float |
The X component of the Y column vector, accessed via [1][0] |
16 |
4 |
Float |
The Y component of the Y column vector, accessed via [1][1] |
20 |
4 |
Float |
The X component of the origin vector, accessed via [2][0] |
24 |
4 |
Float |
The Y component of the origin vector, accessed via [2][1] |
9: Plane¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
Normal X |
8 |
4 |
Float |
Normal Y |
12 |
4 |
Float |
Normal Z |
16 |
4 |
Float |
Distance |
10: Quaternion¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
Imaginary X |
8 |
4 |
Float |
Imaginary Y |
12 |
4 |
Float |
Imaginary Z |
16 |
4 |
Float |
Real W |
11: AABB¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
12 |
4 |
Float |
Z coordinate |
16 |
4 |
Float |
X size |
20 |
4 |
Float |
Y size |
24 |
4 |
Float |
Z size |
12: Basis¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
The X component of the X column vector, accessed via [0][0] |
8 |
4 |
Float |
The Y component of the X column vector, accessed via [0][1] |
12 |
4 |
Float |
The Z component of the X column vector, accessed via [0][2] |
16 |
4 |
Float |
The X component of the Y column vector, accessed via [1][0] |
20 |
4 |
Float |
The Y component of the Y column vector, accessed via [1][1] |
24 |
4 |
Float |
The Z component of the Y column vector, accessed via [1][2] |
28 |
4 |
Float |
The X component of the Z column vector, accessed via [2][0] |
32 |
4 |
Float |
The Y component of the Z column vector, accessed via [2][1] |
36 |
4 |
Float |
The Z component of the Z column vector, accessed via [2][2] |
13: Transform3D¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
The X component of the X column vector, accessed via [0][0] |
8 |
4 |
Float |
The Y component of the X column vector, accessed via [0][1] |
12 |
4 |
Float |
The Z component of the X column vector, accessed via [0][2] |
16 |
4 |
Float |
The X component of the Y column vector, accessed via [1][0] |
20 |
4 |
Float |
The Y component of the Y column vector, accessed via [1][1] |
24 |
4 |
Float |
The Z component of the Y column vector, accessed via [1][2] |
28 |
4 |
Float |
The X component of the Z column vector, accessed via [2][0] |
32 |
4 |
Float |
The Y component of the Z column vector, accessed via [2][1] |
36 |
4 |
Float |
The Z component of the Z column vector, accessed via [2][2] |
40 |
4 |
Float |
The X component of the origin vector, accessed via [3][0] |
44 |
4 |
Float |
The Y component of the origin vector, accessed via [3][1] |
48 |
4 |
Float |
The Z component of the origin vector, accessed via [3][2] |
14: Color¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Float |
Red (typically 0..1, can be above 1 for overbright colors) |
8 |
4 |
Float |
Green (typically 0..1, can be above 1 for overbright colors) |
12 |
4 |
Float |
Blue (typically 0..1, can be above 1 for overbright colors) |
16 |
4 |
Float |
Alpha (0..1) |
15: NodePath¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
For old format:¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
8 |
X |
Bytes |
UTF-8 encoded string |
Padded to 4 bytes.
For new format:¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Sub-name count |
8 |
4 |
Numero intero |
Flags (absolute: val&1 != 0 ) |
For each Name and Sub-Name
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
X+0 |
4 |
Numero intero |
String length |
X+4 |
X |
Bytes |
UTF-8 encoded string |
Every name string is padded to 4 bytes.
16: RID (non supportato)¶
17: 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¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Zero (32-bit signed integer) |
full_objects
disabled¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
8 |
Numero intero |
The Object instance ID (64-bit signed integer) |
full_objects
enabled¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Class name (String length) |
8 |
X |
Bytes |
Class name (UTF-8 encoded string) |
X+8 |
4 |
Numero intero |
The number of properties that are serialized |
For each property:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
Y |
4 |
Numero intero |
Property name (String length) |
Y+4 |
Z |
Bytes |
Property name (UTF-8 encoded string) |
Y+4+Z |
W |
<variable> |
Property value, using this same format |
Nota
Not all properties are included. Only properties that are configured with the
PROPERTY_USAGE_STORAGE
flag set will be serialized. You can add a new usage flag to a property by overriding the
_get_property_list
method in your class. You can also check how property usage is configured by
calling Object._get_property_list
See
PropertyUsageFlags for the
possible usage flags.
18: Dictionary¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Then what follows is, for amount of "elements", pairs of key and value, one after the other, using this same format.
19: Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Then what follows is, for amount of "elements", values one after the other, using this same format.
20: PackedByteArray¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length (Bytes) |
8..8+length |
1 |
Byte |
Byte (0..255) |
The array data is padded to 4 bytes.
21: PackedInt32Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length (Integers) |
8..8+length*4 |
4 |
Numero intero |
32-bit signed integer |
22: PackedInt64Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
8 |
Numero intero |
Array length (Integers) |
8..8+length*8 |
8 |
Numero intero |
64-bit signed integer |
23: PackedFloat32Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length (Floats) |
8..8+length*4 |
4 |
Numero intero |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length (Floats) |
8..8+length*8 |
8 |
Numero intero |
64-bit IEEE 754 double-precision float |
25: PackedStringArray¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length (Strings) |
For each String:
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
X+0 |
4 |
Numero intero |
String length |
X+4 |
X |
Bytes |
UTF-8 encoded string |
Every string is padded to 4 bytes.
26: PackedVector2Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length |
8..8+length*8 |
4 |
Float |
X coordinate |
8..12+length*8 |
4 |
Float |
Y coordinate |
27: PackedVector3Array¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length |
8..8+length*12 |
4 |
Float |
X coordinate |
8..12+length*12 |
4 |
Float |
Y coordinate |
8..16+length*12 |
4 |
Float |
Z coordinate |
28: PackedColorArray¶
Scostamento |
Len |
Tipo |
Descrizione |
---|---|---|---|
4 |
4 |
Numero intero |
Array length |
8..8+length*16 |
4 |
Float |
Red (typically 0..1, can be above 1 for overbright colors) |
8..12+length*16 |
4 |
Float |
Green (typically 0..1, can be above 1 for overbright colors) |
8..16+length*16 |
4 |
Float |
Blue (typically 0..1, can be above 1 for overbright colors) |
8..20+length*16 |
4 |
Float |
Alpha (0..1) |