二进制序列化 API
- 前言
- 包规范

二进制序列化 API

前言

Godot有一个基于Variant的简单序列化API. 它用于有效地将数据类型转换为字节数组. 这个API用于 File 的 get_var 和 store_var 函数, 以及 PacketPeer 的包API. 这种格式不用于二进制场景和资源.

包规范

该数据包被设计为总是被填充到4个字节. 所有的值都是小端编码的. 所有数据包都有一个4字节的头, 代表一个整数, 指定数据的类型.

最低值的两个字节用于确定类型，而最高值的两个字节包含标志：

base_type = val & 0xFFFF;
flags = val >> 16;

类型	值
0	null
1	bool
2	integer
3	(单精度)浮点数
4	字符串
5	vector2
6	rect2
7	vector3
8	transform2d
9	plane
10	quat
11	aabb
12	basis
13	变换
14	颜色
15	node path
16	rid
17	object
18	字典
19	数组
20	raw array
21	int array
22	real array
23	string array
24	vector2 array
25	vector3 array
26	color array
27	max

之后是实际的数据包内容, 每种类型的数据包内容都不同. 请注意, 这是假设Godot是用单精度浮点数编译的, 这是默认的. 如果Godot是用双精度浮点数编译的, 那么数据结构中 “float” 字段的长度应该是8, 偏移量应该是 (offset - 4) * 2 + 4 . “float” 类型本身总是使用双精度.

0: null

1: bool

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

2: int

如果没有设置标志(flags == 0)，整数将作为32位整数发送:

偏移量	长度	类型	描述
4	4	Integer	32位有符号整数

如果标志 ENCODE_FLAG_64 被设置（flags & 1 == 1），则整数被发送为64位整数:

偏移量	长度	类型	描述
4	8	Integer	64位有符号整数

3: float

如果没有设置flags(flags == 0)，浮点数将作为32位单精度发送:

偏移量	长度	类型	描述
4	4	(单精度)浮点数	IEEE 754单精度浮点数

如果标志 ENCODE_FLAG_64 被设置(flags & 1 == 1)，浮点数将作为64位双精度数字发送:

偏移量	长度	类型	描述
4	8	(单精度)浮点数	IEEE 754双精度浮点数

4: String

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

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

5: Vector2

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X坐标
8	4	(单精度)浮点数	Y坐标

6: Rect2

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X坐标
8	4	(单精度)浮点数	Y坐标
12	4	(单精度)浮点数	X尺寸
16	4	(单精度)浮点数	Y尺寸

7: Vector3

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X坐标
8	4	(单精度)浮点数	Y坐标
12	4	(单精度)浮点数	Z坐标

8: Transform2D

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X列向量的X分量, 可通过[0][0]访问
8	4	(单精度)浮点数	X列向量的Y分量, 可通过[0][1]访问
12	4	(单精度)浮点数	Y列向量的X分量, 可通过[1][0]访问
16	4	(单精度)浮点数	Y列向量的Y分量, 可通过[1][1]访问
20	4	(单精度)浮点数	原始向量的X分量, 可通过[2] [0]访问
24	4	(单精度)浮点数	原始向量的Y分量, 可通过[2][1]访问

9: Plane

偏移量	长度	类型	描述
4	4	(单精度)浮点数	法线 X
8	4	(单精度)浮点数	法线 Y
12	4	(单精度)浮点数	法线 Z
16	4	(单精度)浮点数	距离

10: Quat

偏移量	长度	类型	描述
4	4	(单精度)浮点数	虚数X
8	4	(单精度)浮点数	虚数Y
12	4	(单精度)浮点数	虚数Z
16	4	(单精度)浮点数	实数W

11: AABB

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X坐标
8	4	(单精度)浮点数	Y坐标
12	4	(单精度)浮点数	Z坐标
16	4	(单精度)浮点数	X尺寸
20	4	(单精度)浮点数	Y尺寸
24	4	(单精度)浮点数	Z尺寸

12: Basis

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X列向量的X分量, 可通过[0][0]访问
8	4	(单精度)浮点数	X列向量的Y分量, 可通过[0][1]访问
12	4	(单精度)浮点数	X列向量的Z分量, 可通过[0][2]访问
16	4	(单精度)浮点数	Y列向量的X分量, 可通过[1][0]访问
20	4	(单精度)浮点数	Y列向量的Y分量, 可通过[1][1]访问
24	4	(单精度)浮点数	Y列向量的Z分量, 可通过[1][2]访问
28	4	(单精度)浮点数	Z列向量的X分量, 可通过[2][0]访问
32	4	(单精度)浮点数	Z列向量的Y分量, 可通过[2][1]访问
36	4	(单精度)浮点数	Z列向量的Z分量, 可通过[2][2]访问

13: Transform

偏移量	长度	类型	描述
4	4	(单精度)浮点数	X列向量的X分量, 可通过[0][0]访问
8	4	(单精度)浮点数	X列向量的Y分量, 可通过[0][1]访问
12	4	(单精度)浮点数	X列向量的Z分量, 可通过[0][2]访问
16	4	(单精度)浮点数	Y列向量的X分量, 可通过[1][0]访问
20	4	(单精度)浮点数	Y列向量的Y分量, 可通过[1][1]访问
24	4	(单精度)浮点数	Y列向量的Z分量, 可通过[1][2]访问
28	4	(单精度)浮点数	Z列向量的X分量, 可通过[2][0]访问
32	4	(单精度)浮点数	Z列向量的Y分量, 可通过[2][1]访问
36	4	(单精度)浮点数	Z列向量的Z分量, 可通过[2][2]访问
40	4	(单精度)浮点数	原始向量的X分量, 可通过[3][0]访问
44	4	(单精度)浮点数	原点向量的Y分量, 可通过[3][1]访问
48	4	(单精度)浮点数	原点向量的Z分量, 可通过[3][2]访问

14: Color

偏移量	长度	类型	描述
4	4	(单精度)浮点数	红色(一般为0…1, 对于过亮的颜色可大于1)
8	4	(单精度)浮点数	绿色(一般为0…1, 对于过亮的颜色可大于1)
12	4	(单精度)浮点数	蓝色(一般为0…1, 对于过亮的颜色可大于1)
16	4	(单精度)浮点数	透明通道 (0..1)

15: NodePath

偏移量	长度	类型	描述
4	4	Integer	字符串长度, 或新格式(val&0x80000000!=0 and 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	(单精度)浮点数	X坐标
8..12+长度8	4	(单精度)浮点数	Y坐标

25: PoolVector3Array

偏移量	长度	类型	描述
4	4	Integer	数组长度
8..8+长度12	4	(单精度)浮点数	X坐标
8..12+长度12	4	(单精度)浮点数	Y坐标
8..16+长度*12	4	(单精度)浮点数	Z坐标

26: PoolColorArray

偏移量	长度	类型	描述
4	4	Integer	数组长度
8..8+长度16	4	(单精度)浮点数	红色(一般为0…1, 对于过亮的颜色可大于1)
8..12+长度16	4	(单精度)浮点数	绿色(一般为0…1, 对于过亮的颜色可大于1)
8..16+长度16	4	(单精度)浮点数	蓝色(一般为0…1, 对于过亮的颜色可大于1)
8..20+长度16	4	(单精度)浮点数	透明通道 (0..1)