This page is marked as outdated and may not reflect current Redot behavior.
Binary serialization API
Introduction
Redot 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
class FileAccess as well as the packet APIs for class 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;
Type
Value
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 Redot is compiled with single-precision floats,
which is the default. If Redot 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.
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
<variable>
Property value, using this same format
NOTE
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.