Binary serialization API¶
Introduction¶
Godot has a simple serialization API based on Variant. It's used forconverting data types to an array of bytes efficiently. This API is usedin the functionsget_var andstore_var ofFileas well as the packet APIs forPacketPeer. This formatisnot used for binary scenes and resources.
Packet specification¶
The packet is designed to be always padded to 4 bytes. All values arelittle-endian-encoded. All packets have a 4-byte header representing aninteger, specifying the type of data.
The lowest value two bytes are used to determine the type, while the highest valuetwo bytes contain flags:
base_type=val&0xFFFF;flags=val>>16;
Type | Value |
|---|---|
0 | null |
1 | bool |
2 | integer |
3 | float |
4 | string |
5 | vector2 |
6 | rect2 |
7 | vector3 |
8 | transform2d |
9 | plane |
10 | quat |
11 | aabb |
12 | basis |
13 | transform |
14 | color |
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 ofpacket. Note that this assumes Godot is compiled with single-precision floats,which is the default. If Godot was compiled with double-precision floats, thelength of "Float" fields within data structures should be 8, and the offsetshould be(offset-4)*2+4. The "float" type itself always uses doubleprecision.
0: null¶
1:bool¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | 0 for False, 1 for True |
2:int¶
If no flags are set (flags == 0), the integer is sent as a 32 bit integer:
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | 32-bit signed integer |
If flagENCODE_FLAG_64 is set (flags&1==1), the integer is sent asa 64-bit integer:
Offset | Len | Type | Description |
|---|---|---|---|
4 | 8 | Integer | 64-bit signed integer |
3:float¶
If no flags are set (flags == 0), the float is sent as a 32 bit single precision:
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Float | IEEE 754 single-precision float |
If flagENCODE_FLAG_64 is set (flags&1==1), the float is sent asa 64-bit double precision number:
Offset | Len | Type | Description |
|---|---|---|---|
4 | 8 | Float | IEEE 754 double-precision float |
4:String¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | String length (in bytes) |
8 | X | Bytes | UTF-8 encoded string |
This field is padded to 4 bytes.
5:Vector2¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Float | X coordinate |
8 | 4 | Float | Y coordinate |
6:Rect2¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Float | X coordinate |
8 | 4 | Float | Y coordinate |
12 | 4 | Float | X size |
16 | 4 | Float | Y size |
7:Vector3¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Float | X coordinate |
8 | 4 | Float | Y coordinate |
12 | 4 | Float | Z coordinate |
8:Transform2D¶
Offset | Len | Type | Description |
|---|---|---|---|
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 | Type | Description |
|---|---|---|---|
4 | 4 | Float | Normal X |
8 | 4 | Float | Normal Y |
12 | 4 | Float | Normal Z |
16 | 4 | Float | Distance |
10:Quat¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Float | Imaginary X |
8 | 4 | Float | Imaginary Y |
12 | 4 | Float | Imaginary Z |
16 | 4 | Float | Real W |
11:AABB¶
Offset | Len | Type | Description |
|---|---|---|---|
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 | Type | Description |
|---|---|---|---|
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 | Type | Description |
|---|---|---|---|
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 | Type | Description |
|---|---|---|---|
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 | Alpha (0..1) |
15:NodePath¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
For old format:¶
Offset | Len | Type | Description |
|---|---|---|---|
8 | X | Bytes | UTF-8 encoded string |
Padded to 4 bytes.
For new format:¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Sub-name count |
8 | 4 | Integer | Flags (absolute: val&1 != 0 ) |
For each Name and Sub-Name
Offset | Len | Type | Description |
|---|---|---|---|
X+0 | 4 | Integer | String length |
X+4 | X | Bytes | UTF-8 encoded string |
Every name string is padded to 4 bytes.
16:RID (unsupported)¶
17:Object (unsupported)¶
18:Dictionary¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | 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¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool) |
Then what follows is, for amount of "elements", values one after theother, using this same format.
20:PoolByteArray¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length (Bytes) |
8..8+length | 1 | Byte | Byte (0..255) |
The array data is padded to 4 bytes.
21:PoolIntArray¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length (Integers) |
8..8+length*4 | 4 | Integer | 32-bit signed integer |
22:PoolRealArray¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length (Floats) |
8..8+length*4 | 4 | Integer | 32-bits IEEE 754 float |
23:PoolStringArray¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length (Strings) |
For each String:
Offset | Len | Type | Description |
|---|---|---|---|
X+0 | 4 | Integer | String length |
X+4 | X | Bytes | UTF-8 encoded string |
Every string is padded to 4 bytes.
24:PoolVector2Array¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length |
8..8+length*8 | 4 | Float | X coordinate |
8..12+length*8 | 4 | Float | Y coordinate |
25:PoolVector3Array¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length |
8..8+length*12 | 4 | Float | X coordinate |
8..12+length*12 | 4 | Float | Y coordinate |
8..16+length*12 | 4 | Float | Z coordinate |
26:PoolColorArray¶
Offset | Len | Type | Description |
|---|---|---|---|
4 | 4 | Integer | Array length |
8..8+length*16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) |
8..12+length*16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) |
8..16+length*16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) |
8..20+length*16 | 4 | Float | Alpha (0..1) |