Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

二進位序列化 API

前言

Godot 具有一個基於 Variant 的序列化 API。它用於高效率地將資料型別轉換為位元組陣列。這個 API 透過全域函式 bytes_to_var() 和 var_to_bytes() 公開，但它也用於 FileAccess 的 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	int32 陣列
22	int64 陣列
23	float32 陣列
24	float64 陣列
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	浮點數	距離

10: Quaternion 

偏移量	長度	型別	說明
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]存取

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 

物件可以透過三種不同的方式序列化：作為空值，使用“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	變數	屬性值，格式相同

備註

並非所有屬性都會被包含在內。只有設定了 PROPERTY_USAGE_STORAGE 旗標的屬性才會被序列化。你可以在自己的類別中覆寫 _get_property_list 方法來為屬性新增使用旗標。你也可以呼叫 Object._get_property_list 來檢查屬性的使用設定。請參閱 PropertyUsageFlags 以瞭解所有可用的使用旗標。

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+length*4	4	整數	32位元有符號整數

22: PackedInt64Array 

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

23: PackedFloat32Array 

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

24: PackedFloat64Array 

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

25: PackedStringArray 

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

對於每個字串:

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

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

26: PackedVector2Array 

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

27: PackedVector3Array 

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

28: PackedColorArray 

偏移量	長度	型別	說明
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）

二進位序列化 API

前言

完整物件與物件實例 ID

封包規格

0: null

1: bool

2: int

3: float

4: String

5: Vector2

6: Rect2

7: Vector3

8: Transform2D

9: Plane

10: Quaternion

11: AABB

12: Basis

13: Transform3D

14: Color

15: NodePath