二进制序列化API

简介

Godot有一个基于变量的简单序列化API。 它被用于高效地将数据类型转换为字节数组。 这个API用在 File 的函数 get_varstore_var 中 以及 PacketPeer 的包API中。 此格式不用于二进制场景和资源。

包规范

数据包被设计成4个字节的填充。 所有值都是小端编码。 所有数据包都有一个4字节的头,表示成一个指定数据类型的整数:

类型
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. If instead doubles are used, the length of “Float” fields within data structures should be 8, and the offset should be (offset - 4) * 2 + 4. The “float” type itself is always double precision.

0: null

1: bool

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

2: int

偏移量 长度 类型 描述
4 8 Integer Signed, 64-bit Integer

3: float

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

4: String

偏移量 长度 类型 描述
4 4 Integer 字符串长度 (字节)
8 X Bytes UTF-8编码字符串

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

5: Vector2

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

6: Rect2

偏移量 长度 类型 描述
4 4 Float X 坐标
8 4 Float Y 坐标
12 4 Float X大小
16 4 Float Y大小

7: Vector3

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

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 坐标
8 4 Float Y 坐标
12 4 Float Z 坐标
16 4 Float X大小
20 4 Float Y大小
24 4 Float Z大小

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 红色通道 (0..1)
8 4 Float 绿色通道 (0..1)
12 4 Float 蓝色通道 (0..1)
16 4 Float 透明通道 (0..1)

15: NodePath

偏移量 长度 类型 描述
4 4 Integer 字符串长度或新格式 (val&0x80000000!=0 和 NameCount=val&0x7FFFFFFF)

对于旧格式:

偏移量 长度 类型 描述
8 X Bytes UTF-8编码字符串

填充到4个字节。

对于新格式:

偏移量 长度 类型 描述
4 4 Integer 子名称计数
8 4 Integer 标志 (absolute: val&1 != 0 )

对于每个名称和子名称

偏移量 长度 类型 描述
X+0 4 Integer 字符串长度
X+4 X Bytes UTF-8编码字符串

每个名称字符串都会填充到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 数组长度(字节)
8..8+长度 1 Byte 字节 (0..255)

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

21: PoolIntArray

偏移量 长度 类型 描述
4 4 Integer 数组长度(整数)
8..8+长度*4 4 Integer 32位符号整数

22: PoolRealArray

偏移量 长度 类型 描述
4 4 Integer 数组长度(浮点数)
8..8+长度*4 4 Integer 32 Bits IEEE 754 Float

23: PoolStringArray

偏移量 长度 类型 描述
4 4 Integer 数组长度(字符串)

对于每个字符串:

偏移量 长度 类型 描述
X+0 4 Integer 字符串长度
X+4 X Bytes UTF-8编码字符串

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

24: PoolVector2Array

偏移量 长度 类型 描述
4 4 Integer 数组长度
8..8+长度*8 4 Float X 坐标
8..12+长度*8 4 Float Y 坐标

25: PoolVector3Array

偏移量 长度 类型 描述
4 4 Integer 数组长度
8..8+长度*12 4 Float X 坐标
8..12+长度*12 4 Float Y 坐标
8..16+长度*12 4 Float Z 坐标

26: PoolColorArray

偏移量 长度 类型 描述
4 4 Integer 数组长度
8..8+长度*16 4 Float 红色通道 (0..1)
8..12+长度*16 4 Float 绿色通道 (0..1)
8..16+长度*16 4 Float 蓝色通道 (0..1)
8..20+长度*16 4 Float 透明通道 (0..1)