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.
API de sérialisation binaire¶
Introduction¶
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.
Spécification des paquets¶
Le paquet est conçu pour être toujours rembourré(padded) à 4 octets. Toutes les valeurs sont encodées en little endian(little-endian-encoded). Tous les paquets ont un en-tête de 4 octets représentant un entier, spécifiant le type de données.
Les deux octets de valeur la plus faible servent à déterminer le type, tandis que les deux octets de valeur la plus élevée contiennent des drapeaux :
base_type = val & 0xFFFF;
flags = val >> 16;
Type |
Valeur |
---|---|
0 |
null |
1 |
bool |
2 |
Entier |
3 |
flottant |
4 |
chaîne |
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 |
dictionnaire |
19 |
tableau |
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 |
Suit le contenu réel du paquet, qui varie pour chaque type de paquet. Notez que cela suppose que Godot est compilé avec des flottant à précision unique(single-precision floats), ce qui est le cas par défaut. Si Godot est compilé avec des flottants à précision double(double-precision floats), la longueur des champs "Float" dans les structures de données devrait être de 8, et le décalage devrait être (offset - 4) * 2 + 4
. Le type "float" lui-même utilise toujours la double précision.
0 : null¶
1 : bool¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
0 pour False, 1 pour True |
2 : int¶
Si aucun drapeau n'est défini (flags == 0), le nombre entier est envoyé comme un nombre entier de 32 bits :
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Entier 32 bits signé |
Si le drapeau ENCODE_FLAG_64
est activé (flags & 1 == 1
), le nombre entier est envoyé sous forme de nombre entier 64 bits :
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
8 |
Nombre entier |
Entier signé 64 bits |
3 : float¶
Si aucun drapeau n'est défini (flags == 0), le flottant est envoyé en tant que précision simple de 32 bits :
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
IEEE 754 single-precision float |
Si le drapeau ENCODE_FLAG_64
est défini (flags & 1 == 1
), le flottant est envoyé sous la forme d'un nombre double précision de 64 bits :
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
8 |
Float |
IEEE 754 double-precision float |
4 : String¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur de chaîne de caractère (en octets) |
8 |
X |
Octets |
Chaîne de caractère codée en UTF-8 |
Ce champ est rembourré(padded) à 4 octets.
5 : Vector2¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Coordonnée X |
8 |
4 |
Float |
Coordonnée Y |
6 : Rect2¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Coordonnée X |
8 |
4 |
Float |
Coordonnée Y |
12 |
4 |
Float |
Taille X |
16 |
4 |
Float |
Taille Y |
7 : Vector3¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Coordonnée X |
8 |
4 |
Float |
Coordonnée Y |
12 |
4 |
Float |
Coordonnée Z |
8 : Transform2D¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
La composante X du vecteur de la colonne X, accessible via [0][0] |
8 |
4 |
Float |
La composante Y du vecteur de la colonne X, accessible via [0][1] |
12 |
4 |
Float |
La composante X du vecteur de la colonne Y, accessible via [1][0] |
16 |
4 |
Float |
La composante Y du vecteur de la colonne Y, accessible via [1][1] |
20 |
4 |
Float |
La composante X du vecteur origine, accessible via [2][0] |
24 |
4 |
Float |
La composante Y du vecteur origine, accessible via [2][1] |
9 : Plane¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Normale X |
8 |
4 |
Float |
Normale Y |
12 |
4 |
Float |
Normale Z |
16 |
4 |
Float |
Distance |
10: Quaternion¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
X imaginaire |
8 |
4 |
Float |
Imaginaire Y |
12 |
4 |
Float |
Z imaginaire |
16 |
4 |
Float |
Réel W |
11 : AABB¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Coordonnée X |
8 |
4 |
Float |
Coordonnée Y |
12 |
4 |
Float |
Coordonnée Z |
16 |
4 |
Float |
Taille X |
20 |
4 |
Float |
Taille Y |
24 |
4 |
Float |
Taille Z |
12 : Basis¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
La composante X du vecteur de la colonne X, accessible via [0][0] |
8 |
4 |
Float |
La composante Y du vecteur de la colonne X, accessible via [0][1] |
12 |
4 |
Float |
La composante Z du vecteur de la colonne X, accessible via [0][2] |
16 |
4 |
Float |
La composante X du vecteur de la colonne Y, accessible via [1][0] |
20 |
4 |
Float |
La composante Y du vecteur de la colonne Y, accessible via [1][1] |
24 |
4 |
Float |
La composante Z du vecteur de la colonne Y, accessible via [1][2] |
28 |
4 |
Float |
La composante X du vecteur de la colonne Z, accessible via [2][0] |
32 |
4 |
Float |
La composante Y du vecteur de la colonne Z, accessible via [2][1] |
36 |
4 |
Float |
La composante Z du vecteur de la colonne Z, accessible via [2][2] |
13: Transform3D¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
La composante X du vecteur de la colonne X, accessible via [0][0] |
8 |
4 |
Float |
La composante Y du vecteur de la colonne X, accessible via [0][1] |
12 |
4 |
Float |
La composante Z du vecteur de la colonne X, accessible via [0][2] |
16 |
4 |
Float |
La composante X du vecteur de la colonne Y, accessible via [1][0] |
20 |
4 |
Float |
La composante Y du vecteur de la colonne Y, accessible via [1][1] |
24 |
4 |
Float |
La composante Z du vecteur de la colonne Y, accessible via [1][2] |
28 |
4 |
Float |
La composante X du vecteur de la colonne Z, accessible via [2][0] |
32 |
4 |
Float |
La composante Y du vecteur de la colonne Z, accessible via [2][1] |
36 |
4 |
Float |
La composante Z du vecteur de la colonne Z, accessible via [2][2] |
40 |
4 |
Float |
La composante X du vecteur origine, accessible via [3][0] |
44 |
4 |
Float |
La composante Y du vecteur origine, accessible via [3][1] |
48 |
4 |
Float |
La composante Z du vecteur origine, accessible via [3][2] |
14 : Color¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Float |
Rouge (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
8 |
4 |
Float |
Vert (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
12 |
4 |
Float |
Bleu (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
16 |
4 |
Float |
Alpha (0..1) |
15 : NodePath¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur de chaîne de caractère, ou nouveau format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
Pour l'ancien format :¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
8 |
X |
Octets |
Chaîne de caractère codée en UTF-8 |
Rembourré(padded) à 4 octets.
Pour le nouveau format :¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Nombre de sous-noms |
8 |
4 |
Nombre entier |
Flags (absolute: val&1 != 0 ) |
Pour chaque nom et sous-nom
Décalage |
Len |
Type |
Description |
---|---|---|---|
X+0 |
4 |
Nombre entier |
Longueur de chaîne de caractère |
X+4 |
X |
Octets |
Chaîne de caractère codée en UTF-8 |
Chaque chaîne de caractère de nom est rembourrée(padded) à 4 octets.
16 : RID (non pris en charge)¶
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¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Zero (32-bit signed integer) |
full_objects
disabled¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
8 |
Nombre entier |
The Object instance ID (64-bit signed integer) |
full_objects
enabled¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Class name (String length) |
8 |
X |
Octets |
Class name (UTF-8 encoded string) |
X+8 |
4 |
Nombre entier |
The number of properties that are serialized |
For each property:
Décalage |
Len |
Type |
Description |
---|---|---|---|
Y |
4 |
Nombre entier |
Property name (String length) |
Y+4 |
Z |
Octets |
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.
18 : Dictionary¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Ensuite, ce qui suit est, pour la quantité d'"éléments", des paires de clés et de valeurs, l'une après l'autre, en utilisant ce même format.
19 : Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Ensuite, ce qui suit est, pour la quantité d'"éléments", des valeurs l'une après l'autre, en utilisant ce même format.
20: PackedByteArray¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array (octets) |
8..8+length |
1 |
Octet |
Octet (0..255) |
Les données de l'array sont rembourrées(padded) à 4 octets.
21: PackedInt32Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array (entiers) |
8..8+length*4 |
4 |
Nombre entier |
Entier 32 bits signé |
22: PackedInt64Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
8 |
Nombre entier |
Longueur d'Array (entiers) |
8..8+length*8 |
8 |
Nombre entier |
Entier signé 64 bits |
23: PackedFloat32Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array (Flottants) |
8..8+length*4 |
4 |
Nombre entier |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array (Flottants) |
8..8+length*8 |
8 |
Nombre entier |
64-bit IEEE 754 double-precision float |
25: PackedStringArray¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array (Chaîne de caractère) |
Pour chaque chaîne de caractère :
Décalage |
Len |
Type |
Description |
---|---|---|---|
X+0 |
4 |
Nombre entier |
Longueur de chaîne de caractère |
X+4 |
X |
Octets |
Chaîne de caractère codée en UTF-8 |
Chaque chaîne de caractère est rembourrée(padded) à 4 octets.
26: PackedVector2Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array |
8..8+length*8 |
4 |
Float |
Coordonnée X |
8..12+length*8 |
4 |
Float |
Coordonnée Y |
27: PackedVector3Array¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array |
8..8+length*12 |
4 |
Float |
Coordonnée X |
8..12+length*12 |
4 |
Float |
Coordonnée Y |
8..16+length*12 |
4 |
Float |
Coordonnée Z |
28: PackedColorArray¶
Décalage |
Len |
Type |
Description |
---|---|---|---|
4 |
4 |
Nombre entier |
Longueur d'Array |
8..8+length*16 |
4 |
Float |
Rouge (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
8..12+length*16 |
4 |
Float |
Vert (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
8..16+length*16 |
4 |
Float |
Bleu (généralement 0..1, peut être supérieur à 1 pour les couleurs très vives (overbright)) |
8..20+length*16 |
4 |
Float |
Alpha (0..1) |