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

(单精度)浮点数

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

之后是实际的数据包内容,每种类型的数据包内容都不同。请注意,这是假设Godot是用单精度浮点数编译的,这是默认的。如果Godot是用双精度浮点数编译的,那么数据结构中 "float" 字段的长度应该是8,偏移量应该是 (offset - 4) * 2 + 4 。 "float" 类型本身总是使用双精度。

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

红色(一般为0...1,对于过亮的颜色可大于1)

8

4

Float

绿色(一般为0...1,对于过亮的颜色可大于1)

12

4

Float

蓝色(一般为0...1,对于过亮的颜色可大于1)

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

红色(一般为0...1,对于过亮的颜色可大于1)

8..12+长度*16

4

Float

绿色(一般为0...1,对于过亮的颜色可大于1)

8..16+长度*16

4

Float

蓝色(一般为0...1,对于过亮的颜色可大于1)

8..20+长度*16

4

Float

透明通道 (0..1)