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...

Binäre Serialisierungs-API

Einführung

Godot hat eine Serialisierungs-API, die auf Variant basiert. Sie wird verwendet, um Datentypen effizient in ein Array von Bytes zu konvertieren. Diese API wird über die globalen Funktionen bytes_to_var() und var_to_bytes() zugänglich gemacht, aber sie wird auch in den Methoden get_var und store_var von FileAccess sowie in den Paket-APIs für PacketPeer verwendet. Dieses Format wird nicht für binäre Szenen und Ressourcen verwendet.

Vollständige Objekte vs. Objektinstanz-IDs

Wenn eine Variable mit full_objects = true serialisiert wird, dann werden alle in der Variable enthaltenen Objekte serialisiert und in das Ergebnis aufgenommen. Dies ist rekursiv.

Wenn full_objects = false, dann werden nur die Instanz-IDs für alle in der Variable enthaltenen Objekte serialisiert.

Paketspezifikation

Das Paket ist so konzipiert, dass es immer auf 4 Bytes aufgefüllt wird. Alle Werte sind Little-Endian-codiert. Alle Pakete haben einen 4-Byte-Header, der eine Ganzzahl darstellt und den Datentyp angibt.

The lowest value two bytes are used to determine the type, while the highest value two bytes contain flags:

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

Typ	Wert
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

Darauf folgt der tatsächliche Paketinhalt, der für jeden Pakettyp unterschiedlich ist. Beachten Sie, dass dies voraussetzt, dass Godot mit Single Precision-Floats kompiliert wird. Dies ist die Default-Einstellung. Wenn Godot mit Double Precision-Floats kompiliert wurde, sollte die Länge der "Float"-Felder in Datenstrukturen 8 und der Offset (offset - 4) * 2 + 4 betragen. Der Typ "float" selbst verwendet immer die Double Precision.

0: null

1: bool

Versatz	Länge	Typ	Beschreibung
4	4	Integer	0 für False, 1 für True

2: int

Wenn keine Flags gesetzt sind (flags == 0), wird die Integer als 32-Bit-Integer gesendet:

Versatz	Länge	Typ	Beschreibung
4	4	Integer	32-bit Signed Integer

Wenn das Flag ENCODE_FLAG_64 gesetzt ist (flags & 1 == 1), wird das Integer als 64-Bit Integer gesendet:

Versatz	Länge	Typ	Beschreibung
4	8	Integer	64-Bit Signed Integer

3: float

Wenn keine Flags gesetzt sind (flags == 0), wird der Float als 32-Bit-Single-Precision gesendet:

Versatz	Länge	Typ	Beschreibung
4	4	Float	IEEE 754 Single Precision Float

Wenn das Flag ENCODE_FLAG_64 gesetzt ist (flags & 1 == 1), wird der Float als 64-Bit-Zahl mit Double Precision gesendet:

Versatz	Länge	Typ	Beschreibung
4	8	Float	IEEE 754 Double Precision Float

4: String

Versatz	Länge	Typ	Beschreibung
4	4	Integer	String-Länge (in Bytes)
8	X	Bytes	UTF-8-codierter String

Dieses Feld wird auf 4 Bytes per Padding aufgefüllt.

5: Vector2

Versatz	Länge	Typ	Beschreibung
4	4	Float	X-Koordinate
8	4	Float	Y-Koordinate

6: Rect2

Versatz	Länge	Typ	Beschreibung
4	4	Float	X-Koordinate
8	4	Float	Y-Koordinate
12	4	Float	X-Größe
16	4	Float	Y-Größe

7: Vector3

Versatz	Länge	Typ	Beschreibung
4	4	Float	X-Koordinate
8	4	Float	Y-Koordinate
12	4	Float	Z-Koordinate

8: Transform2D

Versatz	Länge	Typ	Beschreibung
4	4	Float	Die X-Komponente des X-Spaltenvektors, auf die über [0][0] zugegriffen wird
8	4	Float	Die Y-Komponente des X-Spaltenvektors, auf die über [0][1] zugegriffen wird
12	4	Float	Die X-Komponente des Y-Spaltenvektors, auf die über [1][0] zugegriffen wird
16	4	Float	Die Y-Komponente des Y-Spaltenvektors, auf die über [1][1] zugegriffen wird
20	4	Float	Die X-Komponente des Ursprungsvektors, auf die über [2][0] zugegriffen wird
24	4	Float	Die Y-Komponente des Ursprungsvektors, auf die über [2][1] zugegriffen wird

