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)