我的书签
添加书签
移除书签- 二进制序列化 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
- 对于旧格式:
- 对于新格式:
- 16: RID （不支持）
- 17: Object
- 18： Dictionary
- 19： Array
- 20： PackedByteArray
- 21： PackedInt32Array
- 22： PackedInt64Array
- 23： PackedFloat32Array
- 24： PackedFloat64Array
- 25： PackedStringArray
- 24： PackedVector2Array
- 27： PackedVector3Array
- 28： PackedColorArray
二进制序列化 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.
完整对象 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 array |
22 | int64 array |
23 | float32 array |
24 | float64 array |
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（不支持）
17: 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） |