9: Plane

Versatz	Länge	Typ	Beschreibung
4	4	Float	Normalen-X
8	4	Float	Normalen-Y
12	4	Float	Normalen-Z
16	4	Float	Distanz

10: Quaternion

Versatz	Länge	Typ	Beschreibung
4	4	Float	Imaginäres X
8	4	Float	Imaginäres Y
12	4	Float	Imaginäres Z
16	4	Float	Reales W

11: AABB

Versatz	Länge	Typ	Beschreibung
4	4	Float	X-Koordinate
8	4	Float	Y-Koordinate
12	4	Float	Z-Koordinate
16	4	Float	X-Größe
20	4	Float	Y-Größe
24	4	Float	Z-Größe

12: Basis

Versatz	Länge	Typ	Beschreibung
4	4	Float	Die X-Komponente des X-Spaltenvektors, auf die über [0][0] zugegriffen wird
8	4	Float	Die Y-Komponente des X-Spaltenvektors, auf die über [0][1] zugegriffen wird
12	4	Float	Die Z-Komponente des X-Spaltenvektors, auf die über [0][2] zugegriffen wird
16	4	Float	Die X-Komponente des Y-Spaltenvektors, auf die über [1][0] zugegriffen wird
20	4	Float	Die Y-Komponente des Y-Spaltenvektors, auf die über [1][1] zugegriffen wird
24	4	Float	Die Z-Komponente des Y-Spaltenvektors, auf die über [1][2] zugegriffen wird
28	4	Float	Die X-Komponente des Z-Spaltenvektors, auf die über [2][0] zugegriffen wird
32	4	Float	Die Y-Komponente des Z-Spaltenvektors, auf die über [2][1] zugegriffen wird
36	4	Float	Die Z-Komponente des Z-Spaltenvektors, auf die über [2][2] zugegriffen wird

13: Transform3D

Versatz	Länge	Typ	Beschreibung
4	4	Float	Die X-Komponente des X-Spaltenvektors, auf die über [0][0] zugegriffen wird
8	4	Float	Die Y-Komponente des X-Spaltenvektors, auf die über [0][1] zugegriffen wird
12	4	Float	Die Z-Komponente des X-Spaltenvektors, auf die über [0][2] zugegriffen wird
16	4	Float	Die X-Komponente des Y-Spaltenvektors, auf die über [1][0] zugegriffen wird
20	4	Float	Die Y-Komponente des Y-Spaltenvektors, auf die über [1][1] zugegriffen wird
24	4	Float	Die Z-Komponente des Y-Spaltenvektors, auf die über [1][2] zugegriffen wird
28	4	Float	Die X-Komponente des Z-Spaltenvektors, auf die über [2][0] zugegriffen wird
32	4	Float	Die Y-Komponente des Z-Spaltenvektors, auf die über [2][1] zugegriffen wird
36	4	Float	Die Z-Komponente des Z-Spaltenvektors, auf die über [2][2] zugegriffen wird
40	4	Float	Die X-Komponente des Ursprungsvektors, auf die über [3][0] zugegriffen wird
44	4	Float	Die Y-Komponente des Ursprungsvektors, auf die über [3][1] zugegriffen wird
48	4	Float	Die Z-Komponente des Ursprungsvektors, auf die über [3][2] zugegriffen wird

14: Color

