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)