Binary serialization API

Einführung

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.

Packet specification

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:

Art Wert
0 null
1 bool
2 integer (Ganzzahl)
3 float
4 Zeichenkette
5 vector2
6 rect2
7 vector3
8 transform2d
9 plane
10 quat
11 aabb
12 Basis
13 transform
14 Farbe
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 Art Beschreibung
4 4 Ganze Zahl 0 for False, 1 for True

2: int

Offset Len Art Beschreibung
4 8 Ganze Zahl 64-bit signed integer

3: float

Offset Len Art Beschreibung
4 4 Float IEE 754 32-Bits Float

4: String

Offset Len Art Beschreibung
4 4 Ganze Zahl String length (in bytes)
8 X Bytes UTF-8 encoded string

This field is padded to 4 bytes.

5: Vector2

Offset Len Art Beschreibung
4 4 Float X coordinate
8 4 Float Y coordinate

6: Rect2

Offset Len Art Beschreibung
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float X size
16 4 Float Y size

7: Vector3

Offset Len Art Beschreibung
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float Z coordinate

8: Transform2D

Offset Len Art Beschreibung
4 4 Float The X component of the X column vector, accessed via [0][0]
8 4 Float The Y component of the X column vector, accessed via [0][1]
12 4 Float The X component of the Y column vector, accessed via [1][0]
16 4 Float The Y component of the Y column vector, accessed via [1][1]
20 4 Float The X component of the origin vector, accessed via [2][0]
24 4 Float The Y component of the origin vector, accessed via [2][1]

9: Plane

Offset Len Art Beschreibung
4 4 Float Normal X
8 4 Float Normal Y
12 4 Float Normal Z
16 4 Float Distance

10: Quat

Offset Len Art Beschreibung
4 4 Float Imaginary X
8 4 Float Imaginary Y
12 4 Float Imaginary Z
16 4 Float Real W

11: AABB

Offset Len Art Beschreibung
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 Art Beschreibung
4 4 Float The X component of the X column vector, accessed via [0][0]
8 4 Float The Y component of the X column vector, accessed via [0][1]
12 4 Float The Z component of the X column vector, accessed via [0][2]
16 4 Float The X component of the Y column vector, accessed via [1][0]
20 4 Float The Y component of the Y column vector, accessed via [1][1]
24 4 Float The Z component of the Y column vector, accessed via [1][2]
28 4 Float The X component of the Z column vector, accessed via [2][0]
32 4 Float The Y component of the Z column vector, accessed via [2][1]
36 4 Float The Z component of the Z column vector, accessed via [2][2]

13: Transform

Offset Len Art Beschreibung
4 4 Float The X component of the X column vector, accessed via [0][0]
8 4 Float The Y component of the X column vector, accessed via [0][1]
12 4 Float The Z component of the X column vector, accessed via [0][2]
16 4 Float The X component of the Y column vector, accessed via [1][0]
20 4 Float The Y component of the Y column vector, accessed via [1][1]
24 4 Float The Z component of the Y column vector, accessed via [1][2]
28 4 Float The X component of the Z column vector, accessed via [2][0]
32 4 Float The Y component of the Z column vector, accessed via [2][1]
36 4 Float The Z component of the Z column vector, accessed via [2][2]
40 4 Float The X component of the origin vector, accessed via [3][0]
44 4 Float The Y component of the origin vector, accessed via [3][1]
48 4 Float The Z component of the origin vector, accessed via [3][2]

14: Color

Offset Len Art 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

Offset Len Art Beschreibung
4 4 Ganze Zahl Zeichenketten Länge, oder neues Format (val&0x80000000!=0 und NameCount=val&0x7FFFFFFF)

für altes Format:

Offset Len Art Beschreibung
8 X Bytes UTF-8 encoded string

aufgefüllt auf 4 Byte.

für neues Format:

Offset Len Art Beschreibung
4 4 Ganze Zahl Sub-name count
8 4 Ganze Zahl Flags (absolut: val&1 != 0 )

For each Name and Sub-Name

Offset Len Art Beschreibung
X+0 4 Ganze Zahl Zeichenketten Länge
X+4 X Bytes UTF-8 encoded string

Every name string is padded to 4 bytes.

16: RID (nicht unterstützt)

17: Object (nicht unterstützt)

18: Dictionary

Offset Len Art Beschreibung
4 4 Ganze Zahl val&0x7FFFFFFF = Elemente, val&0x80000000 = shared (Bool)

Then what follows is, for amount of "elements", pairs of key and value, one after the other, using this same format.

19: Feld

Offset Len Art Beschreibung
4 4 Ganze Zahl val&0x7FFFFFFF = Elemente, val&0x80000000 = shared (Bool)

Then what follows is, for amount of "elements", values one after the other, using this same format.

20: PoolByteArray

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge (Bytes)
8..8+Länge 1 Byte Byte (0..255)

Die Felddaten werden auf 4 Byte aufgefüllt.

21: PoolIntArray

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge (Integer)
8..8+Länge*4 4 Ganze Zahl 32-bit signed integer (Vorzeichen behaftet)

22: PoolRealArray

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge (Fließkomma)
8..8+Länge*4 4 Ganze Zahl 32-bit IEEE 754 Fließkomma

23: PoolStringArray

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge (Zeichenketten)

für jede Zeichenkette:

Offset Len Art Beschreibung
X+0 4 Ganze Zahl Zeichenketten Länge
X+4 X Bytes UTF-8 encoded string

Jede Zeichenkette wird auf 4 Bytes aufgefüllt.

24: PoolVector2Array

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge
8..8+Länge*8 4 Float X coordinate
8..12+Länge*8 4 Float Y coordinate

25: PoolVector3Array

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld Länge
8..8+Länge*12 4 Float X coordinate
8..12+Länge*12 4 Float Y coordinate
8..16+Länge*12 4 Float Z coordinate

26: PoolColorArray

Offset Len Art Beschreibung
4 4 Ganze Zahl Feld 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)