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 :

Type Valeur
0 null
1 bool
2 Entier
3 float
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 dictionary
19 array
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

Offset Len Type Description
4 4 Nombre entier 0 pour False, 1 pour True

2 : int

Offset Len Type Description
4 8 Nombre entier Entier signé 64 bits

3 : float

Offset Len Type Description
4 4 Float IEE 754 32-Bits Float

4 : String

Offset 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

Offset Len Type Description
4 4 Float Coordonnée X
8 4 Float Coordonnée Y

6 : Rect2

Offset 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

Offset Len Type Description
4 4 Float Coordonnée X
8 4 Float Coordonnée Y
12 4 Float Coordonnée Z

8 : Transform2D

Offset 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

Offset Len Type Description
4 4 Float Normale X
8 4 Float Normale Y
12 4 Float Normale Z
16 4 Float Distance

10 : Quat

Offset 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

Offset 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

Offset 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

Offset 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

Offset 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

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

Offset Len Type Description
8 X Octets Chaîne de caractère codée en UTF-8

Rembourré(padded) à 4 octets.

Pour le nouveau format :

Offset 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

Offset 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

Offset 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

Offset 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

Offset 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

Offset Len Type Description
4 4 Nombre entier Longueur d'Array (entiers)
8..8+length*4 4 Nombre entier Entier 32 bits signé

22 : PoolRealArray

Offset 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

Offset Len Type Description
4 4 Nombre entier Longueur d'Array (Chaîne de caractère)

Pour chaque chaîne de caractère :

Offset 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

Offset 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

Offset 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

Offset 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)