Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Binary serialization API
Úvod
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;
Typ |
Hodnota |
---|---|
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 |
barva |
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
0 for False, 1 for True |
2: int
If no flags are set (flags == 0), the integer is sent as a 32 bit integer:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
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 |
Typ |
Popis |
---|---|---|---|
4 |
8 |
Číslo |
64-bit signed integer |
3: :ref:'float<class_float>'
If no flags are set (flags == 0), the float is sent as a 32 bit single precision:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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 |
Typ |
Popis |
---|---|---|---|
4 |
8 |
Float |
IEEE 754 double-precision float |
4: String
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
String length (in bytes) |
8 |
X |
Bytes |
UTF-8 encoded string |
This field is padded to 4 bytes.
5: Vector2
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
6: Rect2
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
12 |
4 |
Float |
X size |
16 |
4 |
Float |
Y size |
7: Vector3
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Float |
X coordinate |
8 |
4 |
Float |
Y coordinate |
12 |
4 |
Float |
Z coordinate |
8: Transform2D
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Float |
Normal X |
8 |
4 |
Float |
Normal Y |
12 |
4 |
Float |
Normal Z |
16 |
4 |
Float |
Distance |
10: Quaternion
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Float |
Imaginary X |
8 |
4 |
Float |
Imaginary Y |
12 |
4 |
Float |
Imaginary Z |
16 |
4 |
Float |
Real W |
11: AABB
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
For old format:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
8 |
X |
Bytes |
UTF-8 encoded string |
Padded to 4 bytes.
For new format:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Sub-name count |
8 |
4 |
Číslo |
Flags (absolute: val&1 != 0 ) |
For each Name and Sub-Name
Offset |
Len |
Typ |
Popis |
---|---|---|---|
X+0 |
4 |
Číslo |
Délka řetězce |
X+4 |
X |
Bytes |
UTF-8 encoded string |
Every name string is padded to 4 bytes.
16: RID (unsupported)
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Zero (32-bit signed integer) |
full_objects
disabled
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
8 |
Číslo |
The Object instance ID (64-bit signed integer) |
full_objects
enabled
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Class name (String length) |
8 |
X |
Bytes |
Class name (UTF-8 encoded string) |
X+8 |
4 |
Číslo |
Počet vlastností které jsou serializovány |
For each property:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
Y |
4 |
Číslo |
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 |
Poznámka
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Array length (Bytes) |
8..8+length |
1 |
Byt |
Byte (0..255) |
The array data is padded to 4 bytes.
21: PackedInt32Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Array length (Integers) |
8..8+length*4 |
4 |
Číslo |
32-bit signed integer |
22: PackedInt64Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
8 |
Číslo |
Array length (Integers) |
8..8+length*8 |
8 |
Číslo |
64-bit signed integer |
23: PackedFloat32Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Array length (Floats) |
8..8+length*4 |
4 |
Číslo |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Array length (Floats) |
8..8+length*8 |
8 |
Číslo |
64-bit IEEE 754 double-precision float |
25: PackedStringArray
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Array length (Strings) |
For each String:
Offset |
Len |
Typ |
Popis |
---|---|---|---|
X+0 |
4 |
Číslo |
Délka řetězce |
X+4 |
X |
Bytes |
UTF-8 encoded string |
Every string is padded to 4 bytes.
26: PackedVector2Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Délka pole |
8..8+length*8 |
4 |
Float |
X coordinate |
8..12+length*8 |
4 |
Float |
Y coordinate |
27: PackedVector3Array
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Délka pole |
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
Offset |
Len |
Typ |
Popis |
---|---|---|---|
4 |
4 |
Číslo |
Délka pole |
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) |