二进制序列化 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 |
整数 |
3 |
浮点数 |
4 |
字符串 |
5 |
vector2 |
6 |
rect2 |
7 |
vector3 |
8 |
transform2d |
9 |
plane |
10 |
quat |
11 |
aabb |
12 |
basis |
13 |
变换 |
14 |
颜色 |
15 |
节点路径 |
16 |
rid |
17 |
对象 |
18 |
字典 |
19 |
数组 |
20 |
原始数组 |
21 |
int 数组 |
22 |
实数数组 |
23 |
字符串数组 |
24 |
vector2 数组 |
25 |
vector3 数组 |
26 |
颜色数组 |
27 |
最大值 |
在此之后是实际的数据包内容,每种类型的数据包内容都不同。请注意,这里假设 Godot 是用单精度浮点数编译的,这也是默认的。如果 Godot 是用双精度浮点数编译的,那么数据结构中“浮点数”字段的长度应该是 8,偏移量应该是 (offset - 4) * 2 + 4
。浮点数“float”类型本身总是使用双精度。
0: null¶
1: bool¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
0 代表 False, 1 代表 True |
2: int¶
如果没有设置标志(flags == 0),整数将作为32位整数发送:
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
32位有符号整数 |
如果标志 ENCODE_FLAG_64
被设置(flags & 1 == 1
),则整数被发送为64位整数:
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
8 |
整数 |
64位有符号整数 |
3: float¶
如果没有设置标志(flags == 0),浮点数将作为 32 位单精度发送:
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
浮点数 |
IEEE 754 单精度浮点数 |
如果设置了 ENCODE_FLAG_64
标志(flags & 1 == 1
),浮点数将作为 64 位双精度数字发送:
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
8 |
浮点数 |
IEEE 754 双精度浮点数 |
4: String¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
字符串长度(字节数) |
8 |
X |
多字节 |
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 |
浮点数 |
Alpha(0..1) |
15: NodePath¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
字符串长度, 或新格式(val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
对于旧格式:¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
8 |
X |
多字节 |
UTF-8 编码字符串 |
填充到4个字节.
对于新格式:¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
子名称数 |
8 |
4 |
整数 |
标志 (absolute: val&1 != 0 ) |
对于每个名称和子名称
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
X+0 |
4 |
整数 |
字符串长度 |
X+4 |
X |
多字节 |
UTF-8 编码字符串 |
每个名称字符串都会填充到4个字节.
16: RID(不支持)¶
17: Object(不支持)¶
18: Dictionary¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
val&0x7FFFFFFF = 元素,val&0x80000000 = 共享(bool) |
然后,后续就有“元素”数量个连续的键值对,使用的也是这种相同的格式。
19: Array¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
val&0x7FFFFFFF = 元素,val&0x80000000 = 共享(bool) |
然后,后续就有“元素”数量个连续的值,使用的也是这种相同的格式。
20: PoolByteArray¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度(字节) |
8..8+长度 |
1 |
Byte |
字节 (0..255) |
数组数据填充为4个字节.
21: PoolIntArray¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度(整数) |
8..8+长度*4 |
4 |
整数 |
32位有符号整数 |
22: PoolRealArray¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度(浮点数) |
8..8+长度*4 |
4 |
整数 |
32 位 IEEE 754 浮点数 |
23: PoolStringArray¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度(字符串) |
对于每个字符串:
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
X+0 |
4 |
整数 |
字符串长度 |
X+4 |
X |
多字节 |
UTF-8 编码字符串 |
每个字符串填充为4个字节.
24: PoolVector2Array¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度 |
8..8+长度*8 |
4 |
浮点数 |
X 坐标 |
8..12+长度*8 |
4 |
浮点数 |
Y 坐标 |
25: PoolVector3Array¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度 |
8..8+长度*12 |
4 |
浮点数 |
X 坐标 |
8..12+长度*12 |
4 |
浮点数 |
Y 坐标 |
8..16+长度*12 |
4 |
浮点数 |
Z 坐标 |
26: PoolColorArray¶
偏移量 |
长度 |
类型 |
描述 |
---|---|---|---|
4 |
4 |
整数 |
数组长度 |
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 |
浮点数 |
Alpha(0..1) |