API de sérialisation binaire

Introduction

Godot a une API de sérialisation simple basée sur Variant. Elle est utilisée pour convertir efficacement les types de données en un tableau d'octets. Cette API est utilisée dans les fonctions get_var et store_var de File ainsi que les API de paquets pour PacketPeer. Ce format n'est pas utilisé pour les scènes et les ressources binaires.

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	quat
11	aabb
12	basis
13	transform
14	color
15	node path
16	rid
17	object
18	dictionnaire
19	tableau
20	raw array
21	int array
22	real array
23	string array
24	vector2 array
25	vector3 array
26	color array
27	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 : Quat

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 : Transform

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 (non pris en charge)

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 : PoolByteArray

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 : PoolIntArray

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 : PoolRealArray

Décalage	Len	Type	Description
4	4	Nombre entier	Longueur d'Array (Flottants)
8..8+length*4	4	Nombre entier	32 Bits IEEE 754 Float

23 : PoolStringArray

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.

24 : PoolVector2Array

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

25 : PoolVector3Array

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

26 : PoolColorArray

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)