Work in progress

The content of this page was not yet updated for Godot 4.4 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

二进制序列化 API

前言

Godot 有一个基于 Variant 的序列化 API。它用于高效地将数据类型转换为字节数组。该 API 通过全局 bytes_to_var() 和 var_to_bytes() 函数公开，但它也用在 FileAccess 的 get_var 和 store_var 方法中以及 PacketPeer 的数据包 API。该格式并不用于二进制场景和资源。

完整对象 vs 对象实例 ID

如果序列化变量时使用了 full_objects = true，则该变量中所包含的 Object 都会进行序列化、包含在结果中。这个过程是递归的。

如果 full_objects = false，则只会对该变量中所包含的 Object 的实例 ID 进行序列化。

数据包规格

根据设计，数据包总是会被填充到 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	四元数
11	aabb
12	basis
13	transform3d
14	颜色
15	节点路径
16	rid
17	对象
18	字典
19	数组
20	原始数组
21	int32 数组
22	int64 数组
23	float32 数组
24	float64 数组
25	字符串数组
26	vector2 数组
27	vector3 数组
28	颜色数组
29	max

在此之后是实际的数据包内容，每种类型的数据包内容都不同。请注意，这里假设 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: Quaternion 

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

偏移量	长度	类型	描述
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（不支持）

Object 

Object 有三种不同的序列化方式：作为空值、使用 full_objects = false、使用 full_objects = true。

空值

偏移量	长度	类型	描述
4	4	整数	零（32 位带符号整数）

禁用 `full_objects`

偏移量	长度	类型	描述
4	8	整数	Object 实例 ID（64 位带符号整数）

启用 `full_objects`

偏移量	长度	类型	描述
4	4	整数	类名（字符串长度）
8	X	多字节	类名（UTF-8 编码字符串）
X+8	4	整数	序列化的属性数

对于每一个属性：

偏移量	长度	类型	描述
Y	4	整数	属性名称（字符串长度）
Y+4	Z	多字节	属性名称（UTF-8 编码字符串）
Y+4+Z	W	<可变>	属性值，格式相同

备注

并非所有属性都包含在内。仅使用 PROPERTY_USAGE_STORAGE 标志集将被序列化。通过重写类中的 _get_property_list 方法，可以向属性添加新的用法标志。你还可以通过调用``Object._get_property_list``详情参见 PropertyUsageFlags 以获取可能的使用位标记。

18：Dictionary 

偏移量	长度	类型	描述
4	4	整数	val&0x7FFFFFFF = 元素，val&0x80000000 = 共享（bool）

然后，后续就有“元素”数量个连续的键值对，使用的也是这种相同的格式。

19：Array 

偏移量	长度	类型	描述
4	4	整数	val&0x7FFFFFFF = 元素，val&0x80000000 = 共享（bool）

然后，后续就有“元素”数量个连续的值，使用的也是这种相同的格式。

20：PackedByteArray 

偏移量	长度	类型	描述
4	4	整数	数组长度（字节）
8..8+长度	1	Byte	字节 (0..255)

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

21：PackedInt32Array 

偏移量	长度	类型	描述
4	4	整数	数组长度（整数）
8..8+长度*4	4	整数	32位有符号整数

22：PackedInt64Array 

偏移量	长度	类型	描述
4	8	整数	数组长度（整数）
8..8+长度*8	8	整数	64位有符号整数

23：PackedFloat32Array 

偏移量	长度	类型	描述
4	4	整数	数组长度（浮点数）
8..8+长度*4	4	整数	32 位 IEEE 754 单精度浮点数

24：PackedFloat64Array 

偏移量	长度	类型	描述
4	4	整数	数组长度（浮点数）
8..8+长度*8	8	整数	64 位 IEEE 754 双精度浮点数

25：PackedStringArray 

偏移量	长度	类型	描述
4	4	整数	数组长度（字符串）

对于每个字符串:

偏移量	长度	类型	描述
X+0	4	整数	字符串长度
X+4	X	多字节	UTF-8 编码字符串

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

24：PackedVector2Array 

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

27：PackedVector3Array 

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

28：PackedColorArray 

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

二进制序列化 API

前言

完整对象 vs 对象实例 ID

数据包规格

0: null

1: bool

2: int

3: float

4: String

5: Vector2

6: Rect2

7: Vector3

8: Transform2D

9: Plane

10: Quaternion

11: AABB

12: Basis

13: Transform3D

14: Color

15: NodePath