Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

API di serializzazione binaria

Introduzione

Godot include un'API di serializzazione basata su Variant. È utilizzata per convertire efficientemente i tipi di dati in un array di byte. Questa API è esposta tramite le funzioni globali bytes_to_var() e var_to_bytes(), ma è utilizzata anche nei metodi get_var e store_var di FileAccess, nonché nelle API dei pacchetti per PacketPeer. Questo formato non è utilizzato per scene e risorse binarie.

Interi oggetti vs ID istanza di oggetto

Se una variabile viene serializzata con full_objects = true, tutti gli oggetti contenuti nella variabile verranno serializzati e inclusi nel risultato. Ciò è ricorsivo.

Se full_objects = false, solo gli ID istanza verranno serializzati, per ogni oggetto contenuto nella variabile.

Specificazione dei pacchetti

Il pacchetto è progettato per essere sempre imbottito a 4 byte. Tutti i valori sono codificati in little-endian. Tutti i pacchetti hanno un'intestazione di 4 byte che rappresenta un intero, specificando il tipo di dati.

I due byte con il valore più basso vengono utilizzati per determinare il tipo, mentre i due byte con il valore più alto contengono i flag:

base_type = val & 0xFFFF;
flags = val >> 16;

Tipo	Valore
0	null
1	bool
2	integer
3	float
4	string
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	dictionary
19	array
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

A seguire è il contenuto effettivo del pacchetto, che varia a seconda del tipo di pacchetto. Si noti che questo presuppone che Godot sia compilato con float a precisione singola, che è l'impostazione predefinita. Se Godot fosse compilato con float a precisione doppia, la lunghezza dei campi "Float" all'interno delle strutture dati dovrebbe essere 8, e l'offset dovrebbe essere (offset - 4) * 2 + 4. Il tipo "float" stesso utilizza sempre la precisione doppia.

0: null

1: bool

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	0 per False, 1 per True

2: int

Se non sono impostati flag (flags == 0), l'intero viene inviato come intero a 32 bit:

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Numero intero con segno a 32 bit

Se il flag ENCODE_FLAG_64 è impostato (flags & 1 == 1), l'intero viene inviato come intero a 64 bit:

Scostamento	Len	Tipo	Descrizione
4	8	Numero intero	Numero intero con segno a 64 bit

3: float

Se nessun flag è impostato (flags == 0), il float viene inviato con precisione singola a 32 bit:

Scostamento	Len	Tipo	Descrizione
4	4	Float	Float IEEE 754 a precisione singola

Se il flag ENCODE_FLAG_64 è impostato (flags & 1 == 1), il float viene inviato come numero a doppia precisione a 64 bit:

Scostamento	Len	Tipo	Descrizione
4	8	Float	Float IEEE 754 a precisione doppia

4: String

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza della stringa (in byte)
8	X	Byte	Stringa codificata in UTF-8

Questo campo è imbottito a 4 byte.

5: Vector2

Scostamento	Len	Tipo	Descrizione
4	4	Float	Coordinata X
8	4	Float	Coordinata Y

6: Rect2

Scostamento	Len	Tipo	Descrizione
4	4	Float	Coordinata X
8	4	Float	Coordinata Y
12	4	Float	Dimensione in X
16	4	Float	Dimensione in Y

7: Vector3

Scostamento	Len	Tipo	Descrizione
4	4	Float	Coordinata X
8	4	Float	Coordinata Y
12	4	Float	Coordinata Z

8: Transform2D

Scostamento	Len	Tipo	Descrizione
4	4	Float	La componente X del vettore colonna X, accessibile tramite [0][0]
8	4	Float	La componente Y del vettore colonna X, accessibile tramite [0][1]
12	4	Float	La componente X del vettore colonna Y, accessibile tramite [1][0]
16	4	Float	La componente Y del vettore colonna Y, accessibile tramite [1][1]
20	4	Float	La componente X del vettore origine, accessibile tramite [2][0]
24	4	Float	La componente Y del vettore origine, accessibile tramite [2][1]

9: Plane

Scostamento	Len	Tipo	Descrizione
4	4	Float	Normale in X
8	4	Float	Normale in Y
12	4	Float	Normale in Z
16	4	Float	Distanza

10: Quaternion

Scostamento	Len	Tipo	Descrizione
4	4	Float	X immaginario
8	4	Float	Y immaginario
12	4	Float	Z immaginario
16	4	Float	W reale

11: AABB

Scostamento	Len	Tipo	Descrizione
4	4	Float	Coordinata X
8	4	Float	Coordinata Y
12	4	Float	Coordinata Z
16	4	Float	Dimensione in X
20	4	Float	Dimensione in Y
24	4	Float	Dimensione in Z

12: Basis

Scostamento	Len	Tipo	Descrizione
4	4	Float	La componente X del vettore colonna X, accessibile tramite [0][0]
8	4	Float	La componente Y del vettore colonna X, accessibile tramite [0][1]
12	4	Float	La componente Z del vettore colonna X, accessibile tramite [0][2]
16	4	Float	La componente X del vettore colonna Y, accessibile tramite [1][0]
20	4	Float	La componente Y del vettore colonna Y, accessibile tramite [1][1]
24	4	Float	La componente Z del vettore colonna Y, accessibile tramite [1][2]
28	4	Float	La componente X del vettore colonna Z, accessibile tramite [2][0]
32	4	Float	La componente Y del vettore colonna Z, accessibile tramite [2][1]
36	4	Float	La componente Z del vettore colonna Z, accessibile tramite [2][2]

13: Transform3D