Versatz	Länge	Typ	Beschreibung
4	4	Float	Rot (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
8	4	Float	Grün (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
12	4	Float	Blau (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
16	4	Float	Alpha (0..1)

15: NodePath

Versatz	Länge	Typ	Beschreibung
4	4	Integer	String-Länge, oder neues Format (val&0x80000000!=0 und NameCount=val&0x7FFFFFFF)

Für altes Format:

Versatz	Länge	Typ	Beschreibung
8	X	Bytes	UTF-8-codierter String

Aufgefüllt mit Padding auf 4 Byte.

Für neues Format:

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Anzahl der Unternamen
8	4	Integer	Flags (absolut: val&1 != 0 )

Für jeden Namen und Unter-Namen

Versatz	Länge	Typ	Beschreibung
X+0	4	Integer	String-Länge
X+4	X	Bytes	UTF-8-codierter String

Jeder Namens-String wird mit Padding auf 4 Bytes aufgefüllt.

16: RID (nicht unterstützt)

17: Object

Ein Objekt kann auf drei verschiedene Arten serialisiert werden: als ein null-Wert, mit full_objects = false, oder mit full_objects = true.

Ein null-Wert

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Null (32-Bit Signed Integer)

full_objects deaktiviert

Versatz	Länge	Typ	Beschreibung
4	8	Integer	Die Objektinstanz-ID (64-Bit Signed Integer)

full_objects aktiviert

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Klassenname (String-Länge)
8	X	Bytes	Klassenname (UTF-8 kodierter String)
X+8	4	Integer	Die Anzahl der Propertys, die serialisiert werden

Für jede Property:

Versatz	Länge	Typ	Beschreibung
Y	4	Integer	Property-Name (String-Länge)
Y+4	Z	Bytes	Property-Name (UTF-8 kodierter String)
Y+4+Z	W	<variable>	Wert der Property, unter Verwendung desselben Formats

Bemerkung

Es werden nicht alle Propertys einbezogen. Nur Propertys, die mit dem gesetzten PROPERTY_USAGE_STORAGE-Flag konfiguriert sind, werden serialisiert. Sie können eine neue Usage Flag zu einer Property hinzufügen, indem Sie die Methode _get_property_list in Ihrer Klasse überschreiben. Sie können auch überprüfen, wie die Property-Verwendung konfiguriert ist, indem Sie Object._get_property_list aufrufen. Siehe PropertyUsageFlags für die möglichen Usage-Flags.

18: Dictionary

Versatz	Länge	Typ	Beschreibung
4	4	Integer	val&0x7FFFFFFF = Elemente, val&0x80000000 = shared (Bool)

Dann folgen für die Menge der "Elemente", Paare von Schlüssel und Wert, eines nach dem anderen, unter Verwendung desselben Formats.

19: Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	val&0x7FFFFFFF = Elemente, val&0x80000000 = shared (Bool)

Dann folgen für die Menge der "Elemente" nacheinander Werte in demselben Format.

20: PackedByteArray

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge (Bytes)
8..8+Länge	1	Byte	Byte (0..255)

Die Array-Daten werden mit Padding auf 4 Byte aufgefüllt.

21: PackedInt32Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge (Integers)
8..8+Länge*4	4	Integer	32-bit Signed Integer

22: PackedInt64Array

Versatz	Länge	Typ	Beschreibung
4	8	Integer	Array-Länge (Integers)
8..8+Länge*8	8	Integer	64-Bit Signed Integer

23: PackedFloat32Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge (Floats)
8..8+Länge*4	4	Integer	32-Bit IEEE 754 Single Precision Float

24: PackedFloat64Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge (Floats)
8..8+Länge*8	8	Integer	64-Bit IEEE 754 Double Precision Float

25: PackedStringArray

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge (Strings)

für jeden String:

Versatz	Länge	Typ	Beschreibung
X+0	4	Integer	String-Länge
X+4	X	Bytes	UTF-8-codierter String

Jeder String wird mit Padding auf 4 Bytes aufgefüllt.

26: PackedVector2Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge
8..8+Länge*8	4	Float	X-Koordinate
8..12+Länge*8	4	Float	Y-Koordinate

27: PackedVector3Array

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge
8..8+Länge*12	4	Float	X-Koordinate
8..12+Länge*12	4	Float	Y-Koordinate
8..16+Länge*12	4	Float	Z-Koordinate

28: PackedColorArray

Versatz	Länge	Typ	Beschreibung
4	4	Integer	Array-Länge
8..8+Länge*16	4	Float	Rot (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
8..12+Länge*16	4	Float	Grün (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
8..16+Länge*16	4	Float	Blau (normalerweise 0..1, kann über 1 sein für überstrahlende Farben)
8..20+Länge*16	4	Float	Alpha (0..1)