Work in progress
The content of this page was not yet updated for Godot
4.2
and may be outdated. If you know how to improve this page or you can confirm
that it's up to date, feel free to open a pull request.
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.
Die zwei Bytes mit dem niedrigsten Wert werden zur Bestimmung des Typs verwendet, während die zwei Bytes mit dem höchsten Wert Flags enthalten:
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) |