Scostamento	Len	Tipo	Descrizione
4	4	Float	La componente X del vettore colonna X, accessibile tramite [0][0]
8	4	Float	La componente Y del vettore colonna X, accessibile tramite [0][1]
12	4	Float	La componente Z del vettore colonna X, accessibile tramite [0][2]
16	4	Float	La componente X del vettore colonna Y, accessibile tramite [1][0]
20	4	Float	La componente Y del vettore colonna Y, accessibile tramite [1][1]
24	4	Float	La componente Z del vettore colonna Y, accessibile tramite [1][2]
28	4	Float	La componente X del vettore colonna Z, accessibile tramite [2][0]
32	4	Float	La componente Y del vettore colonna Z, accessibile tramite [2][1]
36	4	Float	La componente Z del vettore colonna Z, accessibile tramite [2][2]
40	4	Float	La componente X del vettore origine, accessibile tramite [3][0]
44	4	Float	La componente Y del vettore origine, accessibile tramite [3][1]
48	4	Float	La componente Z del vettore origine, accessibile tramite [3][2]

14: Color

Scostamento	Len	Tipo	Descrizione
4	4	Float	Rosso (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
8	4	Float	Verde (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
12	4	Float	Blu (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
16	4	Float	Alfa (0..1)

15: NodePath

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza della stringa, o nuovo formato (val&0x80000000!=0 e NameCount=val&0x7FFFFFFF)

Per il vecchio formato:

Scostamento	Len	Tipo	Descrizione
8	X	Byte	Stringa codificata in UTF-8

Imbottito a 4 byte.

Per il nuovo formato:

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Conteggio dei sotto-nomi
8	4	Numero intero	Flag (assoluto: val&1 != 0 )

Per ogni nome e sotto-nome

Scostamento	Len	Tipo	Descrizione
X+0	4	Numero intero	Lunghezza della stringa
X+4	X	Byte	Stringa codificata in UTF-8

Ogni stringa di nome è imbottita a 4 byte.

16: RID (non supportato)

17: Object

Un oggetto può essere serializzato in tre modi diversi: come valore null, con full_objects = false o con full_objects = true.

Un valore null

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Zero (intero con segno a 32 bit)

full_objects disabilitato

Scostamento	Len	Tipo	Descrizione
4	8	Numero intero	L'ID istanza dell'oggetto (intero con segno a 64 bit)

full_objects abilitato

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Nome di classe (lunghezza della stringa)
8	X	Byte	Nome di classe (stringa codificata in UTF-8)
X+8	4	Numero intero	Il numero di proprietà serializzate

Per ogni proprietà:

Scostamento	Len	Tipo	Descrizione
Y	4	Numero intero	Nome di proprietà (lunghezza della stringa)
X+4	Z	Byte	Nome di proprietà (stringa codificata in UTF-8)
Y+4+Z	W	<variabile>	Valore di proprietà, utilizzando lo stesso formato

Nota

Non tutte le proprietà sono incluse. Solo le proprietà configurate con il flag PROPERTY_USAGE_STORAGE impostato verranno serializzate. È possibile aggiungere un nuovo flag di utilizzo a una proprietà sovrascrivendo il metodo _get_property_list nella classe. È anche possibile verificare come è configurato l'utilizzo della proprietà chiamando Object._get_property_list. Consultare PropertyUsageFlags per i flag di utilizzo possibili.

18: Dictionary

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	val&0x7FFFFFFF = elementi, val&0x80000000 = condiviso (bool)

Ciò che segue è, per la quantità di "elementi", coppie di chiave e valore, una dopo l'altra, utilizzando questo stesso formato.

19: Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	val&0x7FFFFFFF = elementi, val&0x80000000 = condiviso (bool)

Ciò che segue è, per la quantità di "elementi", valori uno dopo l'altro, utilizzando questo stesso formato.

20: PackedByteArray

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array (Byte)
8..8+lunghezza	1	Byte	Byte (0..255)

I dati dell'array sono imbottiti a 4 byte.

21: PackedInt32Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array (interi)
8..8+lunghezza*4	4	Numero intero	Numero intero con segno a 32 bit

22: PackedInt64Array

Scostamento	Len	Tipo	Descrizione
4	8	Numero intero	Lunghezza dell'array (interi)
8..8+lunghezza*8	8	Numero intero	Numero intero con segno a 64 bit

23: PackedFloat32Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array (float)
8..8+lunghezza*4	4	Numero intero	float IEEE 754 a precisione singola a 32 bit

24: PackedFloat64Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array (float)
8..8+lunghezza*8	8	Numero intero	float IEEE 754 a precisione doppia a 64 bit

25: PackedStringArray

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array (Stringhe)

Per ogni stringa:

Scostamento	Len	Tipo	Descrizione
X+0	4	Numero intero	Lunghezza della stringa
X+4	X	Byte	Stringa codificata in UTF-8

Ogni stringa è imbottita a 4 byte.

26: PackedVector2Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array
8..8+lunghezza*8	4	Float	Coordinata X
8..12+lunghezza*8	4	Float	Coordinata Y

27: PackedVector3Array

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array
8..8+lunghezza*12	4	Float	Coordinata X
8..12+lunghezza*12	4	Float	Coordinata Y
8..16+lunghezza*12	4	Float	Coordinata Z

28: PackedColorArray

Scostamento	Len	Tipo	Descrizione
4	4	Numero intero	Lunghezza dell'array
8..8+lunghezza*16	4	Float	Rosso (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
8..12+lunghezza*16	4	Float	Verde (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
8..16+lunghezza*16	4	Float	Blu (tipicamente 0..1, può essere superiore a 1 per colori sovra-luminosi)
8..20+lunghezza*16	4	Float	Alfa (0..1)