Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

二进制序列化 API

前言

Godot has a serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is exposed via the global bytes_to_var() and var_to_bytes() functions, but it is also used in the get_var and store_var methods of FileAccess as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

Full Objects vs Object instance IDs

If a variable is serialized with full_objects = true, then any Objects contained in the variable will be serialized and included in the result. This is recursive.

If full_objects = false, then only the instance IDs will be serialized for any Objects contained in the variable.

数据包规格

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

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

17: Object

An Object could be serialized in three different ways: as a null value, with full_objects = false, or with full_objects = true.

A null value

偏移量	长度	类型	描述
4	4	整数	Zero (32-bit signed integer)

full_objects disabled

偏移量	长度	类型	描述
4	8	整数	The Object instance ID (64-bit signed integer)

full_objects enabled

偏移量	长度	类型	描述
4	4	整数	Class name (String length)
8	X	多字节	Class name (UTF-8 encoded string)
X+8	4	整数	The number of properties that are serialized

For each property:

偏移量	长度	类型	描述
Y	4	整数	Property name (String length)
Y+4	Z	多字节	Property name (UTF-8 encoded string)
Y+4+Z	W	<variable>	Property value, using this same format

备注

Not all properties are included. Only properties that are configured with the PROPERTY_USAGE_STORAGE flag set will be serialized. You can add a new usage flag to a property by overriding the _get_property_list method in your class. You can also check how property usage is configured by calling Object._get_property_list See PropertyUsageFlags for the possible usage flags.

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-bit IEEE 754 single-precision float

24: PackedFloat64Array

偏移量	长度	类型	描述
4	4	整数	数组长度（浮点数）
8..8+长度*8	8	整数	64-bit IEEE 754 double-precision float

25: PackedStringArray

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

对于每个字符串:

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

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

26: 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）