Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it’s up to date, feel free to open a pull request.

二进制序列化 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 字节的头，代表一个整数，指定数据的类型。

两个低字节用于确定类型，而两个高字节则包含标志：

  1. base_type = val & 0xFFFF;
  2. 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

An Object could be serialized in three different ways: as a null value, with full_objects = false, or with 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

<可变>

属性值，格式相同

备注

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 位 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）

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.