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

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

Si aucun drapeau n'est défini (flags == 0), le nombre entier est envoyé comme un nombre entier de 32 bits :

Offset

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 :

Offset

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 :

Offset

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 :

Offset

Len

Type

Description

4

8

Float

IEEE 754 double-precision 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)