二进制序列化API

前言

Godot有一个基于Variant的简单序列化API. 它用于有效地将数据类型转换为字节数组. 这个API用于 Fileget_varstore_var 函数, 以及 PacketPeer 的包API. 这种格式 用于二进制场景和资源.

包规范

该数据包被设计为总是被填充到4个字节. 所有的值都是小端编码的. 所有数据包都有一个4字节的头, 代表一个整数, 指定数据的类型.

最低值的两个字节用于确定类型,而最高值的两个字节包含标志:

base_type = val & 0xFFFF;
flags = val >> 16;

类型

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

变换

14

颜色

15

node path

16

rid

17

object

18

字典

19

数组

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

如果没有设置标志(flags == 0),整数将作为32位整数发送:

偏移量

长度

类型

描述

4

4

Integer

32位有符号整数

如果标志 ENCODE_FLAG_64 被设置(flags & 1 == 1),则整数被发送为64位整数:

偏移量

长度

类型

描述

4

8

Integer

64位有符号整数

3: float

如果没有设置flags(flags == 0),浮点数将作为32位单精度发送:

偏移量

长度

类型

描述

4

4

(单精度)浮点数

IEEE 754单精度浮点数

如果标志 ENCODE_FLAG_64 被设置(flags & 1 == 1),浮点数将作为64位双精度数字发送:

偏移量

长度

类型

描述

4

8

(单精度)浮点数

IEEE 754双精度浮点数

4: String

偏移量

长度

类型

描述

4

4

Integer

字符串长度 (字节)

8

X

Bytes

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: Quat

偏移量

长度

类型

描述

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: Transform

偏移量

长度

类型

描述

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

(单精度)浮点数

透明通道 (0..1)

15: NodePath

偏移量

长度

类型

描述

4

4

Integer

字符串长度, 或新格式(val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

对于旧格式:

偏移量

长度

类型

描述

8

X

Bytes

UTF-8编码字符串

填充到4个字节.

对于新格式:

偏移量

长度

类型

描述

4

4

Integer

子名称数

8

4

Integer

标志 (absolute: val&1 != 0 )

对于每个名称和子名称

偏移量

长度

类型

描述

X+0

4

Integer

字符串长度

X+4

X

Bytes

UTF-8编码字符串

每个名称字符串都会填充到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

数组长度(字节)

8..8+长度

1

Byte

字节 (0..255)

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

21: PoolIntArray

偏移量

长度

类型

描述

4

4

Integer

数组长度(整数)

8..8+长度*4

4

Integer

32位有符号整数

22: PoolRealArray

偏移量

长度

类型

描述

4

4

Integer

数组长度(浮点数)

8..8+长度*4

4

Integer

32-bits IEEE 754 float

23: PoolStringArray

偏移量

长度

类型

描述

4

4

Integer

数组长度(字符串)

对于每个字符串:

偏移量

长度

类型

描述

X+0

4

Integer

字符串长度

X+4

X

Bytes

UTF-8编码字符串

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

24: PoolVector2Array

偏移量

长度

类型

描述

4

4

Integer

数组长度

8..8+长度*8

4

(单精度)浮点数

X坐标

8..12+长度*8

4

(单精度)浮点数

Y坐标

25: PoolVector3Array

偏移量

长度

类型

描述

4

4

Integer

数组长度

8..8+长度*12

4

(单精度)浮点数

X坐标

8..12+长度*12

4

(单精度)浮点数

Y坐标

8..16+长度*12

4

(单精度)浮点数

Z坐标

26: PoolColorArray

偏移量

长度

类型

描述

4

4

Integer

数组长度

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

(单精度)浮点数

透明通道 (0..1)