二进制序列化API
- 简介
- 包规范

二进制序列化API

简介

Godot has a simple serialization API based on Variant. It’s used for converting data types to an array of bytes efficiently. This API is used in the functions get_var and store_var of File as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

包规范

The packet is designed to be always padded to 4 bytes. All values are little-endian-encoded. All packets have a 4-byte header representing an integer, specifying the type of data:

类型	值
0	null
1	bool
2	integer
3	float
4	字符串
5	vector2
6	rect2
7	vector3
8	transform2d
9	plane
10	quat
11	aabb
12	basis
13	transform
14	color
15	node path
16	rid
17	object
18	dictionary
19	array
20	raw array
21	int array
22	real array
23	string array
24	vector2 array
25	vector3 array
26	color array
27	max

Following this is the actual packet contents, which varies for each type of packet. Note that this assumes Godot is compiled with single-precision floats, which is the default. If Godot was compiled with double-precision floats, the length of “Float” fields within data structures should be 8, and the offset should be (offset - 4) * 2 + 4. The “float” type itself always uses double precision.

0: null

1: bool

偏移量	长度	类型	描述
4	4	Integer	0 代表 False, 1 代表 True

2: int

偏移量	长度	类型	描述
4	8	Integer	64-bit signed integer

3: float

偏移量	长度	类型	描述
4	4	Float	IEE 754格式的32位浮点数

4: String

偏移量	长度	类型	描述
4	4	Integer	String length (in bytes)
8	X	Bytes	UTF-8 encoded string

该字段会被填充成4个字节。

5: Vector2

偏移量	长度	类型	描述
4	4	Float	X coordinate
8	4	Float	Y coordinate

6: Rect2

偏移量	长度	类型	描述
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	X size
16	4	Float	Y size

7: Vector3

偏移量	长度	类型	描述
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate

8: Transform2D

偏移量	长度	类型	描述
4	4	Float	X列向量的X分量，可通过[0][0]访问
8	4	Float	X列向量的Y分量，可通过[0][1]访问
12	4	Float	Y列向量的X分量，可通过[1][0]访问
16	4	Float	Y列向量的Y分量，可通过[1][1]访问
20	4	Float	原始向量的X分量，可通过[2] [0]访问
24	4	Float	原始向量的Y分量，可通过[2][1]访问

9: Plane

偏移量	长度	类型	描述
4	4	Float	法线 X
8	4	Float	法线 Y
12	4	Float	法线 Z
16	4	Float	距离

10: Quat

偏移量	长度	类型	描述
4	4	Float	虚数X
8	4	Float	虚数Y
12	4	Float	虚数Z
16	4	Float	实数W

11: AABB

偏移量	长度	类型	描述
4	4	Float	X coordinate
8	4	Float	Y coordinate
12	4	Float	Z coordinate
16	4	Float	X size
20	4	Float	Y size
24	4	Float	Z size

12: Basis

偏移量	长度	类型	描述
4	4	Float	X列向量的X分量，可通过[0][0]访问
8	4	Float	X列向量的Y分量，可通过[0][1]访问
12	4	Float	X列向量的Z分量，可通过[0][2]访问
16	4	Float	Y列向量的X分量，可通过[1][0]访问
20	4	Float	Y列向量的Y分量，可通过[1][1]访问
24	4	Float	Y列向量的Z分量，可通过[1][2]访问
28	4	Float	Z列向量的X分量，可通过[2][0]访问
32	4	Float	Z列向量的Y分量，可通过[2][1]访问
36	4	Float	Z列向量的Z分量，可通过[2][2]访问

13: Transform

偏移量	长度	类型	描述
4	4	Float	X列向量的X分量，可通过[0][0]访问
8	4	Float	X列向量的Y分量，可通过[0][1]访问
12	4	Float	X列向量的Z分量，可通过[0][2]访问
16	4	Float	Y列向量的X分量，可通过[1][0]访问
20	4	Float	Y列向量的Y分量，可通过[1][1]访问
24	4	Float	Y列向量的Z分量，可通过[1][2]访问
28	4	Float	Z列向量的X分量，可通过[2][0]访问
32	4	Float	Z列向量的Y分量，可通过[2][1]访问
36	4	Float	Z列向量的Z分量，可通过[2][2]访问
40	4	Float	原始向量的X分量，可通过[3][0]访问
44	4	Float	原点向量的Y分量，可通过[3][1]访问
48	4	Float	原点向量的Z分量，可通过[3][2]访问

14: Color

偏移量	长度	类型	描述
4	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
12	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
16	4	Float	透明通道 (0..1)

15: NodePath

偏移量	长度	类型	描述
4	4	Integer	String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

对于旧格式:

偏移量	长度	类型	描述
8	X	Bytes	UTF-8 encoded string

填充到4个字节。

对于新格式:

偏移量	长度	类型	描述
4	4	Integer	Sub-name count
8	4	Integer	标志 (absolute: val&1 != 0 )

对于每个名称和子名称

偏移量	长度	类型	描述
X+0	4	Integer	String length
X+4	X	Bytes	UTF-8 encoded string

每个名称字符串都会填充到4个字节。

16: RID (暂不支持)

17: Object (暂不支持)

18: Dictionary

偏移量	长度	类型	描述
4	4	Integer	val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

然后，对于``elements``的数量，使用相同的格式，一个接一个地使用密钥和值对。

19: Array

偏移量	长度	类型	描述
4	4	Integer	val&0x7FFFFFFF = elements, val&0x80000000 = shared (bool)

然后，对于``elements``的数量，使用相同的格式一个接一个地输出值。

20: PoolByteArray

偏移量	长度	类型	描述
4	4	Integer	Array length (Bytes)
8..8+长度	1	Byte	字节 (0..255)

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

21: PoolIntArray

偏移量	长度	类型	描述
4	4	Integer	Array length (Integers)
8..8+长度*4	4	Integer	32-bit signed integer

22: PoolRealArray

偏移量	长度	类型	描述
4	4	Integer	Array length (Floats)
8..8+长度*4	4	Integer	32-bits IEEE 754 float

23: PoolStringArray

偏移量	长度	类型	描述
4	4	Integer	Array length (Strings)

对于每个字符串:

偏移量	长度	类型	描述
X+0	4	Integer	String length
X+4	X	Bytes	UTF-8 encoded string

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

24: PoolVector2Array

偏移量	长度	类型	描述
4	4	Integer	Array length
8..8+长度8	4	Float	X coordinate
8..12+长度8	4	Float	Y coordinate

25: PoolVector3Array

偏移量	长度	类型	描述
4	4	Integer	Array length
8..8+长度12	4	Float	X coordinate
8..12+长度12	4	Float	Y coordinate
8..16+长度*12	4	Float	Z coordinate

26: PoolColorArray

偏移量	长度	类型	描述
4	4	Integer	Array length
8..8+长度16	4	Float	Red (typically 0..1, can be above 1 for overbright colors)
8..12+长度16	4	Float	Green (typically 0..1, can be above 1 for overbright colors)
8..16+长度16	4	Float	Blue (typically 0..1, can be above 1 for overbright colors)
8..20+长度16	4	Float	透明通道 (0..1)