API de sérialisation binaire

Introduction

Godot has a simple serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is used in the functions get_var and store_var of File as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

Spécification des paquets

The packet is designed to be always padded to 4 bytes. All values are little-endian-encoded. All packets have a 4-byte header representing an integer, specifying the type of data:

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

Following this is the actual packet contents, which varies for each type of packet. Note that this assumes Godot is compiled with single-precision floats, which is the default. If Godot was compiled with double-precision floats, the length of "Float" fields within data structures should be 8, and the offset should be (offset - 4) * 2 + 4. The "float" type itself always uses double precision.

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 64-bit signed integer

3 : float

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

4 : String

Offset Len Type Description
4 4 Nombre entier String length (in bytes)
8 X Octets UTF-8 encoded string

Ce champ est rembourré(padded) à 4 octets.

5 : Vector2

Offset Len Type Description
4 4 Float X coordinate
8 4 Float Y coordinate

6 : Rect2

Offset Len Type Description
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float X size
16 4 Float Y size

7 : Vector3

Offset Len Type Description
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float Z coordinate

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 X coordinate
8 4 Float Y coordinate
12 4 Float Z coordinate
16 4 Float X size
20 4 Float Y size
24 4 Float Z size

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 Red (typically 0..1, can be above 1 for overbright colors)
8 4 Float Green (typically 0..1, can be above 1 for overbright colors)
12 4 Float Blue (typically 0..1, can be above 1 for overbright colors)
16 4 Float Alpha (0..1)

15 : NodePath

Offset Len Type Description
4 4 Nombre entier String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

Pour l'ancien format :

Offset Len Type Description
8 X Octets UTF-8 encoded string

Rembourré(padded) à 4 octets.

Pour le nouveau format :

Offset Len Type Description
4 4 Nombre entier Sub-name count
8 4 Nombre entier Flags (absolute: val&1 != 0 )

Pour chaque nom et sous-nom

Offset Len Type Description
X+0 4 Nombre entier String length
X+4 X Octets UTF-8 encoded string

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 Array length (Bytes)
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 Array length (Integers)
8..8+length*4 4 Nombre entier 32-bit signed integer

22 : PoolRealArray

Offset Len Type Description
4 4 Nombre entier Array length (Floats)
8..8+length*4 4 Nombre entier 32-bits IEEE 754 float

23 : PoolStringArray

Offset Len Type Description
4 4 Nombre entier Array length (Strings)

Pour chaque chaîne de caractère :

Offset Len Type Description
X+0 4 Nombre entier String length
X+4 X Octets UTF-8 encoded string

Chaque chaîne de caractère est rembourrée(padded) à 4 octets.

24 : PoolVector2Array

Offset Len Type Description
4 4 Nombre entier Array length
8..8+length*8 4 Float X coordinate
8..12+length*8 4 Float Y coordinate

25 : PoolVector3Array

Offset Len Type Description
4 4 Nombre entier Array length
8..8+length*12 4 Float X coordinate
8..12+length*12 4 Float Y coordinate
8..16+length*12 4 Float Z coordinate

26 : PoolColorArray

Offset Len Type Description
4 4 Nombre entier Array length
8..8+length*16 4 Float Red (typically 0..1, can be above 1 for overbright colors)
8..12+length*16 4 Float Green (typically 0..1, can be above 1 for overbright colors)
8..16+length*16 4 Float Blue (typically 0..1, can be above 1 for overbright colors)
8..20+length*16 4 Float Alpha (0..1)