二进制序列化 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	整数
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）