Binary serialization API

소개

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 class_File as well as the packet APIs for class_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:

유형
0 null
1 bool
2 integer
3 float
4 문자열
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 of packet:

0: null

1: bool

Offset Len 유형 설명
4 4 정수(Integer) 0 for False, 1 for True

2: int

Offset Len 유형 설명
4 4 정수(Integer) Signed, 32-Bit Integer

3: float/real

Offset Len 유형 설명
4 4 Float IEE 754 32-Bits Float

4: String

Offset Len 유형 설명
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 유형 설명
4 4 Float X Coordinate
8 4 Float Y Coordinate

6: Rect2

Offset Len 유형 설명
4 4 Float X Coordinate
8 4 Float Y Coordinate
12 4 Float X Size
16 4 Float Y Size

7: Vector3

Offset Len 유형 설명
4 4 Float X Coordinate
8 4 Float Y Coordinate
12 4 Float Z Coordinate

8: Transform2D

Offset Len 유형 설명
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [1][0]
16 4 Float [1][1]
20 4 Float [2][0]
24 4 Float [2][1]

9: Plane

Offset Len 유형 설명
4 4 Float Normal X
8 4 Float Normal Y
12 4 Float Normal Z
16 4 Float Distance

10: Quat

Offset Len 유형 설명
4 4 Float Imaginary X
8 4 Float Imaginary Y
12 4 Float Imaginary Z
16 4 Float Real W

11: AABB

Offset Len 유형 설명
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 유형 설명
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]

13: Transform

Offset Len 유형 설명
4 4 Float [0][0]
8 4 Float [0][1]
12 4 Float [0][2]
16 4 Float [1][0]
20 4 Float [1][1]
24 4 Float [1][2]
28 4 Float [2][0]
32 4 Float [2][1]
36 4 Float [2][2]
40 4 Float [3][0]
44 4 Float [3][1]
48 4 Float [3][2]

14: Color

Offset Len 유형 설명
4 4 Float Red (0..1)
8 4 Float Green (0..1)
12 4 Float Blue (0..1)
16 4 Float Alpha (0..1)

15: NodePath

Offset Len 유형 설명
4 4 정수(Integer) String Length, or New Format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

For old format:

Offset Len 유형 설명
8 X Bytes UTF-8 Encoded String

Padded to 4 bytes.

For new format:

Offset Len 유형 설명
4 4 정수(Integer) Sub-Name Count
8 4 정수(Integer) Flags (absolute: val&1 != 0 )

For each Name and Sub-Name

Offset Len 유형 설명
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 유형 설명
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 유형 설명
4 4 정수(Integer) 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

Offset Len 유형 설명
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 유형 설명
4 4 정수(Integer) Array Length (Integers)
8..8+length*4 4 정수(Integer) 32 Bits Signed Integer

22: PoolRealArray

Offset Len 유형 설명
4 4 정수(Integer) Array Length (Floats)
8..8+length*4 4 정수(Integer) 32 Bits IEE 754 Float

23: PoolStringArray

Offset Len 유형 설명
4 4 정수(Integer) Array Length (Strings)

For each String:

Offset Len 유형 설명
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 유형 설명
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 유형 설명
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 유형 설명
4 4 정수(Integer) Array Length
8..8+length*16 4 Float Red (0..1)
8..12+length*16 4 Float Green (0..1)
8..16+length*16 4 Float Blue (0..1)
8..20+length*16 4 Float Alpha (0..1)