Binarna serizlizacja API

Wprowadzenie

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.

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	Wartość
0	null
1	bool
2	integer
3	float
4	string
5	vector2
6	rect2
7	vector3
8	transform2d
9	płaszczyzna
10	quat
11	aabb
12	basis
13	transform
14	kolor
15	node path
16	rid
17	obiekt
18	słownik
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

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	0 - Fałsz, 1 - Prawda

2: int

If no flags are set (flags == 0), the integer is sent as a 32 bit integer:

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	32 bity dodatnich liczb całkowitych

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the integer is sent as a 64-bit integer:

Przesunięcie	Długość	Typ	Opis
4	8	Liczba całkowita	64-bit signed integer

3: float

If no flags are set (flags == 0), the float is sent as a 32 bit single precision:

Przesunięcie	Długość	Typ	Opis
4	4	Float	IEEE 754 single-precision float

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the float is sent as a 64-bit double precision number:

Przesunięcie	Długość	Typ	Opis
4	8	Float	IEEE 754 double-precision float

4: String

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	String length (in bytes)
8	X	Bajty	UTF-8 encoded string

This field is padded to 4 bytes.

5: Vector2

Przesunięcie	Długość	Typ	Opis
4	4	Float	X coordinate
8	4	Float	Y coordinate

6: Rect2

Przesunięcie	Długość	Typ	Opis
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	rozmiar X
16	4	Float	rozmiar Y

7: Vector3

Przesunięcie	Długość	Typ	Opis
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate

8: Transform2D

Przesunięcie	Długość	Typ	Opis
4	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
8	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
12	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
16	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
20	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
24	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie

9: Plane

Przesunięcie	Długość	Typ	Opis
4	4	Float	Normal X
8	4	Float	Normal Y
12	4	Float	Normalna Z
16	4	Float	Dystans

10: Quat

Przesunięcie	Długość	Typ	Opis
4	4	Float	Zespolone X
8	4	Float	Zespolone Y
12	4	Float	Zespolone Z
16	4	Float	Rzeczywiste W

11: AABB

Przesunięcie	Długość	Typ	Opis
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate
16	4	Float	rozmiar X
20	4	Float	rozmiar Y
24	4	Float	Z size

12: Basis

Przesunięcie	Długość	Typ	Opis
4	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
8	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
12	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
16	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
20	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
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	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
36	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie

13: Transform

Przesunięcie	Długość	Typ	Opis
4	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
8	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
12	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
16	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
20	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
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	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
36	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
40	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
44	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie
48	4	Float	Poszczególne komponenty wektora są dostępne bezpośrednio po nazwie

14: Color

Przesunięcie	Długość	Typ	Opis
4	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
12	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
16	4	Float	Przezroczystość (0..1)

15: NodePath

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

Dla starego formatu:

Przesunięcie	Długość	Typ	Opis
8	X	Bajty	UTF-8 encoded string

Padded to 4 bytes.

Dla nowego formatu:

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Sub-name count
8	4	Liczba całkowita	Flags (absolute: val&1 != 0 )

For each Name and Sub-Name

Przesunięcie	Długość	Typ	Opis
X+0	4	Liczba całkowita	String length
X+4	X	Bajty	UTF-8 encoded string

Every name string is padded to 4 bytes.

16: RID (niewspierany)

17: Object (niewspierany)

18: Dictionary

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	val&0x7FFFFFFF = elements, 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: Array

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

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

20: PoolByteArray

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length (Bytes)
8..8+długość	1	Bajt	Bajt (0..255)

The array data is padded to 4 bytes.

21: PoolIntArray

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length (Integers)
8..8+długość*4	4	Liczba całkowita	32 bity dodatnich liczb całkowitych

22: PoolRealArray

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length (Floats)
8..8+długość*4	4	Liczba całkowita	32-bits IEEE 754 float

23: PoolStringArray

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length (Strings)

Dla każdego łańcucha znaków:

Przesunięcie	Długość	Typ	Opis
X+0	4	Liczba całkowita	String length
X+4	X	Bajty	UTF-8 encoded string

Każdy ciąg jest dopełniany do 4 bajtów.

24: PoolVector2Array

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length
8..8+długość*8	4	Float	X coordinate
8..12+długość*8	4	Float	Y coordinate

25: PoolVector3Array

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length
8..8+długość*12	4	Float	X coordinate
8..12+długość*12	4	Float	Y coordinate
8..16+długość*12	4	Float	Z coordinate

26: PoolColorArray

Przesunięcie	Długość	Typ	Opis
4	4	Liczba całkowita	Array length
8..8+długość*16	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8..12+długość*16	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
8..16+długość*16	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
8..20+długość*16	4	Float	Przezroczystość (0..1)