二进制序列化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 File as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

包规范

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. 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

偏移量 长度 类型 描述
4 4 Integer 0 代表 False, 1 代表 True

2: int

偏移量 长度 类型 描述
4 8 Integer 64-bit signed integer

3: float

偏移量 长度 类型 描述
4 4 Float IEE 754格式的32位浮点数

4: String

偏移量 长度 类型 描述
4 4 Integer String length (in bytes)
8 X Bytes UTF-8 encoded string

该字段会被填充成4个字节。

5: Vector2

偏移量 长度 类型 描述
4 4 Float X coordinate
8 4 Float Y coordinate

6: Rect2

偏移量 长度 类型 描述
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float X size
16 4 Float Y size

7: Vector3

偏移量 长度 类型 描述
4 4 Float X coordinate
8 4 Float Y coordinate
12 4 Float Z coordinate

8: Transform2D

偏移量 长度 类型 描述
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

偏移量 长度 类型 描述
4 4 Float 法线 X
8 4 Float 法线 Y
12 4 Float 法线 Z
16 4 Float 距离

10: Quat

偏移量 长度 类型 描述
4 4 Float 虚数X
8 4 Float 虚数Y
12 4 Float 虚数Z
16 4 Float 实数W

11: AABB

偏移量 长度 类型 描述
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

偏移量 长度 类型 描述
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

偏移量 长度 类型 描述
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

偏移量 长度 类型 描述
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 透明通道 (0..1)

15: NodePath

偏移量 长度 类型 描述
4 4 Integer String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

对于旧格式:

偏移量 长度 类型 描述
8 X Bytes UTF-8 encoded string

填充到4个字节。

对于新格式:

偏移量 长度 类型 描述
4 4 Integer Sub-name count
8 4 Integer 标志 (absolute: val&1 != 0 )

对于每个名称和子名称

偏移量 长度 类型 描述
X+0 4 Integer String length
X+4 X Bytes UTF-8 encoded string

每个名称字符串都会填充到4个字节。

16: RID (暂不支持)

17: Object (暂不支持)

18: Dictionary

偏移量 长度 类型 描述
4 4 Integer val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

然后,对于``elements``的数量,使用相同的格式,一个接一个地使用密钥和值对。

19: Array

偏移量 长度 类型 描述
4 4 Integer val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

然后,对于``elements``的数量,使用相同的格式一个接一个地输出值。

20: PoolByteArray

偏移量 长度 类型 描述
4 4 Integer Array length (Bytes)
8..8+长度 1 Byte 字节 (0..255)

数组数据填充为4个字节。

21: PoolIntArray

偏移量 长度 类型 描述
4 4 Integer Array length (Integers)
8..8+长度*4 4 Integer 32-bit signed integer

22: PoolRealArray

偏移量 长度 类型 描述
4 4 Integer Array length (Floats)
8..8+长度*4 4 Integer 32-bits IEEE 754 float

23: PoolStringArray

偏移量 长度 类型 描述
4 4 Integer Array length (Strings)

对于每个字符串:

偏移量 长度 类型 描述
X+0 4 Integer String length
X+4 X Bytes UTF-8 encoded string

每个字符串填充为4个字节。

24: PoolVector2Array

偏移量 长度 类型 描述
4 4 Integer Array length
8..8+长度*8 4 Float X coordinate
8..12+长度*8 4 Float Y coordinate

25: PoolVector3Array

偏移量 长度 类型 描述
4 4 Integer Array length
8..8+长度*12 4 Float X coordinate
8..12+长度*12 4 Float Y coordinate
8..16+长度*12 4 Float Z coordinate

26: PoolColorArray

偏移量 长度 类型 描述
4 4 Integer Array length
8..8+长度*16 4 Float Red (typically 0..1, can be above 1 for overbright colors)
8..12+长度*16 4 Float Green (typically 0..1, can be above 1 for overbright colors)
8..16+长度*16 4 Float Blue (typically 0..1, can be above 1 for overbright colors)
8..20+长度*16 4 Float 透明通道 (0..1)