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 有一個基於 Variant 的簡單序列化 API。它用於有效地將資料型別轉換為位元組陣列。這個 API 用於 class_File 的 get_var 和 store_var 函式，以及 PacketPeer 的資料包 API。二進位場景和資源*不使用*該格式。

完整物件與物件實例 ID

如果使用「full_objects = true」序列化變量，則該變數中包含的任何物件都會被序列化並包含在結果中。這是遞歸的。

如果“full_objects = false”，則只有實例 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	變換
14	顏色
15	節點路徑
16	rid
17	物件
18	字典
19	陣列
20	原始陣列
21	反轉陣列。
22	反轉陣列。
23	本地坐標
24	本地坐標
25	字串陣列
26	vector2 陣列
27	vector3 陣列
28	顏色陣列
29	最大值

在此之後是實際的封包內容，每種型別的封包內容都不同。請注意，這裡假設 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	浮點數	下一個座標
8	4	浮點數	下一個座標

6: Rect2

偏移量	長度	型別	說明
4	4	浮點數	下一個座標
8	4	浮點數	下一個座標
12	4	浮點數	X 尺寸
16	4	浮點數	Y 尺寸

7: Vector3

偏移量	長度	型別	說明
4	4	浮點數	下一個座標
8	4	浮點數	下一個座標
12	4	浮點數	下一個座標

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	浮點數	距離

Quat

偏移量	長度	型別	說明
4	4	浮點數	虛數 X
8	4	浮點數	虛數 Y
12	4	浮點數	虛數 Z
16	4	浮點數	實數 W

11: AABB

偏移量	長度	型別	說明
4	4	浮點數	下一個座標
8	4	浮點數	下一個座標
12	4	浮點數	下一個座標
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]存取

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	浮點數	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: :ref:`RID<class_rid>`（不支援）

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	變數	屬性值，格式相同

備註

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）

然後，後續就有“元素”數量個連續的值，使用的也是這種相同的格式。

Array

偏移量	長度	型別	說明
4	4	整數	陣列長度（位元組）
8..8+長度	1	Byte	位元組 (0..255)

陣列資料填充為4個位元組.

Array

偏移量	長度	型別	說明
4	4	整數	陣列長度（整數）
8..8+length*4	4	整數	32位元有符號整數

Array

偏移量	長度	型別	說明
4	8	整數	陣列長度（整數）
8..8+length*8	8	整數	64位元有符號整數

Array

偏移量	長度	型別	說明
4	4	整數	陣列長度（浮點數）
8..8+length*4	4	整數	32 位 IEEE 754 單精確度浮點數

Array

偏移量	長度	型別	說明
4	4	整數	陣列長度（浮點數）
8..8+length*8	8	整數	64 位 IEEE 754 雙精度浮點數

String

偏移量	長度	型別	說明
4	4	整數	陣列長度（字串）

對於每個字串:

偏移量	長度	型別	說明
X+0	4	整數	每行字數限制
X+4	X	多位元組	UTF-8 編碼字串

每個字串填充為4個位元組.

Vector3

偏移量	長度	型別	說明
4	4	整數	陣列
8..8+length*8	4	浮點數	下一個座標
8..12+length*8	4	浮點數	下一個座標

Vector3

偏移量	長度	型別	說明
4	4	整數	陣列
8..8+length*12	4	浮點數	下一個座標
8..12+length*12	4	浮點數	下一個座標
8..16+length*12	4	浮點數	下一個座標

Array

偏移量	長度	型別	說明
4	4	整數	陣列
8..8+length*16	4	浮點數	紅色（一般為 0...1，對於過亮的顏色可大於 1）
8..12+length*16	4	浮點數	綠色（一般為 0...1，對於過亮的顏色可大於 1）
8..16+length*16	4	浮點數	藍色（一般為 0...1，對於過亮的顏色可大於 1）
8..20+length*16	4	浮點數	Alpha（0..1）